@trevrpc/trevrpc-js 1.6.0 → 1.8.0

package/README.md

@@ -4,6 +4,10 @@ TrevRPC is an RPC framework like gRPC, but uses QUIC (and HTTP/3 / WebTransport)
 
 `trevrpc-js` is the **browser client**: a WebTransport runtime with a QMux over WebSocket fallback, for the messages and service descriptors that [protobuf-es](https://github.com/bufbuild/protobuf-es) generates. It has no Node.js runtime; servers are written in Go or Rust, native QUIC clients in Go or Rust, and HTTP/3 clients in Kotlin.
 
+> **Compatibility:** every TrevRPC package shares one version, and packages of the same version are compatible
+> with each other: `trevrpc-rust` 1.8.0 works with `trevrpc-go` 1.8.0, `trevrpc-js` 1.8.0, and `trevrpc-kotlin`
+> 1.8.0. Compatibility across different versions isn't guaranteed yet; that's a milestone for 2.0.
+
 Full documentation: https://trev.zip/llc/TrevRPC/wiki
 
 ## Protobuf
@@ -205,7 +209,7 @@ channel.setConnectionMetadata({ authorization: `Bearer ${refreshed}` }); // call
 channel.setConnectionMetadata(); // removes it
 ```
 
-A changed set is sent in full again on every session, and so is the set on a session after a reconnect. Keys follow the rules of call metadata. Other transports carry it when they forward a channel's `connectionMetadata`.
+A call carries the set that is current when it starts, once its interceptors have run, until it ends, like its own `metadata`: a change applies to calls that start after it, and a call still waiting for the channel to connect keeps the set it started with. A changed set is sent in full again on every session, and so is the set on a session after a reconnect. Keys follow the rules of call metadata. Other transports carry it when they forward a channel's `connectionMetadata`.
 
 ### Interceptors
 
@@ -235,6 +239,18 @@ const client = createClient(Greeter, channel, { interceptors: [logCalls] });
 - An interceptor that throws fails the call with what it threw before it starts; the finish functions of earlier interceptors still run.
 - A client-streaming call has a `status` promise too, like the other streaming calls.
 
+### Request validation
+
+The separate package [`@trevrpc/protovalidate`](protovalidate) checks request messages against their [`buf.validate`](https://buf.build/bufbuild/protovalidate) rules before they are sent, with [protovalidate](https://github.com/bufbuild/protovalidate-es):
+
+```js
+import { createRequestValidator } from "@trevrpc/protovalidate";
+
+const client = createClient(Greeter, channel, { validator: createRequestValidator() });
+```
+
+A request that breaks its rules fails with `Code.InvalidArgument` and a `buf.validate.Violations` detail, which `error.findDetails(ViolationsSchema)` decodes, as a Go or Rust server that validates requests reports it. The request of a unary or server-streaming call fails the call after its interceptors ran; a message passed to `send()` rejects that send, and the call goes on. Methods whose request type has no rules are not checked. The `validator` option takes any object with a `validateFunc(schema)` method that returns the check of that request type, or nothing to skip it; see `RequestValidator`.
+
 ### Effect
 
 The separate package [`@trevrpc/effect`](effect) makes clients for [Effect](https://effect.website): `createEffectClient(Greeter, channel)` returns a client whose unary calls are effects, whose server-streaming calls are streams, and whose client-streaming and bidirectional calls take their requests as a stream. Interrupting an effect or stream cancels its call. `TrevRpcError` has a `_tag` of `"TrevRpcError"`, so `Effect.catchTag` matches it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevrpc/trevrpc-js",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Browser WebTransport client for TrevRPC, on protobuf-es",
   "homepage": "https://trev.zip/llc/TrevRPC",
   "bugs": {
@@ -48,7 +48,7 @@
     "@connectrpc/connect": "^2.3.0",
     "@connectrpc/connect-web": "^2.3.0",
     "playwright": "1.64.1",
-    "rolldown": "^1.3.0",
+    "rolldown": "^1.3.1",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {

package/src/call.js

@@ -167,8 +167,9 @@ export class Call {
   #flushing = false;
   /**
    * What the call needs to open itself again, for the replay of a refused optimistic call:
-   * `{ transport, request, rpc, deadline }`, where `deadline` is the `performance.now()` time the
-   * call's timeout ends, or undefined.
+   * `{ transport, request, rpc, deadline, connectionMetadata }`, where `deadline` is the
+   * `performance.now()` time the call's timeout ends, or undefined, and `connectionMetadata` is
+   * the connection metadata set the call carries, or undefined.
    */
   #setup;
   /**
@@ -201,12 +202,14 @@ export class Call {
   static async open(transport, request, message, options, rpc = {}) {
     const fields = { ...request, metadata: options.metadata, ...timeoutField(options) };
     const compression = transportCompression(transport);
+    // The call carries the connection metadata that is current as it starts, like its own
+    // metadata, until it ends: a change while its stream opens or before a replay is for later
+    // calls.
+    const connectionMetadata = transportConnectionMetadata(transport)?.current;
     // The REQUEST depends on the session that carries the call if it negotiates compression, opens
     // a datagram flow or carries connection metadata.
     const perSession =
-      rpc.datagrams !== undefined ||
-      compression !== undefined ||
-      transportConnectionMetadata(transport)?.current !== undefined;
+      rpc.datagrams !== undefined || compression !== undefined || connectionMetadata !== undefined;
     const header = perSession
       ? null
       : encodeRequestFrame(fields, outgoing(message), options.maxFrameSize);
@@ -221,6 +224,7 @@ export class Call {
         request: { ...request, metadata: options.metadata },
         rpc,
         deadline: options.timeoutMs == null ? undefined : performance.now() + options.timeoutMs,
+        connectionMetadata,
       };
       await call.#write(
         header ?? call.#requestOnSession(fields, message, session, compression, transport, rpc),
@@ -236,7 +240,8 @@ export class Call {
 
   /**
    * Sets the call up on the session that carries it, negotiating compression and opening its
-   * datagram flow as the method needs, and encodes the REQUEST. A call whose requests may be
+   * datagram flow as the method needs, and encodes the REQUEST with the connection metadata the
+   * call carries, offered or referred to as the session needs. A call whose requests may be
    * stream-compressed offers optimistically while the session allows it, unless `replay` says this
    * is the replay of a refused call or the call has a datagram flow, which a replay would need to
    * open again.
@@ -277,13 +282,12 @@ export class Call {
         }
       }
     }
-    this.#connectionMetadata = transportConnectionMetadata(transport)?.session(session.key);
-    if (this.#connectionMetadata !== undefined) {
-      const { field, offered } = this.#connectionMetadata.prepare();
+    const set = this.#setup.connectionMetadata;
+    if (set !== undefined) {
+      this.#connectionMetadata = transportConnectionMetadata(transport).session(session.key);
+      const { field, offered } = this.#connectionMetadata.prepare(set);
       this.#offeredMetadata = offered;
-      if (field !== undefined) {
-        request.connectionMetadata = field;
-      }
+      request.connectionMetadata = field;
     }
     return encodeRequestFrame(
       request,
@@ -769,7 +773,8 @@ export class Call {
 /**
  * Opens a bidirectional stream. A call whose setup depends on its session passes `session`, which
  * receives that session's `key` and `datagrams` object, so the compression state and datagram flow
- * belong to the connection that carries the call and not to one a reconnect swapped in later.
+ * belong to the connection that carries the call and not to one a reconnect swapped in later. A
+ * stream the browser refuses for want of stream credit is opened again (see StreamRefusalRetryMs).
  */
 function openStream(transport, signal, session) {
   return new Promise((resolve, reject) => {
@@ -777,34 +782,72 @@ function openStream(transport, signal, session) {
       reject(signal.reason);
       return;
     }
-    const onAbort = () => reject(signal.reason);
+    let retryTimer;
+    const onAbort = () => {
+      clearTimeout(retryTimer);
+      reject(signal.reason);
+    };
     signal.addEventListener("abort", onAbort, { once: true });
-
-    let opening;
-    try {
-      opening = Promise.resolve(startStream(transport, session));
-    } catch (error) {
-      opening = Promise.reject(error);
-    }
-    opening.then(
-      (stream) => {
-        signal.removeEventListener("abort", onAbort);
-        if (signal.aborted) {
-          // The caller gave up while the stream was opening; do not leak it.
-          stream.writable.abort(signal.reason).catch(() => {});
-          stream.readable.cancel(signal.reason).catch(() => {});
-        } else {
-          resolve(stream);
-        }
-      },
-      (error) => {
-        signal.removeEventListener("abort", onAbort);
-        reject(statusFromTransportError(error));
-      },
-    );
+    const giveUpAt = Date.now() + StreamRefusalRetryMs;
+
+    const attempt = (delay) => {
+      let opening;
+      try {
+        opening = Promise.resolve(startStream(transport, session));
+      } catch (error) {
+        opening = Promise.reject(error);
+      }
+      opening.then(
+        (stream) => {
+          signal.removeEventListener("abort", onAbort);
+          if (signal.aborted) {
+            // The caller gave up while the stream was opening; do not leak it.
+            stream.writable.abort(signal.reason).catch(() => {});
+            stream.readable.cancel(signal.reason).catch(() => {});
+          } else {
+            resolve(stream);
+          }
+        },
+        (error) => {
+          if (signal.aborted) {
+            return;
+          }
+          if (isStreamRefusal(error) && Date.now() + delay <= giveUpAt) {
+            // Nothing reached the server, so opening the stream again is safe.
+            retryTimer = setTimeout(
+              () => attempt(Math.min(delay * 2, StreamRefusalMaxDelayMs)),
+              delay,
+            );
+            return;
+          }
+          signal.removeEventListener("abort", onAbort);
+          reject(statusFromTransportError(error));
+        },
+      );
+    };
+    attempt(StreamRefusalFirstDelayMs);
   });
 }
 
+/**
+ * How long a call keeps opening a stream the browser refused, and how long it waits between
+ * attempts. Chromium refuses a new WebTransport stream at once while the server's stream credit is
+ * used up, where the WebTransport spec has it wait for more. Credit comes back about two round
+ * trips after a stream opens, so the call waits for it itself, doubling the delay from 1 ms.
+ */
+const StreamRefusalRetryMs = 2000;
+const StreamRefusalFirstDelayMs = 1;
+const StreamRefusalMaxDelayMs = 64;
+
+/**
+ * Whether opening a stream failed because the browser refused it for now: Chromium's NetworkError
+ * "Failed to create bidirectional stream". A closed session fails differently, and a channel
+ * without a session fails with a status.
+ */
+function isStreamRefusal(error) {
+  return !(error instanceof TrevRpcError) && error?.name === "NetworkError";
+}
+
 function messageOf(item) {
   return item.message;
 }

package/src/client.js

@@ -4,18 +4,20 @@ import { interceptCall, interceptorList } from "./interceptor.js";
 import { validateMetadata } from "./metadata.js";
 import { methodSettings } from "./method-options.js";
 import { Code, cancelled, internal, invalidArgument, statusError } from "./status.js";
+import { requestValidation } from "./validator.js";
 import { RpcAnswer, RpcHeaders, RpcKind, RpcStatus } from "./wire.js";
 
 /**
  * Creates a client for `service`, a service descriptor that protoc-gen-es generates, with one
  * function per method, named by the method's `localName`. Its calls run the interceptors of the
- * transport, then those of `options.interceptors`.
+ * transport, then those of `options.interceptors`, and `options.validator` checks the request
+ * messages they send.
  */
 export function createClient(service, transport, options = {}) {
   if (service?.kind !== "service" || !Array.isArray(service.methods)) {
     throw invalidArgument("createClient needs a protobuf-es service descriptor");
   }
-  const { interceptors: clientInterceptors, ...callOptions } = options;
+  const { interceptors: clientInterceptors, validator, ...callOptions } = options;
   const defaults = mergeCallOptions(defaultCallOptions(), callOptions);
   const interceptors = [
     ...interceptorList(transport.interceptors, "transport interceptors"),
@@ -30,6 +32,8 @@ export function createClient(service, transport, options = {}) {
       path: `/${service.typeName}/${method.name}`,
       requestType: method.input,
       responseType: method.output,
+      // Checks each request message once it is encoded, or undefined to send them unchecked.
+      validate: requestValidation(validator, method.input),
       // Full protobuf names, which pick the compression dictionaries.
       types: { request: method.input.typeName, response: method.output.typeName },
       datagrams: datagramUse(settings),
@@ -91,7 +95,7 @@ const MethodShapes = Object.freeze({
 
 /** Calls a unary RPC and returns the decoded response. */
 export async function unaryCall(transport, rpc, request, options) {
-  const body = marshalMessage(rpc.requestType, request);
+  const body = marshalMessage(rpc.requestType, request, rpc.validate);
   const call = await Call.open(transport, requestFields(rpc, RpcKind.Unary), body, options, rpc);
   const stream = new BidirectionalStreamingCall(call, rpc, { options });
   // The response decides the outcome, so the request side finishes in the background.
@@ -101,7 +105,7 @@ export async function unaryCall(transport, rpc, request, options) {
 
 /** Calls a server-streaming RPC and returns its response stream. */
 export async function serverStreamingCall(transport, rpc, request, options) {
-  const body = marshalMessage(rpc.requestType, request);
+  const body = marshalMessage(rpc.requestType, request, rpc.validate);
   const call = await Call.open(
     transport,
     requestFields(rpc, RpcKind.ServerStreaming),
@@ -329,10 +333,12 @@ export class BidirectionalStreamingCall {
   /**
    * Sends one request message. Fails with the server's final status if the server ended the
    * call, as soon as it is known; with Cancelled if that status is OK; and with the error that
-   * ended the call otherwise.
+   * ended the call otherwise. A message that cannot be encoded, or that the client's validator
+   * rejects, fails with InvalidArgument (or the validator's status) and is not sent; the call
+   * goes on.
    */
   async send(message) {
-    const body = marshalMessage(this.#rpc.requestType, message);
+    const body = marshalMessage(this.#rpc.requestType, message, this.#rpc.validate);
     try {
       await this.#call.sendMessage(body);
     } catch (error) {
@@ -515,7 +521,7 @@ export class BidirectionalStreamingCall {
   }
 
   /** The final status arrived: it is the outcome, and it ends the upload. */
-  #endWithStatus({ code, message, metadata }) {
+  #endWithStatus({ code, message, metadata, details }) {
     if (code === Code.Ok && this.#onResponseMetadata !== undefined) {
       try {
         this.#onResponseMetadata(metadata);
@@ -524,7 +530,8 @@ export class BidirectionalStreamingCall {
         return;
       }
     }
-    const error = code === Code.Ok ? undefined : statusError(code, message, metadata);
+    const error =
+      code === Code.Ok ? undefined : statusError(code, message, metadata, undefined, details);
     this.#terminal = { status: { code, message, metadata }, error };
     this.#call.finish(error);
     if (error === undefined) {

package/src/connection-metadata.js

@@ -5,7 +5,9 @@
 // in any order, so a reference only follows a confirmation. The server merges the set into each
 // call's metadata, the call's own entries winning, so the client just sends both; see the wiki's
 // Connection Metadata section. This module holds the channel's set and what each session
-// confirmed; call.js puts them on the REQUEST and learns the confirmation from the ANSWER.
+// confirmed; call.js puts them on the REQUEST and learns the confirmation from the ANSWER. A call
+// carries the set that was current when it started for its whole life, replays included, so a
+// change applies to the calls that start after it.
 import { normalizeMetadata } from "./metadata.js";
 
 /**
@@ -16,9 +18,6 @@ export function transportConnectionMetadata(transport) {
   return transport.connectionMetadata ?? undefined;
 }
 
-/** A request that carries no connection metadata. */
-const NoConnectionMetadata = Object.freeze({ field: undefined, offered: 0 });
-
 /**
  * A channel's connection metadata, shared by its sessions: the current set, whose ID changes with
  * it, and the state of each session.
@@ -83,17 +82,15 @@ class SessionConnectionMetadata {
   }
 
   /**
-   * The connection metadata of one REQUEST as `{ field, offered }`: `field` is the value of
-   * `connectionMetadata`, a reference to the current set once the session confirmed it and an
-   * offer of it otherwise, or undefined without a set; `offered` is the ID the REQUEST offers,
-   * which `learn` checks the ANSWER against, or zero.
+   * The connection metadata of a REQUEST that carries `set`, the current set when its call
+   * started, as `{ field, offered }`: `field` is the value of `connectionMetadata`, a reference to
+   * the set if this session confirmed it and it is still current, and an offer of it otherwise;
+   * `offered` is the ID the REQUEST offers, which `learn` checks the ANSWER against, or zero.
    */
-  prepare() {
-    const set = this.#source.current;
-    if (set === undefined) {
-      return NoConnectionMetadata;
-    }
-    if (this.#confirmed === set.id) {
+  prepare(set) {
+    // The server keeps the newest few sets the session offered, so one replaced since its call
+    // started may be gone: only the current set is referred to.
+    if (this.#confirmed === set.id && this.#source.current === set) {
       return { field: { id: set.id }, offered: 0 };
     }
     return { field: { id: set.id, metadata: set.metadata }, offered: set.id };

package/src/framing.js

@@ -23,17 +23,24 @@ const EmptyBytes = new Uint8Array(0);
 
 /**
  * Encodes a protobuf message body: `message` is a message of `schema` (a protobuf-es message
- * descriptor) or the init object `create()` takes.
+ * descriptor) or the init object `create()` takes. A message that cannot be encoded fails with
+ * InvalidArgument. Once it is encoded, `validate`, if given, checks it and throws to reject it,
+ * so that it sees only well-formed messages.
  */
-export function marshalMessage(schema, message) {
+export function marshalMessage(schema, message, validate) {
+  let value;
+  let body;
   try {
-    return toBinary(schema, create(schema, message));
+    value = create(schema, message);
+    body = toBinary(schema, value);
   } catch (error) {
     throw invalidArgument(
       `failed to encode protobuf message: ${error?.message ?? String(error)}`,
       error,
     );
   }
+  validate?.(value);
+  return body;
 }
 
 /** Decodes a protobuf message body of `schema`, rejecting malformed wire data. */

package/src/index.d.ts

@@ -29,15 +29,36 @@ export type MetadataValue = string | Uint8Array | ArrayBuffer | ArrayBufferView
 export type MetadataInput = Record<string, MetadataValue> | ReadonlyMap<string, MetadataValue>;
 export type Metadata = Record<string, Uint8Array>;
 
-/** Error carrying a TrevRPC status code, message, and metadata. */
+/**
+ * One detail of a status: a protobuf message, carried as its full name, such as
+ * `"buf.validate.Violations"`, and its encoding.
+ */
+export interface StatusDetail {
+  readonly type: string;
+  readonly value: Uint8Array;
+}
+
+export interface TrevRpcErrorOptions extends ErrorOptions {
+  details?: readonly StatusDetail[];
+}
+
+/** Error carrying a TrevRPC status code, message, metadata, and details. */
 export class TrevRpcError extends Error {
   /** Always `"TrevRpcError"`, for matching errors by tag, as Effect's `catchTag` does. */
   readonly _tag: "TrevRpcError";
   readonly code: StatusCode;
   readonly statusMessage: string;
   readonly metadata: Metadata;
+  /** The status details, still encoded; `findDetails` decodes those of one message type. */
+  readonly details: readonly StatusDetail[];
+
+  constructor(code: number, message?: string, metadata?: Metadata, options?: TrevRpcErrorOptions);
 
-  constructor(code: number, message?: string, metadata?: Metadata, options?: ErrorOptions);
+  /**
+   * Decodes the details whose type is the full name of `schema`, such as `ViolationsSchema` for
+   * `buf.validate.Violations`.
+   */
+  findDetails<Desc extends DescMessage>(schema: Desc): MessageShape<Desc>[];
 }
 
 export interface CallOptions {
@@ -109,10 +130,39 @@ export type CallInterceptor = (
   call: InterceptedCall,
 ) => void | CallFinish | Promise<void | CallFinish>;
 
-/** Options of a service client: defaults for its calls, and interceptors that run around them. */
+/**
+ * Checks the request messages of a client before they are sent; see `ClientOptions.validator`.
+ * `@trevrpc/protovalidate` implements it with `buf.validate` rules.
+ */
+export interface RequestValidator {
+  /**
+   * Returns the function that checks request messages of type `schema`, or nothing when messages
+   * of that type never need checking, which costs their methods nothing. `createClient` calls it
+   * once for each method, and throws what it throws.
+   *
+   * The returned function throws to reject a message, which is then not sent: a TrevRpcError
+   * fails the request as it is, normally InvalidArgument with details that say why, and any other
+   * error fails it with InvalidArgument and the error as `cause`. It only sees messages that
+   * encode.
+   */
+  validateFunc<Desc extends DescMessage>(
+    schema: Desc,
+  ): ((message: MessageShape<Desc>) => void) | undefined | void;
+}
+
+/**
+ * Options of a service client: defaults for its calls, the interceptors that run around them, and
+ * the validator of their request messages.
+ */
 export interface ClientOptions extends CallOptions {
   /** Interceptors for the client's calls, after those of its transport, such as a Channel's. */
   interceptors?: readonly CallInterceptor[];
+  /**
+   * Checks every request message before it is sent: the request of a unary or server-streaming
+   * call, which fails the call after its interceptors ran, and each message passed to `send()`,
+   * which rejects that send and leaves the call open. Without one, requests are not checked.
+   */
+  validator?: RequestValidator;
 }
 
 export interface TransportStream {
@@ -239,7 +289,9 @@ export interface ClientStreamingCall<TRequest, TResponse> {
    * error. A failed send is not retried or reported twice: later sends fail the same way, and
    * `closeAndRecv()` returns the call's outcome.
    *
-   * Pending sends are rejected too when the call is cancelled or its deadline expires.
+   * Pending sends are rejected too when the call is cancelled or its deadline expires. A
+   * message that cannot be encoded, or that the client's `validator` rejects, is not sent: the
+   * send rejects with InvalidArgument (or the validator's status) and the call goes on.
    */
   send(request: TRequest): Promise<void>;
   /**
@@ -293,7 +345,9 @@ export interface BidirectionalStreamingCall<TRequest, TResponse> extends AsyncIt
    * status: at most 32 frames or 1 MiB (plus one frame of at most `maxFrameSize`), after which
    * reading pauses until `recv()` takes messages. Responses read ahead are delivered in order.
    *
-   * Pending sends are rejected too when the call is cancelled or its deadline expires.
+   * Pending sends are rejected too when the call is cancelled or its deadline expires. A
+   * message that cannot be encoded, or that the client's `validator` rejects, is not sent: the
+   * send rejects with InvalidArgument (or the validator's status) and the call goes on.
    */
   send(request: TRequest): Promise<void>;
   /**
@@ -363,7 +417,8 @@ export type Client<S extends DescService> = {
  * Creates a client for `service`, a service descriptor that protoc-gen-es generates (such as
  * `GreeterService` from `greeter_pb.js`). The `trevrpc.method` option of each method decides
  * what its calls send as datagrams and compress; one the method's kind cannot use throws
- * InvalidArgument. Calls run the transport's interceptors, then those of `options.interceptors`.
+ * InvalidArgument. Calls run the transport's interceptors, then those of `options.interceptors`,
+ * and `options.validator` checks the request messages they send.
  */
 export function createClient<S extends DescService>(
   service: S,
@@ -527,9 +582,11 @@ export class Channel implements Transport {
   readonly interceptors: readonly CallInterceptor[];
   /**
    * Replaces the channel's connection metadata (see `ConnectOptions.connectionMetadata`); empty or
-   * missing metadata removes it. Calls started after this use the new metadata, and each
-   * connection sends it again before referring to it. Throws if it is invalid, and then keeps the
-   * old.
+   * missing metadata removes it. A call carries the connection metadata that is current when it
+   * starts, once its interceptors have run, until it ends: calls started after this use the new
+   * metadata, and calls in flight keep theirs, even if they are still connecting. Each connection
+   * sends the new metadata again before referring to it. Throws if it is invalid, and then keeps
+   * the old.
    */
   setConnectionMetadata(metadata?: MetadataInput): void;
   createBidirectionalStream(): Promise<TransportStream>;

package/src/status.js

@@ -1,3 +1,5 @@
+import { fromBinary } from "@bufbuild/protobuf";
+
 export const Code = Object.freeze({
   Ok: 0,
   Cancelled: 1,
@@ -20,7 +22,7 @@ export const Code = Object.freeze({
 
 const CodeNames = Object.freeze(Object.keys(Code));
 
-/** Error carrying a TrevRPC status code, message, and metadata. */
+/** Error carrying a TrevRPC status code, message, metadata, and details. */
 export class TrevRpcError extends Error {
   /** Creates a TrevRPC status error. */
   constructor(code, message = "", metadata = {}, options = {}) {
@@ -34,6 +36,17 @@ export class TrevRpcError extends Error {
     this.code = normalizedCode;
     this.statusMessage = message;
     this.metadata = metadata;
+    this.details = options.details ?? [];
+  }
+
+  /**
+   * Decodes the details whose type is the full name of `schema`, a message schema generated by
+   * protoc-gen-es, such as `ViolationsSchema` for `buf.validate.Violations`.
+   */
+  findDetails(schema) {
+    return this.details
+      .filter((detail) => detail.type === schema.typeName)
+      .map((detail) => fromBinary(schema, detail.value));
   }
 }
 
@@ -52,8 +65,8 @@ export function codeName(code) {
 }
 
 /** Creates a TrevRPC status error. */
-export function statusError(code, message = "", metadata = {}, cause) {
-  return new TrevRpcError(code, message, metadata, { cause });
+export function statusError(code, message = "", metadata = {}, cause, details) {
+  return new TrevRpcError(code, message, metadata, { cause, details });
 }
 
 /** Creates an internal error status. */

package/src/validator.js

@@ -0,0 +1,36 @@
+import { TrevRpcError, invalidArgument } from "./status.js";
+
+/**
+ * Returns the function that checks request messages of `schema` with `validator`, the
+ * `validator` option of a client, or undefined when there is no validator or it never needs to
+ * check that type, which costs the method nothing. The function throws a TrevRpcError: the one
+ * the validator threw, or InvalidArgument with any other error as cause. Throws InvalidArgument
+ * if `validator` is not a request validator, and what `validator.validateFunc` throws.
+ */
+export function requestValidation(validator, schema) {
+  if (validator == null) {
+    return undefined;
+  }
+  if (typeof validator.validateFunc !== "function") {
+    throw invalidArgument("validator must have a validateFunc method");
+  }
+  const validate = validator.validateFunc(schema);
+  if (validate == null) {
+    return undefined;
+  }
+  if (typeof validate !== "function") {
+    throw invalidArgument(
+      `validator.validateFunc must return a function or nothing for ${schema.typeName}`,
+    );
+  }
+  return (message) => {
+    try {
+      validate(message);
+    } catch (error) {
+      if (error instanceof TrevRpcError) {
+        throw error;
+      }
+      throw invalidArgument(error?.message ?? String(error), error);
+    }
+  };
+}

package/src/wire.js

@@ -164,7 +164,10 @@ export const RpcAnswer = Object.freeze({
   },
 });
 
-/** The STATUS payload: `{ code, message, metadata, refusedStreamCompression }`. */
+/**
+ * The STATUS payload: `{ code, message, metadata, refusedStreamCompression, details }`, where each
+ * detail is `{ type, value }`.
+ */
 export const RpcStatus = Object.freeze({
   name: "RpcStatus",
   encode(status) {
@@ -173,6 +176,14 @@ export const RpcStatus = Object.freeze({
     writeString(writer, 2, status.message);
     writeMetadata(writer, 3, status.metadata);
     writeBool(writer, 4, status.refusedStreamCompression);
+    for (const detail of status.details ?? []) {
+      writer.tag(5, WireType.LengthDelimited).fork();
+      writeString(writer, 1, detail.type);
+      if (detail.value != null && detail.value.byteLength > 0) {
+        writer.tag(2, WireType.LengthDelimited).bytes(detail.value);
+      }
+      writer.join();
+    }
     return writer.finish();
   },
   decode(bytes) {
@@ -181,6 +192,7 @@ export const RpcStatus = Object.freeze({
       message: "",
       metadata: emptyMetadata(),
       refusedStreamCompression: false,
+      details: [],
     };
     const reader = new WireReader(bytes);
     while (reader.more()) {
@@ -198,6 +210,9 @@ export const RpcStatus = Object.freeze({
         case 4:
           status.refusedStreamCompression = reader.bool(wireType, "refused_stream_compression");
           break;
+        case 5:
+          status.details.push(reader.detail(wireType, "details"));
+          break;
         default:
           reader.skip(field, wireType);
       }
@@ -366,6 +381,23 @@ class WireReader {
     return info;
   }
 
+  /** A status Detail message, `{ type, value }`. */
+  detail(wireType, name) {
+    const reader = this.#nested(wireType, name);
+    const detail = { type: "", value: new Uint8Array(0) };
+    while (reader.more()) {
+      const [field, fieldWireType] = reader.tag();
+      if (field === 1) {
+        detail.type = reader.string(fieldWireType, `${name}.type`);
+      } else if (field === 2) {
+        detail.value = reader.bytes(fieldWireType, `${name}.value`);
+      } else {
+        reader.skip(field, fieldWireType);
+      }
+    }
+    return detail;
+  }
+
   /** A ConnectionMetadata message, `{ id, metadata }`. */
   connectionMetadata(wireType, name) {
     const reader = this.#nested(wireType, name);