@trevrpc/trevrpc-js 1.3.1 → 1.4.0

package/src/interceptor.js

@@ -0,0 +1,102 @@
+import { normalizeMetadata } from "./metadata.js";
+import { Code, TrevRpcError, invalidArgument } from "./status.js";
+
+/**
+ * Checks a list of call interceptors from the options of a channel or client, and returns it as a
+ * frozen array; undefined or null is no interceptors. Throws InvalidArgument otherwise.
+ */
+export function interceptorList(interceptors, what) {
+  if (interceptors == null) {
+    return Object.freeze([]);
+  }
+  if (typeof interceptors[Symbol.iterator] !== "function" || typeof interceptors === "string") {
+    throw invalidArgument(`${what} must be a list of functions`);
+  }
+  const list = [...interceptors];
+  if (!list.every((interceptor) => typeof interceptor === "function")) {
+    throw invalidArgument(`${what} must be a list of functions`);
+  }
+  return Object.freeze(list);
+}
+
+/**
+ * Runs `interceptors` in order, then starts the call with `start(options)`, passing the options
+ * with the metadata the interceptors left, and returns what `start` returns. The finish functions
+ * the interceptors returned run once, innermost first, with `{ code, error }` when the call ends:
+ * when an interceptor or `start` fails, when `start` settles if `ended` is undefined, and when
+ * `ended(result)` settles otherwise, such as a streaming call's final status.
+ */
+export async function interceptCall(interceptors, info, options, start, ended) {
+  const finishes = [];
+  let result;
+  try {
+    const call = new InterceptedCall(info, options);
+    for (const interceptor of interceptors) {
+      const finish = await interceptor(call);
+      if (finish != null) {
+        if (typeof finish !== "function") {
+          throw new TypeError("a call interceptor must return a function or nothing");
+        }
+        finishes.push(finish);
+      }
+    }
+    result = await start({ ...options, metadata: normalizeMetadata(call.metadata) });
+  } catch (error) {
+    runFinishes(finishes, error);
+    throw error;
+  }
+  if (ended === undefined) {
+    runFinishes(finishes, undefined);
+  } else if (finishes.length > 0) {
+    ended(result).then(
+      () => runFinishes(finishes, undefined),
+      (error) => runFinishes(finishes, error),
+    );
+  }
+  return result;
+}
+
+/** What an interceptor sees of a call before it starts, and may change. */
+class InterceptedCall {
+  constructor({ method, service, name, kind }, { metadata, timeoutMs, signal }) {
+    this.method = method;
+    this.service = service;
+    this.name = name;
+    this.kind = kind;
+    /** The request metadata; interceptors may add, replace and delete entries. */
+    this.metadata = { ...metadata };
+    this.timeoutMs = timeoutMs;
+    this.signal = signal;
+    Object.seal(this);
+  }
+}
+
+/**
+ * Calls each finish function, innermost first, with how the call ended. A finish function that
+ * throws does not stop the others; its error is reported as uncaught.
+ */
+function runFinishes(finishes, error) {
+  if (finishes.length === 0) {
+    return;
+  }
+  const end = Object.freeze(
+    error === undefined
+      ? { code: Code.Ok, error: undefined }
+      : { code: error instanceof TrevRpcError ? error.code : Code.Unknown, error },
+  );
+  for (let index = finishes.length - 1; index >= 0; index -= 1) {
+    try {
+      finishes[index](end);
+    } catch (failure) {
+      reportUncaught(failure);
+    }
+  }
+}
+
+function reportUncaught(error) {
+  if (typeof globalThis.reportError === "function") {
+    globalThis.reportError(error);
+  } else {
+    console.error(error);
+  }
+}

package/src/stream-compression.js

@@ -17,9 +17,6 @@ const StreamCompressionStart = 3;
 /** The default memory budget of one channel's stream contexts, in bytes. */
 export const DefaultStreamCompressionMemory = 64 * 1024 * 1024;
 
