Document limitations of Node.js streaming and protocols with HTTP 1.1 (…

…#174) Signed-off-by: Timo Stamm <[email protected]> Signed-off-by: Steve Ayers <[email protected]>
connectrpc · Sep 30, 2024 · a3b2c53 · a3b2c53
1 parent b48ace1
commit a3b2c53
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 11 deletions.
diff --git a/docs/node/server-plugins.md b/docs/node/server-plugins.md
@@ -40,6 +40,12 @@ ones:
   context values are passed to the service implementation. See
   [Context values](./interceptors.md#context-values) for more information.
 
+:::note
+Over HTTP/2, Node.js can serve the Connect, gRPC, and gRPC-Web protocols with
+all types of RPCs.
+Over HTTP 1.1, the gRPC protocol and bidirectional streaming RPCs are not
+supported.
+:::
 
 ## Fastify
 
@@ -49,7 +55,7 @@ with your Connect RPCs. Use the plugin from [@connectrpc/connect-fastify](https:
 with Fastify:
 
 ```bash
-$ npm install fastify @connectrpc/connect-node @connectrpc/connect-fastify
+$ npm install fastify @connectrpc/connect @connectrpc/connect-node @connectrpc/connect-fastify
 ```
 
 ```ts
@@ -75,8 +81,12 @@ The plugin accepts all common options, and the following additional ones:
   context values are passed to the service implementation. See
   [Context values](./interceptors.md#context-values) for more information.
 
-Note that `@connectrpc/connect` and `@connectrpc/connect-node` are peer 
-dependencies of  `@connectrpc/connect-fastify`.
+:::note
+Over HTTP/2, Fastify can serve the Connect, gRPC, and gRPC-Web protocols with
+all types of RPCs.
+Over HTTP 1.1, the gRPC protocol and bidirectional streaming are not supported.
+:::
+
 
 ## Next.js
 
@@ -85,7 +95,7 @@ using the latest React features. With [@connectrpc/connect-next](https://www.npm
 you can serve your Connect RPCs via Next.js API Routes.
 
 ```bash
-$ npm install next @connectrpc/connect-node @connectrpc/connect-next
+$ npm install next @connectrpc/connect @connectrpc/connect-node @connectrpc/connect-next
 ```
 
 To enable the server plugin, create the file `pages/api/[[...connect]].ts` in your project:
@@ -110,7 +120,10 @@ one:
   context values are passed to the service implementation. See
   [Context values](./interceptors.md#context-values) for more information.
 
-Note that Next.js does not support the http2 module.
+:::note
+Next.js does not support the `http2` module. You can serve the Connect protocol 
+and gRPC-Web. The gRPC protocol and bidirectional streaming are not supported.
+:::
 
 ## Express
 
@@ -119,7 +132,7 @@ popular because of its simplicity. Use the middleware provided by [@connectrpc/c
 to add your Connect RPCs to Express:
 
 ```bash
-$ npm install express @connectrpc/connect-node @connectrpc/connect-express
+$ npm install express @connectrpc/connect @connectrpc/connect-node @connectrpc/connect-express
 ```
 
 ```ts
@@ -149,8 +162,11 @@ Note that many gRPC client implementations do not allow for prefixes.
   context values are passed to the service implementation. See
   [Context values](./interceptors.md#context-values) for more information.
 
-
-Note that Express does not support the `http2` module.
+:::note
+Express does not support the `http2` module. You can serve the Connect protocol 
+and gRPC-Web. The gRPC protocol and bidirectional streaming RPCs are not 
+supported.
+:::
 
 
 ## Common options

diff --git a/docs/node/using-clients.md b/docs/node/using-clients.md
@@ -36,9 +36,9 @@ headers and trailers), please refer to the documentation for [Web](../web/using-
 
 Under the hood, the transports from [@connectrpc/connect-node](https://www.npmjs.com/package/@connectrpc/connect-node)
 use the built-in Node modules `http`, `https`, and `http2` instead of the fetch
-API. They allow us to provide a transport for gRPC and to support bidi streaming. 
-Node.js v18 comes with `fetch()`, but it is limited to HTTP 1.1.
-
+API. With HTTP/2, clients can use the Connect, gRPC, or gRPC-Web protocol, and 
+call all types of RPCs. With HTTP 1.1, the gRPC protocol and bidirectional 
+streaming are not supported.
 
 ## Connect