@durable-streams/server 0.3.2 → 0.3.3

package/src/subscription-routes.ts

@@ -0,0 +1,504 @@
+import {
+  DEFAULT_LEASE_TTL_MS,
+  MAX_LEASE_TTL_MS,
+  MIN_LEASE_TTL_MS,
+  normalizeRelativePath,
+} from "./subscription-manager"
+import type { IncomingMessage, ServerResponse } from "node:http"
+import type { SubscriptionManager } from "./subscription-manager"
+import type {
+  SubscriptionCallbackRequest,
+  SubscriptionCreateInput,
+  SubscriptionErrorCode,
+  SubscriptionType,
+} from "./subscription-types"
+
+const RESERVED_CONTROL_PREFIX = `/v1/stream/__ds`
+const SUBSCRIPTION_PREFIX = `${RESERVED_CONTROL_PREFIX}/subscriptions/`
+const JWKS_PATH = `${RESERVED_CONTROL_PREFIX}/jwks.json`
+
+interface ParsedRoute {
+  subscriptionId: string
+  action:
+    | `base`
+    | `streams`
+    | `stream`
+    | `callback`
+    | `claim`
+    | `ack`
+    | `release`
+  streamPath?: string
+}
+
+const ERROR_STATUS: Record<SubscriptionErrorCode, number> = {
+  INVALID_REQUEST: 400,
+  SUBSCRIPTION_NOT_FOUND: 404,
+  SUBSCRIPTION_ALREADY_EXISTS: 409,
+  WEBHOOK_URL_REJECTED: 400,
+  TOKEN_INVALID: 401,
+  TOKEN_EXPIRED: 401,
+  FENCED: 409,
+  ALREADY_CLAIMED: 409,
+  NO_PENDING_WORK: 409,
+  INVALID_OFFSET: 409,
+}
+
+export class SubscriptionRoutes {
+  private readonly manager: SubscriptionManager
+
+  constructor(manager: SubscriptionManager) {
+    this.manager = manager
+  }
+
+  async handleRequest(
+    method: string,
+    path: string,
+    req: IncomingMessage,
+    res: ServerResponse
+  ): Promise<boolean> {
+    if (path === JWKS_PATH) {
+      this.handleJwks(method, res)
+      return true
+    }
+
+    const route = this.parseRoute(path)
+    if (!route) {
+      if (
+        path === RESERVED_CONTROL_PREFIX ||
+        path.startsWith(`${RESERVED_CONTROL_PREFIX}/`)
+      ) {
+        this.writeError(
+          res,
+          404,
+          `SUBSCRIPTION_NOT_FOUND`,
+          `Durable Streams control route not found`
+        )
+        return true
+      }
+      return false
+    }
+
+    try {
+      switch (route.action) {
+        case `base`:
+          await this.handleBase(route, method, req, res)
+          return true
+        case `streams`:
+          await this.handleStreams(route, method, req, res)
+          return true
+        case `stream`:
+          this.handleStream(route, method, res)
+          return true
+        case `callback`:
+          await this.handleCallback(route, req, res)
+          return true
+        case `claim`:
+          await this.handleClaim(route, req, res)
+          return true
+        case `ack`:
+          await this.handleAck(route, req, res)
+          return true
+        case `release`:
+          await this.handleRelease(route, req, res)
+          return true
+      }
+    } catch (err) {
+      if (err instanceof SyntaxError) {
+        this.writeError(res, 400, `INVALID_REQUEST`, `Invalid JSON body`)
+        return true
+      }
+      throw err
+    }
+  }
+
+  private async handleBase(
+    route: ParsedRoute,
+    method: string,
+    req: IncomingMessage,
+    res: ServerResponse
+  ): Promise<void> {
+    if (method === `PUT`) {
+      const parsed = await this.readJson(req)
+      const input = this.parseCreateInput(parsed)
+      if (`error` in input) {
+        this.writeError(res, 400, `INVALID_REQUEST`, input.error)
+        return
+      }
+
+      const result = this.manager.createOrConfirm(
+        route.subscriptionId,
+        input.value
+      )
+      if (`error` in result) {
+        this.writeError(
+          res,
+          ERROR_STATUS[result.error.code],
+          result.error.code,
+          result.error.message
+        )
+        return
+      }
+
+      this.writeJson(
+        res,
+        result.created ? 201 : 200,
+        this.manager.serialize(result.subscription)
+      )
+      return
+    }
+
+    if (method === `GET`) {
+      const subscription = this.manager.get(route.subscriptionId)
+      if (!subscription) {
+        this.writeError(
+          res,
+          404,
+          `SUBSCRIPTION_NOT_FOUND`,
+          `Subscription not found`
+        )
+        return
+      }
+      this.writeJson(res, 200, this.manager.serialize(subscription))
+      return
+    }
+
+    if (method === `DELETE`) {
+      this.manager.delete(route.subscriptionId)
+      res.writeHead(204)
+      res.end()
+      return
+    }
+
+    this.methodNotAllowed(res)
+  }
+
+  private handleJwks(method: string, res: ServerResponse): void {
+    if (method !== `GET`) {
+      this.methodNotAllowed(res)
+      return
+    }
+    res.writeHead(200, {
+      "content-type": `application/jwk-set+json`,
+      "cache-control": `public, max-age=300`,
+    })
+    res.end(JSON.stringify(this.manager.getWebhookJwks()))
+  }
+
+  private async handleStreams(
+    route: ParsedRoute,
+    method: string,
+    req: IncomingMessage,
+    res: ServerResponse
+  ): Promise<void> {
+    if (method !== `POST`) {
+      this.methodNotAllowed(res)
+      return
+    }
+    const parsed = await this.readJson(req)
+    const streams = (parsed as { streams?: unknown }).streams
+    if (
+      !Array.isArray(streams) ||
+      streams.some(
+        (stream) => typeof stream !== `string` || stream.length === 0
+      )
+    ) {
+      this.writeError(
+        res,
+        400,
+        `INVALID_REQUEST`,
+        `streams must be a non-empty string array`
+      )
+      return
+    }
+    const ok = this.manager.addExplicitStreams(
+      route.subscriptionId,
+      streams.map(normalizeRelativePath)
+    )
+    if (!ok) {
+      this.writeError(
+        res,
+        404,
+        `SUBSCRIPTION_NOT_FOUND`,
+        `Subscription not found`
+      )
+      return
+    }
+    res.writeHead(204)
+    res.end()
+  }
+
+  private handleStream(
+    route: ParsedRoute,
+    method: string,
+    res: ServerResponse
+  ): void {
+    if (method !== `DELETE`) {
+      this.methodNotAllowed(res)
+      return
+    }
+    const ok = this.manager.removeExplicitStream(
+      route.subscriptionId,
+      route.streamPath ?? ``
+    )
+    if (!ok) {
+      this.writeError(
+        res,
+        404,
+        `SUBSCRIPTION_NOT_FOUND`,
+        `Subscription not found`
+      )
+      return
+    }
+    res.writeHead(204)
+    res.end()
+  }
+
+  private async handleCallback(
+    route: ParsedRoute,
+    req: IncomingMessage,
+    res: ServerResponse
+  ): Promise<void> {
+    const token = this.readBearerToken(req)
+    if (!token) {
+      this.writeError(
+        res,
+        401,
+        `TOKEN_INVALID`,
+        `Missing or malformed Authorization header`
+      )
+      return
+    }
+    const body = (await this.readJson(req)) as SubscriptionCallbackRequest
+    const result = await this.manager.handleWebhookCallback(
+      route.subscriptionId,
+      token,
+      body
+    )
+    this.writeManagerResult(res, result)
+  }
+
+  private async handleClaim(
+    route: ParsedRoute,
+    req: IncomingMessage,
+    res: ServerResponse
+  ): Promise<void> {
+    const parsed = await this.readJson(req)
+    const worker = (parsed as { worker?: unknown }).worker
+    if (typeof worker !== `string` || worker.length === 0) {
+      this.writeError(
+        res,
+        400,
+        `INVALID_REQUEST`,
+        `worker must be a non-empty string`
+      )
+      return
+    }
+    const result = await this.manager.claim(route.subscriptionId, worker)
+    this.writeManagerResult(res, result)
+  }
+
+  private async handleAck(
+    route: ParsedRoute,
+    req: IncomingMessage,
+    res: ServerResponse
+  ): Promise<void> {
+    const token = this.readBearerToken(req)
+    if (!token) {
+      this.writeError(
+        res,
+        401,
+        `TOKEN_INVALID`,
+        `Missing or malformed Authorization header`
+      )
+      return
+    }
+    const body = (await this.readJson(req)) as SubscriptionCallbackRequest
+    const result = await this.manager.ack(route.subscriptionId, token, body)
+    this.writeManagerResult(res, result)
+  }
+
+  private async handleRelease(
+    route: ParsedRoute,
+    req: IncomingMessage,
+    res: ServerResponse
+  ): Promise<void> {
+    const token = this.readBearerToken(req)
+    if (!token) {
+      this.writeError(
+        res,
+        401,
+        `TOKEN_INVALID`,
+        `Missing or malformed Authorization header`
+      )
+      return
+    }
+    const body = (await this.readJson(req)) as SubscriptionCallbackRequest
+    const result = await this.manager.release(route.subscriptionId, token, body)
+    this.writeManagerResult(res, result)
+  }
+
+  private parseCreateInput(
+    value: unknown
+  ): { value: SubscriptionCreateInput } | { error: string } {
+    if (!value || typeof value !== `object`) {
+      return { error: `Request body must be a JSON object` }
+    }
+    const payload = value as Record<string, unknown>
+    if (payload.type !== `webhook` && payload.type !== `pull-wake`) {
+      return { error: `type must be "webhook" or "pull-wake"` }
+    }
+    const type = payload.type as SubscriptionType
+    const pattern =
+      typeof payload.pattern === `string` && payload.pattern.length > 0
+        ? normalizeRelativePath(payload.pattern)
+        : undefined
+    const streams =
+      Array.isArray(payload.streams) && payload.streams.length > 0
+        ? payload.streams.map((stream) =>
+            typeof stream === `string` ? normalizeRelativePath(stream) : null
+          )
+        : []
+    if (streams.some((stream) => stream === null)) {
+      return { error: `streams must contain only strings` }
+    }
+    if (!pattern && streams.length === 0) {
+      return { error: `At least one of pattern or streams is required` }
+    }
+
+    const leaseTtl =
+      payload.lease_ttl_ms === undefined
+        ? DEFAULT_LEASE_TTL_MS
+        : payload.lease_ttl_ms
+    if (
+      typeof leaseTtl !== `number` ||
+      !Number.isInteger(leaseTtl) ||
+      leaseTtl < MIN_LEASE_TTL_MS ||
+      leaseTtl > MAX_LEASE_TTL_MS
+    ) {
+      return { error: `lease_ttl_ms must be an integer from 1000 to 600000` }
+    }
+
+    let webhook: { url: string } | undefined
+    if (type === `webhook`) {
+      const rawWebhook = payload.webhook
+      if (!rawWebhook || typeof rawWebhook !== `object`) {
+        return { error: `webhook subscriptions require webhook.url` }
+      }
+      const url = (rawWebhook as { url?: unknown }).url
+      if (typeof url !== `string` || url.length === 0) {
+        return { error: `webhook subscriptions require webhook.url` }
+      }
+      webhook = { url }
+    }
+
+    const wakeStream =
+      typeof payload.wake_stream === `string` && payload.wake_stream.length > 0
+        ? normalizeRelativePath(payload.wake_stream)
+        : undefined
+    if (type === `pull-wake` && !wakeStream) {
+      return { error: `pull-wake subscriptions require wake_stream` }
+    }
+
+    return {
+      value: {
+        type,
+        pattern,
+        streams: streams as Array<string>,
+        webhook,
+        wake_stream: wakeStream,
+        lease_ttl_ms: leaseTtl,
+        description:
+          typeof payload.description === `string`
+            ? payload.description
+            : undefined,
+      },
+    }
+  }
+
+  private parseRoute(path: string): ParsedRoute | null {
+    if (!path.startsWith(SUBSCRIPTION_PREFIX)) return null
+
+    const rest = path.slice(SUBSCRIPTION_PREFIX.length)
+    const parts = rest.split(`/`)
+    const subscriptionId = parts[0] ? decodeURIComponent(parts[0]) : ``
+    if (!subscriptionId) return null
+
+    const tail = parts.slice(1)
+    if (tail.length === 0) {
+      return { subscriptionId, action: `base` }
+    }
+    if (tail[0] === `streams` && tail.length === 1) {
+      return { subscriptionId, action: `streams` }
+    }
+    if (tail[0] === `streams` && tail.length > 1) {
+      return {
+        subscriptionId,
+        action: `stream`,
+        streamPath: normalizeRelativePath(
+          decodeURIComponent(tail.slice(1).join(`/`))
+        ),
+      }
+    }
+    if (
+      tail.length === 1 &&
+      [`callback`, `claim`, `ack`, `release`].includes(tail[0]!)
+    ) {
+      return {
+        subscriptionId,
+        action: tail[0] as ParsedRoute[`action`],
+      }
+    }
+
+    return null
+  }
+
+  private readBearerToken(req: IncomingMessage): string | null {
+    const authHeader = req.headers.authorization
+    if (!authHeader || !authHeader.startsWith(`Bearer `)) return null
+    return authHeader.slice(`Bearer `.length)
+  }
+
+  private async readJson(req: IncomingMessage): Promise<unknown> {
+    const chunks: Array<Buffer> = []
+    for await (const chunk of req) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+    }
+    const raw = Buffer.concat(chunks).toString(`utf8`)
+    return raw.length > 0 ? JSON.parse(raw) : {}
+  }
+
+  private writeManagerResult(
+    res: ServerResponse,
+    result: { status: number; body?: Record<string, unknown> }
+  ): void {
+    if (result.status === 204) {
+      res.writeHead(204)
+      res.end()
+      return
+    }
+    this.writeJson(res, result.status, result.body ?? {})
+  }
+
+  private writeJson(
+    res: ServerResponse,
+    status: number,
+    body: Record<string, unknown>
+  ): void {
+    res.writeHead(status, { "content-type": `application/json` })
+    res.end(JSON.stringify(body))
+  }
+
+  private writeError(
+    res: ServerResponse,
+    status: number,
+    code: SubscriptionErrorCode,
+    message: string
+  ): void {
+    this.writeJson(res, status, { error: { code, message } })
+  }
+
+  private methodNotAllowed(res: ServerResponse): void {
+    res.writeHead(405, { "content-type": `text/plain` })
+    res.end(`Method not allowed`)
+  }
+}

