@facilis.dev/nitro 0.0.0-stage → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +18 -2
- package/dist/config.d.ts +30 -0
- package/dist/config.js +112 -0
- package/dist/constants.d.ts +24 -0
- package/dist/constants.js +24 -0
- package/dist/facade.d.ts +37 -0
- package/dist/facade.js +121 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +14 -0
- package/dist/middleware/context.d.ts +5 -0
- package/dist/middleware/context.js +86 -0
- package/dist/middleware/cors.d.ts +10 -0
- package/dist/middleware/cors.js +34 -0
- package/dist/middleware/session.d.ts +9 -0
- package/dist/middleware/session.js +18 -0
- package/dist/module.d.ts +7 -0
- package/dist/module.js +234 -0
- package/dist/rolldown-parser.d.ts +3 -0
- package/dist/rolldown-parser.js +66 -0
- package/dist/route-metadata.d.ts +22 -0
- package/dist/route-metadata.js +161 -0
- package/dist/routes/dev-query.post.d.ts +10 -0
- package/dist/routes/dev-query.post.js +49 -0
- package/dist/routes/dev-schema.get.d.ts +9 -0
- package/dist/routes/dev-schema.get.js +34 -0
- package/dist/routes/dev-view.post.d.ts +11 -0
- package/dist/routes/dev-view.post.js +61 -0
- package/dist/routes/health.get.d.ts +8 -0
- package/dist/routes/health.get.js +18 -0
- package/dist/routes/manifest-revision.get.d.ts +8 -0
- package/dist/routes/manifest-revision.get.js +26 -0
- package/dist/routes/manifest.get.d.ts +8 -0
- package/dist/routes/manifest.get.js +68 -0
- package/dist/routes/openapi.get.d.ts +8 -0
- package/dist/routes/openapi.get.js +29 -0
- package/dist/routes/sso.d.ts +2 -0
- package/dist/routes/sso.js +216 -0
- package/dist/routes/token.post.d.ts +10 -0
- package/dist/routes/token.post.js +75 -0
- package/dist/runtime/boot-runtimes.d.ts +21 -0
- package/dist/runtime/boot-runtimes.js +38 -0
- package/dist/runtime/bootstrap.d.ts +47 -0
- package/dist/runtime/bootstrap.js +214 -0
- package/dist/runtime/config.d.ts +27 -0
- package/dist/runtime/config.js +44 -0
- package/dist/runtime/cors-policy.d.ts +16 -0
- package/dist/runtime/cors-policy.js +88 -0
- package/dist/runtime/db-bootstrap.d.ts +9 -0
- package/dist/runtime/db-bootstrap.js +87 -0
- package/dist/runtime/db-target.d.ts +21 -0
- package/dist/runtime/db-target.js +52 -0
- package/dist/runtime/dev-db-persistence.d.ts +39 -0
- package/dist/runtime/dev-db-persistence.js +124 -0
- package/dist/runtime/dev-query.d.ts +38 -0
- package/dist/runtime/dev-query.js +87 -0
- package/dist/runtime/env.d.ts +9 -0
- package/dist/runtime/env.js +14 -0
- package/dist/runtime/http-guard.d.ts +16 -0
- package/dist/runtime/http-guard.js +42 -0
- package/dist/runtime/http.d.ts +11 -0
- package/dist/runtime/http.js +18 -0
- package/dist/runtime/jobs/boot.d.ts +20 -0
- package/dist/runtime/jobs/boot.js +77 -0
- package/dist/runtime/jobs/contracts.d.ts +161 -0
- package/dist/runtime/jobs/contracts.js +1 -0
- package/dist/runtime/jobs/db-store.d.ts +21 -0
- package/dist/runtime/jobs/db-store.js +210 -0
- package/dist/runtime/jobs/definitions.d.ts +14 -0
- package/dist/runtime/jobs/definitions.js +31 -0
- package/dist/runtime/jobs/engine-support.d.ts +22 -0
- package/dist/runtime/jobs/engine-support.js +32 -0
- package/dist/runtime/jobs/engine.d.ts +6 -0
- package/dist/runtime/jobs/engine.js +261 -0
- package/dist/runtime/jobs/executor.d.ts +11 -0
- package/dist/runtime/jobs/executor.js +27 -0
- package/dist/runtime/jobs/memory-store.d.ts +7 -0
- package/dist/runtime/jobs/memory-store.js +183 -0
- package/dist/runtime/jobs/row-mapping.d.ts +28 -0
- package/dist/runtime/jobs/row-mapping.js +61 -0
- package/dist/runtime/jobs/runtime.d.ts +24 -0
- package/dist/runtime/jobs/runtime.js +86 -0
- package/dist/runtime/logging/audit-chain.d.ts +54 -0
- package/dist/runtime/logging/audit-chain.js +102 -0
- package/dist/runtime/logging/bootstrap-logging.d.ts +28 -0
- package/dist/runtime/logging/bootstrap-logging.js +26 -0
- package/dist/runtime/logging/entry.d.ts +14 -0
- package/dist/runtime/logging/entry.js +85 -0
- package/dist/runtime/logging/file-sink.d.ts +24 -0
- package/dist/runtime/logging/file-sink.js +128 -0
- package/dist/runtime/logging/log-settings.d.ts +52 -0
- package/dist/runtime/logging/log-settings.js +93 -0
- package/dist/runtime/logging/log-sink.d.ts +18 -0
- package/dist/runtime/logging/log-sink.js +22 -0
- package/dist/runtime/logging/redact.d.ts +31 -0
- package/dist/runtime/logging/redact.js +106 -0
- package/dist/runtime/logging/runtime.d.ts +25 -0
- package/dist/runtime/logging/runtime.js +114 -0
- package/dist/runtime/logging/sudo-bridge.d.ts +13 -0
- package/dist/runtime/logging/sudo-bridge.js +38 -0
- package/dist/runtime/manifest-data.d.ts +28 -0
- package/dist/runtime/manifest-data.js +70 -0
- package/dist/runtime/manifest-response.d.ts +45 -0
- package/dist/runtime/manifest-response.js +50 -0
- package/dist/runtime/manifest-sections.d.ts +20 -0
- package/dist/runtime/manifest-sections.js +59 -0
- package/dist/runtime/manifest-service.d.ts +16 -0
- package/dist/runtime/manifest-service.js +66 -0
- package/dist/runtime/project-config.d.ts +8 -0
- package/dist/runtime/project-config.js +22 -0
- package/dist/runtime/project-files.d.ts +12 -0
- package/dist/runtime/project-files.js +99 -0
- package/dist/runtime/rate-limit.d.ts +6 -0
- package/dist/runtime/rate-limit.js +6 -0
- package/dist/runtime/revision-service.d.ts +15 -0
- package/dist/runtime/revision-service.js +26 -0
- package/dist/runtime/sql.d.ts +8 -0
- package/dist/runtime/sql.js +23 -0
- package/dist/runtime/sso.d.ts +40 -0
- package/dist/runtime/sso.js +98 -0
- package/dist/runtime/state.d.ts +7 -0
- package/dist/runtime/state.js +7 -0
- package/dist/runtime/storage-keys.d.ts +9 -0
- package/dist/runtime/storage-keys.js +82 -0
- package/dist/runtime/storage-target.d.ts +25 -0
- package/dist/runtime/storage-target.js +155 -0
- package/dist/runtime/system-role.d.ts +9 -0
- package/dist/runtime/system-role.js +21 -0
- package/dist/runtime/tasks/boot.d.ts +20 -0
- package/dist/runtime/tasks/boot.js +32 -0
- package/dist/runtime/tasks/contracts.d.ts +70 -0
- package/dist/runtime/tasks/contracts.js +1 -0
- package/dist/runtime/tasks/db-store.d.ts +18 -0
- package/dist/runtime/tasks/db-store.js +139 -0
- package/dist/runtime/tasks/row-mapping.d.ts +11 -0
- package/dist/runtime/tasks/row-mapping.js +69 -0
- package/dist/runtime/tasks/runtime.d.ts +7 -0
- package/dist/runtime/tasks/runtime.js +162 -0
- package/dist/runtime/tasks/tasks-test-harness.d.ts +16 -0
- package/dist/runtime/tasks/tasks-test-harness.js +70 -0
- package/dist/runtime/tenant.d.ts +10 -0
- package/dist/runtime/tenant.js +13 -0
- package/dist/runtime/workflows/boot.d.ts +25 -0
- package/dist/runtime/workflows/boot.js +75 -0
- package/dist/runtime/workflows/contracts.d.ts +96 -0
- package/dist/runtime/workflows/contracts.js +1 -0
- package/dist/runtime/workflows/db-store.d.ts +18 -0
- package/dist/runtime/workflows/db-store.js +128 -0
- package/dist/runtime/workflows/definitions.d.ts +14 -0
- package/dist/runtime/workflows/definitions.js +50 -0
- package/dist/runtime/workflows/dispatch.d.ts +4 -0
- package/dist/runtime/workflows/dispatch.js +119 -0
- package/dist/runtime/workflows/row-mapping.d.ts +5 -0
- package/dist/runtime/workflows/row-mapping.js +38 -0
- package/dist/runtime/workflows/runner.d.ts +15 -0
- package/dist/runtime/workflows/runner.js +89 -0
- package/dist/runtime/workflows/runtime.d.ts +14 -0
- package/dist/runtime/workflows/runtime.js +129 -0
- package/dist/runtime/workflows/steps.d.ts +14 -0
- package/dist/runtime/workflows/steps.js +49 -0
- package/dist/runtime/workflows/support.d.ts +20 -0
- package/dist/runtime/workflows/support.js +36 -0
- package/dist/runtime/workflows/transitions.d.ts +8 -0
- package/dist/runtime/workflows/transitions.js +184 -0
- package/dist/runtime/workflows/workflows-test-harness.d.ts +62 -0
- package/dist/runtime/workflows/workflows-test-harness.js +178 -0
- package/dist/session-cookie.d.ts +13 -0
- package/dist/session-cookie.js +48 -0
- package/dist/storage.d.ts +50 -0
- package/dist/storage.js +118 -0
- package/dist/types.d.ts +44 -0
- package/dist/types.js +1 -0
- package/dist/virtual-ids.d.ts +17 -0
- package/dist/virtual-ids.js +17 -0
- package/dist/vite.d.ts +22 -0
- package/dist/vite.js +135 -0
- package/package.json +61 -4
- package/src/config.ts +120 -0
- package/src/constants.ts +24 -0
- package/src/facade.ts +153 -0
- package/src/index.ts +44 -0
- package/src/middleware/context.ts +106 -0
- package/src/middleware/cors.ts +42 -0
- package/src/middleware/session.ts +23 -0
- package/src/module.ts +278 -0
- package/src/rolldown-parser.ts +79 -0
- package/src/route-metadata-test-harness.ts +62 -0
- package/src/route-metadata.ts +194 -0
- package/src/routes/dev-query.post.ts +53 -0
- package/src/routes/dev-schema.get.ts +43 -0
- package/src/routes/dev-view.post.ts +66 -0
- package/src/routes/health.get.ts +26 -0
- package/src/routes/manifest-revision.get.ts +38 -0
- package/src/routes/manifest.get.ts +111 -0
- package/src/routes/openapi.get.ts +34 -0
- package/src/routes/sso.ts +247 -0
- package/src/routes/token.post.ts +89 -0
- package/src/runtime/boot-runtimes.ts +69 -0
- package/src/runtime/bootstrap.ts +300 -0
- package/src/runtime/config.ts +60 -0
- package/src/runtime/cors-policy.ts +107 -0
- package/src/runtime/db-bootstrap.ts +99 -0
- package/src/runtime/db-target.ts +87 -0
- package/src/runtime/dev-db-persistence.ts +146 -0
- package/src/runtime/dev-query.ts +124 -0
- package/src/runtime/env.ts +18 -0
- package/src/runtime/http-guard.ts +50 -0
- package/src/runtime/http.ts +30 -0
- package/src/runtime/jobs/boot.ts +97 -0
- package/src/runtime/jobs/contracts.ts +165 -0
- package/src/runtime/jobs/db-store-test-harness.ts +98 -0
- package/src/runtime/jobs/db-store.ts +273 -0
- package/src/runtime/jobs/definitions.ts +42 -0
- package/src/runtime/jobs/engine-support.ts +44 -0
- package/src/runtime/jobs/engine.ts +296 -0
- package/src/runtime/jobs/executor.ts +37 -0
- package/src/runtime/jobs/memory-store.ts +222 -0
- package/src/runtime/jobs/row-mapping.ts +67 -0
- package/src/runtime/jobs/runtime.ts +110 -0
- package/src/runtime/logging/audit-chain.ts +135 -0
- package/src/runtime/logging/bootstrap-logging.ts +62 -0
- package/src/runtime/logging/entry.ts +99 -0
- package/src/runtime/logging/file-sink.ts +157 -0
- package/src/runtime/logging/log-settings.ts +166 -0
- package/src/runtime/logging/log-sink.ts +31 -0
- package/src/runtime/logging/redact.ts +108 -0
- package/src/runtime/logging/runtime.ts +163 -0
- package/src/runtime/logging/sudo-bridge.ts +41 -0
- package/src/runtime/manifest-data.ts +103 -0
- package/src/runtime/manifest-response.ts +95 -0
- package/src/runtime/manifest-sections.ts +79 -0
- package/src/runtime/manifest-service.ts +83 -0
- package/src/runtime/project-config.ts +25 -0
- package/src/runtime/project-files.ts +103 -0
- package/src/runtime/rate-limit.ts +12 -0
- package/src/runtime/revision-service.ts +38 -0
- package/src/runtime/sql.ts +24 -0
- package/src/runtime/sso.ts +153 -0
- package/src/runtime/state.ts +7 -0
- package/src/runtime/storage-keys.ts +95 -0
- package/src/runtime/storage-target.ts +238 -0
- package/src/runtime/system-role.ts +26 -0
- package/src/runtime/tasks/boot.ts +49 -0
- package/src/runtime/tasks/contracts.ts +77 -0
- package/src/runtime/tasks/db-store.ts +191 -0
- package/src/runtime/tasks/row-mapping.ts +75 -0
- package/src/runtime/tasks/runtime.ts +192 -0
- package/src/runtime/tasks/tasks-test-harness.ts +92 -0
- package/src/runtime/tenant.ts +15 -0
- package/src/runtime/workflows/boot.ts +97 -0
- package/src/runtime/workflows/contracts.ts +114 -0
- package/src/runtime/workflows/db-store.ts +156 -0
- package/src/runtime/workflows/definitions.ts +75 -0
- package/src/runtime/workflows/dispatch.ts +148 -0
- package/src/runtime/workflows/row-mapping.ts +54 -0
- package/src/runtime/workflows/runner.ts +105 -0
- package/src/runtime/workflows/runtime.ts +161 -0
- package/src/runtime/workflows/steps.ts +74 -0
- package/src/runtime/workflows/support.ts +60 -0
- package/src/runtime/workflows/transitions.ts +259 -0
- package/src/runtime/workflows/workflows-test-harness.ts +238 -0
- package/src/session-cookie.ts +69 -0
- package/src/storage.ts +173 -0
- package/src/types.ts +51 -0
- package/src/virtual-ids.ts +18 -0
- package/src/virtual-modules.d.ts +53 -0
- package/src/vite.ts +175 -0
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
import { JobError, serializeJobData } from "@facilis.dev/core";
|
|
2
|
+
import type { JobDefinition, JobJson, JobListOptions } from "@facilis.dev/core";
|
|
3
|
+
import { TableAccessError, type PolicyScopedDatabase } from "@facilis.dev/db";
|
|
4
|
+
|
|
5
|
+
import type { JobCounts, JobEngine, JobEngineOptions, JobStore, StoredJob } from "./contracts.ts";
|
|
6
|
+
import {
|
|
7
|
+
errorMessage,
|
|
8
|
+
formatIssues,
|
|
9
|
+
INTERRUPTED_ERROR,
|
|
10
|
+
MAX_STORED_ERROR,
|
|
11
|
+
normalizeLimit,
|
|
12
|
+
SYSTEM_TIMERS,
|
|
13
|
+
} from "./engine-support.ts";
|
|
14
|
+
|
|
15
|
+
interface RunningAttempt {
|
|
16
|
+
readonly controller: AbortController;
|
|
17
|
+
cancelRequested: boolean;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
type AttemptOutcome =
|
|
21
|
+
| { readonly ok: true; readonly output: JobJson }
|
|
22
|
+
| {
|
|
23
|
+
readonly ok: false;
|
|
24
|
+
readonly error: string;
|
|
25
|
+
/** A declaration violation is deterministic: never requeued (D-157). */
|
|
26
|
+
readonly terminal?: boolean;
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* The scheduler (docs/JOBS.md §7): claims due jobs, runs at most `maxConcurrent` attempts,
|
|
31
|
+
* applies retry/timeout/cancel and delegates all state to the injected `JobStore`.
|
|
32
|
+
*/
|
|
33
|
+
export function createJobEngine(options: JobEngineOptions): JobEngine {
|
|
34
|
+
const { definitions, store, config, executor } = options;
|
|
35
|
+
const timers = options.timers ?? SYSTEM_TIMERS;
|
|
36
|
+
const report = (error: unknown, context: string): void => options.onError?.(error, context);
|
|
37
|
+
|
|
38
|
+
const running = new Map<string, RunningAttempt>();
|
|
39
|
+
const attempts = new Set<Promise<void>>();
|
|
40
|
+
let started = false;
|
|
41
|
+
let stopping = false;
|
|
42
|
+
let stopped = false;
|
|
43
|
+
let tickRunning = false;
|
|
44
|
+
let wakeRequested = false;
|
|
45
|
+
let tickTimer: unknown = null;
|
|
46
|
+
let stopPromise: Promise<void> | null = null;
|
|
47
|
+
|
|
48
|
+
const now = (): Date => new Date(timers.now());
|
|
49
|
+
|
|
50
|
+
function scheduleTick(delayMs: number): void {
|
|
51
|
+
if (!started || stopping) return;
|
|
52
|
+
if (tickTimer !== null) timers.clearTimeout(tickTimer);
|
|
53
|
+
tickTimer = timers.setTimeout(() => {
|
|
54
|
+
tickTimer = null;
|
|
55
|
+
void tick().catch(() => undefined);
|
|
56
|
+
}, delayMs);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Enqueue and attempt settlement ask for an immediate tick; a running tick defers to it. */
|
|
60
|
+
function requestTick(delayMs: number): void {
|
|
61
|
+
if (!started || stopping) return;
|
|
62
|
+
if (tickRunning) {
|
|
63
|
+
wakeRequested = true;
|
|
64
|
+
return;
|
|
65
|
+
}
|
|
66
|
+
scheduleTick(delayMs);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
async function tick(): Promise<void> {
|
|
70
|
+
if (!started || stopping || tickRunning) return;
|
|
71
|
+
tickRunning = true;
|
|
72
|
+
try {
|
|
73
|
+
const free = config.maxConcurrent - running.size;
|
|
74
|
+
if (free <= 0) return;
|
|
75
|
+
const claimed = await store.claim(now(), free);
|
|
76
|
+
// A stop() racing the claim must not start work the caller is shutting down.
|
|
77
|
+
if (stopping) {
|
|
78
|
+
await Promise.all(claimed.map((job) => interrupt(job)));
|
|
79
|
+
return;
|
|
80
|
+
}
|
|
81
|
+
for (const job of claimed) launch(job);
|
|
82
|
+
} catch (error) {
|
|
83
|
+
report(error, "engine.tick");
|
|
84
|
+
} finally {
|
|
85
|
+
tickRunning = false;
|
|
86
|
+
if (started && !stopping) {
|
|
87
|
+
const immediate = wakeRequested;
|
|
88
|
+
wakeRequested = false;
|
|
89
|
+
scheduleTick(immediate ? 0 : config.pollIntervalMs);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
async function interrupt(job: StoredJob): Promise<void> {
|
|
95
|
+
const finishedAt = now();
|
|
96
|
+
if (job.attempts >= job.maxAttempts) {
|
|
97
|
+
await store.complete(job.id, { status: "failed", error: INTERRUPTED_ERROR, finishedAt });
|
|
98
|
+
return;
|
|
99
|
+
}
|
|
100
|
+
await store.requeue(job.id, { runAt: finishedAt, error: INTERRUPTED_ERROR });
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
function launch(job: StoredJob): void {
|
|
104
|
+
const attempt: RunningAttempt = { controller: new AbortController(), cancelRequested: false };
|
|
105
|
+
running.set(job.id, attempt);
|
|
106
|
+
const promise = runAttempt(job, attempt)
|
|
107
|
+
.catch((error: unknown) => report(error, `engine.attempt:${job.id}`))
|
|
108
|
+
.finally(() => {
|
|
109
|
+
running.delete(job.id);
|
|
110
|
+
requestTick(0);
|
|
111
|
+
});
|
|
112
|
+
attempts.add(promise);
|
|
113
|
+
void promise.finally(() => attempts.delete(promise)).catch(() => undefined);
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
async function runAttempt(job: StoredJob, attempt: RunningAttempt): Promise<void> {
|
|
117
|
+
const definition = definitions.get(job.name);
|
|
118
|
+
const outcome: AttemptOutcome =
|
|
119
|
+
definition === undefined
|
|
120
|
+
? { ok: false, error: `Job "${job.name}" has no definition in this project.` }
|
|
121
|
+
: await executeAttempt(job, attempt, definition);
|
|
122
|
+
|
|
123
|
+
// Cancellation wins over a late result: once the caller asked the job to stop, its output
|
|
124
|
+
// is not trusted (docs/JOBS.md §6).
|
|
125
|
+
if (attempt.cancelRequested) {
|
|
126
|
+
await store.complete(job.id, { status: "cancelled", error: null, finishedAt: now() });
|
|
127
|
+
return;
|
|
128
|
+
}
|
|
129
|
+
if (outcome.ok) {
|
|
130
|
+
await store.complete(job.id, {
|
|
131
|
+
status: "succeeded",
|
|
132
|
+
output: outcome.output,
|
|
133
|
+
finishedAt: now(),
|
|
134
|
+
});
|
|
135
|
+
return;
|
|
136
|
+
}
|
|
137
|
+
if (outcome.terminal === true) {
|
|
138
|
+
// Retrying cannot fix a declaration the definition does not carry: store the stable
|
|
139
|
+
// code as the error and never the relation name the guard refused (D-157).
|
|
140
|
+
await store.complete(job.id, { status: "failed", error: outcome.error, finishedAt: now() });
|
|
141
|
+
return;
|
|
142
|
+
}
|
|
143
|
+
if (stopping) return interrupt(job);
|
|
144
|
+
const error =
|
|
145
|
+
outcome.error.length > MAX_STORED_ERROR
|
|
146
|
+
? outcome.error.slice(0, MAX_STORED_ERROR)
|
|
147
|
+
: outcome.error;
|
|
148
|
+
if (job.attempts < job.maxAttempts) {
|
|
149
|
+
await store.requeue(job.id, { runAt: new Date(timers.now() + config.retryDelayMs), error });
|
|
150
|
+
return;
|
|
151
|
+
}
|
|
152
|
+
await store.complete(job.id, { status: "failed", error, finishedAt: now() });
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
async function executeAttempt(
|
|
156
|
+
job: StoredJob,
|
|
157
|
+
attempt: RunningAttempt,
|
|
158
|
+
definition: JobDefinition<unknown, unknown>,
|
|
159
|
+
): Promise<AttemptOutcome> {
|
|
160
|
+
const parsedInput = definition.input.safeParse(job.input);
|
|
161
|
+
if (!parsedInput.success) return { ok: false, error: formatIssues(parsedInput.error.issues) };
|
|
162
|
+
|
|
163
|
+
const controller = attempt.controller;
|
|
164
|
+
let timedOut = false;
|
|
165
|
+
let timeoutHandle: unknown = null;
|
|
166
|
+
const abort = (): void => controller.abort();
|
|
167
|
+
const timeout = new Promise<never>((_, reject) => {
|
|
168
|
+
timeoutHandle = timers.setTimeout(() => {
|
|
169
|
+
timedOut = true;
|
|
170
|
+
// The signal is the contract, not a kill: the engine moves on even if the job ignores it.
|
|
171
|
+
abort();
|
|
172
|
+
reject(new Error("timeout"));
|
|
173
|
+
}, job.timeoutMs);
|
|
174
|
+
});
|
|
175
|
+
const aborted = new Promise<never>((_, reject) => {
|
|
176
|
+
controller.signal.addEventListener("abort", () => reject(new Error("aborted")), {
|
|
177
|
+
once: true,
|
|
178
|
+
});
|
|
179
|
+
});
|
|
180
|
+
|
|
181
|
+
try {
|
|
182
|
+
const raw = await Promise.race([
|
|
183
|
+
Promise.resolve(
|
|
184
|
+
executor({ definition, data: parsedInput.data, job, signal: controller.signal }),
|
|
185
|
+
),
|
|
186
|
+
timeout,
|
|
187
|
+
aborted,
|
|
188
|
+
]);
|
|
189
|
+
const parsedOutput = definition.output.safeParse(raw);
|
|
190
|
+
if (!parsedOutput.success)
|
|
191
|
+
return { ok: false, error: formatIssues(parsedOutput.error.issues) };
|
|
192
|
+
return { ok: true, output: serializeJobData(parsedOutput.data, "job_invalid_output") };
|
|
193
|
+
} catch (error) {
|
|
194
|
+
if (timedOut) return { ok: false, error: `timeout after ${job.timeoutMs}ms` };
|
|
195
|
+
if (error instanceof TableAccessError) {
|
|
196
|
+
return { ok: false, error: error.code, terminal: true };
|
|
197
|
+
}
|
|
198
|
+
return { ok: false, error: errorMessage(error) };
|
|
199
|
+
} finally {
|
|
200
|
+
if (timeoutHandle !== null) timers.clearTimeout(timeoutHandle);
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
async function enqueue(
|
|
205
|
+
name: string,
|
|
206
|
+
data: unknown,
|
|
207
|
+
enqueueOptions: { readonly runAt?: Date } | undefined,
|
|
208
|
+
target: JobStore,
|
|
209
|
+
): Promise<{ id: string }> {
|
|
210
|
+
// stop() is terminal (the boot owns the lifecycle), so this is a caller bug, not a
|
|
211
|
+
// job-contract violation and therefore not a JobError code.
|
|
212
|
+
if (stopping || stopped) throw new Error("The job engine is stopped.");
|
|
213
|
+
const definition = definitions.get(name);
|
|
214
|
+
if (definition === undefined) {
|
|
215
|
+
throw new JobError("job_unknown", `Job "${name}" is not defined by this project.`);
|
|
216
|
+
}
|
|
217
|
+
const parsed = definition.input.safeParse(data);
|
|
218
|
+
if (!parsed.success) throw new JobError("job_invalid_input", formatIssues(parsed.error.issues));
|
|
219
|
+
const createdAt = now();
|
|
220
|
+
const id = crypto.randomUUID();
|
|
221
|
+
await target.insert({
|
|
222
|
+
id,
|
|
223
|
+
name,
|
|
224
|
+
input: serializeJobData(parsed.data, "job_invalid_input"),
|
|
225
|
+
maxAttempts: definition.maxAttempts ?? config.maxAttempts,
|
|
226
|
+
timeoutMs: definition.timeoutMs ?? config.timeoutMs,
|
|
227
|
+
runAt: enqueueOptions?.runAt ?? createdAt,
|
|
228
|
+
createdAt,
|
|
229
|
+
});
|
|
230
|
+
requestTick(0);
|
|
231
|
+
return { id };
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
async function cancel(id: string, target: JobStore): Promise<boolean> {
|
|
235
|
+
const job = await target.get(id);
|
|
236
|
+
if (job === null) return false;
|
|
237
|
+
if (job.status === "queued") return target.cancelQueued(id, now());
|
|
238
|
+
if (job.status !== "running") return false;
|
|
239
|
+
const attempt = running.get(id);
|
|
240
|
+
if (attempt === undefined) return false;
|
|
241
|
+
attempt.cancelRequested = true;
|
|
242
|
+
attempt.controller.abort();
|
|
243
|
+
return true;
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
function start(): Promise<void> {
|
|
247
|
+
if (started || stopped) return Promise.resolve();
|
|
248
|
+
started = true;
|
|
249
|
+
return store
|
|
250
|
+
.recoverInterrupted(now())
|
|
251
|
+
.catch((error: unknown) => report(error, "engine.start"))
|
|
252
|
+
.then(() => {
|
|
253
|
+
scheduleTick(0);
|
|
254
|
+
});
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
function stop(): Promise<void> {
|
|
258
|
+
stopPromise ??= (async (): Promise<void> => {
|
|
259
|
+
if (!started) return;
|
|
260
|
+
stopping = true;
|
|
261
|
+
started = false;
|
|
262
|
+
stopped = true;
|
|
263
|
+
if (tickTimer !== null) {
|
|
264
|
+
timers.clearTimeout(tickTimer);
|
|
265
|
+
tickTimer = null;
|
|
266
|
+
}
|
|
267
|
+
for (const attempt of running.values()) attempt.controller.abort();
|
|
268
|
+
await Promise.all(attempts);
|
|
269
|
+
wakeRequested = false;
|
|
270
|
+
})();
|
|
271
|
+
return stopPromise;
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** One engine surface over one store view; timer and in-flight state stay shared. */
|
|
275
|
+
function createView(target: JobStore): JobEngine {
|
|
276
|
+
return {
|
|
277
|
+
start,
|
|
278
|
+
stop,
|
|
279
|
+
enqueue: (name, data, enqueueOptions) => enqueue(name, data, enqueueOptions, target),
|
|
280
|
+
get: (id) => target.get(id),
|
|
281
|
+
list: (listOptions?: JobListOptions) =>
|
|
282
|
+
target.list({ ...listOptions, limit: normalizeLimit(listOptions?.limit) }),
|
|
283
|
+
queue: () => target.queue(),
|
|
284
|
+
running: () => target.running(),
|
|
285
|
+
cancel: (id) => cancel(id, target),
|
|
286
|
+
stats: async (): Promise<JobCounts> => target.counts(),
|
|
287
|
+
};
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
const engine: JobEngine = createView(store);
|
|
291
|
+
// A handler's ctx.jobs is bound to the request transaction: queue operations must join it
|
|
292
|
+
// (PGlite single connection), while the scheduler keeps the base store for its own ticks.
|
|
293
|
+
engine.scoped = (scope: PolicyScopedDatabase): JobEngine =>
|
|
294
|
+
createView(store.scoped?.(scope) ?? store);
|
|
295
|
+
return engine;
|
|
296
|
+
}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { FacilisDb } from "@facilis.dev/db";
|
|
2
|
+
import { runAsSystem } from "@facilis.dev/db";
|
|
3
|
+
|
|
4
|
+
import type { JobExecutor } from "./contracts.ts";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Runs every job attempt in a system context (D-107, docs/JOBS.md §5/§7).
|
|
8
|
+
*
|
|
9
|
+
* The engine owns scheduling and input/output validation; this adapter owns the security
|
|
10
|
+
* boundary: each attempt is its own transaction as `facilis_system`, audited like a route's
|
|
11
|
+
* sudo and guarded by the job's `dbTables` declaration (D-157), so a job body never sees a
|
|
12
|
+
* policy-free client, the declaration is enforced and the trail names the job.
|
|
13
|
+
*/
|
|
14
|
+
export function createSystemJobExecutor(db: FacilisDb): JobExecutor {
|
|
15
|
+
return async ({ definition, data, job, signal }) =>
|
|
16
|
+
runAsSystem(
|
|
17
|
+
db,
|
|
18
|
+
{
|
|
19
|
+
actor: `system:job:${definition.name}`,
|
|
20
|
+
operation: `jobs:${definition.name}`,
|
|
21
|
+
reason: `Background job "${definition.name}" (attempt ${job.attempts})`,
|
|
22
|
+
// The declaration is required (possibly empty) and enforced inside the elevation: an
|
|
23
|
+
// undeclared relation fails closed instead of being audited after the fact (D-157).
|
|
24
|
+
dbTables: definition.dbTables,
|
|
25
|
+
rawSql: definition.rawSql === true,
|
|
26
|
+
},
|
|
27
|
+
async (systemDb) =>
|
|
28
|
+
definition.run({
|
|
29
|
+
jobId: job.id,
|
|
30
|
+
name: definition.name,
|
|
31
|
+
attempt: job.attempts,
|
|
32
|
+
data,
|
|
33
|
+
signal,
|
|
34
|
+
db: systemDb,
|
|
35
|
+
}),
|
|
36
|
+
);
|
|
37
|
+
}
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
import type {
|
|
2
|
+
JobCounts,
|
|
3
|
+
JobOutcome,
|
|
4
|
+
JobStore,
|
|
5
|
+
NewStoredJob,
|
|
6
|
+
StoredJob,
|
|
7
|
+
StoredJobListOptions,
|
|
8
|
+
} from "./contracts.ts";
|
|
9
|
+
|
|
10
|
+
/** Status values come from the frozen contract so the store cannot drift from the API. */
|
|
11
|
+
type JobStatus = StoredJob["status"];
|
|
12
|
+
|
|
13
|
+
/** Internal row: the snapshot plus its insertion order, used as a deterministic tie-break. */
|
|
14
|
+
interface Row {
|
|
15
|
+
readonly seq: number;
|
|
16
|
+
readonly job: StoredJob;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
const INTERRUPTED_ERROR = "interrupted (recovered after restart)";
|
|
20
|
+
|
|
21
|
+
/** Reads hand out fresh snapshots: callers must never observe a later mutation. */
|
|
22
|
+
function cloneJob(job: StoredJob): StoredJob {
|
|
23
|
+
return {
|
|
24
|
+
...job,
|
|
25
|
+
runAt: new Date(job.runAt),
|
|
26
|
+
createdAt: new Date(job.createdAt),
|
|
27
|
+
startedAt: job.startedAt === null ? null : new Date(job.startedAt),
|
|
28
|
+
finishedAt: job.finishedAt === null ? null : new Date(job.finishedAt),
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
function matchesStatus(status: JobStatus, filter: StoredJobListOptions["status"]): boolean {
|
|
33
|
+
if (filter === undefined) return true;
|
|
34
|
+
return typeof filter === "string" ? status === filter : filter.includes(status);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Nothing to release: the map is garbage-collected with the store. */
|
|
38
|
+
async function closeStore(): Promise<void> {}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* The in-memory queue: used when `jobs.persist` is false, or when the project has not
|
|
42
|
+
* migrated `facilis_jobs` yet. Work is lost across a reload, which is why persistence is
|
|
43
|
+
* the default (docs/JOBS.md §8).
|
|
44
|
+
*/
|
|
45
|
+
export function createMemoryJobStore(): JobStore {
|
|
46
|
+
const rows = new Map<string, Row>();
|
|
47
|
+
let sequence = 0;
|
|
48
|
+
|
|
49
|
+
function replace(id: string, job: StoredJob): void {
|
|
50
|
+
const row = rows.get(id);
|
|
51
|
+
if (row !== undefined) rows.set(id, { seq: row.seq, job });
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function byRunAt(a: Row, b: Row): number {
|
|
55
|
+
return a.job.runAt.getTime() - b.job.runAt.getTime() || a.seq - b.seq;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
async function insert(job: NewStoredJob): Promise<void> {
|
|
59
|
+
rows.set(job.id, {
|
|
60
|
+
seq: sequence++,
|
|
61
|
+
job: {
|
|
62
|
+
id: job.id,
|
|
63
|
+
name: job.name,
|
|
64
|
+
status: "queued",
|
|
65
|
+
input: job.input,
|
|
66
|
+
output: null,
|
|
67
|
+
error: null,
|
|
68
|
+
attempts: 0,
|
|
69
|
+
maxAttempts: job.maxAttempts,
|
|
70
|
+
timeoutMs: job.timeoutMs,
|
|
71
|
+
runAt: new Date(job.runAt),
|
|
72
|
+
createdAt: new Date(job.createdAt),
|
|
73
|
+
startedAt: null,
|
|
74
|
+
finishedAt: null,
|
|
75
|
+
},
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
async function get(id: string): Promise<StoredJob | null> {
|
|
80
|
+
const row = rows.get(id);
|
|
81
|
+
return row === undefined ? null : cloneJob(row.job);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
async function list(options: StoredJobListOptions): Promise<StoredJob[]> {
|
|
85
|
+
const matching = [...rows.values()].filter(
|
|
86
|
+
({ job }) =>
|
|
87
|
+
matchesStatus(job.status, options.status) &&
|
|
88
|
+
(options.name === undefined || job.name === options.name),
|
|
89
|
+
);
|
|
90
|
+
// Newest-created first; a later insertion wins an identical timestamp.
|
|
91
|
+
matching.sort((a, b) => b.job.createdAt.getTime() - a.job.createdAt.getTime() || b.seq - a.seq);
|
|
92
|
+
return matching.slice(0, Math.max(0, options.limit)).map(({ job }) => cloneJob(job));
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
async function queue(limit?: number): Promise<StoredJob[]> {
|
|
96
|
+
const queued = [...rows.values()].filter(({ job }) => job.status === "queued");
|
|
97
|
+
queued.sort(byRunAt);
|
|
98
|
+
const page = limit === undefined ? queued : queued.slice(0, Math.max(0, limit));
|
|
99
|
+
return page.map(({ job }) => cloneJob(job));
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
async function running(): Promise<StoredJob[]> {
|
|
103
|
+
const active = [...rows.values()].filter(({ job }) => job.status === "running");
|
|
104
|
+
active.sort(
|
|
105
|
+
(a, b) =>
|
|
106
|
+
(a.job.startedAt?.getTime() ?? 0) - (b.job.startedAt?.getTime() ?? 0) || a.seq - b.seq,
|
|
107
|
+
);
|
|
108
|
+
return active.map(({ job }) => cloneJob(job));
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
async function claim(now: Date, limit: number): Promise<StoredJob[]> {
|
|
112
|
+
const due = [...rows.values()].filter(
|
|
113
|
+
({ job }) => job.status === "queued" && job.runAt.getTime() <= now.getTime(),
|
|
114
|
+
);
|
|
115
|
+
due.sort(byRunAt);
|
|
116
|
+
const claimed: StoredJob[] = [];
|
|
117
|
+
for (const { seq, job } of due.slice(0, Math.max(0, limit))) {
|
|
118
|
+
const next: StoredJob = {
|
|
119
|
+
...job,
|
|
120
|
+
status: "running",
|
|
121
|
+
attempts: job.attempts + 1,
|
|
122
|
+
startedAt: new Date(now),
|
|
123
|
+
};
|
|
124
|
+
rows.set(job.id, { seq, job: next });
|
|
125
|
+
claimed.push(cloneJob(next));
|
|
126
|
+
}
|
|
127
|
+
return claimed;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
async function complete(id: string, outcome: JobOutcome): Promise<void> {
|
|
131
|
+
const row = rows.get(id);
|
|
132
|
+
if (row === undefined) return;
|
|
133
|
+
replace(id, {
|
|
134
|
+
...row.job,
|
|
135
|
+
status: outcome.status,
|
|
136
|
+
output: outcome.status === "succeeded" ? outcome.output : null,
|
|
137
|
+
error: outcome.status === "succeeded" ? null : outcome.error,
|
|
138
|
+
finishedAt: new Date(outcome.finishedAt),
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
async function requeue(
|
|
143
|
+
id: string,
|
|
144
|
+
options: { readonly runAt: Date; readonly error: string },
|
|
145
|
+
): Promise<void> {
|
|
146
|
+
const row = rows.get(id);
|
|
147
|
+
if (row === undefined) return;
|
|
148
|
+
replace(id, {
|
|
149
|
+
...row.job,
|
|
150
|
+
status: "queued",
|
|
151
|
+
output: null,
|
|
152
|
+
error: options.error,
|
|
153
|
+
runAt: new Date(options.runAt),
|
|
154
|
+
startedAt: null,
|
|
155
|
+
finishedAt: null,
|
|
156
|
+
});
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
async function cancelQueued(id: string, finishedAt: Date): Promise<boolean> {
|
|
160
|
+
const row = rows.get(id);
|
|
161
|
+
if (row === undefined || row.job.status !== "queued") return false;
|
|
162
|
+
replace(id, {
|
|
163
|
+
...row.job,
|
|
164
|
+
status: "cancelled",
|
|
165
|
+
error: null,
|
|
166
|
+
finishedAt: new Date(finishedAt),
|
|
167
|
+
});
|
|
168
|
+
return true;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
async function recoverInterrupted(now: Date): Promise<number> {
|
|
172
|
+
let recovered = 0;
|
|
173
|
+
for (const { job } of rows.values()) {
|
|
174
|
+
if (job.status !== "running") continue;
|
|
175
|
+
recovered += 1;
|
|
176
|
+
if (job.attempts >= job.maxAttempts) {
|
|
177
|
+
replace(job.id, {
|
|
178
|
+
...job,
|
|
179
|
+
status: "failed",
|
|
180
|
+
error: INTERRUPTED_ERROR,
|
|
181
|
+
finishedAt: new Date(now),
|
|
182
|
+
});
|
|
183
|
+
} else {
|
|
184
|
+
replace(job.id, {
|
|
185
|
+
...job,
|
|
186
|
+
status: "queued",
|
|
187
|
+
error: INTERRUPTED_ERROR,
|
|
188
|
+
runAt: new Date(now),
|
|
189
|
+
startedAt: null,
|
|
190
|
+
});
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
return recovered;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
async function counts(): Promise<JobCounts> {
|
|
197
|
+
const tally: Record<JobStatus, number> = {
|
|
198
|
+
queued: 0,
|
|
199
|
+
running: 0,
|
|
200
|
+
succeeded: 0,
|
|
201
|
+
failed: 0,
|
|
202
|
+
cancelled: 0,
|
|
203
|
+
};
|
|
204
|
+
for (const { job } of rows.values()) tally[job.status] += 1;
|
|
205
|
+
return { ...tally };
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
return {
|
|
209
|
+
insert,
|
|
210
|
+
get,
|
|
211
|
+
list,
|
|
212
|
+
queue,
|
|
213
|
+
running,
|
|
214
|
+
claim,
|
|
215
|
+
complete,
|
|
216
|
+
requeue,
|
|
217
|
+
cancelQueued,
|
|
218
|
+
recoverInterrupted,
|
|
219
|
+
counts,
|
|
220
|
+
close: closeStore,
|
|
221
|
+
};
|
|
222
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
// Row <-> store-contract mapping for the persistent job queue (D-107).
|
|
2
|
+
//
|
|
3
|
+
// Kept apart from db-store.ts so each file stays well under the 300-line limit and the
|
|
4
|
+
// mapping is the single place that knows the text status column and the JSONB columns.
|
|
5
|
+
import { JOB_STATUSES } from "@facilis.dev/core";
|
|
6
|
+
import type { JobJson, JobStatus } from "@facilis.dev/core";
|
|
7
|
+
import type { FacilisJobRow } from "@facilis.dev/db";
|
|
8
|
+
|
|
9
|
+
import type { JobOutcome, StoredJob } from "./contracts.ts";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Maps a row to the store contract. The JSONB columns read as `unknown` because Drizzle
|
|
13
|
+
* cannot know the app's JSON shape; the engine serialized them through a JSON round-trip,
|
|
14
|
+
* so they are JobJson by construction (JOBS.md §5).
|
|
15
|
+
*/
|
|
16
|
+
export function toStoredJob(row: FacilisJobRow): StoredJob {
|
|
17
|
+
return {
|
|
18
|
+
id: row.id,
|
|
19
|
+
name: row.name,
|
|
20
|
+
status: toJobStatus(row.status),
|
|
21
|
+
input: row.input as JobJson,
|
|
22
|
+
output: (row.output ?? null) as JobJson | null,
|
|
23
|
+
error: row.error,
|
|
24
|
+
attempts: row.attempts,
|
|
25
|
+
maxAttempts: row.maxAttempts,
|
|
26
|
+
timeoutMs: row.timeoutMs,
|
|
27
|
+
runAt: row.runAt,
|
|
28
|
+
createdAt: row.createdAt,
|
|
29
|
+
startedAt: row.startedAt,
|
|
30
|
+
finishedAt: row.finishedAt,
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** Column set for `complete`: a terminal status plus the fields that status owns. */
|
|
35
|
+
export function completionValues(outcome: JobOutcome) {
|
|
36
|
+
switch (outcome.status) {
|
|
37
|
+
case "succeeded":
|
|
38
|
+
return {
|
|
39
|
+
status: "succeeded" as const,
|
|
40
|
+
output: outcome.output,
|
|
41
|
+
error: null,
|
|
42
|
+
finishedAt: outcome.finishedAt,
|
|
43
|
+
};
|
|
44
|
+
case "failed":
|
|
45
|
+
return {
|
|
46
|
+
status: "failed" as const,
|
|
47
|
+
output: null,
|
|
48
|
+
error: outcome.error,
|
|
49
|
+
finishedAt: outcome.finishedAt,
|
|
50
|
+
};
|
|
51
|
+
case "cancelled":
|
|
52
|
+
return {
|
|
53
|
+
status: "cancelled" as const,
|
|
54
|
+
output: null,
|
|
55
|
+
error: outcome.error,
|
|
56
|
+
finishedAt: outcome.finishedAt,
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Narrows the text status column; an unknown value is corrupt queue data, not a job. */
|
|
62
|
+
export function toJobStatus(value: string): JobStatus {
|
|
63
|
+
for (const status of JOB_STATUSES) {
|
|
64
|
+
if (status === value) return status;
|
|
65
|
+
}
|
|
66
|
+
throw new Error(`facilis_jobs: unknown status "${value}"`);
|
|
67
|
+
}
|