experimental-a2 0.20.0 → 0.22.0

package/examples/playground/app/a2slack/drills/harness.ts

@@ -0,0 +1,244 @@
+/**
+ * What the drills share: a throwaway Redis and Postgres, a scheduler made of
+ * timers, a telemetry sink that times every consumer run, the workspace's
+ * cursors, and percentiles.
+ */
+import { execFileSync, spawn, type ChildProcess } from 'node:child_process'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { createServer as listen } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { A2AttributeValue, A2Telemetry } from 'experimental-a2'
+import type {
+  A2Scheduler,
+  A2Store,
+  DrainableServer,
+} from 'experimental-a2/server'
+
+const freePort = (): Promise<number> =>
+  new Promise((resolve, reject) => {
+    const server = listen()
+    server.unref()
+    server.on('error', reject)
+    server.listen(0, () => {
+      const address = server.address()
+      server.close(() =>
+        resolve(typeof address === 'object' && address ? address.port : 0),
+      )
+    })
+  })
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+
+export type Services = {
+  redisUrl: string
+  databaseUrl: string
+  /** Stops Postgres the way a crash would; `startPostgres` brings it back. */
+  stopPostgres(): void
+  startPostgres(): void
+  close(): void
+}
+
+/** A Redis and a Postgres in a temporary directory, on free ports. */
+export async function startServices(): Promise<Services> {
+  const dir = mkdtempSync(join(tmpdir(), 'a2slack-drills-'))
+  const redisPort = await freePort()
+  const pgPort = await freePort()
+  const redis: ChildProcess = spawn(
+    'redis-server',
+    [
+      '--port',
+      String(redisPort),
+      '--save',
+      '',
+      '--appendonly',
+      'no',
+      '--dir',
+      dir,
+    ],
+    { stdio: 'ignore' },
+  )
+  for (let tries = 0; ; tries += 1) {
+    try {
+      if (
+        execFileSync('redis-cli', ['-p', String(redisPort), 'ping'])
+          .toString()
+          .trim() === 'PONG'
+      )
+        break
+    } catch {
+      if (tries > 100) throw new Error('redis-server did not start')
+    }
+    await sleep(50)
+  }
+  const data = join(dir, 'pg')
+  execFileSync('initdb', ['-U', 'postgres', '-A', 'trust', data], {
+    stdio: 'ignore',
+  })
+  const pgCtl = (...args: string[]) =>
+    execFileSync('pg_ctl', ['-D', data, ...args], { stdio: 'ignore' })
+  const startPostgres = () =>
+    pgCtl(
+      '-o',
+      `-p ${pgPort} -k ${dir} -c max_connections=300`,
+      '-l',
+      join(dir, 'pg.log'),
+      '-w',
+      'start',
+    )
+  startPostgres()
+  return {
+    redisUrl: `redis://127.0.0.1:${redisPort}`,
+    databaseUrl: `postgres://postgres@127.0.0.1:${pgPort}/postgres`,
+    stopPostgres: () => pgCtl('-m', 'immediate', '-w', 'stop'),
+    startPostgres,
+    close() {
+      redis.kill('SIGKILL')
+      try {
+        pgCtl('-m', 'immediate', '-w', 'stop')
+      } catch {
+        // already stopped
+      }
+      rmSync(dir, { recursive: true, force: true })
+    },
+  }
+}
+
+/**
+ * A scheduler made of timers. A due drain task drains its session, the way
+ * Vercel Queues delivers one, so failed events retry and watchdogs fire as
+ * they do in production. Without a scheduler, a failed event waits for the
+ * session's next append or `consume`.
+ */
+export function timerScheduler(): {
+  scheduler: A2Scheduler
+  deliverTo(server: DrainableServer): void
+} {
+  let target: DrainableServer | undefined
+  return {
+    scheduler: {
+      async schedule(task) {
+        if (task.kind !== 'drain') return
+        setTimeout(
+          () => void target?.drain(task.sessionId).catch(() => {}),
+          Math.max(0, task.dueAt - Date.now()),
+        ).unref()
+      },
+      handler: () => async () => new Response(null, { status: 204 }),
+    },
+    deliverTo(server) {
+      target = server
+    },
+  }
+}
+
+/** One consumer run, as its `a2.event` span saw it. */
+export type Run = {
+  consumer: string
+  index: number
+  /** How old the event was when the run started. */
+  ageMs: number
+  /** How many events the session had after it when it was claimed. */
+  lag: number
+  durationMs: number
+  failed: boolean
+}
+
+/** Telemetry that keeps every consumer run and every append's duration. */
+export function recorder(): {
+  telemetry: A2Telemetry
+  runs: Run[]
+  reset(): void
+} {
+  const runs: Run[] = []
+  const telemetry: A2Telemetry = {
+    async span(name, attributes, fn) {
+      const started = performance.now()
+      let failed = false
+      const set: Record<string, A2AttributeValue> = {}
+      try {
+        return await fn({
+          setAttribute: (key, value) => {
+            set[key] = value
+          },
+          recordError: () => {
+            failed = true
+          },
+        })
+      } catch (error) {
+        failed = true
+        throw error
+      } finally {
+        if (name === 'a2.event' && attributes['a2.event.handled'] === true)
+          runs.push({
+            consumer: String(attributes['a2.event.consumer']),
+            index: Number(attributes['a2.event.index']),
+            ageMs: Number(attributes['a2.event.age_ms'] ?? 0),
+            lag: Number(attributes['a2.event.lag'] ?? 0),
+            durationMs: performance.now() - started,
+            failed: failed || set['a2.event.outcome'] === 'failed',
+          })
+      }
+    },
+  }
+  return { telemetry, runs, reset: () => runs.splice(0) }
+}
+
+export type Summary = {
+  n: number
+  p50: number
+  p95: number
+  p99: number
+  max: number
+}
+
+/** Percentiles of `values`, rounded to a tenth. */
+export function summarize(values: readonly number[]): Summary {
+  const sorted = values.toSorted((a, b) => a - b)
+  const at = (q: number) =>
+    sorted.length === 0
+      ? 0
+      : Math.round(
+          sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))]! *
+            10,
+        ) / 10
+  return {
+    n: sorted.length,
+    p50: at(0.5),
+    p95: at(0.95),
+    p99: at(0.99),
+    max: at(1),
+  }
+}
+
+/** Waits until `ready` holds, checking every `everyMs`. */
+export async function until(
+  ready: () => Promise<boolean> | boolean,
+  { timeoutMs, everyMs = 50 }: { timeoutMs: number; everyMs?: number },
+): Promise<number> {
+  const started = performance.now()
+  for (;;) {
+    // oxlint-disable-next-line no-await-in-loop -- polling, one check at a time
+    if (await ready()) return performance.now() - started
+    if (performance.now() - started > timeoutMs)
+      throw new Error(`not ready after ${timeoutMs}ms`)
+    // oxlint-disable-next-line no-await-in-loop -- polling, one check at a time
+    await sleep(everyMs)
+  }
+}
+
+/** The workspace session as the store keys it. */
+export const WORKSPACE_KEY = 'a2slack\u001fworkspace'
+
+/** Whether none of `consumers` has an event left to run. */
+export async function idle(
+  store: A2Store,
+  consumers: readonly string[],
+): Promise<boolean> {
+  const cursors = await store.cursors(WORKSPACE_KEY)
+  return cursors
+    .filter((cursor) => consumers.includes(cursor.consumer))
+    .every((cursor) => cursor.head === null)
+}
+
+export { sleep }

