How to implement graphql subscriptions using oasgraph?

[ryankauk]

Really interested in utilizing graphql with loopback 4 and am wondering if it's possible to implement subscriptions?

[ErikWittern]

From an OASGraph point-of-view, the support of subscriptions depends on support for expressing streams / pub-sub like mechanisms in the OAS. The notion of callbacks and related callback objects may be the right thing to look at, but still the debate around this seems not to have concluded yet.

Apart from that, this question seems to be specifically about LoopBack 4 also. Maybe @raymondfeng or @dhmlau know more about subscription / stream / pub-sub support in LoopBack 4?

[dhmlau]

@ryankauk, we're looking into supporting messaging/eventing style APIs. Please see our story in https://github.com/strongloop/loopback-next/issues/1884. @raymondfeng has a PoC: https://github.com/raymondfeng/loopback4-example-websocket.

[dhmlau]

Actually this one might fit more what you're looking for: https://github.com/strongloop/loopback4-example-kafka. (cross posting from https://github.com/strongloop/loopback-next/issues/1925)

[ErikWittern]

Related to #101

[mitar]

I am looking into using GraphQL for Kubernetes API, which has a way of watching resources. I think that could be directly translated to GraphQL subscriptions. But it seems this package is currently not really supporting it. Maybe also because how Kubernetes describes its API looks like it simple provides watch parameter, and mark that the response can be application/json;stream=watch. So it seems this package should somehow now that if one makes a subscribe GraphQL, it should set watch parameter to true and then interpret application/json;stream=watch correctly?

[mitar]

After more looking into this, I think that yes, OpenAPI 3.0 callbacks should be converted to GraphQL subscriptions.

I think adding support for generating GraphQL schemas/types automatically from callbacks into GraphQL subscriptions would be a great first step. But it seems different API implementations are implementing callbacks differently. Some use websockets, some use HTTP2, it is pretty non-standard. So instead of waiting for world to find a standard way, I think easier would be to allow one to pass an implementation on how should a subscription be converted to the request (by maybe passing an event emitter factory, new event emitter for each subscription request). Then this package could use the schema plus event emmiter factory to expose those subscriptions.

[ErikWittern]

@mitar We looked into better subscription support in the past and found that OpenAPI is likely does not contain the required information for us to implement a generic solution. Some thoughts are captured in https://github.com/IBM/openapi-to-graphql/issues/101. The existence of alternative formats like https://www.asyncapi.com/ support this impression. I think you make the same point in your last comment, actually.

While allowing to pass in your own implementation, as you suggest, may address the issue, we currently want to focus on improving request-response flows (and are, for example, in the process of supporting wrapping the Kubernetes API better to that regard).

We are of course appreciative of PRs that could improve subscription support but - just to be fully transparent - it is not currently something we are actively pursuing ourselves.

[mitar]

OpenAPI is likely does not contain the required information for us to implement a generic solution

But it does enough for one to implement the schema for the subscription calls? So if I would have callback defined in OpenAPI 3.0, there is enough information to map that to the schema. The only missing piece is then how to handle such call and that would have to be custom because there is no standard way.

Am I missing something?

we currently want to focus on improving request-response flows

Any links of what are those plans?

and are, for example, in the process of supporting wrapping the Kubernetes API better to that regard

Oh, interesting, but what issues have you found there? It looked to me that (besides watching/subscription) otherwise the API seems pretty well supported already?

Currently Kubernetes API is not defined in terms of callbacks so one would have to anyway manually post-process schemas and remove watch parameter.

[ErikWittern]

@mitar Thanks for the prompt reply. To your questions:

Am I missing something?

I think you could be right, but am not very familiar with the callbacks option. Would it imply that the GraphQL server would listen at a (customizable) route for callbacks made by the REST-API server, and then forward these as subscriptions?

We are constantly improving schema-creation, so I think you are right, that logic can be reused for creating the subscription-related GraphQL types.

Any links of what are those plans?

We don't have an official "plan" for what items we want to tackle when, sorry! But we have been concerned with better support of anyOf and oneOf definitions for a while now, and the improvements should land soon: https://github.com/IBM/openapi-to-graphql/pull/287. These improvements will broaden the set of OpenAPI descriptions we support, including the Kubernetes OpenAPI, which uses these features.

[mitar]

