experimental-a2 0.20.0 → 0.22.0

package/examples/playground/app/a2slack/search-index.ts

@@ -0,0 +1,108 @@
+/**
+ * Search, in the Upstash Redis the playground already has: one JSON
+ * document per message under PREFIX, which Upstash Redis Search indexes as
+ * it's written (consumers/search.ts writes them). Where Redis Search isn't
+ * configured, as in development, search reads the feed's table instead.
+ *
+ * The index's name versions it with its consumer's: to change the schema,
+ * rename both, and the new consumer fills the new index from the beginning.
+ */
+import 'server-only'
+import { Redis, s } from '@upstash/redis'
+import { searchFeed } from './db/queries'
+import type { SearchResult } from './model'
+
+const NAME = 'a2slack-messages-v1'
+const PREFIX = `${NAME}:message:`
+
+const schema = s.object({
+  channel: s.keyword(),
+  threadId: s.keyword(),
+  authorId: s.keyword(),
+  authorName: s.string(),
+  text: s.string(),
+  postedAt: s.number(),
+})
+
+export type SearchDocument = {
+  channel: string
+  /** Empty for a top-level message. */
+  threadId: string
+  authorId: string
+  authorName: string
+  text: string
+  postedAt: number
+}
+
+// Upstash's REST credentials: Vercel's default names, or this project's prefix.
+const url = process.env.KV_REST_API_URL || process.env.REDIS_KV_REST_API_URL
+const token =
+  process.env.KV_REST_API_TOKEN || process.env.REDIS_KV_REST_API_TOKEN
+
+const redis = url && token ? new Redis({ url, token }) : undefined
+
+/** Whether this deployment searches with Upstash Redis Search. */
+export const hasSearchIndex: boolean = redis !== undefined
+
+let created: Promise<unknown> | undefined
+
+/** The index, created once per process if it doesn't exist yet. */
+async function index() {
+  if (!redis) throw new Error('Upstash Redis Search is not configured')
+  created ??= redis.search
+    .createIndex({
+      name: NAME,
+      prefix: PREFIX,
+      dataType: 'json',
+      schema,
+      existsOk: true,
+    })
+    .catch((error: unknown) => {
+      created = undefined
+      throw error
+    })
+  await created
+  return redis.search.index({ name: NAME, schema })
+}
+
+export async function putDocument(
+  id: string,
+  document: SearchDocument,
+): Promise<void> {
+  await index()
+  await redis!.json.set(`${PREFIX}${id}`, '$', document)
+}
+
+export async function setDocumentText(id: string, text: string): Promise<void> {
+  await index()
+  // A path below the root can't be set on a missing document, and RedisJSON
+  // refuses it: an edit of a message never indexed, or since deleted, is a no-op.
+  if (!(await redis!.exists(`${PREFIX}${id}`))) return
+  await redis!.json.set(`${PREFIX}${id}`, '$.text', JSON.stringify(text))
+}
+
+export async function deleteDocument(id: string): Promise<void> {
+  await redis!.del(`${PREFIX}${id}`)
+}
+
+/** Waits until Upstash has indexed every document written so far. */
+export async function indexed(): Promise<void> {
+  if (redis) await (await index()).waitIndexing()
+}
+
+/** The messages that best match `q`, across every channel. */
+export async function search(q: string): Promise<SearchResult[]> {
+  if (!redis) return searchFeed(q)
+  const hits = await (await index()).query({ filter: { text: q }, limit: 50 })
+  return hits.map(({ key, data }) => {
+    const result: SearchResult = {
+      channel: data.channel,
+      id: key.slice(PREFIX.length),
+      author: { id: data.authorId, name: data.authorName },
+      text: data.text,
+      at: new Date(data.postedAt).toISOString(),
+    }
+    if (data.threadId !== '') result.threadId = data.threadId
+    return result
+  })
+}

package/examples/playground/app/a2slack/server.test.ts

