experimental-a2 0.5.1 → 0.7.0

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
+}