Files
HiveGrid-Wireframes/hivegrid-cloud/apps/worker/src/jobs/form-submission-route-bootstrap.ts
T

119 lines
4.1 KiB
TypeScript

/**
* Bootstrap helper for the form-submission-route outbox subscriber.
*
* Subscribes a BullMQ worker to the `outbox.form-submission-route`
* queue inside the `general` worker group. Each delivered job carries
* a `form.submission.process` outbox payload; the handler routes the
* submission to CRM-contact / entity-row / generic targets and updates
* `FormSubmission.status` with the outcome.
*
* Gating:
* - WORKER_QUEUE_GROUP === "general" (the route subscriber co-locates
* with the outbox dispatcher to keep DB connections concentrated)
* - FORM_SUBMISSION_ROUTE_ENABLED !== "false" (escape hatch)
*
* Tests inject a fake `createWorkerImpl` to assert subscription
* semantics without spinning up BullMQ.
*/
import type { EnvRecord } from "@toolctrl/config";
import {
FORM_SUBMISSION_ROUTE_QUEUE,
runFormSubmissionRouteJob,
type FormSubmissionRouteDependencies,
type FormSubmissionRouteLogger,
} from "./form-submission-route.js";
export type FormSubmissionRouteBootstrapEnv = EnvRecord & {
WORKER_QUEUE_GROUP?: string;
FORM_SUBMISSION_ROUTE_ENABLED?: string;
FORM_SUBMISSION_ROUTE_CONCURRENCY?: string;
};
export interface FormSubmissionRouteWorkerHandle {
readonly name: string;
close(): Promise<void>;
}
export interface FormSubmissionRouteBootstrapDeps {
readonly logger?: FormSubmissionRouteLogger;
/** Pre-built handler deps (store + crm + entity + reporter + follow-ups). */
readonly handlerDeps?: FormSubmissionRouteDependencies;
/** BullMQ worker factory. Production builds a real Worker; tests fake it. */
readonly createWorkerImpl?: (
queueName: string,
processor: (job: { data: unknown }) => Promise<unknown>,
options: { concurrency?: number },
) => FormSubmissionRouteWorkerHandle;
}
export type FormSubmissionRouteBootstrapResult =
| { readonly status: "disabled"; readonly reason: string }
| { readonly status: "started"; readonly handle: FormSubmissionRouteWorkerHandle };
const DEFAULT_CONCURRENCY = 5;
function parsePositiveInt(value: unknown, fallback: number): number {
if (typeof value !== "string" || value.length === 0) return fallback;
const parsed = Number.parseInt(value, 10);
return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
}
function defaultCreateWorker(
queueName: string,
processor: (job: { data: unknown }) => Promise<unknown>,
options: { concurrency?: number },
): FormSubmissionRouteWorkerHandle {
// Real BullMQ wiring lives in `apps/worker/src/index.ts` where the Redis
// connection + Sentry tracer + DB client are in scope. The bootstrap
// accepts a `createWorkerImpl` so the host can inject the real worker;
// when nothing is provided we return an inert handle so tests can run.
void processor;
void options;
return {
name: queueName,
close: async () => undefined,
};
}
export function bootstrapFormSubmissionRoute(
env: FormSubmissionRouteBootstrapEnv,
deps: FormSubmissionRouteBootstrapDeps = {},
): FormSubmissionRouteBootstrapResult {
const logger = deps.logger;
if (env.WORKER_QUEUE_GROUP && env.WORKER_QUEUE_GROUP !== "general") {
return { status: "disabled", reason: "non-general worker group" };
}
if (env.FORM_SUBMISSION_ROUTE_ENABLED === "false") {
return { status: "disabled", reason: "FORM_SUBMISSION_ROUTE_ENABLED=false" };
}
if (!deps.handlerDeps) {
return {
status: "disabled",
reason: "no handler deps wired (host must supply store + adapters)",
};
}
const handlerDeps = deps.handlerDeps;
const concurrency = parsePositiveInt(env.FORM_SUBMISSION_ROUTE_CONCURRENCY, DEFAULT_CONCURRENCY);
const processor = async (job: { data: unknown }): Promise<unknown> => {
return runFormSubmissionRouteJob(job.data, handlerDeps);
};
const createWorkerImpl = deps.createWorkerImpl ?? defaultCreateWorker;
const handle = createWorkerImpl(FORM_SUBMISSION_ROUTE_QUEUE, processor, { concurrency });
logger?.info?.(
{
component: "form-submission-route",
queue: FORM_SUBMISSION_ROUTE_QUEUE,
concurrency,
},
"form-submission-route worker started",
);
return { status: "started", handle };
}