package/examples/playground/app/a2slack/events/route.ts

@@ -0,0 +1,36 @@
+import { WORKSPACE } from '../model'
+import { a2slackServer } from '../server'
+
+/** What a person does. Notifications and labels are the server's: its consumers append them. */
+const CLIENT_TYPES = new Set([
+  'channel.created',
+  'message.posted',
+  'message.edited',
+  'message.deleted',
+  'reaction.added',
+  'reaction.removed',
+  'inbox.read',
+])
+
+/** The ids the client makes, with crypto.randomUUID(). */
+const RANDOM_ID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+/**
+ * The workspace is the app's one session: a request can't read or write any
+ * other, push an event the server appends, or pick an id a consumer will need.
+ */
+const handle = (request: Request): Promise<Response> =>
+  a2slackServer.fetch(request, {
+    authorize: (operation) =>
+      operation.sessionId === WORKSPACE &&
+      (operation.type !== 'push' ||
+        operation.events.every(
+          (event) =>
+            CLIENT_TYPES.has(event.type) &&
+            (event.id === undefined || RANDOM_ID.test(event.id)),
+        )),
+  })
+
+export const GET = handle
+export const POST = handle

package/examples/playground/app/a2slack/identity.ts

@@ -0,0 +1,44 @@
+/**
+ * Who is typing — a name picked on first visit, kept in localStorage.
+ * This example has no auth: the identity is client-asserted, exactly as
+ * far as it should be trusted (not at all). A real app derives it from
+ * the request in the route's `before` hook instead.
+ */
+'use client'
+import { useSyncExternalStore } from 'react'
+
+export type Identity = { id: string; name: string }
+
+const KEY = 'a2slack-identity'
+const listeners = new Set<() => void>()
+let cached: Identity | null | undefined
+
+function read(): Identity | null {
+  if (cached === undefined) {
+    try {
+      cached = JSON.parse(
+        localStorage.getItem(KEY) ?? 'null',
+      ) as Identity | null
+    } catch {
+      cached = null
+    }
+  }
+  return cached
+}
+
+export function useIdentity(): Identity | null {
+  return useSyncExternalStore(
+    (onChange) => {
+      listeners.add(onChange)
+      return () => listeners.delete(onChange)
+    },
+    read,
+    () => null,
+  )
+}
+
+export function saveIdentity(name: string): void {
+  cached = { id: crypto.randomUUID(), name: name.trim() }
+  localStorage.setItem(KEY, JSON.stringify(cached))
+  for (const notify of listeners) notify()
+}

