experimental-a2 0.3.0 → 0.5.0

package/src/devtools-server.browser.ts

@@ -0,0 +1,5 @@
+/** experimental-a2/devtools/server owns store access and is server-only. */
+throw new Error(
+  'experimental-a2/devtools/server is server-only — mount its handler in a server route and open that URL in the browser.',
+)
+export {}

package/src/devtools-server.ts

@@ -0,0 +1,604 @@
+/**
+ * experimental-a2/devtools/server — a read-only dashboard over A2's durable data.
+ * One Request handler serves the application, its private browser bundle,
+ * JSON inspection endpoints, and live SSE invalidations.
+ */
+
+import {
+  DEVTOOLS_APP_CSS,
+  DEVTOOLS_APP_JS,
+  devtoolsHtml,
+  type DevtoolsBootstrap,
+} from './devtools-app.ts'
+import {
+  DEVTOOLS_CAPABILITIES,
+  DEVTOOLS_CAPTURE_MEDIA_TYPE,
+  DEVTOOLS_PROTOCOL_VERSION,
+  DEVTOOLS_SESSION_PAGE_LIMIT,
+  DEVTOOLS_SESSION_PAGE_MAX_LIMIT,
+  devtoolsSessionRevision,
+  encodeDevtoolsCapture,
+  type DevtoolsSessionPage,
+  type DevtoolsSessionDetail,
+  type DevtoolsWireEvent,
+  type DevtoolsWireSessionSummary,
+  type DevtoolsWireSnapshot,
+} from './devtools.ts'
+import {
+  DEVTOOLS_TIMINGS,
+  InspectionUnsupportedError,
+  serverInspection,
+  type ServerInspection,
+} from './inspection.ts'
+import type {
+  StoredEvent,
+  StoredSessionSummary,
+  StoredSnapshot,
+} from './store.ts'
+
+export type DevtoolsServer = {
+  readonly contract: { readonly name: string }
+}
+
+export type DevtoolsAuthorization = (
+  request: Request,
+) => boolean | Response | Promise<boolean | Response>
+
+export type DevtoolsOptions = {
+  servers: readonly DevtoolsServer[]
+  /**
+   * Application-owned access control. Returning a Response short-circuits
+   * the request. Without this option, devtools is available only when
+   * NODE_ENV is exactly "development" and otherwise returns 404.
+   */
+  authorize?: DevtoolsAuthorization
+}
+
+export type Devtools = {
+  handler(): (request: Request) => Promise<Response>
+}
+
+const MARKER = '/_a2/'
+const encoder = new TextEncoder()
+
+type InspectionDetail = {
+  events: StoredEvent[]
+  snapshots: StoredSnapshot[]
+}
+
+const isDevelopment = (): boolean =>
+  typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'development'
+
+const headers = (contentType: string): HeadersInit => ({
+  'content-type': contentType,
+  'cache-control': 'no-store',
+  'x-content-type-options': 'nosniff',
+  'referrer-policy': 'no-referrer',
+})
+
+const json = (value: unknown, init?: ResponseInit): Response =>
+  Response.json(value, {
+    ...init,
+    headers: {
+      ...headers('application/json; charset=utf-8'),
+      ...init?.headers,
+    },
+  })
+
+const notFound = (): Response =>
+  new Response('Not found', { status: 404, headers: headers('text/plain') })
+
+const badRequest = (message: string): Response =>
+  json({ error: message }, { status: 400 })
+
+const unavailable = (message: string): Response =>
+  json({ error: message }, { status: 501 })
+
+const wireSummary = (
+  session: StoredSessionSummary,
+): DevtoolsWireSessionSummary => ({
+  sessionId: session.sessionId,
+  eventCount: session.eventCount,
+  pendingCount: session.pendingCount,
+  failedCount: session.failedCount,
+  attemptCount: session.attemptCount,
+  failureCount: session.failureCount,
+  firstEventAt: session.firstEventAt.toISOString(),
+  updatedAt: session.updatedAt.toISOString(),
+})
+
+const wireEvent = (event: StoredEvent): DevtoolsWireEvent => ({
+  id: event.id,
+  type: event.type,
+  payload: event.payload,
+  index: event.index,
+  sessionId: event.sessionId,
+  createdAt: event.createdAt.toISOString(),
+  cause:
+    event.cause === null
+      ? null
+      : {
+          index: event.cause.index,
+          attempt: event.cause.attempt,
+          ...(event.cause.batchSize === undefined
+            ? {}
+            : { batchSize: event.cause.batchSize }),
+        },
+  lane: event.lane,
+  processedAt: event.processedAt?.toISOString() ?? null,
+  processedByAttempt: event.processedByAttempt,
+  returnedEventIds: event.returnedEventIds,
+  firstClaimedAt: event.firstClaimedAt?.toISOString() ?? null,
+  lastClaimedAt: event.lastClaimedAt?.toISOString() ?? null,
+  attemptCount: event.attemptCount,
+  claimHolder: event.claimHolder,
+  claimExpiresAt: event.claimExpiresAt?.toISOString() ?? null,
+  failureCount: event.failureCount,
+  lastFailedAt: event.lastFailedAt?.toISOString() ?? null,
+  lastFailedAttempt: event.lastFailedAttempt,
+  lastError: event.lastError,
+  failedAt: event.failedAt?.toISOString() ?? null,
+})
+
+const wireSnapshot = (snapshot: StoredSnapshot): DevtoolsWireSnapshot => ({
+  reducerName: snapshot.reducerName,
+  index: snapshot.index,
+  // Redis snapshots written before inspection metadata have no durable
+  // timestamp. Epoch zero is the adapter's explicit "unknown" marker.
+  updatedAt:
+    snapshot.updatedAt.getTime() === 0
+      ? null
+      : snapshot.updatedAt.toISOString(),
+})
+
+const sessionRevision = async (detail: InspectionDetail): Promise<string> => {
+  return devtoolsSessionRevision({
+    events: detail.events.map(wireEvent),
+    snapshots: detail.snapshots.map(wireSnapshot),
+  })
+}
+
+const wireDetail = async (
+  contract: string,
+  sessionId: string,
+  detail: InspectionDetail,
+): Promise<DevtoolsSessionDetail> => ({
+  protocolVersion: DEVTOOLS_PROTOCOL_VERSION,
+  contract,
+  sessionId,
+  revision: await sessionRevision(detail),
+  events: detail.events.map(wireEvent),
+  snapshots: detail.snapshots.map(wireSnapshot),
+})
+
+const readCompleteSession = async (
+  inspection: ServerInspection,
+  sessionId: string,
+): Promise<InspectionDetail> => {
+  const events: StoredEvent[] = []
+  let snapshots: StoredSnapshot[] = []
+  let afterIndex = 0
+  let throughIndex: number | undefined
+  for (;;) {
+    // oxlint-disable-next-line no-await-in-loop -- each request advances one fixed-frontier page
+    const page = await inspection.readSessionPage(sessionId, {
+      afterIndex,
+      limit: DEVTOOLS_SESSION_PAGE_LIMIT,
+      ...(throughIndex === undefined ? {} : { throughIndex }),
+    })
+    if (throughIndex === undefined) {
+      throughIndex = page.throughIndex
+      snapshots = page.snapshots
+    } else if (page.throughIndex !== throughIndex) {
+      throw new Error('inspection session frontier changed between pages')
+    }
+    if (events.length + page.events.length > page.throughIndex) {
+      throw new Error('inspection session page crossed its frozen frontier')
+    }
+    events.push(...page.events)
+    if (page.nextIndex === null) break
+    if (events.length === page.throughIndex) {
+      throw new Error('inspection session cursor continued past its frontier')
+    }
+    if (page.nextIndex <= afterIndex) {
+      throw new Error('inspection session cursor did not advance')
+    }
+    afterIndex = page.nextIndex
+  }
+  if (throughIndex !== events.length) {
+    throw new Error('inspection session ended before its frozen frontier')
+  }
+  return { events, snapshots }
+}
+
+const readRevision = async (
+  inspection: ServerInspection,
+  sessionId: string,
+): Promise<{
+  detail: InspectionDetail
+  revision: string
+}> => {
+  const detail = await readCompleteSession(inspection, sessionId)
+  return { detail, revision: await sessionRevision(detail) }
+}
+
+const bootstrapState = async (
+  url: URL,
+  servers: ReadonlyMap<string, DevtoolsServer>,
+): Promise<DevtoolsBootstrap> => {
+  const contracts = [...servers.keys()].map((name) => ({ name }))
+  const requestedContract = url.searchParams.get('contract')
+  const contract =
+    requestedContract && servers.has(requestedContract)
+      ? requestedContract
+      : (contracts[0]?.name ?? null)
+  const bootstrap: DevtoolsBootstrap = {
+    contracts,
+    contract,
+    sessions: [],
+    cursor: null,
+    session: null,
+    detail: null,
+    error: null,
+  }
+  if (!contract) return bootstrap
+
+  const server = servers.get(contract)
+  const inspection = server ? serverInspection.get(server) : undefined
+  if (!inspection) {
+    bootstrap.error = `contract '${contract}' is not an inspectable A2 server`
+    return bootstrap
+  }
+
+  try {
+    const page = await inspection.listSessions({ limit: 50 })
+    bootstrap.sessions = page.sessions.map(wireSummary)
+    bootstrap.cursor = page.cursor
+    const requestedSession =
+      requestedContract === contract ? url.searchParams.get('session') : null
+    bootstrap.session = requestedSession ?? page.sessions[0]?.sessionId ?? null
+    if (!bootstrap.session) return bootstrap
+
+    const detail = await readCompleteSession(inspection, bootstrap.session)
+    if (detail.events.length === 0) {
+      bootstrap.error = `session '${bootstrap.session}' was not found`
+      return bootstrap
+    }
+    bootstrap.detail = await wireDetail(contract, bootstrap.session, detail)
+  } catch (error) {
+    bootstrap.error = error instanceof Error ? error.message : String(error)
+  }
+  return bootstrap
+}
+
+const resourceOf = (pathname: string): string | null => {
+  const marker = pathname.lastIndexOf(MARKER)
+  return marker === -1 ? null : pathname.slice(marker + MARKER.length)
+}
+
+const inspectionOf = (
+  servers: ReadonlyMap<string, DevtoolsServer>,
+  contractName: string | null,
+): ServerInspection | Response => {
+  if (!contractName) return badRequest('contract is required')
+  const server = servers.get(contractName)
+  if (!server) return notFound()
+  return (
+    serverInspection.get(server) ??
+    unavailable(`contract '${contractName}' is not an inspectable A2 server`)
+  )
+}
+
+type SessionCursor = { afterIndex: number; throughIndex: number }
+
+const encodeSessionCursor = (
+  contract: string,
+  sessionId: string,
+  cursor: SessionCursor,
+): string =>
+  JSON.stringify([
+    1,
+    contract,
+    sessionId,
+    cursor.throughIndex,
+    cursor.afterIndex,
+  ])
+
+const parseSessionCursor = (
+  value: string,
+  contract: string,
+  sessionId: string,
+): SessionCursor | Response => {
+  let decoded: unknown
+  try {
+    decoded = JSON.parse(value) as unknown
+  } catch {
+    return badRequest('cursor is invalid')
+  }
+  if (
+    !Array.isArray(decoded) ||
+    decoded.length !== 5 ||
+    decoded[0] !== 1 ||
+    !Number.isSafeInteger(decoded[3]) ||
+    !Number.isSafeInteger(decoded[4]) ||
+    (decoded[3] as number) < 1 ||
+    (decoded[4] as number) < 1 ||
+    (decoded[4] as number) >= (decoded[3] as number)
+  ) {
+    return badRequest('cursor is invalid')
+  }
+  if (decoded[1] !== contract || decoded[2] !== sessionId) {
+    return badRequest('cursor does not belong to this contract and session')
+  }
+  return {
+    throughIndex: decoded[3] as number,
+    afterIndex: decoded[4] as number,
+  }
+}
+
+const captureFilename = (contract: string, sessionId: string): string => {
+  const safe = `${contract}-${sessionId}`
+    .replaceAll(/[^a-zA-Z0-9._-]/g, '_')
+    .slice(0, 160)
+  return `${safe || 'a2-session'}.a2log`
+}
+
+const watchResponse = (
+  request: Request,
+  inspection: ServerInspection,
+  sessionId: string,
+  initial: InspectionDetail,
+): Response => {
+  let stopped = false
+  let timeout: ReturnType<typeof setTimeout> | null = null
+  let wake: (() => void) | null = null
+  const stop = (): void => {
+    stopped = true
+    if (timeout !== null) clearTimeout(timeout)
+    timeout = null
+    wake?.()
+    wake = null
+  }
+  const wait = (milliseconds: number): Promise<void> =>
+    new Promise((resolve) => {
+      wake = resolve
+      timeout = setTimeout(() => {
+        timeout = null
+        wake = null
+        resolve()
+      }, milliseconds)
+    })
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      request.signal.addEventListener('abort', stop, { once: true })
+      controller.enqueue(encoder.encode('retry: 1000\n: connected\n\n'))
+      void (async () => {
+        let detail = initial
+        let previous = new URL(request.url).searchParams.get('revision') ?? ''
+        let lastHeartbeat = Date.now()
+        try {
+          let revision = await sessionRevision(detail)
+          for (;;) {
+            if (stopped) break
+            if (revision !== previous) {
+              previous = revision
+              controller.enqueue(
+                encoder.encode(
+                  `event: invalidate\ndata: ${JSON.stringify({ revision })}\n\n`,
+                ),
+              )
+            } else if (
+              Date.now() - lastHeartbeat >=
+              DEVTOOLS_TIMINGS.heartbeatMs
+            ) {
+              controller.enqueue(encoder.encode(': ping\n\n'))
+              lastHeartbeat = Date.now()
+            }
+            const active = detail.events.some(
+              (event) => event.processedAt === null && event.failedAt === null,
+            )
+            // oxlint-disable-next-line no-await-in-loop -- each revision read follows its poll interval
+            await wait(
+              active ? DEVTOOLS_TIMINGS.activeMs : DEVTOOLS_TIMINGS.idleMs,
+            )
+            if (!stopped) {
+              // oxlint-disable-next-line no-await-in-loop -- poll state advances from the prior read
+              const next = await readRevision(inspection, sessionId)
+              detail = next.detail
+              revision = next.revision
+            }
+          }
+          controller.close()
+        } catch (error) {
+          if (!stopped) controller.error(error)
+        }
+      })()
+    },
+    cancel() {
+      stop()
+    },
+  })
+
+  return new Response(stream, {
+    headers: {
+      ...headers('text/event-stream; charset=utf-8'),
+      connection: 'keep-alive',
+      'x-accel-buffering': 'no',
+    },
+  })
+}
+
+const authorizeRequest = async (
+  request: Request,
+  authorize: DevtoolsAuthorization | undefined,
+): Promise<Response | null> => {
+  if (!authorize) return isDevelopment() ? null : notFound()
+  const result = await authorize(request)
+  if (result instanceof Response) return result
+  return result === true ? null : notFound()
+}
+
+export function createDevtools(options: DevtoolsOptions): Devtools {
+  if (
+    !options ||
+    !Array.isArray(options.servers) ||
+    options.servers.length === 0
+  ) {
+    throw new TypeError('createDevtools expects at least one A2 server')
+  }
+  const servers = new Map<string, DevtoolsServer>()
+  for (const server of options.servers) {
+    const name = server?.contract?.name
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new TypeError('createDevtools received a server without a contract')
+    }
+    if (servers.has(name)) {
+      throw new TypeError(`createDevtools received contract '${name}' twice`)
+    }
+    servers.set(name, server)
+  }
+
+  return {
+    handler() {
+      return async (request) => {
+        const denied = await authorizeRequest(request, options.authorize)
+        if (denied) return denied
+        if (request.method !== 'GET') {
+          return new Response('Method not allowed', {
+            status: 405,
+            headers: { ...headers('text/plain'), allow: 'GET' },
+          })
+        }
+
+        const url = new URL(request.url)
+        const resource = resourceOf(url.pathname)
+        if (resource === null) {
+          const basePath = `${url.pathname.replace(/\/$/, '')}/`
+          const bootstrap = await bootstrapState(url, servers)
+          return new Response(devtoolsHtml(basePath, bootstrap), {
+            headers: {
+              ...headers('text/html; charset=utf-8'),
+              'content-security-policy':
+                "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; base-uri 'self'; frame-ancestors 'none'",
+            },
+          })
+        }
+        if (resource === 'app.js') {
+          return new Response(DEVTOOLS_APP_JS, {
+            headers: headers('text/javascript; charset=utf-8'),
+          })
+        }
+        if (resource === 'app.css') {
+          return new Response(DEVTOOLS_APP_CSS, {
+            headers: headers('text/css; charset=utf-8'),
+          })
+        }
+        if (resource === 'contracts') {
+          return json({
+            protocolVersion: DEVTOOLS_PROTOCOL_VERSION,
+            contracts: [...servers.keys()].map((name) => ({ name })),
+          })
+        }
+        if (resource === 'capabilities') {
+          return json(DEVTOOLS_CAPABILITIES)
+        }
+
+        const contractName = url.searchParams.get('contract')
+        const inspection = inspectionOf(servers, contractName)
+        if (inspection instanceof Response) return inspection
+        try {
+          if (resource === 'sessions') {
+            const requestedLimit = Number(url.searchParams.get('limit') ?? 50)
+            if (!Number.isInteger(requestedLimit) || requestedLimit < 1) {
+              return badRequest('limit must be a positive integer')
+            }
+            const limit = Math.min(requestedLimit, 100)
+            const cursor = url.searchParams.get('cursor')
+            const page = await inspection.listSessions({
+              limit,
+              ...(cursor !== null ? { cursor } : {}),
+            })
+            return json({
+              protocolVersion: DEVTOOLS_PROTOCOL_VERSION,
+              cursor: page.cursor,
+              sessions: page.sessions.map(wireSummary),
+            })
+          }
+
+          const sessionId = url.searchParams.get('session')
+          if (!sessionId) return badRequest('session is required')
+          if (
+            resource === 'session' &&
+            (url.searchParams.has('limit') || url.searchParams.has('cursor'))
+          ) {
+            const requestedLimit = Number(
+              url.searchParams.get('limit') ?? DEVTOOLS_SESSION_PAGE_LIMIT,
+            )
+            if (!Number.isSafeInteger(requestedLimit) || requestedLimit < 1) {
+              return badRequest('limit must be a positive integer')
+            }
+            const limit = Math.min(
+              requestedLimit,
+              DEVTOOLS_SESSION_PAGE_MAX_LIMIT,
+            )
+            const cursorValue = url.searchParams.get('cursor')
+            const cursor =
+              cursorValue === null
+                ? { afterIndex: 0, throughIndex: undefined }
+                : parseSessionCursor(cursorValue, contractName!, sessionId)
+            if (cursor instanceof Response) return cursor
+            const page = await inspection.readSessionPage(sessionId, {
+              afterIndex: cursor.afterIndex,
+              limit,
+              ...(cursor.throughIndex === undefined
+                ? {}
+                : { throughIndex: cursor.throughIndex }),
+            })
+            if (page.throughIndex === 0) return notFound()
+            const response: DevtoolsSessionPage = {
+              protocolVersion: DEVTOOLS_PROTOCOL_VERSION,
+              contract: contractName!,
+              sessionId,
+              throughIndex: page.throughIndex,
+              cursor:
+                page.nextIndex === null
+                  ? null
+                  : encodeSessionCursor(contractName!, sessionId, {
+                      throughIndex: page.throughIndex,
+                      afterIndex: page.nextIndex,
+                    }),
+              events: page.events.map(wireEvent),
+              snapshots: page.snapshots.map(wireSnapshot),
+            }
+            return json(response)
+          }
+
+          const detail = await readCompleteSession(inspection, sessionId)
+          if (detail.events.length === 0) return notFound()
+          const wired = await wireDetail(contractName!, sessionId, detail)
+          if (resource === 'session') {
+            return json(wired)
+          }
+          if (resource === 'export') {
+            return new Response(await encodeDevtoolsCapture(wired), {
+              headers: {
+                ...headers(`${DEVTOOLS_CAPTURE_MEDIA_TYPE}; charset=utf-8`),
+                'content-disposition': `attachment; filename="${captureFilename(wired.contract, sessionId)}"`,
+              },
+            })
+          }
+          if (resource === 'watch') {
+            return watchResponse(request, inspection, sessionId, detail)
+          }
+        } catch (error) {
+          if (error instanceof InspectionUnsupportedError) {
+            return unavailable(error.message)
+          }
+          throw error
+        }
+        return notFound()
+      }
+    },
+  }
+}