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

package/src/config.ts

@@ -0,0 +1,171 @@
+import type {
+  Config, JobOptions, QueueDeclaration, QueueWorkerOptions, ScheduleDeclaration
+} from './types.js'
+import { ScheduleMisdeclared, UnknownJobName, UnknownQueue } from './errors.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
+}
+
+/**
+ * @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`.
+ *
+ * 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 => {
+  assertSchedule(cfg, 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
+}
+
+/** The declared schedules, of one queue when it is named. */
+export const schedulesOf = <C extends Config>(cfg: C, queue?: string): ScheduleDeclaration[] =>
+  (cfg.queue?.schedules ?? []).filter(schedule => queue == null || schedule.queue === 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)
+  }
+}

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/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,10 @@
+export * from './types.js'
+export * from './consts.js'
+export * from './utils.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'
+export * from './route.js'

package/src/protocol.ts

@@ -0,0 +1,74 @@
+import { type EntrypointProtocolDeclaration, type RequestOf, type ResponseOf, isEntrypointProtocol } from '@owlmeans/entrypoint'
+import { ResilientError } from '@owlmeans/error'
+import { queueOf } from './config.js'
+import { UnknownQueue } from './errors.js'
+import { isQueueRoute, queueRouteOptions } from './route.js'
+import type { JobEnvelope, JobOptions, JobRecord, JobReply } from './types.js'
+import type { QueueContext } from './types.local.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')
+  }
+  if (!isQueueRoute(declaration.route)) {
+    throw new UnknownQueue(`${declaration.alias}: not a queue protocol`)
+  }
+  const { queue } = queueRouteOptions(declaration.route)
+  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/route.ts

@@ -0,0 +1,40 @@
+import { backend, type RouteDeclaration, type RouteModel, type RouteOptions } from '@owlmeans/route'
+import { UnknownQueue } from './errors.js'
+import { QUEUE_PROTOCOL } from './consts.js'
+import type { QueueRouteOptions } from './types.js'
+
+/** Declare a backend route carried by a queue. */
+export const job = (
+  opts: QueueRouteOptions,
+  secondary?: Omit<QueueRouteOptions, 'queue'>,
+): Partial<RouteOptions> => {
+  const { queue, reply, ...routeOptions } = { ...opts, ...secondary }
+  const declaration = backend(routeOptions)
+  declaration.protocol = QUEUE_PROTOCOL
+  declaration.protocolOptions = { queue, ...(reply == null ? {} : { reply }) }
+  return declaration
+}
+
+/** Whether a declaration belongs to the queue transport. */
+export const isQueueRoute = (route: RouteDeclaration | RouteModel): boolean =>
+  ('route' in route ? route.route : route).protocol === QUEUE_PROTOCOL
+
+/** Read and validate queue-owned route options. */
+export 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 }
+}

package/src/transport.ts

@@ -0,0 +1,77 @@
+import { assertContext, createService } from '@owlmeans/context'
+import { type AbstractRequest, type AbstractResponse, type EntrypointTransport, EntrypointOutcome, transportAlias, type CommonEntrypoint } from '@owlmeans/entrypoint'
+import { ResilientError } from '@owlmeans/error'
+import type { Config, Context, JobEnvelope, JobReply, QueueAppend } from './types.js'
+import { DEFAULT_JOB_TIMEOUT, QUEUE_PROTOCOL } from './consts.js'
+import { queueRouteOptions } from './route.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(QUEUE_PROTOCOL)) => {
+  const location = `queue-transport:${alias}`
+
+  const service = createService<EntrypointTransport>(alias, {
+    protocol: QUEUE_PROTOCOL,
+
+    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
+
+      const { queue, reply: waitsForReply } = queueRouteOptions(route)
+
+      const jobs = (context as unknown as QueueAppend).jobs<JobEnvelope, JobReply<T>>(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, 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 (waitsForReply === false) {
+        res.resolve({ id: job.id, 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.local.ts

@@ -0,0 +1,3 @@
+import type { Config, Context, QueueAppend } from './types.js'
+
+export type QueueContext = Context<Config> & QueueAppend