@owlmeans/queue 0.1.18-rc.2 → 0.1.18-rc.21

package/src/errors.ts

@@ -0,0 +1,106 @@
+import { ResilientError } from '@owlmeans/error'
+
+export class QueueError extends ResilientError {
+  public static override typeName = 'QueueError'
+
+  constructor(message: string = 'error') {
+    super(QueueError.typeName, `queue:${message}`)
+  }
+}
+
+/**
+ * The caller stopped waiting. The job is untouched — it may still be queued, running, or already
+ * finished; only the wait ended. Read the job back to learn which.
+ */
+export class QueueTimeout extends QueueError {
+  public static override typeName = `${QueueError.typeName}Timeout`
+
+  constructor(msg: string) {
+    super(`timeout:${msg}`)
+    this.type = QueueTimeout.typeName
+  }
+}
+
+/** No job with that id in this queue — it never existed, or it was removed after completing. */
+export class UnknownJob extends QueueError {
+  public static override typeName = `${QueueError.typeName}UnknownJob`
+
+  constructor(msg: string) {
+    super(`unknown-job:${msg}`)
+    this.type = UnknownJob.typeName
+  }
+}
+
+/**
+ * A job name the queue does not declare. Declaring every job a queue accepts is what keeps an
+ * enqueue from succeeding into a queue where nothing can ever process it.
+ */
+export class UnknownJobName extends QueueError {
+  public static override typeName = `${QueueError.typeName}UnknownJobName`
+
+  constructor(msg: string) {
+    super(`unknown-job-name:${msg}`)
+    this.type = UnknownJobName.typeName
+  }
+}
+
+/** A queue asked for that no declaration names. */
+export class UnknownQueue extends QueueError {
+  public static override typeName = `${QueueError.typeName}UnknownQueue`
+
+  constructor(msg: string) {
+    super(`unknown-queue:${msg}`)
+    this.type = UnknownQueue.typeName
+  }
+}
+
+/**
+ * This process was asked to consume a queue it does not listen to. Which queues a process
+ * consumes is configuration (`cfg.queue.listen`), so this is a deployment question, not a code
+ * one — the same binary is a producer or a worker depending on it.
+ */
+export class QueueNotListening extends QueueError {
+  public static override typeName = `${QueueError.typeName}NotListening`
+
+  constructor(msg: string) {
+    super(`not-listening:${msg}`)
+    this.type = QueueNotListening.typeName
+  }
+}
+
+/**
+ * The job named an entrypoint this process does not serve. Unlike a missing queue this is not a
+ * declaration problem: the alias exists, but nothing here bound it, so the job was taken by a
+ * worker that cannot run it.
+ */
+export class JobNotServed extends QueueError {
+  public static override typeName = `${QueueError.typeName}JobNotServed`
+
+  constructor(msg: string) {
+    super(`job-not-served:${msg}`)
+    this.type = JobNotServed.typeName
+  }
+}
+
+/**
+ * The signed envelope is older than the configured lifetime. Freshness is judged from when the
+ * producer enqueued the job, not from when a worker picked it up, so a long backlog does not
+ * invalidate work that was legitimate when it was submitted.
+ */
+export class EnvelopeExpired extends QueueError {
+  public static override typeName = `${QueueError.typeName}EnvelopeExpired`
+
+  constructor(msg: string) {
+    super(`envelope-expired:${msg}`)
+    this.type = EnvelopeExpired.typeName
+  }
+}
+
+ResilientError.registerErrorClass(QueueError)
+ResilientError.registerErrorClass(QueueTimeout)
+ResilientError.registerErrorClass(UnknownJob)
+ResilientError.registerErrorClass(UnknownJobName)
+ResilientError.registerErrorClass(UnknownQueue)
+ResilientError.registerErrorClass(QueueNotListening)
+ResilientError.registerErrorClass(JobNotServed)
+ResilientError.registerErrorClass(EnvelopeExpired)

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './types.js'
+export * from './consts.js'
+export * from './errors.js'
+export * from './config.js'
+export * from './transport.js'
+export * from './bridge.js'
+export * from './worker.js'
+export * from './protocol.js'

