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

package/build/transport.js

@@ -0,0 +1,59 @@
+import { assertContext, createService } from '@owlmeans/context';
+import { EntrypointOutcome, transportAlias } from '@owlmeans/entrypoint';
+import { ResilientError } from '@owlmeans/error';
+import { DEFAULT_JOB_TIMEOUT, QUEUE_PROTOCOL } from './consts.js';
+import { queueRouteHelper } from './queue-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 = transportAlias(QUEUE_PROTOCOL)) => {
+    const location = `queue-transport:${alias}`;
+    const service = createService(alias, {
+        protocol: QUEUE_PROTOCOL,
+        handle: (async (req, res) => {
+            const context = assertContext(service.ctx, location);
+            const entrypoint = context.entrypoint(req.alias);
+            const route = entrypoint.route.route;
+            const { queue, reply: waitsForReply } = queueRouteHelper.queueRouteOptions(route);
+            const jobs = context.jobs(queue);
+            const envelope = {
+                alias: req.alias,
+                params: req.params,
+                body: req.body,
+                query: req.query,
+                headers: req.headers,
+                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 }, EntrypointOutcome.Accepted);
+                return;
+            }
+            const reply = await jobs.wait(job.id, {
+                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);
+            }
+            res.resolve(reply?.value, reply?.outcome ?? EntrypointOutcome.Ok);
+        })
+    });
+    return service;
+};
+export const appendQueueTransport = (context, alias) => {
+    const service = makeQueueTransport(alias);
+    context.registerService(service);
+    return context;
+};
+//# sourceMappingURL=transport.js.map

package/build/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

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

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAC3B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,sFAAsF;IACtF,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,CAAC,EAAE,UAAU,CAAA;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,mBAAmB,EAAE,CAAA;CAClC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6DAA6D;IAC7D,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAA;IAClC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAA;IAChC,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,OAAO,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,QAAQ,CAAC,EAAE,UAAU,CAAA;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,GAAG,aAAa,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,gBAAgB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IACnC,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,CAAE,SAAQ,cAAc;IACzE,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,CAAC,CAAA;IACP,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,MAAM,CAAC,EAAE,CAAC,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,UAAU,CAAA;CAClB;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACnC,IAAI,EAAE,YAAY,CAAA;IAClB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,CAAC,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,wEAAwE;AACxE,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,CAAC,CAAA;IACP,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,CACrD,SAAQ,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC9D,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B;;;;OAIG;IACH,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;IAC7D,0FAA0F;IAC1F,IAAI,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IACrD,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAA;CAChD;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,CAAC,CAAA;IACP,MAAM,EAAE,WAAW,CAAA;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,CAAC,GAAG,OAAO,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAA;IACvD,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACtD;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IACpD,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,CAAA;IACnF,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACzB,sEAAsE;IACtE,SAAS,EAAE,MAAM,MAAM,EAAE,CAAA;IACzB;;;;;;;OAOG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAA;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IAC5C,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,4FAA4F;IAC5F,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,2FAA2F;AAC3F,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACnC,KAAK,CAAC,EAAE,CAAC,CAAA;IACT,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IACjF,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,SAAS,GAAG,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvH;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrE;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACtD,MAAM,EAAE,MAAM,kBAAkB,CAAA;CACjC;AAED,MAAM,WAAW,MAAO,SAAQ,WAAW;IACzC,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAED,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;CACxE;AAED,MAAM,WAAW,qBAAsB,SAAQ,eAAe;CAC7D;AAED,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB,CAAC,OAAO,CAAC;CACxE;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,YAAY,EAAE,UAAU,GAAG,iBAAiB,CAAC;IAC3F,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,iGAAiG;AACjG,MAAM,WAAW,YAAa,SAAQ,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW;CAAG"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/build/types.local.d.ts

@@ -0,0 +1,4 @@
+import type { Config, Context, QueueAppend } from './types.js';
+export interface QueueContext extends Context<Config>, QueueAppend {
+}
+//# sourceMappingURL=types.local.d.ts.map

package/build/types.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.local.d.ts","sourceRoot":"","sources":["../src/types.local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE9D,MAAM,WAAW,YAAa,SAAQ,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW;CAAG"}

package/build/types.local.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.local.js.map

package/build/types.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.local.js","sourceRoot":"","sources":["../src/types.local.ts"],"names":[],"mappings":""}

package/build/utils.d.ts

@@ -0,0 +1,4 @@
+import { JobState } from './consts.js';
+/** A job has reached a state it will not leave on its own. */
+export declare const isSettled: (state?: JobState) => boolean;
+//# sourceMappingURL=utils.d.ts.map

package/build/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,8DAA8D;AAC9D,eAAO,MAAM,SAAS,WAAY,QAAQ,KAAG,OACc,CAAA"}

package/build/utils.js

