anchordb-relay 0.2.0

package/dist/esm/mongo-bridge.js

@@ -0,0 +1,252 @@
+import { BRIDGE_PROTOCOL_VERSION, redactMongoUri, } from "anchordb";
+/** Documents per streamed frame. Large enough to be efficient, small enough to stay under limits. */
+const READ_BATCH = 200;
+class BridgeFailure extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class MongoBridge {
+    constructor(options) {
+        /** One MongoDB connection per socket, closed with it. */
+        this.sessions = new Map();
+        this.enabled = options.enabled;
+        this.loadDriver = options.driver ?? loadMongoDriver;
+        this.onLog = options.onLog ?? (() => undefined);
+    }
+    /** Attach a socket that dialled `/bridge`. */
+    join(socket, room, validRoom) {
+        if (!this.enabled) {
+            socket.close(4403, "the MongoDB bridge is disabled; start the relay with --mongo-bridge");
+            return;
+        }
+        if (!room || !validRoom(room)) {
+            socket.close(4404, "a valid room is required to use the bridge");
+            return;
+        }
+        this.onLog("bridge: client joined");
+        socket.on("message", (raw) => {
+            void this.handle(socket, String(raw));
+        });
+        socket.on("close", () => {
+            void this.release(socket);
+        });
+    }
+    async release(socket) {
+        const session = this.sessions.get(socket);
+        if (!session)
+            return;
+        this.sessions.delete(socket);
+        // The credential dies with the socket — there is nowhere else it is held.
+        await session.connection.close().catch(() => undefined);
+        this.onLog("bridge: connection closed");
+    }
+    send(socket, response) {
+        socket.send(JSON.stringify(response));
+    }
+    async handle(socket, raw) {
+        let request;
+        try {
+            request = JSON.parse(raw);
+        }
+        catch {
+            return; // not a bridge frame
+        }
+        if (!request || typeof request.id !== "string" || typeof request.op !== "string")
+            return;
+        const base = { v: BRIDGE_PROTOCOL_VERSION, id: request.id };
+        try {
+            switch (request.op) {
+                case "connect":
+                    this.send(socket, { ...base, ok: true, result: await this.connect(socket, request) });
+                    return;
+                case "read":
+                    await this.read(socket, request, base);
+                    return;
+                case "write":
+                    this.send(socket, { ...base, ok: true, result: await this.write(socket, request) });
+                    return;
+                case "disconnect":
+                    await this.release(socket);
+                    this.send(socket, { ...base, ok: true, result: { closed: true } });
+                    return;
+                default:
+                    throw new BridgeFailure("bad_request", `Unknown bridge operation "${String(request.op)}"`);
+            }
+        }
+        catch (err) {
+            const failure = err instanceof BridgeFailure
+                ? err
+                : new BridgeFailure("failed", err.message ?? "The bridge failed.");
+            this.onLog(`bridge: ${request.op} failed — ${failure.message}`);
+            this.send(socket, { ...base, ok: false, error: { code: failure.code, message: failure.message } });
+        }
+    }
+    async connect(socket, request) {
+        const uri = String(request.uri ?? "");
+        const database = String(request.database ?? "");
+        if (!uri || !database) {
+            throw new BridgeFailure("bad_request", "A connection string and a database name are required.");
+        }
+        let driver;
+        try {
+            driver = await this.loadDriver();
+        }
+        catch {
+            throw new BridgeFailure("driver_missing", "The mongodb driver is not installed. Run `npm install mongodb` where the relay runs.");
+        }
+        await this.release(socket); // one connection per socket; a second connect replaces the first
+        let connection;
+        try {
+            connection = await driver.connect(uri);
+        }
+        catch (err) {
+            // The URI is in scope here and must not reach the message.
+            throw new BridgeFailure("connect_failed", `Could not connect to ${redactMongoUri(uri)} — ${err.message}`);
+        }
+        this.sessions.set(socket, { connection, database });
+        this.onLog(`bridge: connected to ${redactMongoUri(uri)}`);
+        return {
+            database,
+            serverVersion: await connection.serverVersion(),
+            collections: await connection.listCollections(database),
+        };
+    }
+    session(socket) {
+        const session = this.sessions.get(socket);
+        if (!session)
+            throw new BridgeFailure("not_connected", "Connect to a MongoDB first.");
+        return session;
+    }
+    /** Stream a collection out as newline-delimited Extended JSON. */
+    async read(socket, request, base) {
+        const { connection, database } = this.session(socket);
+        const collection = String(request.collection ?? "");
+        if (!collection)
+            throw new BridgeFailure("bad_request", "A collection name is required.");
+        const driver = await this.loadDriver();
+        let sent = 0;
+        // Batched rather than one frame: a large collection would exceed any sane frame limit, and
+        // holding the whole thing as a single string on both sides at once is avoidable.
+        for await (const batch of connection.find(database, collection, READ_BATCH)) {
+            const chunk = batch.map((doc) => driver.stringifyEJSON(doc)).join("\n");
+            sent += batch.length;
+            this.send(socket, { ...base, ok: true, chunk, done: false, sent });
+        }
+        this.send(socket, {
+            ...base,
+            ok: true,
+            chunk: "",
+            done: true,
+            sent,
+            result: { collection, count: sent },
+        });
+    }
+    async write(socket, request) {
+        const { connection, database } = this.session(socket);
+        const collection = String(request.collection ?? "");
+        if (!collection)
+            throw new BridgeFailure("bad_request", "A collection name is required.");
+        const mode = (request.mode ?? "insert");
+        const driver = await this.loadDriver();
+        // Decoded with MongoDB's own Extended JSON codec, so an $oid becomes a real driver ObjectId
+        // rather than something that would land in the database as a string.
+        const documents = String(request.data ?? "")
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line, index) => {
+            try {
+                return driver.parseEJSON(line);
+            }
+            catch (err) {
+                throw new BridgeFailure("bad_request", `Malformed Extended JSON on line ${index + 1}: ${err.message}`);
+            }
+        });
+        if (documents.length === 0)
+            return { collection, inserted: 0, updated: 0, skipped: 0 };
+        const result = await connection.write(database, collection, documents, mode);
+        this.onLog(`bridge: wrote ${documents.length} document(s) to ${collection}`);
+        return { collection, ...result };
+    }
+}
+/**
+ * Load the real driver.
+ *
+ * A lazy import so the relay stays usable — and installable — without `mongodb`. It is an optional
+ * dependency: most people running `npx anchor-relay` only want the inspector.
+ */
+async function loadMongoDriver() {
+    // mongodb is an OPTIONAL dependency: the relay must install and run without it, and most
+    // people running the inspector never want the driver. MongoModule above types the slice used
+    // here, so absence is a runtime condition rather than a compile error.
+    // @ts-ignore -- resolved at runtime; may legitimately not be installed
+    const mongo = (await import("mongodb"));
+    const EJSON = mongo.EJSON ?? mongo.BSON?.EJSON;
+    if (!EJSON)
+        throw new Error("This mongodb driver does not expose Extended JSON.");
+    return {
+        stringifyEJSON: (value) => EJSON.stringify(value, { relaxed: false }),
+        parseEJSON: (text) => EJSON.parse(text, { relaxed: false }),
+        async connect(uri) {
+            const client = new mongo.MongoClient(uri, { serverSelectionTimeoutMS: 10_000 });
+            await client.connect();
+            return {
+                async serverVersion() {
+                    const info = (await client.db("admin").command({ buildInfo: 1 }));
+                    return info.version ?? "unknown";
+                },
+                async listCollections(database) {
+                    const db = client.db(database);
+                    const names = await db.listCollections({}, { nameOnly: true }).toArray();
+                    const out = [];
+                    for (const { name } of names) {
+                        // Estimated: instant, where an exact count is a full scan on a large collection.
+                        out.push({ name, count: await db.collection(name).estimatedDocumentCount() });
+                    }
+                    return out.sort((a, b) => a.name.localeCompare(b.name));
+                },
+                async *find(database, collection, batchSize) {
+                    const cursor = client.db(database).collection(collection).find({}, { batchSize });
+                    let batch = [];
+                    for await (const doc of cursor) {
+                        batch.push(doc);
+                        if (batch.length >= batchSize) {
+                            yield batch;
+                            batch = [];
+                        }
+                    }
+                    if (batch.length > 0)
+                        yield batch;
+                },
+                async write(database, collection, documents, mode) {
+                    const target = client.db(database).collection(collection);
+                    if (mode === "replace")
+                        await target.deleteMany({});
+                    const summary = { inserted: 0, updated: 0, skipped: 0 };
+                    const withId = documents;
+                    if (mode === "insert") {
+                        // $setOnInsert leaves an existing document untouched, which is "skip" without needing a
+                        // read first or a thrown duplicate-key error to catch.
+                        const result = await target.bulkWrite(withId.map((doc) => ({
+                            updateOne: { filter: { _id: doc._id }, update: { $setOnInsert: doc }, upsert: true },
+                        })), { ordered: false });
+                        summary.inserted = result.upsertedCount ?? 0;
+                        summary.skipped = (result.matchedCount ?? 0);
+                    }
+                    else {
+                        const result = await target.bulkWrite(withId.map((doc) => ({
+                            replaceOne: { filter: { _id: doc._id }, replacement: doc, upsert: true },
+                        })), { ordered: false });
+                        summary.inserted = result.upsertedCount ?? 0;
+                        summary.updated = result.modifiedCount ?? 0;
+                    }
+                    return summary;
+                },
+                close: () => client.close(),
+            };
+        },
+    };
+}
+//# sourceMappingURL=mongo-bridge.js.map