package/src/protocol.ts

@@ -0,0 +1,81 @@
+import type { EntrypointProtocolDeclaration, RequestOf, ResponseOf } from '@owlmeans/entrypoint'
+import { isEntrypointProtocol } from '@owlmeans/entrypoint'
+import { ResilientError } from '@owlmeans/error'
+import { RouteProtocols } from '@owlmeans/route'
+import { queueOf } from './config.js'
+import { UnknownQueue } from './errors.js'
+import type {
+  Config, Context, JobEnvelope, JobOptions, JobRecord, JobReply, QueueAppend,
+} from './types.js'
+
+type QueueContext = Context<Config> & QueueAppend
+
+const queueFor = (context: QueueContext, declaration: unknown): {
+  protocol: EntrypointProtocolDeclaration
+  queue: string
+} => {
+  if (declaration == null || typeof declaration !== 'object' || !isEntrypointProtocol(declaration)) {
+    throw new UnknownQueue('protocol declaration required')
+  }
+  if (declaration.route.route.protocol !== RouteProtocols.QUEUE) {
+    throw new UnknownQueue(`${declaration.alias}: not a QUEUE protocol`)
+  }
+  const queue = declaration.route.route.queue
+  if (queue == null) {
+    throw new UnknownQueue(`${declaration.alias}: route declares no queue`)
+  }
+  const configured = queueOf(context.cfg, queue)
+  if (!configured.jobs.includes(declaration.alias)) {
+    throw new UnknownQueue(`${queue}:${declaration.alias}`)
+  }
+  return { protocol: declaration, queue }
+}
+
+/** Enqueue an immutable QUEUE protocol while preserving its exact request and response types. */
+export const enqueueProtocol = async <Protocol extends EntrypointProtocolDeclaration>(
+  context: QueueContext,
+  declaration: Protocol,
+  request: RequestOf<Protocol>,
+  options?: JobOptions,
+): Promise<JobRecord<JobEnvelope, JobReply<ResponseOf<Protocol>>>> => {
+  const { protocol, queue } = queueFor(context, declaration)
+  const shaped = (request ?? {}) as unknown as Record<string, unknown>
+  const envelope: JobEnvelope = {
+    alias: protocol.alias,
+    params: shaped.params as Record<string, unknown> | undefined,
+    body: shaped.body,
+    query: shaped.query as Record<string, unknown> | undefined,
+    headers: shaped.headers as Record<string, string | undefined> | undefined,
+    enqueuedAt: new Date().toISOString(),
+  }
+
+  return await context.jobs<JobEnvelope, JobReply<ResponseOf<Protocol>>>(queue).create({
+    queue,
+    name: protocol.alias,
+    data: envelope,
+    opts: options,
+  })
+}
+
+/** Wait for a protocol job and unwrap the typed entrypoint reply. */
+export const waitForProtocol = async <Protocol extends EntrypointProtocolDeclaration>(
+  context: QueueContext,
+  declaration: Protocol,
+  job: string | JobRecord<JobEnvelope, JobReply<ResponseOf<Protocol>>>,
+  options?: { timeout?: number },
+): Promise<ResponseOf<Protocol>> => {
+  const { protocol, queue } = queueFor(context, declaration)
+  if (typeof job !== 'string' && (job.queue !== queue || job.name !== protocol.alias)) {
+    throw new UnknownQueue(`${job.queue}:${job.name}`)
+  }
+  const id = typeof job === 'string' ? job : job.id
+  if (id == null) {
+    throw new UnknownQueue(`${queue}:${protocol.alias}: missing job id`)
+  }
+  const reply = await context.jobs<JobEnvelope, JobReply<ResponseOf<Protocol>>>(queue)
+    .wait(id, options)
+  if (reply.error != null) {
+    throw ResilientError.ensure(reply.error as Error | string)
+  }
+  return reply.value as ResponseOf<Protocol>
+}

