Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

ralph(M9-001): jobs.registry: all 7 queues + envelope on for producers + compat hooks proven

ralph896d368d7567
diff --git a/apps/api/e2e/README.md b/apps/api/e2e/README.md
index 2464532d1..8b4f40333 100644
--- a/apps/api/e2e/README.md
+++ b/apps/api/e2e/README.md
@@ -318,3 +318,24 @@ consumer code paths in a way expected to cost throughput — `M8-006`'s
correctness checkpoint (`0f8d956a`) already proved the ported path behaves
identically to the one BENCH-001 measured; this run's job was only to attach a
number to it.
+
+## `legacy-job-proof.sh` — the P9 jobs cutover proof (M9-001)
+
+Independent of the session harnesses and of `pnpm dev`: it needs only Redis.
+
+```bash
+bash apps/api/e2e/legacy-job-proof.sh
+```
+
+Writes one **V1-shaped** job per queue straight into Redis (V1's exact
+`Queue.add(name, data)`, dumping the stored bytes to show there is no
+`{payload, meta}` envelope on them), then starts the V2 workers over the real
+`jobs.registry` and asserts every one is resolved through its `compat` hook to
+the right V2 job name and payload — plus the other direction, a producer-
+enqueued envelope whose `requestId` reaches the handler's logger.
+
+It runs on a `-m9001proof` queue-key namespace so it cannot touch the shared
+dev Redis's live queues, and it refuses to start if the event/group buffers are
+non-empty (the real `flushEvents` handler it runs would drain them). The
+un-namespaced keys' byte-identity is pinned separately by
+`packages/core/src/jobs/naming.test.ts`.
diff --git a/apps/api/e2e/legacy-job-proof.sh b/apps/api/e2e/legacy-job-proof.sh
new file mode 100755
index 000000000..31ad1bb37
--- /dev/null
+++ b/apps/api/e2e/legacy-job-proof.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# M9-001 acceptance proof (playbook rule 1: a runtime claim gets a runnable
+# proof). Loads the repo .env for REDIS_URL, then runs the proof under Bun.
+#
+# bash apps/api/e2e/legacy-job-proof.sh
+set -u
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$REPO_ROOT" || exit 1
+
+if [ -f .env ]; then
+ set -a
+ # shellcheck disable=SC1091
+ . ./.env
+ set +a
+fi
+
+exec bun run apps/api/e2e/legacy-job-proof.ts
diff --git a/apps/api/e2e/legacy-job-proof.ts b/apps/api/e2e/legacy-job-proof.ts
new file mode 100644
index 000000000..f52ecbbd2
--- /dev/null
+++ b/apps/api/e2e/legacy-job-proof.ts
@@ -0,0 +1,513 @@
+/**
+ * M9-001 acceptance proof: a LEGACY-shaped job already sitting in Redis is
+ * still picked up and run by the V2 worker, with no drain and no rename
+ * (ADR-005). Plus the other direction — a job the V2 producer enqueues
+ * carries the `{payload, meta}` envelope and its `requestId` reaches the
+ * handler's logger (ADR-018 R1).
+ *
+ * What is real here: the registry (`queues`), every `compat` hook, every job
+ * payload schema, `resolveJob`, BullMQ, and Redis. The legacy jobs are put in
+ * Redis by `Queue.add(name, data)` with V1's exact data — byte-for-byte the
+ * call `packages/queue`'s producers make — before any worker starts, so they
+ * are genuinely waiting on the list when the worker connects.
+ *
+ * Two deliberate narrowings, both stated in the output:
+ *
+ * 1. It runs on a `-m9001proof` queue-key namespace, not on the shared dev
+ * Redis's live `cron`/`sessions`/… keys, so it can neither consume nor be
+ * confused by whatever the golden harness left there. Only the key string
+ * differs; the un-namespaced keys' byte-identity is pinned separately by
+ * `packages/core/src/jobs/naming.test.ts`.
+ * 2. `cron` runs its REAL handlers over the REAL boot buffers. The other six
+ * queues' handlers reach `ctx.services`, which needs the db/ch clients
+ * `AppDeps` does not carry until M9-002/M9-003, so for those six the
+ * handler body is a recorder — everything up to and including the handler
+ * lookup is the real thing.
+ *
+ * Run: `bash apps/api/e2e/legacy-job-proof.sh`
+ */
+
+process.env.TZ = 'UTC';
+
+import {
+ type AnyJob,
+ type AppDeps,
+ createBuffers,
+ createProducers,
+ type QueueDefinition,
+ type Queues,
+ queueKey,
+ queues,
+ startWorkers,
+} from '@openpanel/core';
+import { produceIncomingEvent } from '@openpanel/queue';
+import { Redis } from '@openpanel/redis';
+import pino from 'pino';
+
+/** Isolates the proof from the shared dev Redis — see the header. */
+const NAMESPACE = 'm9001proof';
+const REDIS_URL = process.env.REDIS_URL || 'redis://127.0.0.1:6379';
+const JOB_WAIT_TIMEOUT_MS = 20_000;
+const JOB_POLL_INTERVAL_MS = 100;
+const REAL_HANDLER_QUEUE = 'cron';
+
+type QueueKey = keyof Queues;
+
+interface LegacyCase {
+ queue: QueueKey;
+ /** The BullMQ job name V1 put on the wire. */
+ wireName: string;
+ /** V1's job data, verbatim (packages/queue/src/queues.ts). */
+ data: unknown;
+ /** The V2 job the compat hook must resolve it to. */
+ expectJob: string;
+ expectPayload: unknown;
+}
+
+// One per queue. Every `data` below is a V1 payload type from
+// packages/queue/src/queues.ts; `undefined` fields are omitted because JSON
+// drops them, which is exactly what is in Redis today.
+const LEGACY_CASES: LegacyCase[] = [
+ {
+ queue: 'cron',
+ wireName: 'flushEvents',
+ data: { type: 'flushEvents' },
+ expectJob: 'flushEvents',
+ expectPayload: null,
+ },
+ {
+ queue: 'sessions',
+ wireName: 'session',
+ data: {
+ type: 'createSessionEnd',
+ payload: { projectId: 'proj_m9001', deviceId: 'dev_m9001' },
+ snapshot: {
+ id: 'ses_m9001',
+ project_id: 'proj_m9001',
+ device_id: 'dev_m9001',
+ ended_at: '2026-09-05 00:00:00',
+ },
+ },
+ expectJob: 'session',
+ expectPayload: {
+ event: { projectId: 'proj_m9001', deviceId: 'dev_m9001' },
+ snapshot: {
+ id: 'ses_m9001',
+ project_id: 'proj_m9001',
+ device_id: 'dev_m9001',
+ ended_at: '2026-09-05 00:00:00',
+ },
+ },
+ },
+ {
+ queue: 'notification',
+ wireName: 'sendNotification',
+ data: {
+ type: 'sendNotification',
+ payload: {
+ notification: {
+ projectId: 'proj_m9001',
+ title: 'legacy',
+ message: 'still processed',
+ },
+ },
+ },
+ expectJob: 'sendNotification',
+ expectPayload: {
+ notification: {
+ projectId: 'proj_m9001',
+ title: 'legacy',
+ message: 'still processed',
+ },
+ },
+ },
+ {
+ queue: 'import',
+ wireName: 'import',
+ data: { type: 'import', payload: { importId: 'imp_m9001' } },
+ expectJob: 'import',
+ expectPayload: { importId: 'imp_m9001' },
+ },
+ {
+ queue: 'insights',
+ wireName: 'insightsProject',
+ data: {
+ type: 'insightsProject',
+ payload: { projectId: 'proj_m9001', date: '2026-09-05' },
+ },
+ expectJob: 'insightsProject',
+ expectPayload: { projectId: 'proj_m9001', date: '2026-09-05' },
+ },
+ {
+ queue: 'gsc',
+ wireName: 'gscProjectBackfill',
+ data: {
+ type: 'gscProjectBackfill',
+ payload: { projectId: 'proj_m9001' },
+ },
+ expectJob: 'gscProjectBackfill',
+ expectPayload: { projectId: 'proj_m9001' },
+ },
+ {
+ // The one V1 payload with no discriminant at all — a bare `{cohortId}`,
+ // which must NOT be mistaken for an envelope.
+ queue: 'cohortCompute',
+ wireName: 'cohortCompute',
+ data: { cohortId: 'coh_m9001' },
+ expectJob: 'cohortCompute',
+ expectPayload: { cohortId: 'coh_m9001' },
+ },
+];
+
+interface HandlerRun {
+ queue: string;
+ job: string;
+ payload: unknown;
+ requestId: string;
+}
+
+const runs: HandlerRun[] = [];
+const logLines: string[] = [];
+let failures = 0;
+
+function pass(message: string) {
+ process.stdout.write(`PASS: ${message}\n`);
+}
+
+function fail(message: string) {
+ failures += 1;
+ process.stdout.write(`FAIL: ${message}\n`);
+}
+
+function check(condition: boolean, message: string) {
+ if (condition) {
+ pass(message);
+ } else {
+ fail(message);
+ }
+}
+
+/** Both records every line and lets it out, so the run is readable live. */
+const logger = pino(
+ { name: 'legacy-job-proof', level: 'debug' },
+ {
+ write: (line: string) => {
+ logLines.push(line.trimEnd());
+ process.stdout.write(line);
+ },
+ }
+);
+
+/**
+ * The six queues whose real handlers need `ctx.services`. Only the handler
+ * body is replaced: the queue's `compat` hook, `defaults`, `worker` settings
+ * and every job's payload schema are the registry's own.
+ */
+function recordingCopy(definition: QueueDefinition): QueueDefinition {
+ const jobs = Object.fromEntries(
+ Object.entries(definition.jobs).map(([name, job]) => [
+ name,
+ {
+ ...(job as AnyJob),
+ queue: definition.name,
+ name,
+ handler: (async (args: {
+ payload: unknown;
+ ctx: { requestId: string };
+ }) => {
+ runs.push({
+ queue: definition.name,
+ job: name,
+ payload: args.payload,
+ requestId: args.ctx.requestId,
+ });
+ }) as AnyJob['handler'],
+ },
+ ])
+ ) as QueueDefinition['jobs'];
+
+ return { ...definition, jobs };
+}
+
+/**
+ * Structurally identical to `queues` — same keys, same queue names, same
+ * schemas — so the typed producer surface survives the cast.
+ */
+function proofRegistry(): Queues {
+ return Object.fromEntries(
+ Object.entries(queues).map(([key, definition]) => [
+ key,
+ key === REAL_HANDLER_QUEUE
+ ? (definition as QueueDefinition)
+ : recordingCopy(definition as QueueDefinition),
+ ])
+ ) as unknown as Queues;
+}
+
+function delay(ms: number): Promise<void> {
+ return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function main() {
+ const connections: Redis[] = [];
+ const newConnection = () => {
+ // BullMQ requires `maxRetriesPerRequest: null`; V1's `getRedisQueue` sets
+ // the same three options.
+ const client = new Redis(REDIS_URL, {
+ maxRetriesPerRequest: null,
+ enableReadyCheck: false,
+ enableOfflineQueue: true,
+ });
+ client.on('error', (error) =>
+ logger.error({ err: error }, 'proof redis error')
+ );
+ connections.push(client);
+ return client;
+ };
+
+ const producerConnection = newConnection();
+ const registry = proofRegistry();
+
+ const producers = createProducers(registry, {
+ connection: producerConnection,
+ namespace: NAMESPACE,
+ logger,
+ });
+
+ const buffers = createBuffers({
+ createLogger: (name) => logger.child({ name }),
+ isCronPaused: async () => false,
+ });
+
+ const deps: AppDeps = {
+ db: undefined,
+ ch: undefined,
+ redis: undefined,
+ clients: undefined,
+ buffers,
+ producers,
+ produceIncomingEvent,
+ logger,
+ config: { selfHosted: false },
+ };
+
+ process.stdout.write(
+ '\n--- keys ------------------------------------------------------\n' +
+ `production key for 'cron' : ${queueKey('cron')}\n` +
+ `key this proof runs on : ${queueKey('cron', { namespace: NAMESPACE })}\n`
+ );
+
+ // Never drain a buffer somebody else filled: the real `flushEvents` /
+ // `flushGroups` handlers below write to ClickHouse if their list is
+ // non-empty, and the buffers' Redis keys are fixed names on the shared
+ // client — a namespace cannot isolate them.
+ const buffered =
+ (await buffers.event.getBufferSize()) +
+ (await buffers.group.getBufferSize());
+ if (buffered !== 0) {
+ process.stdout.write(
+ `\nABORT: the shared event/group buffers hold ${buffered} rows; running the real flush handlers would drain them. Refusing.\n`
+ );
+ await producers.close();
+ for (const client of connections) {
+ client.disconnect();
+ }
+ process.exit(1);
+ }
+
+ const queueByName = new Map(
+ producers.bullQueues.map((queue) => [queue.name, queue])
+ );
+ const bullFor = (key: QueueKey) => {
+ const queue = queueByName.get(queueKey(key, { namespace: NAMESPACE }));
+ if (!queue) {
+ throw new Error(`no bull queue for '${key}'`);
+ }
+ return queue;
+ };
+
+ // --- 1. Put the legacy jobs in Redis, before any worker exists -----------
+
+ process.stdout.write(
+ '\n--- legacy jobs written to Redis (raw stored bytes) -----------\n'
+ );
+
+ const enqueued: { legacyCase: LegacyCase; jobId: string }[] = [];
+ for (const legacyCase of LEGACY_CASES) {
+ const bull = bullFor(legacyCase.queue);
+ const job = await bull.add(legacyCase.wireName, legacyCase.data as object);
+ if (!job.id) {
+ throw new Error(`no job id for ${legacyCase.queue}`);
+ }
+ enqueued.push({ legacyCase, jobId: job.id });
+
+ const stored = await producerConnection.hget(
+ `bull:${bull.name}:${job.id}`,
+ 'data'
+ );
+ process.stdout.write(
+ `${legacyCase.queue.padEnd(14)} name=${legacyCase.wireName.padEnd(19)} data=${stored}\n`
+ );
+ check(
+ stored !== null && !stored.includes('"meta"'),
+ `${legacyCase.queue}: stored bytes carry no envelope (V1 shape)`
+ );
+ }
+
+ // --- 2. One envelope job, from the V2 producer, for the round trip -------
+
+ const requestId = 'm9001proof-req';
+ const envelopeJobId = await producers
+ .scope({ requestId })
+ .cron.flushGroups.add(null);
+ const envelopeStored = await producerConnection.hget(
+ `bull:${bullFor('cron').name}:${envelopeJobId}`,
+ 'data'
+ );
+ process.stdout.write(
+ '\n--- envelope job written by the V2 producer -------------------\n' +
+ `cron name=flushGroups data=${envelopeStored}\n`
+ );
+ check(
+ envelopeStored === `{"payload":null,"meta":{"requestId":"${requestId}"}}`,
+ 'producer stores {payload, meta} with the scoped requestId'
+ );
+
+ // --- 3. Now start the workers -------------------------------------------
+
+ process.stdout.write(
+ '\n--- worker log ------------------------------------------------\n'
+ );
+
+ const workers = startWorkers({
+ definitions: registry,
+ deps,
+ createConnection: () => newConnection(),
+ namespace: NAMESPACE,
+ onTerminalFailure: (failure) =>
+ fail(
+ `${failure.queue}/${failure.job} failed terminally: ${failure.error.message}`
+ ),
+ });
+
+ /**
+ * `sessions` carries `removeOnComplete: true`, so a completed job is gone
+ * from Redis rather than marked finished — the job was already added, so a
+ * disappearance is a completion. A terminal failure would leave the job in
+ * the failed set (and fire `onTerminalFailure`), not delete it.
+ */
+ const waitForCompletion = async (key: QueueKey, jobId: string) => {
+ const bull = bullFor(key);
+ const deadline = Date.now() + JOB_WAIT_TIMEOUT_MS;
+ while (Date.now() < deadline) {
+ const job = await bull.getJob(jobId);
+ if (!job) {
+ return 'completed and removed';
+ }
+ if (job.finishedOn) {
+ return await job.getState();
+ }
+ await delay(JOB_POLL_INTERVAL_MS);
+ }
+ return null;
+ };
+
+ for (const { legacyCase, jobId } of enqueued) {
+ const state = await waitForCompletion(legacyCase.queue, jobId);
+ check(
+ state === 'completed' || state === 'completed and removed',
+ `${legacyCase.queue}: legacy job ${jobId} was processed by the new worker (${state})`
+ );
+ }
+ const envelopeState = await waitForCompletion('cron', envelopeJobId);
+ check(
+ envelopeState === 'completed' || envelopeState === 'completed and removed',
+ `cron: envelope job ${envelopeJobId} was processed by the new worker (${envelopeState})`
+ );
+
+ // --- 4. Assertions on what the worker actually resolved ------------------
+
+ process.stdout.write(
+ '\n--- what the compat hooks resolved ----------------------------\n'
+ );
+
+ for (const legacyCase of LEGACY_CASES) {
+ if (legacyCase.queue === REAL_HANDLER_QUEUE) {
+ continue;
+ }
+ const run = runs.find(
+ (candidate) =>
+ candidate.queue === legacyCase.queue &&
+ candidate.job === legacyCase.expectJob
+ );
+ process.stdout.write(
+ `${legacyCase.queue.padEnd(14)} ${JSON.stringify(legacyCase.data)}\n` +
+ `${''.padEnd(14)} -> job=${run?.job} payload=${JSON.stringify(run?.payload)}\n`
+ );
+ check(
+ run !== undefined &&
+ JSON.stringify(run.payload) ===
+ JSON.stringify(legacyCase.expectPayload),
+ `${legacyCase.queue}: resolved to '${legacyCase.expectJob}' with V1's payload`
+ );
+ }
+
+ const startedLegacy = logLines.filter(
+ (line) => line.includes('"job started"') && line.includes('"legacy":true')
+ );
+ check(
+ startedLegacy.length === LEGACY_CASES.length,
+ `worker logged 'job started' with legacy:true for all ${LEGACY_CASES.length} legacy jobs (got ${startedLegacy.length})`
+ );
+
+ const realFlush = logLines.find(
+ (line) =>
+ line.includes('"job completed"') &&
+ line.includes('"job":"flushEvents"') &&
+ line.includes('"legacy":true')
+ );
+ check(
+ realFlush !== undefined,
+ "cron: the REAL flushEvents handler ran to completion off V1's `{type:'flushEvents'}`"
+ );
+
+ const envelopeLine = logLines.find(
+ (line) =>
+ line.includes('"job completed"') &&
+ line.includes('"job":"flushGroups"') &&
+ line.includes(`"requestId":"${requestId}"`)
+ );
+ check(
+ envelopeLine !== undefined,
+ 'envelope job: the producer requestId reached the handler logger'
+ );
+
+ // --- 5. Clean the proof namespace up ------------------------------------
+
+ await workers.close();
+ await producers.close();
+
+ const proofKeys = await producerConnection.keys(`bull:*-${NAMESPACE}*`);
+ if (proofKeys.length > 0) {
+ await producerConnection.del(...proofKeys);
+ }
+ process.stdout.write(`\ncleaned ${proofKeys.length} proof redis keys\n`);
+
+ for (const client of connections) {
+ client.disconnect();
+ }
+
+ process.stdout.write(
+ failures === 0
+ ? '\nlegacy-job-proof: all checks passed\n'
+ : `\nlegacy-job-proof: ${failures} failure(s)\n`
+ );
+ process.exit(failures === 0 ? 0 : 1);
+}
+
+main().catch((error) => {
+ process.stdout.write(
+ `\nlegacy-job-proof: crashed\n${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`
+ );
+ process.exit(1);
+});
diff --git a/apps/api/package.json b/apps/api/package.json
index 3af22cc73..b73aeb388 100644
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -10,6 +10,7 @@
"test:manage": "jiti scripts/test-manage-api.ts",
"e2e:sessions": "LOG_LEVEL=warn dotenv -e ../../.env -- jiti e2e/session-e2e.ts",
"e2e:sessions:stress": "LOG_LEVEL=warn dotenv -e ../../.env -- jiti e2e/session-stress.ts",
+ "e2e:legacy-jobs": "bash e2e/legacy-job-proof.sh",
"test": "vitest",
"test:run": "vitest run",
"typecheck": "tsc --noEmit"
diff --git a/apps/api/src/config/env.ts b/apps/api/src/config/env.ts
index 46c997fe0..744ffbe6e 100644
--- a/apps/api/src/config/env.ts
+++ b/apps/api/src/config/env.ts
@@ -2,8 +2,8 @@
// per TARGET_ARCHITECTURE §7 "apps/api — three files". `packages/db` and
// `packages/redis` keep reading their own env until they grow factories —
// an accepted pragmatic deviation (ADR-007 §7) — so this catalogue covers
-// only what `main.ts` itself reads today: TZ, ROLE, LOG_LEVEL, API_PORT and
-// SELF_HOSTED.
+// only what `main.ts` itself reads today: TZ, ROLE, LOG_LEVEL, API_PORT,
+// SELF_HOSTED and QUEUE_CLUSTER.
//
// Invalid config fails boot loudly, with every issue reported at once —
// never a fail-fast on the first bad var.
@@ -64,6 +64,21 @@ const envSchema = z.object({
.optional()
.default('false')
.transform((value) => value === TRUE_STRING),
+ /**
+ * Redis Cluster hash-tags every queue key (`cron` -> `{cron}`). Read here
+ * because `main.ts` hands it to `createProducers`, and it decides a Redis
+ * key name: set it on a deployment whose queues already exist unbraced and
+ * every one of them is orphaned. V1 read it as a bare truthy check
+ * (`packages/queue/src/queues.ts` `getQueueName`); a blank value is unset,
+ * exactly as before.
+ */
+ QUEUE_CLUSTER: z.preprocess(
+ blankToUndefined,
+ z
+ .string()
+ .optional()
+ .transform((value) => value !== undefined)
+ ),
});
export type Config = z.infer<typeof envSchema>;
diff --git a/apps/api/src/main.ts b/apps/api/src/main.ts
index bced7c8e8..f2a20c96d 100644
--- a/apps/api/src/main.ts
+++ b/apps/api/src/main.ts
@@ -3,12 +3,14 @@
// keeps serving the golden harness untouched until `apps/worker` is deleted
// at P9.
//
-// This is the M3 gate boot only: db/ch/redis/clients are not wired into
-// `AppDeps` yet — their types stay the `unknown` stubs `context.ts` declares
-// until P3/P4 land the real clients — so only the ops surface (healthz +
-// metrics) is mounted here. `dashboardRoutes`/`publicApiRoutes` land with
-// their first module (see `rest.routes.ts`). The buffers ARE real from M8-001:
-// `createBuffers` builds them once, here, and nowhere else.
+// This is the M3 gate boot only: db/ch/clients are not wired into `AppDeps`
+// yet — their types stay the `unknown` stubs `context.ts` declares until
+// P3/P4 land the real clients — so only the ops surface (healthz + metrics)
+// is mounted here. `dashboardRoutes`/`publicApiRoutes` land with their first
+// module (see `rest.routes.ts`). The buffers ARE real from M8-001:
+// `createBuffers` builds them once, here, and nowhere else. The producers are
+// real from M9-001: all seven queues, envelope on, byte-identical Redis keys.
+// Workers, schedulers and the ingest consumer are M9-002.
process.env.TZ = 'UTC';
@@ -16,12 +18,15 @@ import {
type AppDeps,
type BufferDeps,
createBuffers,
+ createProducers,
opsRoutes,
type QueueProducerHandle,
+ queueKey,
queues,
registerBufferMetrics,
} from '@openpanel/core';
import { produceIncomingEvent } from '@openpanel/queue';
+import { getRedisQueue } from '@openpanel/redis';
import pino from 'pino';
import { type Config, loadConfig } from './config/env';
@@ -55,53 +60,45 @@ const config = loadConfigOrExit();
const logger = pino({ name: 'api', level: config.LOG_LEVEL });
/**
- * `AppDeps.producers` needs a real `QueueProducerHandle`, but core's exports
- * map (ADR-008) only publishes the type — `createProducers` is internal.
- * Every registry queue's `jobs` map is still empty (no module has landed
- * one, see jobs.registry.ts), so there is nothing to enqueue yet; this stub
- * satisfies the type with no Redis connection. It is replaced by a real
- * `createProducers` call site inside core once a module needs to enqueue.
+ * All seven queues, envelope on, on the Redis keys V1 already uses — so a job
+ * V1 enqueued before the cutover is read back by V2's `resolveJob` through
+ * that queue's compat hook, with no drain and no rename (ADR-005).
+ *
+ * The connection is `packages/redis`'s dedicated queue client: a separate
+ * client from cache/pub/sub with `maxRetriesPerRequest: null`, which is what
+ * BullMQ requires and exactly what V1's `packages/queue` producers connect
+ * through. It stays that package's singleton to close (ADR-007 §7's accepted
+ * pragmatic deviation); `producers.close()` closes the queues over it.
*/
-function stubProducers(): QueueProducerHandle {
- const emptyQueues = Object.fromEntries(
- Object.keys(queues).map((name) => [name, {}])
- ) as QueueProducerHandle['queues'];
-
- const notWired = (): never => {
- throw new Error('Job producers are not wired up yet (M3 boot stub)');
- };
-
- return {
- queues: emptyQueues,
- scope: () => emptyQueues,
- enqueue: notWired,
- remove: notWired,
- bullQueues: [],
- close: () => Promise.resolve(),
- };
+function buildProducerHandle(): QueueProducerHandle {
+ return createProducers(queues, {
+ connection: getRedisQueue(),
+ cluster: config.QUEUE_CLUSTER,
+ logger,
+ });
}
/**
* A named child of the boot logger per buffer, plus the buffers' one direct
* BullMQ read — ADR-005's `bullQueues` escape hatch.
* Pausing `cron` from bull-board halts ALL buffer flushing, preserved
- * deliberately (docs/ANSWERS.md §3: "known!"). The M3 producer stub owns no
- * queues yet, and a queue that does not exist has not been paused.
+ * deliberately (docs/ANSWERS.md §3: "known!").
*/
function bufferDeps(producers: QueueProducerHandle): BufferDeps {
+ // `bullQueues` are keyed by the Redis name, which `QUEUE_CLUSTER` braces.
+ const cronKey = queueKey(CRON_QUEUE_NAME, { cluster: config.QUEUE_CLUSTER });
+
return {
createLogger: (name) => logger.child({ name }),
isCronPaused: async () => {
- const cron = producers.bullQueues.find(
- (queue) => queue.name === CRON_QUEUE_NAME
- );
+ const cron = producers.bullQueues.find((queue) => queue.name === cronKey);
return cron ? await cron.isPaused() : false;
},
};
}
function buildDeps(): AppDeps {
- const producers = stubProducers();
+ const producers = buildProducerHandle();
return {
// db/ch/redis/clients are `unknown` stubs in context.ts until P3/P4 land
// the real clients — reading one before its type lands is meant to be a
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 76ece8588..9b9c9580d 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -142,6 +142,33 @@ export type {
} from './context';
export { createCtx, extendCtx } from './context';
export { requestContext, requestLogging } from './http/context';
+// The two runtime seams over the registry (ADR-005). `main.ts` builds
+// producers in every role and workers only where the role consumes; both take
+// the registry as data, so neither opens a connection until it is called.
+export type {
+ AnyJob,
+ EnqueueOptions,
+ QueueDefinition,
+} from './jobs/define';
+export type { JobEnvelope, JobMeta } from './jobs/envelope';
+export { queueKey } from './jobs/naming';
+export type { CreateProducersOptions } from './jobs/producers';
+export { createProducers } from './jobs/producers';
+export type {
+ SchedulerDefinition,
+ SchedulerFlags,
+} from './jobs/schedulers';
+export {
+ CRON_SCHEDULES,
+ PING_SCHEDULE,
+ startSchedulers,
+} from './jobs/schedulers';
+export type {
+ StartWorkersOptions,
+ TerminalFailure,
+ WorkerHandle,
+} from './jobs/workers';
+export { startWorkers } from './jobs/workers';
export type {
QueueProducerHandle,
QueueProducers,
@@ -277,7 +304,6 @@ export {
verifyPasswordHash,
verifyTotpCode,
} from './modules/auth/auth.service';
-export { getIsRegistrationAllowed } from './modules/auth/src/registration';
// Moved from packages/db/src/services/auth-session.service.ts (M8-005) —
// the Postgres-backed login session CRUD. packages/db keeps a re-export
// shim (existing `@openpanel/db` importers, apps/api's app.ts).
@@ -289,6 +315,7 @@ export {
invalidateSession,
validateSessionToken,
} from './modules/auth/src/login-session';
+export { getIsRegistrationAllowed } from './modules/auth/src/registration';
// Dissolved from @openpanel/db's services/chart.service.ts and engine/
// (M7-003) — packages/trpc's chart router, apps/api's export controller,
// V1's funnel/conversion/sankey/retention/overview services and the
@@ -364,12 +391,6 @@ export {
rewriteProfilePropertyRefs,
transformPropertyKey,
} from './modules/chart/chart.service';
-// Moved from packages/db/src/services/filter-where.service.ts (M8-005) — the
-// sessions/profiles/events-table filter compiler, distinct from
-// `getEventFiltersWhereClause` above. packages/db/src/services/
-// filter-where.service.ts stays a re-export shim.
-export type { FilterTableContext } from './modules/chart/src/table-filter-where';
-export { buildFilterWhere } from './modules/chart/src/table-filter-where';
// Dissolved from @openpanel/db's services/conversion.service.ts (M7-004) —
// reached through the chart module's own dispatch and the db shim.
export { getConversion } from './modules/chart/conversion.service';
@@ -427,6 +448,12 @@ export {
getUserFlowCore,
zGetSankeyInput,
} from './modules/chart/sankey.service';
+// Moved from packages/db/src/services/filter-where.service.ts (M8-005) — the
+// sessions/profiles/events-table filter compiler, distinct from
+// `getEventFiltersWhereClause` above. packages/db/src/services/
+// filter-where.service.ts stays a re-export shim.
+export type { FilterTableContext } from './modules/chart/src/table-filter-where';
+export { buildFilterWhere } from './modules/chart/src/table-filter-where';
// Dissolved from @openpanel/db's services/clients.service.ts (M6-002) —
// packages/trpc's client router, apps/api's manage controller and mcp/utils
// auth call these directly, the same way V1 reaches every other dissolved
diff --git a/packages/core/src/jobs.registry.test.ts b/packages/core/src/jobs.registry.test.ts
index 482371196..e102d5a77 100644
--- a/packages/core/src/jobs.registry.test.ts
+++ b/packages/core/src/jobs.registry.test.ts
@@ -1,4 +1,5 @@
import { expect, test } from 'bun:test';
+import { CRON_SCHEDULES, PING_SCHEDULE } from './jobs/schedulers';
import { queues } from './jobs.registry';
// V1's `defaultJobOptions`, verbatim from packages/queue/src/queues.ts.
@@ -213,3 +214,31 @@ test('the notification queue carries the notification module job', () => {
name: 'sendNotification',
});
});
+
+// M9-001: every scheduler id must land on a cron job that exists, or the
+// scheduled run resolves (legacyCompat.cron maps `type` straight onto a job
+// name) and then throws `has no job named ...`.
+//
+// Three ids do not yet: `dataHealth`, `windDown` and `flushExports` are still
+// only implemented in apps/worker/src/jobs (cron.data-health.ts,
+// cron.wind-down.ts, cron.flush-exports.ts) and are ported with the rest of
+// the worker at M9-003 ("every job the old worker ran is served by the merged
+// app under ROLE=worker"). Pinned as a precise, exhaustive exception set so
+// the gap is loud here rather than silent in production — and so M9-003 has
+// to delete this list to go green.
+const CRON_JOBS_NOT_YET_PORTED = ['dataHealth', 'flushExports', 'windDown'];
+
+test('every cron scheduler id has a handler, bar the three M9-003 ports', () => {
+ const declared = new Set(Object.keys(queues.cron.jobs));
+ const scheduled = [...CRON_SCHEDULES, PING_SCHEDULE].map(
+ (scheduler) => scheduler.id
+ );
+
+ expect(scheduled.filter((id) => !declared.has(id)).sort()).toEqual(
+ CRON_JOBS_NOT_YET_PORTED
+ );
+ // The reverse direction: nothing is registered that nothing ever schedules.
+ expect(
+ [...declared].filter((name) => !scheduled.includes(name)).sort()
+ ).toEqual([]);
+});
diff --git a/packages/core/src/jobs/producers.ts b/packages/core/src/jobs/producers.ts
index 2e65302f9..0d5c5bdb6 100644
--- a/packages/core/src/jobs/producers.ts
+++ b/packages/core/src/jobs/producers.ts
@@ -3,6 +3,7 @@ import {
type ConnectionOptions,
type JobsOptions,
} from 'bullmq';
+import type { Logger } from '../logger';
import type {
AnyBoundJob,
EnqueueOptions,
@@ -48,6 +49,14 @@ export interface CreateProducersOptions {
/** `QUEUE_CLUSTER`. Off in every deployment that exists today — see `queueKey`. */
cluster?: boolean;
namespace?: string;
+ /**
+ * Where a queue's connection errors go. BullMQ re-emits ioredis errors on
+ * every `Queue`, and an `'error'` event with no listener is an uncaught
+ * exception that kills the process — V1 lost the api roughly daily to idle
+ * ECONNRESETs before `guardQueue` was added (packages/queue/src/queues.ts).
+ * A listener is attached either way; this decides whether it says anything.
+ */
+ logger?: Logger;
}
/**
@@ -59,18 +68,29 @@ export interface CreateProducersOptions {
*/
export function createProducers<TQueues extends QueueMap>(
definitions: TQueues,
- { connection, cluster, namespace }: CreateProducersOptions
+ { connection, cluster, namespace, logger }: CreateProducersOptions
): ProducerHandle<TQueues> {
const bullQueues = new Map<string, BullQueue>();
for (const definition of Object.values(definitions)) {
- bullQueues.set(
- definition.name,
- new BullQueue(queueKey(definition.name, { cluster, namespace }), {
+ const queue = new BullQueue(
+ queueKey(definition.name, { cluster, namespace }),
+ {
connection,
defaultJobOptions: toJobsOptions(definition.defaults),
- })
+ }
+ );
+
+ // Never omitted: the listener is what stops a reconnectable socket error
+ // from taking the process down. ioredis reconnects on its own.
+ queue.on('error', (error) =>
+ logger?.error(
+ { err: error, queue: definition.name },
+ 'queue connection error'
+ )
);
+
+ bullQueues.set(definition.name, queue);
}
const queueFor = (name: string): BullQueue => {
diff --git a/packages/core/src/jobs/workers.ts b/packages/core/src/jobs/workers.ts
index 826a67617..96ecd9ac9 100644
--- a/packages/core/src/jobs/workers.ts
+++ b/packages/core/src/jobs/workers.ts
@@ -8,6 +8,7 @@ import { REQUEST_ID_LENGTH, REQUEST_ID_LOG_FIELD } from '../logger';
import { generateId } from '../shared/id';
import { resolveJob } from './compat';
import type { QueueDefinition, QueueMap } from './define';
+import { isEnvelope } from './envelope';
import { queueKey } from './naming';
export interface TerminalFailure {
@@ -181,5 +182,18 @@ export async function runJob(
ctx: JobCtx;
}) => Promise<void>;
+ // `debug`, not `info`: `sessions` runs one of these per session close.
+ // `legacy` is the cutover's own signal — while it is still ever true, a
+ // V1-shaped job is still being replayed and the compat hooks cannot go
+ // (ADR-005 risk 1).
+ const legacy = !isEnvelope(job.data);
+ logger.debug({ legacy }, 'job started');
+ const startedAt = performance.now();
+
await handler({ payload, ctx });
+
+ logger.debug(
+ { legacy, durationMs: Math.round(performance.now() - startedAt) },
+ 'job completed'
+ );
}