@@ -0,0 +1,315 @@
+import { asc, eq } from 'drizzle-orm'
+import { expect, it, vi } from 'vitest'
+import { database } from './db'
+import {
+  FEED,
+  inboxPage,
+  messagePage,
+  position,
+  searchFeed,
+  threadPage,
+} from './db/queries'
+import { notifications } from './db/schema'
+import { feedEvent } from './consumers/feed'
+import { mentionedNames } from './consumers/notify'
+import { liveMessages, WORKSPACE, type Author } from './model'
+import { POST } from './events/route'
+import { a2slackServer } from './server'
+
+const ada: Author = { id: 'user-ada', name: 'ada' }
+const bob: Author = { id: 'user-bob', name: 'bob' }
+const cat: Author = { id: 'user-cat', name: 'cat' }
+
+const room = a2slackServer.session(WORKSPACE)
+
+/** Waits until the feed has applied every event in the log so far. */
+async function caughtUp(): Promise<number> {
+  const head = (await room.history()).at(-1)?.index ?? 0
+  const db = await database()
+  await vi.waitFor(async () => {
+    expect(await position(db, FEED)).toBeGreaterThanOrEqual(head)
+  })
+  return head
+}
+
+it('welcomes a new channel once', async () => {
+  const created = {
+    type: 'channel.created',
+    payload: { id: 'welcomed', by: ada },
+  } as const
+  await room.append(created)
+  await room.append(created)
+
+  await vi.waitFor(async () => {
+    const page = await messagePage('welcomed')
+    expect(page.messages.map((message) => message.text)).toEqual([
+      '#welcomed is open — ada started it.',
+    ])
+  })
+})
+
+it('reads pages and threads from the feed, as of its position', async () => {
+  const [root] = await room.append({
+    type: 'message.posted',
+    payload: { channel: 'pages', author: ada, text: 'the deploy is green' },
+  })
+  await room.append(
+    {
+      type: 'message.posted',
+      payload: {
+        channel: 'pages',
+        author: bob,
+        text: 'nice',
+        threadId: root!.id,
+      },
+    },
+    {
+      type: 'reaction.added',
+      payload: {
+        channel: 'pages',
+        messageId: root!.id,
+        emoji: '🎉',
+        by: bob,
+      },
+    },
+    {
+      type: 'message.edited',
+      payload: {
+        channel: 'pages',
+        messageId: root!.id,
+        text: 'the deploy is green again',
+        by: ada,
+      },
+    },
+  )
+  const head = await caughtUp()
+
+  const page = await messagePage('pages')
+  expect(page.through).toBeGreaterThanOrEqual(head)
+  expect(page.messages).toMatchObject([
+    {
+      text: 'the deploy is green again',
+      replyCount: 1,
+      reactions: [{ emoji: '🎉', by: [bob] }],
+    },
+  ])
+  expect((await threadPage(root!.id)).replies.map((m) => m.text)).toEqual([
+    'nice',
+  ])
+
+  // A page read before the edit, kept live with the events after it,
+  // matches the page read now.
+  const events = await room.history()
+  const stale = {
+    ...page,
+    messages: [{ ...page.messages[0]!, text: 'the deploy is green' }],
+    through: root!.index + 2,
+  }
+  expect(
+    liveMessages(stale, events, { channel: 'pages', append: true }),
+  ).toEqual(page.messages)
+})
+
+it('applies each event to the feed once', async () => {
+  const [event] = await room.append({
+    type: 'message.posted',
+    payload: { channel: 'once', author: ada, text: 'only once' },
+  })
+  await caughtUp()
+  await feedEvent(await database(), event as Parameters<typeof feedEvent>[1])
+  expect((await messagePage('once')).messages).toHaveLength(1)
+})
+
+it('notifies whoever is mentioned and whoever is in the thread', async () => {
+  // bob and cat have posted, so `@bob` and `@cat` name them.
+  await room.append(
+    {
+      type: 'message.posted',
+      payload: { channel: 'notify', author: bob, text: 'hi' },
+    },
+    {
+      type: 'message.posted',
+      payload: { channel: 'notify', author: cat, text: 'hey' },
+    },
+  )
+  const [root] = await room.append({
+    type: 'message.posted',
+    payload: { channel: 'notify', author: ada, text: '@bob can you look?' },
+  })
+  await room.append(
+    {
+      type: 'message.posted',
+      payload: {
+        channel: 'notify',
+        author: bob,
+        text: 'sure, @cat too',
+        threadId: root!.id,
+      },
+    },
+    {
+      type: 'message.posted',
+      payload: {
+        channel: 'notify',
+        author: ada,
+        text: 'thanks',
+        threadId: root!.id,
+      },
+    },
+  )
+
+  const db = await database()
+  await vi.waitFor(async () => {
+    const sent = await db
+      .select({ to: notifications.userId, reason: notifications.reason })
+      .from(notifications)
+      .where(eq(notifications.threadId, root!.id))
+      .orderBy(asc(notifications.logIndex), asc(notifications.userId))
+    expect(sent).toEqual([
+      { to: bob.id, reason: 'mention' },
+      { to: ada.id, reason: 'reply' },
+      { to: cat.id, reason: 'mention' },
+      { to: bob.id, reason: 'reply' },
+      { to: cat.id, reason: 'reply' },
+    ])
+  })
+
+  const inbox = await inboxPage(bob.id)
+  expect(inbox.items).toMatchObject([
+    { threadId: root!.id, text: 'thanks', unread: 2 },
+  ])
+  await room.append({
+    type: 'inbox.read',
+    payload: { by: bob.id, threadId: root!.id, through: inbox.items[0]!.index },
+  })
+  await caughtUp()
+  expect((await inboxPage(bob.id)).items).toMatchObject([{ unread: 0 }])
+})
+
+it('finds mentions only where they are names', () => {
+  expect(mentionedNames('@Ada and @bob-2, not me@x.com, @ada again')).toEqual([
+    'ada',
+    'bob-2',
+  ])
+})
+
+it('searches every channel in the feed where Redis Search is not configured', async () => {
+  await room.append(
+    {
+      type: 'message.posted',
+      payload: { channel: 'search-a', author: ada, text: '100% green' },
+    },
+    {
+      type: 'message.posted',
+      payload: { channel: 'search-b', author: bob, text: 'green_ish tea' },
+    },
+  )
+  await caughtUp()
+  expect(
+    (await searchFeed('green')).map((r) => [r.channel, r.text]).toSorted(),
+  ).toEqual(
+    [
+      ['pages', 'the deploy is green again'],
+      ['search-a', '100% green'],
+      ['search-b', 'green_ish tea'],
+    ].toSorted(),
+  )
+  // LIKE's wildcards match only themselves.
+  expect((await searchFeed('%')).map((r) => r.text)).toEqual(['100% green'])
+  expect((await searchFeed('n_i')).map((r) => r.text)).toEqual([
+    'green_ish tea',
+  ])
+})
+
+/** Pushes one event to the workspace through the public route. */
+const pushEvent = (event: Record<string, unknown>) =>
+  POST(
+    new Request('http://a2slack.test/a2slack/events', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ sessionId: WORKSPACE, events: [event] }),
+    }),
+  )
+
+it('serves only the workspace session to requests', async () => {
+  const push = (sessionId: string) =>
+    POST(
+      new Request('http://a2slack.test/a2slack/events', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          sessionId,
+          events: [
+            { type: 'channel.created', payload: { id: 'elsewhere', by: ada } },
+          ],
+        }),
+      }),
+    )
+  expect((await push('another')).status).toBe(403)
+  expect(await a2slackServer.session('another').history()).toEqual([])
+  expect((await push(WORKSPACE)).status).toBe(200)
+
+  // Nor an event the server appends, nor an id the client didn't make at random.
+  const label = {
+    type: 'message.labeled',
+    payload: { channel: 'general', messageId: 'event-1', label: 'idea' },
+  }
+  expect((await pushEvent(label)).status).toBe(403)
+  const named = {
+    type: 'channel.created',
+    payload: { id: 'named', by: ada },
+    id: 'my-own-id',
+  }
+  expect((await pushEvent(named)).status).toBe(403)
+  expect((await pushEvent({ ...named, id: crypto.randomUUID() })).status).toBe(
+    200,
+  )
+})
+
+it("keeps the feed's position to the workspace's own log", async () => {
+  const head = await caughtUp()
+  const db = await database()
+  // Another session, further along than the workspace: its indexes would pass the feed's position.
+  const elsewhere = a2slackServer.session('elsewhere')
+  for (let n = 0; n < head + 20; n += 1) {
+    await elsewhere.append({
+      type: 'channel.created',
+      payload: { id: `far-${n}`, by: ada },
+    })
+  }
+  // Every consumer has run the other session's events.
+  await vi.waitFor(
+    async () => {
+      expect((await a2slackServer.drain('elsewhere')).settled).toBe(true)
+    },
+    { timeout: 10_000 },
+  )
+  const ownHead = (await room.history()).at(-1)!.index
+  expect(await position(db, FEED)).toBeLessThanOrEqual(ownHead)
+
+  await room.append({
+    type: 'message.posted',
+    payload: { channel: 'general', author: ada, text: 'still here' },
+  })
+  await caughtUp()
+  const page = await messagePage('general')
+  expect(page.messages.map((message) => message.text)).toContain('still here')
+})
+
+it('refuses NUL in text that the feed writes to Postgres', async () => {
+  await expect(
+    room.append({
+      type: 'message.posted',
+      payload: { channel: 'general', author: ada, text: 'a\u0000b' },
+    }),
+  ).rejects.toThrow(/invalid payload/)
+  await expect(
+    room.append({
+      type: 'message.posted',
+      payload: {
+        channel: 'general',
+        author: { id: 'user-\u0000', name: 'nul' },
+        text: 'hi',
+      },
+    }),
+  ).rejects.toThrow(/invalid payload/)
+})

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

