@minip2p/web 0.0.0-stage → 0.10.1

package/src/sdk.ts

@@ -0,0 +1,237 @@
+/* oxlint-disable func-style, max-classes-per-file, no-use-before-define -- Hoisted helpers keep the public entry points first. */
+
+/**
+ * The implementation both entry points share: `Minip2p` over the wasm
+ * module's `WebEndpoint`, the key helpers, and `initMinip2p`.
+ */
+
+import {
+  ClosedError,
+  DriverFailedError,
+  DriverFailureKind,
+  Minip2pBase,
+} from "@minip2p/core";
+import type { Bytes, Minip2pConfig } from "@minip2p/core";
+import { resolveEndpointConfig } from "@minip2p/core/backend";
+import type { Minip2pBackend } from "@minip2p/core/backend";
+import { SerdeBackend, typedNativeCall } from "@minip2p/core/serde-backend";
+
+import { JsIo } from "./io.js";
+import { loadWasm, wasm } from "./wasm.js";
+import type { WasmSource } from "./wasm.js";
+
+/** Options for {@link initMinip2p}. */
+export interface InitMinip2pOptions {
+  /**
+   * The `.wasm`: a URL, a `Response`, its bytes, or a compiled
+   * `WebAssembly.Module`. Defaults to the file beside the package.
+   */
+  readonly wasm?: WasmSource;
+}
+
+/**
+ * Loads minip2p's wasm module. `@minip2p/web` calls it at import;
+ * `@minip2p/web/manual` leaves it to the host, which must await it before
+ * `Minip2p.create`. Safe to call again: later calls share the first load
+ * that succeeds, and a failed load can be retried.
+ */
+export async function initMinip2p(
+  options: InitMinip2pOptions = {}
+): Promise<void> {
+  await loadWasm(options.wasm);
+}
+
+/** High-level browser owner for one minip2p endpoint. */
+export class Minip2p extends Minip2pBase {
+  private constructor(backend: Minip2pBackend, relays: readonly string[]) {
+    super(backend, relays);
+  }
+
+  /** Constructs and starts a browser endpoint. */
+  static create(config: Minip2pConfig): Minip2p {
+    return new Minip2p(webBackend(config), config.relays ?? []);
+  }
+}
+
+/** Generates a new 32-byte Ed25519 secret key with `crypto.getRandomValues`. */
+export function generateSecretKey(): Uint8Array {
+  return typedNativeCall(() => wasm().generateSecretKey());
+}
+
+/** Derives a peer ID from raw Ed25519 secret key material. */
+export function peerIdFromSecretKey(secretKey: Bytes): string {
+  return typedNativeCall(() =>
+    wasm().peerIdFromSecretKey(toUint8Array(secretKey))
+  );
+}
+
+/** Builds a circuit multiaddress through a direct relay address. */
+export function circuitAddress(relayAddress: string, peerId: string): string {
+  return typedNativeCall(() => wasm().circuitAddress(relayAddress, peerId));
+}
+
+/** Polls a batch of rounds back to back before yielding the event loop. */
+const PUMP_ROUNDS = 64;
+
+/**
+ * Drives the wasm endpoint on the page's event loop: one coalesced
+ * microtask per burst of calls and I/O events, at most {@link PUMP_ROUNDS}
+ * polls before yielding with `setTimeout(0)`, and one re-armed timer for
+ * the endpoint's next deadline.
+ */
+class Pump {
+  readonly #poll: () => number | undefined;
+  #queued = false;
+  #timer: ReturnType<typeof setTimeout> | undefined;
+  #stopped = false;
+
+  /**
+   * `poll` pumps once and returns the delay until the next pump; a throw
+   * stops the pump for good.
+   */
+  constructor(poll: () => number | undefined) {
+    this.#poll = poll;
+  }
+
+  schedule(): void {
+    if (this.#queued || this.#stopped) {
+      return;
+    }
+    this.#queued = true;
+    queueMicrotask(() => {
+      this.#run();
+    });
+  }
+
+  stop(): void {
+    this.#stopped = true;
+    clearTimeout(this.#timer);
+  }
+
+  #run(): void {
+    this.#queued = false;
+    clearTimeout(this.#timer);
+    this.#timer = undefined;
+    for (let round = 0; round < PUMP_ROUNDS && !this.#stopped; round += 1) {
+      let delay: number | undefined;
+      try {
+        delay = this.#poll();
+      } catch {
+        // The endpoint failed, and its owner already reported it.
+        this.stop();
+        return;
+      }
+      if (delay === undefined) {
+        return;
+      }
+      if (delay > 0) {
+        this.#arm(delay);
+        return;
+      }
+    }
+    // Still busy: let the page run, then carry on.
+    this.#arm(0);
+  }
+
+  #arm(delay: number): void {
+    if (this.#stopped) {
+      return;
+    }
+    this.#timer = setTimeout(() => {
+      this.#timer = undefined;
+      this.schedule();
+    }, delay);
+  }
+}
+
+/**
+ * Calls into one wasm instance. A trap (`WebAssembly.RuntimeError`, which a
+ * Rust panic becomes on wasm32) leaves the instance unusable: the call that
+ * hit it throws `DriverFailedError`, `onFail` fails the endpoint, and every
+ * later call throws `ClosedError` without touching wasm again.
+ */
+class WasmCalls {
+  readonly #onFail: (detail: string) => void;
+  /** Trapped, or the instance was freed. */
+  #failed = false;
+
+  constructor(onFail: (detail: string) => void) {
+    this.#onFail = onFail;
+  }
+
+  call<T>(operation: () => T): T {
+    if (this.#failed) {
+      throw new ClosedError();
+    }
+    try {
+      return operation();
+    } catch (error) {
+      if (!(error instanceof WebAssembly.RuntimeError)) {
+        throw error;
+      }
+      this.#failed = true;
+      const detail = `the minip2p wasm module trapped: ${error.message}`;
+      this.#onFail(detail);
+      throw new DriverFailedError(DriverFailureKind.Panic, detail);
+    }
+  }
+
+  /** Runs `free` unless the instance trapped; later calls throw `ClosedError`. */
+  release(free: () => void): void {
+    if (!this.#failed) {
+      this.#failed = true;
+      free();
+    }
+  }
+}
+
+function webBackend(config: Minip2pConfig): Minip2pBackend {
+  const module = wasm();
+  // A trapped instance can neither close its sessions nor be freed: close
+  // them from TypeScript.
+  const calls = new WasmCalls((detail) => {
+    pump.stop();
+    io.dispose();
+    backend.fail(detail);
+  });
+  const pump = new Pump(() => calls.call(() => endpoint.pump()));
+  const io = new JsIo(() => {
+    pump.schedule();
+  });
+  const endpoint = typedNativeCall(
+    () =>
+      new module.WebEndpoint(
+        toUint8Array(config.secretKey),
+        resolveEndpointConfig(config),
+        io
+      )
+  );
+  const backend = new SerdeBackend(endpoint, {
+    // Every command may queue work (a dial, a write): pump after it.
+    call: (operation) => {
+      try {
+        return calls.call(operation);
+      } finally {
+        pump.schedule();
+      }
+    },
+    circuitAddress,
+    // Closed and drained: stop pumping and free the wasm object, which
+    // drops its doorbell and `JsIo`.
+    release: () => {
+      pump.stop();
+      calls.release(() => {
+        endpoint.free();
+      });
+    },
+    schedule: (task) => {
+      queueMicrotask(task);
+    },
+  });
+  return backend;
+}
+
+/** A view wasm-bindgen copies into wasm memory before the call returns. */
+function toUint8Array(value: Bytes): Uint8Array {
+  return value instanceof Uint8Array ? value : new Uint8Array(value);
+}

