experimental-a2 0.6.0 → 0.7.0

package/src/internal.ts

@@ -4,7 +4,7 @@
  */
 
 import type { ScheduledEvent } from './scheduler-task.ts'
-import type { A2Scheduler, DrainableServer } from './server.ts'
+import type { DrainableServer } from './server.ts'
 
 export type DrainOutcome = 'busy' | 'stalled' | 'settled'
 
@@ -67,14 +67,6 @@ export type ServerInternals = {
 
 export const serverInternals: WeakMap<object, ServerInternals> = new WeakMap()
 
-type ServerSchedulerBinding = {
-  scheduler: A2Scheduler | undefined
-}
-
-/** Scheduler configuration captured only for servers made by `createServer`. */
-export const serverSchedulerBindings: WeakMap<object, ServerSchedulerBinding> =
-  new WeakMap()
-
 const objectLike = (value: unknown): value is object =>
   (typeof value === 'object' && value !== null) || typeof value === 'function'
 
@@ -232,13 +224,11 @@ const isDrainableServer = (value: unknown): value is DrainableServer => {
 
 /**
  * Validate the server list captured by a scheduler route at construction time.
- * Built-in adapters keep their low-level target seam structural for custom
- * integrations. The application-facing `schedulerHandler` uses strict mode
- * so only servers made by this A2 copy reach a configured adapter.
+ * The seam stays structural so custom scheduler integrations can supply their
+ * own drainable targets.
  */
 export function assertSchedulerTargets(
   servers: readonly unknown[],
-  options: { allowStructural: boolean },
 ): asserts servers is readonly DrainableServer[] {
   const contracts = new Set<string>()
   for (const target of servers) {
@@ -252,56 +242,7 @@ export function assertSchedulerTargets(
       )
     }
     contracts.add(name)
-
-    const binding = serverSchedulerBindings.get(target)
-    if (!binding) {
-      if (!options.allowStructural) {
-        throw new TypeError(
-          `a2 scheduler: server for contract '${name}' was not created by createServer()`,
-        )
-      }
-      continue
-    }
-  }
-}
-
-/** Require every real server to share one exact configured scheduler. */
-export function assertServerSchedulerBindings(
-  scheduler: A2Scheduler,
-  servers: readonly DrainableServer[],
-): void {
-  for (const server of servers) {
-    const binding = serverSchedulerBindings.get(server)
-    if (!binding?.scheduler) {
-      throw new TypeError(
-        `a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`,
-      )
-    }
-    if (binding.scheduler !== scheduler) {
-      throw new TypeError(
-        `a2 scheduler: server for contract '${server.contract.name}' is configured with a different scheduler instance`,
-      )
-    }
-  }
-}
-
-/** Resolve the scheduler privately bound to a real A2 server. */
-export function schedulerForServer(server: unknown): A2Scheduler {
-  if (!isDrainableServer(server)) {
-    throw new TypeError('a2 scheduler: expected a server from createServer()')
-  }
-  const binding = serverSchedulerBindings.get(server)
-  if (!binding) {
-    throw new TypeError(
-      `a2 scheduler: server for contract '${server.contract.name}' was not created by createServer()`,
-    )
-  }
-  if (!binding.scheduler) {
-    throw new TypeError(
-      `a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`,
-    )
   }
-  return binding.scheduler
 }
 
 /**

package/src/push-envelope.ts

@@ -1,14 +1,25 @@
 /**
- * The push envelope's trust boundary — parsing and provenance-branding
- * for `{ sessionId, events, presence? }`, shared verbatim by the HTTP
+ * The push envelope's trust boundary for `{ sessionId, events, presence? }`,
+ * shared verbatim by the HTTP
  * POST lane and the socket's push/presence frames so INVALID_PAYLOAD
- * shapes are one implementation. Internal module — `handle` (and the
- * socket handler) compose it; it is not part of the public surface.
+ * shapes are one implementation. Internal module, not public API.
  */
 
 import { A2Error } from './errors.ts'
 import { MAX_DATE_MS, RESERVED_PARTICIPANT_IDS } from './internal.ts'
-import type { PushedEvent, PushedPresence } from './server.ts'
+
+export type ParsedPushEvent = {
+  type: string
+  payload: unknown
+  id?: string
+}
+
+export type ParsedPushPresence = {
+  participant: string
+  values: Record<string, unknown>
+  seen?: number
+  at?: number
+}
 
 export const invalidPushBody = (message: string): A2Error =>
   new A2Error('INVALID_PAYLOAD', `malformed push body: ${message}`)
@@ -17,18 +28,13 @@ const invalid = invalidPushBody
 
 export type PushBody = {
   sessionId: string
-  /** Branded: `session.append` accepts these directly (the push route
-   * path); schema validation still happens inside `append`. Empty only
-   * for a presence-only push. */
-  events: PushedEvent[]
-  /** Branded like `events`: `session.setPresence` accepts it whole;
-   * field validation still happens inside `setPresence`. */
-  presence?: PushedPresence
+  events: ParsedPushEvent[]
+  presence?: ParsedPushPresence
 }
 
 export function parsePresenceSibling(
   value: unknown,
-): PushedPresence | undefined {
+): ParsedPushPresence | undefined {
   if (value === undefined) return undefined
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     throw invalid('presence must be an object when present')
@@ -68,14 +74,12 @@ export function parsePresenceSibling(
   } = { participant, values: values as Record<string, unknown> }
   if (seen !== undefined) out.seen = seen
   if (at !== undefined) out.at = at
-  Object.defineProperty(out, '~a2.pushed', { value: true })
-  return out as PushedPresence
+  return out
 }
 
-/** The events half of the envelope — shared verbatim by the POST body
- * and the socket's `push` frames, so the provenance brand and the
- * INVALID_PAYLOAD shapes are one implementation. */
-export function parsePushEvents(events: unknown): PushedEvent[] {
+/** The events half of the envelope, shared by the POST body and socket
+ * `push` frames so INVALID_PAYLOAD shapes have one implementation. */
+export function parsePushEvents(events: unknown): ParsedPushEvent[] {
   if (!Array.isArray(events) || events.length === 0) {
     throw invalid('events must be a non-empty array')
   }
@@ -95,8 +99,7 @@ export function parsePushEvents(events: unknown): PushedEvent[] {
       payload,
     }
     if (id !== undefined) out.id = id
-    Object.defineProperty(out, '~a2.pushed', { value: true })
-    return out as PushedEvent
+    return out
   })
 }
 