@@ -0,0 +1,55 @@
+/**
+ * a2slack's server: one contract, one session, and the consumers that read
+ * its log. Each keeps its own place in the log, retries on its own, and
+ * either writes somewhere else or returns events into the log:
+ *
+ * - `welcome` posts a new channel's opening message.
+ * - `a2slack-feed` keeps the tables every page reads (db/schema.ts).
+ * - `a2slack-search-v1` keeps the search index in Upstash Redis Search,
+ *   where it's configured (search-index.ts).
+ * - `a2slack-notify` works out who should hear about each message, and
+ *   returns a notification addressed to each of them.
+ * - `a2slack-agent` is the bot, woken by the notifications addressed to it.
+ * - `a2slack-triage` labels top-level messages. It's off for now: AI Gateway
+ *   rejects its model, so every message retried until it dead-lettered.
+ *
+ * The bot and triage call a model, so they run only where AI Gateway is
+ * reachable.
+ */
+import 'server-only'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { createServer } from 'experimental-a2/server'
+import { store } from '@/lib/store'
+import { agent } from './consumers/agent'
+import { feed } from './consumers/feed'
+import { notify } from './consumers/notify'
+import { searchIndex } from './consumers/search'
+// import { triage } from './consumers/triage'
+import { welcome } from './consumers/welcome'
+import { workspace } from './model'
+import { hasSearchIndex } from './search-index'
+
+export const a2slackScheduler =
+  process.env.VERCEL || process.env.A2_QUEUES
+    ? vercelQueues({ topic: 'a2-a2slack' })
+    : undefined
+
+/** AI Gateway authenticates with an API key, or with the deployment's OIDC token. */
+const canReachGateway = Boolean(
+  process.env.AI_GATEWAY_API_KEY ||
+  process.env.VERCEL_OIDC_TOKEN ||
+  process.env.VERCEL,
+)
+
+export const a2slackServer = createServer({
+  ...(store ? { store } : {}),
+  ...(a2slackScheduler ? { scheduler: a2slackScheduler } : {}),
+  contract: workspace,
+  consumers: [
+    welcome,
+    feed,
+    notify,
+    ...(hasSearchIndex ? [searchIndex] : []),
+    ...(canReachGateway ? [agent /* , triage */] : []),
+  ],
+})

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

