@trevrpc/trevrpc-js 1.2.0 → 1.3.0

package/README.md

@@ -128,7 +128,7 @@ const channel = await connect(url, {
 
 `serverCertificateHashes` trusts a self-signed ECDSA certificate that is valid for at most 14 days by its SHA-256 hash, which is how development servers and the interop tests are reached. It applies to WebTransport only: the WebSocket fallback needs a certificate the browser trusts. `allowPooling`, `congestionControl` and `requireUnreliable` are passed to the `WebTransport` constructor.
 
-`connect()` always offers the WebTransport protocol `trevrpc-1` (wire version 1) through the `protocols` constructor option; it cannot be changed. If the server selects any other protocol, that connection attempt fails with `Code.FailedPrecondition` and the channel carries on as after any failed dial: the WebSocket fallback starts, or a reconnect is retried with backoff. An empty or missing selection means version 1, because older browsers cannot negotiate protocols and the Rust server cannot echo one.
+`connect()` always offers the WebTransport protocol `trevrpc-1` (wire version 1) through the `protocols` constructor option; it cannot be changed. If the server selects any other protocol, that connection attempt fails with `Code.FailedPrecondition` and the channel carries on as after any failed dial: the WebSocket fallback starts, or a reconnect is retried with backoff. An empty or missing selection means version 1, because older browsers cannot negotiate protocols.
 
 Any object with `createBidirectionalStream()`, including a plain `WebTransport` session, can be used as the transport of a generated client. Create such a session with `new WebTransport(url, { protocols: ["trevrpc-1"] })` so the server knows the wire version. Requests name the method by its full path, `/<package.Service>/<Method>` (for example `/example.greeter.Greeter/SayHello`), which the generated clients build from the service and method names.
 
@@ -187,17 +187,17 @@ trevrpc-interop-browser --browser chromium|firefox|safari \
   --url https://127.0.0.1:4433/trevrpc \
   --cert-hash <hex sha256 of the server certificate DER> \
   [--transport webtransport|websocket|auto] [--ws-url wss://127.0.0.1:4433/trevrpc] \
-  [--expect-transport webtransport|websocket]
+  [--expect-transport webtransport|websocket] [--dictionary <file>]
 ```
 
-It prints `ok <name>` or `fail <name>: <reason>` per scenario and exits 0 only if all scenarios passed. Chromium and Firefox are launched through Playwright from `PLAYWRIGHT_BROWSERS_PATH`, or from `TREVRPC_BROWSER_CHROMIUM` and `TREVRPC_BROWSER_FIREFOX` when those name an executable, and ignore certificate errors because WSS cannot pin a certificate hash. Safari is driven through `safaridriver` (`TREVRPC_BROWSER_SAFARI` overrides its path), which needs `sudo safaridriver --enable` once; Safari cannot ignore certificate errors, so the server certificate must be trusted by the system, as `interop/run.py` does. The CLI serves the page from a loopback origin; the page fetches its input from there and posts each result back, so where the browser has no WebTransport at all every scenario fails with a clear reason. `--write-page <dir>` writes that page to a directory instead, and `--page-url <url> --cert <pem> --key <pem>` opens it from a TrevRPC server that serves the directory through its HTTP fallback; the page then reports to the CLI over HTTPS, at the origin in its `report` query parameter. `--page-protocol h2|h3` has the browser load that page over HTTP/2 or HTTP/3 and fails every scenario unless it did (`h3` in Chromium only).
+It prints `ok <name>` or `fail <name>: <reason>` per scenario and exits 0 only if all scenarios passed. `--dictionary` makes the channel compress Echo messages with that zstd dictionary, the one the interop servers hold. `trevrpc-interop-browser bench` runs the load benchmark in a browser instead (see [`bench/README.md`](../bench/README.md#browsers)). Chromium and Firefox are launched through Playwright from `PLAYWRIGHT_BROWSERS_PATH`, or from `TREVRPC_BROWSER_CHROMIUM` and `TREVRPC_BROWSER_FIREFOX` when those name an executable, and ignore certificate errors because WSS cannot pin a certificate hash. Safari is driven through `safaridriver` (`TREVRPC_BROWSER_SAFARI` overrides its path), which needs `sudo safaridriver --enable` once; Safari cannot ignore certificate errors, so the server certificate must be trusted by the system, as `interop/run.py` does. The CLI serves the page from a loopback origin; the page fetches its input from there and posts each result back, so where the browser has no WebTransport at all every scenario fails with a clear reason. `--write-page <dir>` writes that page to a directory instead, and `--page-url <url> --cert <pem> --key <pem>` opens it from a TrevRPC server that serves the directory through its HTTP fallback; the page then reports to the CLI over HTTPS, at the origin in its `report` query parameter. `--page-protocol h2|h3` has the browser load that page over HTTP/2 or HTTP/3 and fails every scenario unless it did (`h3` in Chromium only).
 
 ## Development
 
 ```sh
 npm ci
 npm run check      # format check, lint, typecheck, tests
-npm run build      # generate the Echo client and bundle the interop page into build/interop/
+npm run build      # generate the interop clients and bundle the interop and benchmark pages into build/interop/
 npm run interop -- --browser chromium --url ... --cert-hash ...
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevrpc/trevrpc-js",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Browser WebTransport client and protobuf.js code generator for TrevRPC",
   "homepage": "https://trev.zip/llc/TrevRPC",
   "bugs": {

package/src/generator.js

@@ -185,6 +185,9 @@ const FieldLabel = Object.freeze({
   Repeated: 3,
 });
 
+/** The CodeGeneratorResponse features this generator supports. */
+const FEATURE_PROTO3_OPTIONAL = 1;
+
 /** Generic runtime types that generated declarations import only when they use them. */
 const GeneratedTypeImports = [
   "BidirectionalStreamingCall",
@@ -262,9 +265,9 @@ export function generate(request) {
       });
     }
 
-    return { file: files };
+    return { file: files, supportedFeatures: FEATURE_PROTO3_OPTIONAL };
   } catch (error) {
-    return { error: error.message };
+    return { error: error.message, supportedFeatures: FEATURE_PROTO3_OPTIONAL };
   }
 }
 
@@ -605,12 +608,25 @@ function generateMessageDeclaration({ fullName, message }, typeNames) {
 
 function generateFieldDeclaration(field, mapEntries, typeNames, currentFullName) {
   const optional = field.label === FieldLabel.Required ? "" : "?";
+  const nullable = decodesAbsentAsNull(field) ? " | null" : "";
   return `  ${typescriptPropertyName(fieldJsonName(field))}${optional}: ${fieldTypeScriptType(
     field,
     mapEntries,
     typeNames,
     currentFullName,
-  )};`;
+  )}${nullable};`;
+}
+
+/** Reports whether protobuf.js decodes the field as null when it is absent. */
+function decodesAbsentAsNull(field) {
+  if (field.label === FieldLabel.Repeated) {
+    return false;
+  }
+  return (
+    field.proto3Optional === true ||
+    field.type === FieldType.Message ||
+    field.type === FieldType.Group
+  );
 }
 
 function fieldTypeScriptType(field, mapEntries, typeNames, currentFullName) {
@@ -786,6 +802,11 @@ function fieldToJson(field, mapEntries) {
   if (field.defaultValue != null && field.defaultValue !== "") {
     json.options = { default: field.defaultValue };
   }
+  if (field.proto3Optional) {
+    // protobuf.js gives the field presence, decoding it as null when absent,
+    // only when this option marks its synthetic oneof.
+    json.options = { ...json.options, proto3_optional: true };
+  }
 
   return json;
 }
@@ -806,7 +827,9 @@ function oneofsToJson(message) {
   const oneofs = {};
   for (const [index, oneof] of (message.oneofDecl ?? []).entries()) {
     const fields = (message.field ?? [])
-      .filter((field) => field.oneofIndex === index)
+      // A decoded descriptor reads an unset oneof_index as 0 from its
+      // prototype, so only an own property places the field in a oneof.
+      .filter((field) => Object.hasOwn(field, "oneofIndex") && field.oneofIndex === index)
       .map(fieldJsonName);
     if (fields.length > 0) {
       oneofs[oneof.name] = { oneof: fields };