package/examples/playground/app/a2slack/inbox/route.ts

@@ -0,0 +1,8 @@
+import { inboxPage } from '../db/queries'
+
+/** Someone's inbox. There's no auth: identity is a name in localStorage. */
+export async function GET(request: Request): Promise<Response> {
+  const user = new URL(request.url).searchParams.get('user')
+  if (!user) return Response.json({ error: 'no user' }, { status: 400 })
+  return Response.json(await inboxPage(user))
+}

package/examples/playground/app/a2slack/lag/data/route.ts

@@ -0,0 +1,8 @@
+import { workspaceLag } from '../../lag'
+
+export const dynamic = 'force-dynamic'
+
+/** Each consumer's place in the workspace's log; the lag page polls it. */
+export async function GET(): Promise<Response> {
+  return Response.json(await workspaceLag())
+}

package/examples/playground/app/a2slack/lag/page.tsx

@@ -0,0 +1,101 @@
+'use client'
+/**
+ * How far each consumer is behind the workspace's log, every two seconds:
+ * where it is, what it runs next, and what it gave up on.
+ */
+import { useEffect, useState, type ReactNode } from 'react'
+import type { Lag } from '@/app/a2slack/lag'
+
+const EVERY_MS = 2_000
+
+export default function LagPage(): ReactNode {
+  const [lag, setLag] = useState<Lag | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    let stopped = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const read = async () => {
+      try {
+        const response = await fetch('/a2slack/lag/data', { cache: 'no-store' })
+        if (!response.ok) throw new Error(`lag failed (${response.status})`)
+        const next = (await response.json()) as Lag
+        if (!stopped) {
+          setLag(next)
+          setError(null)
+        }
+      } catch (caught) {
+        if (!stopped) setError(String(caught))
+      }
+      if (!stopped) timer = setTimeout(read, EVERY_MS)
+    }
+    void read()
+    return () => {
+      stopped = true
+      clearTimeout(timer)
+    }
+  }, [])
+
+  return (
+    <div className="a2slack-view">
+      <div className="a2slack-header">
+        <span className="a2slack-header-name">lag</span>
+        <span className="a2slack-status">
+          {error ?? (lag ? `head ${lag.head}` : 'reading…')}
+        </span>
+      </div>
+      {lag && (
+        <div className="a2slack-lag">
+          <table>
+            <thead>
+              <tr>
+                <th>consumer</th>
+                <th>lane</th>
+                <th>position</th>
+                <th>next</th>
+                <th>behind</th>
+                <th>failures</th>
+                <th>last error</th>
+              </tr>
+            </thead>
+            <tbody>
+              {lag.consumers.map((row) => (
+                <tr
+                  key={`${row.consumer}|${row.lane}|${row.next}`}
+                  data-behind={row.behind > 0 ? 'yes' : undefined}
+                >
+                  <td>{row.consumer}</td>
+                  <td>{row.lane ?? '·'}</td>
+                  <td>{row.position}</td>
+                  <td>{row.next ?? '·'}</td>
+                  <td>{row.behind}</td>
+                  <td>{row.failures}</td>
+                  <td className="a2slack-lag-error">{row.lastError ?? ''}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+          {lag.deadLetters.length > 0 && (
+            <>
+              <p className="a2slack-lag-title">dead letters</p>
+              <table>
+                <tbody>
+                  {lag.deadLetters.map((letter) => (
+                    <tr key={`${letter.consumer}|${letter.index}`}>
+                      <td>{letter.consumer}</td>
+                      <td>#{letter.index}</td>
+                      <td>{letter.type}</td>
+                      <td className="a2slack-lag-error">
+                        {letter.error ?? ''}
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

package/examples/playground/app/a2slack/lag.ts

@@ -0,0 +1,73 @@
+/**
+ * How far each consumer is behind the workspace's log: its cursors as the
+ * store keeps them, against the log's head, and the events it gave up on.
+ * The lag page (lag/page.tsx) polls it.
+ */
+import 'server-only'
+import type { A2Store } from 'experimental-a2/server'
+import { store } from '@/lib/store'
+import { WORKSPACE, workspace } from './model'
+import { a2slackServer } from './server'
+
+export type ConsumerLag = {
+  consumer: string
+  lane: string | null
+  /** The last event it finished. */
+  position: number
+  /** The event it runs next; null when it has nothing to run. */
+  next: number | null
+  /**
+   * Events in the log after its position, while it has one to run. A
+   * consumer that takes some types is caught up once none of them is left.
+   */
+  behind: number
+  attempts: number
+  failures: number
+  lastError: string | null
+}
+
+export type Lag = {
+  /** The log's last event. */
+  head: number
+  consumers: ConsumerLag[]
+  deadLetters: {
+    consumer: string
+    index: number
+    type: string
+    error: string | null
+  }[]
+  at: string
+}
+
+// Without REDIS_URL or DATABASE_URL, the server uses A2's development store.
+const lagStore = async (): Promise<A2Store> =>
+  store ?? (await import('experimental-a2/store-sqlite')).sqlite()
+
+export async function workspaceLag(): Promise<Lag> {
+  const session = a2slackServer.session(WORKSPACE)
+  const [cursors, { index: head }, deadLetters] = await Promise.all([
+    (await lagStore()).cursors(`${workspace.name}\u001f${WORKSPACE}`),
+    session.state(),
+    session.deadLetters(),
+  ])
+  return {
+    head,
+    consumers: cursors.map((cursor) => ({
+      consumer: cursor.consumer,
+      lane: cursor.lane,
+      position: cursor.position,
+      next: cursor.head,
+      behind: cursor.head === null ? 0 : Math.max(0, head - cursor.position),
+      attempts: cursor.attemptCount,
+      failures: cursor.failureCount,
+      lastError: cursor.lastError,
+    })),
+    deadLetters: deadLetters.map((letter) => ({
+      consumer: letter.consumer,
+      index: letter.index,
+      type: letter.type,
+      error: letter.lastError,
+    })),
+    at: new Date().toISOString(),
+  }
+}

package/examples/playground/app/a2slack/layout.tsx

@@ -0,0 +1,43 @@
+import type { Metadata } from 'next'
+import type { ReactNode } from 'react'
+import { GeistSans } from 'geist/font/sans'
+import { WORKSPACE } from '@/app/a2slack/model'
+import { feed } from '@/app/a2slack/consumers/feed'
+import { workspaceSnapshot } from '@/app/a2slack/db/queries'
+import { a2slackServer } from '@/app/a2slack/server'
+import { WorkspaceProvider } from '@/app/a2slack/sessions'
+import { Shell } from '@/app/a2slack/ui/Shell'
+import './a2slack.css'
+
+export const metadata: Metadata = {
+  title: 'a2slack · a2 example',
+  description: 'A team chat whose whole workspace is one A2 session.',
+}
+
+// A chat is dynamic by definition; never read the workspace at build time.
+export const dynamic = 'force-dynamic'
+
+export default async function A2slackLayout({
+  children,
+}: {
+  children: ReactNode
+}): Promise<ReactNode> {
+  // The channel list as the database has it, and the log index it reflects:
+  // the stream resumes after `through`.
+  const { channels, opened, through } = await workspaceSnapshot()
+  // A feed that hasn't read anything yet, on a log that already has events,
+  // starts its backfill now instead of waiting for the next post.
+  if (through === 0)
+    await a2slackServer.session(WORKSPACE).consume(feed, { through: 0 })
+
+  return (
+    <div className={`a2slack-page ${GeistSans.variable}`}>
+      <WorkspaceProvider
+        sessionId={WORKSPACE}
+        initial={{ state: { channels, opened }, index: through }}
+      >
+        <Shell>{children}</Shell>
+      </WorkspaceProvider>
+    </div>
+  )
+}

package/examples/playground/app/a2slack/messages/route.ts

@@ -0,0 +1,17 @@
+import { messagePage } from '../db/queries'
+import { channelIdSchema } from '../model'
+
+/** A page of a channel's top-level messages, older than `before` if given. */
+export async function GET(request: Request): Promise<Response> {
+  const params = new URL(request.url).searchParams
+  const channel = channelIdSchema.safeParse(params.get('channel'))
+  const before = Number(params.get('before') ?? Number.NaN)
+  if (!channel.success)
+    return Response.json({ error: 'unknown channel' }, { status: 400 })
+  return Response.json(
+    await messagePage(
+      channel.data,
+      Number.isSafeInteger(before) && before > 0 ? { before } : {},
+    ),
+  )
+}