@@ -0,0 +1,50 @@
+/**
+ * The whole client/server seam: one client for the one workspace session.
+ * Its state is just the channel list (and when each opened); pages read everything else from the
+ * server and stay live from `events` (model.ts's live* helpers). Nothing in
+ * this file touches `experimental-a2/server`.
+ */
+'use client'
+import { createElement, type ReactNode } from 'react'
+import type { StateSnapshot } from 'experimental-a2'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { channelsReducer, workspace } from '@/app/a2slack/model'
+import { useIdentity } from '@/app/a2slack/identity'
+
+const workspaceClient = createClient({
+  contract: workspace,
+  api: '/a2slack/events',
+})
+
+const { SessionProvider, useSession } = createReact({
+  client: workspaceClient,
+})
+
+export const useWorkspace = useSession
+
+/**
+ * The workspace session, with whoever is typing as its participant. The
+ * name is picked in the browser, so the provider takes it from there; the
+ * session handle adopts it once it's known.
+ */
+export function WorkspaceProvider({
+  sessionId,
+  initial,
+  children,
+}: {
+  sessionId: string
+  initial: StateSnapshot<(typeof channelsReducer)['initialState']>
+  children: ReactNode
+}): ReactNode {
+  const identity = useIdentity()
+  return createElement(
+    SessionProvider,
+    {
+      sessionId,
+      initial,
+      ...(identity ? { participant: identity.id } : {}),
+    },
+    children,
+  )
+}

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

