@vcp-dev/site-edit-bridge 0.6.3 → 0.6.4

package/dist/mutation-session-queue.js

@@ -0,0 +1,18 @@
+/**
+ * Serializes the complete Bridge mutation boundary for one preview server.
+ *
+ * The queue deliberately covers assertion verification, durable-history session
+ * binding and the Engine mutation itself. Serializing only history-store open is
+ * insufficient because another session can replace/dispose the active runtime
+ * between bind and execute.
+ */
+export class SiteEditBridgeMutationQueue {
+    constructor() {
+        this.tail = Promise.resolve();
+    }
+    run(operation) {
+        const result = this.tail.then(operation, operation);
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}

package/dist/protocol.js

@@ -0,0 +1,419 @@
+import { encodeRenderDocument, } from "./document-codec.js";
+export class SiteEditBridgeTransport {
+    constructor() { }
+    static parseMessage(raw, options = {}) {
+        const parsed = JSON.parse(raw);
+        if (!SiteEditBridgeTransport.isMessage(parsed, options)) {
+            throw new Error("Invalid site edit bridge message");
+        }
+        return parsed;
+    }
+    static stringifyMessage(message) {
+        return JSON.stringify(message);
+    }
+    static extractRequestInfo(message) {
+        if (typeof message === "object" &&
+            message !== null &&
+            "payload" in message &&
+            typeof message.payload === "object" &&
+            message.payload !== null) {
+            const payload = message.payload;
+            const id = typeof payload.id === "string" ? payload.id : "unknown";
+            const kind = SiteEditBridgeTransport.isRequestKind(payload.kind)
+                ? payload.kind
+                : "get-document";
+            return { id, kind };
+        }
+        return { id: "unknown", kind: "get-document" };
+    }
+    static isRequestKind(value) {
+        return (value === "initialize-session" ||
+            value === "get-document" ||
+            value === "get-history-status" ||
+            value === "get-style-context" ||
+            value === "get-object-edit-context" ||
+            value === "get-class-name-source" ||
+            value === "get-source-tree" ||
+            value === "get-source-file" ||
+            value === "resolve-source-location" ||
+            value === "execute" ||
+            value === "undo" ||
+            value === "redo");
+    }
+    static isMessage(value, options = {}) {
+        if (!isRecord(value) || typeof value.type !== "string") {
+            return false;
+        }
+        if (value.type === "request") {
+            return SiteEditBridgeTransport.isRequestPayload(value.payload, options);
+        }
+        if (value.type === "response" || value.type === "error") {
+            return isRecord(value.payload) && typeof value.payload.id === "string";
+        }
+        if (value.type === "event") {
+            return isRecord(value.payload) && isRecord(value.payload.event);
+        }
+        if (value.type === "auth") {
+            return isRecord(value.payload) && typeof value.payload.key === "string";
+        }
+        if (value.type === "auth-ok") {
+            return isRecord(value.payload) && value.payload.ok === true;
+        }
+        return false;
+    }
+    static isRequestPayload(payload, options = {}) {
+        if (!isRecord(payload) ||
+            typeof payload.id !== "string" ||
+            !SiteEditBridgeTransport.isRequestKind(payload.kind)) {
+            return false;
+        }
+        switch (payload.kind) {
+            case "initialize-session":
+                return (typeof payload.routeId === "string" &&
+                    (payload.mutationContext === undefined ||
+                        isValidMutationContext(payload.mutationContext)));
+            case "get-document":
+            case "get-style-context":
+                return typeof payload.routeId === "string";
+            case "get-object-edit-context":
+            case "get-class-name-source":
+            case "resolve-source-location":
+                return (typeof payload.key === "string" &&
+                    (payload.routeId === undefined || typeof payload.routeId === "string"));
+            case "get-history-status":
+                return payload.mutationContext === undefined;
+            case "get-source-tree":
+                return true;
+            case "get-source-file":
+                return typeof payload.path === "string";
+            case "execute":
+                return (isOperationRequestLike(payload.request) &&
+                    (payload.request.mutationContext === undefined ||
+                        isValidMutationContext(payload.request.mutationContext)) &&
+                    (options.validateOperationRequest?.(payload.request) ?? true));
+            case "undo":
+            case "redo":
+                return (payload.mutationContext === undefined ||
+                    isValidMutationContext(payload.mutationContext));
+        }
+    }
+}
+export class SiteEditBridgeSocketServer {
+    constructor(options) {
+        this.options = options;
+        this.messageQueue = new SerializedSiteEditMessageQueue();
+        this.eventDispatcher = new BufferedSiteEditEventDispatcher((message) => {
+            this.sendJson(message);
+        });
+        this.unsubscribe = options.engine.subscribe((event) => {
+            this.eventDispatcher.push(event);
+        });
+        options.socket.onmessage = (event) => {
+            try {
+                void this.messageQueue.enqueue(() => this.handleRawMessage(event.data));
+            }
+            catch (error) {
+                this.sendJson({
+                    type: "error",
+                    payload: {
+                        id: "unknown",
+                        kind: "get-document",
+                        message: error instanceof Error ? error.message : "Bridge queue overflow",
+                    },
+                });
+                options.socket.close(1013, "bridge busy");
+            }
+        };
+        options.socket.onclose = () => {
+            this.unsubscribe();
+        };
+    }
+    async handleMessage(message) {
+        try {
+            const parsed = message;
+            if (parsed.type !== "request") {
+                return;
+            }
+            const payload = parsed.payload;
+            const { id } = payload;
+            switch (payload.kind) {
+                case "initialize-session": {
+                    const result = await this.options.engine.initializeSession({
+                        routeId: payload.routeId,
+                        ...(payload.mutationContext
+                            ? { mutationContext: payload.mutationContext }
+                            : {}),
+                    });
+                    this.sendJson({
+                        type: "response",
+                        payload: {
+                            id,
+                            kind: payload.kind,
+                            result: {
+                                ok: true,
+                                data: {
+                                    document: encodeRenderDocument(result.data.document),
+                                    historyStatus: result.data.historyStatus,
+                                },
+                            },
+                        },
+                    });
+                    return;
+                }
+                case "get-document":
+                    this.sendJson({
+                        type: "response",
+                        payload: {
+                            id,
+                            kind: payload.kind,
+                            result: {
+                                ok: true,
+                                data: encodeRenderDocument((await this.options.engine.getDocument(payload.routeId)).data),
+                            },
+                        },
+                    });
+                    return;
+                case "get-history-status":
+                    this.sendJson({
+                        type: "response",
+                        payload: {
+                            id,
+                            kind: payload.kind,
+                            result: await this.options.engine.getHistoryStatus(),
+                        },
+                    });
+                    return;
+                case "get-style-context":
+                    this.sendJson({
+                        type: "response",
+                        payload: {
+                            id,
+                            kind: payload.kind,
+                            result: await this.options.engine.getStyleContext(payload.routeId),
+                        },
+                    });
+                    return;
+                case "get-object-edit-context":
+                    this.sendJson({
+                        type: "response",
+                        payload: {
+                            id,
+                            kind: payload.kind,
+                            result: await this.options.engine.getObjectEditContext(payload.key, payload.routeId),
+                        },
+                    });
+                    return;
+                case "get-class-name-source":
+                    this.sendJson({
+                        type: "response",
+                        payload: {
+                            id,
+                            kind: payload.kind,
+                            result: await this.options.engine.getClassNameSource(payload.key, payload.routeId),
+                        },
+                    });
+                    return;
+                case "get-source-tree":
+                    this.sendJson({
+                        type: "response",
+                        payload: {
+                            id,
+                            kind: payload.kind,
+                            result: await this.options.engine.getSourceTree(),
+                        },
+                    });
+                    return;
+                case "get-source-file":
+                    this.sendJson({
+                        type: "response",
+                        payload: {
+                            id,
+                            kind: payload.kind,
+                            result: await this.options.engine.getSourceFile({
+                                path: payload.path,
+                            }),
+                        },
+                    });
+                    return;
+                case "resolve-source-location":
+                    this.sendJson({
+                        type: "response",
+                        payload: {
+                            id,
+                            kind: payload.kind,
+                            result: await this.options.engine.resolveSourceLocation({
+                                key: payload.key,
+                                routeId: payload.routeId,
+                            }),
+                        },
+                    });
+                    return;
+                case "execute": {
+                    await this.handleBufferedOperation(id, payload.kind, () => this.options.engine.execute(payload.request));
+                    return;
+                }
+                case "undo":
+                    await this.handleBufferedOperation(id, payload.kind, () => this.options.engine.undo());
+                    return;
+                case "redo":
+                    await this.handleBufferedOperation(id, payload.kind, () => this.options.engine.redo());
+                    return;
+            }
+        }
+        catch (error) {
+            const requestInfo = SiteEditBridgeTransport.extractRequestInfo(message);
+            this.sendJson({
+                type: "error",
+                payload: {
+                    ...requestInfo,
+                    message: getBridgeErrorMessage(error),
+                    code: getBridgeErrorCode(error),
+                },
+            });
+        }
+    }
+    async handleRawMessage(raw) {
+        try {
+            await this.handleMessage(SiteEditBridgeTransport.parseMessage(raw, {
+                validateOperationRequest: this.options.validateOperationRequest,
+            }));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Invalid websocket message";
+            const requestInfo = extractRawRequestInfo(raw);
+            this.sendJson({
+                type: "error",
+                payload: { ...requestInfo, message },
+            });
+        }
+    }
+    sendJson(message) {
+        this.options.socket.send(SiteEditBridgeTransport.stringifyMessage(message));
+    }
+    async handleBufferedOperation(id, kind, operation) {
+        this.eventDispatcher.beginBuffering();
+        try {
+            const result = await operation();
+            this.sendJson({ type: "response", payload: { id, kind, result } });
+            this.eventDispatcher.flush();
+        }
+        catch (error) {
+            this.sendJson({
+                type: "error",
+                payload: {
+                    id,
+                    kind,
+                    message: getBridgeErrorMessage(error),
+                    code: getBridgeErrorCode(error),
+                },
+            });
+            this.eventDispatcher.flush();
+        }
+    }
+}
+class BufferedSiteEditEventDispatcher {
+    constructor(send) {
+        this.send = send;
+        this.bufferedEvents = null;
+    }
+    push(event) {
+        const message = {
+            type: "event",
+            payload: { event },
+        };
+        if (this.bufferedEvents) {
+            this.bufferedEvents.push(message);
+            return;
+        }
+        this.send(message);
+    }
+    beginBuffering() {
+        this.bufferedEvents = [];
+    }
+    flush() {
+        const buffered = this.bufferedEvents ?? [];
+        this.bufferedEvents = null;
+        buffered.forEach((message) => {
+            this.send(message);
+        });
+    }
+}
+class SerializedSiteEditMessageQueue {
+    constructor(maxQueued = 64) {
+        this.maxQueued = maxQueued;
+        this.queue = Promise.resolve();
+        this.queued = 0;
+    }
+    enqueue(task) {
+        if (this.queued >= this.maxQueued) {
+            throw new Error("Bridge request queue is full");
+        }
+        this.queued += 1;
+        const run = async () => {
+            this.queued -= 1;
+            await task();
+        };
+        const next = this.queue.then(run, run);
+        this.queue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isOperationRequestLike(value) {
+    return (isRecord(value) &&
+        typeof value.id === "string" &&
+        typeof value.siteId === "string" &&
+        typeof value.baseSnapshotId === "string" &&
+        (value.routeId === undefined || typeof value.routeId === "string") &&
+        typeof value.kind === "string" &&
+        isRecord(value.target) &&
+        typeof value.documentVersion === "number" &&
+        Number.isInteger(value.documentVersion) &&
+        value.documentVersion >= 0 &&
+        isRecord(value.params));
+}
+function isValidMutationContext(value) {
+    return isMutationContextLike(value);
+}
+function getBridgeErrorCode(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === "string" && code.length > 0 ? code : undefined;
+}
+function getBridgeErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (!error || typeof error !== "object") {
+        return "Unknown websocket operation failure";
+    }
+    const message = error.message;
+    return typeof message === "string" && message.length > 0
+        ? message
+        : "Unknown websocket operation failure";
+}
+function isMutationContextLike(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (typeof value.editingSessionId === "string" &&
+        value.editingSessionId.length > 0 &&
+        typeof value.lockId === "string" &&
+        value.lockId.length > 0 &&
+        typeof value.ownerId === "string" &&
+        value.ownerId.length > 0 &&
+        typeof value.leaseAssertion === "string" &&
+        value.leaseAssertion.length > 0);
+}
+function extractRawRequestInfo(raw) {
+    try {
+        return SiteEditBridgeTransport.extractRequestInfo(JSON.parse(raw));
+    }
+    catch {
+        return { id: "unknown", kind: "get-document" };
+    }
+}

package/dist/start-next-dev-server-cli.js

@@ -0,0 +1,74 @@
+import { startSiteEditNextDevServer } from "./next-dev-server.js";
+export async function runStartNextDevServerCli(argv, dependencies = {}) {
+    const env = dependencies.env ?? process.env;
+    const input = parseInput(argv);
+    const port = readPort(input.port ?? env.PORT ?? env.VCP_PREVIEW_PORT, 3000);
+    const host = input.host ?? env.HOST ?? "0.0.0.0";
+    const projectRoot = input.projectRoot ?? (dependencies.cwd ?? process.cwd)();
+    const preview = await (dependencies.startServer ?? startSiteEditNextDevServer)({
+        host,
+        port,
+        projectRoot,
+        siteId: env.VCP_SITE_ID ?? "site_preview",
+        snapshotId: env.VCP_SNAPSHOT_ID,
+    });
+    (dependencies.log ?? console.log)(JSON.stringify({
+        status: "ready",
+        kind: "site-edit-next-dev-server",
+        projectRoot,
+        preview_url: `http://127.0.0.1:${preview.port}`,
+        bridge_path: "/__vcp/site-edit/bridge",
+        bundler: preview.bundler,
+    }, null, 2));
+    return preview;
+}
+export async function main(argv, dependencies = {}) {
+    try {
+        await runStartNextDevServerCli(argv, dependencies);
+    }
+    catch (error) {
+        (dependencies.error ?? console.error)(error);
+        (dependencies.setExitCode ?? ((exitCode) => (process.exitCode = exitCode)))(1);
+    }
+}
+export function parseInput(argv) {
+    const input = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        switch (arg) {
+            case "--host":
+                input.host = readValue(argv, (index += 1), arg);
+                break;
+            case "--port":
+                input.port = readValue(argv, (index += 1), arg);
+                break;
+            case "--project-root":
+                input.projectRoot = readValue(argv, (index += 1), arg);
+                break;
+            default:
+                throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return input;
+}
+function readValue(argv, index, optionName) {
+    const value = argv[index];
+    if (!value ||
+        (value.startsWith("-") && !(optionName === "--port" && /^-\d/.test(value)))) {
+        throw new Error(`${optionName} requires a value.`);
+    }
+    return value;
+}
+export function readPort(value, fallback) {
+    if (value === undefined || value.trim() === "") {
+        return fallback;
+    }
+    if (!/^(?:0|[1-9]\d*)$/.test(value)) {
+        throw new Error(`Invalid port: ${value}. Expected an integer from 0 to 65535.`);
+    }
+    const parsed = Number(value);
+    if (parsed > 65_535) {
+        throw new Error(`Invalid port: ${value}. Expected an integer from 0 to 65535.`);
+    }
+    return parsed;
+}

package/dist/start-next-dev-server.js

@@ -1,83 +1,3 @@
 #!/usr/bin/env node
-import { pathToFileURL } from "node:url";
-import { startSiteEditNextDevServer } from "./next-dev-server.js";
-export async function runStartNextDevServerCli(argv, dependencies = {}) {
-    const env = dependencies.env ?? process.env;
-    const input = parseInput(argv);
-    const port = readPort(input.port ?? env.PORT ?? env.VCP_PREVIEW_PORT, 3000);
-    const host = input.host ?? env.HOST ?? "0.0.0.0";
-    const projectRoot = input.projectRoot ?? (dependencies.cwd ?? process.cwd)();
-    const preview = await (dependencies.startServer ?? startSiteEditNextDevServer)({
-        host,
-        port,
-        projectRoot,
-        siteId: env.VCP_SITE_ID ?? "site_preview",
-        snapshotId: env.VCP_SNAPSHOT_ID,
-    });
-    (dependencies.log ?? console.log)(JSON.stringify({
-        status: "ready",
-        kind: "site-edit-next-dev-server",
-        projectRoot: projectRoot,
-        preview_url: `http://127.0.0.1:${preview.port}`,
-        bridge_path: "/__vcp/site-edit/bridge",
-        bundler: preview.bundler,
-    }, null, 2));
-    return preview;
-}
-export async function main(argv, dependencies = {}) {
-    try {
-        await runStartNextDevServerCli(argv, dependencies);
-    }
-    catch (error) {
-        (dependencies.error ?? console.error)(error);
-        (dependencies.setExitCode ?? ((exitCode) => (process.exitCode = exitCode)))(1);
-    }
-}
-export function parseInput(argv) {
-    const input = {};
-    for (let index = 0; index < argv.length; index += 1) {
-        const arg = argv[index];
-        switch (arg) {
-            case "--host":
-                input.host = readValue(argv, (index += 1), arg);
-                break;
-            case "--port":
-                input.port = readValue(argv, (index += 1), arg);
-                break;
-            case "--project-root":
-                input.projectRoot = readValue(argv, (index += 1), arg);
-                break;
-            default:
-                throw new Error(`Unknown option: ${arg}`);
-        }
-    }
-    return input;
-}
-function readValue(argv, index, optionName) {
-    const value = argv[index];
-    if (!value ||
-        (value.startsWith("-") && !(optionName === "--port" && /^-\d/.test(value)))) {
-        throw new Error(`${optionName} requires a value.`);
-    }
-    return value;
-}
-export function readPort(value, fallback) {
-    if (value === undefined || value.trim() === "") {
-        return fallback;
-    }
-    if (!/^(?:0|[1-9]\d*)$/.test(value)) {
-        throw new Error(`Invalid port: ${value}. Expected an integer from 0 to 65535.`);
-    }
-    const parsed = Number(value);
-    if (parsed > 65_535) {
-        throw new Error(`Invalid port: ${value}. Expected an integer from 0 to 65535.`);
-    }
-    return parsed;
-}
-function isMainModule() {
-    const entryPath = process.argv[1];
-    return Boolean(entryPath && import.meta.url === pathToFileURL(entryPath).href);
-}
-if (isMainModule()) {
-    void main(process.argv.slice(2));
-}
+import { main } from "./start-next-dev-server-cli.js";
+void main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vcp-dev/site-edit-bridge",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -74,8 +74,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@vcp-dev/contracts": "0.6.3",
-    "@vcp-dev/site-edit-engine": "0.6.3",
+    "@vcp-dev/contracts": "0.6.4",
+    "@vcp-dev/site-edit-engine": "0.6.4",
     "@types/ws": "^8.18.1",
     "ws": "^8.20.1"
   },