@@ -0,0 +1,4 @@
+import { JobState } from './consts.js';
+/** A job has reached a state it will not leave on its own. */
+export const isSettled = (state) => state === JobState.Completed || state === JobState.Failed;
+//# sourceMappingURL=utils.js.map

package/build/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,8DAA8D;AAC9D,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAgB,EAAW,EAAE,CACrD,KAAK,KAAK,QAAQ,CAAC,SAAS,IAAI,KAAK,KAAK,QAAQ,CAAC,MAAM,CAAA"}

package/build/worker.d.ts

@@ -0,0 +1,10 @@
+import type { Middleware } from '@owlmeans/context';
+/**
+ * Start the worker once the context is ready.
+ *
+ * Ready stage, not Loading: processors are registered while the application wires itself up, and
+ * binding the queues before that finished would take jobs this process cannot yet run. A process
+ * that listens to nothing registers no worker at all, so a producer pays nothing for this.
+ */
+export declare const queueWorkerMiddleware: (alias?: string) => Middleware;
+//# sourceMappingURL=worker.d.ts.map

package/build/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAKnD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,WAAW,MAAM,KAAmB,UAcpE,CAAA"}

package/build/worker.js

@@ -0,0 +1,24 @@
+import { MiddlewareStage, MiddlewareType } from '@owlmeans/context';
+import { DEFAULT_ALIAS } from './consts.js';
+/**
+ * Start the worker once the context is ready.
+ *
+ * Ready stage, not Loading: processors are registered while the application wires itself up, and
+ * binding the queues before that finished would take jobs this process cannot yet run. A process
+ * that listens to nothing registers no worker at all, so a producer pays nothing for this.
+ */
+export const queueWorkerMiddleware = (alias = DEFAULT_ALIAS) => ({
+    type: MiddlewareType.Context,
+    stage: MiddlewareStage.Ready,
+    apply: async (context) => {
+        const ctx = context;
+        if ((ctx.cfg.queue?.listen ?? []).length === 0) {
+            return;
+        }
+        if (!ctx.hasService(alias)) {
+            return;
+        }
+        await ctx.service(alias).start();
+    }
+});
+//# sourceMappingURL=worker.js.map

package/build/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEnE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,KAAK,GAAW,aAAa,EAAc,EAAE,CAAC,CAAC;IACnF,IAAI,EAAE,cAAc,CAAC,OAAO;IAC5B,KAAK,EAAE,eAAe,CAAC,KAAK;IAC5B,KAAK,EAAE,KAAK,EAAC,OAAO,EAAC,EAAE;QACrB,MAAM,GAAG,GAAG,OAAqC,CAAA;QACjD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/C,OAAM;QACR,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAM;QACR,CAAC;QAED,MAAM,GAAG,CAAC,OAAO,CAAqB,KAAK,CAAC,CAAC,KAAK,EAAE,CAAA;IACtD,CAAC;CACF,CAAC,CAAA"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/queue",
-  "version": "0.1.18-rc.4",
+  "version": "0.1.18-rc.41",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 234 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -22,11 +23,20 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.6.4",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@owlmeans/auth": "^0.1.18-rc.40",
+    "@owlmeans/auth-common": "^0.1.18-rc.47",
+    "@owlmeans/context": "^0.1.18-rc.34",
+    "@owlmeans/entrypoint": "^0.1.18-rc.41",
+    "@owlmeans/error": "^0.1.18-rc.38",
+    "@owlmeans/resource": "^0.1.18-rc.40",
+    "@owlmeans/route": "^0.1.18-rc.35"
   }
 }

package/src/bridge/types.ts

@@ -0,0 +1,25 @@
+import type { BasicContext } from '@owlmeans/context'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { JobEnvelope, QueueJobMeta } from '../types.js'
+
+/** The envelope ↔ request bridge a queued entrypoint call crosses. */
+export interface QueueBridgeHelper {
+  /**
+   * 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.
+   */
+  requestOf: (envelope: JobEnvelope, path: string, context?: BasicContext<any>, job?: QueueJobMeta) => AbstractRequest
+  /** Read broker identity only where an entrypoint truly needs to bind work to an admission claim. */
+  queueJobOf: (request: unknown) => QueueJobMeta | 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}
+   */
+  assertFresh: (envelope: JobEnvelope, ttl?: number) => void
+}

package/src/bridge.ts

@@ -0,0 +1,46 @@
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { BasicContext } from '@owlmeans/context'
+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
+  }
+
+  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`)
+    }
+  }
+
+  return { requestOf, queueJobOf, assertFresh }
+}
+
+export const queueBridgeHelper = createQueueBridgeHelper()
+
+/** @deprecated compat:factory-refactor — use `queueBridgeHelper.queueJobOf(…)` */
+export const queueJobOf = (request: unknown): QueueJobMeta | null => queueBridgeHelper.queueJobOf(request)