From d3a00c46af892453cb89e936ceaf8d17a3507bc1 Mon Sep 17 00:00:00 2001 From: Steve Ayers Date: Mon, 11 Nov 2024 11:29:51 -0500 Subject: [PATCH] Updates --- README.md | 89 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 61 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 4d5b95cf..841a5cfc 100644 --- a/README.md +++ b/README.md @@ -108,26 +108,21 @@ npm install @connectrpc/connect@^2.0.0 @connectrpc/connect-web@^2.0.0 Next, you'll need to account for any breaking changes. Following is a list to be aware of: -* `createGrpcTransport` now requires HTTP/2. +* The gRPC Transport now requires HTTP/2. If you are using `createGrpcTransport` + and specifying an `httpVersion`, it will fail compilation. Remove the + `httpVersion` property to use the default. - If you are using `createGrpcTransport` and specifying an `httpVersion`, it will - now fail compilation. Remove the `httpVersion` property to use the default. Note that if you were relying on HTTP/1.1 as part of your gRPC strategy, this may require bigger architectural changes, but the hope is that this is not a common problem. -* The deprecated `createPromiseClient` has been removed. - - Promise clients are now the default. Any callsites using `createPromiseClient` +* Promise clients are now the default and the previously-deprecated + `createPromiseClient` has been removed. Any callsites using `createPromiseClient` should be updated to use `createClient`. -* Node 16 is no longer supported. - - Connect v2 now supports Node versions 18.14.1 and up. - -* Requests with similar shapes can no longer be used interchangeably. +* Node 16 is no longer supported. Connect v2 now supports Node versions 18.14.1 and up. - Previously, Connect allowed request objects with matching shapes to be passed +* Previously, Connect allowed request objects with matching shapes to be passed to API calls interchangeably as long as the passed object was a superset of the target type. For example, given the following proto definitions: @@ -157,9 +152,7 @@ be aware of: This was an unintended bug and not a feature and in Connect v2, only the specified target type will pass compilation. -* `fetch`-related options `credentials` and `init` have been removed. - - We have removed the `credentials` option from transports as well as the `init` +* We have removed the `credentials` option from transports as well as the `init` option in interceptors. These two options were used to customize `fetch` routines. Users should now rely on the `fetch` option in transports as a way to perform these customizations. For example: @@ -175,26 +168,66 @@ be aware of: Connect GET request in server-side interceptors, the property `requestMethod: string` has been added to intercepted requests. This property is symmetrical to `HandlerContext.requestMethod`. -* The access pattern of `MethodDescriptor` has slightly changed. - - In v2, the Protobuf-ES plugin generates service descriptors and changes the +* The access pattern of `MethodDescriptor` has slightly changed. In v2, the + Protobuf-ES plugin generates service descriptors and changes the access pattern for method descriptors. Instead of the plural form `methods`, it now uses the singular `method`. - For example: `ElizaService.methods.Say` becomes `ElizaService.method.Say`. - -* Errors details are a pair of desc and init values - - TBD - -* MethodDescriptor is self sufficient + For example: `ElizaService.methods.Say` now becomes `ElizaService.method.Say`. + +* Errors details are now a pair of desc and init values. In Connect v1, error + details were specified as message instances. In v2, error + details are now an object that specifies both a schema and initialization + object which are both passed to the `create` function of Protobuf-ES. For example: + + ```diff + - import { LocalizedMessage } from "./gen/google/rpc/error_details_pb"; + - const details = [ + - new LocalizedMessage({ + - locale: "fr-CH", + - message: "Je n'ai plus de mots.", + - }), + - ]; + + import { LocalizedMessageSchema } from "./gen/google/rpc/error_details_pb"; + + const details = [ + + { + + desc: LocalizedMessageSchema, + + value: { + + locale: "fr-CH", + + message: "Je n'ai plus de mots.", + + } + + }, + + ]; + const metadata = new Headers({ + "words-left": "none" + }); + throw new ConnectError( + "I have no words anymore.", + Code.ResourceExhausted, + metadata, + details + ); + ``` - TBD +* `MethodDescriptor` is now self-sufficient. In v1, method descriptors always + had to be used alongside the service descriptors. In v2, they can now be used + standalone. This means that all callsites that previously passed a service + and method descriptor can now just pass the method descriptor. -* Interceptors always use stream types + A notable example is when using a Connect `Router` on the server-side: - TBD + ```diff + const routes = ({rpc}: Router) => { + - rpc(ElizaService, ElizaService.say, impl); + + rpc(ElizaService.say, impl); + } + ``` +* Interceptors for streaming RPCs now use appropriate stream types. In + v1, the server used more exact types in interceptors, for example `UnaryRequest` + for server-streaming rpcs while the client always used streaming variants. + This was unintended behavior and has been fixed in v2. Now all streaming RPCs + use the `StreamRequest` and `StreamResponse` on the server as well. ## Other platforms