package/src/transport.ts

@@ -0,0 +1,82 @@
+import { assertContext, createService } from '@owlmeans/context'
+import type { AbstractRequest, AbstractResponse, EntrypointTransport } from '@owlmeans/entrypoint'
+import { EntrypointOutcome, transportAlias } from '@owlmeans/entrypoint'
+import { RouteProtocols } from '@owlmeans/route'
+import { ResilientError } from '@owlmeans/error'
+import type { CommonEntrypoint } from '@owlmeans/entrypoint'
+import type { Config, Context, JobEnvelope, JobReply, QueueAppend } from './types.js'
+import { DEFAULT_JOB_TIMEOUT } from './consts.js'
+import { UnknownQueue } from './errors.js'
+
+/**
+ * The producing half of the bridge: it turns a call on a QUEUE entrypoint into a job, and the
+ * job's outcome back into a reply.
+ *
+ * Registering it is the whole opt-in. `apiHandler` looks up a transport by the route's protocol,
+ * so a consumer writes `ep.call(...)` against a declaration it shares with every other kind of
+ * entrypoint and never learns which one carried it. That is also why the envelope is built from
+ * the request rather than from the entrypoint: the far side rebuilds a request, and anything only
+ * HTTP understands would not survive the trip anyway.
+ */
+export const makeQueueTransport = (alias: string = transportAlias(RouteProtocols.QUEUE)) => {
+  const location = `queue-transport:${alias}`
+
+  const service = createService<EntrypointTransport>(alias, {
+    protocol: RouteProtocols.QUEUE,
+
+    handle: (async <T>(req: AbstractRequest, res: AbstractResponse<T>) => {
+      const context = assertContext<Config, Context<Config>>(service.ctx as Context<Config>, location)
+      const entrypoint = context.entrypoint<CommonEntrypoint>(req.alias)
+      const route = entrypoint.route.route
+
+      if (route.queue == null) {
+        throw new UnknownQueue(`${req.alias}: route declares no queue`)
+      }
+
+      const jobs = (context as unknown as QueueAppend).jobs<JobEnvelope, JobReply<T>>(route.queue)
+
+      const envelope: JobEnvelope = {
+        alias: req.alias,
+        params: req.params as Record<string, unknown>,
+        body: req.body,
+        query: req.query as Record<string, unknown>,
+        headers: req.headers as Record<string, string | undefined>,
+        enqueuedAt: new Date().toISOString(),
+      }
+
+      const job = await jobs.create({ queue: route.queue, name: req.alias, data: envelope })
+
+      // `reply: false` says the caller is not waiting for the work, only for the promise that it
+      // was taken. `Accepted` plus the job's identity is the whole answer — enough to watch it.
+      if (route.reply === false) {
+        res.resolve({ id: job.id, queue: route.queue } as T, EntrypointOutcome.Accepted)
+
+        return
+      }
+
+      const reply = await jobs.wait(job.id as string, {
+        timeout: req.timeout ?? route.timeout ?? DEFAULT_JOB_TIMEOUT
+      })
+
+      // A processor reports a domain failure by returning it, so it crosses the hop as the class
+      // it was thrown as rather than as a string a caller would have to parse.
+      if (reply?.error != null) {
+        throw ResilientError.ensure(reply.error as Error | string)
+      }
+
+      res.resolve(reply?.value as T, (reply?.outcome as EntrypointOutcome) ?? EntrypointOutcome.Ok)
+    }) as EntrypointTransport['handle']
+  })
+
+  return service
+}
+
+export const appendQueueTransport = <C extends Config, T extends Context<C> = Context<C>>(
+  context: T, alias?: string
+): T => {
+  const service = makeQueueTransport(alias)
+
+  context.registerService(service)
+
+  return context
+}