package/dist/esm/mongo-bridge.js.map

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

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/relay.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The Anchor Inspector Relay — development only.
+ *
+ * ## Why a relay exists at all
+ *
+ * React Native (and every browser) can open a WebSocket **client** but cannot **listen**. Neither
+ * the app being inspected nor Anchor Lens can host a server without a native TCP module, which
+ * would force an Expo dev build and rule out Expo Go entirely.
+ *
+ * So both sides dial out to this tiny Node process, which pairs them by room and copies frames
+ * across. Nothing here understands the inspector protocol — it is a dumb pipe on purpose, so the
+ * protocol can evolve without the relay ever needing an update.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * It does not authenticate the inspector session. Pairing is end-to-end between the agent and Lens
+ * (HMAC over a challenge), so a compromised or malicious relay still cannot issue itself a session.
+ * The room token here only decides *who can be connected to whom*; it is not the security boundary.
+ */
+export type RelayRole = "agent" | "client";
+export interface RelaySocket {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    on(event: "message", handler: (data: unknown) => void): void;
+    on(event: "close", handler: () => void): void;
+    on(event: "error", handler: (err: Error) => void): void;
+}
+export interface RelayOptions {
+    /** Rooms with no agent for this long are reclaimed. */
+    roomTtlMs?: number;
+    /** Frames larger than this are refused rather than forwarded. */
+    maxFrameBytes?: number;
+    onLog?: (message: string) => void;
+}
+export interface RoomInfo {
+    id: string;
+    agentName: string;
+    agentConnected: boolean;
+    clientConnected: boolean;
+    ageMs: number;
+}
+/**
+ * Transport-agnostic relay core.
+ *
+ * Kept free of any `ws` import so it can be driven by a real WebSocket server, by a test double, or
+ * by any other transport, and so the routing logic is testable without opening a port.
+ */
+export declare class InspectorRelay {
+    private readonly rooms;
+    private readonly opts;
+    constructor(options?: RelayOptions);
+    /** Create a room for an app to publish itself into. The id goes into the QR code. */
+    createRoom(agentName?: string): string;
+    /** Does this room exist? The bridge uses it as an access token. */
+    hasRoom(id: string): boolean;
+    rooms_(): RoomInfo[];
+    /**
+     * Join a socket to a room in a given role.
+     *
+     * A second socket claiming an occupied role is refused rather than replacing the incumbent:
+     * silently swapping would let anyone who learns a room id evict the real Lens mid-session.
+     */
+    join(roomId: string, role: RelayRole, socket: RelaySocket): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    closeRoom(roomId: string): void;
+    private reap;
+    /** Connection details a QR code encodes. The pairing code is NOT included — see below. */
+    connectionInfo(host: string, port: number, roomId: string): {
+        url: string;
+        room: string;
+        deepLink: string;
+    };
+}
+//# sourceMappingURL=relay.d.ts.map

