@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/lib/types/http/routes.js

@@ -0,0 +1,323 @@
+import { DataSheetError } from "../errors.js";
+import { WorkbookRevisionConflictError } from "../workbook-manager.js";
+import { parseIndex } from "../request-params.js";
+/**
+ * Describe a failed route, naming the path that failed.
+ *
+ * @param where - The path or prefix being served.
+ * @param error - Whatever was thrown.
+ * @returns a message a person can act on.
+ */
+function described(where, error) {
+    return `${where} 处理失败：${error instanceof Error ? error.message : String(error)}`;
+}
+export function routeFor(routes, pathname) {
+    return routes.find(route => route.kind === 'exact' && route.path === pathname)
+        ?? routes
+            .filter(route => route.kind === 'prefix' && (pathname === route.path || pathname.startsWith(`${route.path}/`)))
+            .sort((left, right) => right.path.length - left.path.length)[0];
+}
+/** Adapt the HTTP handlers to the official Electron shell's Connection carrier. */
+export async function dispatchConnectionRoute(routes, request, prefix) {
+    const carrierUrl = new URL(request.url);
+    const rawPath = carrierUrl.searchParams.get('path');
+    if (rawPath === null || !rawPath.startsWith(`${prefix}/`))
+        return new Response('not found', { status: 404 });
+    const target = new URL(rawPath, 'http://dsh.invalid');
+    const route = routeFor(routes, target.pathname);
+    if (route === undefined)
+        return new Response('not found', { status: 404 });
+    const body = request.body === null ? undefined : Buffer.from(await request.arrayBuffer());
+    let started = false;
+    let status = 200;
+    let headers = {};
+    let start;
+    const startedPromise = new Promise(resolve => { start = resolve; });
+    let streamController;
+    let closeListener;
+    const begin = (nextStatus = 200, nextHeaders) => {
+        if (started)
+            return;
+        started = true;
+        status = nextStatus;
+        headers = nextHeaders ?? {};
+        start();
+    };
+    const response = {
+        writeHead(nextStatus, nextHeaders = {}) { begin(nextStatus, nextHeaders); },
+        write(chunk) {
+            begin();
+            try {
+                streamController?.enqueue(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+            }
+            catch {
+                return false;
+            }
+            return (streamController?.desiredSize ?? 1) > 0;
+        },
+        end(chunk) {
+            begin();
+            try {
+                if (chunk !== undefined)
+                    streamController?.enqueue(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+                streamController?.close();
+            }
+            catch { /* the browser cancelled the stream */ }
+        },
+        once(_event, listener) { closeListener = listener; },
+        on() { },
+        destroy() { closeListener?.(); try {
+            streamController?.close();
+        }
+        catch { /* already closed */ } },
+    };
+    const nodeHeaders = Object.fromEntries(request.headers);
+    nodeHeaders.host ??= '127.0.0.1';
+    const nodeRequest = {
+        method: request.method,
+        url: `${target.pathname}${target.search}`,
+        headers: nodeHeaders,
+        socket: { localAddress: '127.0.0.1' },
+        async *[Symbol.asyncIterator]() {
+            if (body !== undefined && body.byteLength > 0)
+                yield body;
+        },
+    };
+    const stream = new ReadableStream({
+        start(controller) {
+            streamController = controller;
+            void route.handler(nodeRequest, response).catch(error => {
+                if (!started)
+                    begin(500, { 'content-type': 'application/json; charset=utf-8' });
+                response.end(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+            });
+        },
+        cancel() { closeListener?.(); },
+    });
+    await startedPromise;
+    return new Response(stream, { status, headers });
+}
+export function registerConnectionRoutes(ctx, routes, prefix) {
+    const route = {
+        path: `/api/${prefix.slice(1).split('/', 1)[0]}`,
+        methods: ['GET', 'HEAD', 'POST'],
+        requestBody: 'buffered',
+        // A failed handler must say so. DSH's web server turns an exception into a bodyless 400,
+        // which is indistinguishable from a malformed request — the same blindness that made a
+        // missing declaration look like a broken canvas.
+        fetch: async (request) => {
+            try {
+                return await dispatchConnectionRoute(routes, request, prefix);
+            }
+            catch (error) {
+                return new Response(JSON.stringify({ error: described(prefix, error) }), {
+                    status: 500,
+                    headers: { 'content-type': 'application/json' },
+                });
+            }
+        },
+    };
+    ctx.effect(() => ctx.connection.fetch.register(route), `data-sheet: ${route.path} Connection route`);
+    const inject = ctx.inject;
+    if (typeof inject === 'function') {
+        inject.call(ctx, ['webServer'], webCtx => {
+            for (const legacyRoute of routes) {
+                // Same reason as above, on the other carrier: these are the `/data-sheet/...` URLs the
+                // browser console was reporting as bare 400s with nothing to go on.
+                const guarded = {
+                    ...legacyRoute,
+                    handler: async (req, res) => {
+                        try {
+                            await legacyRoute.handler(req, res);
+                        }
+                        catch (error) {
+                            const message = described(legacyRoute.path, error);
+                            console.warn(`[data-sheet] ${message}`);
+                            if (!res.headersSent) {
+                                res.writeHead(500, { 'content-type': 'application/json' });
+                                res.end(JSON.stringify({ error: message }));
+                            }
+                            else {
+                                res.end();
+                            }
+                        }
+                    },
+                };
+                webCtx.effect(() => webCtx.webServer.register(guarded), `data-sheet: ${legacyRoute.path} web route`);
+            }
+        });
+    }
+}
+export async function readJsonBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += buffer.length;
+        // Snapshot limits are 25 MiB; leave a small envelope margin while still
+        // allowing a legitimate checkpoint to reach the Host without a browser
+        // side `Failed to fetch` caused by an undersized request parser.
+        if (size > 32 * 1024 * 1024)
+            throw new DataSheetError('PAYLOAD_TOO_LARGE', 'request body too large', 413);
+        chunks.push(buffer);
+    }
+    const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw new Error('body must be an object');
+    return parsed;
+}
+/**
+ * Keep plugin routes behind the same browser-origin fence as the Host API.
+ * Loopback is allowed by default; non-loopback authorities must be explicitly
+ * listed in DSH_TRUSTED_HOSTS or match the local listening address.
+ */
+export function guardDataSheetRequest(req, res) {
+    const hostHeader = typeof req.headers.host === 'string' ? req.headers.host.trim().toLowerCase() : '';
+    if (hostHeader.length === 0) {
+        res.writeHead(403, { 'content-type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ ok: false, error: '缺少 Host' }));
+        return false;
+    }
+    let hostUrl;
+    try {
+        hostUrl = new URL(`http://${hostHeader}`);
+    }
+    catch {
+        res.writeHead(403, { 'content-type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ ok: false, error: 'Host 无效' }));
+        return false;
+    }
+    const hostname = hostUrl.hostname.toLowerCase();
+    const localAddress = (req.socket.localAddress ?? '').replace(/^::ffff:/, '').toLowerCase();
+    const loopback = hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'
+        || hostname === '[::1]';
+    const trusted = new Set((process.env.DSH_TRUSTED_HOSTS ?? '').split(',').map(item => item.trim().toLowerCase()).filter(Boolean));
+    const localMatch = localAddress.length > 0 && (hostname === localAddress || (localAddress === '::1' && hostname === 'localhost'));
+    if (!loopback && !localMatch && !trusted.has(hostHeader) && !trusted.has(hostname)) {
+        res.writeHead(403, { 'content-type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ ok: false, error: '请求 authority 不在信任范围内' }));
+        return false;
+    }
+    const fetchSite = req.headers['sec-fetch-site'];
+    if (fetchSite === 'cross-site') {
+        res.writeHead(403, { 'content-type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({ ok: false, error: '拒绝跨站请求' }));
+        return false;
+    }
+    const origin = typeof req.headers.origin === 'string' ? req.headers.origin : undefined;
+    if (origin !== undefined) {
+        try {
+            if (new URL(origin).host.toLowerCase() !== hostUrl.host.toLowerCase())
+                throw new Error('origin mismatch');
+        }
+        catch {
+            res.writeHead(403, { 'content-type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify({ ok: false, error: 'Origin 不匹配' }));
+            return false;
+        }
+    }
+    return true;
+}
+/** Resolve the per-tab session used to scope isolated worktrees. EventSource
+ * cannot send custom headers, so collaboration clients may provide `session`
+ * as a query parameter; normal fetch clients use the header. */
+export function requireDataSheetSession(req, res, url) {
+    const header = typeof req.headers['x-data-sheet-session'] === 'string' ? req.headers['x-data-sheet-session'] : '';
+    const query = url.searchParams.get('session') ?? '';
+    const value = (header || query).trim();
+    if (value.length === 0 || value.length > 256) {
+        writeOperationError(res, new DataSheetError('SESSION_SCOPE_DENIED', '缺少有效的 data-sheet session', 403));
+        return null;
+    }
+    return value;
+}
+export function writeOperationError(res, error) {
+    if (error instanceof WorkbookRevisionConflictError) {
+        res.writeHead(409, { 'content-type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify({
+            ok: false,
+            code: 'REVISION_CONFLICT',
+            error: error.message,
+            // Compatible legacy fields plus the unified cross-plugin body (PRD §5.1).
+            expectedRevision: error.expected,
+            revision: error.actual,
+            conflict: error.payload,
+        }));
+        return;
+    }
+    const dataSheetError = error instanceof DataSheetError ? error : null;
+    const status = dataSheetError?.status ?? 400;
+    const code = dataSheetError?.code ?? 'VALIDATION_ERROR';
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ ok: false, code, error: error instanceof Error ? error.message : String(error), ...(dataSheetError?.details ?? {}) }));
+}
+/**
+ * The `?after=` revision cursor.
+ *
+ * An absent (or blank) cursor means "from the beginning", which is a real value,
+ * not an error. Anything else has to parse — this used to swallow every failure
+ * into `0`, so `?after=abc` did not fail, it silently replayed the *entire*
+ * operation log at the asking client. A malformed cursor is now a 400 like any
+ * other bad parameter, which is what the surrounding handlers already do.
+ */
+export function parseRevision(value) {
+    const trimmed = value?.trim() ?? '';
+    if (trimmed.length === 0)
+        return 0;
+    // Decimal digits only. `Number()` would also accept `0x10` (16), `1e3` (1000)
+    // and `5.0` (5) — a cursor is a revision number, and accepting a spelling
+    // nobody writes is how a typo turns into a plausible-looking revision.
+    if (!/^\d+$/.test(trimmed))
+        throw new Error('after 必须是大于等于 0 的整数');
+    return parseIndex(Number(trimmed), 'after');
+}
+/**
+ * Matching for one workbook path.
+ *
+ * The id segment is `[^/]+` rather than an ASCII class: a workbook's id is now its
+ * file name (`yyyymmdd-中文名`, see `storageNameOf` in `#contracts`),
+ * and the browser percent-encodes it into the path. Spelling the character set out
+ * here would be a second copy of `storageSegment`'s rule — one that silently 404s a
+ * name the store happily created. What keeps a path inside the store is not this
+ * regex but the store itself: every path builder in `store/paths.ts` runs the id
+ * through `normalizeWorkbookId` before it becomes a file name.
+ */
+const WORKBOOK_PATH = /^\/data-sheet\/workbook\/([^/]+?)(?:\.json)?(?:\/(.*))?$/;
+const PLAIN_ROUTES = {
+    changes: 'changes', collaboration: 'collaboration', history: 'history',
+    'history/diff': 'history-diff', range: 'range', presence: 'presence', operations: 'operation',
+    view: 'view', proposals: 'proposals', rollback: 'rollback', worktrees: 'worktrees',
+};
+/** Match one workbook path; null when nothing here claims it. */
+export function matchWorkbookRoute(pathname) {
+    const match = WORKBOOK_PATH.exec(pathname);
+    if (match === null)
+        return null;
+    const id = match[1];
+    const rest = match[2];
+    if (rest === undefined)
+        return { kind: 'snapshot', id };
+    const plain = PLAIN_ROUTES[rest];
+    if (plain !== undefined)
+        return { kind: plain, id };
+    // Same `[^/]+` id segment as the workbook path above: worktree and proposal ids
+    // are minted from the workbook's, so they inherit its character set.
+    const proposalAction = /^proposals\/([^/]+)\/(commit|reject)$/.exec(rest);
+    if (proposalAction !== null) {
+        return { kind: 'proposal-action', id, proposalId: proposalAction[1], action: proposalAction[2] };
+    }
+    const worktreeAction = /^worktrees\/([^/]+)\/(ready|reopen|merge|discard)$/.exec(rest);
+    if (worktreeAction !== null) {
+        return { kind: 'worktree-action', id, worktreeId: worktreeAction[1], action: worktreeAction[2] };
+    }
+    const worktreeChild = /^worktrees\/([^/]+)(?:\/(operations|diff))?$/.exec(rest);
+    if (worktreeChild !== null) {
+        const worktreeId = worktreeChild[1];
+        if (worktreeChild[2] === 'operations')
+            return { kind: 'worktree-operations', id, worktreeId };
+        if (worktreeChild[2] === 'diff')
+            return { kind: 'worktree-diff', id, worktreeId };
+        return { kind: 'worktree', id, worktreeId };
+    }
+    return null;
+}

package/lib/types/http/standalone.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The standalone workbook viewer (docs/issue/0022 P3).
+ *
+ * One workbook, no shell: the panel can hand a workbook to a plain page, which
+ * is why this HTML is assembled on the server and served as `…/view`.
+ */
+export declare function escapeHtml(value: string): string;
+/** Minimal same-origin shell; the React page bundle owns the workbook UI. */
+export declare function standaloneWorkbookHtml(title: string): string;

package/lib/types/http/standalone.js

@@ -0,0 +1,31 @@
+/**
+ * The standalone workbook viewer (docs/issue/0022 P3).
+ *
+ * One workbook, no shell: the panel can hand a workbook to a plain page, which
+ * is why this HTML is assembled on the server and served as `…/view`.
+ */
+export function escapeHtml(value) {
+    return value.replace(/[&<>'"]/g, character => ({
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        "'": '&#39;',
+        '"': '&quot;',
+    })[character] ?? character);
+}
+/** Minimal same-origin shell; the React page bundle owns the workbook UI. */
+export function standaloneWorkbookHtml(title) {
+    const safeTitle = escapeHtml(title);
+    return `<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>${safeTitle} - Table</title>
+  </head>
+  <body>
+    <div id="data-sheet-workbook-root"></div>
+    <script src="/data-sheet/workbook-page.js"></script>
+  </body>
+</html>`;
+}

package/lib/types/http/trunk.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The workbook's own routes (docs/issue/0022 P3).
+ *
+ * Snapshot read/write, the incremental `changes` cursor, one bounded range read,
+ * the operation append, proposals and rollback — everything a browser or another
+ * plugin uses to read and write the trunk workbook.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type WorkbookRoute } from './routes.ts';
+export declare function handleTrunkRoute(route: WorkbookRoute, req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;