grpc-dc 0.0.0-stage → 0.31.0

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# JavaScript (browser + Node) — grpc-dc runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Start here if you are new to the project. The runtime in
+this directory is generated, dependency-free, and speaks
+the gRPC wire protocol over WebRTC DataChannels.
+
+## First run
+
+```sh
+    node js/examples/echo_demo.js   # all four method shapes, in-memory pair
+    node --test js/test/*.test.js   # full suite
+```
+
+## Use it in your project
+
+npm install grpc-dc — or copy this directory; there are no dependencies. TypeScript types ship in `index.d.ts`.
+
+## Regenerate stubs for your schema
+
+From the repository root (one wrapper per language in `bin/`):
+
+    protoc --plugin=protoc-gen-grpc-dc-js=$PWD/bin/protoc-gen-grpc-dc-js \
+           --grpc-dc-js_out=out -I . your.proto
+
+Or generate in the browser and download the zip:
+https://browser-grpc.github.io/grpc-over-datachannels/app/
+
+## Where things live
+
+- Runtime: this directory (see its generated sources).
+- Worked example: `examples/` (Echo in every method shape).
+- Tests: `tests/` — the same BDD scenarios every language runs.
+
+Full project quickstart: [`../QUICKSTART.md`](../QUICKSTART.md).

package/index.d.ts

