@pattern-stack/codegen 0.8.0 → 0.9.0

package/dist/runtime/subsystems/jobs/job-orchestrator.bullmq-backend.d.ts

@@ -0,0 +1,107 @@
+import { ConnectionOptions, FlowProducer } from 'bullmq';
+import { DrizzleClient } from '../../types/drizzle.js';
+import { DrizzleTransaction } from '../events/event-bus.protocol.js';
+import { DrizzleJobOrchestrator } from './job-orchestrator.drizzle-backend.js';
+import { l as StartOptions, i as JobRun, C as CancelOptions } from '../../../job-orchestrator.protocol-BwsBd37o.js';
+import { BullMqResolvedConfig } from './bullmq.config.js';
+import 'drizzle-orm/node-postgres';
+import './job-orchestration.schema.js';
+import 'drizzle-orm/pg-core';
+import 'drizzle-orm';
+import '@nestjs/common';
+import './pool-config.loader.js';
+
+/**
+ * Derive a colon-safe, stable BullMQ `jobId` from a logical idempotency key.
+ *
+ * SHA-1 over the raw key. Collision analysis (spec §Gotcha 1, resolved during
+ * implementation): SHA-1's 160-bit space makes an accidental collision between
+ * two *distinct* logical keys astronomically unlikely at any realistic job
+ * volume (the birthday bound is ~2^80 keys before a 50% collision chance —
+ * orders of magnitude beyond any job throughput). SHA-1's cryptographic
+ * weakness is irrelevant here: there is no adversary forging idempotency keys,
+ * and even a forged collision only deduplicates two jobs that the caller chose
+ * to key identically. We therefore accept SHA-1 with no mitigation. The *same*
+ * logical key intentionally maps to the *same* jobId — that is the dedup
+ * mechanism, not a collision.
+ */
+declare function sha1JobId(idempotencyKey: string): string;
+declare class BullMQJobOrchestrator extends DrizzleJobOrchestrator {
+    private readonly connection;
+    private readonly bullConfig;
+    private readonly bullLogger;
+    /** Lazily-opened `Queue` handles, one per pool. */
+    private readonly queues;
+    /** Single FlowProducer for parent/child hierarchies. Lazily opened. */
+    private _flow;
+    /**
+     * Cached `bullmq` value constructors, populated by `loadBullMq()` on first
+     * use (the `start`/`cancel`/`replay` entrypoints `await` it before touching
+     * a queue). Kept off the import graph so a `drizzle`-only consumer never
+     * resolves the optional `'bullmq'` package.
+     */
+    private QueueCtor;
+    private FlowProducerCtor;
+    private bullMqLoad;
+    /**
+     * Own reference to the Drizzle client. `DrizzleJobOrchestrator.db` is
+     * `private` (can't be redeclared even privately in a subclass), and the
+     * spec forbids touching that file — so the subclass keeps its own handle
+     * under a distinct name (same instance, passed through to `super`) for the
+     * cancel-cascade snapshot + definition/run loads below.
+     */
+    private readonly bullDb;
+    constructor(db: DrizzleClient, multiTenant: boolean, connection: ConnectionOptions, bullConfig?: BullMqResolvedConfig | null);
+    /**
+     * Lazily load the optional `bullmq` package and cache its value
+     * constructors. Idempotent (single in-flight promise). Throws a friendly,
+     * actionable error when the consumer selected `backend: 'bullmq'` but did
+     * not install the package — mirrors `createRedisClient` in the redis event
+     * backend. Must be `await`ed before any `queueFor`/`flow` access.
+     */
+    private loadBullMq;
+    /**
+     * Open (or reuse) the `Queue` for a pool. Synchronous — callers `await
+     * loadBullMq()` first so `QueueCtor` is populated.
+     */
+    private queueFor;
+    private flow;
+    start(type: string, input: unknown, opts?: StartOptions, tx?: DrizzleTransaction): Promise<JobRun>;
+    /**
+     * Map a `job_run` row onto a BullMQ job via `queue.add`. When the run has a
+     * `parentRunId` we attach it to the parent's existing BullMQ job through the
+     * `parent: { id, queue }` opt — BullMQ then tracks the parent/child link in
+     * its own graph. (The FlowProducer is reserved for whole-tree atomic
+     * submits, exposed as an opt-in extension via `flowProducer()`; runtime
+     * `ctx.spawnChild` is incremental, so `queue.add` with a parent ref is the
+     * correct primitive here.)
+     *
+     * The `jobId` is colon-safe + stable: `sha1(dedupeKey)` when a dedupe key is
+     * present (so the same logical key dedups), else the `job_run.id` UUID
+     * (already colon-free).
+     *
+     * The domain `parentClosePolicy` cascade is still enforced in Postgres by
+     * the shared `cancel` path — BullMQ's parent link is dispatch bookkeeping,
+     * not the authority.
+     */
+    private dispatch;
+    /**
+     * Opt-in extension (spec §Extensions): expose the FlowProducer for
+     * consumers that want to submit a whole parent/child DAG atomically up
+     * front, rather than incrementally via `ctx.spawnChild`. Backend-specific —
+     * code using it is not portable to the Drizzle backend. Async because it
+     * lazily loads the optional `bullmq` package on first use.
+     */
+    flowProducer(): Promise<FlowProducer>;
+    private retryOpts;
+    private dedupeOpts;
+    cancel(runId: string, opts?: CancelOptions): Promise<void>;
+    private removeFromQueue;
+    replay(runId: string): Promise<JobRun>;
+    private loadDefinition;
+    private loadRun;
+    /** Close all open queue + flow connections. Called on module destroy. */
+    closeConnections(): Promise<void>;
+}
+
+export { BullMQJobOrchestrator, sha1JobId };