y-reticulum 0.1.0

package/src/peer-conn.js

@@ -0,0 +1,204 @@
+/**
+ * @file peer-conn.js
+ * @description Wrapper around a Reticulum {@link Link} to a single Yjs peer.
+ *
+ * Owns link lifecycle and the low-level send/receive of raw framed bytes. It
+ * carries no Yjs semantics of its own: the Room plugs the sync/awareness
+ * protocol into the bytes that flow through here.
+ *
+ * Small payloads travel as reliable {@link Channel} messages: the channel adds
+ * automatic retries, send-window flow control, and in-order / dedup'd delivery
+ * over the link, so a sync update or awareness change dropped on a lossy hop is
+ * retransmitted rather than lost. Payloads larger than the channel MDU (an
+ * initial doc state or a large update) cannot fit in a single channel message
+ * and are instead transported as a chunked, integrity-checked, bz2-compressed
+ * Reticulum {@link Resource}, reassembled before delivery.
+ */
+import {
+  CEType,
+  ChannelException,
+  MessageBase,
+  Resource,
+  toHex,
+} from "@reticulum/core";
+
+/**
+ * Application message type used on every y-reticulum {@link Channel}. Its body
+ * is a single raw Yjs wire frame (the y-webrtc tag + lib0 payload), carried
+ * verbatim — the channel envelope adds the framing Reticulum needs for
+ * reliability, ordering, and flow control, so nothing here touches the Yjs
+ * bytes.
+ *
+ * @extends {MessageBase}
+ */
+class YjsSyncMessage extends MessageBase {
+  /** Unique y-reticulum message type on the channel (< 0xf000). */
+  static MSGTYPE = 0x0001;
+
+  constructor() {
+    super();
+    /** @type {Uint8Array} */
+    this.data = new Uint8Array(0);
+  }
+
+  /** @returns {Uint8Array} */
+  pack() {
+    return this.data;
+  }
+
+  /** @param {Uint8Array} raw */
+  unpack(raw) {
+    this.data = raw;
+  }
+}
+
+/**
+ * A peer-to-peer connection over a Reticulum Link.
+ *
+ * Exactly one PeerConn exists per established Link. `send` writes a raw byte
+ * payload — as a reliable Channel message when it fits the channel MDU, else as
+ * a compressed Resource. Inbound payloads arrive via the channel's message
+ * handler (small) or the link's `resource` event (large) and are forwarded to
+ * the room. The peer id is the hex link_id — identical on both ends of a link,
+ * so both peers agree on the id.
+ */
+export class PeerConn {
+  /**
+   * @param {object} options
+   * @param {import("@reticulum/core").Link} options.link
+   * @param {Uint8Array|null} options.remoteDestHash
+   *   The peer's destination hash. Known on the initiator side (from the
+   *   announce that triggered the link); `null` on the responder side.
+   * @param {import("@digitaldefiance/bzip2-wasm").default | null} [options.bz2]
+   *   Shared bzip2 provider; set on the link so inbound Resources can be
+   *   decompressed, and used to compress outbound ones. `null` disables it.
+   * @param {(payload: Uint8Array, peer: PeerConn) => void} options.onData
+   * @param {(peer: PeerConn) => void} options.onClose
+   */
+  constructor({ link, remoteDestHash, bz2, onData, onClose }) {
+    this.link = link;
+    // The receiver decompresses via the link's bz2 (Resource.accept reads it).
+    this.link.bz2 = bz2 ?? undefined;
+    this.remoteDestHash = remoteDestHash;
+    /** @type {import("@digitaldefiance/bzip2-wasm").default | undefined} */
+    this.bz2 = bz2 ?? undefined;
+    /** Reliable typed-message channel over the link (retries + flow control). */
+    this.channel = link.getChannel();
+    this.channel.registerMessageType(YjsSyncMessage);
+    this._onChannelMessage = this._onChannelMessage.bind(this);
+    this.channel.addMessageHandler(this._onChannelMessage);
+    /** Hex link_id; used as the peer id (symmetric across both ends). */
+    this.peerId = toHex(link.linkId);
+    /** Whether the Yjs doc is synced with this peer. */
+    this.synced = false;
+    this.closed = false;
+    this._onData = onData;
+    this._onClose = onClose;
+
+    // Large, chunked payloads: reassemble, then feed the same path.
+    link.addEventListener("resource", (/** @type {any} */ event) => {
+      const resource = event.detail.resource;
+      resource
+        .whenComplete()
+        .then(() => {
+          if (resource.data) this._onData(resource.data, this);
+        })
+        .catch(() => {
+          // Transfer failed (peer dropped, corrupt, rejected) — nothing to
+          // deliver; the room's sync will converge on the next exchange.
+        });
+    });
+    link.addEventListener("close", () => this._handleClose());
+  }
+
+  /**
+   * Inbound Yjs channel message: forward the raw body to the room. Returns
+   * `true` to claim the message (no other handlers are registered).
+   * @param {import("@reticulum/core").MessageBase} msg
+   * @returns {boolean}
+   */
+  _onChannelMessage(msg) {
+    if (!(msg instanceof YjsSyncMessage)) return false;
+    this._onData(msg.data, this);
+    return true;
+  }
+
+  /**
+   * Sends a raw byte payload to the peer. Small payloads go as a reliable
+   * Channel message (waiting for the send window if it is momentarily full);
+   * payloads larger than the channel MDU travel as a compressed Resource.
+   * @param {Uint8Array} payload
+   */
+  async send(payload) {
+    if (this.closed) return;
+    if (payload.length > this.channel.mdu) {
+      await this._sendResource(payload);
+      return;
+    }
+    await this._sendChannel(payload);
+  }
+
+  /**
+   * Sends `payload` as a reliable Channel message. Waits while the send window
+   * is full (backpressure) and re-arms if the window fills between the readiness
+   * check and the serialized send — matching the library's buffer-layer loop.
+   * @param {Uint8Array} payload
+   */
+  async _sendChannel(payload) {
+    const message = new YjsSyncMessage();
+    message.data = payload;
+    for (;;) {
+      if (this.closed || this.channel._shutDown) return;
+      while (!this.channel.isReadyToSend()) {
+        if (this.closed || this.channel._shutDown) return;
+        await new Promise((r) => setTimeout(r, 50));
+      }
+      try {
+        await this.channel.send(message);
+        return;
+      } catch (err) {
+        if (
+          err instanceof ChannelException &&
+          err.type === CEType.ME_LINK_NOT_READY
+        ) {
+          continue; // window filled between the check and the serialized send
+        }
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Transfers `payload` as a chunked Reticulum Resource, bz2-compressed when
+   * that shrinks it. Only the advertisement is awaited; the chunked transfer
+   * then proceeds on the link and the receiver reassembles (and decompresses)
+   * it before delivery.
+   * @param {Uint8Array} payload
+   */
+  async _sendResource(payload) {
+    const resource = new Resource({
+      data: payload,
+      link: this.link,
+      bz2: this.bz2,
+      autoCompress: true,
+    });
+    await resource.advertise();
+  }
+
+  /**
+   * Silently tears down the link (does not invoke `onClose` — the caller is
+   * responsible for bookkeeping, e.g. a bulk disconnect).
+   */
+  destroy() {
+    if (this.closed) return;
+    this.closed = true;
+    this.link.teardown().catch(() => {});
+  }
+
+  /** Internal: a `close` event arrived from the link (peer dropped / timeout). */
+  _handleClose() {
+    if (this.closed) return;
+    this.closed = true;
+    this._onClose(this);
+  }
+}

package/src/provider.js

@@ -0,0 +1,145 @@
+/**
+ * @file provider.js
+ * @description Reticulum provider for Yjs.
+ *
+ * Wraps a {@link Y.Doc} and synchronizes it with peers discovered over the
+ * Reticulum mesh. Each provider owns (or borrows) a {@link Reticulum} instance
+ * and a {@link Room} that announces a destination derived from the room name
+ * and maintains pairwise Links to peers.
+ *
+ * Phase 2 (this file) implements the connection lifecycle and peer mesh:
+ * announcing, discovery and `peers` events. Yjs sync/awareness over those Links
+ * lands in Phase 3.
+ */
+
+import { Identity } from "@reticulum/core";
+import { ObservableV2 } from "lib0/observable";
+import * as awarenessProtocol from "y-protocols/awareness";
+import * as Y from "yjs";
+import { roomDestinationName } from "./destination.js";
+import { Room } from "./room.js";
+
+/**
+ * Options accepted by {@link ReticulumProvider}.
+ *
+ * @typedef {Object} ProviderOptions
+ * @property {import("@reticulum/core").Reticulum} reticulum
+ *   A configured Reticulum instance with at least one (default) interface
+ *   attached. The provider does not open interfaces itself.
+ * @property {import("@reticulum/core").Identity} [identity]
+ *   Identity for this peer's room destination. Generated (non-persistent) if
+ *   omitted; supply your own to keep a stable address across restarts.
+ * @property {awarenessProtocol.Awareness} [awareness]
+ *   Reuse an existing Awareness instance. A fresh one is created when omitted.
+ * @property {number} [maxConns]
+ *   Upper bound on simultaneous peer Links. Mirrors y-webrtc's `maxConns`.
+ * @property {number} [announceIntervalMs]
+ *   Cadence (ms) at which the room destination is re-announced for discovery.
+ *   Forwarded to `Destination.startAnnouncing`, which clamps it to the
+ *   §9.7 60 s floor (sub-minute intervals trigger ingress rate limiting).
+ */
+
+/**
+ * Events emitted by {@link ReticulumProvider}. Mirrors the y-webrtc event
+ * surface so consumers can switch providers with minimal changes.
+ *
+ * @typedef {Object} ReticulumProviderEvents
+ * @property {(event: { connected: boolean }) => void} status
+ *   Fired when the provider (dis)connects from the mesh.
+ * @property {(event: { synced: boolean }) => void} synced
+ *   Fired when sync state with the peer mesh changes. (Phase 3.)
+ * @property {(event: { added: Array<string>, removed: Array<string> }) => void} peers
+ *   Fired when peers are discovered or drop off.
+ */
+
+/**
+ * Reticulum provider for Yjs.
+ *
+ * @extends {ObservableV2<ReticulumProviderEvents>}
+ */
+export class ReticulumProvider extends ObservableV2 {
+  /**
+   * @param {string} roomName
+   * @param {Y.Doc} doc
+   * @param {ProviderOptions} opts
+   */
+  constructor(roomName, doc, opts) {
+    super();
+    if (!opts || !opts.reticulum) {
+      throw new Error("ReticulumProvider requires a `reticulum` instance.");
+    }
+    this.roomName = roomName;
+    this.doc = doc;
+    this.reticulum = opts.reticulum;
+    /** @type {awarenessProtocol.Awareness} */
+    this.awareness = opts.awareness ?? new awarenessProtocol.Awareness(doc);
+    this.maxConns = opts.maxConns ?? 20;
+    this.announceIntervalMs = opts.announceIntervalMs ?? 60_000;
+
+    /** Resolved with the room destination's identity on connect(). */
+    this.identityPromise = opts.identity
+      ? Promise.resolve(opts.identity)
+      : Identity.generate();
+    /** @type {Identity|null} */
+    this.identity = opts.identity ?? null;
+
+    /** @type {Room|null} */
+    this.room = null;
+    this.shouldConnect = false;
+  }
+
+  /**
+   * Whether the provider is announcing and accepting peer Links. Does not imply
+   * that any peer is reachable; only that we are looking.
+   *
+   * @type {boolean}
+   */
+  get connected() {
+    return this.room !== null && this.shouldConnect;
+  }
+
+  /** Begin announcing and maintaining the peer mesh. */
+  async connect() {
+    if (this.shouldConnect) return;
+    this.shouldConnect = true;
+    this.identity ??= await this.identityPromise;
+
+    const appName = await roomDestinationName(this.roomName);
+    this.room = new Room({
+      doc: this.doc,
+      awareness: this.awareness,
+      reticulum: this.reticulum,
+      identity: /** @type {Identity} */ (this.identity),
+      appName,
+      maxConns: this.maxConns,
+      announceIntervalMs: this.announceIntervalMs,
+      callbacks: {
+        onPeers: (
+          /** @type {string[]} */ added,
+          /** @type {string[]} */ removed,
+        ) => this.emit("peers", [{ added, removed }]),
+        onSynced: (/** @type {boolean} */ synced) =>
+          this.emit("synced", [{ synced }]),
+      },
+    });
+    await this.room.connect();
+    this.emit("status", [{ connected: true }]);
+  }
+
+  /** Stop announcing, tear down all peer Links, and release the destination. */
+  async disconnect() {
+    if (!this.shouldConnect) return;
+    this.shouldConnect = false;
+    if (this.room) {
+      await this.room.disconnect();
+      this.room = null;
+    }
+    this.emit("status", [{ connected: false }]);
+  }
+
+  /** Permanently release all resources. */
+  async destroy() {
+    await this.disconnect();
+    super.destroy();
+  }
+}