package/src/types.ts

@@ -0,0 +1,260 @@
+import type { BasicConfig, BasicContext, InitializedService } from '@owlmeans/context'
+import type { PubSubResource, Resource, ResourceRecord } from '@owlmeans/resource'
+import type { AbstractRequest, AbstractResponse } from '@owlmeans/entrypoint'
+import type { JobEventType, JobState } from './consts.js'
+
+/**
+ * Everything the monorepo knows about its queues, declared in the shared backend package so that
+ * producer and consumer read the same list. A process becomes a worker by naming queues in
+ * `listen` — nothing in a declaration decides where it runs.
+ */
+export interface QueueConfig {
+  queues?: QueueDeclaration[]
+  /** The queues THIS process consumes. Absent or empty means producer only. */
+  listen?: string[]
+  /** Which db service carries the queues. Defaults to the queue service's own alias. */
+  db?: string
+  defaults?: JobOptions
+  /**
+   * How long a signed job envelope stays acceptable, in seconds. It bounds both the freshness
+   * check and the nonce cache, so a job delayed behind a long backlog is still admitted.
+   */
+  envelopeTtl?: number
+}
+
+export interface QueueDeclaration {
+  name: string
+  /**
+   * The job names this queue accepts. A job the queue does not declare is refused at enqueue
+   * time rather than becoming a job nothing can process.
+   */
+  jobs: string[]
+  worker?: QueueWorkerOptions
+  defaults?: JobOptions
+}
+
+export interface QueueWorkerOptions {
+  concurrency?: number
+  /**
+   * How long a job may hold its lock without reporting progress. A processor that runs longer
+   * than this between `touch()` calls is treated as stalled and its job is handed to someone else.
+   */
+  lockDuration?: number
+  stalledInterval?: number
+  maxStalledCount?: number
+}
+
+export interface JobOptions {
+  attempts?: number
+  backoff?: { type: 'fixed' | 'exponential', delay: number }
+  delay?: number
+  priority?: number
+  /**
+   * A caller-chosen identity for the job. Enqueueing the same id twice while the first is still
+   * around is a no-op, which is what makes an admission step safe to retry.
+   */
+  id?: string
+  removeOnComplete?: boolean | number
+  removeOnFail?: boolean | number
+}
+
+/**
+ * A job as a RECORD — the same shape the resource contract reads and writes, so inspecting a
+ * queue is `list`/`get`/`count` rather than a broker-specific API.
+ */
+export interface JobRecord<D = unknown, R = unknown> extends ResourceRecord {
+  queue: string
+  name: string
+  data: D
+  state?: JobState
+  result?: R
+  error?: string
+  attempts?: number
+  progress?: unknown
+  parentId?: string
+  createdAt?: string
+  startedAt?: string
+  finishedAt?: string
+  opts?: JobOptions
+}
+
+export interface JobEvent<R = unknown> {
+  type: JobEventType
+  id: string
+  queue: string
+  /**
+   * Empty when the job is already gone. A broker's completion event carries only an id, so the
+   * name is read back from the job — and a queue that removes jobs on completion has nothing left
+   * to read. Subscribe for the id and the outcome; do not branch on the name.
+   */
+  name: string
+  result?: R
+  error?: string
+  progress?: unknown
+}
+
+/** A node of a job graph: children run first, siblings run together. */
+export interface FlowSpec<D = unknown> {
+  name: string
+  queue?: string
+  data: D
+  opts?: JobOptions
+  children?: FlowSpec[]
+}
+
+/**
+ * One queue, addressed as a resource.
+ *
+ * `create` enqueues, `get`/`load`/`list`/`count` inspect, `delete`/`take` cancel. What the base
+ * contract cannot express — waiting for an answer, submitting a graph, releasing the connection —
+ * is added here.
+ *
+ * Three places where the base `Resource` contract reads differently against a broker, because a
+ * job is not a row:
+ * - `create` does NOT throw `RecordExists` for a repeated `opts.id`. Re-enqueueing an id that is
+ *   still around returns the existing job, which is the idempotency that makes an admission step
+ *   safe to retry.
+ * - `WriteOptions.ttl` is refused. A job's lifetime is `removeOnComplete`/`removeOnFail` —
+ *   explicit deletion once it has finished, not expiry while it waits.
+ * - `update`/`save` reach only the job's `data`. Everything else about a job belongs to the
+ *   broker, and an implementation refuses rather than pretending to write it.
+ */
+export interface QueueResource<D = unknown, R = unknown>
+  extends Resource<JobRecord<D, R>>, PubSubResource<JobEvent<R>> {
+  queue: string
+  /**
+   * Release the connections this queue holds.
+   *
+   * Watching for completions means a blocking connection, and a process that never releases it
+   * does not exit. Nothing else in the resource contract can express that, so it lives here and a
+   * producer calls it on shutdown.
+   */
+  close: () => Promise<void>
+  /**
+   * Wait for a job's return value.
+   * @throws {QueueTimeout} when the wait elapses — the job itself is left alone.
+   * @throws the processor's own error, rebuilt as its original class.
+   */
+  wait: (id: string, opts?: { timeout?: number }) => Promise<R>
+  /** Submit a graph and get its root back. Children complete before their parent starts. */
+  flow: (root: FlowSpec<D>) => Promise<JobRecord<D, R>>
+  counts: () => Promise<Record<JobState, number>>
+}
+
+/**
+ * What a processor is handed. `data` is the job's payload; everything else is the means to stay
+ * alive and to read what the children reported.
+ */
+export interface JobContext<D = unknown> {
+  id: string
+  name: string
+  queue: string
+  attempt: number
+  data: D
+  signal: AbortSignal
+  /**
+   * Renew the lock. A processor that runs a long loop MUST call it as it goes: the broker judges
+   * liveness by the lock, so silence for longer than `lockDuration` is indistinguishable from a
+   * dead worker, and the job is re-run somewhere else while this one is still working on it.
+   */
+  touch: () => Promise<void>
+  progress: (value: unknown) => Promise<void>
+  /**
+   * What the children returned, keyed by child job id.
+   *
+   * A broker keys them by its own fully qualified job key; an implementation re-keys to the bare
+   * id, so two children of one parent that live in DIFFERENT queues and happen to share an id
+   * collide here. Give the children of a cross-queue flow distinct ids.
+   */
+  children: <T = unknown>() => Promise<Record<string, T>>
+  failedChildren: () => Promise<Record<string, string>>
+}
+
+export interface JobProcessor<D = unknown, R = unknown> {
+  (job: JobContext<D>): Promise<R>
+}
+
+/**
+ * The consuming half. It is registered only in processes that consume: `start()` binds the
+ * queues named in `cfg.listen` and dispatches by job name, to a processor registered here or to
+ * an entrypoint served in this process.
+ */
+export interface QueueWorkerService extends InitializedService {
+  process: <D, R>(queue: string, name: string, processor: JobProcessor<D, R>) => void
+  start: () => Promise<void>
+  stop: () => Promise<void>
+  /** The queues this process actually consumes. Empty in a producer. */
+  listening: () => string[]
+  /**
+   * Bind the application's reactions to job lifecycle events. Registering more than once merges,
+   * so an application composed of several parts can each contribute what it cares about.
+   *
+   * It belongs on the contract rather than on a driver because `onJobDead` is where an
+   * application COMPENSATES — releases the lock the admission step took, marks the record failed —
+   * and that behaviour must not have to be rewritten when the broker changes.
+   */
+  hooks: (hooks: QueueHooks) => void
+}
+
+/**
+ * The envelope a queued entrypoint call travels in. It is the request, minus everything that only
+ * means something to HTTP — the transport rebuilds a request from it on the far side.
+ */
+export interface JobEnvelope {
+  alias: string
+  params?: Record<string, unknown>
+  body?: unknown
+  query?: Record<string, unknown>
+  headers?: Record<string, string | undefined>
+  /** When the producer enqueued it — freshness is judged here, not at processing time. */
+  enqueuedAt?: string
+}
+
+export interface QueueJobMeta {
+  id: string
+  name: string
+  queue: string
+  attempt: number
+  /** Renew the broker lock for protocol handlers whose work can outlive one lock duration. */
+  touch: () => Promise<void>
+}
+
+/** What a processor returns for an entrypoint job, so the caller can rebuild the reply. */
+export interface JobReply<T = unknown> {
+  value?: T
+  outcome?: string
+  error?: unknown
+}
+
+export interface QueueHooks {
+  wrapHandler?: (job: JobContext, next: () => Promise<unknown>) => Promise<unknown>
+  onJobResult?: (event: JobEvent) => void | Promise<void>
+  onJobStalled?: (meta: { id: string, queue: string, name: string }, phase: 'stalled' | 'failed') => void | Promise<void>
+  /**
+   * The job is finished for good — retries exhausted, or it was dropped. This is where an
+   * application compensates: release the lock the admission step took, mark the record failed.
+   */
+  onJobDead?: (job: JobRecord, reason: string) => void | Promise<void>
+}
+
+export interface QueueDriver {
+  resource: <D, R>(queue: string) => QueueResource<D, R>
+  worker: () => QueueWorkerService
+}
+
+export interface Config extends BasicConfig {
+  queue?: QueueConfig
+}
+
+export interface Context<C extends Config = Config> extends BasicContext<C> {
+}
+
+export interface QueueAppend {
+  jobs: <D = unknown, R = unknown>(queue?: string) => QueueResource<D, R>
+}
+
+export interface QueueTransportRequest extends AbstractRequest {
+}
+
+export interface QueueTransportResponse extends AbstractResponse<unknown> {
+}