package/src/scheduler-qstash.ts

@@ -94,7 +94,7 @@ export type QStashTransport = {
 }
 
 export type QStashSchedulerOptions = {
-  /** Exact URL mounted with `schedulerHandler(...)`. Inferred in local dev and on Vercel. */
+  /** Exact URL mounted with `scheduler.handler(...)`. Inferred in local dev and on Vercel. */
   url?: string
   /** QStash API token. Default: `QSTASH_TOKEN`. */
   token?: string
@@ -819,7 +819,7 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
     },
 
     handler(...servers: DrainableServer[]) {
-      assertSchedulerTargets(servers, { allowStructural: true })
+      assertSchedulerTargets(servers)
       const byContract = new Map<string, DrainableServer>()
       for (const server of servers) {
         byContract.set(server.contract.name, server)
@@ -851,7 +851,7 @@ export function qstash(options: QStashSchedulerOptions = {}): A2Scheduler {
         const server = byContract.get(task.contract)
         if (!server) {
           throw new Error(
-            `a2 scheduler: no server for contract '${task.contract}' — pass it to schedulerHandler(...)`,
+            `a2 scheduler: no server for contract '${task.contract}' — pass it to scheduler.handler(...)`,
           )
         }
         const internals = serverInternals.get(server)

package/src/scheduler-vercel.ts

@@ -368,7 +368,7 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
     },
 
     handler(...servers: DrainableServer[]) {
-      assertSchedulerTargets(servers, { allowStructural: true })
+      assertSchedulerTargets(servers)
       const byContract = new Map<string, DrainableServer>()
       for (const server of servers) {
         byContract.set(server.contract.name, server)
@@ -386,7 +386,7 @@ export function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {
             // wiring bug — throw so it redelivers and stays visible in
             // queue observability instead of vanishing on an ack.
             throw new Error(
-              `a2 scheduler: no server for contract '${task.contract}' — pass it to schedulerHandler(...)`,
+              `a2 scheduler: no server for contract '${task.contract}' — pass it to scheduler.handler(...)`,
             )
           }
           const internals = serverInternals.get(server)

package/src/server-fetch.ts

@@ -0,0 +1,344 @@
+import type {
+  AppendInput,
+  ContractEvent,
+  EventDefs,
+  PresenceDefs,
+} from './contract.ts'
+import { A2Error } from './errors.ts'
+import { invocationDeadlineMs } from './platform.ts'
+import {
+  invalidPushBody,
+  parsePushBody,
+  type ParsedPushEvent,
+  type ParsedPushPresence,
+} from './push-envelope.ts'
+import type { A2Server } from './server.ts'
+import {
+  sessionsSocket,
+  type A2Socket,
+  type SocketSession,
+} from './session-socket.ts'
+import { sseResponse } from './sse.ts'
+import { asA2Error, errorStatus, errorToWire, eventToWire } from './wire.ts'
+
+type SuggestedEventType<D extends EventDefs> =
+  (keyof D & string) | (string & Record<never, never>)
+
+type SuggestedPresenceValues<P extends PresenceDefs> = Readonly<
+  { [F in keyof P & string]?: unknown } & Record<string, unknown>
+>
+
+export type A2PushEvent<D extends EventDefs = EventDefs> = {
+  readonly type: SuggestedEventType<D>
+  readonly payload: unknown
+  readonly id?: string
+}
+
+export type A2PushPresence<P extends PresenceDefs = PresenceDefs> = {
+  readonly participant: string
+  readonly values: SuggestedPresenceValues<P>
+  readonly seen?: number
+  readonly at?: number
+}
+
+export type A2Operation<
+  D extends EventDefs = EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+> =
+  | {
+      readonly type: 'stream'
+      readonly sessionId: string
+      readonly startAfter: number
+      readonly transport: 'http' | 'websocket'
+    }
+  | {
+      readonly type: 'history'
+      readonly sessionId: string
+      readonly gte: number
+      readonly lte: number
+      readonly transport: 'http'
+    }
+  | {
+      readonly type: 'push'
+      readonly sessionId: string
+      readonly events: readonly A2PushEvent<D>[]
+      readonly presence?: A2PushPresence<P>
+      readonly transport: 'http' | 'websocket'
+    }
+
+export type UpgradeWebSocket = (
+  attach: (socket: A2Socket) => void,
+) => Response | Promise<Response>
+
+export type ServerFetchOptions<
+  D extends EventDefs = EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  authorize?: (operation: A2Operation<D, P>) => boolean | Promise<boolean>
+  upgradeWebSocket?: UpgradeWebSocket
+}
+
+export type ServerIngressContext = {
+  sessionId: string
+  events: readonly ParsedPushEvent[]
+  presence?: ParsedPushPresence
+}
+
+type ServerFetchHooks = {
+  validateIngress?(context: ServerIngressContext): void | PromiseLike<void>
+}
+
+const serverFetchHooks = new WeakMap<object, ServerFetchHooks>()
+
+export function setServerFetchHooks<
+  D extends EventDefs,
+  P extends PresenceDefs,
+>(server: Pick<A2Server<D, P>, 'fetch'>, hooks: ServerFetchHooks): void {
+  serverFetchHooks.set(server.fetch, hooks)
+}
+
+type FetchServer<D extends EventDefs, P extends PresenceDefs> = Pick<
+  A2Server<D, P>,
+  'contract' | 'session'
+>
+
+type ServerFetch<D extends EventDefs, P extends PresenceDefs> = {
+  (request: Request): Promise<Response>
+  (request: Request, options: ServerFetchOptions<D, P>): Promise<Response>
+}
+
+const parseHistoryBounds = (
+  gte: string | null,
+  lte: string | null,
+): { gte: number; lte: number } => {
+  if (gte === null || lte === null) {
+    throw new A2Error(
+      'INVALID_PAYLOAD',
+      'a history read takes both gte and lte',
+    )
+  }
+  const bounds = { gte: Number(gte), lte: Number(lte) }
+  for (const [name, value] of Object.entries(bounds)) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new A2Error(
+        'INVALID_PAYLOAD',
+        `history ${name} must be a non-negative safe integer`,
+      )
+    }
+  }
+  if (bounds.gte > bounds.lte) {
+    throw new A2Error(
+      'INVALID_PAYLOAD',
+      'history gte must be less than or equal to lte',
+    )
+  }
+  return bounds
+}
+
+const parseResumeIndex = (raw: string | null): number => {
+  if (raw === null) return 0
+  const index = Number(raw)
+  if (!Number.isSafeInteger(index) || index < 0) {
+    throw new A2Error(
+      'INVALID_PAYLOAD',
+      'stream index must be a non-negative safe integer',
+    )
+  }
+  return index
+}
+
+const errorResponse = (error: unknown): Response => {
+  const a2error = asA2Error(error)
+  return Response.json(errorToWire(a2error), {
+    status: errorStatus(a2error.code),
+  })
+}
+
+const forbidden = (): A2Error =>
+  new A2Error('FORBIDDEN', 'the operation is not authorized')
+
+const freezePush = <D extends EventDefs, P extends PresenceDefs>(
+  sessionId: string,
+  events: ParsedPushEvent[],
+  presence: ParsedPushPresence | undefined,
+  transport: 'http' | 'websocket',
+): A2Operation<D, P> & { type: 'push' } => {
+  for (const event of events) Object.freeze(event)
+  Object.freeze(events)
+  if (presence !== undefined) {
+    Object.freeze(presence.values)
+    Object.freeze(presence)
+  }
+  return {
+    type: 'push',
+    sessionId,
+    events,
+    ...(presence === undefined
+      ? {}
+      : { presence: presence as A2PushPresence<P> }),
+    transport,
+  }
+}
+
+export function createServerFetch<
+  D extends EventDefs,
+  P extends PresenceDefs = Record<never, never>,
+>(server: FetchServer<D, P>): ServerFetch<D, P> {
+  const presence = Object.keys(server.contract.presence).length > 0
+
+  const fetch = async (
+    request: Request,
+    options?: ServerFetchOptions<D, P>,
+  ): Promise<Response> => {
+    const authorized = async (
+      operation: A2Operation<D, P>,
+    ): Promise<boolean> => {
+      try {
+        return (await options?.authorize?.(Object.freeze(operation))) !== false
+      } catch (cause) {
+        throw new A2Error('STORE_UNAVAILABLE', 'authorization failed', {
+          cause,
+        })
+      }
+    }
+
+    const authorize = async (operation: A2Operation<D, P>): Promise<void> => {
+      if (!(await authorized(operation))) throw forbidden()
+    }
+
+    const validateIngress = async (
+      context: ServerIngressContext,
+    ): Promise<void> => {
+      await serverFetchHooks.get(fetch)?.validateIngress?.(context)
+    }
+
+    const attach = (socket: A2Socket): void => {
+      const deadline = invocationDeadlineMs()
+      sessionsSocket<D>(
+        async (sessionId, startAfter) => {
+          const operation: A2Operation<D, P> = {
+            type: 'stream',
+            sessionId,
+            startAfter,
+            transport: 'websocket',
+          }
+          return (await authorized(operation))
+            ? server.session(sessionId)
+            : null
+        },
+        socket,
+        {
+          presence,
+          ...(deadline === null ? {} : { deadline }),
+          gatePush: async (sessionId, events, pushedPresence) => {
+            try {
+              await authorize(
+                freezePush<D, P>(
+                  sessionId,
+                  events,
+                  pushedPresence,
+                  'websocket',
+                ),
+              )
+              await validateIngress({
+                sessionId,
+                events,
+                ...(pushedPresence === undefined
+                  ? {}
+                  : { presence: pushedPresence }),
+              })
+              return null
+            } catch (error) {
+              return asA2Error(error)
+            }
+          },
+        },
+      )
+    }
+
+    try {
+      if (request.method === 'GET') {
+        if (request.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+          if (options?.upgradeWebSocket === undefined) {
+            return new Response(
+              'WebSocket upgrade requested, but server.fetch() has no upgrade implementation',
+              { status: 426 },
+            )
+          }
+          return await options.upgradeWebSocket(attach)
+        }
+
+        const { searchParams } = new URL(request.url)
+        const sessionId = searchParams.get('sessionId')
+        if (sessionId === null || sessionId.length === 0) {
+          throw new A2Error('INVALID_PAYLOAD', 'missing sessionId')
+        }
+        const gteRaw = searchParams.get('gte')
+        const lteRaw = searchParams.get('lte')
+        if (gteRaw !== null || lteRaw !== null) {
+          const bounds = parseHistoryBounds(gteRaw, lteRaw)
+          await authorize({
+            type: 'history',
+            sessionId,
+            ...bounds,
+            transport: 'http',
+          })
+          const events = await server.session(sessionId).history(bounds)
+          const covered = events.length === bounds.lte - bounds.gte + 1
+          return Response.json(events.map(eventToWire), {
+            headers: { 'a2-history-covered': String(covered) },
+          })
+        }
+
+        const startAfter = parseResumeIndex(searchParams.get('index'))
+        await authorize({
+          type: 'stream',
+          sessionId,
+          startAfter,
+          transport: 'http',
+        })
+        const target = server.session(sessionId) as unknown as SocketSession
+        return sseResponse(
+          presence
+            ? target.stream({ startAfter, presence: true })
+            : target.stream({ startAfter }),
+        )
+      }
+
+      if (request.method === 'POST') {
+        const body = await parsePushBody(request)
+        await authorize(
+          freezePush<D, P>(body.sessionId, body.events, body.presence, 'http'),
+        )
+        await validateIngress({
+          sessionId: body.sessionId,
+          events: body.events,
+          ...(body.presence === undefined ? {} : { presence: body.presence }),
+        })
+        const session = server.session(body.sessionId)
+        if (body.presence !== undefined) {
+          const target = session as unknown as SocketSession
+          if (typeof target.setPresence !== 'function') {
+            throw invalidPushBody('presence is not declared by this contract')
+          }
+          await target.setPresence(body.presence)
+        }
+        const appended: ContractEvent<D>[] =
+          body.events.length === 0
+            ? []
+            : await session.append(
+                ...(body.events as unknown as AppendInput<D>[]),
+              )
+        return Response.json(appended.map(eventToWire))
+      }
+
+      return new Response('Method Not Allowed', {
+        status: 405,
+        headers: { allow: 'GET, POST' },
+      })
+    } catch (error) {
+      return errorResponse(error)
+    }
+  }
+  return fetch
+}