@vibecook/truffle 0.4.7 → 0.4.9

package/dist/create-mesh-node.d.ts

@@ -1,4 +1,44 @@
 import { NapiNode, type NapiPeerEvent } from '@vibecook/truffle-native';
+import { type TruffleNet } from './net.js';
+import { type TruffleHttp } from './http.js';
+import { type TruffleQuic } from './quic.js';
+import { type TruffleDgram } from './dgram.js';
+import { type TruffleWs } from './ws.js';
+/**
+ * A started mesh node: the full native `NapiNode` API plus protocol
+ * namespaces (RFC 021). Namespaces are attached to the same underlying
+ * instance, so every `NapiNode` method is available directly and new
+ * native methods surface automatically.
+ */
+export type MeshNode = NapiNode & {
+    /** node:net-shaped raw TCP API over the mesh (RFC 021). */
+    net: TruffleNet;
+    /**
+     * node:http interop over the mesh (RFC 021): a MeshAgent for outbound
+     * requests to peers plus `request`/`get`/`fetchText` sugar. Inbound HTTP
+     * is served by feeding `mesh.net` connections into an `http.Server` via
+     * `httpServer.emit('connection', socket)`.
+     */
+    http: TruffleHttp;
+    /**
+     * QUIC over the mesh (RFC 021): multiplexed bidirectional byte streams
+     * with no head-of-line blocking, async-iterable connections/streams.
+     */
+    quic: TruffleQuic;
+    /**
+     * node:dgram-shaped raw UDP API over the mesh (RFC 021): datagram sockets
+     * with `'message'` events and preserved datagram boundaries.
+     */
+    dgram: TruffleDgram;
+    /**
+     * WebSocket over the mesh (RFC 021): thin wrappers over the `ws` package —
+     * `ws.connect(peer, port)` for a client, `ws.createServer({ port })` for a
+     * server. Requires the optional `ws` peer dependency to be installed.
+     */
+    ws: TruffleWs;
+    /** The underlying native handle (escape hatch; the same object). */
+    native: NapiNode;
+};
 /**
  * Options for {@link createMeshNode}. RFC 017 shape — `appId` is required,
  * `deviceName` / `deviceId` are optional overrides that the underlying
@@ -36,7 +76,7 @@ export interface CreateMeshNodeOptions {
     authKey?: string;
     /** Whether this node is ephemeral (removed from tailnet on stop). */
     ephemeral?: boolean;
-    /** WebSocket listener port (0 = auto). */
+    /** WebSocket listener port. Defaults to 9417 when omitted. */
     wsPort?: number;
     /**
      * Auto-open the Tailscale auth URL in the default browser.
@@ -62,15 +102,20 @@ export interface CreateMeshNodeOptions {
  *
  * @example
  * ```ts
- * const node = await createMeshNode({
+ * const mesh = await createMeshNode({
  *   appId: 'playground',
  *   deviceName: 'alice-mbp',
  *   onPeerChange: (event) => console.log('Peer event:', event),
  * });
  *
- * const peers = await node.getPeers();
- * await node.send(peers[0].deviceId, 'chat', Buffer.from(JSON.stringify({ text: 'hello' })));
+ * const peers = await mesh.getPeers();
+ * await mesh.send(peers[0].deviceId, 'chat', Buffer.from(JSON.stringify({ text: 'hello' })));
+ *
+ * // Raw TCP over the mesh, node:net-style (RFC 021):
+ * const server = mesh.net.createServer((socket) => socket.pipe(socket));
+ * server.listen(8080);
+ * const client = mesh.net.connect({ host: 'other-machine', port: 8080 });
  * ```
  */
-export declare function createMeshNode(options: CreateMeshNodeOptions): Promise<NapiNode>;
+export declare function createMeshNode(options: CreateMeshNodeOptions): Promise<MeshNode>;
 //# sourceMappingURL=create-mesh-node.d.ts.map