package/src/worker.ts

@@ -0,0 +1,72 @@
+import type { Middleware } from '@owlmeans/context'
+import { MiddlewareStage, MiddlewareType, AppType } from '@owlmeans/context'
+import type { CommonEntrypoint } from '@owlmeans/entrypoint'
+import { RouteProtocols } from '@owlmeans/route'
+import type { Config, Context, JobContext, JobEnvelope, JobProcessor, QueueWorkerService } from './types.js'
+import { handleJob } from './bridge.js'
+import { DEFAULT_ALIAS } from './consts.js'
+
+/**
+ * Every queued entrypoint this process both SERVES and LISTENS to, grouped by queue.
+ *
+ * Both halves are required and they answer different questions. Serving is about code — the alias
+ * was bound here, so a handler exists. Listening is about deployment — this process was
+ * configured to consume that queue. A worker that bound queues by what it can serve would make
+ * every deployment of the same binary a worker for everything it happens to import.
+ */
+export const servedJobs = <C extends Config, T extends Context<C>>(
+  context: T
+): Map<string, CommonEntrypoint[]> => {
+  const listen = context.cfg.queue?.listen ?? []
+  const served = new Map<string, CommonEntrypoint[]>()
+
+  context.entrypoints<CommonEntrypoint>().forEach(entrypoint => {
+    const route = entrypoint.route.route
+    if (route.type !== AppType.Backend || route.protocol !== RouteProtocols.QUEUE) {
+      return
+    }
+    if (route.service != null && route.service !== context.cfg.service) {
+      return
+    }
+    if (entrypoint.handle == null || route.queue == null || !listen.includes(route.queue)) {
+      return
+    }
+
+    served.set(route.queue, [...(served.get(route.queue) ?? []), entrypoint])
+  })
+
+  return served
+}
+
+/**
+ * A processor that runs a queued entrypoint call. The driver dispatches by job name, and an
+ * entrypoint job's name IS its alias — which is what lets one worker carry both entrypoint jobs
+ * and the internal steps an application registers with `process()`.
+ */
+export const entrypointProcessor = <C extends Config, T extends Context<C>>(
+  context: T
+): JobProcessor<JobEnvelope, unknown> =>
+  async (job: JobContext<JobEnvelope>) => await handleJob(context, job)
+
+/**
+ * Start the worker once the context is ready.
+ *
+ * Ready stage, not Loading: processors are registered while the application wires itself up, and
+ * binding the queues before that finished would take jobs this process cannot yet run. A process
+ * that listens to nothing registers no worker at all, so a producer pays nothing for this.
+ */
+export const queueWorkerMiddleware = (alias: string = DEFAULT_ALIAS): Middleware => ({
+  type: MiddlewareType.Context,
+  stage: MiddlewareStage.Ready,
+  apply: async context => {
+    const ctx = context as unknown as Context<Config>
+    if ((ctx.cfg.queue?.listen ?? []).length === 0) {
+      return
+    }
+    if (!ctx.hasService(alias)) {
+      return
+    }
+
+    await ctx.service<QueueWorkerService>(alias).start()
+  }
+})

