@owlmeans/queue 0.1.18-rc.40 → 0.1.18-rc.41

package/src/bridge.ts

@@ -1,126 +1,46 @@
-import type { AbstractRequest, CommonEntrypoint, GuardService } from '@owlmeans/entrypoint'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
 import type { BasicContext } from '@owlmeans/context'
-import { EntrypointOutcome, provideResponse } from '@owlmeans/entrypoint'
-import type { Auth } from '@owlmeans/auth'
-import { AuthorizationError } from '@owlmeans/auth'
-import { attachEntity } from '@owlmeans/auth-common'
-import { ResilientError } from '@owlmeans/error'
-import type { Config, Context, JobContext, JobEnvelope, JobReply, QueueJobMeta } from './types.js'
-import { EnvelopeExpired, JobNotServed } from './errors.js'
-
-/**
- * Rebuild the request the producer described. A queued call is still a call: the same guards, the
- * same filter, the same handler run against it — only the wire is different.
- */
-export const requestOf = (
-  envelope: JobEnvelope, path: string, context?: BasicContext<any>, job?: QueueJobMeta,
-): AbstractRequest => ({
-  alias: envelope.alias,
-  params: (envelope.params ?? {}) as AbstractRequest['params'],
-  body: envelope.body as AbstractRequest['body'],
-  headers: (envelope.headers ?? {}) as AbstractRequest['headers'],
-  query: (envelope.query ?? {}) as AbstractRequest['query'],
-  path,
-  // Handlers reach their context through `original._ctx`, which the HTTP boundary sets on the raw
-  // Fastify request. There is no raw request here, so the shape is supplied deliberately — a
-  // handler must not have to know which transport delivered it.
-  original: context != null || job != null ? { _ctx: context, _job: job } : undefined,
-})
-
-/** Read broker identity only where an entrypoint truly needs to bind work to an admission claim. */
-export const queueJobOf = (request: unknown): QueueJobMeta | null => {
-  if (request == null || typeof request !== 'object' || !('original' in request)) return null
-  const original = (request as { original?: unknown }).original
-  if (original == null || typeof original !== 'object' || !('_job' in original)) return null
-  return (original as { _job?: QueueJobMeta })._job ?? null
-}
-
-/**
- * Freshness is judged from when the job was ENQUEUED, not from now.
- *
- * A signed envelope proves who produced it, and a replay window keeps a captured one from being
- * useful forever. But a job can legitimately sit behind a long backlog, and judging it on pickup
- * would reject exactly the work that a busy queue delayed — so the producer's timestamp is what
- * the window applies to.
- *
- * @throws {EnvelopeExpired}
- */
-export const assertFresh = (envelope: JobEnvelope, ttl?: number): void => {
-  if (ttl == null || envelope.enqueuedAt == null) {
-    return
-  }
-  const age = (Date.now() - new Date(envelope.enqueuedAt).getTime()) / 1000
-  if (age > ttl) {
-    throw new EnvelopeExpired(`${envelope.alias}: ${Math.round(age)}s > ${ttl}s`)
+import type { JobEnvelope, QueueJobMeta } from './types.js'
+import type { QueueBridgeHelper } from './bridge/types.js'
+import { EnvelopeExpired } from './errors.js'
+
+export const createQueueBridgeHelper = (): QueueBridgeHelper => {
+  const requestOf = (
+    envelope: JobEnvelope, path: string, context?: BasicContext<any>, job?: QueueJobMeta,
+  ): AbstractRequest => ({
+    alias: envelope.alias,
+    params: (envelope.params ?? {}) as AbstractRequest['params'],
+    body: envelope.body as AbstractRequest['body'],
+    headers: (envelope.headers ?? {}) as AbstractRequest['headers'],
+    query: (envelope.query ?? {}) as AbstractRequest['query'],
+    path,
+    // Handlers reach their context through `original._ctx`, which the HTTP boundary sets on the raw
+    // Fastify request. There is no raw request here, so the shape is supplied deliberately — a
+    // handler must not have to know which transport delivered it.
+    original: context != null || job != null ? { _ctx: context, _job: job } : undefined,
+  })
+
+  const queueJobOf = (request: unknown): QueueJobMeta | null => {
+    if (request == null || typeof request !== 'object' || !('original' in request)) return null
+    const original = (request as { original?: unknown }).original
+    if (original == null || typeof original !== 'object' || !('_job' in original)) return null
+    return (original as { _job?: QueueJobMeta })._job ?? null
   }
-}
-
-/**
- * Run one queued entrypoint call and describe the outcome.
- *
- * It never throws for a DOMAIN failure — the error is marshalled into the returned reply so the
- * producer can rebuild it as its own class, and so the broker does not count a legitimate refusal
- * as a job to retry. Infrastructure failures are left to propagate: those are what retries are for.
- */
-export const handleJob = async <C extends Config, T extends Context<C>>(
-  context: T, job: JobContext<JobEnvelope>
-): Promise<JobReply> => {
-  const envelope = job.data
-
-  try {
-    assertFresh(envelope, context.cfg.queue?.envelopeTtl)
 
-    const entrypoint = context.entrypoint<CommonEntrypoint>(envelope.alias)
-    if (entrypoint.handle == null) {
-      throw new JobNotServed(envelope.alias)
+  const assertFresh = (envelope: JobEnvelope, ttl?: number): void => {
+    if (ttl == null || envelope.enqueuedAt == null) {
+      return
     }
-
-    const request = requestOf(envelope, entrypoint.path(), context, {
-      id: job.id, name: job.name, queue: job.queue, attempt: job.attempt, touch: job.touch,
-    })
-    const response = provideResponse<unknown>()
-
-    const guards = entrypoint.getGuards()
-    if (guards.length > 0) {
-      let matched: GuardService | undefined
-      for (const alias of guards) {
-        const guard: GuardService = context.service(alias)
-        if (await guard.match(request, response)) {
-          matched = guard
-          break
-        }
-      }
-      if (matched == null) {
-        throw new AuthorizationError(`queue:${envelope.alias}`)
-      }
-
-      const auth = provideResponse<Auth>()
-      if (!await matched.handle<boolean>(request, auth)) {
-        throw new AuthorizationError(`queue:${envelope.alias}:${matched.alias}`)
-      }
-      request.auth = auth.value
-
-      const entity = await attachEntity(context, request)
-      if (entity != null) {
-        request.entity = entity
-      }
+    const age = (Date.now() - new Date(envelope.enqueuedAt).getTime()) / 1000
+    if (age > ttl) {
+      throw new EnvelopeExpired(`${envelope.alias}: ${Math.round(age)}s > ${ttl}s`)
     }
+  }
 
-    await entrypoint.handle(request, response)
-
-    if (response.error != null) {
-      return { error: ResilientError.marshal(response.error).message }
-    }
+  return { requestOf, queueJobOf, assertFresh }
+}
 
-    return { value: response.value, outcome: response.outcome ?? EntrypointOutcome.Ok }
-  } catch (e) {
-    // A refusal the caller must see as its own class — `ContentRefused`, `AgentLocked` — travels
-    // in the reply. Only a broker- or connection-level fault should ever reach the retry logic:
-    // retrying a refusal just spends the work again to be refused identically.
-    if (e instanceof ResilientError) {
-      return { error: ResilientError.marshal(e).message }
-    }
+export const queueBridgeHelper = createQueueBridgeHelper()
 
-    throw e
-  }
-}
+/** @deprecated compat:factory-refactor — use `queueBridgeHelper.queueJobOf(…)` */
+export const queueJobOf = (request: unknown): QueueJobMeta | null => queueBridgeHelper.queueJobOf(request)

package/src/config.ts

@@ -1,7 +1,7 @@
 import type {
   Config, JobOptions, QueueDeclaration, QueueWorkerOptions, ScheduleDeclaration
 } from './types.js'
-import { ScheduleMisdeclared, UnknownJobName, UnknownQueue } from './errors.js'
+import { queueConfigOf } from './queue-config.js'
 
 /**
  * Add a queue to the shared configuration. Every process in the monorepo loads the same
@@ -38,91 +38,6 @@ export const listenQueues = <C extends Config>(cfg: C, ...names: string[]): C =>
   return cfg
 }
 
-/**
- * @throws {UnknownQueue}
- */
-export const queueOf = <C extends Config>(cfg: C, name: string): QueueDeclaration => {
-  const queue = cfg.queue?.queues?.find(declared => declared.name === name)
-
-  if (queue == null) {
-    throw new UnknownQueue(name)
-  }
-
-  return queue
-}
-
-export const queueOfJob = <C extends Config>(cfg: C, job: string): QueueDeclaration | undefined =>
-  cfg.queue?.queues?.find(declared => declared.jobs.includes(job))
-
-export const isListening = <C extends Config>(cfg: C, name: string): boolean =>
-  cfg.queue?.listen?.includes(name) === true
-
-/** A date option the broker can read — a `Date`, epoch milliseconds or a parsable string. */
-const isInstant = (value: Date | number | string): boolean =>
-  Number.isFinite((value instanceof Date ? value : new Date(value)).getTime())
-
-/**
- * Whether the broker can carry a schedule out as written. Nothing is recorded or changed.
- *
- * @throws {ScheduleMisdeclared} naming the schedule id and the reason.
- * @throws {UnknownQueue} when the schedule's queue is not declared.
- * @throws {UnknownJobName} when that queue does not accept the schedule's job name — a scheduled
- * run of a name nothing declares would fail on every tick instead of once, at declaration.
- */
-export const assertSchedule = <C extends Config>(cfg: C, schedule: ScheduleDeclaration): void => {
-  const { id } = schedule
-  if (typeof id !== 'string' || id.trim() === '') {
-    throw new ScheduleMisdeclared('(empty):id')
-  }
-
-  const queue = queueOf(cfg, schedule.queue)
-  if (!queue.jobs.includes(schedule.name)) {
-    throw new UnknownJobName(`${schedule.queue}:${schedule.name}`)
-  }
-
-  const every = schedule.every != null
-  const pattern = schedule.pattern != null
-  if (every === pattern) {
-    throw new ScheduleMisdeclared(`${id}:every-or-pattern`)
-  }
-  if (every && !(Number.isSafeInteger(schedule.every) && (schedule.every as number) > 0)) {
-    throw new ScheduleMisdeclared(`${id}:every`)
-  }
-  if (pattern && (typeof schedule.pattern !== 'string' || schedule.pattern.trim() === '')) {
-    throw new ScheduleMisdeclared(`${id}:pattern`)
-  }
-  // Both only mean something to a cron pattern: an interval has no wall clock to read in a time
-  // zone, and its first run is immediate already.
-  if (!pattern && schedule.tz != null) {
-    throw new ScheduleMisdeclared(`${id}:tz`)
-  }
-  if (!pattern && schedule.immediately === true) {
-    throw new ScheduleMisdeclared(`${id}:immediately`)
-  }
-  if (schedule.immediately === true && schedule.startDate != null) {
-    throw new ScheduleMisdeclared(`${id}:immediately-start-date`)
-  }
-  if (schedule.limit != null && !(Number.isSafeInteger(schedule.limit) && schedule.limit > 0)) {
-    throw new ScheduleMisdeclared(`${id}:limit`)
-  }
-  if (schedule.startDate != null && !isInstant(schedule.startDate)) {
-    throw new ScheduleMisdeclared(`${id}:start-date`)
-  }
-  if (schedule.endDate != null && !isInstant(schedule.endDate)) {
-    throw new ScheduleMisdeclared(`${id}:end-date`)
-  }
-
-  // The type already omits both; a declaration assembled at runtime still reaches this check. The
-  // broker names every run itself and places it on the schedule, so either would be overridden.
-  const opts = schedule.opts as JobOptions | undefined
-  if (opts?.id != null) {
-    throw new ScheduleMisdeclared(`${id}:opts-id`)
-  }
-  if (opts?.delay != null) {
-    throw new ScheduleMisdeclared(`${id}:opts-delay`)
-  }
-}
-
 /**
  * Add a recurring job to the shared configuration. Declare the queue first — a schedule is checked
  * against it here. Declaring an id twice replaces, like `declareQueue`.
@@ -133,7 +48,7 @@ export const assertSchedule = <C extends Config>(cfg: C, schedule: ScheduleDecla
  * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} — see `assertSchedule`.
  */
 export const declareSchedule = <C extends Config>(cfg: C, schedule: ScheduleDeclaration): C => {
-  assertSchedule(cfg, schedule)
+  queueConfigOf(cfg).assertSchedule(schedule)
 
   const schedules = cfg.queue?.schedules ?? []
   const existing = schedules.findIndex(declared => declared.id === schedule.id)
@@ -149,23 +64,17 @@ export const declareSchedule = <C extends Config>(cfg: C, schedule: ScheduleDecl
   return cfg
 }
 
-/** The declared schedules, of one queue when it is named. */
+/** @deprecated compat:factory-refactor — use `queueConfigOf(cfg).queueOfJob(…)` */
+export const queueOfJob = <C extends Config>(cfg: C, job: string): QueueDeclaration | undefined =>
+  queueConfigOf(cfg).queueOfJob(job)
+
+/** @deprecated compat:factory-refactor — use `queueConfigOf(cfg).isListening(…)` */
+export const isListening = <C extends Config>(cfg: C, name: string): boolean =>
+  queueConfigOf(cfg).isListening(name)
+
+/** @deprecated compat:factory-refactor — use `queueConfigOf(cfg).schedulesOf(…)` */
 export const schedulesOf = <C extends Config>(cfg: C, queue?: string): ScheduleDeclaration[] =>
-  (cfg.queue?.schedules ?? []).filter(schedule => queue == null || schedule.queue === queue)
+  queueConfigOf(cfg).schedulesOf(queue)
 
-/**
- * Check every declared schedule, including any written into the configuration without
- * `declareSchedule`, and refuse two under one id.
- *
- * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} for the first one that fails.
- */
-export const assertSchedules = <C extends Config>(cfg: C): void => {
-  const seen = new Set<string>()
-  for (const schedule of schedulesOf(cfg)) {
-    assertSchedule(cfg, schedule)
-    if (seen.has(schedule.id)) {
-      throw new ScheduleMisdeclared(`${schedule.id}:duplicate`)
-    }
-    seen.add(schedule.id)
-  }
-}
+/** @deprecated compat:factory-refactor — use `queueConfigOf(cfg).assertSchedules()` */
+export const assertSchedules = <C extends Config>(cfg: C): void => queueConfigOf(cfg).assertSchedules()

package/src/entrypoint-jobs/types.ts

@@ -0,0 +1,29 @@
+import type { CommonEntrypoint } from '@owlmeans/entrypoint'
+import type { JobContext, JobEnvelope, JobProcessor, JobReply } from '../types.js'
+
+/** The queued entrypoints one context serves as a worker, and how a job of theirs is run. */
+export interface EntrypointJobsHelper {
+  /**
+   * 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.
+   */
+  served: () => Map<string, CommonEntrypoint[]>
+  /**
+   * 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()`.
+   */
+  processor: () => JobProcessor<JobEnvelope, unknown>
+  /**
+   * Run one queued entrypoint call and describe the outcome.
+   *
+   * It never throws for a DOMAIN failure — the error is marshalled into the returned reply so the
+   * producer can rebuild it as its own class, and so the broker does not count a legitimate refusal
+   * as a job to retry. Infrastructure failures are left to propagate: those are what retries are for.
+   */
+  handle: (job: JobContext<JobEnvelope>) => Promise<JobReply>
+}

package/src/entrypoint-jobs.ts

@@ -0,0 +1,105 @@
+import { AppType, memoHelper } from '@owlmeans/context'
+import type { CommonEntrypoint, GuardService } from '@owlmeans/entrypoint'
+import { EntrypointOutcome, provideResponse } from '@owlmeans/entrypoint'
+import type { Auth } from '@owlmeans/auth'
+import { AuthorizationError } from '@owlmeans/auth'
+import { ResilientError } from '@owlmeans/error'
+import type { Config, Context, JobContext, JobEnvelope, JobProcessor, JobReply } from './types.js'
+import type { EntrypointJobsHelper } from './entrypoint-jobs/types.js'
+import { JobNotServed } from './errors.js'
+import { queueBridgeHelper } from './bridge.js'
+import { queueRouteHelper } from './queue-route.js'
+import { makeEntityScope } from '@owlmeans/auth-common'
+
+export const makeEntrypointJobsHelper = (context: Context<Config>): EntrypointJobsHelper => {
+  const served = (): 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 || !queueRouteHelper.isQueueRoute(route)) {
+        return
+      }
+      if (route.service != null && route.service !== context.cfg.service) {
+        return
+      }
+      const { queue } = queueRouteHelper.queueRouteOptions(route)
+      if (entrypoint.handle == null || !listen.includes(queue)) {
+        return
+      }
+
+      served.set(queue, [...(served.get(queue) ?? []), entrypoint])
+    })
+
+    return served
+  }
+
+  const handle = async (job: JobContext<JobEnvelope>): Promise<JobReply> => {
+    const envelope = job.data
+
+    try {
+      queueBridgeHelper.assertFresh(envelope, context.cfg.queue?.envelopeTtl)
+
+      const entrypoint = context.entrypoint<CommonEntrypoint>(envelope.alias)
+      if (entrypoint.handle == null) {
+        throw new JobNotServed(envelope.alias)
+      }
+
+      const request = queueBridgeHelper.requestOf(envelope, entrypoint.path(), context, {
+        id: job.id, name: job.name, queue: job.queue, attempt: job.attempt, touch: job.touch,
+      })
+      const response = provideResponse<unknown>()
+
+      const guards = entrypoint.getGuards()
+      if (guards.length > 0) {
+        let matched: GuardService | undefined
+        for (const alias of guards) {
+          const guard: GuardService = context.service(alias)
+          if (await guard.match(request, response)) {
+            matched = guard
+            break
+          }
+        }
+        if (matched == null) {
+          throw new AuthorizationError(`queue:${envelope.alias}`)
+        }
+
+        const auth = provideResponse<Auth>()
+        if (!await matched.handle<boolean>(request, auth)) {
+          throw new AuthorizationError(`queue:${envelope.alias}:${matched.alias}`)
+        }
+        request.auth = auth.value
+
+        const entity = await makeEntityScope(request).attachEntity(context)
+        if (entity != null) {
+          request.entity = entity
+        }
+      }
+
+      await entrypoint.handle(request, response)
+
+      if (response.error != null) {
+        return { error: ResilientError.marshal(response.error).message }
+      }
+
+      return { value: response.value, outcome: response.outcome ?? EntrypointOutcome.Ok }
+    } catch (e) {
+      // A refusal the caller must see as its own class — `ContentRefused`, `AgentLocked` — travels
+      // in the reply. Only a broker- or connection-level fault should ever reach the retry logic:
+      // retrying a refusal just spends the work again to be refused identically.
+      if (e instanceof ResilientError) {
+        return { error: ResilientError.marshal(e).message }
+      }
+
+      throw e
+    }
+  }
+
+  const processor = (): JobProcessor<JobEnvelope, unknown> =>
+    async (job: JobContext<JobEnvelope>) => await handle(job)
+
+  return { served, processor, handle }
+}
+
+export const entrypointJobsOf = memoHelper.oncePer(makeEntrypointJobsHelper)

