A resolver can return a single value or an object, as shown in [Defining a resolver](#defining-a-resolver). This return value is passed down to any nested resolvers via the `parent` argument.
| | `Array` |Return an array if and only if your schema indicates that the resolver's associated field contains a list.
After you return an array, Apollo Server executes nested resolvers for each item in the array.
| | `null` / `undefined` |Indicates that the value for the field could not be found.
If your schema indicates that this resolver's field is nullable, then the operation result has a `null` value at the field's position.
If this resolver's field is _not_ nullable, Apollo Server sets the field's _parent_ to `null`. If necessary, this process continues up the resolver chain until it reaches a field that _is_ nullable. This ensures that a response never includes a `null` value for a non-nullable field. When this happens, the response's `errors` property will be populated with relevant errors concerning the nullability of that field.
| -| [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) |Resolvers often perform asynchronous actions, such as fetching from a database or back-end API. To support this, a resolver can return a promise that resolves to any other supported return type.
| - +| [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) |Resolvers can be asynchronous and perform async actions, such as fetching from a database or back-end API. To support this, a resolver can return a promise that resolves to any other supported return type.
| ## Default resolvers diff --git a/docs/source/data/subscriptions.mdx b/docs/source/data/subscriptions.mdx index 79e40294912..8477c78795c 100644 --- a/docs/source/data/subscriptions.mdx +++ b/docs/source/data/subscriptions.mdx @@ -3,15 +3,15 @@ title: Subscriptions in Apollo Server description: Persistent GraphQL read operations --- -> **Apollo Server 3 removes built-in support for subscriptions.** You can reenable support as [described below](#enabling-subscriptions). +>**Apollo Server does not provide built-in support for subscriptions.** You can enable support for subscriptions as [described below](#enabling-subscriptions). > > **Subscriptions are not currently supported in [Apollo Federation](/federation/).** > -> This article has been updated to use the `graphql-ws` library to add support for subscriptions to Apollo Server. We no longer recommend using the previously documented `subscriptions-transport-ws`, because this library is not actively maintained. For more information about the differences between the two libraries, see [Switching from `subscriptions-transport-ws`](#switching-from-subscriptions-transport-ws). +> This article uses the `graphql-ws` library to add support for subscriptions to Apollo Server 4. We no longer recommend using the previously documented `subscriptions-transport-ws`, because this library is not actively maintained. For more information about the differences between the two libraries, see [Switching from `subscriptions-transport-ws`](#switching-from-subscriptions-transport-ws). **Subscriptions** are long-lasting GraphQL read operations that can update their result whenever a particular server-side event occurs. Most commonly, updated results are _pushed_ from the server to subscribing clients. For example, a chat application's server might use a subscription to push newly received messages to all clients in a particular chat room. -Because subscription updates are usually pushed by the server (instead of polled by the client), they usually use [the WebSocket protocol](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) instead of HTTP. +Because subscription updates are usually pushed by the server (instead of polled by the client), they generally use [the WebSocket protocol](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) instead of HTTP. > **Important:** Compared to queries and mutations, subscriptions are significantly more complex to implement. Before you begin, [confirm that your use case requires subscriptions](/react/data/subscriptions/#when-to-use-subscriptions). @@ -42,102 +42,94 @@ subscription PostFeed { ## Enabling subscriptions -> Beginning in Apollo Server 3, subscriptions are **not** supported by the "batteries-included" `apollo-server` package. To enable subscriptions, you must first [swap to the `apollo-server-express` package](../integrations/middleware/#swapping-out-apollo-server) (or any other Apollo Server integration package that supports subscriptions). + + +> Subscriptions are **not** supported by Apollo Server 4's `startStandaloneServer` function. To enable subscriptions, you must first [swap to using the `expressMiddleware` function](./migration#migrate-from-apollo-server-express) (or any other Apollo Server integration package that supports subscriptions). > -> The following steps assume you've already swapped to `apollo-server-express`. +> The following steps assume you've already swapped to `expressMiddleware`. To run both an Express app _and_ a separate WebSocket server for subscriptions, we'll create an `http.Server` instance that effectively wraps the two and becomes our new `listen`er. -1. Install `graphql-ws`, `ws`, `@graphql-tools/schema`, and `apollo-server-core`: - ```bash - npm install graphql-ws ws @graphql-tools/schema apollo-server-core - ``` +1. Install `graphql-ws`, `ws`, and `@graphql-tools/schema`: + + ```bash + npm install graphql-ws ws @graphql-tools/schema + ``` 2. Add the following imports to the file where you initialize your `ApolloServer` instance (we'll use these in later steps): - ```ts title="index.ts" - import { createServer } from 'http'; - import { - ApolloServerPluginDrainHttpServer, - ApolloServerPluginLandingPageLocalDefault, - } from "apollo-server-core"; - import { makeExecutableSchema } from '@graphql-tools/schema'; - import { WebSocketServer } from 'ws'; - import { useServer } from 'graphql-ws/lib/use/ws'; - ``` + ```ts title="index.ts" + import { createServer } from 'http'; + import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer'; + import { makeExecutableSchema } from '@graphql-tools/schema'; + import { WebSocketServer } from 'ws'; + import { useServer } from 'graphql-ws/lib/use/ws'; + ``` 3. Next, in order to set up both the HTTP and subscription servers, we need to first create an `http.Server`. Do this by passing your Express `app` to the `createServer` function, which we imported from the `http` module: - ```ts title="index.ts" - // This `app` is the returned value from `express()`. - const httpServer = createServer(app); - ``` + ```ts title="index.ts" + // This `app` is the returned value from `express()`. + const httpServer = createServer(app); + ``` 4. Create an instance of `GraphQLSchema` (if you haven't already). - > If you already pass the `schema` option to the `ApolloServer` constructor (instead of `typeDefs` and `resolvers`), you can skip this step. + > If you already pass the `schema` option to the `ApolloServer` constructor (instead of `typeDefs` and `resolvers`), you can skip this step. - The subscription server (which we'll instantiate next) doesn't take `typeDefs` and `resolvers` options. Instead, it takes an executable `GraphQLSchema`. We can pass this `schema` object to both the subscription server and `ApolloServer`. This way, we make sure that the same schema is being used in both places. + The subscription server (which we'll instantiate next) doesn't take `typeDefs` and `resolvers` options. Instead, it takes an executable `GraphQLSchema`. We can pass this `schema` object to both the subscription server and `ApolloServer`. This way, we make sure that the same schema is being used in both places. - ```ts title="index.ts" - const schema = makeExecutableSchema({ typeDefs, resolvers }); - // ... - const server = new ApolloServer({ - schema, - csrfPrevention: true, - cache: "bounded", - plugins: [ - ApolloServerPluginLandingPageLocalDefault({ embed: true }), - ], - }); - ``` + ```ts title="index.ts" + const schema = makeExecutableSchema({ typeDefs, resolvers }); + // ... + const server = new ApolloServer({ + schema, + }); + ``` 5. Create a `WebSocketServer` to use as your subscription server. - ```ts title="index.ts" - // Creating the WebSocket server - const wsServer = new WebSocketServer({ - // This is the `httpServer` we created in a previous step. - server: httpServer, - // Pass a different path here if your ApolloServer serves at - // a different path. - path: '/graphql', - }); - - // Hand in the schema we just created and have the - // WebSocketServer start listening. - const serverCleanup = useServer({ schema }, wsServer); - ``` - -6. Add [plugins](../integrations/plugins) to your `ApolloServer` constructor to shutdown both the HTTP server and the `WebSocketServer`: - - ```ts title="index.ts" - const server = new ApolloServer({ - schema, - csrfPrevention: true, - cache: "bounded", - plugins: [ - // Proper shutdown for the HTTP server. - ApolloServerPluginDrainHttpServer({ httpServer }), - - // Proper shutdown for the WebSocket server. - { - async serverWillStart() { - return { - async drainServer() { - await serverCleanup.dispose(); - }, - }; - }, - }, - ApolloServerPluginLandingPageLocalDefault({ embed: true }), - ], - }); - ``` + ```ts title="index.ts" + // Creating the WebSocket server + const wsServer = new WebSocketServer({ + // This is the `httpServer` we created in a previous step. + server: httpServer, + // Pass a different path here if app.use + // serves expressMiddleware at a different path + path: '/graphql', + }); + + // Hand in the schema we just created and have the + // WebSocketServer start listening. + const serverCleanup = useServer({ schema }, wsServer); + ``` + +6. Add [plugins](/apollo-server/integrations/plugins) to your `ApolloServer` constructor to shutdown both the HTTP server and the `WebSocketServer`: + + ```ts title="index.ts" + const server = new ApolloServer({ + schema, + plugins: [ + // Proper shutdown for the HTTP server. + ApolloServerPluginDrainHttpServer({ httpServer }), + + // Proper shutdown for the WebSocket server. + { + async serverWillStart() { + return { + async drainServer() { + await serverCleanup.dispose(); + }, + }; + }, + }, + ], + }); + ``` 7. Finally, ensure you are `listen`ing to your `httpServer`. - Most Express applications call `app.listen(...)`, but for your setup change this to `httpServer.listen(...)` using the same arguments. This way, the server starts listening on the HTTP and WebSocket transports simultaneously. + Most Express applications call `app.listen(...)`, but for your setup change this to `httpServer.listen(...)` using the same arguments. This way, the server starts listening on the HTTP and WebSocket transports simultaneously. A completed example of setting up subscriptions is shown below: @@ -146,13 +138,16 @@ A completed example of setting up subscriptions is shown below:
+
+
The server exposes one subscription (`numberIncremented`) that returns an integer that's incremented on the server every second. Here's an example subscription that you can run against your server:
@@ -431,9 +432,9 @@ useServer(
// Our GraphQL schema.
schema,
// Adding a context property lets you add data to your GraphQL operation context
- context: (ctx, msg, args) => {
- // You can define your own function for setting a dynamic context
- // or provide a static value
+ context: (ctx, msg, args) => {
+ // You can define your own function for setting a dynamic context
+ // or provide a static value
return getDynamicContext(ctx, msg, args);
},
},
@@ -450,8 +451,8 @@ Below is an example of the common use case of extracting an authentication token
```ts
const getDynamicContext = async (ctx, msg, args) => {
// ctx is the graphql-ws Context where connectionParams live
- if (ctx.connectionParams.authentication) {
- const currentUser = await findUser(connectionParams.authentication);
+ if (ctx.connectionParams.authentication) {
+ const currentUser = await findUser(ctx.connectionParams.authentication);
return { currentUser };
}
// Otherwise let our resolvers know we don't have a current user
@@ -462,15 +463,16 @@ useServer(
{
schema,
// Adding a context property lets you add data to your GraphQL operation context
- context: (ctx, msg, args) => {
- // Returning an object will add that information to our
- // GraphQL context, which all of our resolvers have access to.
+ context: (ctx, msg, args) => {
+ // Returning an object will add that information to our
+ // GraphQL context, which all of our resolvers have access to.
return getDynamicContext(ctx, msg, args);
},
},
wsServer,
);
```
+
Putting it all together, if the `useServer.context` function returns an _object_, that object is passed to the GraphQL operation `context`, which is available to your resolvers.
Note that the `context` option is called once per `subscription` request, not once per event emission. This means that in the above example, every time a client sends a `subscription` operation, we check their authentication token.
@@ -502,11 +504,12 @@ useServer(
wsServer,
);
```
+
For more information and examples of using `onConnect` and `onDisconnect`, see the [`graphql-ws` documentation](https://github.com/enisdenjo/graphql-ws#ws-auth-handling).
### Example: Authentication with Apollo Client
->If you plan to use subscriptions with Apollo Client, ensure **[both your client and server subscription protocols are consistent](#switching-from-subscriptions-transport-ws)** for the subscription library you're using (this example uses the `graphql-ws` library).
+> If you plan to use subscriptions with Apollo Client, ensure **[both your client and server subscription protocols are consistent](#switching-from-subscriptions-transport-ws)** for the subscription library you're using (this example uses the `graphql-ws` library).
In Apollo Client, the `GraphQLWsLink` constructor supports adding information to `connectionParams` ([example](/react/data/subscriptions/#5-authenticate-over-websocket-optional)). Those `connectionParams` are sent to your server when it connects, allowing you to extract information from the client request by accessing `Context.connectionParams`.
@@ -516,12 +519,14 @@ Let's suppose we create our subscription client like so:
import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
import { createClient } from 'graphql-ws';
-const wsLink = new GraphQLWsLink(createClient({
- url: 'ws://localhost:4000/subscriptions',
- connectionParams: {
- authentication: user.authToken,
- },
-}));
+const wsLink = new GraphQLWsLink(
+ createClient({
+ url: 'ws://localhost:4000/subscriptions',
+ connectionParams: {
+ authentication: user.authToken,
+ },
+ }),
+);
```
The `connectionParams` argument (which contains the information provided by the client) is passed to your server, enabling you to validate the user's credentials.
@@ -536,8 +541,8 @@ const findUser = async (authToken) => {
};
const getDynamicContext = async (ctx, msg, args) => {
- if (ctx.connectionParams.authentication) {
- const currentUser = await findUser(connectionParams.authentication);
+ if (ctx.connectionParams.authentication) {
+ const currentUser = await findUser(ctx.connectionParams.authentication);
return { currentUser };
}
// Let the resolvers know we don't have a current user so they can
@@ -550,8 +555,8 @@ useServer(
{
// Our GraphQL schema.
schema,
- context: (ctx, msg, args) => {
- // This will be run every time the client sends a subscription request
+ context: (ctx, msg, args) => {
+ // This will be run every time the client sends a subscription request
return getDynamicContext(ctx, msg, args);
},
},
@@ -581,20 +586,19 @@ The following are community-created `PubSub` libraries for popular event-publish
- [Azure SignalR Service](https://github.com/aaronpowell/graphql-azure-subscriptions)
- [Azure ServiceBus](https://github.com/abdomohamed/graphql-azure-servicebus-subscriptions)
-
If none of these libraries fits your use case, you can also create your own `PubSubEngine` subclass. If you create a new open-source library, click **Edit on GitHub** to let us know about it!
## Switching from `subscriptions-transport-ws`
->If you use subscriptions with Apollo Client you must ensure **[both your client and server subscription protocols are consistent](/react/data/subscriptions/#choosing-a-subscription-library)** for the subscription library you're using.
+> If you use subscriptions with Apollo Client you must ensure **[both your client and server subscription protocols are consistent](/react/data/subscriptions/#choosing-a-subscription-library)** for the subscription library you're using.
This article previously demonstrated using the `subscriptions-transport-ws` library to set up subscriptions. However, this library is no longer actively maintained. You can still use it with Apollo Server, but we strongly recommend using [`graphql-ws`](https://www.npmjs.com/package/graphql-ws) instead.
-For more information on using Apollo Server with `subscriptions-transport-ws`, you can view the [previous version of this article](https://github.com/apollographql/apollo-server/blob/4b82967c10a69aa104848a8c9d15c591b528918c/docs/source/data/subscriptions.mdx).
+For details on how to switch from `subscriptions-transport-ws` to `graphql-ws`, follow the steps in the [Apollo Server 3 docs](/apollo-server/v3/data/subscriptions/#switching-to-graphql-ws).
### Updating subscription clients
-If you intend to [switch from `subscriptions-transport-ws` to `graphql-ws`](#switching-to-graphql-ws) you will need to update the following clients:
+If you intend to [switch from `subscriptions-transport-ws` to `graphql-ws`](/apollo-server/v3/data/subscriptions/#switching-to-graphql-ws) you will need to update the following clients:
| [`subscriptions-transport-ws`](/studio/explorer/additional-features/#subscription-support) + | @@ -633,7 +638,6 @@ If you intend to [switch from `subscriptions-transport-ws` to `graphql-ws`](#swi -
Use [`GraphQLWsLink`](/react/api/link/apollo-link-subscriptions/) @@ -644,11 +648,11 @@ Use [`GraphQLWsLink`](/react/api/link/apollo-link-subscriptions/) | Use [`WebSocketLink`](/react/api/link/apollo-link-ws/) + | -
| @@ -656,7 +660,6 @@ Use [`WebSocketLink`](/react/api/link/apollo-link-ws/) | -
[`graphql_transport_ws`](/ios/api/ApolloWebSocket/enums/WebSocket.WSProtocol/#graphql_transport_ws) @@ -667,11 +670,11 @@ Use [`WebSocketLink`](/react/api/link/apollo-link-ws/) | [`graphql_ws`](/ios/api/ApolloWebSocket/enums/WebSocket.WSProtocol/#graphql_ws) + |
| @@ -689,147 +692,10 @@ Use [`WebSocketLink`](/react/api/link/apollo-link-ws/) | [`SubscriptionWsProtocol`](/kotlin/essentials/subscriptions/#customizing-your-websocket-protocol) + |
+>
+>