Would it imply that the GraphQL server would listen at a (customizable) route for callbacks made by the REST-API server, and then forward these as subscriptions?

I looked into this more, and I think that this package could really do this automatically for all OpenAPI 3.0 compatible API endpoints. It would not work for Kubernetes at the moment (because Kubernetes is not yet using OpenAPI 3.0, nor defining callbacks, and having a custom approach to watching resources), but for standard compliant OpenAPI 3.0 implementations, we could do something pretty nice:

• So all callbacks defined in the spec would be mapped to corresponding GraphQL subscriptions. During this mapping, callbackUrl fields in the subscription request to the underlying OpenAPI 3.0 API would not be mapped and would not be exposed through GraphQL. (There might be some need to do some heuristic to discover which fields those are, based on templates for callback URls.)
• When a GraphQL client subscribes, the GraphQL proxy provided by this tool would add the callbackUrl which would point to the internal IP/HTTP server/callback server of the proxy itself, and call further the underlying OpenAPI API endpoint to subscribe to callbacks.
• As the underlying OpenAPI API endpoint makes callbacks against the proxy, the proxy would convert them to GraphQL subscription messages and route them back to clients through subscriptions.
• If client disconnects or stops the subscriptions, the proxy would unsubscribe from the underlying OpenAPI API endpoint, if that is supported by the endpoint (I am slightly unclear here how can one in general automatically discover which approach to unsubscription is used by the endpoint, OpenAPI 3.0 has some ways to describe such unsubscription endpoint, but I do not see a way to without human help knowing which is exactly is that and how to use it, maybe I am missing something).

So, magic. It just works and makes subscriptions automatically. The proxy becomes slightly more complicated than just calling graphqlHTTP express, but it can work with all OpenAPI 3.0 compliant implementations. In the past I thought that OpenAPI 3.0 just defines the API for callbacks, but in fact it also defines how those callbacks should be made and so on, so we can do everything automatically.

A good side-effect of this is that now also clients behind NATs and firewalls can subscribe to events from the server. With OpenAPI 3.0 one has to have a public IP and can allow API to call back to them. This is pretty heavy limitation in my mind. The approach above addresses it.

For supporting Kubernetes watching, a manual schema post-processing seems will be necessary: to remove watch and other related parameters from queries, adding similar subscriptions, and then implementing with custom logic which uses watch.

[getlarge]

@Alan-Cha I think this one can be closed now ?

[mitar]

Just to provide context here. This has been done in version 2.1.0 in this PR: https://github.com/IBM/openapi-to-graphql/pull/311 See documentation here.

@getlarge @Alan-Cha Awesome work! I think this could be closed, but I think README section could have a part about subscriptions. I think it is a really cool feature to have it listed there.

[mitar]

So I have looked into the implementation and I think that current implementation is taking quite opinionated view on how REST server implements callbacks, namely, that is uses a pubsub service to do so. From the OpenAPI 3.0 spec and callbacks there, my understanding is that callbacks are HTTP request from the REST server back to the client. So an OpenAPI 3.0 callbacks example will not really work with current implementation here. openapi-to-graphql does not use HTTP to subscribe and does not define a callback endpoint for REST server to call back to (so the openapi-to-graphql server should listen to HTTP callbacks from the REST server).

So I would suggest we leave this issue open until also the HTTP based callbacks are supported and that it is not required that one augments the REST server/implementation itself.

[Alan-Cha]

@mitar I see what you mean and I think I largely agree. The current implementation is opinionated, enabling Subscription support by utilizing callbacks in a way that is different then how it was originally intended.

Regarding documentation, we will be adding a little bit more with #313 but I think more is needed.

To keep the discussion going, I will leave this issue open.

[mitar]

I do agree thought that what is currently made is probably a better overall design/architecture. Using HTTP for pub/sub what OpenAPI 3.0 defines is definitely less efficient than using a dedicated pubsub solution.

So maybe one way to address this gap is to have a stand-alone additional service which translates between HTTP backed callbacks and dedicated pubsub solution. So if one does not want to change their REST server (which uses HTTP callbacks) they can put in front this to-be-made service, which connects exposes a callback for the REST server to call into, subscribes as necessary to callbacks on the REST server, and pushes all calls into the dedicated pubsub solution. So maybe this does not have to be integrated directly with openapi-to-graphql but could be in addition to it.