@@ -0,0 +1,8 @@
+import { threadPage } from '../db/queries'
+
+/** A thread's root and every reply. */
+export async function GET(request: Request): Promise<Response> {
+  const root = new URL(request.url).searchParams.get('root')
+  if (!root) return Response.json({ error: 'no root' }, { status: 400 })
+  return Response.json(await threadPage(root))
+}

package/examples/playground/app/a2slack/ui/ChannelView.tsx

@@ -0,0 +1,87 @@
+'use client'
+import { useMemo, type ReactNode } from 'react'
+import { usePathname, useSearchParams } from 'next/navigation'
+import { liveMessages, type MessagePage } from '@/app/a2slack/model'
+import { useWorkspace } from '../sessions'
+import { Composer } from './Composer'
+import { Feed } from './Feed'
+import { ThreadPanel } from './ThreadPanel'
+
+function Status(): ReactNode {
+  const { connection } = useWorkspace()
+  if (connection.status === 'live') {
+    return (
+      <span className="a2slack-status" data-status="live">
+        live
+      </span>
+    )
+  }
+  if (connection.status === 'connecting') {
+    return (
+      <span className="a2slack-status" data-status="connecting">
+        {connection.reconnects > 0 ? 'reconnecting…' : 'connecting…'}
+      </span>
+    )
+  }
+  return <span className="a2slack-status">offline</span>
+}
+
+/** One channel: its newest page from the server, kept live from the workspace's events. */
+export function ChannelView({
+  channel,
+  page,
+}: {
+  channel: string
+  page: MessagePage
+}): ReactNode {
+  const { events } = useWorkspace()
+  const pathname = usePathname()
+
+  // The open thread lives in the URL (?thread=<root message id>): deep
+  // links work, back closes the panel, and switching channels drops it.
+  // Native pushState is Next's shallow routing: useSearchParams tracks
+  // it without re-running the server component.
+  const threadId = useSearchParams().get('thread')
+  const openThread = (id: string): void =>
+    window.history.pushState(
+      null,
+      '',
+      `${pathname}?thread=${encodeURIComponent(id)}`,
+    )
+  const closeThread = (): void => window.history.pushState(null, '', pathname)
+
+  const newest = useMemo(
+    () => liveMessages(page, events, { channel, append: true }),
+    [page, events, channel],
+  )
+
+  return (
+    <div className="a2slack-split">
+      <div className="a2slack-view">
+        <header className="a2slack-header">
+          <span className="a2slack-header-name">#{channel}</span>
+          <Status />
+        </header>
+        <Feed
+          channel={channel}
+          newest={newest}
+          more={page.more}
+          onOpenThread={openThread}
+        />
+        <Composer
+          channel={channel}
+          placeholder={`message #${channel}… or ask @bot`}
+        />
+      </div>
+      {threadId !== null && (
+        <ThreadPanel
+          key={threadId}
+          channel={channel}
+          rootId={threadId}
+          known={newest.find((m) => m.id === threadId) ?? null}
+          onClose={closeThread}
+        />
+      )}
+    </div>
+  )
+}