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

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

package/src/queue-config.ts

@@ -0,0 +1,102 @@
+import { memoHelper } from '@owlmeans/context'
+import type { Config, JobOptions, QueueDeclaration, ScheduleDeclaration } from './types.js'
+import type { QueueConfigHelper } from './queue-config/types.js'
+import { ScheduleMisdeclared, UnknownJobName, UnknownQueue } from './errors.js'
+
+/**
+ * The queue configuration of one `cfg`. It reads `cfg.queue` on every call, so declarations made
+ * after it was built are seen.
+ */
+export const makeQueueConfigHelper = (cfg: Config): QueueConfigHelper => {
+  const queueOf = (name: string): QueueDeclaration => {
+    const queue = cfg.queue?.queues?.find(declared => declared.name === name)
+
+    if (queue == null) {
+      throw new UnknownQueue(name)
+    }
+
+    return queue
+  }
+
+  const queueOfJob = (job: string): QueueDeclaration | undefined =>
+    cfg.queue?.queues?.find(declared => declared.jobs.includes(job))
+
+  const isListening = (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())
+
+  const assertSchedule = (schedule: ScheduleDeclaration): void => {
+    const { id } = schedule
+    if (typeof id !== 'string' || id.trim() === '') {
+      throw new ScheduleMisdeclared('(empty):id')
+    }
+
+    const queue = queueOf(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`)
+    }
+  }
+
+  const schedulesOf = (queue?: string): ScheduleDeclaration[] =>
+    (cfg.queue?.schedules ?? []).filter(schedule => queue == null || schedule.queue === queue)
+
+  const assertSchedules = (): void => {
+    const seen = new Set<string>()
+    for (const schedule of schedulesOf()) {
+      assertSchedule(schedule)
+      if (seen.has(schedule.id)) {
+        throw new ScheduleMisdeclared(`${schedule.id}:duplicate`)
+      }
+      seen.add(schedule.id)
+    }
+  }
+
+  return { queueOf, queueOfJob, isListening, assertSchedule, schedulesOf, assertSchedules }
+}
+
+export const queueConfigOf = memoHelper.oncePer(makeQueueConfigHelper)

package/src/queue-route/types.ts

@@ -0,0 +1,14 @@
+import type { RouteDeclaration, RouteModel } from '@owlmeans/route'
+import type { QueueRouteOptions } from '../types.js'
+
+/** Reads a route declaration as one carried by the queue transport. */
+export interface QueueRouteHelper {
+  /** Whether a declaration belongs to the queue transport. */
+  isQueueRoute: (route: RouteDeclaration | RouteModel) => boolean
+  /**
+   * Read and validate queue-owned route options.
+   *
+   * @throws {UnknownQueue} for a route of another protocol, or queue options that do not validate
+   */
+  queueRouteOptions: (route: RouteDeclaration | RouteModel) => Pick<QueueRouteOptions, 'queue' | 'reply'>
+}

package/src/queue-route.ts

@@ -0,0 +1,33 @@
+import type { RouteDeclaration, RouteModel } from '@owlmeans/route'
+import { UnknownQueue } from './errors.js'
+import { QUEUE_PROTOCOL } from './consts.js'
+import type { QueueRouteOptions } from './types.js'
+import type { QueueRouteHelper } from './queue-route/types.js'
+
+export const createQueueRouteHelper = (): QueueRouteHelper => {
+  const isQueueRoute = (route: RouteDeclaration | RouteModel): boolean =>
+    ('route' in route ? route.route : route).protocol === QUEUE_PROTOCOL
+
+  const queueRouteOptions = (
+    route: RouteDeclaration | RouteModel,
+  ): Pick<QueueRouteOptions, 'queue' | 'reply'> => {
+    const declaration = 'route' in route ? route.route : route
+    if (declaration.protocol !== QUEUE_PROTOCOL
+      || declaration.protocolOptions == null
+      || typeof declaration.protocolOptions !== 'object') {
+      throw new UnknownQueue(`${declaration.alias}: not a queue protocol`)
+    }
+    const options = declaration.protocolOptions as Record<string, unknown>
+    if (typeof options.queue !== 'string' || options.queue.trim() === '') {
+      throw new UnknownQueue(`${declaration.alias}: route declares no queue`)
+    }
+    if (options.reply != null && typeof options.reply !== 'boolean') {
+      throw new UnknownQueue(`${declaration.alias}: invalid queue reply option`)
+    }
+    return { queue: options.queue, reply: options.reply as boolean | undefined }
+  }
+
+  return { isQueueRoute, queueRouteOptions }
+}
+
+export const queueRouteHelper = createQueueRouteHelper()