@@ -0,0 +1,193 @@
+// TypeScript declarations for the grpc-dc JavaScript runtime.
+// Hand-written against js/index.js + js/src/*; generated stubs
+// (echo_*_grpc_dc.js etc.) are plain JS and can be wrapped with
+// typed facades using the Channel generics below.
+
+export type Metadata = Record<string, string>;
+
+export interface CallOptions {
+  metadata?: Metadata;
+  timeout?: number;
+}
+
+export interface MessageType<T> {
+  encode(message: T): Uint8Array;
+  decode(bytes: Uint8Array): T;
+}
+
+export declare const FrameType: Record<string, number>;
+export declare const StatusCode: Record<string, number>;
+export declare const StatusName: Record<number, string>;
+
+export declare class StatusError extends Error {
+  code: number;
+  constructor(code: number, message?: string);
+  static ok(): StatusError;
+  static unimplemented(message: string): StatusError;
+  static internal(message: string): StatusError;
+  static unavailable(message: string): StatusError;
+  static invalidArgument(message: string): StatusError;
+}
+
+export declare function encodeFrame(
+  type: number, streamId: number, payload?: Uint8Array): Uint8Array;
+export declare function decodeFrame(
+  data: Uint8Array | ArrayBuffer): { type: number; streamId: number; payload: Uint8Array };
+export declare function encodeTimeout(timeoutMs: number): string;
+export declare function parseTimeout(text: string): number | null;
+export declare function setTracer(tracer: unknown): void;
+export declare function setTraceFilter(patterns: unknown): void;
+export declare function toHex(bytes: Uint8Array): string;
+export declare function fromHex(hex: string): Uint8Array;
+
+export type DataChannelLike = {
+  send(data: unknown): void;
+  addEventListener?: (type: string, listener: (event: unknown) => void) => void;
+  binaryType?: string;
+  readyState?: string;
+  bufferedAmount?: number;
+};
+
+export declare class StreamInput<T = unknown> {
+  push(item: T): void;
+  end(): void;
+  fail(error: unknown): void;
+}
+
+export declare class Endpoint {
+  dispatcher: unknown;
+  constructor(dc: DataChannelLike, options?: { parity?: "odd" | "even" });
+  openStream(): StreamInput;
+  closeStream(id: number): void;
+  sendFrame(frameBytes: Uint8Array): Promise<void>;
+  closeAll(): void;
+}
+
+export declare class Channel {
+  readonly endpoint: Endpoint;
+  constructor(dcOrEndpoint: DataChannelLike | Endpoint,
+              options?: { parity?: "odd" | "even" });
+  unary<Req, Res>(path: string, request: Req,
+                  reqType: MessageType<Req>, resType: MessageType<Res>,
+                  options?: CallOptions): Promise<Res>;
+  serverStream<Req, Res>(path: string, request: Req,
+                         reqType: MessageType<Req>, resType: MessageType<Res>,
+                         options?: CallOptions): Promise<AsyncIterable<Res>>;
+  clientStream<Req, Res>(path: string, requests: AsyncIterable<Req>,
+                         reqType: MessageType<Req>, resType: MessageType<Res>,
+                         options?: CallOptions): Promise<Res>;
+  bidi<Req, Res>(path: string, requests: AsyncIterable<Req>,
+                 reqType: MessageType<Req>, resType: MessageType<Res>,
+                 options?: CallOptions): AsyncIterable<Res>;
+  cancel(streamId: number): Promise<void>;
+}
+
+export interface MethodDef {
+  path: string;
+  kind: "unary" | "server-streaming" | "client-streaming" | "bidi";
+  requestType: MessageType<unknown>;
+  responseType: MessageType<unknown>;
+  handler: (...args: never[]) => unknown;
+}
+
+export interface ServiceDef {
+  name: string;
+  methods: Record<string, MethodDef>;
+}
+
+export interface CallContext {
+  path: string;
+  metadata: Metadata;
+  streamId: number;
+  deadline: number | null;
+}
+
+export declare class Server {
+  addService(definition: ServiceDef): void;
+  serve(dcOrEndpoint: DataChannelLike | Endpoint,
+        options?: { parity?: "odd" | "even" }): void;
+}
+
+export declare function memoryDataChannelPair(): [DataChannelLike, DataChannelLike];
+
+export declare function createPeer(
+  dc: DataChannelLike,
+  options?: { parity?: "odd" | "even" },
+): { endpoint: Endpoint; server: Server; channel: Channel };
+
+export declare class GenericMessage {
+  constructor(model?: unknown);
+  set(number: number, value: unknown): void;
+  add(number: number, value: unknown): void;
+  getAll(number: number): unknown[];
+  get(number: number, fallback?: unknown): unknown;
+  getString(number: number, fallback?: string): string;
+  getInt(number: number, fallback?: number): number;
+}
+
+export interface FileModel {
+  services: Map<string, unknown>;
+  messages: Map<string, unknown>;
+  enums: Map<string, unknown>;
+  fileName: string;
+  packageName: string;
+}
+
+export declare function parseDescriptorSet(data: Uint8Array): FileModel;
+export declare function createDynamicService(
+  fileModel: FileModel, serviceName: string,
+  handler: Record<string, (...args: never[]) => unknown>): ServiceDef;
+
+export declare class DynamicClient {
+  constructor(channel: Channel, fileModel: FileModel);
+  unary(serviceName: string, methodName: string, request: GenericMessage,
+        options?: CallOptions): Promise<GenericMessage>;
+  serverStream(serviceName: string, methodName: string, request: GenericMessage,
+               options?: CallOptions): Promise<AsyncIterable<GenericMessage>>;
+  clientStream(serviceName: string, methodName: string,
+               requests: AsyncIterable<GenericMessage>,
+               options?: CallOptions): Promise<GenericMessage>;
+  bidi(serviceName: string, methodName: string,
+       requests: AsyncIterable<GenericMessage>,
+       options?: CallOptions): AsyncIterable<GenericMessage>;
+}
+
+export interface GrpcDcBridge {
+  unary(path: string, payload: Uint8Array,
+        options?: CallOptions): Promise<Uint8Array>;
+  serverStream(path: string, payload: Uint8Array,
+               onMessage: (message: Uint8Array) => void,
+               options?: CallOptions): Promise<void>;
+  clientStream(path: string, payloads: Uint8Array[] | AsyncIterable<Uint8Array>,
+               options?: CallOptions): Promise<Uint8Array>;
+  bidi(path: string, payloads: Uint8Array[] | AsyncIterable<Uint8Array>,
+       onMessage: (message: Uint8Array) => void,
+       options?: CallOptions): Promise<void>;
+}
+
+export declare function createGrpcDcBridge(
+  dcOrChannel: DataChannelLike | Channel): GrpcDcBridge;
+
+export interface GrpcDcServerBridge {
+  registerUnary(path: string,
+    handler: (payload: Uint8Array, metadata: [string, string][]) => Promise<Uint8Array> | Uint8Array): void;
+  registerServerStream(path: string,
+    handler: (payload: Uint8Array, metadata: [string, string][],
+              onMessage: (message: Uint8Array) => void) => unknown): void;
+  registerClientStream(path: string,
+    handler: (payloads: Uint8Array[], metadata: [string, string][]) => Promise<Uint8Array> | Uint8Array): void;
+  registerBidi(path: string,
+    handler: (payloads: Uint8Array[], metadata: [string, string][],
+              onMessage: (message: Uint8Array) => void) => unknown): void;
+  registerClientStreamInc(path: string,
+    handler: (source: { next(): Promise<Uint8Array | null> },
+              metadata: [string, string][]) => Promise<Uint8Array> | Uint8Array): void;
+  registerBidiInc(path: string,
+    handler: (source: { next(): Promise<Uint8Array | null> },
+              metadata: [string, string][],
+              onMessage: (message: Uint8Array) => void) => unknown): void;
+  start(serviceName?: string): void;
+}
+
+export declare function createGrpcDcServerBridge(
+  dcOrChannel: DataChannelLike | Channel): GrpcDcServerBridge;