package/dist/esm/relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../../src/relay.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE3C,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7D,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC9C,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;CACzD;AAUD,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyE;gBAElF,OAAO,GAAE,YAAiB;IAQtC,qFAAqF;IACrF,UAAU,CAAC,SAAS,SAAa,GAAG,MAAM;IAQ1C,mEAAmE;IACnE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAK5B,MAAM,IAAI,QAAQ,EAAE;IAWpB;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAqCxG,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ/B,OAAO,CAAC,IAAI;IAQZ,0FAA0F;IAC1F,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;QAC1D,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;KAClB;CAaF"}

package/dist/esm/relay.js

@@ -0,0 +1,113 @@
+import { randomBytes } from "node:crypto";
+/**
+ * Transport-agnostic relay core.
+ *
+ * Kept free of any `ws` import so it can be driven by a real WebSocket server, by a test double, or
+ * by any other transport, and so the routing logic is testable without opening a port.
+ */
+export class InspectorRelay {
+    constructor(options = {}) {
+        this.rooms = new Map();
+        this.opts = {
+            roomTtlMs: options.roomTtlMs ?? 30 * 60_000,
+            maxFrameBytes: options.maxFrameBytes ?? 4 * 1024 * 1024,
+            onLog: options.onLog ?? (() => undefined),
+        };
+    }
+    /** Create a room for an app to publish itself into. The id goes into the QR code. */
+    createRoom(agentName = "AnchorDB") {
+        this.reap();
+        const id = randomBytes(9).toString("base64url");
+        this.rooms.set(id, { id, agent: null, client: null, createdAt: Date.now(), agentName });
+        this.opts.onLog(`room ${id} created for "${agentName}"`);
+        return id;
+    }
+    /** Does this room exist? The bridge uses it as an access token. */
+    hasRoom(id) {
+        this.reap();
+        return this.rooms.has(id);
+    }
+    rooms_() {
+        this.reap();
+        return [...this.rooms.values()].map((r) => ({
+            id: r.id,
+            agentName: r.agentName,
+            agentConnected: r.agent !== null,
+            clientConnected: r.client !== null,
+            ageMs: Date.now() - r.createdAt,
+        }));
+    }
+    /**
+     * Join a socket to a room in a given role.
+     *
+     * A second socket claiming an occupied role is refused rather than replacing the incumbent:
+     * silently swapping would let anyone who learns a room id evict the real Lens mid-session.
+     */
+    join(roomId, role, socket) {
+        this.reap();
+        const room = this.rooms.get(roomId);
+        if (!room)
+            return { ok: false, reason: "unknown room" };
+        if (room[role])
+            return { ok: false, reason: `a ${role} is already connected to this room` };
+        room[role] = socket;
+        this.opts.onLog(`room ${roomId}: ${role} joined`);
+        socket.on("message", (data) => {
+            const frame = typeof data === "string" ? data : String(data);
+            if (frame.length > this.opts.maxFrameBytes) {
+                this.opts.onLog(`room ${roomId}: frame of ${frame.length} bytes refused`);
+                return;
+            }
+            const peer = role === "agent" ? room.client : room.agent;
+            // Frames are forwarded verbatim. The relay never parses the protocol.
+            if (peer)
+                peer.send(frame);
+        });
+        socket.on("close", () => {
+            if (room[role] === socket)
+                room[role] = null;
+            this.opts.onLog(`room ${roomId}: ${role} left`);
+            // Closing the agent ends the session for the client too — there is nothing left to inspect.
+            if (role === "agent" && room.client) {
+                room.client.close(4001, "agent disconnected");
+                room.client = null;
+            }
+        });
+        socket.on("error", () => {
+            if (room[role] === socket)
+                room[role] = null;
+        });
+        return { ok: true };
+    }
+    closeRoom(roomId) {
+        const room = this.rooms.get(roomId);
+        if (!room)
+            return;
+        room.agent?.close(4000, "room closed");
+        room.client?.close(4000, "room closed");
+        this.rooms.delete(roomId);
+    }
+    reap() {
+        const now = Date.now();
+        for (const [id, room] of this.rooms) {
+            const stale = now - room.createdAt > this.opts.roomTtlMs;
+            if (stale && !room.agent && !room.client)
+                this.rooms.delete(id);
+        }
+    }
+    /** Connection details a QR code encodes. The pairing code is NOT included — see below. */
+    connectionInfo(host, port, roomId) {
+        const url = `ws://${host}:${port}/relay?room=${roomId}&role=client`;
+        return {
+            url,
+            room: roomId,
+            /**
+             * The QR carries the relay address and room only. The pairing code is displayed separately
+             * and typed by the developer, so photographing the screen is not enough to pair — which is
+             * the whole point of keeping the code out of the QR (§51).
+             */
+            deepLink: `anchor-lens://connect?relay=${encodeURIComponent(url)}&room=${roomId}`,
+        };
+    }
+}
+//# sourceMappingURL=relay.js.map

