grpc-dc 0.0.0-stage → 0.31.0

package/src/endpoint.js

@@ -0,0 +1,269 @@
+// @generated by grpc-dc codegen. DO NOT EDIT.
+// SPDX-License-Identifier: Apache-2.0
+// Stream multiplexor: one data channel, many concurrent calls.
+// Incoming HEADERS are handed to `dispatcher` (installed by Server);
+// everything else is routed to the owning stream's event queue.
+
+import {
+  FrameType,
+  StatusCode,
+  StatusError,
+  asUint8Array,
+  decodeFrame,
+  encodeFrame,
+  headersFrame,
+  parseHeaders,
+  parseStatus,
+  statusFrame,
+} from "./codec.js";
+
+/** Async queue of stream events with terminal-error semantics. */
+export class StreamInput {
+  #items = [];
+  #waiters = [];
+  #error = null;
+  #ended = false;
+
+  push(item) {
+    if (this.#ended) return;
+    const waiter = this.#waiters.shift();
+    if (waiter) waiter({ value: item, done: false });
+    else this.#items.push(item);
+  }
+
+  end() {
+    if (this.#ended) return;
+    this.#ended = true;
+    for (const w of this.#waiters.splice(0)) w({ value: undefined, done: true });
+  }
+
+  fail(error) {
+    if (this.#ended) return;
+    this.#ended = true;
+    this.#error = error;
+    for (const w of this.#waiters.splice(0)) w({ error, done: true });
+  }
+
+  [Symbol.asyncIterator]() {
+    return {
+      next: () => {
+        if (this.#items.length) {
+          return Promise.resolve({ value: this.#items.shift(), done: false });
+        }
+        if (this.#error) return Promise.reject(this.#error);
+        if (this.#ended) return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve) => {
+          this.#waiters.push((r) => {
+            if (r.error) resolve(Promise.reject(r.error));
+            else resolve(r);
+          });
+        }).then((r) => r);
+      },
+    };
+  }
+}
+
+const DRAIN_THRESHOLD = 1 << 20; // 1 MiB of bufferedAmount before pausing
+
+export class Endpoint {
+  #dc;
+  #streams = new Map();
+  #nextId;
+  #sendChain = Promise.resolve();
+  dispatcher = null; // async (path, headers, input, sink) => void, set by Server
+
+  /**
+   * @param dc an RTCDataChannel (browser, werift, node-datachannel) or any
+   *   object with send() + message events. Memory pair in loopback.js works.
+   * @param parity 'odd' if this peer created the channel, else 'even'.
+   */
+  constructor(dc, { parity = "odd" } = {}) {
+    this.#dc = dc;
+    this.#nextId = parity === "odd" ? 1 : 2;
+    try {
+      dc.binaryType = "arraybuffer";
+    } catch {
+      /* structural channels may not expose binaryType */
+    }
+    const onMessage = (event) => {
+      const data = event?.data ?? event;
+      if (data instanceof Blob) {
+        data.arrayBuffer().then((b) => this.#onBytes(new Uint8Array(b)));
+      } else {
+        try {
+          this.#onBytes(asUint8Array(data));
+        } catch {
+          /* ignore non-binary messages */
+        }
+      }
+    };
+    if (typeof dc.addEventListener === "function") {
+      dc.addEventListener("message", onMessage);
+    } else {
+      dc.onmessage = onMessage;
+    }
+  }
+
+  get dataChannel() {
+    return this.#dc;
+  }
+
+  /** Allocate a locally-initiated stream. Returns [id, input]. */
+  openStream() {
+    const id = this.#nextId;
+    this.#nextId += 2;
+    const input = new StreamInput();
+    this.#streams.set(id, input);
+    return [id, input];
+  }
+
+  closeStream(id) {
+    const input = this.#streams.get(id);
+    if (input) {
+      input.end();
+      this.#streams.delete(id);
+    }
+  }
+
+  async sendFrame(frameBytes) {
+    // Serialize sends so HEADERS never overtakes a previous frame on the
+    // wire, and pause while the SCTP send buffer is above the threshold.
+    const run = async () => {
+      await this.#waitForDrain();
+      if (this.#dc.readyState && this.#dc.readyState !== "open") {
+        throw StatusError.unavailable("data channel is not open");
+      }
+      this.#dc.send(frameBytes);
+    };
+    this.#sendChain = this.#sendChain.then(run, run);
+    return this.#sendChain;
+  }
+
+  async #waitForDrain() {
+    const dc = this.#dc;
+    if (typeof dc.bufferedAmount !== "number" || dc.bufferedAmount <= DRAIN_THRESHOLD) return;
+    await new Promise((resolve) => {
+      if (typeof dc.addEventListener === "function") {
+        try {
+          dc.bufferedAmountLowThreshold = DRAIN_THRESHOLD / 2;
+        } catch {
+          /* optional */
+        }
+        const done = () => {
+          dc.removeEventListener?.("bufferedamountlow", done);
+          resolve();
+        };
+        dc.addEventListener("bufferedamountlow", done);
+        setTimeout(done, 50); // fallback poll for structural channels
+      } else {
+        setTimeout(resolve, 10);
+      }
+    });
+    if (typeof dc.bufferedAmount === "number" && dc.bufferedAmount > DRAIN_THRESHOLD) {
+      return this.#waitForDrain();
+    }
+  }
+
+  #onBytes(bytes) {
+    let frame;
+    try {
+      frame = decodeFrame(bytes);
+    } catch {
+      return; // malformed frame: drop, keep the channel up
+    }
+    const { type, streamId, payload } = frame;
+    switch (type) {
+      case FrameType.HEADERS:
+        this.#onHeaders(streamId, payload);
+        break;
+      case FrameType.DATA:
+        this.#push(streamId, { kind: "data", payload });
+        break;
+      case FrameType.TRAILERS:
+        this.#terminal(streamId, payload, "trailers");
+        break;
+      case FrameType.HALF_CLOSE:
+        this.#push(streamId, { kind: "half-close" });
+        break;
+      case FrameType.RST:
+        this.#terminal(streamId, payload, "rst");
+        break;
+      default:
+        break; // unknown frame type: ignore for forward compatibility
+    }
+  }
+
+  #push(streamId, event) {
+    this.#streams.get(streamId)?.push(event);
+  }
+
+  #terminal(streamId, payload, kind) {
+    const status = parseStatus(payload);
+    this.#streams.get(streamId)?.push({ kind, status });
+    this.#streams.delete(streamId);
+  }
+
+  async #onHeaders(streamId, payload) {
+    let headers;
+    try {
+      headers = parseHeaders(payload);
+    } catch (e) {
+      this.sendFrame(statusFrame(FrameType.RST, streamId, e)).catch(() => {});
+      return;
+    }
+    if (headers.path === null) {
+      // Server initial metadata for one of our outbound streams.
+      this.#streams.get(streamId)?.push({ kind: "headers", headers });
+      return;
+    }
+    if (this.#streams.has(streamId)) {
+      this.sendFrame(
+        statusFrame(
+          FrameType.RST,
+          streamId,
+          StatusError.internal("HEADERS for stream already in use"),
+        ),
+      ).catch(() => {});
+      return;
+    }
+    if (!this.dispatcher) {
+      this.sendFrame(
+        statusFrame(
+          FrameType.TRAILERS,
+          streamId,
+          StatusError.unimplemented(`unknown method ${headers.path}`),
+        ),
+      ).catch(() => {});
+      return;
+    }
+    const input = new StreamInput();
+    this.#streams.set(streamId, input);
+    const sink = {
+      sendData: (payload) => this.sendFrame(encodeFrame(FrameType.DATA, streamId, payload)),
+      sendHeaders: () => this.sendFrame(headersFrame(streamId, null)),
+      sendTrailers: (status) =>
+        this.sendFrame(statusFrame(FrameType.TRAILERS, streamId, status)),
+    };
+    try {
+      await sink.sendHeaders();
+      await this.dispatcher(headers.path, headers, input, sink);
+      await sink.sendTrailers(StatusError.ok());
+    } catch (e) {
+      const status =
+        e instanceof StatusError ? e : StatusError.internal(e?.message ?? String(e));
+      await sink.sendTrailers(status).catch(() => {});
+    } finally {
+      this.#streams.delete(streamId);
+    }
+  }
+
+  /** Fail every live stream (channel teardown). */
+  closeAll() {
+    for (const input of this.#streams.values()) {
+      input.fail(StatusError.unavailable("data channel closed"));
+    }
+    this.#streams.clear();
+  }
+}
+
+export { StatusCode };

package/src/loopback.js

@@ -0,0 +1,60 @@
+// @generated by grpc-dc codegen. DO NOT EDIT.
+// SPDX-License-Identifier: Apache-2.0
+// In-memory RTCDataChannel pair for Node tests and demos: message
+// boundaries preserved, ordered, reliable — the same contract a real
+// RTCDataChannel offers. Delivery is a microtask, like a fast network.
+
+class MemoryDataChannel {
+  #listeners = new Map();
+
+  constructor(label) {
+    this.label = label;
+    this.readyState = "open";
+    this.bufferedAmount = 0;
+    this.binaryType = "arraybuffer";
+    this.peer = null;
+  }
+
+  addEventListener(type, fn) {
+    if (!this.#listeners.has(type)) this.#listeners.set(type, []);
+    this.#listeners.get(type).push(fn);
+  }
+
+  removeEventListener(type, fn) {
+    const list = this.#listeners.get(type) ?? [];
+    this.#listeners.set(type, list.filter((f) => f !== fn));
+  }
+
+  #emit(type, event) {
+    for (const fn of [...(this.#listeners.get(type) ?? [])]) fn(event);
+    const handler = this[`on${type}`];
+    if (typeof handler === "function") handler(event);
+  }
+
+  send(data) {
+    if (this.readyState !== "open") throw new Error("data channel is not open");
+    const copy = data instanceof Uint8Array ? data.slice() : data;
+    const peer = this.peer;
+    queueMicrotask(() => {
+      if (peer.readyState === "open") peer.#emit("message", { data: copy });
+    });
+  }
+
+  close() {
+    if (this.readyState === "closed") return;
+    this.readyState = "closed";
+    this.#emit("close", {});
+    if (this.peer.readyState !== "closed") {
+      this.peer.readyState = "closed";
+      this.peer.#emit("close", {});
+    }
+  }
+}
+
+export function memoryDataChannelPair() {
+  const a = new MemoryDataChannel("a");
+  const b = new MemoryDataChannel("b");
+  a.peer = b;
+  b.peer = a;
+  return [a, b];
+}

package/src/server.js

@@ -0,0 +1,126 @@
+// @generated by grpc-dc codegen. DO NOT EDIT.
+// SPDX-License-Identifier: Apache-2.0
+// Server side: registers generated service definitions (createXService)
+// on an endpoint and dispatches HEADERS by path.
+
+import {
+  StatusError,
+  StatusName,
+  parseTimeout,
+  parseTraceparent,
+  traceEnd,
+  traceStart,
+} from "./codec.js";
+import { Endpoint } from "./endpoint.js";
+
+async function* typedRequests(input, ReqType) {
+  for await (const event of input) {
+    if (event.kind === "data") {
+      yield ReqType.decode(event.payload);
+    } else if (event.kind === "half-close") {
+      return;
+    } else if (event.kind === "trailers" || event.kind === "rst") {
+      throw event.status;
+    }
+  }
+}
+
+async function firstRequest(requests) {
+  const iterator = requests[Symbol.asyncIterator]();
+  const first = await iterator.next();
+  if (first.done) {
+    throw StatusError.invalidArgument("missing request message");
+  }
+  return first.value;
+}
+
+export class Server {
+  #methods = new Map();
+
+  addService(definition) {
+    for (const [name, method] of Object.entries(definition.methods)) {
+      if (typeof method.handler !== "function") {
+        throw new Error(`grpc-dc: missing handler for ${definition.name}.${name}`);
+      }
+      this.#methods.set(method.path, { ...method, service: definition.name, method: name });
+    }
+    return this;
+  }
+
+  /** Attach to an endpoint (or raw channel, wrapped with even parity). */
+  serve(dcOrEndpoint, options) {
+    const endpoint =
+      dcOrEndpoint instanceof Endpoint
+        ? dcOrEndpoint
+        : new Endpoint(dcOrEndpoint, { parity: "even", ...options });
+    endpoint.dispatcher = (path, headers, input, sink) =>
+      this.#dispatch(path, headers, input, sink);
+    return endpoint;
+  }
+
+  async #dispatch(path, headers, input, sink) {
+    const method = this.#methods.get(path);
+    if (!method) {
+      throw StatusError.unimplemented(`unknown method ${path}`);
+    }
+    const metadata = headers.metadata ?? {};
+    const timeoutMs = parseTimeout(metadata["grpc-timeout"]);
+    const deadline = timeoutMs === null ? null : Date.now() + timeoutMs;
+    const ctx = {
+      path,
+      metadata,
+      service: method.service,
+      method: method.method,
+      deadline,
+      timeRemaining: () => (deadline === null ? null : deadline - Date.now()),
+    };
+    const traceCtx = traceStart("server", path, parseTraceparent(metadata.traceparent));
+    let traceStatus = "OK";
+    try {
+      await this.#dispatchTraced(path, method, ctx, input, sink);
+    } catch (e) {
+      traceStatus =
+        e instanceof StatusError
+          ? (StatusName[e.code] ?? `CODE_${e.code}`)
+          : "INTERNAL";
+      throw e;
+    } finally {
+      traceEnd("server", path, traceCtx, traceStatus);
+    }
+  }
+
+  async #dispatchTraced(path, method, ctx, input, sink) {
+    const requests = typedRequests(input, method.requestType);
+    const encode = (resp) => method.responseType.encode(resp);
+    switch (method.kind) {
+      case "unary": {
+        const req = await firstRequest(requests);
+        const resp = await method.handler(req, ctx);
+        await sink.sendData(encode(resp));
+        return;
+      }
+      case "server-streaming": {
+        const req = await firstRequest(requests);
+        const out = await method.handler(req, ctx);
+        for await (const resp of out) {
+          await sink.sendData(encode(resp));
+        }
+        return;
+      }
+      case "client-streaming": {
+        const resp = await method.handler(requests, ctx);
+        await sink.sendData(encode(resp));
+        return;
+      }
+      case "bidi": {
+        const out = await method.handler(requests, ctx);
+        for await (const resp of out) {
+          await sink.sendData(encode(resp));
+        }
+        return;
+      }
+      default:
+        throw StatusError.unimplemented(`unknown method kind ${method.kind}`);
+    }
+  }
+}

package/src/wasm_bridge.js

@@ -0,0 +1,241 @@
+// @generated by grpc-dc codegen. DO NOT EDIT.
+// SPDX-License-Identifier: Apache-2.0
+// WASM bridge: the generic byte-level surface that generated WASM
+// client facades (Go/Rust/...) call into. The JS runtime owns the
+// wire; the facade owns the types. Payloads cross the boundary as
+// Uint8Array protobuf bytes, so no object mapping is needed.
+//
+//   unary(path, payload, options?) -> Promise<Uint8Array>
+//   serverStream(path, payload, onMessage, options?) -> Promise<void>
+//   clientStream(path, payloads, options?) -> Promise<Uint8Array>
+//   bidi(path, payloads, onMessage, options?) -> Promise<void>
+//
+// options may carry {metadata, timeout} (forwarded to the call)
+// and, for streaming calls, {cancelAfter: n} to abort the stream
+// after n responses. onMessage receives one Uint8Array per
+// response; the promise resolves on OK trailers and rejects
+// with StatusError otherwise.
+
+import { Channel } from "./channel.js";
+import { Server } from "./server.js";
+import { StatusError } from "./codec.js";
+
+const identity = { encode: (bytes) => bytes, decode: (bytes) => bytes };
+
+async function* fromList(items) {
+  yield* items;
+}
+
+export function createGrpcDcBridge(dcOrChannel) {
+  const channel = dcOrChannel instanceof Channel ? dcOrChannel : new Channel(dcOrChannel);
+  const callOptions = (options) => ({
+    metadata: options?.metadata ?? {},
+    timeout: options?.timeout,
+  });
+  return {
+    async unary(path, payload, options) {
+      return channel.unary(path, payload, identity, identity, callOptions(options));
+    },
+    async serverStream(path, payload, onMessage, options) {
+      const responses = await channel.serverStream(path, payload, identity, identity, callOptions(options));
+      let seen = 0;
+      for await (const resp of responses) {
+        onMessage(resp);
+        seen++;
+        // cancelAfter: the caller aborts the stream after this
+        // many responses (breaking the iteration tears the call
+        // down); the promise then resolves normally.
+        if (options?.cancelAfter && seen >= options.cancelAfter) break;
+      }
+    },
+    async clientStream(path, payloads, options) {
+      return channel.clientStream(path, fromList(payloads), identity, identity, callOptions(options));
+    },
+    async bidi(path, payloads, onMessage, options) {
+      const responses = await channel.bidi(path, fromList(payloads), identity, identity, callOptions(options));
+      let seen = 0;
+      for await (const resp of responses) {
+        onMessage(resp);
+        seen++;
+        if (options?.cancelAfter && seen >= options.cancelAfter) break;
+      }
+    },
+  };
+}
+
+// Server bridge: the mirror image for generated WASM server
+// facades. The JS runtime still owns the wire (a real Server
+// on the channel); the facade registers typed handlers per
+// path. Handlers receive protobuf bytes plus metadata as a
+// flattened [key, value, ...] string array and respond in
+// bytes; streaming handlers push responses through onMessage
+// and settle their promise at the end. Handler failures cross
+// as {code, message} objects and become StatusError here.
+// Facade client-streaming/bidi calls deliver all requests up
+// front, so clientStream/bidi handlers receive the full list
+// (same shape as the client bridge's payloads).
+function toStatusError(err) {
+  if (err instanceof StatusError) return err;
+  const code = err && typeof err.code === "number" ? err.code : 13;
+  const message = err && err.message ? String(err.message) : String(err);
+  return new StatusError(code, message);
+}
+
+function metadataPairs(metadata) {
+  return Object.entries(metadata ?? {}).flat();
+}
+
+async function* collectResponses(invoke) {
+  const queue = [];
+  let notify = null;
+  let settled = false;
+  let failure = null;
+  const wake = () => {
+    if (notify) {
+      const resolve = notify;
+      notify = null;
+      resolve();
+    }
+  };
+  invoke((bytes) => {
+    queue.push(bytes);
+    wake();
+  }).then(
+    () => {
+      settled = true;
+      wake();
+    },
+    (err) => {
+      failure = err;
+      settled = true;
+      wake();
+    }
+  );
+  for (;;) {
+    while (queue.length > 0) yield queue.shift();
+    if (settled) break;
+    await new Promise((resolve) => {
+      notify = resolve;
+    });
+  }
+  if (failure) throw toStatusError(failure);
+}
+
+/** Pull-based view of a request stream for incremental handlers. */
+function requestSource(requests) {
+  const iterator = requests[Symbol.asyncIterator]();
+  return {
+    next: async () => {
+      const result = await iterator.next();
+      return result.done ? null : result.value;
+    },
+  };
+}
+
+export function createGrpcDcServerBridge(dcOrChannel) {
+  const channel = dcOrChannel instanceof Channel ? dcOrChannel : new Channel(dcOrChannel);
+  const server = new Server();
+  const methods = {};
+  let started = false;
+  const register = (path, method) => {
+    methods[path] = method;
+  };
+  return {
+    registerUnary(path, handler) {
+      register(path, {
+        path,
+        kind: "unary",
+        requestType: identity,
+        responseType: identity,
+        handler: async (req, ctx) => {
+          try {
+            return await handler(req, metadataPairs(ctx.metadata));
+          } catch (err) {
+            throw toStatusError(err);
+          }
+        },
+      });
+    },
+    registerServerStream(path, handler) {
+      register(path, {
+        path,
+        kind: "server-streaming",
+        requestType: identity,
+        responseType: identity,
+        handler: (req, ctx) =>
+          collectResponses((onMessage) => handler(req, metadataPairs(ctx.metadata), onMessage)),
+      });
+    },
+    registerClientStream(path, handler) {
+      register(path, {
+        path,
+        kind: "client-streaming",
+        requestType: identity,
+        responseType: identity,
+        handler: async (requests, ctx) => {
+          const payloads = [];
+          for await (const req of requests) payloads.push(req);
+          try {
+            return await handler(payloads, metadataPairs(ctx.metadata));
+          } catch (err) {
+            throw toStatusError(err);
+          }
+        },
+      });
+    },
+    registerBidi(path, handler) {
+      register(path, {
+        path,
+        kind: "bidi",
+        requestType: identity,
+        responseType: identity,
+        handler: async (requests, ctx) => {
+          const payloads = [];
+          for await (const req of requests) payloads.push(req);
+          return collectResponses((onMessage) =>
+            handler(payloads, metadataPairs(ctx.metadata), onMessage)
+          );
+        },
+      });
+    },
+    // Incremental variants: the handler pulls requests one at a
+    // time from source.next() (null at end of stream) instead of
+    // receiving every payload up front, so a bidi handler can
+    // answer each request before the next one is sent.
+    registerClientStreamInc(path, handler) {
+      register(path, {
+        path,
+        kind: "client-streaming",
+        requestType: identity,
+        responseType: identity,
+        handler: async (requests, ctx) => {
+          try {
+            return await handler(requestSource(requests), metadataPairs(ctx.metadata));
+          } catch (err) {
+            throw toStatusError(err);
+          }
+        },
+      });
+    },
+    registerBidiInc(path, handler) {
+      register(path, {
+        path,
+        kind: "bidi",
+        requestType: identity,
+        responseType: identity,
+        handler: (requests, ctx) =>
+          collectResponses((onMessage) =>
+            handler(requestSource(requests), metadataPairs(ctx.metadata), onMessage)
+          ),
+      });
+    },
+    start(serviceName) {
+      if (started) return;
+      started = true;
+      server.addService({ name: serviceName ?? "grpc-dc-bridge", methods });
+      // Serve on the channel's endpoint (a raw DataChannel is
+      // wrapped by Server itself; a Channel must not be).
+      server.serve(channel instanceof Channel ? channel.endpoint : channel);
+    },
+  };
+}