v0.9.0

[timostamm]

What's Changed

As of this release, connect-es supports performing idempotent, side-effect free requests using HTTP GETs. This makes it easier to cache responses in the browser, on your CDN, or in proxies and other middleboxes.

Note
This functionality is only supported when using the Connect protocol—using a Connect client with a Connect server. When using any gRPC or gRPC-web client, including createGrpcTransport() and createGrpcWebTransport() from @bufbuild/connect-web or @bufbuild/connect-node, all requests will continue to be HTTP POSTs.

To opt into GET support for a given Protobuf RPC, you must mark it as being side-effect free using the MethodOptions.IdempotencyLevel option:

service ElizaService {
  rpc Say(stream SayRequest) returns (SayResponse) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
}

With this schema change, handlers will automatically support both GET and POST requests for this RPC. However, clients will continue to use POST requests by default, even when GETs are possible. To make clients use GETs for side effect free RPCs, set the useHttpGet option:

const transport = createConnectTransport({
  // ...
  useHttpGet: true
});

Another noteworthy change is the full support of timeouts, also known as deadlines in gRPC. For example, when a client provides the timeoutMs call option, a header Connect-Timeout-Ms is added to the request. The server parses this timeout, and if it takes longer than the given timeout to process the request, it should give up, and respond with the error code deadline_exceeded.

On a connect-es server, the parsed timeout is available as an AbortSignal on the context:

import type { HandlerContext } from "@bufbuild/connect";

const say = async (req: SayRequest, ctx: HandlerContext) => {

  ctx.signal.aborted; // true if timed out
  ctx.signal.reason; // an error with code deadline_exceed if timed out
  ctx.timeoutMs(); // the remaining time in milliseconds

  // raises an error with code deadline_exceed if timed out
  ctx.signal.throwIfAborted();

  // the AbortSignal can be passed to other functions
  await longRunning(ctx.signal);

  return new SayResponse({sentence: `You said: ${req.sentence}`});
};

Enhancements

• Add client support for Connect HTTP GET requests by @jchadwick-buf in Add client support for Connect HTTP GET requests #620
• Add server support for Connect HTTP GET requests by @jchadwick-buf in Add server support for Connect HTTP GET requests #624
• Allow a fetch override for connect-web by @dimitropoulos in Allow a fetch override for connect-web #618
• Support timeouts in clients by @timostamm in Support timeouts in clients #635
• Support timeouts in handlers by @timostamm in Support timeouts in handlers #591
• Update HandlerContext signal to trigger on other reasons than timeouts by @johynpapin in Update HandlerContext signal to trigger on other reasons than timeouts #531
• Add a timeout getter to the HandlerContext and export createHandlerContext by @timostamm in Add a timeout getter to HandlerContext and export createHandlerContext #632
• Add from() and findDetails() to ConnectError by @timostamm in Add from() and findDetails() to ConnectError #638
• Always generate files when no services exist by @sjbarag in Always generate files when no services exist #598

Bugfixes

• Fix UniversalHandlers resolving the response before headers are complete by @timostamm in Fix UniversalHandlers resolving the response before headers are complete #588
• Improve tests for Node.js clients and fix hanging requests by @timostamm in Improve tests for Node.js clients and fix hanging requests #619
• Indent "idempotency" in protoc-gen-connect-es by @timostamm in Indent "idempotency" in protoc-gen-connect-es #626
• Close the session on error in client transports by @timostamm in Close the session on error in client transports #623
• Raise proper Connect error codes for closed streams in handlers by @timostamm in Raise proper Connect error codes for closed streams in handlers #628
• Support client-side cancellation in the router transport by @timostamm in Support client-side cancellation in the router transport #637

Breaking changes

• Remove deprecated exports from connect-web by @smaye81 in Remove deprecated exports from connect-web #636
• Stop supporting Node.js earlier than v16 in protoc-gen-es by @dimitropoulos in Stop supporting Node.js earlier than v16 in protoc-gen-es #614

New Contributors

• @bufdev made their first contribution in Update README.md #593
• @sjbarag made their first contribution in Always generate files when no services exist #598

Full Changelog: v0.8.6...v0.9.0

---

This discussion was created from the release v0.9.0.