package/src/subscription-types.ts

@@ -0,0 +1,80 @@
+export type SubscriptionType = `webhook` | `pull-wake`
+export type SubscriptionStatus = `active` | `failed`
+export type SubscriptionLinkType = `glob` | `explicit`
+
+export interface SubscriptionStreamLink {
+  path: string
+  link_types: Set<SubscriptionLinkType>
+  acked_offset: string
+}
+
+export interface SubscriptionWebhookConfig {
+  url: string
+}
+
+export interface SubscriptionRecord {
+  id: string
+  type: SubscriptionType
+  pattern?: string
+  webhook?: SubscriptionWebhookConfig
+  wake_stream?: string
+  lease_ttl_ms: number
+  description?: string
+  created_at: string
+  status: SubscriptionStatus
+  config_hash: string
+  streams: Map<string, SubscriptionStreamLink>
+  generation: number
+  wake_id: string | null
+  wake_snapshot: Map<string, string>
+  token: string | null
+  holder: string | null
+  lease_timer: ReturnType<typeof setTimeout> | null
+  retry_count: number
+  retry_timer: ReturnType<typeof setTimeout> | null
+  next_attempt_at: number | null
+}
+
+export interface SubscriptionStreamInfo {
+  path: string
+  link_type: SubscriptionLinkType
+  acked_offset: string
+  tail_offset: string
+  has_pending: boolean
+}
+
+export interface SubscriptionCreateInput {
+  type: SubscriptionType
+  pattern?: string
+  streams: Array<string>
+  webhook?: { url: string }
+  wake_stream?: string
+  lease_ttl_ms: number
+  description?: string
+}
+
+export interface SubscriptionCallbackRequest {
+  wake_id?: string
+  generation?: number
+  acks?: Array<{ stream?: string; path?: string; offset: string }>
+  done?: boolean
+}
+
+export type SubscriptionErrorCode =
+  | `INVALID_REQUEST`
+  | `SUBSCRIPTION_NOT_FOUND`
+  | `SUBSCRIPTION_ALREADY_EXISTS`
+  | `WEBHOOK_URL_REJECTED`
+  | `TOKEN_INVALID`
+  | `TOKEN_EXPIRED`
+  | `FENCED`
+  | `ALREADY_CLAIMED`
+  | `NO_PENDING_WORK`
+  | `INVALID_OFFSET`
+
+export interface SubscriptionError {
+  code: SubscriptionErrorCode
+  message: string
+  current_holder?: string
+  generation?: number
+}

package/src/types.ts

@@ -206,6 +206,14 @@ export interface TestServerOptions {
    * Default: October 9, 2024 00:00:00 UTC.
    */
   cursorEpoch?: Date
+
+  /**
+   * Enable webhook subscriptions.
+   * Pull-wake subscription routes are always mounted, but type=webhook creates
+   * are rejected unless this is true.
+   * Default: false.
+   */
+  webhooks?: boolean
 }
 
 /**