package/index.js

@@ -0,0 +1,51 @@
+// grpc-dc: gRPC over WebRTC DataChannels (JavaScript runtime).
+// Wire tables in wire_gen.js and the protoc plugin that generates service
+// stubs are produced by the grpc-dc code generator.
+
+export {
+  FrameType,
+  StatusCode,
+  StatusName,
+  StatusError,
+  encodeFrame,
+  decodeFrame,
+  encodeTimeout,
+  parseTimeout,
+  setTracer,
+  setTraceFilter,
+  toHex,
+  fromHex,
+} from "./src/codec.js";
+export { Endpoint, StreamInput } from "./src/endpoint.js";
+export { Channel } from "./src/channel.js";
+export { Server } from "./src/server.js";
+export { memoryDataChannelPair } from "./src/loopback.js";
+export { createGrpcDcBridge, createGrpcDcServerBridge } from "./src/wasm_bridge.js";
+// Note: the Node WebRTC-Direct adapter (src/webrtc_direct.js)
+// is deliberately NOT re-exported here -- it imports Node-only
+// modules (node:dgram via webrtc/js/direct.js) and this index
+// is also loaded in browsers. Import it directly:
+//   import { directClientEndpoint } from "grpc-dc/webrtc_direct";
+
+import { Channel } from "./src/channel.js";
+import { Endpoint } from "./src/endpoint.js";
+import { Server } from "./src/server.js";
+
+/**
+ * A bidirectional peer: a Channel and a Server sharing one endpoint, so
+ * both sides can call each other over the same data channel. The peer
+ * that created the channel allocates odd stream ids; the answering peer
+ * must pass { parity: "even" }.
+ */
+export function createPeer(dc, { parity = "odd" } = {}) {
+  const endpoint = new Endpoint(dc, { parity });
+  const server = new Server();
+  server.serve(endpoint);
+  return { endpoint, server, channel: new Channel(endpoint) };
+}
+export {
+  DynamicClient,
+  GenericMessage,
+  createDynamicService,
+  parseDescriptorSet,
+} from "./src/dynamic.js";

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "grpc-dc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.31.0",
+  "description": "gRPC in the browser over WebRTC DataChannels: dependency-free generated gRPC clients & servers for JavaScript — no grpc-web proxy, no external runtime",
+  "keywords": [
+    "grpc",
+    "grpc-web",
+    "webrtc",
+    "datachannel",
+    "rtcdatachannel",
+    "protobuf",
+    "protoc",
+    "wasm",
+    "browser",
+    "peer-to-peer"
+  ],
+  "homepage": "https://browser-grpc.github.io/grpc-over-datachannels/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/browser-grpc/grpc-over-datachannels.git"
+  },
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./wire_gen.js": "./wire_gen.js",
+    "./webrtc_direct": "./src/webrtc_direct.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "wire_gen.js",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "license": "Apache-2.0"
+}

package/src/channel.js