package/dist/esm/relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../../src/relay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAwD1C;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IAIzB,YAAY,UAAwB,EAAE;QAHrB,UAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;QAI/C,IAAI,CAAC,IAAI,GAAG;YACV,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE,GAAG,MAAM;YAC3C,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;YACvD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;SAC1C,CAAC;IACJ,CAAC;IAED,qFAAqF;IACrF,UAAU,CAAC,SAAS,GAAG,UAAU;QAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAChD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QACxF,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,iBAAiB,SAAS,GAAG,CAAC,CAAC;QACzD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,mEAAmE;IACnE,OAAO,CAAC,EAAU;QAChB,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC1C,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,cAAc,EAAE,CAAC,CAAC,KAAK,KAAK,IAAI;YAChC,eAAe,EAAE,CAAC,CAAC,MAAM,KAAK,IAAI;YAClC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,SAAS;SAChC,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,MAAc,EAAE,IAAe,EAAE,MAAmB;QACvD,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QACxD,IAAI,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,oCAAoC,EAAE,CAAC;QAE5F,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,MAAM,KAAK,IAAI,SAAS,CAAC,CAAC;QAElD,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE;YAC5B,MAAM,KAAK,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC7D,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;gBAC3C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,MAAM,cAAc,KAAK,CAAC,MAAM,gBAAgB,CAAC,CAAC;gBAC1E,OAAO;YACT,CAAC;YACD,MAAM,IAAI,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;YACzD,sEAAsE;YACtE,IAAI,IAAI;gBAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACtB,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;YAC7C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,MAAM,KAAK,IAAI,OAAO,CAAC,CAAC;YAChD,4FAA4F;YAC5F,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBACpC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;gBAC9C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACrB,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACtB,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAC/C,CAAC,CAAC,CAAC;QAEH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,SAAS,CAAC,MAAc;QACtB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI;YAAE,OAAO;QAClB,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAEO,IAAI;QACV,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACpC,MAAM,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;YACzD,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,MAAM;gBAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,0FAA0F;IAC1F,cAAc,CAAC,IAAY,EAAE,IAAY,EAAE,MAAc;QAKvD,MAAM,GAAG,GAAG,QAAQ,IAAI,IAAI,IAAI,eAAe,MAAM,cAAc,CAAC;QACpE,OAAO;YACL,GAAG;YACH,IAAI,EAAE,MAAM;YACZ;;;;eAIG;YACH,QAAQ,EAAE,+BAA+B,kBAAkB,CAAC,GAAG,CAAC,SAAS,MAAM,EAAE;SAClF,CAAC;IACJ,CAAC;CACF"}