package/src/index.ts

@@ -1,10 +1,18 @@
 export * from './types.js'
+export type * from './queue-config/types.js'
+export type * from './bridge/types.js'
+export type * from './queue-route/types.js'
+export type * from './protocol/types.js'
+export type * from './entrypoint-jobs/types.js'
 export * from './consts.js'
 export * from './utils.js'
 export * from './errors.js'
 export * from './config.js'
+export * from './queue-config.js'
 export * from './transport.js'
 export * from './bridge.js'
+export * from './entrypoint-jobs.js'
 export * from './worker.js'
 export * from './protocol.js'
 export * from './route.js'
+export * from './queue-route.js'

package/src/protocol/types.ts

@@ -0,0 +1,16 @@
+import type { EntrypointProtocolDeclaration, RequestOf, ResponseOf } from '@owlmeans/entrypoint'
+import type { JobEnvelope, JobOptions, JobRecord, JobReply } from '../types.js'
+
+/** Enqueueing and awaiting QUEUE protocols in one context, with their exact types kept. */
+export interface QueueProtocolHelper {
+  /** Enqueue an immutable QUEUE protocol while preserving its exact request and response types. */
+  enqueue: <Protocol extends EntrypointProtocolDeclaration>(
+    declaration: Protocol, request: RequestOf<Protocol>, options?: JobOptions,
+  ) => Promise<JobRecord<JobEnvelope, JobReply<ResponseOf<Protocol>>>>
+  /** Wait for a protocol job and unwrap the typed entrypoint reply. */
+  waitFor: <Protocol extends EntrypointProtocolDeclaration>(
+    declaration: Protocol,
+    job: string | JobRecord<JobEnvelope, JobReply<ResponseOf<Protocol>>>,
+    options?: { timeout?: number },
+  ) => Promise<ResponseOf<Protocol>>
+}

