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

package/src/http/routes.ts

@@ -0,0 +1,364 @@
+/**
+ * HTTP transport for the Datasheet plugin (docs/issue/0022 P3).
+ *
+ * This module does two things and nothing else: it adapts the plugin's routes to
+ * whichever carrier is running (the DSH Connection fetch carrier, or the
+ * Electron shell's webserver), and it decides which route a
+ * `/data-sheet/workbook/...` path is. The handlers live in the domain modules
+ * beside it, so a new endpoint means one case here and one block in a handler.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import type { ConnectionFetchRoute } from '@deepseek-ai/dsh-client-connection'
+import { DataSheetError } from '../errors.ts'
+import { WorkbookRevisionConflictError } from '../workbook-manager.ts'
+import { parseIndex } from '../request-params.ts'
+
+/**
+ * Structural view of the host webserver route API (no manifest dependency).
+ *
+ * Declared here rather than in the plugin body because this is where the cast
+ * that needs it lives: `registerConnectionRoutes` registers the same handlers
+ * with both carriers.
+ */
+interface WebServerLike {
+  register(route: {
+    kind: 'exact' | 'prefix'
+    path: string
+    handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>
+  }): () => void
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    webServer: WebServerLike
+  }
+}
+
+/**
+ * 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: string, error: unknown): string {
+  return `${where} 处理失败：${error instanceof Error ? error.message : String(error)}`
+}
+
+export interface LegacyRoute {
+  readonly kind: 'exact' | 'prefix'
+  readonly path: string
+  readonly handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>
+}
+
+export interface LegacyResponse {
+  writeHead(status: number, headers?: Record<string, string>): void
+  write(chunk: string | Uint8Array): boolean
+  end(chunk?: string | Uint8Array): void
+  once(event: 'close', listener: () => void): void
+  on(event: 'drain', listener: () => void): void
+  destroy(): void
+}
+
+export function routeFor(routes: readonly LegacyRoute[], pathname: string): LegacyRoute | undefined {
+  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: readonly LegacyRoute[], request: Request, prefix: string): Promise<Response> {
+  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: Record<string, string> = {}
+  let start!: () => void
+  const startedPromise = new Promise<void>(resolve => { start = resolve })
+  let streamController: ReadableStreamDefaultController<Uint8Array> | undefined
+  let closeListener: (() => void) | undefined
+  const begin = (nextStatus = 200, nextHeaders?: Record<string, string>): void => {
+    if (started) return
+    started = true
+    status = nextStatus
+    headers = nextHeaders ?? {}
+    start()
+  }
+  const response: LegacyResponse = {
+    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() { /* node:http backpressure is not needed by the Fetch stream */ },
+    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](): AsyncGenerator<Buffer> {
+      if (body !== undefined && body.byteLength > 0) yield body
+    },
+  } as unknown as IncomingMessage
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      streamController = controller
+      void route.handler(nodeRequest, response as unknown as ServerResponse).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: Context, routes: readonly LegacyRoute[], prefix: string): void {
+  const route: ConnectionFetchRoute = {
+    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 as unknown as { inject?: (keys: readonly string[], callback: (ctx: Context) => void) => unknown }).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 = {
+          ...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 as Context & { webServer: { register(route: LegacyRoute): () => unknown } }).webServer.register(guarded), `data-sheet: ${legacyRoute.path} web route`)
+      }
+    })
+  }
+}
+
+export async function readJsonBody(req: IncomingMessage): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = []
+  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: unknown = 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 as Record<string, unknown>
+}
+
+/**
+ * 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: IncomingMessage, res: ServerResponse): boolean {
+  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: URL
+  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: IncomingMessage, res: ServerResponse, url: URL): string | null {
+  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: ServerResponse, error: unknown): void {
+  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: string | null): number {
+  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')
+}
+
+/**
+ * One matched `/data-sheet/workbook/...` path.
+ *
+ * Matching lives here, in the transport module, and dispatch lives in the domain
+ * modules: a handler can be read without working out which regexes it owns, and
+ * a new endpoint cannot silently shadow an existing one — the order of the `if`s
+ * inside a single 600-line handler used to decide that.
+ */
+export type WorkbookRoute =
+  | { kind: 'view' | 'snapshot' | 'changes' | 'collaboration' | 'history' | 'history-diff' | 'range' | 'presence' | 'operation' | 'proposals' | 'rollback' | 'worktrees'; id: string }
+  | { kind: 'proposal-action'; id: string; proposalId: string; action: 'commit' | 'reject' }
+  | { kind: 'worktree' | 'worktree-operations' | 'worktree-diff'; id: string; worktreeId: string }
+  | { kind: 'worktree-action'; id: string; worktreeId: string; action: 'ready' | 'reopen' | 'merge' | 'discard' }
+
+/**
+ * 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: Record<string, 'changes' | 'collaboration' | 'history' | 'history-diff' | 'range' | 'presence' | 'operation' | 'view' | 'proposals' | 'rollback' | 'worktrees'> = {
+  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: string): WorkbookRoute | null {
+  const match = WORKBOOK_PATH.exec(pathname)
+  if (match === null) return null
+  const id = match[1] as string
+  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] as string, action: proposalAction[2] as 'commit' | 'reject' }
+  }
+  const worktreeAction = /^worktrees\/([^/]+)\/(ready|reopen|merge|discard)$/.exec(rest)
+  if (worktreeAction !== null) {
+    return { kind: 'worktree-action', id, worktreeId: worktreeAction[1] as string, action: worktreeAction[2] as 'ready' | 'reopen' | 'merge' | 'discard' }
+  }
+  const worktreeChild = /^worktrees\/([^/]+)(?:\/(operations|diff))?$/.exec(rest)
+  if (worktreeChild !== null) {
+    const worktreeId = worktreeChild[1] as string
+    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/src/http/standalone.ts

@@ -0,0 +1,32 @@
+/**
+ * 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: string): string {
+  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: string): string {
+  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>`
+}