@rig-c/review 2.6.0 → 2.7.0
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/docs/REVIEW_PACKAGE.md +48 -10
- package/docs/STABILITY.md +232 -15
- package/package.json +1 -1
- package/src/job-act.ts +316 -8
- package/src/job-api.ts +821 -8
- package/src/job-contract.ts +299 -0
- package/src/job-front.ts +763 -23
- package/src/job-host.ts +9 -1
- package/src/job-hub.ts +11 -6
- package/src/job-session.ts +68 -9
- package/src/job-source.ts +787 -7
- package/src/job-store.ts +114 -8
- package/src/job-worker.ts +5 -1
package/src/job-store.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Database } from 'bun:sqlite';
|
|
1
|
+
import { Database, constants as sqliteConstants } from 'bun:sqlite';
|
|
2
2
|
import { randomUUID } from 'node:crypto';
|
|
3
3
|
import { chmodSync, lstatSync, mkdirSync, realpathSync } from 'node:fs';
|
|
4
4
|
import { join } from 'node:path';
|
|
@@ -106,6 +106,10 @@ function privateEntry(path: string, directory: boolean): void {
|
|
|
106
106
|
}
|
|
107
107
|
}
|
|
108
108
|
|
|
109
|
+
export interface JobStoreOpenOptions {
|
|
110
|
+
readonly readonly?: boolean;
|
|
111
|
+
}
|
|
112
|
+
|
|
109
113
|
/** One SQLite transaction seals the entire job, including its events, acts and
|
|
110
114
|
* idempotency receipts. IMMEDIATE transactions serialize independent daemons.
|
|
111
115
|
* FULL synchronous durability and the rollback journal survive process death.
|
|
@@ -113,10 +117,56 @@ function privateEntry(path: string, directory: boolean): void {
|
|
|
113
117
|
*/
|
|
114
118
|
export class JobStore<Data> {
|
|
115
119
|
readonly root: string;
|
|
116
|
-
private
|
|
120
|
+
private readOnly: boolean;
|
|
121
|
+
get isReadonly(): boolean { return this.readOnly; }
|
|
122
|
+
private db: Database;
|
|
123
|
+
private identities!: {directory: {dev: number; ino: number}; file: {dev: number; ino: number}};
|
|
124
|
+
private writeAdoption?: () => void;
|
|
117
125
|
|
|
118
|
-
|
|
126
|
+
|
|
127
|
+
constructor(directory: string, options: JobStoreOpenOptions = {}) {
|
|
128
|
+
this.readOnly = options.readonly === true;
|
|
119
129
|
try {
|
|
130
|
+
if (this.isReadonly) {
|
|
131
|
+
privateEntry(directory, true);
|
|
132
|
+
const directInfo = lstatSync(directory);
|
|
133
|
+
this.root = realpathSync(directory);
|
|
134
|
+
const realInfo = lstatSync(this.root);
|
|
135
|
+
if (directInfo.dev !== realInfo.dev || directInfo.ino !== realInfo.ino) {
|
|
136
|
+
throw new JobError('JOB_STORAGE_FAILED', 'State directory must not be a symlink');
|
|
137
|
+
}
|
|
138
|
+
const file = join(this.root, 'jobs.sqlite');
|
|
139
|
+
privateEntry(file, false);
|
|
140
|
+
for (const suffix of ['-journal', '-wal', '-shm']) {
|
|
141
|
+
let exists = false;
|
|
142
|
+
try { lstatSync(file + suffix); exists = true; }
|
|
143
|
+
catch (error) {
|
|
144
|
+
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
|
|
145
|
+
}
|
|
146
|
+
if (exists) throw new JobError('JOB_STORAGE_FAILED', 'Unrecovered SQLite sidecar present');
|
|
147
|
+
}
|
|
148
|
+
const fileInfo = lstatSync(file);
|
|
149
|
+
this.identities = {directory: {dev: directInfo.dev, ino: directInfo.ino}, file: {dev: fileInfo.dev, ino: fileInfo.ino}};
|
|
150
|
+
this.db = new Database(file, sqliteConstants.SQLITE_OPEN_READONLY | sqliteConstants.SQLITE_OPEN_NOFOLLOW);
|
|
151
|
+
try {
|
|
152
|
+
this.db.exec('PRAGMA query_only=ON; PRAGMA busy_timeout=1000;');
|
|
153
|
+
this.assertStorage();
|
|
154
|
+
const tables = new Set(
|
|
155
|
+
this.db.query<{ name: string }, []>("SELECT name FROM sqlite_master WHERE type='table'")
|
|
156
|
+
.all().map(row => row.name),
|
|
157
|
+
);
|
|
158
|
+
for (const required of [
|
|
159
|
+
'jobs', 'job_closures', 'job_snapshot_owners',
|
|
160
|
+
'job_snapshot_reads', 'job_snapshot_tombstones', 'job_act_stills',
|
|
161
|
+
]) {
|
|
162
|
+
if (!tables.has(required)) throw new JobError('JOB_STORAGE_FAILED', 'Required job table missing');
|
|
163
|
+
}
|
|
164
|
+
} catch (error) {
|
|
165
|
+
this.db.close();
|
|
166
|
+
throw error;
|
|
167
|
+
}
|
|
168
|
+
return;
|
|
169
|
+
}
|
|
120
170
|
mkdirSync(directory, { recursive: true, mode: 0o700 });
|
|
121
171
|
privateEntry(directory, true);
|
|
122
172
|
this.root = realpathSync(directory);
|
|
@@ -159,13 +209,55 @@ export class JobStore<Data> {
|
|
|
159
209
|
sha256 TEXT NOT NULL, binding TEXT NOT NULL, png BLOB NOT NULL, act_bytes BLOB NOT NULL,
|
|
160
210
|
PRIMARY KEY(job_id, act_id), UNIQUE(job_id, page_id, submission_id)
|
|
161
211
|
);`);
|
|
212
|
+
this.captureStorage();
|
|
162
213
|
} catch {
|
|
163
214
|
throw new JobError('JOB_STORAGE_FAILED', 'Private job storage could not be opened');
|
|
164
215
|
}
|
|
165
216
|
}
|
|
166
217
|
|
|
218
|
+
private captureStorage(): void {
|
|
219
|
+
const directory = lstatSync(this.root), file = lstatSync(join(this.root, 'jobs.sqlite'));
|
|
220
|
+
this.identities = {directory: {dev: directory.dev, ino: directory.ino}, file: {dev: file.dev, ino: file.ino}};
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
assertStorage(): void {
|
|
224
|
+
for (const [path, captured, directory] of [
|
|
225
|
+
[this.root, this.identities.directory, true],
|
|
226
|
+
[join(this.root, 'jobs.sqlite'), this.identities.file, false],
|
|
227
|
+
] as const) {
|
|
228
|
+
privateEntry(path, directory);
|
|
229
|
+
const current = lstatSync(path);
|
|
230
|
+
if (current.dev !== captured.dev || current.ino !== captured.ino) throw new JobError('JOB_STORAGE_FAILED');
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/** Install the exact-job guard without opening a writable connection. */
|
|
235
|
+
allowExistingWrites(verify: () => void): void { this.writeAdoption = verify; }
|
|
236
|
+
|
|
237
|
+
/** Deferred snapshot: acceptance performs SELECTs only, ordered against sealClose. */
|
|
238
|
+
inspect<Value>(operation: () => Value): Value {
|
|
239
|
+
return this.db.transaction(operation).deferred();
|
|
240
|
+
}
|
|
241
|
+
|
|
167
242
|
private transaction<Value>(operation: () => Value): Value {
|
|
168
|
-
try {
|
|
243
|
+
try {
|
|
244
|
+
if (this.readOnly) {
|
|
245
|
+
if (!this.writeAdoption) throw new JobError('JOB_STORAGE_FAILED');
|
|
246
|
+
this.assertStorage();
|
|
247
|
+
const writable = new Database(join(this.root, 'jobs.sqlite'), sqliteConstants.SQLITE_OPEN_READWRITE | sqliteConstants.SQLITE_OPEN_NOFOLLOW);
|
|
248
|
+
try {
|
|
249
|
+
this.assertStorage();
|
|
250
|
+
writable.exec('PRAGMA synchronous=FULL; PRAGMA busy_timeout=1000;');
|
|
251
|
+
} catch (error) { writable.close(); throw error; }
|
|
252
|
+
this.db.close(); this.db = writable; this.readOnly = false;
|
|
253
|
+
}
|
|
254
|
+
return this.db.transaction(() => {
|
|
255
|
+
if (this.writeAdoption) {
|
|
256
|
+
this.assertStorage(); this.writeAdoption(); this.writeAdoption = undefined;
|
|
257
|
+
}
|
|
258
|
+
return operation();
|
|
259
|
+
}).immediate();
|
|
260
|
+
}
|
|
169
261
|
catch (error) {
|
|
170
262
|
if (typeof (error as { code?: unknown }).code === 'string' &&
|
|
171
263
|
String((error as { code: string }).code).startsWith('SQLITE_')) {
|
|
@@ -176,10 +268,24 @@ export class JobStore<Data> {
|
|
|
176
268
|
}
|
|
177
269
|
|
|
178
270
|
get(jobId: string): StoredJob<Data> {
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
271
|
+
try {
|
|
272
|
+
const row = this.db.query<JobRow, [string]>(`SELECT jobs.*, job_closures.document AS closure
|
|
273
|
+
FROM jobs LEFT JOIN job_closures USING(job_id) WHERE job_id=?`).get(jobId);
|
|
274
|
+
if (!row) throw new JobError('JOB_UNKNOWN');
|
|
275
|
+
return decode<Data>(row);
|
|
276
|
+
} catch (error) {
|
|
277
|
+
if (error instanceof JobError) throw error;
|
|
278
|
+
throw new JobError('JOB_STORAGE_FAILED', 'Stored job state is invalid');
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
activeByRootKey(rootKey: string): StoredJob<Data> | null {
|
|
283
|
+
try {
|
|
284
|
+
const row = this.db.query<JobRow, [string]>('SELECT * FROM jobs WHERE root_key=? AND active=1').get(rootKey);
|
|
285
|
+
return row ? decode<Data>(row) : null;
|
|
286
|
+
} catch {
|
|
287
|
+
throw new JobError('JOB_STORAGE_FAILED', 'Stored job state is invalid');
|
|
288
|
+
}
|
|
183
289
|
}
|
|
184
290
|
|
|
185
291
|
open(rootKey: string, initialize: (jobId: string) => Data, canonicalRoot?: string): StoredJob<Data> {
|
package/src/job-worker.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import {randomUUID} from 'node:crypto';
|
|
1
2
|
import { createJobHostPorts } from './job-api.ts';
|
|
2
3
|
import { JobSession, type JobSessionOptions } from './job-session.ts';
|
|
3
4
|
import type { JobHostPorts } from './job-contract.ts';
|
|
@@ -7,6 +8,7 @@ export interface JobWorkerOptions extends JobSessionOptions {
|
|
|
7
8
|
readonly port?: number;
|
|
8
9
|
/** Trusted Create #184 adapter installs its private writer-owned sibling.
|
|
9
10
|
* No project record key or binding-file format is defined by this callback.
|
|
11
|
+
* Reusable owner-host attachment (`reuseOnly`) belongs to JobHostOptions.
|
|
10
12
|
*/
|
|
11
13
|
readonly installWriterBinding?: (binding: {
|
|
12
14
|
readonly jobId: string;
|
|
@@ -23,9 +25,11 @@ export async function startJobWorker(options: JobWorkerOptions): Promise<{
|
|
|
23
25
|
readonly session: JobSession;
|
|
24
26
|
readonly ports: JobHostPorts;
|
|
25
27
|
readonly origin: string;
|
|
28
|
+
readonly listenerIncarnation: string;
|
|
26
29
|
stop(): void;
|
|
27
30
|
}> {
|
|
28
31
|
const session = new JobSession(options);
|
|
32
|
+
const listenerIncarnation = randomUUID();
|
|
29
33
|
let ports: JobHostPorts;
|
|
30
34
|
let stopped = false;
|
|
31
35
|
const server = Bun.serve({
|
|
@@ -48,7 +52,7 @@ export async function startJobWorker(options: JobWorkerOptions): Promise<{
|
|
|
48
52
|
};
|
|
49
53
|
try {
|
|
50
54
|
await options.installWriterBinding?.({ ...session.writerGrant(), origin });
|
|
51
|
-
return { session, ports, origin, stop };
|
|
55
|
+
return { session, ports, origin, listenerIncarnation, stop };
|
|
52
56
|
} catch {
|
|
53
57
|
stop();
|
|
54
58
|
throw new JobError('JOB_AUTHORITY_REFUSED', 'Writer binding installation failed');
|