package/tests/bridge.spec.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect } from 'bun:test'
+import { assertFresh, requestOf } from '../src/bridge.js'
+import { EnvelopeExpired } from '../src/errors.js'
+import type { JobEnvelope } from '../src/types.js'
+
+const envelope = (enqueuedAt?: string): JobEnvelope => ({
+  alias: 'story:code', params: { id: '7' }, body: { prompt: 'x' }, headers: {}, query: {}, enqueuedAt
+})
+
+describe('rebuilding the request', () => {
+  test('the envelope becomes an ordinary request', () => {
+    const request = requestOf(envelope(), '/story/:id/code')
+
+    expect(request.alias).toBe('story:code')
+    expect(request.params).toEqual({ id: '7' })
+    expect(request.body).toEqual({ prompt: 'x' })
+    expect(request.path).toBe('/story/:id/code')
+  })
+
+  /**
+   * A producer may omit any of the optional parts. The handler on the far side reads them without
+   * checking, so they have to arrive as empty containers rather than as undefined.
+   */
+  test('absent parts arrive as empty, never undefined', () => {
+    const request = requestOf({ alias: 'story:code' }, '/x')
+
+    expect(request.params).toEqual({})
+    expect(request.headers).toEqual({})
+    expect(request.query).toEqual({})
+  })
+})
+
+describe('envelope freshness', () => {
+  test('a fresh envelope passes', () => {
+    expect(() => assertFresh(envelope(new Date().toISOString()), 60)).not.toThrow()
+  })
+
+  test('an envelope older than the window is refused', () => {
+    const old = new Date(Date.now() - 120_000).toISOString()
+
+    expect(() => assertFresh(envelope(old), 60)).toThrow(EnvelopeExpired)
+  })
+
+  /**
+   * The window is judged from when the job was ENQUEUED. A job that waited behind a long backlog
+   * was legitimate when it was produced, and judging it on pickup would reject exactly the work a
+   * busy queue delayed — so a generous window has to keep it.
+   */
+  test('a long wait in the queue is not what expiry is for', () => {
+    const enqueued = new Date(Date.now() - 3600_000).toISOString()
+
+    expect(() => assertFresh(envelope(enqueued), 86_400)).not.toThrow()
+  })
+
+  test('no configured window means no check', () => {
+    const ancient = new Date(0).toISOString()
+
+    expect(() => assertFresh(envelope(ancient), undefined)).not.toThrow()
+  })
+
+  test('an envelope without a timestamp is not judged', () => {
+    expect(() => assertFresh(envelope(undefined), 60)).not.toThrow()
+  })
+})