package/dist/esm/server.d.ts

@@ -0,0 +1,30 @@
+import { InspectorRelay, type RelayOptions } from "./relay.js";
+import { MongoBridge, type MongoDriver } from "./mongo-bridge.js";
+/**
+ * A runnable relay over `ws`.
+ *
+ * `ws` is loaded lazily so `InspectorRelay` itself stays dependency-free and testable without a
+ * socket library — the routing logic is the part worth testing, and it should not require a port.
+ */
+export interface RelayServerOptions extends RelayOptions {
+    port?: number;
+    host?: string;
+    /**
+     * Enable the MongoDB bridge on `/bridge`.
+     *
+     * Off by default and deliberately so: a relay that will dial any MongoDB on request lets anything
+     * that can reach the port use this machine to reach a database.
+     */
+    mongoBridge?: boolean;
+    /** Supply a driver instead of importing `mongodb` — used by the tests. */
+    mongoDriver?: () => Promise<MongoDriver>;
+}
+export interface RelayServer {
+    relay: InspectorRelay;
+    bridge: MongoBridge;
+    port: number;
+    host: string;
+    close(): Promise<void>;
+}
+export declare function startRelayServer(options?: RelayServerOptions): Promise<RelayServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/esm/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAoB,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CAoE7F"}

package/dist/esm/server.js

