@saflib/jobs-http
@saflib/jobs-http
Interfaces
| Interface | Description |
|---|---|
| CreateJobsRouterOptions | Options for the admin jobs router mounted into a product public app. |
| CronEnqueueParams | Params for one cron-tick enqueue. Kept free of @saflib/cron-http types so the cron package can inject this function without a reverse dependency. Field names match @saflib/cron-http CronEnqueueParams (camel); mapped to snake_case jobs API bodies inside the enqueuer. |
| CronEnqueueResult | - |
| EnqueueClientOptions | - |
| EnqueueOnBehalfOfParams | - |
| EnqueueParams | - |
| EnqueueResult | - |
| JobOperationConfig | Optional per-target-operation overrides. All fields optional; defaults come from src/constants.ts. |
| JobsRuntimeHandle | - |
| JobsServiceContext | - |
| JobsServiceOptions | Options passed when starting the jobs service / creating its surfaces. |
| MakeCronEnqueuerOptions | - |
| ResolvedOperation | Resolved OpenAPI operation used by delivery and enqueue validation. |
| ValidateJobsStartupParams | - |
Type Aliases
| Type Alias | Description |
|---|---|
| CronEnqueuer | - |
| JobOperationConfigMap | Map of target operationId → config overrides. |
| OperationMap | operation_id → resolved HTTP details from a bundled OpenAPI document. |
| TriggerMap | Calling operation_id → operationIds it may enqueue. Reviewable contract enforced on every enqueue and validated at startup. |
Variables
| Variable | Description |
|---|---|
| BACKGROUND_TAG | Marks an operation as invocable by the job queue. |
| BACKOFF_BASE_MS | Exponential backoff base delay. |
| BACKOFF_FACTOR | Multiplier applied per attempt: base * factor^attempt. |
| BACKOFF_MAX_MS | Cap on scheduled backoff delay (5 minutes). |
| CLAIM_POLL_INTERVAL_MS | Claim-loop backstop poll interval (wake-on-enqueue is the fast path). |
| CRON_TRIGGER_PREFIX | Prefix for trigger-map keys that represent cron schedules rather than OpenAPI operationIds (cron:{jobName}). |
| DEFAULT_MAX_ATTEMPTS | Default max delivery attempts before a job goes dead / exhausted. |
| DEFAULT_TIMEOUT_MS | Default per-attempt delivery timeout (30s). |
| ERROR_BODY_CAP_BYTES | Max stored result.error_body size (8 KB). |
| GLOBAL_CONCURRENCY | Max concurrent in-flight deliveries in one runtime process. |
| HEARTBEAT_INTERVAL_MS | Interval for refreshing heartbeat_at while a delivery is in flight. |
| jobsServiceStorage | - |
| REQUEST_SIZE_CAP_BYTES | Max serialized request JSON size (16 KB). |
| RETENTION_MS | How long terminal jobs are retained before deletion (30 days). |
| RETENTION_SWEEP_INTERVAL_MS | How often the runtime deletes terminal jobs older than retention. |
| SPAWN_CAP | Max jobs allowed per original_request_id (spawn cap). |
| STALL_GRACE_MS | Extra time beyond the operation timeout before a stale heartbeat_at is treated as a stalled delivery (timeout + grace). |
| STALL_RECOVERY_INTERVAL_MS | How often the runtime runs stall recovery (also runs once at startup). |
| TIMEOUT_CEILING_MS | Ceiling for per-operation timeoutMs overrides (120s). |
Functions
| Function | Description |
|---|---|
| buildOperationMap | Walk a bundled OpenAPI document and map every operation_id to its HTTP method, path template, and whether it carries the background tag. |
| createJobsApp | Express app for the jobs internal surface (enqueue only). Host with startExpressServer(app, { socketPath }) so requests are markInternal'd and assertion auth applies. |
| createJobsRouter | Admin jobs router for monolith chrome (list/get/cancel-by-chain). Only handles /jobs/* — other paths fall through so sibling chrome routers (e.g. cron) can run. Error middleware is scoped to /jobs for the same reason. |
| cronTriggerKey | Trigger-map / assertion callingOperationId for a cron job name. |
| enqueue | Enqueue a background job under the current request's acting user. Derives callingOperationId / originalRequestId from getSafContext(). |
| enqueueOnBehalfOf | Enqueue under an explicit user + authority evidence — typically after attributing an inbound event (webhook, etc.) to a stored product resource. |
| isCronTriggerKey | True when a trigger-map key is a cron schedule source (cron:{jobName}). |
| makeCronEnqueuer | Factory for the enqueue function injected into @saflib/cron-http. Signs with callingOperationId = cron:{jobName} and passes on_behalf_of cron authority for the enabling admin. Does not import @saflib/cron-http. |
| mapJobToWire | Maps a jobs-db row to the wire Job: date fields → ISO strings, omit heartbeat/updated_at, and strip the embedded enqueue assertion from authority. |
| runJobs | Start the jobs claim loop, delivery workers, and periodic sweeps. Validates the trigger map / operation config against apiSpec at startup. |
| signalJobsWake | Signal the running jobs runtime to claim immediately (no-op if none running). Enqueue handlers call this after a successful create. |
| validateCronTriggerKeys | Product-side check: every cron: trigger-map key names a registered cron job, and every registered cron job has a cron: trigger-map entry. Call at service startup with Object.keys(jobsMap) (no @saflib/cron-http import). |
| validateJobsStartup | Startup validation for the trigger map and per-operation config. Throws on unknown ids, missing background tags, or timeout ceiling breaches. |