-
-
Notifications
You must be signed in to change notification settings - Fork 163
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(server): Make and use with your own flavour (#64)
BREAKING CHANGE: You now "make" a ready-to-use server that can be used with _any_ WebSocket implementation! Summary of breaking changes: - No more `keepAlive`. The user should provide its own keep-alive implementation. _(I highly recommend [WebSocket Ping and Pongs](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#Pings_and_Pongs_The_Heartbeat_of_WebSockets))_ - No more HTTP `request` in the server context. - No more WebSocket in the server context (you're the one that creates it). - You use your own WebSocket server - Server exports only `makeServer` _(no more `createServer`)_ ### Benefits - You're responsible for the server (_any_ optimisation or adjustment can be applied) - Any WebSocket server can be used (or even mocked if necessary) - You control the disposal of the server (close or transfer clients however you wish) - New `extra` field in the `Context` for storing custom values useful for callbacks - Full control of authentication flow - Full control over error handling - True zero-dependency ### Migrating from v1 **Only the server has to be migrated.** Since this release allows you to use your favourite WebSocket library (or your own implementation), using [ws](https://github.com/websockets/ws) is just one way of using `graphql-ws`. This is how to use the implementation shipped with the lib: ```ts /** * ❌ instead of the lib creating a WebSocket server internally with the provided arguments */ import https from 'https'; import { createServer } from 'graphql-ws'; const server = https.createServer(...); createServer( { onConnect(ctx) { // were previously directly on the context ctx.request as IncomingRequest ctx.socket as WebSocket }, ...rest, }, { server, path: '/graphql', }, ); /** * ✅ you have to supply the server yourself */ import https from 'https'; import ws from 'ws'; // yarn add ws import { useServer } from 'graphql-ws/lib/use/ws'; // notice the import path const server = https.createServer(...); const wsServer = new ws.Server({ server, path: '/graphql', }); useServer( { onConnect(ctx) { // are now in the `extra` field ctx.extra.request as IncomingRequest ctx.extra.socket as WebSocket }, ...rest, }, wsServer, // optional keepAlive with ping pongs (defaults to 12 seconds) ); ``` Closes: #61, closes: #73, closes: #75
- Loading branch information
Showing
20 changed files
with
1,099 additions
and
823 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| **[graphql-ws](../README.md)** | ||
|
|
||
| > [Globals](../README.md) / ["server"](../modules/_server_.md) / WebSocket | ||
| # Interface: WebSocket | ||
|
|
||
| ## Hierarchy | ||
|
|
||
| * **WebSocket** | ||
|
|
||
| ## Index | ||
|
|
||
| ### Properties | ||
|
|
||
| * [protocol](_server_.websocket.md#protocol) | ||
|
|
||
| ### Methods | ||
|
|
||
| * [close](_server_.websocket.md#close) | ||
| * [onMessage](_server_.websocket.md#onmessage) | ||
| * [send](_server_.websocket.md#send) | ||
|
|
||
| ## Properties | ||
|
|
||
| ### protocol | ||
|
|
||
| • `Readonly` **protocol**: string | ||
|
|
||
| The subprotocol of the WebSocket. Will be used | ||
| to validate agains the supported ones. | ||
|
|
||
| ## Methods | ||
|
|
||
| ### close | ||
|
|
||
| ▸ **close**(`code`: number, `reason`: string): Promise\<void> \| void | ||
|
|
||
| Closes the socket gracefully. Will always provide | ||
| the appropriate code and close reason. | ||
|
|
||
| The returned promise is used to control the graceful | ||
| closure. | ||
|
|
||
| #### Parameters: | ||
|
|
||
| Name | Type | | ||
| ------ | ------ | | ||
| `code` | number | | ||
| `reason` | string | | ||
|
|
||
| **Returns:** Promise\<void> \| void | ||
|
|
||
| ___ | ||
|
|
||
| ### onMessage | ||
|
|
||
| ▸ **onMessage**(`cb`: (data: string) => Promise\<void>): void | ||
|
|
||
| Called when message is received. The library requires the data | ||
| to be a `string`. | ||
|
|
||
| All operations requested from the client will block the promise until | ||
| completed, this means that the callback will not resolve until all | ||
| subscription events have been emittet (or until the client has completed | ||
| the stream), or until the query/mutation resolves. | ||
|
|
||
| Exceptions raised during any phase of operation processing will | ||
| reject the callback's promise, catch them and communicate them | ||
| to your clients however you wish. | ||
|
|
||
| #### Parameters: | ||
|
|
||
| Name | Type | | ||
| ------ | ------ | | ||
| `cb` | (data: string) => Promise\<void> | | ||
|
|
||
| **Returns:** void | ||
|
|
||
| ___ | ||
|
|
||
| ### send | ||
|
|
||
| ▸ **send**(`data`: string): Promise\<void> \| void | ||
|
|
||
| Sends a message through the socket. Will always | ||
| provide a `string` message. | ||
|
|
||
| Please take care that the send is ready. Meaning, | ||
| only provide a truly OPEN socket through the `opened` | ||
| method of the `Server`. | ||
|
|
||
| The returned promise is used to control the flow of data | ||
| (like handling backpressure). | ||
|
|
||
| #### Parameters: | ||
|
|
||
| Name | Type | | ||
| ------ | ------ | | ||
| `data` | string | | ||
|
|
||
| **Returns:** Promise\<void> \| void |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -10,8 +10,6 @@ | |
|
|
||
| ↳ [Client](_client_.client.md) | ||
|
|
||
| ↳ [Server](_server_.server.md) | ||
|
|
||
| ## Index | ||
|
|
||
| ### Properties | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| **[graphql-ws](../README.md)** | ||
|
|
||
| > [Globals](../README.md) / ["use/ws"](../modules/_use_ws_.md) / Extra | ||
| # Interface: Extra | ||
|
|
||
| The extra that will be put in the `Context`. | ||
|
|
||
| ## Hierarchy | ||
|
|
||
| * **Extra** | ||
|
|
||
| ## Index | ||
|
|
||
| ### Properties | ||
|
|
||
| * [request](_use_ws_.extra.md#request) | ||
| * [socket](_use_ws_.extra.md#socket) | ||
|
|
||
| ## Properties | ||
|
|
||
| ### request | ||
|
|
||
| • `Readonly` **request**: IncomingMessage | ||
|
|
||
| The initial HTTP request before the actual | ||
| socket and connection is established. | ||
|
|
||
| ___ | ||
|
|
||
| ### socket | ||
|
|
||
| • `Readonly` **socket**: WebSocket | ||
|
|
||
| The actual socket connection between the server and the client. |
Oops, something went wrong.