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

package/src/config.ts

@@ -0,0 +1,80 @@
+import type {
+  Config, JobOptions, QueueDeclaration, QueueWorkerOptions, ScheduleDeclaration
+} from './types.js'
+import { queueConfigOf } from './queue-config.js'
+
+/**
+ * Add a queue to the shared configuration. Every process in the monorepo loads the same
+ * declarations — a producer needs them to know a queue exists and what it accepts, a worker needs
+ * them to bind. Declaring twice replaces, so a helper that runs per app is safe to call.
+ */
+export const declareQueue = <C extends Config>(
+  cfg: C, name: string, jobs: string[], opts?: { worker?: QueueWorkerOptions, defaults?: JobOptions }
+): C => {
+  const queue: QueueDeclaration = { name, jobs, ...opts }
+  const queues = cfg.queue?.queues ?? []
+  const existing = queues.findIndex(declared => declared.name === name)
+
+  if (existing < 0) {
+    queues.push(queue)
+  } else {
+    queues[existing] = queue
+  }
+
+  cfg.queue = { ...cfg.queue, queues }
+
+  return cfg
+}
+
+/**
+ * Name the queues this process consumes. It is what turns an otherwise identical binary into a
+ * worker, which is why it lives in the process's own config and never in a declaration.
+ */
+export const listenQueues = <C extends Config>(cfg: C, ...names: string[]): C => {
+  const listen = new Set([...(cfg.queue?.listen ?? []), ...names])
+
+  cfg.queue = { ...cfg.queue, listen: [...listen] }
+
+  return cfg
+}
+
+/**
+ * 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`.
+ *
+ * Declaring is all this does: the driver creates, updates and removes the broker's schedulers when
+ * a worker that listens to the queue starts.
+ *
+ * @throws {ScheduleMisdeclared} / {UnknownQueue} / {UnknownJobName} — see `assertSchedule`.
+ */
+export const declareSchedule = <C extends Config>(cfg: C, schedule: ScheduleDeclaration): C => {
+  queueConfigOf(cfg).assertSchedule(schedule)
+
+  const schedules = cfg.queue?.schedules ?? []
+  const existing = schedules.findIndex(declared => declared.id === schedule.id)
+
+  if (existing < 0) {
+    schedules.push(schedule)
+  } else {
+    schedules[existing] = schedule
+  }
+
+  cfg.queue = { ...cfg.queue, schedules }
+
+  return cfg
+}
+
+/** @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[] =>
+  queueConfigOf(cfg).schedulesOf(queue)
+
+/** @deprecated compat:factory-refactor — use `queueConfigOf(cfg).assertSchedules()` */
+export const assertSchedules = <C extends Config>(cfg: C): void => queueConfigOf(cfg).assertSchedules()

package/src/consts.ts

@@ -0,0 +1,38 @@
+
+export const DEFAULT_ALIAS = 'queue'
+
+/**
+ * The state a job is in, as the broker reports it. `Waiting` covers both a job queued normally
+ * and one held by an unfinished parent — the difference matters to the broker, never to a caller
+ * asking whether an answer has arrived.
+ */
+export enum JobState {
+  Waiting = 'waiting',
+  Delayed = 'delayed',
+  Active = 'active',
+  Completed = 'completed',
+  Failed = 'failed',
+  Unknown = 'unknown',
+}
+
+export enum JobEventType {
+  Completed = 'completed',
+  Failed = 'failed',
+  Progress = 'progress',
+}
+
+/**
+ * How long a caller waits for a reply when neither the route nor the request says. Long enough
+ * for work that talks to a model, short enough that a lost job surfaces as an error rather than a
+ * hung request.
+ */
+export const DEFAULT_JOB_TIMEOUT = 60_000
+
+/**
+ * Retries default to one attempt: the jobs here are mostly LLM work, and a blind retry re-spends
+ * the tokens that just failed. A queue whose jobs are cheap and idempotent raises it per queue.
+ */
+export const DEFAULT_ATTEMPTS = 1
+
+/** The transport identifier owned by the queue package. */
+export const QUEUE_PROTOCOL = 'queue' as const

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/errors.ts

@@ -0,0 +1,121 @@
+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
+  }
+}
+
+/**
+ * A schedule the broker could not carry out as written: no id, both or neither of `every` and
+ * `pattern`, an option that only means something for the other one, or a job option the broker
+ * owns for a scheduled run. The message names the schedule id and the reason.
+ */
+export class ScheduleMisdeclared extends QueueError {
+  public static override typeName = `${QueueError.typeName}ScheduleMisdeclared`
+
+  constructor(msg: string) {
+    super(`schedule-misdeclared:${msg}`)
+    this.type = ScheduleMisdeclared.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)
+ResilientError.registerErrorClass(ScheduleMisdeclared)

package/src/index.ts

@@ -0,0 +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

@@ -0,0 +1,95 @@
+import { type EntrypointProtocolDeclaration, type RequestOf, type ResponseOf, isEntrypointProtocol } from '@owlmeans/entrypoint'
+import { memoHelper } from '@owlmeans/context'
+import { ResilientError } from '@owlmeans/error'
+import { queueConfigOf } from './queue-config.js'
+import { UnknownQueue } from './errors.js'
+import { queueRouteHelper } from './queue-route.js'
+import type { JobEnvelope, JobOptions, JobRecord, JobReply } from './types.js'
+import type { QueueContext } from './types.js'
+import type { QueueProtocolHelper } from './protocol/types.js'
+
+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 }
+  }
+
+  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 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 { enqueue, waitFor }
+}
+
+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>>>> =>
+  await queueProtocolOf(context).enqueue(declaration, request, options)
+
+/** @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>> => 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'>
+}