package/src/wasm.ts

@@ -0,0 +1,48 @@
+/**
+ * The minip2p wasm module (`crates/web`) and its one-time initialisation.
+ * Nothing here fetches on import: `@minip2p/web` initialises at its own
+ * import, `@minip2p/web/manual` when the host calls `initMinip2p`.
+ */
+
+import init, * as glue from "../wasm/minip2p_web.js";
+import type { InitInput } from "../wasm/minip2p_web.js";
+
+/** Where the `.wasm` comes from: a URL, a `Response`, its bytes, or a compiled module. */
+export type WasmSource = InitInput | Promise<InitInput>;
+
+let loading: Promise<void> | undefined;
+let loaded = false;
+
+const instantiate = async (source: WasmSource | undefined): Promise<void> => {
+  // wasm-bindgen fetches a string or URL only when it is passed directly,
+  // so a promised one is awaited here first.
+  await init(
+    source === undefined ? undefined : { module_or_path: await source }
+  );
+  loaded = true;
+};
+
+/**
+ * Instantiates the module once; later calls share the first that succeeds.
+ * Without `source`, the `.wasm` beside this package is fetched (resolved
+ * from `import.meta.url`). A failed load can be retried, with another source.
+ */
+export const loadWasm = async (source?: WasmSource): Promise<void> => {
+  loading ??= instantiate(source);
+  try {
+    await loading;
+  } catch (error) {
+    loading = undefined;
+    throw error;
+  }
+};
+
+/** The initialised module's exports; throws until {@link loadWasm} resolved. */
+export const wasm = (): typeof glue => {
+  if (!loaded) {
+    throw new Error(
+      "minip2p's wasm module is not initialised: import @minip2p/web, or await initMinip2p() from @minip2p/web/manual before creating an endpoint"
+    );
+  }
+  return glue;
+};

