@trevrpc/trevrpc-js 1.0.0 → 1.1.0

package/src/race.js

@@ -0,0 +1,90 @@
+import { cancelled, statusFromTransportError, unavailable } from "./status.js";
+
+/**
+ * Dials `primary`, adds `fallback` once the primary fails or `delayMs` passes, and resolves with
+ * `{ session, transport }` from the first to connect. The loser is abandoned and closed if it
+ * connects anyway. Each candidate is `{ transport, dial(signal) }`.
+ */
+export function dialRace(primary, fallback, { delayMs, signal } = {}) {
+  return new Promise((resolve, reject) => {
+    const attempts = new Map();
+    const errors = [];
+    let settled = false;
+    let fallbackStarted = false;
+    let timer;
+
+    const settle = (winner) => {
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      for (const [candidate, controller] of attempts) {
+        if (candidate !== winner) {
+          controller.abort();
+        }
+      }
+    };
+    const start = (candidate) => {
+      const controller = new AbortController();
+      attempts.set(candidate, controller);
+      let dialing;
+      try {
+        // Dialing starts synchronously, so a session exists as soon as the race begins.
+        dialing = Promise.resolve(candidate.dial(controller.signal));
+      } catch (error) {
+        dialing = Promise.reject(error);
+      }
+      dialing.then(
+        (session) => {
+          if (settled) {
+            closeQuietly(session);
+            return;
+          }
+          settle(candidate);
+          resolve({ session, transport: candidate.transport });
+        },
+        (error) => {
+          attempts.delete(candidate);
+          if (settled) {
+            return;
+          }
+          errors.push(`${candidate.transport}: ${statusFromTransportError(error).message}`);
+          if (candidate === primary) {
+            startFallback();
+          } else if (attempts.size === 0) {
+            settle(null);
+            reject(unavailable(`transport unavailable: ${errors.join("; ")}`));
+          }
+        },
+      );
+    };
+    const startFallback = () => {
+      if (!fallbackStarted && !settled) {
+        fallbackStarted = true;
+        clearTimeout(timer);
+        start(fallback);
+      }
+    };
+    const onAbort = () => {
+      if (!settled) {
+        settle(null);
+        reject(cancelled("connection cancelled", signal.reason));
+      }
+    };
+
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+    start(primary);
+    timer = setTimeout(startFallback, delayMs);
+  });
+}
+
+function closeQuietly(session) {
+  try {
+    session.close();
+  } catch {
+    // The session may already be gone.
+  }
+}

package/src/status.js

@@ -48,7 +48,7 @@ export function codeName(code) {
 }
 
 /** Creates a TrevRPC status error. */
