diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-02 18:09:59 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-06-02 18:09:59 +0300 |
commit | 1c2ff01b694fd06be15bc20279eef71ee5adf402 (patch) | |
tree | 98a588172ab8021790538a515933cf83552c5086 /doc/development/api_graphql_styleguide.md | |
parent | 2e4e6e9bb63212c628e67c6865fa39f62217a83d (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development/api_graphql_styleguide.md')
-rw-r--r-- | doc/development/api_graphql_styleguide.md | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index e8b71e0509a..ae6e7df2b73 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -1575,6 +1575,41 @@ deprecated aliased mutations. EE mutations should follow the same process. For an example of the merge request process, read [merge request !42588](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42588). +## Subscriptions + +We use subscriptions to push updates to clients. We use the [Action Cable implementation](https://graphql-ruby.org/subscriptions/action_cable_implementation) +to deliver the messages over websockets. + +When a client subscribes to a subscription, we store their query in-memory within Puma workers. Then when the subscription is triggered, +the Puma workers execute the stored GraphQL queries and push the results to the clients. + +NOTE: +We cannot test subscriptions using GraphiQL, because they require an Action Cable client, which GraphiQL does not support at the moment. + +### Building subscriptions + +All fields under `Types::SubscriptionType` are subscriptions that clients can subscribe to. These fields require a subscription class, +which is a descendant of `Subscriptions::BaseSubscription` and is stored under `app/graphql/subscriptions`. + +The arguments required to subscribe and the fields that are returned are defined within the subscription class. Multiple fields can share +the same subscription class if they have the same arguments and return the same fields. + +This class runs during the initial subscription request and subsequent updates. You can read more about this in the +[GraphQL Ruby guides](https://graphql-ruby.org/subscriptions/subscription_classes). + +### Authorization + +You should implement the `#authorized?` method of the subscription class so that the initial subscription and subsequent updates are authorized. + +When a user is not authorized, you should call the `unauthorized!` helper so that execution is halted and the user is unsubscribed. Returning `false` +results in redaction of the response but we leak information that some updates are happening. This is due to a +[bug in the GraphQL gem](https://github.com/rmosolgo/graphql-ruby/issues/3390). + +### Triggering subscriptions + +Define a method under the `GraphqlTriggers` module to trigger a subscription. Do not call `GitlabSchema.subscriptions.trigger` directly in application +code so that we have a single source of truth and we do not trigger a subscription with different arguments and objects. + ## Pagination implementation To learn more, visit [GraphQL pagination](graphql_guide/pagination.md). |