package/wasm/minip2p_web.d.ts

@@ -0,0 +1,241 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * A minip2p endpoint in the browser, dialing over WebTransport.
+ *
+ * It is driven by its TypeScript owner: every call returns at once, and
+ * `pump` polls the endpoint, which the owner schedules after each call, each
+ * `JsIo` event, and at the deadline `pump` returns.
+ */
+export class WebEndpoint {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Resets and relinquishes a stream.
+     */
+    abandonStream(conn_id: bigint, stream_id: bigint): void;
+    /**
+     * The relay reservation currently held, or `null`.
+     */
+    activeReservation(): any;
+    /**
+     * Registers an application protocol.
+     */
+    addProtocol(protocol_id: string): void;
+    /**
+     * Cancels a Connection attempt.
+     */
+    cancelConnect(id: bigint): void;
+    /**
+     * Half-closes a stream's write side.
+     */
+    closeStreamWrite(conn_id: bigint, stream_id: bigint): void;
+    /**
+     * Closes the endpoint; `EndpointClosed` is the last event drained.
+     *
+     * The timeout is ignored in the browser: every session closes at once
+     * (`WebTransport.close()` sends the close capsule), so there is no
+     * drain for it to bound.
+     */
+    close(_timeout_ms: number): void;
+    /**
+     * Starts one Connection attempt: a peer ID string, or an array of peer
+     * addresses naming one peer. Returns the Connect ID.
+     */
+    connect(target: any): bigint;
+    /**
+     * Connected peer IDs.
+     */
+    connectedPeers(): string[];
+    /**
+     * A snapshot of a peer's connection, or `null`.
+     */
+    connectionInfo(peer_id: string): any;
+    /**
+     * Disconnects one peer.
+     */
+    disconnect(peer_id: string): void;
+    /**
+     * The discovery clock (always `null` in a browser).
+     */
+    discoveryNowMs(): any;
+    /**
+     * Pulls a bounded batch of events.
+     */
+    drainEvents(limit: number): any;
+    /**
+     * Whether Identify completed for a peer.
+     */
+    isPeerReady(peer_id: string): boolean;
+    /**
+     * Whether the endpoint is started and not closed.
+     */
+    isRunning(): boolean;
+    /**
+     * The discovery book (always empty in a browser).
+     */
+    knownPeers(): any;
+    /**
+     * The listen set; empty, since browsers do not listen.
+     */
+    listenAddrs(): string[];
+    /**
+     * Validates the key and config and builds the endpoint over `io`,
+     * without driving it yet.
+     */
+    constructor(secret_key: Uint8Array, config: any, io: any);
+    /**
+     * Starts opening an application stream.
+     */
+    openStream(peer_id: string, protocol_id: string): any;
+    /**
+     * The path of a peer's connection, or `null`.
+     */
+    path(peer_id: string): any;
+    /**
+     * The local peer ID.
+     */
+    peerId(): string;
+    /**
+     * The latest Identify snapshot, or `null`.
+     */
+    peerInfo(peer_id: string): any;
+    /**
+     * Starts one ping.
+     */
+    ping(peer_id: string): void;
+    /**
+     * Publishes one pubsub payload.
+     */
+    publish(topic: string, data: Uint8Array): void;
+    /**
+     * Polls the endpoint once and returns the milliseconds until it needs
+     * polling again (`0` at once), or `undefined` when nothing is
+     * scheduled.
+     */
+    pump(): number | undefined;
+    /**
+     * The reachability verdict (always `Unknown` in a browser).
+     */
+    reachability(): any;
+    /**
+     * Resets a stream.
+     */
+    resetStream(conn_id: bigint, stream_id: bigint): void;
+    /**
+     * Sends bytes on a stream: `true` once all are accepted, `false` while
+     * the tail is held and `StreamWriteAccepted` is still to come.
+     */
+    sendStream(conn_id: bigint, stream_id: bigint, data: Uint8Array): boolean;
+    /**
+     * Ignored in the browser, kept for the shared SDK surface: there is no
+     * background driver whose cadence it could change. The page's own
+     * timers pump the endpoint.
+     */
+    setActive(_active: boolean): void;
+    /**
+     * Starts driving; `doorbell` is called when events become ready to drain.
+     */
+    start(doorbell: Function): void;
+    /**
+     * Acknowledges `bytes` of a stream's received data as consumed.
+     */
+    streamConsumed(conn_id: bigint, stream_id: bigint, bytes: number): void;
+    /**
+     * Subscribes to a pubsub topic.
+     */
+    subscribe(topic: string): boolean;
+    /**
+     * Unsubscribes from a pubsub topic.
+     */
+    unsubscribe(topic: string): boolean;
+}
+
+/**
+ * Builds a circuit address through a direct relay address.
+ */
+export function circuitAddress(relay_address: string, peer_id: string): string;
+
+/**
+ * Generates a 32-byte Ed25519 secret key from `crypto.getRandomValues`.
+ */
+export function generateSecretKey(): Uint8Array;
+
+/**
+ * Derives a peer ID from raw Ed25519 secret key material.
+ */
+export function peerIdFromSecretKey(secret_key: Uint8Array): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_webendpoint_free: (a: number, b: number) => void;
+    readonly circuitAddress: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly generateSecretKey: () => [number, number, number, number];
+    readonly peerIdFromSecretKey: (a: number, b: number) => [number, number, number, number];
+    readonly webendpoint_abandonStream: (a: number, b: bigint, c: bigint) => [number, number];
+    readonly webendpoint_activeReservation: (a: number) => [number, number, number];
+    readonly webendpoint_addProtocol: (a: number, b: number, c: number) => [number, number];
+    readonly webendpoint_cancelConnect: (a: number, b: bigint) => [number, number];
+    readonly webendpoint_close: (a: number, b: number) => void;
+    readonly webendpoint_closeStreamWrite: (a: number, b: bigint, c: bigint) => [number, number];
+    readonly webendpoint_connect: (a: number, b: any) => [bigint, number, number];
+    readonly webendpoint_connectedPeers: (a: number) => [number, number, number, number];
+    readonly webendpoint_connectionInfo: (a: number, b: number, c: number) => [number, number, number];
+    readonly webendpoint_disconnect: (a: number, b: number, c: number) => [number, number];
+    readonly webendpoint_discoveryNowMs: (a: number) => [number, number, number];
+    readonly webendpoint_drainEvents: (a: number, b: number) => [number, number, number];
+    readonly webendpoint_isPeerReady: (a: number, b: number, c: number) => [number, number, number];
+    readonly webendpoint_isRunning: (a: number) => number;
+    readonly webendpoint_knownPeers: (a: number) => [number, number, number];
+    readonly webendpoint_listenAddrs: (a: number) => [number, number];
+    readonly webendpoint_new: (a: number, b: number, c: any, d: any) => [number, number, number];
+    readonly webendpoint_openStream: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly webendpoint_path: (a: number, b: number, c: number) => [number, number, number];
+    readonly webendpoint_peerId: (a: number) => [number, number];
+    readonly webendpoint_peerInfo: (a: number, b: number, c: number) => [number, number, number];
+    readonly webendpoint_ping: (a: number, b: number, c: number) => [number, number];
+    readonly webendpoint_publish: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly webendpoint_pump: (a: number) => [number, number];
+    readonly webendpoint_reachability: (a: number) => [number, number, number];
+    readonly webendpoint_resetStream: (a: number, b: bigint, c: bigint) => [number, number];
+    readonly webendpoint_sendStream: (a: number, b: bigint, c: bigint, d: number, e: number) => [number, number, number];
+    readonly webendpoint_setActive: (a: number, b: number) => void;
+    readonly webendpoint_start: (a: number, b: any) => [number, number];
+    readonly webendpoint_streamConsumed: (a: number, b: bigint, c: bigint, d: number) => [number, number];
+    readonly webendpoint_subscribe: (a: number, b: number, c: number) => [number, number, number];
+    readonly webendpoint_unsubscribe: (a: number, b: number, c: number) => [number, number, number];
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_drop_slice: (a: number, b: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;