package/dist/create-mesh-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-mesh-node.d.ts","sourceRoot":"","sources":["../src/create-mesh-node.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAuB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAG7F;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,qEAAqE;IACrE,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAC/C;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAuDtF"}
+{"version":3,"file":"create-mesh-node.d.ts","sourceRoot":"","sources":["../src/create-mesh-node.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAuB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAG5D;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG;IAChC,2DAA2D;IAC3D,GAAG,EAAE,UAAU,CAAC;IAChB;;;;;OAKG;IACH,IAAI,EAAE,WAAW,CAAC;IAClB;;;OAGG;IACH,IAAI,EAAE,WAAW,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,YAAY,CAAC;IACpB;;;;OAIG;IACH,EAAE,EAAE,SAAS,CAAC;IACd,oEAAoE;IACpE,MAAM,EAAE,QAAQ,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,qEAAqE;IACrE,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CAC/C;AAsBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAoFtF"}

package/dist/create-mesh-node.js

@@ -1,24 +1,29 @@
-import { execSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
 import { NapiNode } from '@vibecook/truffle-native';
+import { createNetNamespace } from './net.js';
+import { createHttpNamespace } from './http.js';
+import { createQuicNamespace } from './quic.js';
+import { createDgramNamespace } from './dgram.js';
+import { createWsNamespace } from './ws.js';
 import { resolveSidecarPath } from './sidecar.js';
 /**
  * Open a URL in the system's default browser.
  */
 function defaultOpenUrl(url) {
-    try {
-        if (process.platform === 'darwin') {
-            execSync(`open "${url}"`);
-        }
-        else if (process.platform === 'win32') {
-            execSync(`start "" "${url}"`);
-        }
-        else {
-            execSync(`xdg-open "${url}"`);
-        }
-    }
-    catch {
-        // Silently fail
-    }
+    // Only ever open http(s) URLs, and pass the URL as an argv element (never
+    // through a shell) so it cannot be interpreted as a command. The previous
+    // `execSync(`open "${url}"`)` form let shell metacharacters ($(), backticks)
+    // in the URL execute arbitrary commands.
+    if (!/^https?:\/\//i.test(url))
+        return;
+    const [cmd, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['explorer', [url]]
+            : ['xdg-open', [url]];
+    execFile(cmd, args, () => {
+        // Best-effort; ignore failures (no browser, headless environment, etc.).
+    });
 }
 /**
  * Create and start a Truffle node with sensible defaults.
@@ -29,18 +34,29 @@ function defaultOpenUrl(url) {
  *
  * @example
  * ```ts
- * const node = await createMeshNode({
+ * const mesh = await createMeshNode({
  *   appId: 'playground',
  *   deviceName: 'alice-mbp',
  *   onPeerChange: (event) => console.log('Peer event:', event),
  * });
  *
- * const peers = await node.getPeers();
- * await node.send(peers[0].deviceId, 'chat', Buffer.from(JSON.stringify({ text: 'hello' })));
+ * const peers = await mesh.getPeers();
+ * await mesh.send(peers[0].deviceId, 'chat', Buffer.from(JSON.stringify({ text: 'hello' })));
+ *
+ * // Raw TCP over the mesh, node:net-style (RFC 021):
+ * const server = mesh.net.createServer((socket) => socket.pipe(socket));
+ * server.listen(8080);
+ * const client = mesh.net.connect({ host: 'other-machine', port: 8080 });
  * ```
  */
 export async function createMeshNode(options) {
     const { appId, deviceName, deviceId, autoAuth = true, openUrl: customOpenUrl, onAuthRequired, onPeerChange, sidecarPath, stateDir, authKey, ephemeral, wsPort, } = options;
+    // Validate appId synchronously (mirrors the Rust-side rule) so a bad value
+    // fails here with a clear error instead of asynchronously across the FFI.
+    if (!/^[a-z][a-z0-9-]{1,31}$/.test(appId)) {
+        throw new Error(`[truffle] Invalid appId ${JSON.stringify(appId)}: must match ^[a-z][a-z0-9-]{1,31}$ ` +
+            `(2–32 chars; lowercase letters, digits, hyphens; must start with a letter).`);
+    }
     const resolvedSidecarPath = sidecarPath ?? resolveSidecarPath();
     const node = new NapiNode();
     // IMPORTANT: install the auth-required callback BEFORE calling `start()`.
@@ -68,11 +84,32 @@ export async function createMeshNode(options) {
         ephemeral,
         wsPort,
     };
-    await node.start(config);
+    try {
+        await node.start(config);
+    }
+    catch (err) {
+        // Best-effort cleanup so a failed start doesn't leak the spawned sidecar
+        // process. `stop()` is safe to call even if start() failed early.
+        try {
+            await node.stop();
+        }
+        catch {
+            // ignore — nothing to clean up, or already torn down
+        }
+        throw err;
+    }
     // Post-start: forward ongoing peer lifecycle events to the user callback.
     if (onPeerChange) {
         node.onPeerChange(onPeerChange);
     }
-    return node;
+    // Attach the protocol namespaces (RFC 021) to the native instance.
+    const mesh = node;
+    mesh.net = createNetNamespace(node);
+    mesh.http = createHttpNamespace(mesh.net);
+    mesh.quic = createQuicNamespace(node);
+    mesh.dgram = createDgramNamespace(node);
+    mesh.ws = createWsNamespace(mesh.net);
+    mesh.native = node;
+    return mesh;
 }
 //# sourceMappingURL=create-mesh-node.js.map

package/dist/create-mesh-node.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-mesh-node.js","sourceRoot":"","sources":["../src/create-mesh-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAA2C,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAyDlD;;GAEG;AACH,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAClC,QAAQ,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC;QAC5B,CAAC;aAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACxC,QAAQ,CAAC,aAAa,GAAG,GAAG,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,aAAa,GAAG,GAAG,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gBAAgB;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAA8B;IACjE,MAAM,EACJ,KAAK,EACL,UAAU,EACV,QAAQ,EACR,QAAQ,GAAG,IAAI,EACf,OAAO,EAAE,aAAa,EACtB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,OAAO,EACP,SAAS,EACT,MAAM,GACP,GAAG,OAAO,CAAC;IAEZ,MAAM,mBAAmB,GAAG,WAAW,IAAI,kBAAkB,EAAE,CAAC;IAEhE,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;IAE5B,0EAA0E;IAC1E,wEAAwE;IACxE,iEAAiE;IACjE,wEAAwE;IACxE,gEAAgE;IAChE,EAAE;IACF,0EAA0E;IAC1E,4DAA4D;IAC5D,IAAI,CAAC,cAAc,CAAC,CAAC,GAAW,EAAE,EAAE;QAClC,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,aAAa,IAAI,cAAc,CAAC;YAC/C,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC;QACD,cAAc,EAAE,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAmB;QAC7B,KAAK;QACL,UAAU;QACV,QAAQ;QACR,WAAW,EAAE,mBAAmB;QAChC,QAAQ;QACR,OAAO;QACP,SAAS;QACT,MAAM;KACP,CAAC;IAEF,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAEzB,0EAA0E;IAC1E,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"create-mesh-node.js","sourceRoot":"","sources":["../src/create-mesh-node.ts"],"names":[],"mappings":"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"}

package/dist/dgram.d.ts

@@ -0,0 +1,106 @@
+import { EventEmitter } from 'node:events';
+import type { NapiNode } from '@vibecook/truffle-native';
+/**
+ * Sender metadata delivered with each `'message'` event, mirroring
+ * node:dgram's `RemoteInfo` and extending it with mesh peer identity.
+ *
+ * `address`/`port` are the datagram's WireGuard-authenticated tailnet
+ * source (`100.x` IPv4). `peerId`/`peerName` are best-effort enrichments
+ * resolved from the local netmap — they may be `undefined` for a sender
+ * that isn't a known peer yet, and message delivery never blocks on them.
+ */
+export interface TruffleRemoteInfo {
+    /** Sender's tailnet IP (`100.x.x.x`). */
+    address: string;
+    /** Sender's source port. */
+    port: number;
+    /** Always `'IPv4'`: datagram addressing is IPv4-only in v1 (RFC 021 §3). */
+    family: 'IPv4';
+    /** Datagram payload length in bytes. */
+    size: number;
+    /** Sender's stable device id, when the source IP maps to a known peer. */
+    peerId?: string;
+    /** Sender's human-readable device name, when known. */
+    peerName?: string;
+}
+/**
+ * A UDP socket over the mesh, mimicking `dgram.Socket`.
+ *
+ * Events:
+ * - `'listening'` — after {@link bind} resolves; `this.port` is set.
+ * - `'message'` — `(msg: Buffer, rinfo: TruffleRemoteInfo)` per datagram.
+ * - `'error'` — a terminal receive error, or a {@link send} failure with no
+ *   callback (node:dgram contract).
+ * - `'close'` — the socket has shut down (via {@link close} or a closed
+ *   relay); fires exactly once.
+ *
+ * ```ts
+ * const sock = mesh.dgram.createSocket();
+ * sock.on('message', (msg, rinfo) => {
+ *   console.log(`${rinfo.peerName ?? rinfo.address}: ${msg}`);
+ * });
+ * await sock.bind(8081);
+ * sock.send(Buffer.from('ping'), 8081, 'other-machine');
+ * ```
+ */
+export declare class TruffleDgramSocket extends EventEmitter {
+    #private;
+    /**
+     * The mesh port this socket is bound to; `0` until {@link bind} resolves.
+     * Note it reflects the *requested* tsnet port — an ephemeral client
+     * socket bound with port `0` keeps `0` here (its real relay port isn't
+     * surfaced), so read `port` only after `'listening'` and only when you
+     * bound an explicit port.
+     */
+    port: number;
+    constructor(node: NapiNode);
+    /**
+     * Bind the socket to `port` (default `0` = ephemeral relay port) and start
+     * receiving. Resolves with the socket once bound; `'listening'` fires at
+     * the same point, and `callback` (if given) is invoked as a one-shot
+     * `'listening'` listener — so both `await sock.bind(port)` and
+     * `sock.bind(port, () => …)` work.
+     *
+     * Deviates from node:dgram, which returns the socket synchronously and
+     * signals readiness only via the event; here bind is genuinely async
+     * (it round-trips to the sidecar), so the promise is the primary channel.
+     * Failure semantics follow the calling style: promise style (`await
+     * sock.bind(p)`) **rejects**; callback style (`sock.bind(p, cb)`,
+     * typically fire-and-forget) emits **`'error'`** like node:dgram and
+     * never leaves an unhandled rejection.
+     */
+    bind(port?: number, callback?: () => void): Promise<this>;
+    /**
+     * Send a datagram to `address:port`. `address` accepts any peer reference
+     * (device id or ≥4-char prefix, device name, Tailscale hostname, or `100.x`
+     * IP), matching node:dgram's `(msg, port, address, callback?)` arg order.
+     *
+     * Must be called after {@link bind}: unlike node:dgram this does **not**
+     * auto-bind (that would silently pick an ephemeral port), so sending before
+     * bind throws synchronously. Async send failures go to `callback` if given,
+     * otherwise the `'error'` event (node:dgram contract).
+     */
+    send(msg: Buffer | string | Uint8Array, port: number, address: string, callback?: (error: Error | null) => void): void;
+    /**
+     * Close the socket. In-flight `recv()` resolves `null`, ending the receive
+     * pump and emitting `'close'` once. Idempotent; `callback` (if given) runs
+     * on `'close'`, even if the socket has already closed.
+     */
+    close(callback?: () => void): void;
+    /**
+     * node:dgram `address()` compat. Mesh sockets have no local IP, so
+     * `address` is empty; `port` is the bound port (see the {@link port} note).
+     */
+    address(): {
+        address: string;
+        family: 'IPv4';
+        port: number;
+    };
+}
+/** node:dgram-shaped namespace bound to a mesh node. */
+export interface TruffleDgram {
+    /** Create an unbound UDP socket, like `dgram.createSocket('udp4')`. */
+    createSocket(): TruffleDgramSocket;
+}
+export declare function createDgramNamespace(node: NapiNode): TruffleDgram;
+//# sourceMappingURL=dgram.d.ts.map

package/dist/dgram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dgram.d.ts","sourceRoot":"","sources":["../src/dgram.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAgB,QAAQ,EAAiB,MAAM,0BAA0B,CAAC;AAUtF;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;;IAYlD;;;;;;OAMG;IACH,IAAI,SAAK;gBAEG,IAAI,EAAE,QAAQ;IAK1B;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,IAAI,SAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCpD;;;;;;;;;OASG;IACH,IAAI,CACF,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,EACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GACvC,IAAI;IAaP;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI;IAkBlC;;;OAGG;IACH,OAAO,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;CAwE7D;AAED,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,YAAY,IAAI,kBAAkB,CAAC;CACpC;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,CAIjE"}

package/dist/dgram.js

@@ -0,0 +1,248 @@
+// node:dgram-shaped API over truffle's raw UDP transport (RFC 021 Phase 3).
+//
+// TruffleDgramSocket mirrors `dgram.Socket` closely enough that existing
+// node:dgram code ports by swapping the module: `createSocket()`, `bind()`,
+// `send()`, `close()`, and the `'listening'` / `'message'` / `'error'` /
+// `'close'` events all behave as a Node developer expects.
+//
+// Two deliberate deviations from node:dgram, both documented at their call
+// sites: (1) `bind()` returns a Promise<this> (node:dgram returns the socket
+// synchronously and signals readiness only via `'listening'`); the event
+// still fires, so callback-style code keeps working. (2) `send()` before
+// `bind()` throws instead of auto-binding — auto-bind would silently pick an
+// ephemeral relay port, and explicitness beats a surprise here.
+//
+// Datagram semantics are preserved by the receive pump: it awaits one
+// `recv()` at a time, so a slow `'message'` handler backpressures the read
+// loop and the relay/OS buffer drops the overflow — correct UDP behaviour
+// with bounded memory, never an unbounded in-process queue.
+import { EventEmitter } from 'node:events';
+/**
+ * Minimum spacing between `getPeers()` calls made to enrich datagram
+ * `rinfo` with peer identity. A cache miss from an unknown sender triggers
+ * at most one refresh per window, so a burst of datagrams from unmapped IPs
+ * can't turn into a `getPeers()` storm.
+ */
+const PEER_CACHE_TTL_MS = 5_000;
+/**
+ * A UDP socket over the mesh, mimicking `dgram.Socket`.
+ *
+ * Events:
+ * - `'listening'` — after {@link bind} resolves; `this.port` is set.
+ * - `'message'` — `(msg: Buffer, rinfo: TruffleRemoteInfo)` per datagram.
+ * - `'error'` — a terminal receive error, or a {@link send} failure with no
+ *   callback (node:dgram contract).
+ * - `'close'` — the socket has shut down (via {@link close} or a closed
+ *   relay); fires exactly once.
+ *
+ * ```ts
+ * const sock = mesh.dgram.createSocket();
+ * sock.on('message', (msg, rinfo) => {
+ *   console.log(`${rinfo.peerName ?? rinfo.address}: ${msg}`);
+ * });
+ * await sock.bind(8081);
+ * sock.send(Buffer.from('ping'), 8081, 'other-machine');
+ * ```
+ */
+export class TruffleDgramSocket extends EventEmitter {
+    #node;
+    #native = null;
+    #binding = false;
+    #closed = false;
+    #closeEmitted = false;
+    // Lazy ip→peer map for rinfo enrichment, rebuilt wholesale on refresh so
+    // departed peers don't linger. Refreshes are rate-limited (see below).
+    #peerCache = new Map();
+    #peerCacheRefreshedAt = 0;
+    /**
+     * The mesh port this socket is bound to; `0` until {@link bind} resolves.
+     * Note it reflects the *requested* tsnet port — an ephemeral client
+     * socket bound with port `0` keeps `0` here (its real relay port isn't
+     * surfaced), so read `port` only after `'listening'` and only when you
+     * bound an explicit port.
+     */
+    port = 0;
+    constructor(node) {
+        super();
+        this.#node = node;
+    }
+    /**
+     * Bind the socket to `port` (default `0` = ephemeral relay port) and start
+     * receiving. Resolves with the socket once bound; `'listening'` fires at
+     * the same point, and `callback` (if given) is invoked as a one-shot
+     * `'listening'` listener — so both `await sock.bind(port)` and
+     * `sock.bind(port, () => …)` work.
+     *
+     * Deviates from node:dgram, which returns the socket synchronously and
+     * signals readiness only via the event; here bind is genuinely async
+     * (it round-trips to the sidecar), so the promise is the primary channel.
+     * Failure semantics follow the calling style: promise style (`await
+     * sock.bind(p)`) **rejects**; callback style (`sock.bind(p, cb)`,
+     * typically fire-and-forget) emits **`'error'`** like node:dgram and
+     * never leaves an unhandled rejection.
+     */
+    bind(port = 0, callback) {
+        const attempt = this.#bind(port);
+        if (!callback)
+            return attempt;
+        this.once('listening', callback);
+        return attempt.catch((err) => {
+            this.removeListener('listening', callback);
+            this.emit('error', err);
+            return this;
+        });
+    }
+    async #bind(port) {
+        if (this.#closed)
+            throw new Error('dgram: socket is closed');
+        if (this.#native || this.#binding)
+            throw new Error('dgram: bind() already called');
+        this.#binding = true;
+        let native;
+        try {
+            native = await this.#node.bindUdp(port);
+        }
+        finally {
+            this.#binding = false;
+        }
+        // close() may have raced in while bindUdp was in flight; honour it and
+        // don't start the pump or announce 'listening'.
+        if (this.#closed) {
+            native.close();
+            return this;
+        }
+        this.#native = native;
+        this.port = native.port();
+        this.emit('listening');
+        void this.#recvPump(native);
+        return this;
+    }
+    /**
+     * Send a datagram to `address:port`. `address` accepts any peer reference
+     * (device id or ≥4-char prefix, device name, Tailscale hostname, or `100.x`
+     * IP), matching node:dgram's `(msg, port, address, callback?)` arg order.
+     *
+     * Must be called after {@link bind}: unlike node:dgram this does **not**
+     * auto-bind (that would silently pick an ephemeral port), so sending before
+     * bind throws synchronously. Async send failures go to `callback` if given,
+     * otherwise the `'error'` event (node:dgram contract).
+     */
+    send(msg, port, address, callback) {
+        const native = this.#native;
+        if (!native) {
+            throw new Error('dgram: call bind() before send() (auto-bind is not supported)');
+        }
+        const data = typeof msg === 'string' ? Buffer.from(msg) : Buffer.isBuffer(msg) ? msg : Buffer.from(msg);
+        native.send(data, address, port).then(() => callback?.(null), (err) => this.#failSend(err, callback));
+    }
+    /**
+     * Close the socket. In-flight `recv()` resolves `null`, ending the receive
+     * pump and emitting `'close'` once. Idempotent; `callback` (if given) runs
+     * on `'close'`, even if the socket has already closed.
+     */
+    close(callback) {
+        if (callback) {
+            if (this.#closeEmitted)
+                queueMicrotask(callback);
+            else
+                this.once('close', callback);
+        }
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const native = this.#native;
+        if (native) {
+            // recv() resolves null → the pump exits and emits 'close'.
+            native.close();
+        }
+        else {
+            // Never bound (or bind still in flight): no pump to unwind.
+            this.#emitClose();
+        }
+    }
+    /**
+     * node:dgram `address()` compat. Mesh sockets have no local IP, so
+     * `address` is empty; `port` is the bound port (see the {@link port} note).
+     */
+    address() {
+        return { address: '', family: 'IPv4', port: this.port };
+    }
+    // ─── internals ─────────────────────────────────────────────────────────
+    async #recvPump(native) {
+        try {
+            for (;;) {
+                const datagram = await native.recv();
+                if (datagram === null)
+                    break; // socket closed
+                // Enrichment may await one getPeers() on a cold-cache miss (rate-
+                // limited); it's the only place the pump awaits beyond recv itself.
+                const rinfo = await this.#rinfoFor(datagram);
+                this.emit('message', datagram.data, rinfo);
+            }
+        }
+        catch (err) {
+            // A recv error on this socket is terminal — surface it and stop (unless
+            // we're already tearing down, where the null-on-close path handles it).
+            if (!this.#closed)
+                this.emit('error', err);
+        }
+        this.#emitClose();
+    }
+    async #rinfoFor(datagram) {
+        let peer = this.#peerCache.get(datagram.address);
+        if (!peer) {
+            await this.#maybeRefreshPeerCache();
+            peer = this.#peerCache.get(datagram.address);
+        }
+        return {
+            address: datagram.address,
+            port: datagram.port,
+            family: 'IPv4',
+            size: datagram.data.length,
+            peerId: peer?.peerId,
+            peerName: peer?.peerName,
+        };
+    }
+    /**
+     * Rebuild the ip→peer cache from `getPeers()`, at most once per
+     * {@link PEER_CACHE_TTL_MS}. Best-effort: a failed lookup leaves the prior
+     * cache in place and never propagates, so enrichment never blocks or breaks
+     * message delivery. The pump is sequential, so no in-flight guard is needed.
+     */
+    async #maybeRefreshPeerCache() {
+        const now = Date.now();
+        if (now - this.#peerCacheRefreshedAt < PEER_CACHE_TTL_MS)
+            return;
+        this.#peerCacheRefreshedAt = now; // rate-limit even if the call fails
+        try {
+            const peers = await this.#node.getPeers();
+            const next = new Map();
+            for (const peer of peers) {
+                if (peer.ip)
+                    next.set(peer.ip, { peerId: peer.deviceId, peerName: peer.deviceName });
+            }
+            this.#peerCache = next;
+        }
+        catch {
+            // Enrichment is best-effort; keep the prior cache.
+        }
+    }
+    #failSend(err, callback) {
+        if (callback)
+            callback(err);
+        else
+            this.emit('error', err);
+    }
+    #emitClose() {
+        if (this.#closeEmitted)
+            return;
+        this.#closeEmitted = true;
+        this.emit('close');
+    }
+}
+export function createDgramNamespace(node) {
+    return {
+        createSocket: () => new TruffleDgramSocket(node),
+    };
+}
+//# sourceMappingURL=dgram.js.map

package/dist/dgram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dgram.js","sourceRoot":"","sources":["../src/dgram.ts"],"names":[],"mappings":"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"}

package/dist/http.d.ts

@@ -0,0 +1,57 @@
+import http from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { TruffleNet } from './net.js';
+/**
+ * An `http.Agent` that dials its connections over the mesh instead of the
+ * host network. Pass it as `{ agent }` to any `node:http` request and the
+ * request travels to the peer named by the URL hostname (or `options.host`).
+ *
+ * Connection reuse behaves exactly like the stock agent. The default
+ * `keepAlive: false` opens a fresh mesh connection per request and closes it
+ * on response end; `new MeshAgent(net, { keepAlive: true })` pools and reuses
+ * idle sockets like any http.Agent (but see the idle-reaping caveat on
+ * `TruffleSocket.setTimeout` — quiet pooled sockets aren't reaped on a timer).
+ */
+export declare class MeshAgent extends http.Agent {
+    #private;
+    constructor(net: TruffleNet, opts?: http.AgentOptions);
+    /**
+     * Called by node:http to obtain a socket for a request. Returns a mesh
+     * TruffleSocket (a `stream.Duplex`) synchronously — it connects in the
+     * background and emits `'connect'` later, which is exactly the net.Socket
+     * contract http expects. The callback form is also honoured for robustness
+     * (node uses whichever settles first, once).
+     */
+    createConnection(options: http.ClientRequestArgs, callback?: (err: Error | null, stream: Duplex) => void): Duplex;
+}
+/** node:http-shaped namespace bound to a mesh node's `net` namespace. */
+export interface TruffleHttp {
+    /**
+     * Shared MeshAgent instance. Pass as `{ agent: mesh.http.agent }` to a raw
+     * `node:http` / `node:https`-less request to route it over the mesh.
+     */
+    agent: MeshAgent;
+    /** The MeshAgent class, for constructing an agent with custom options. */
+    Agent: typeof MeshAgent;
+    /**
+     * `http.request` with the mesh agent injected. URL form:
+     * `http://<peer>:<port>/path` (Tailscale IPs work as hostnames). Device
+     * names containing spaces aren't valid URL hostnames — use the options-
+     * object form, which takes any peer reference via `host`:
+     * `mesh.http.request({ host: 'living room pi', port: 8080, path: '/x' })`.
+     * A user-supplied `agent` (including `agent: false`) wins over the default.
+     */
+    request(options: http.RequestOptions | string | URL, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
+    request(url: string | URL, options: http.RequestOptions, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
+    /** As {@link request}, but calls `req.end()` for you (http.get shape). */
+    get(options: http.RequestOptions | string | URL, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
+    get(url: string | URL, options: http.RequestOptions, callback?: (res: http.IncomingMessage) => void): http.ClientRequest;
+    /** GET a path on a peer and buffer the response body as UTF-8 text. */
+    fetchText(peer: string, port: number, path?: string): Promise<{
+        status: number;
+        headers: http.IncomingHttpHeaders;
+        body: string;
+    }>;
+}
+export declare function createHttpNamespace(net: TruffleNet): TruffleHttp;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAmBA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,qBAAa,SAAU,SAAQ,IAAI,CAAC,KAAK;;gBAG3B,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY;IAKrD;;;;;;OAMG;IACM,gBAAgB,CACvB,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAC/B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GACrD,MAAM;CAiBV;AAgBD,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB,0EAA0E;IAC1E,KAAK,EAAE,OAAO,SAAS,CAAC;IACxB;;;;;;;OAOG;IACH,OAAO,CACL,OAAO,EAAE,IAAI,CAAC,cAAc,GAAG,MAAM,GAAG,GAAG,EAC3C,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,KAAK,IAAI,GAC7C,IAAI,CAAC,aAAa,CAAC;IACtB,OAAO,CACL,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,OAAO,EAAE,IAAI,CAAC,cAAc,EAC5B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,KAAK,IAAI,GAC7C,IAAI,CAAC,aAAa,CAAC;IACtB,0EAA0E;IAC1E,GAAG,CACD,OAAO,EAAE,IAAI,CAAC,cAAc,GAAG,MAAM,GAAG,GAAG,EAC3C,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,KAAK,IAAI,GAC7C,IAAI,CAAC,aAAa,CAAC;IACtB,GAAG,CACD,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,OAAO,EAAE,IAAI,CAAC,cAAc,EAC5B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,KAAK,IAAI,GAC7C,IAAI,CAAC,aAAa,CAAC;IACtB,uEAAuE;IACvE,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,IAAI,CAAC,mBAAmB,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjF;AAeD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,WAAW,CAoFhE"}