package/src/protocol.ts

@@ -1,74 +1,95 @@
 import { type EntrypointProtocolDeclaration, type RequestOf, type ResponseOf, isEntrypointProtocol } from '@owlmeans/entrypoint'
+import { memoHelper } from '@owlmeans/context'
 import { ResilientError } from '@owlmeans/error'
-import { queueOf } from './config.js'
+import { queueConfigOf } from './queue-config.js'
 import { UnknownQueue } from './errors.js'
-import { isQueueRoute, queueRouteOptions } from './route.js'
+import { queueRouteHelper } from './queue-route.js'
 import type { JobEnvelope, JobOptions, JobRecord, JobReply } from './types.js'
-import type { QueueContext } from './types.local.js'
+import type { QueueContext } from './types.js'
+import type { QueueProtocolHelper } from './protocol/types.js'
 
-const queueFor = (context: QueueContext, declaration: unknown): {
-  protocol: EntrypointProtocolDeclaration
-  queue: string
-} => {
-  if (declaration == null || typeof declaration !== 'object' || !isEntrypointProtocol(declaration)) {
-    throw new UnknownQueue('protocol declaration required')
+export const makeQueueProtocolHelper = (context: QueueContext): QueueProtocolHelper => {
+  const queueFor = (declaration: unknown): {
+    protocol: EntrypointProtocolDeclaration
+    queue: string
+  } => {
+    if (declaration == null || typeof declaration !== 'object' || !isEntrypointProtocol(declaration)) {
+      throw new UnknownQueue('protocol declaration required')
+    }
+    if (!queueRouteHelper.isQueueRoute(declaration.route)) {
+      throw new UnknownQueue(`${declaration.alias}: not a queue protocol`)
+    }
+    const { queue } = queueRouteHelper.queueRouteOptions(declaration.route)
+    const configured = queueConfigOf(context.cfg).queueOf(queue)
+    if (!configured.jobs.includes(declaration.alias)) {
+      throw new UnknownQueue(`${queue}:${declaration.alias}`)
+    }
+    return { protocol: declaration, queue }
   }
-  if (!isQueueRoute(declaration.route)) {
-    throw new UnknownQueue(`${declaration.alias}: not a queue protocol`)
+
+  const enqueue = async <Protocol extends EntrypointProtocolDeclaration>(
+    declaration: Protocol,
+    request: RequestOf<Protocol>,
+    options?: JobOptions,
+  ): Promise<JobRecord<JobEnvelope, JobReply<ResponseOf<Protocol>>>> => {
+    const { protocol, queue } = queueFor(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,
+    })
   }
-  const { queue } = queueRouteOptions(declaration.route)
-  const configured = queueOf(context.cfg, queue)
-  if (!configured.jobs.includes(declaration.alias)) {
-    throw new UnknownQueue(`${queue}:${declaration.alias}`)
+
+  const waitFor = async <Protocol extends EntrypointProtocolDeclaration>(
+    declaration: Protocol,
+    job: string | JobRecord<JobEnvelope, JobReply<ResponseOf<Protocol>>>,
+    options?: { timeout?: number },
+  ): Promise<ResponseOf<Protocol>> => {
+    const { protocol, queue } = queueFor(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>
   }
-  return { protocol: declaration, queue }
+
+  return { enqueue, waitFor }
 }
 
-/** Enqueue an immutable QUEUE protocol while preserving its exact request and response types. */
+export const queueProtocolOf = memoHelper.oncePer(makeQueueProtocolHelper)
+
+/** @deprecated compat:factory-refactor — use `queueProtocolOf(ctx).enqueue(…)` */
 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(),
-  }
+): Promise<JobRecord<JobEnvelope, JobReply<ResponseOf<Protocol>>>> =>
+  await queueProtocolOf(context).enqueue(declaration, request, options)
 
-  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. */
+/** @deprecated compat:factory-refactor — use `queueProtocolOf(ctx).waitFor(…)` */
 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>
-}
+): Promise<ResponseOf<Protocol>> => await queueProtocolOf(context).waitFor(declaration, job, options)