-export function statusError(code, message = "", metadata = {}, cause = undefined) {
+export function statusError(code, message = "", metadata = {}, cause) {
   return new TrevRpcError(code, message, metadata, { cause });
 }
 

package/src/varint.js

@@ -0,0 +1,73 @@
+// QUIC variable-length integers (RFC 9000 §16), shared by the frame layer and QMux. Values below
+// 2^53 are numbers; larger codepoints are bigints.
+
+const MaxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+
+/** Encoded length of a varint. */
+export function varintLength(value) {
+  if (typeof value === "number" && value >= 0 && value < 0x4000_0000) {
+    return value < 0x40 ? 1 : value < 0x4000 ? 2 : 4;
+  }
+  const v = typeof value === "bigint" ? value : BigInt(value);
+  if (v < 0x40n) {
+    return 1;
+  }
+  if (v < 0x4000n) {
+    return 2;
+  }
+  if (v < 0x4000_0000n) {
+    return 4;
+  }
+  if (v < 0x4000_0000_0000_0000n) {
+    return 8;
+  }
+  throw new RangeError(`varint ${v} exceeds 2^62 - 1`);
+}
+
+/** Writes a varint at offset and returns the offset after it. */
+export function writeVarint(bytes, offset, value) {
+  const length = varintLength(value);
+  if (typeof value === "number" && length < 8 && Number.isInteger(value)) {
+    // Fast path without BigInt for the common small values.
+    let v = value;
+    for (let i = length - 1; i >= 0; i -= 1) {
+      bytes[offset + i] = v % 256;
+      v = Math.floor(v / 256);
+    }
+    bytes[offset] |= [0, 0x40, 0, 0x80][length - 1];
+    return offset + length;
+  }
+  let v = typeof value === "bigint" ? value : BigInt(value);
+  for (let i = length - 1; i >= 0; i -= 1) {
+    bytes[offset + i] = Number(v & 0xffn);
+    v >>= 8n;
+  }
+  bytes[offset] |= [0, 0x40, 0, 0x80, 0, 0, 0, 0xc0][length - 1];
+  return offset + length;
+}
+
+/**
+ * Reads a varint at offset. Returns `{ value, next }`, or null when the bytes end first. Values
+ * above 2^53 - 1 are bigints.
+ */
+export function readVarint(bytes, offset) {
+  if (offset >= bytes.length) {
+    return null;
+  }
+  const length = 1 << (bytes[offset] >> 6);
+  if (offset + length > bytes.length) {
+    return null;
+  }
+  if (length < 8) {
+    let value = bytes[offset] & 0x3f;
+    for (let i = 1; i < length; i += 1) {
+      value = value * 256 + bytes[offset + i];
+    }
+    return { value, next: offset + length };
+  }
+  let value = BigInt(bytes[offset] & 0x3f);
+  for (let i = 1; i < 8; i += 1) {
+    value = (value << 8n) | BigInt(bytes[offset + i]);
+  }
+  return { value: value <= MaxSafe ? Number(value) : value, next: offset + 8 };
+}

package/src/wire.js

@@ -4,8 +4,6 @@ import { byteView } from "./bytes.js";
 
 export { protobuf };
 
-export const WireVersion = 1;
-
 export const RpcKind = Object.freeze({
   Unary: 0,
   ClientStreaming: 1,
@@ -13,11 +11,6 @@ export const RpcKind = Object.freeze({
   BidirectionalStreaming: 3,
 });
 
-export const RpcStreamFrameKind = Object.freeze({
-  Message: 0,
-  Status: 1,
-});
-
 const wireRoot = protobuf.Root.fromJSON({
   nested: {
     trevrpc: {
@@ -30,38 +23,32 @@ const wireRoot = protobuf.Root.fromJSON({
             BidirectionalStreaming: 3,
           },
         },
-        RpcStreamFrameKind: {
-          values: {
-            Message: 0,
-            Status: 1,
-          },
-        },
         RpcRequest: {
           fields: {
-            service: { type: "string", id: 1 },
-            method: { type: "string", id: 2 },
-            body: { type: "bytes", id: 3 },
+            method: { type: "string", id: 1 },
             metadata: { keyType: "string", type: "bytes", id: 4 },
             kind: { type: "RpcKind", id: 5 },
-            version: { type: "uint32", id: 6 },
             timeoutNanos: { type: "uint64", id: 7 },
+            extensions: { rule: "repeated", type: "uint64", id: 8 },
+            datagramFlow: { type: "uint64", id: 9 },
           },
+          // Fields 2 (method name), 3 (request body) and 6 (wire version) must never be reused.
+          reserved: [
+            [2, 3],
+            [6, 6],
+          ],
         },
-        RpcResponse: {
+        RpcHeaders: {
           fields: {
-            status: { type: "uint32", id: 1 },
-            message: { type: "string", id: 2 },
-            body: { type: "bytes", id: 3 },
-            metadata: { keyType: "string", type: "bytes", id: 4 },
+            metadata: { keyType: "string", type: "bytes", id: 1 },
+            extensions: { rule: "repeated", type: "uint64", id: 2 },
           },
         },
-        RpcStreamFrame: {
+        RpcStatus: {
           fields: {
-            kind: { type: "RpcStreamFrameKind", id: 1 },
-            status: { type: "uint32", id: 2 },
-            message: { type: "string", id: 3 },
-            body: { type: "bytes", id: 4 },
-            metadata: { keyType: "string", type: "bytes", id: 5 },
+            code: { type: "uint32", id: 1 },
+            message: { type: "string", id: 2 },
+            metadata: { keyType: "string", type: "bytes", id: 3 },
           },
         },
       },
@@ -70,8 +57,8 @@ const wireRoot = protobuf.Root.fromJSON({
 });
 
 export const RpcRequest = wireRoot.lookupType("trevrpc.RpcRequest");
-export const RpcResponse = wireRoot.lookupType("trevrpc.RpcResponse");
-export const RpcStreamFrame = wireRoot.lookupType("trevrpc.RpcStreamFrame");
+export const RpcHeaders = wireRoot.lookupType("trevrpc.RpcHeaders");
+export const RpcStatus = wireRoot.lookupType("trevrpc.RpcStatus");
 
 const MaxFieldNumber = 0x1fffffff;
 const MaxUint32 = 0xffffffffn;