@@ -0,0 +1,228 @@
+// @generated by grpc-dc codegen. DO NOT EDIT.
+// SPDX-License-Identifier: Apache-2.0
+// Client side: opens streams on one endpoint, all four gRPC shapes.
+// Message types are classes with static encode(msg)/decode(bytes).
+
+import {
+  FrameType,
+  StatusError,
+  StatusName,
+  encodeFrame,
+  encodeTimeout,
+  formatTraceparent,
+  getTracer,
+  headersFrame,
+  parseTraceparent,
+  statusFrame,
+  traceEnd,
+  traceStart,
+} from "./codec.js";
+import { Endpoint } from "./endpoint.js";
+
+export class Channel {
+  #endpoint;
+  #traces = new Map();
+
+  /** Accepts an Endpoint or a raw RTCDataChannel-like object. */
+  constructor(dcOrEndpoint, options) {
+    this.#endpoint =
+      dcOrEndpoint instanceof Endpoint ? dcOrEndpoint : new Endpoint(dcOrEndpoint, options);
+  }
+
+  get endpoint() {
+    return this.#endpoint;
+  }
+
+  async #open(path, metadata, timeout) {
+    let deadline = null;
+    if (timeout !== undefined && timeout !== null) {
+      deadline = Date.now() + timeout;
+      metadata = { ...metadata, "grpc-timeout": encodeTimeout(timeout) };
+    }
+    let traceCtx = null;
+    if (getTracer() !== null) {
+      traceCtx = traceStart("client", path, parseTraceparent(metadata?.traceparent));
+      if (traceCtx !== null) {
+        metadata = {
+          ...metadata,
+          traceparent: formatTraceparent(traceCtx.traceId, traceCtx.spanId),
+        };
+      }
+    }
+    const [id, input] = this.#endpoint.openStream();
+    if (traceCtx !== null) this.#traces.set(id, { ctx: traceCtx, path });
+    try {
+      await this.#endpoint.sendFrame(headersFrame(id, path, metadata));
+    } catch (e) {
+      this.#endTrace(id, "UNAVAILABLE");
+      this.#endpoint.closeStream(id);
+      throw e;
+    }
+    return [id, input, deadline];
+  }
+
+  #endTrace(id, status) {
+    const entry = this.#traces.get(id);
+    if (entry) {
+      this.#traces.delete(id);
+      traceEnd("client", entry.path, entry.ctx, status);
+    }
+  }
+
+  // Next event from input's iterator, enforcing the call deadline:
+  // on expiry the stream is aborted (RST) and DEADLINE_EXCEEDED
+  // (code 4) is thrown.
+  async #next(id, iterator, deadline) {
+    if (deadline === null) return iterator.next();
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      await this.cancel(id).catch(() => {});
+      throw new StatusError(4, "deadline exceeded");
+    }
+    let timer;
+    try {
+      return await Promise.race([
+        iterator.next(),
+        new Promise((_, reject) => {
+          timer = setTimeout(
+            () => reject(new StatusError(4, "deadline exceeded")),
+            remaining,
+          );
+        }),
+      ]);
+    } catch (e) {
+      if (e instanceof StatusError && e.code === 4) {
+        await this.cancel(id).catch(() => {});
+      }
+      throw e;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async #sendMessage(id, ReqType, request) {
+    await this.#endpoint.sendFrame(encodeFrame(FrameType.DATA, id, ReqType.encode(request)));
+  }
+
+  async #collectOne(id, input, RespType, deadline = null) {
+    const iterator = input[Symbol.asyncIterator]();
+    try {
+      let response = null;
+      for (;;) {
+        const step = await this.#next(id, iterator, deadline);
+        if (step.done) break;
+        const event = step.value;
+        if (event.kind === "data") {
+          if (response !== null) {
+            throw StatusError.internal("unary call received more than one response");
+          }
+          response = RespType.decode(event.payload);
+        } else if (event.kind === "trailers") {
+          this.#endTrace(id, StatusName[event.status.code] ?? `CODE_${event.status.code}`);
+          if (event.status.code !== 0) throw event.status;
+          if (response === null) throw StatusError.internal("call closed with no response");
+          return response;
+        } else if (event.kind === "rst") {
+          this.#endTrace(id, StatusName[event.status.code] ?? `CODE_${event.status.code}`);
+          throw event.status;
+        }
+      }
+      throw StatusError.unavailable("data channel closed");
+    } finally {
+      this.#endTrace(id, "UNAVAILABLE");
+      this.#endpoint.closeStream(id);
+    }
+  }
+
+  async *#responses(id, input, RespType, deadline = null) {
+    const iterator = input[Symbol.asyncIterator]();
+    try {
+      for (;;) {
+        const step = await this.#next(id, iterator, deadline);
+        if (step.done) break;
+        const event = step.value;
+        if (event.kind === "data") {
+          yield RespType.decode(event.payload);
+        } else if (event.kind === "trailers") {
+          this.#endTrace(id, StatusName[event.status.code] ?? `CODE_${event.status.code}`);
+          if (event.status.code !== 0) throw event.status;
+          return;
+        } else if (event.kind === "rst") {
+          this.#endTrace(id, StatusName[event.status.code] ?? `CODE_${event.status.code}`);
+          throw event.status;
+        }
+      }
+      throw StatusError.unavailable("data channel closed");
+    } finally {
+      this.#endTrace(id, "UNAVAILABLE");
+      this.#endpoint.closeStream(id);
+    }
+  }
+
+  async #pump(id, requests, ReqType) {
+    try {
+      for await (const request of requests) {
+        await this.#sendMessage(id, ReqType, request);
+      }
+      await this.#endpoint.sendFrame(encodeFrame(FrameType.HALF_CLOSE, id));
+    } catch (e) {
+      const status = e instanceof StatusError ? e : StatusError.internal(e?.message ?? String(e));
+      await this.#endpoint
+        .sendFrame(statusFrame(FrameType.RST, id, status))
+        .catch(() => {});
+    }
+  }
+
+  /** Unary: one request, one response. */
+  async unary(path, request, ReqType, RespType, { metadata = {}, timeout } = {}) {
+    const [id, input, deadline] = await this.#open(path, metadata, timeout);
+    await this.#sendMessage(id, ReqType, request);
+    await this.#endpoint.sendFrame(encodeFrame(FrameType.HALF_CLOSE, id));
+    return this.#collectOne(id, input, RespType, deadline);
+  }
+
+  /** Server-streaming: one request, async iterable of responses. */
+  serverStream(path, request, ReqType, RespType, { metadata = {}, timeout } = {}) {
+    return (async () => {
+      const [id, input, deadline] = await this.#open(path, metadata, timeout);
+      await this.#sendMessage(id, ReqType, request);
+      await this.#endpoint.sendFrame(encodeFrame(FrameType.HALF_CLOSE, id));
+      return this.#responses(id, input, RespType, deadline);
+    })();
+  }
+
+  /** Client-streaming: async iterable of requests, one response. */
+  async clientStream(path, requests, ReqType, RespType, { metadata = {}, timeout } = {}) {
+    const [id, input, deadline] = await this.#open(path, metadata, timeout);
+    const pump = this.#pump(id, requests, ReqType);
+    try {
+      return await this.#collectOne(id, input, RespType, deadline);
+    } finally {
+      pump.catch(() => {});
+    }
+  }
+
+  /** Bidirectional: async iterable of requests and of responses. */
+  bidi(path, requests, ReqType, RespType, { metadata = {}, timeout } = {}) {
+    return (async () => {
+      const [id, input, deadline] = await this.#open(path, metadata, timeout);
+      const pump = this.#pump(id, requests, ReqType);
+      pump.catch(() => {});
+      return this.#responses(id, input, RespType, deadline);
+    })();
+  }
+
+  /** Abort a call: sends RST CANCELLED. */
+  async cancel(streamId) {
+    await this.#endpoint
+      .sendFrame(
+        statusFrame(
+          FrameType.RST,
+          streamId,
+          new StatusError(1, "cancelled by caller"),
+        ),
+      )
+      .catch(() => {});
+    this.#endpoint.closeStream(streamId);
+  }
+}