package/src/queue-config/types.ts

@@ -0,0 +1,29 @@
+import type { QueueDeclaration, ScheduleDeclaration } from '../types.js'
+
+/** What one configuration declares about its queues and schedules, read and checked. */
+export interface QueueConfigHelper {
+  /**
+   * @throws {UnknownQueue}
+   */
+  queueOf: (name: string) => QueueDeclaration
+  queueOfJob: (job: string) => QueueDeclaration | undefined
+  isListening: (name: string) => boolean
+  /**
+   * Whether the broker can carry a schedule out as written. Nothing is recorded or changed.
+   *
+   * @throws {ScheduleMisdeclared} naming the schedule id and the reason.
+   * @throws {UnknownQueue} when the schedule's queue is not declared.
+   * @throws {UnknownJobName} when that queue does not accept the schedule's job name — a scheduled
+   * run of a name nothing declares would fail on every tick instead of once, at declaration.
+   */
+  assertSchedule: (schedule: ScheduleDeclaration) => void
+  /** The declared schedules, of one queue when it is named. */
+  schedulesOf: (queue?: string) => ScheduleDeclaration[]
+  /**
+   * Check every declared schedule, including any written into the configuration without
+   * `declareSchedule`, and refuse two under one id.
+   *
+   * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} for the first one that fails.
+   */
+  assertSchedules: () => void
+}