@@ -0,0 +1,61 @@
+import { createServer } from "node:http";
+import { InspectorRelay } from "./relay.js";
+import { MongoBridge } from "./mongo-bridge.js";
+export async function startRelayServer(options = {}) {
+    const port = options.port ?? 9440;
+    const host = options.host ?? "127.0.0.1";
+    const relay = new InspectorRelay(options);
+    const bridge = new MongoBridge({
+        enabled: options.mongoBridge ?? false,
+        ...(options.mongoDriver ? { driver: options.mongoDriver } : {}),
+        ...(options.onLog ? { onLog: options.onLog } : {}),
+    });
+    const { WebSocketServer } = (await import("ws"));
+    const http = createServer((req, res) => {
+        // A tiny control surface: create a room, list rooms, health.
+        if (req.url?.startsWith("/rooms") && req.method === "POST") {
+            const id = relay.createRoom("AnchorDB");
+            res.writeHead(200, { "content-type": "application/json" });
+            // connectionInfo already carries `room`; spreading after it would silently overwrite.
+            res.end(JSON.stringify(relay.connectionInfo(host, port, id)));
+            return;
+        }
+        if (req.url?.startsWith("/rooms") && req.method === "GET") {
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify(relay.rooms_()));
+            return;
+        }
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ ok: true, service: "anchor-inspector-relay" }));
+    });
+    const wss = new WebSocketServer({ server: http });
+    wss.on("connection", (socket, request) => {
+        const url = new URL(request.url ?? "/", `http://${host}:${port}`);
+        const room = url.searchParams.get("room");
+        const role = url.searchParams.get("role");
+        // The bridge is a separate endpoint, not a room member: the relay answers it rather than
+        // forwarding it to the app.
+        if (url.pathname === "/bridge") {
+            bridge.join(socket, room, (id) => relay.hasRoom(id));
+            return;
+        }
+        if (!room || (role !== "agent" && role !== "client")) {
+            socket.close(4400, "room and role=agent|client are required");
+            return;
+        }
+        const result = relay.join(room, role, socket);
+        if (!result.ok)
+            socket.close(4404, result.reason);
+    });
+    await new Promise((resolve) => http.listen(port, host, resolve));
+    return {
+        relay,
+        bridge,
+        port,
+        host,
+        close: () => new Promise((resolve) => {
+            wss.close(() => http.close(() => resolve()));
+        }),
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/esm/server.js.map

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

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "anchordb-relay",
+  "version": "0.2.0",
+  "description": "Development-only relay that brokers Anchor Inspector connections between a mobile app and Anchor Lens.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "anchor-relay": "./dist/esm/cli.js"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.build.cjs.json && node ../core/scripts/finalize-dist.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "check:package": "publint && attw --pack . --profile node16",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "anchordb": "^0.2.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "rimraf": "^6.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knnadeera/anchordb.git",
+    "directory": "packages/inspector-relay"
+  },
+  "homepage": "https://github.com/knnadeera/anchordb#readme",
+  "bugs": {
+    "url": "https://github.com/knnadeera/anchordb/issues"
+  },
+  "optionalDependencies": {
+    "mongodb": "^6.10.0"
+  },
+  "author": "Nisala Nadeera <knnadeera@gmail.com>"
+}