-/** The key of a transport's StreamBudget; a Channel sets it from its connect options. */
-export const StreamBudgetKey = Symbol("trevrpc.streamBudget");
-
 /** The memory stream contexts may hold, shared by the calls of one channel. */
 export class StreamBudget {
   #available;
@@ -54,9 +51,12 @@ export class StreamBudget {
 
 const defaultBudgets = new WeakMap();
 
-/** The stream budget of a transport: a Channel's own, or a default one per other transport. */
+/**
+ * The stream budget of a transport: a Channel's own, which a transport that wraps one forwards, or
+ * a default one per other transport.
+ */
 export function streamBudget(transport) {
-  const budget = transport[StreamBudgetKey];
+  const budget = transport.streamCompressionBudget;
   if (budget !== undefined) {
     return budget;
   }

package/src/wire.js

@@ -1,6 +1,7 @@
 import protobuf from "protobufjs";
 
 import { byteView } from "./bytes.js";
+import { setInt64Representation } from "./int64.js";
 
 export { protobuf };
 
@@ -102,9 +103,16 @@ export function preflightWireMessage(messageType, body) {
   scanMessage(messageType, byteView(body), 0);
 }
 
-/** Creates a protobuf root from a JSON namespace definition. */
-export function createRoot(json) {
-  return protobuf.Root.fromJSON(json);
+/**
+ * Creates a protobuf root from a JSON namespace definition. `options.int64` sets how calls decode
+ * its messages' 64-bit integers (see `setInt64Representation`); without it they stay Long objects.
+ */
+export function createRoot(json, options = {}) {
+  const root = protobuf.Root.fromJSON(json);
+  if (options.int64 !== undefined) {
+    setInt64Representation(root, options.int64);
+  }
+  return root;
 }
 
 function scanMessage(messageType, bytes, depth) {
@@ -183,15 +191,25 @@ function scanMapEntry(field, bytes, depth) {
     if (fieldNumber === 1) {
       scanSyntheticField(field.keyType, `${field.name}.key`, bytes, cursor, wireType, depth);
     } else if (fieldNumber === 2) {
-      scanSyntheticField(field.type, `${field.name}.value`, bytes, cursor, wireType, depth);
+      const messageType = field.resolvedType?.fieldsById != null ? field.resolvedType : undefined;
+      scanSyntheticField(
+        field.type,
+        `${field.name}.value`,
+        bytes,
+        cursor,
+        wireType,
+        depth,
+        messageType,
+      );
     } else {
       skipUnknownField(bytes, cursor, fieldNumber, wireType, depth);
     }
   }
 }
 
-function scanSyntheticField(type, name, bytes, cursor, wireType, depth) {
-  const expected = scalarWireType(type);
+/** Scans a map key or value: a scalar of `type`, or a message of `messageType` when it is set. */
+function scanSyntheticField(type, name, bytes, cursor, wireType, depth, messageType) {
+  const expected = messageType === undefined ? scalarWireType(type) : 2;
   if (wireType !== expected) {
     throw malformedWire(`field ${name} used incompatible protobuf wire type ${wireType}`);
   }
@@ -206,7 +224,9 @@ function scanSyntheticField(type, name, bytes, cursor, wireType, depth) {
     skipFixed(bytes, cursor, 4, name);
   } else if (wireType === 2) {
     const value = readLengthDelimited(bytes, cursor, `truncated protobuf field ${name}`);
-    if (type === "string") {
+    if (messageType !== undefined) {
+      scanMessage(messageType, value, depth + 1);
+    } else if (type === "string") {
       validateUtf8(value, name);
     }
   } else {
@@ -234,6 +254,10 @@ function scanPackedField(field, bytes) {
 }
 
 function acceptedWireTypes(field) {
+  // A map entry is a length-delimited message, whatever its value type.
+  if (field.map) {
+    return [2];
+  }
   const expected = field.resolvedType?.fieldsById != null ? 2 : scalarWireType(field.type);
   return field.repeated && isPackableField(field) ? [expected, 2] : [expected];
 }

package/src/wkt.js

@@ -0,0 +1,137 @@
+// Helpers for the well-known types google.protobuf.Timestamp, Duration, Struct, Value and
+// ListValue, whose declarations generated code imports from the runtime.
+import { int64ToBigInt } from "./int64.js";
+import { invalidArgument } from "./status.js";
+
+/** google.protobuf.NullValue. */
+export const NullValue = Object.freeze({ NULL_VALUE: 0 });
+
+const MsPerSecond = 1000n;
+const NanosPerMs = 1_000_000;
+
+/** Returns the Timestamp of a Date. */
+export function timestampFromDate(date) {
+  return timestampFromMs(date.getTime());
+}
+
+/** Returns the Timestamp of milliseconds since the Unix epoch. */
+export function timestampFromMs(ms) {
+  checkFinite(ms, "timestamp");
+  const whole = Math.floor(ms);
+  const seconds = Math.floor(whole / 1000);
+  return { seconds: BigInt(seconds), nanos: (whole - seconds * 1000) * NanosPerMs };
+}
+
+/** Returns the Date of a Timestamp. */
+export function timestampDate(timestamp) {
+  return new Date(timestampMs(timestamp));
+}
+
+/** Returns the milliseconds since the Unix epoch of a Timestamp, rounded down. */
+export function timestampMs(timestamp) {
+  return toMs(timestamp, Math.floor);
+}
+
+/** Returns the Duration of a number of milliseconds. */
+export function durationFromMs(ms) {
+  checkFinite(ms, "duration");
+  const whole = Math.trunc(ms);
+  const seconds = Math.trunc(whole / 1000);
+  // Seconds and nanos share the duration's sign; `+ 0` turns -0 into 0.
+  return { seconds: BigInt(seconds), nanos: (whole - seconds * 1000) * NanosPerMs + 0 };
+}
+
+/** Returns the milliseconds of a Duration, rounded towards zero. */
+export function durationMs(duration) {
+  return toMs(duration, Math.trunc);
+}
+
+/** Returns the Struct of a JSON object. */
+export function structFromJson(json) {
+  if (json === null || typeof json !== "object" || Array.isArray(json)) {
+    throw invalidArgument("a Struct is made from a JSON object");
+  }
+  const fields = {};
+  for (const [key, value] of Object.entries(json)) {
+    fields[key] = valueFromJson(value);
+  }
+  return { fields };
+}
+
+/** Returns the JSON object of a Struct. */
+export function structToJson(struct) {
+  const json = {};
+  for (const [key, value] of Object.entries(struct?.fields ?? {})) {
+    json[key] = valueToJson(value);
+  }
+  return json;
+}
+
+/** Returns the Value of a JSON value. */
+export function valueFromJson(json) {
+  if (json === null) {
+    return { nullValue: NullValue.NULL_VALUE };
+  }
+  switch (typeof json) {
+    case "number":
+      return { numberValue: json };
+    case "string":
+      return { stringValue: json };
+    case "boolean":
+      return { boolValue: json };
+    case "object":
+      return Array.isArray(json)
+        ? { listValue: { values: json.map(valueFromJson) } }
+        : { structValue: structFromJson(json) };
+    default:
+      throw invalidArgument(`a Value cannot hold a ${typeof json}`);
+  }
+}
+
+/** Returns the JSON value of a Value; a Value with no kind set is null. */
+export function valueToJson(value) {
+  switch (valueKind(value)) {
+    case "numberValue":
+      return value.numberValue;
+    case "stringValue":
+      return value.stringValue;
+    case "boolValue":
+      return value.boolValue;
+    case "structValue":
+      return structToJson(value.structValue);
+    case "listValue":
+      return (value.listValue.values ?? []).map(valueToJson);
+    default:
+      return null;
+  }
+}
+
+const ValueKinds = [
+  "nullValue",
+  "numberValue",
+  "stringValue",
+  "boolValue",
+  "structValue",
+  "listValue",
+];
+
+/**
+ * The member of a Value's `kind` oneof that is set. A decoded Value reads the defaults of the
+ * other members from its prototype, so only own properties count.
+ */
+function valueKind(value) {
+  return ValueKinds.find(
+    (kind) => value != null && Object.hasOwn(value, kind) && value[kind] != null,
+  );
+}
+
+/** The milliseconds of a Timestamp or Duration, with sub-millisecond nanos rounded by `round`. */
+function toMs({ seconds, nanos } = {}, round) {
+  return Number(int64ToBigInt(seconds) * MsPerSecond) + round((nanos ?? 0) / NanosPerMs);
+}
+
+function checkFinite(ms, what) {
+  if (!Number.isFinite(ms)) {
+    throw invalidArgument(`a ${what} needs a finite number of milliseconds, not ${ms}`);
+  }
+}