fascicle 0.18.1 → 0.19.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/CHANGELOG.md +59 -0
- package/README.md +27 -1
- package/dist/AGENTS.md +11 -10
- package/dist/a2a.d.ts +358 -0
- package/dist/a2a.js +2234 -0
- package/dist/a2a.js.map +1 -0
- package/dist/acp.d.ts +120 -9
- package/dist/acp.js +927 -154
- package/dist/acp.js.map +1 -1
- package/dist/adapters-DYFauXE1.js +1147 -0
- package/dist/adapters-DYFauXE1.js.map +1 -0
- package/dist/adapters.d.ts +124 -36
- package/dist/adapters.js +1 -1
- package/dist/agents.d.ts +2 -2
- package/dist/agents.js +1 -1
- package/dist/{core-BH7sWpEG.js → core-xTtRZqdb.js} +217 -99
- package/dist/core-xTtRZqdb.js.map +1 -0
- package/dist/diagram_bin.js +1 -1
- package/dist/durable-CgU0kO2H.d.ts +144 -0
- package/dist/{engine-fOjYHcv6.js → engine-B_Yl7acj.js} +128 -42
- package/dist/engine-B_Yl7acj.js.map +1 -0
- package/dist/index.d.ts +9 -136
- package/dist/index.js +6 -5
- package/dist/index.js.map +1 -1
- package/dist/{invoke-7iu8db6V.js → invoke-Bbk0RuVL.js} +3 -3
- package/dist/{invoke-7iu8db6V.js.map → invoke-Bbk0RuVL.js.map} +1 -1
- package/dist/{leading_system-BeQUSAim.js → leading_system-m-x7HzbQ.js} +16 -4
- package/dist/leading_system-m-x7HzbQ.js.map +1 -0
- package/dist/mcp-D1hN5ywq.js +662 -0
- package/dist/mcp-D1hN5ywq.js.map +1 -0
- package/dist/mcp.d.ts +115 -5
- package/dist/mcp.js +2 -2
- package/dist/otel.d.ts +1 -1
- package/dist/stdio.d.ts +1 -1
- package/dist/stdio.js +2 -2
- package/dist/testing.d.ts +7 -5
- package/dist/testing.js +618 -318
- package/dist/testing.js.map +1 -1
- package/dist/{types-BUXt_zgJ.d.ts → types-BtRpSctv.d.ts} +38 -5
- package/dist/{types-Dk9tLpUq.d.ts → types-CDTW7XWB.d.ts} +2 -2
- package/dist/ui.d.ts +2 -2
- package/dist/viewer.js +2 -2
- package/dist/web.d.ts +1 -1
- package/package.json +17 -5
- package/dist/adapters-CpKpDk7r.js +0 -461
- package/dist/adapters-CpKpDk7r.js.map +0 -1
- package/dist/core-BH7sWpEG.js.map +0 -1
- package/dist/engine-fOjYHcv6.js.map +0 -1
- package/dist/leading_system-BeQUSAim.js.map +0 -1
- package/dist/mcp-CHJ88HiG.js +0 -262
- package/dist/mcp-CHJ88HiG.js.map +0 -1
|
@@ -0,0 +1,1147 @@
|
|
|
1
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
2
|
+
import { link, mkdir, readFile, readdir, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
|
|
3
|
+
import { dirname, join } from "node:path";
|
|
4
|
+
import { appendFileSync, mkdirSync } from "node:fs";
|
|
5
|
+
// src/adapters/trajectory_recorder.ts
|
|
6
|
+
/**
|
|
7
|
+
* Shared span/record core for trajectory loggers.
|
|
8
|
+
*
|
|
9
|
+
* Every Fascicle trajectory logger emits the same wire format (one JSON object
|
|
10
|
+
* per event) and differs only in where each event goes: `line_logger` writes a
|
|
11
|
+
* line, `http_logger` POSTs NDJSON. This module holds the span bookkeeping they
|
|
12
|
+
* share, parameterized by a single `emit` sink.
|
|
13
|
+
*
|
|
14
|
+
* `start_span` and `end_span` each emit one event; `record` emits the event as
|
|
15
|
+
* written. When the caller supplies `parent_span_id` in the span meta (the
|
|
16
|
+
* runner threads the true structural parent through `RunContext`), that value is
|
|
17
|
+
* used verbatim, so span trees are correct even for concurrent children under
|
|
18
|
+
* `parallel`/`map`. Only when no parent is supplied does the recorder fall back
|
|
19
|
+
* to an in-memory stack of still-open spans, which is best-effort under
|
|
20
|
+
* concurrency.
|
|
21
|
+
*/
|
|
22
|
+
/**
|
|
23
|
+
* Build a `TrajectoryLogger` whose events are handed, one at a time, to `emit`.
|
|
24
|
+
*/
|
|
25
|
+
function trajectory_recorder(emit) {
|
|
26
|
+
const stack = [];
|
|
27
|
+
const start_span = (name, meta) => {
|
|
28
|
+
const span_id = `${name}:${randomUUID().slice(0, 8)}`;
|
|
29
|
+
const event = {
|
|
30
|
+
kind: "span_start",
|
|
31
|
+
span_id,
|
|
32
|
+
name,
|
|
33
|
+
...meta
|
|
34
|
+
};
|
|
35
|
+
if (event["parent_span_id"] === void 0 && stack.length > 0) event["parent_span_id"] = stack[stack.length - 1];
|
|
36
|
+
emit(event);
|
|
37
|
+
stack.push(span_id);
|
|
38
|
+
return span_id;
|
|
39
|
+
};
|
|
40
|
+
const end_span = (id, meta) => {
|
|
41
|
+
emit({
|
|
42
|
+
kind: "span_end",
|
|
43
|
+
span_id: id,
|
|
44
|
+
...meta
|
|
45
|
+
});
|
|
46
|
+
const idx = stack.lastIndexOf(id);
|
|
47
|
+
if (idx !== -1) stack.splice(idx, 1);
|
|
48
|
+
};
|
|
49
|
+
const record = (event) => {
|
|
50
|
+
emit({ ...event });
|
|
51
|
+
};
|
|
52
|
+
return {
|
|
53
|
+
record,
|
|
54
|
+
start_span,
|
|
55
|
+
end_span
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
// src/adapters/line_logger.ts
|
|
59
|
+
/**
|
|
60
|
+
* Create a `TrajectoryLogger` that writes one JSON object per line via
|
|
61
|
+
* `write_line`.
|
|
62
|
+
*/
|
|
63
|
+
function line_logger(write_line) {
|
|
64
|
+
return trajectory_recorder(write_line);
|
|
65
|
+
}
|
|
66
|
+
// src/adapters/filesystem_logger.ts
|
|
67
|
+
/**
|
|
68
|
+
* Filesystem JSONL trajectory logger.
|
|
69
|
+
*
|
|
70
|
+
* Appends one JSON object per line to a configured output file. Span
|
|
71
|
+
* bookkeeping (including the `parent_span_id` handling that keeps span trees
|
|
72
|
+
* correct for concurrent children under `parallel`/`map`) lives in
|
|
73
|
+
* `line_logger`. Two concurrent `run(...)` calls that pass distinct logger
|
|
74
|
+
* instances (constructed with distinct `output_path`s) share nothing.
|
|
75
|
+
*
|
|
76
|
+
* Failure policy: an event that can't be serialized or appended is dropped
|
|
77
|
+
* and reported, through the optional `on_error` callback or else as one line
|
|
78
|
+
* on stderr. Never throws into the flow, the same as every adapter logger.
|
|
79
|
+
*
|
|
80
|
+
* Paths are accepted at construction; the logger never reads `process.env`.
|
|
81
|
+
*/
|
|
82
|
+
/**
|
|
83
|
+
* Create a `TrajectoryLogger` that appends one JSON object per line to
|
|
84
|
+
* `output_path`, creating the parent directory if needed.
|
|
85
|
+
*/
|
|
86
|
+
function filesystem_logger(config) {
|
|
87
|
+
const { output_path } = config;
|
|
88
|
+
const report = config.on_error ?? ((err) => report_to_stderr(output_path, err));
|
|
89
|
+
mkdirSync(dirname(output_path), { recursive: true });
|
|
90
|
+
return line_logger((event) => {
|
|
91
|
+
try {
|
|
92
|
+
appendFileSync(output_path, `${JSON.stringify(event)}\n`);
|
|
93
|
+
} catch (err) {
|
|
94
|
+
try {
|
|
95
|
+
report(err);
|
|
96
|
+
} catch {}
|
|
97
|
+
}
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* The default reporter: one stderr line that names the file and the reason
|
|
102
|
+
* an event was dropped.
|
|
103
|
+
*/
|
|
104
|
+
function report_to_stderr(output_path, err) {
|
|
105
|
+
const reason = err instanceof Error ? err.message : String(err);
|
|
106
|
+
process.stderr.write(`filesystem_logger: dropped an event it could not write to ${output_path} (${reason}). Check that the path is a writable file and that every emitted value is JSON-serializable.\n`);
|
|
107
|
+
}
|
|
108
|
+
// src/adapters/http_logger.ts
|
|
109
|
+
/**
|
|
110
|
+
* Default `HttpLoggerFetch`, backed by the global `fetch`.
|
|
111
|
+
*/
|
|
112
|
+
const default_fetch = async (url, init) => {
|
|
113
|
+
const res = await fetch(url, init);
|
|
114
|
+
return {
|
|
115
|
+
ok: res.ok,
|
|
116
|
+
status: res.status
|
|
117
|
+
};
|
|
118
|
+
};
|
|
119
|
+
/**
|
|
120
|
+
* Create a `TrajectoryLogger` that POSTs each event as NDJSON to
|
|
121
|
+
* `config.url`.
|
|
122
|
+
*
|
|
123
|
+
* Never throws: a transport failure, an event JSON can't serialize, and a
|
|
124
|
+
* custom `fetch` that throws are each dropped and reported through the
|
|
125
|
+
* optional `on_error` callback, so a dev viewer being unreachable never
|
|
126
|
+
* blocks the flow.
|
|
127
|
+
*/
|
|
128
|
+
function http_logger(config) {
|
|
129
|
+
const { url, on_error } = config;
|
|
130
|
+
const send = config.fetch ?? default_fetch;
|
|
131
|
+
const post = (event) => {
|
|
132
|
+
new Promise((resolve) => {
|
|
133
|
+
resolve(`${JSON.stringify(event)}\n`);
|
|
134
|
+
}).then(async (body) => send(url, {
|
|
135
|
+
method: "POST",
|
|
136
|
+
headers: { "content-type": "application/x-ndjson" },
|
|
137
|
+
body
|
|
138
|
+
})).then((res) => {
|
|
139
|
+
if (!res.ok && on_error) on_error(/* @__PURE__ */ new Error(`http_logger: POST ${url} -> ${res.status}`));
|
|
140
|
+
}).catch((err) => {
|
|
141
|
+
if (on_error) on_error(err);
|
|
142
|
+
});
|
|
143
|
+
};
|
|
144
|
+
return trajectory_recorder(post);
|
|
145
|
+
}
|
|
146
|
+
// src/adapters/noop_logger.ts
|
|
147
|
+
/**
|
|
148
|
+
* No-op trajectory logger.
|
|
149
|
+
*
|
|
150
|
+
* Satisfies `TrajectoryLogger` from `core` without emitting any
|
|
151
|
+
* output. A caller passes it where a logger is required and nothing should be
|
|
152
|
+
* recorded, such as a test that does not care about trajectory output.
|
|
153
|
+
* `run(...)` keeps its own private no-op for a run given no logger.
|
|
154
|
+
*/
|
|
155
|
+
/**
|
|
156
|
+
* Create a `TrajectoryLogger` whose methods do nothing.
|
|
157
|
+
*/
|
|
158
|
+
function noop_logger() {
|
|
159
|
+
return {
|
|
160
|
+
record: () => {},
|
|
161
|
+
start_span: (name) => `${name}:${randomUUID().slice(0, 8)}`,
|
|
162
|
+
end_span: () => {}
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
// src/adapters/stderr_logger.ts
|
|
166
|
+
/**
|
|
167
|
+
* Create a `TrajectoryLogger` that writes one JSON object per line to
|
|
168
|
+
* stderr, or to `options.stream` when supplied.
|
|
169
|
+
*/
|
|
170
|
+
function stderr_logger(options = {}) {
|
|
171
|
+
const stream = options.stream ?? process.stderr;
|
|
172
|
+
return line_logger((event) => {
|
|
173
|
+
try {
|
|
174
|
+
stream.write(`${JSON.stringify(event)}\n`);
|
|
175
|
+
} catch {}
|
|
176
|
+
});
|
|
177
|
+
}
|
|
178
|
+
// src/adapters/tee_logger.ts
|
|
179
|
+
/**
|
|
180
|
+
* Create a `TrajectoryLogger` that fans every call out to `loggers`.
|
|
181
|
+
*/
|
|
182
|
+
function tee_logger(...loggers) {
|
|
183
|
+
if (loggers.length === 0) throw new Error("tee_logger needs at least one logger: pass the sinks to fan out to, as in `tee_logger(stderr_logger(), http_logger(config))`");
|
|
184
|
+
const id_map = /* @__PURE__ */ new Map();
|
|
185
|
+
const safe_each = (fn) => {
|
|
186
|
+
for (let i = 0; i < loggers.length; i += 1) {
|
|
187
|
+
const l = loggers[i];
|
|
188
|
+
if (l === void 0) continue;
|
|
189
|
+
try {
|
|
190
|
+
fn(l, i);
|
|
191
|
+
} catch {}
|
|
192
|
+
}
|
|
193
|
+
};
|
|
194
|
+
return {
|
|
195
|
+
record: (event) => {
|
|
196
|
+
safe_each((l) => l.record(event));
|
|
197
|
+
},
|
|
198
|
+
start_span: (name, meta) => {
|
|
199
|
+
const ids = loggers.map(() => void 0);
|
|
200
|
+
safe_each((l, idx) => {
|
|
201
|
+
ids[idx] = l.start_span(name, meta);
|
|
202
|
+
});
|
|
203
|
+
const canonical = ids.find((sink_id) => sink_id !== void 0) ?? `${name}:tee`;
|
|
204
|
+
if (loggers.length > 1) id_map.set(canonical, ids);
|
|
205
|
+
return canonical;
|
|
206
|
+
},
|
|
207
|
+
end_span: (id, meta) => {
|
|
208
|
+
const ids = id_map.get(id);
|
|
209
|
+
if (ids === void 0) {
|
|
210
|
+
safe_each((l) => l.end_span(id, meta));
|
|
211
|
+
return;
|
|
212
|
+
}
|
|
213
|
+
id_map.delete(id);
|
|
214
|
+
safe_each((l, idx) => l.end_span(ids[idx] ?? id, meta));
|
|
215
|
+
}
|
|
216
|
+
};
|
|
217
|
+
}
|
|
218
|
+
// src/adapters/filesystem_store.ts
|
|
219
|
+
/**
|
|
220
|
+
* Filesystem-backed checkpoint store.
|
|
221
|
+
*
|
|
222
|
+
* Satisfies `CheckpointStore` from `core`, every optional capability
|
|
223
|
+
* included. Each key is stored as
|
|
224
|
+
* a JSON file under the configured root directory. Writes are all-or-nothing:
|
|
225
|
+
* values are written to a temporary sibling file and then atomically renamed
|
|
226
|
+
* into place, so an interrupted write never leaves a partially written file
|
|
227
|
+
* at the target key. On `get`, a missing file, a partial temp file that was
|
|
228
|
+
* never atomically renamed, or a JSON parse failure each read as a cache
|
|
229
|
+
* miss (returning `null`) rather than an error. Any other failure to read
|
|
230
|
+
* (a permission error, a failing disk) surfaces, because reading it as a miss
|
|
231
|
+
* could start a durable run over, or hand a live claim to a second owner.
|
|
232
|
+
*
|
|
233
|
+
* A scope is a directory beside the values (`<prefix>.scope/`), which makes
|
|
234
|
+
* `clear` one recursive delete. A claim is a directory of numbered
|
|
235
|
+
* generations (`<key>.claim/<n>.json`), and the newest one is the claim. A
|
|
236
|
+
* claimer takes a free or expired key by creating the next generation with
|
|
237
|
+
* `link`, which makes the file appear whole and refuses a target that
|
|
238
|
+
* already exists, so two claimers can't both create it. Taking an expired
|
|
239
|
+
* claim never overwrites a live one, which a rename into place couldn't
|
|
240
|
+
* promise, and a claimer that finds a newer generation than its own has lost.
|
|
241
|
+
*
|
|
242
|
+
* A value's version, for `get_versioned` and `set_if`, is a hash of its
|
|
243
|
+
* file's bytes, so the files stay where they always were. Every write to a
|
|
244
|
+
* key holds a lock on it while it works, `set` and `delete` included, which
|
|
245
|
+
* is what makes `set_if` atomic against all of them. The lock is an empty
|
|
246
|
+
* directory beside the value (`<key>.lock/`), made with one `mkdir`, which
|
|
247
|
+
* refuses a directory that exists, and removed with one `rmdir` when the
|
|
248
|
+
* write is done, so nothing stays behind. Under the lock, `set_if` writes its
|
|
249
|
+
* temporary file, reads the bytes at the key, and renames the file into place
|
|
250
|
+
* only when their hash is the version it was given. A create
|
|
251
|
+
* (`expected: null`) needs no lock, because it's the same `link` a claim
|
|
252
|
+
* uses.
|
|
253
|
+
*
|
|
254
|
+
* The lock costs a write two calls more than it would make without one: a
|
|
255
|
+
* `set` is four filesystem calls, a `delete` three, and a `set_if` on a
|
|
256
|
+
* version six. Writers to one key go one at a time. Those in one process
|
|
257
|
+
* queue in memory, and those in other processes ask for the lock again every
|
|
258
|
+
* couple of milliseconds, so a key that many writers want at once is as slow
|
|
259
|
+
* as the queue is long.
|
|
260
|
+
*
|
|
261
|
+
* A writer that dies between its `mkdir` and its `rmdir` leaves the lock
|
|
262
|
+
* behind. A lock older than ten seconds counts as abandoned, and the writer
|
|
263
|
+
* that finds one removes it while holding a claim on the directory's
|
|
264
|
+
* `lock.recovery/`, so two writers can't both clear the way and a lock taken
|
|
265
|
+
* since is never the one removed. That directory appears the first time a
|
|
266
|
+
* lock is recovered and stays. A writer that stalls for longer than ten
|
|
267
|
+
* seconds inside a write is taken for dead, and the write it finishes late
|
|
268
|
+
* is no longer exclusive.
|
|
269
|
+
*
|
|
270
|
+
* All of this leans on `link`, `rename`, and `mkdir` being atomic and on a
|
|
271
|
+
* directory listing being current, which a local filesystem gives and a network
|
|
272
|
+
* filesystem may not. So this is a store for the processes of one machine,
|
|
273
|
+
* and a run that events reach on several hosts wants `object_store`.
|
|
274
|
+
*
|
|
275
|
+
* Paths are accepted at construction; the store never reads `process.env`.
|
|
276
|
+
*/
|
|
277
|
+
const LOCK_MS = 1e4;
|
|
278
|
+
const LOCK_RETRY_MS = 2;
|
|
279
|
+
const RECOVERY = "lock.recovery";
|
|
280
|
+
const turns = /* @__PURE__ */ new Map();
|
|
281
|
+
/**
|
|
282
|
+
* Turn a key or a scope prefix into a filesystem-safe name.
|
|
283
|
+
*
|
|
284
|
+
* Slugs it down to `[a-zA-Z0-9._-]` and appends a short hash of the whole
|
|
285
|
+
* string, so two strings that slug alike still land on distinct names.
|
|
286
|
+
*/
|
|
287
|
+
function safe_name(key) {
|
|
288
|
+
const hash = createHash("sha256").update(key).digest("hex").slice(0, 12);
|
|
289
|
+
return `${key.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 64)}.${hash}`;
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* Read the `code` a Node filesystem error carries, if it has one.
|
|
293
|
+
*/
|
|
294
|
+
function error_code(err) {
|
|
295
|
+
return err instanceof Error ? Reflect.get(err, "code") : void 0;
|
|
296
|
+
}
|
|
297
|
+
/**
|
|
298
|
+
* Serialize a value for disk. A value JSON has no text for (`undefined`, a
|
|
299
|
+
* bare function) is written as `null`, which reads back as a miss.
|
|
300
|
+
*/
|
|
301
|
+
function to_json$2(value) {
|
|
302
|
+
return JSON.stringify(value) ?? "null";
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* Write `value` to `path` through a temporary sibling and a rename, so a
|
|
306
|
+
* reader sees the old file or the new one and never a torn one.
|
|
307
|
+
*/
|
|
308
|
+
async function write_atomic(path, value) {
|
|
309
|
+
const tmp = `${path}.${randomUUID().slice(0, 8)}.tmp`;
|
|
310
|
+
await writeFile(tmp, to_json$2(value));
|
|
311
|
+
await rename(tmp, path);
|
|
312
|
+
}
|
|
313
|
+
/**
|
|
314
|
+
* Create `path` holding `value` unless something is already there.
|
|
315
|
+
*
|
|
316
|
+
* The JSON goes to a temporary file first and is hard-linked into place, so
|
|
317
|
+
* the file appears whole, and `link` refuses an existing target, so exactly
|
|
318
|
+
* one of several racing creators sees true.
|
|
319
|
+
*/
|
|
320
|
+
async function create_exclusive(path, value) {
|
|
321
|
+
const tmp = `${path}.${randomUUID().slice(0, 8)}.tmp`;
|
|
322
|
+
await writeFile(tmp, to_json$2(value));
|
|
323
|
+
try {
|
|
324
|
+
await link(tmp, path);
|
|
325
|
+
return true;
|
|
326
|
+
} catch (err) {
|
|
327
|
+
if (error_code(err) === "EEXIST") return false;
|
|
328
|
+
throw err;
|
|
329
|
+
} finally {
|
|
330
|
+
await rm(tmp);
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
/**
|
|
334
|
+
* The path of one generation in a claim directory.
|
|
335
|
+
*/
|
|
336
|
+
function generation_path(dir, generation) {
|
|
337
|
+
return join(dir, `${generation}.json`);
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* The newest generation in a claim directory, or 0 when it holds none or
|
|
341
|
+
* doesn't exist yet.
|
|
342
|
+
*/
|
|
343
|
+
async function latest_generation(dir) {
|
|
344
|
+
return Math.max(0, ...await generations(dir));
|
|
345
|
+
}
|
|
346
|
+
/**
|
|
347
|
+
* Every generation number present in a claim directory.
|
|
348
|
+
*/
|
|
349
|
+
async function generations(dir) {
|
|
350
|
+
let names;
|
|
351
|
+
try {
|
|
352
|
+
names = await readdir(dir);
|
|
353
|
+
} catch (err) {
|
|
354
|
+
if (error_code(err) === "ENOENT") return [];
|
|
355
|
+
throw err;
|
|
356
|
+
}
|
|
357
|
+
return names.flatMap((name) => {
|
|
358
|
+
const match = /^(\d+)\.json$/.exec(name);
|
|
359
|
+
return match === null ? [] : [Number(match[1])];
|
|
360
|
+
});
|
|
361
|
+
}
|
|
362
|
+
/**
|
|
363
|
+
* Read and parse the JSON at `path`, or `null` when the file is missing or
|
|
364
|
+
* doesn't parse. Any other failure surfaces.
|
|
365
|
+
*/
|
|
366
|
+
async function read_json(path) {
|
|
367
|
+
let raw;
|
|
368
|
+
try {
|
|
369
|
+
raw = await readFile(path, "utf8");
|
|
370
|
+
} catch (err) {
|
|
371
|
+
if (error_code(err) === "ENOENT") return null;
|
|
372
|
+
throw err;
|
|
373
|
+
}
|
|
374
|
+
return parse_json(raw);
|
|
375
|
+
}
|
|
376
|
+
/**
|
|
377
|
+
* Parse stored text, or `null` when it isn't whole JSON.
|
|
378
|
+
*/
|
|
379
|
+
function parse_json(raw) {
|
|
380
|
+
try {
|
|
381
|
+
return JSON.parse(raw);
|
|
382
|
+
} catch {
|
|
383
|
+
return null;
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
/**
|
|
387
|
+
* The bytes at `path`, or `undefined` when no file is there. Any other
|
|
388
|
+
* failure surfaces.
|
|
389
|
+
*/
|
|
390
|
+
async function read_bytes(path) {
|
|
391
|
+
try {
|
|
392
|
+
return await readFile(path);
|
|
393
|
+
} catch (err) {
|
|
394
|
+
if (error_code(err) === "ENOENT") return void 0;
|
|
395
|
+
throw err;
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
/**
|
|
399
|
+
* The version of a value whose file holds `bytes`: a hash of them, so it
|
|
400
|
+
* moves whenever the stored text does.
|
|
401
|
+
*/
|
|
402
|
+
function version_of(bytes) {
|
|
403
|
+
return createHash("sha256").update(bytes).digest("hex");
|
|
404
|
+
}
|
|
405
|
+
/**
|
|
406
|
+
* Replace the value at `path` with `value` while the file there still
|
|
407
|
+
* hashes to `expected`, resolving whether it did.
|
|
408
|
+
*
|
|
409
|
+
* The temporary file is written before the bytes are read. A scope that's
|
|
410
|
+
* cleared and made again in between takes the temporary file with it, and
|
|
411
|
+
* the rename then fails, where a file written after the read would land in
|
|
412
|
+
* the new scope over a value this call never saw. A missing directory or a
|
|
413
|
+
* missing file is a conflict like any other, since the key is absent.
|
|
414
|
+
*/
|
|
415
|
+
async function replace_if(path, value, expected) {
|
|
416
|
+
const tmp = `${path}.${randomUUID().slice(0, 8)}.tmp`;
|
|
417
|
+
try {
|
|
418
|
+
await writeFile(tmp, to_json$2(value));
|
|
419
|
+
const bytes = await read_bytes(path);
|
|
420
|
+
if (bytes === void 0 || version_of(bytes) !== expected) return false;
|
|
421
|
+
await rename(tmp, path);
|
|
422
|
+
return true;
|
|
423
|
+
} catch (err) {
|
|
424
|
+
if (error_code(err) === "ENOENT") return false;
|
|
425
|
+
throw err;
|
|
426
|
+
} finally {
|
|
427
|
+
await rm(tmp, { force: true });
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
/**
|
|
431
|
+
* Wait `ms` milliseconds.
|
|
432
|
+
*/
|
|
433
|
+
function sleep(ms) {
|
|
434
|
+
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
435
|
+
}
|
|
436
|
+
/**
|
|
437
|
+
* True when the lock at `path` is older than `LOCK_MS`. A lock that's gone
|
|
438
|
+
* isn't abandoned, it was let go.
|
|
439
|
+
*/
|
|
440
|
+
async function is_abandoned(path) {
|
|
441
|
+
try {
|
|
442
|
+
return Date.now() - (await stat(path)).mtimeMs > LOCK_MS;
|
|
443
|
+
} catch (err) {
|
|
444
|
+
if (error_code(err) === "ENOENT") return false;
|
|
445
|
+
throw err;
|
|
446
|
+
}
|
|
447
|
+
}
|
|
448
|
+
/**
|
|
449
|
+
* Remove the abandoned lock at `path`, or wait a moment when another writer
|
|
450
|
+
* is already removing one.
|
|
451
|
+
*
|
|
452
|
+
* Two writers that both found the lock abandoned can't both be let remove
|
|
453
|
+
* it: the second would remove the lock a third writer took after the first
|
|
454
|
+
* cleared the way. So the removal happens under a claim, and the lock's age
|
|
455
|
+
* is read again once the claim is held. The claim lapses by itself when its
|
|
456
|
+
* holder dies, which a second lock directory wouldn't.
|
|
457
|
+
*/
|
|
458
|
+
async function recover(path) {
|
|
459
|
+
const dir = join(dirname(path), RECOVERY);
|
|
460
|
+
const owner = randomUUID();
|
|
461
|
+
if (!await claim_in(dir, owner, LOCK_MS)) return sleep(LOCK_RETRY_MS);
|
|
462
|
+
try {
|
|
463
|
+
if (await is_abandoned(path)) await rm(path, {
|
|
464
|
+
recursive: true,
|
|
465
|
+
force: true
|
|
466
|
+
});
|
|
467
|
+
} finally {
|
|
468
|
+
await release_in(dir, owner);
|
|
469
|
+
}
|
|
470
|
+
}
|
|
471
|
+
/**
|
|
472
|
+
* Take the lock at `path`, waiting for it while another writer has it.
|
|
473
|
+
*
|
|
474
|
+
* The lock is a directory, and `mkdir` refuses one that exists, so of the
|
|
475
|
+
* writers that ask at once exactly one gets it. The first write to a store
|
|
476
|
+
* finds no directory to make the lock in, and makes that first.
|
|
477
|
+
*/
|
|
478
|
+
async function take_lock(path) {
|
|
479
|
+
for (;;) {
|
|
480
|
+
try {
|
|
481
|
+
await mkdir(path);
|
|
482
|
+
return;
|
|
483
|
+
} catch (err) {
|
|
484
|
+
const code = error_code(err);
|
|
485
|
+
if (code === "ENOENT") {
|
|
486
|
+
await mkdir(dirname(path), { recursive: true });
|
|
487
|
+
continue;
|
|
488
|
+
}
|
|
489
|
+
if (code !== "EEXIST") throw err;
|
|
490
|
+
}
|
|
491
|
+
if (await is_abandoned(path)) await recover(path);
|
|
492
|
+
else await sleep(LOCK_RETRY_MS);
|
|
493
|
+
}
|
|
494
|
+
}
|
|
495
|
+
/**
|
|
496
|
+
* Let go of the lock at `path`. A lock that vanished meanwhile (its scope
|
|
497
|
+
* was cleared) has nothing left to let go of.
|
|
498
|
+
*/
|
|
499
|
+
async function drop_lock(path) {
|
|
500
|
+
try {
|
|
501
|
+
await rmdir(path);
|
|
502
|
+
} catch (err) {
|
|
503
|
+
if (error_code(err) !== "ENOENT") throw err;
|
|
504
|
+
}
|
|
505
|
+
}
|
|
506
|
+
/**
|
|
507
|
+
* Run `body` once every write this process began on `path` before it has
|
|
508
|
+
* finished.
|
|
509
|
+
*
|
|
510
|
+
* The lock directory is for the other processes. Inside one process the
|
|
511
|
+
* writers to a key queue here, so each takes the lock on its first try and
|
|
512
|
+
* none of them spends its wait asking the disk for it.
|
|
513
|
+
*/
|
|
514
|
+
async function in_turn(path, body) {
|
|
515
|
+
const ahead = turns.get(path);
|
|
516
|
+
const done = Promise.withResolvers();
|
|
517
|
+
turns.set(path, done.promise);
|
|
518
|
+
await ahead;
|
|
519
|
+
try {
|
|
520
|
+
return await body();
|
|
521
|
+
} finally {
|
|
522
|
+
if (turns.get(path) === done.promise) turns.delete(path);
|
|
523
|
+
done.resolve();
|
|
524
|
+
}
|
|
525
|
+
}
|
|
526
|
+
/**
|
|
527
|
+
* Run `body` while holding the lock at `path`, waiting for it when another
|
|
528
|
+
* writer has it.
|
|
529
|
+
*/
|
|
530
|
+
function with_lock(path, body) {
|
|
531
|
+
return in_turn(path, async () => {
|
|
532
|
+
await take_lock(path);
|
|
533
|
+
try {
|
|
534
|
+
return await body();
|
|
535
|
+
} finally {
|
|
536
|
+
await drop_lock(path);
|
|
537
|
+
}
|
|
538
|
+
});
|
|
539
|
+
}
|
|
540
|
+
/**
|
|
541
|
+
* Read the claim one generation holds, or null when the file is gone or
|
|
542
|
+
* doesn't hold a claim.
|
|
543
|
+
*/
|
|
544
|
+
async function read_claim$1(path) {
|
|
545
|
+
const parsed = await read_json(path);
|
|
546
|
+
return is_claim_record(parsed) ? parsed : null;
|
|
547
|
+
}
|
|
548
|
+
/**
|
|
549
|
+
* True for the `{ owner, expires_at }` shape a generation file holds.
|
|
550
|
+
*/
|
|
551
|
+
function is_claim_record(value) {
|
|
552
|
+
if (typeof value !== "object" || value === null) return false;
|
|
553
|
+
return typeof Reflect.get(value, "owner") === "string" && typeof Reflect.get(value, "expires_at") === "number";
|
|
554
|
+
}
|
|
555
|
+
/**
|
|
556
|
+
* Delete every generation older than `keep`. A claimer only reads the newest
|
|
557
|
+
* generation, so the older ones are history and nothing waits on them.
|
|
558
|
+
*/
|
|
559
|
+
async function prune(dir, keep) {
|
|
560
|
+
const stale = (await generations(dir)).filter((generation) => generation < keep);
|
|
561
|
+
await Promise.all(stale.map((generation) => rm(generation_path(dir, generation), { force: true })));
|
|
562
|
+
}
|
|
563
|
+
/**
|
|
564
|
+
* Take or renew the claim in `dir` for `owner`.
|
|
565
|
+
*
|
|
566
|
+
* A live claim held by `owner` is renewed in place. Anything else that isn't
|
|
567
|
+
* a live claim is taken by creating the next generation, and the claimer
|
|
568
|
+
* still loses if a newer generation shows up before it confirms. Only a live
|
|
569
|
+
* claim is ever renewed in place, so an expired one changes hands through
|
|
570
|
+
* `create_exclusive` alone and two claimers can't both win it. A renewal that
|
|
571
|
+
* lands at the very instant its claim expires can still race a takeover, and
|
|
572
|
+
* it loses whenever the takeover's generation appears before it confirms.
|
|
573
|
+
*/
|
|
574
|
+
async function claim_in(dir, owner, ttl_ms) {
|
|
575
|
+
await mkdir(dir, { recursive: true });
|
|
576
|
+
const generation = await latest_generation(dir);
|
|
577
|
+
const current = await read_claim$1(generation_path(dir, generation));
|
|
578
|
+
const now = Date.now();
|
|
579
|
+
const claim = {
|
|
580
|
+
owner,
|
|
581
|
+
expires_at: now + ttl_ms
|
|
582
|
+
};
|
|
583
|
+
if (current !== null && current.expires_at > now) {
|
|
584
|
+
if (current.owner !== owner) return false;
|
|
585
|
+
await write_atomic(generation_path(dir, generation), claim);
|
|
586
|
+
return await latest_generation(dir) === generation;
|
|
587
|
+
}
|
|
588
|
+
const next = generation + 1;
|
|
589
|
+
if (!await create_exclusive(generation_path(dir, next), claim)) return false;
|
|
590
|
+
if (await latest_generation(dir) !== next) return false;
|
|
591
|
+
await prune(dir, next);
|
|
592
|
+
return true;
|
|
593
|
+
}
|
|
594
|
+
/**
|
|
595
|
+
* Release the claim in `dir` when `owner` holds it.
|
|
596
|
+
*
|
|
597
|
+
* The newest generation is rewritten as expired rather than deleted, so
|
|
598
|
+
* generation numbers only ever grow and a slow claimer can't recreate one
|
|
599
|
+
* that was already taken. A directory that vanished meanwhile (its scope was
|
|
600
|
+
* cleared) has nothing left to release.
|
|
601
|
+
*/
|
|
602
|
+
async function release_in(dir, owner) {
|
|
603
|
+
const path = generation_path(dir, await latest_generation(dir));
|
|
604
|
+
if ((await read_claim$1(path))?.owner !== owner) return;
|
|
605
|
+
try {
|
|
606
|
+
await write_atomic(path, {
|
|
607
|
+
owner,
|
|
608
|
+
expires_at: 0
|
|
609
|
+
});
|
|
610
|
+
} catch (err) {
|
|
611
|
+
if (error_code(err) !== "ENOENT") throw err;
|
|
612
|
+
}
|
|
613
|
+
}
|
|
614
|
+
/**
|
|
615
|
+
* Build the store rooted at `root_dir`, scopes and claims included.
|
|
616
|
+
*/
|
|
617
|
+
function store_at$2(root_dir) {
|
|
618
|
+
const value_path = (key) => join(root_dir, `${safe_name(key)}.json`);
|
|
619
|
+
const claim_dir = (key) => join(root_dir, `${safe_name(key)}.claim`);
|
|
620
|
+
const lock_dir = (key) => join(root_dir, `${safe_name(key)}.lock`);
|
|
621
|
+
const get = (key) => read_json(value_path(key));
|
|
622
|
+
const set = (key, value) => with_lock(lock_dir(key), () => write_atomic(value_path(key), value));
|
|
623
|
+
const delete_key = (key) => with_lock(lock_dir(key), () => rm(value_path(key), { force: true }));
|
|
624
|
+
const get_versioned = async (key) => {
|
|
625
|
+
const bytes = await read_bytes(value_path(key));
|
|
626
|
+
if (bytes === void 0) return void 0;
|
|
627
|
+
const parsed = parse_json(bytes.toString("utf8"));
|
|
628
|
+
return {
|
|
629
|
+
value: parsed === null ? void 0 : parsed,
|
|
630
|
+
version: version_of(bytes)
|
|
631
|
+
};
|
|
632
|
+
};
|
|
633
|
+
const set_if = async (key, value, expected) => {
|
|
634
|
+
if (expected === null) {
|
|
635
|
+
await mkdir(root_dir, { recursive: true });
|
|
636
|
+
return create_exclusive(value_path(key), value);
|
|
637
|
+
}
|
|
638
|
+
return with_lock(lock_dir(key), () => replace_if(value_path(key), value, expected));
|
|
639
|
+
};
|
|
640
|
+
const scope = (prefix) => {
|
|
641
|
+
const dir = join(root_dir, `${safe_name(prefix)}.scope`);
|
|
642
|
+
return {
|
|
643
|
+
...store_at$2(dir),
|
|
644
|
+
clear: () => rm(dir, {
|
|
645
|
+
recursive: true,
|
|
646
|
+
force: true
|
|
647
|
+
})
|
|
648
|
+
};
|
|
649
|
+
};
|
|
650
|
+
return {
|
|
651
|
+
get,
|
|
652
|
+
set,
|
|
653
|
+
delete: delete_key,
|
|
654
|
+
scope,
|
|
655
|
+
claim: (key, owner, ttl_ms) => claim_in(claim_dir(key), owner, ttl_ms),
|
|
656
|
+
release: (key, owner) => release_in(claim_dir(key), owner),
|
|
657
|
+
get_versioned,
|
|
658
|
+
set_if
|
|
659
|
+
};
|
|
660
|
+
}
|
|
661
|
+
/**
|
|
662
|
+
* Create a `CheckpointStore` backed by JSON files under `config.root_dir`.
|
|
663
|
+
*/
|
|
664
|
+
function filesystem_store(config) {
|
|
665
|
+
return store_at$2(config.root_dir);
|
|
666
|
+
}
|
|
667
|
+
// src/adapters/memory_store.ts
|
|
668
|
+
/**
|
|
669
|
+
* Build an in-memory `CheckpointStore` with scopes, claims, and conditional
|
|
670
|
+
* writes.
|
|
671
|
+
*/
|
|
672
|
+
function memory_store(options = {}) {
|
|
673
|
+
const now = options.now ?? (() => Date.now());
|
|
674
|
+
const spaces = /* @__PURE__ */ new Map();
|
|
675
|
+
let writes = 0;
|
|
676
|
+
const space_at = (path) => {
|
|
677
|
+
const id = JSON.stringify(path);
|
|
678
|
+
const existing = spaces.get(id);
|
|
679
|
+
if (existing !== void 0) return existing;
|
|
680
|
+
const created = {
|
|
681
|
+
path,
|
|
682
|
+
values: /* @__PURE__ */ new Map(),
|
|
683
|
+
claims: /* @__PURE__ */ new Map()
|
|
684
|
+
};
|
|
685
|
+
spaces.set(id, created);
|
|
686
|
+
return created;
|
|
687
|
+
};
|
|
688
|
+
const clear_under = (path) => {
|
|
689
|
+
for (const [id, space] of spaces) if (path.every((part, i) => space.path[i] === part)) spaces.delete(id);
|
|
690
|
+
};
|
|
691
|
+
const write = (path, key, value) => {
|
|
692
|
+
writes += 1;
|
|
693
|
+
const version = options.content_versions === true ? JSON.stringify(value) : `w${writes}`;
|
|
694
|
+
space_at(path).values.set(key, {
|
|
695
|
+
value: structuredClone(value),
|
|
696
|
+
version
|
|
697
|
+
});
|
|
698
|
+
};
|
|
699
|
+
const store_at = (path) => ({
|
|
700
|
+
get: async (key) => {
|
|
701
|
+
const value = space_at(path).values.get(key)?.value;
|
|
702
|
+
return value === void 0 ? null : structuredClone(value);
|
|
703
|
+
},
|
|
704
|
+
set: async (key, value) => {
|
|
705
|
+
write(path, key, value);
|
|
706
|
+
},
|
|
707
|
+
delete: async (key) => {
|
|
708
|
+
space_at(path).values.delete(key);
|
|
709
|
+
},
|
|
710
|
+
scope: (prefix) => {
|
|
711
|
+
const inner = [...path, prefix];
|
|
712
|
+
return {
|
|
713
|
+
...store_at(inner),
|
|
714
|
+
clear: async () => clear_under(inner)
|
|
715
|
+
};
|
|
716
|
+
},
|
|
717
|
+
claim: async (key, owner, ttl_ms) => {
|
|
718
|
+
const claims = space_at(path).claims;
|
|
719
|
+
const current = claims.get(key);
|
|
720
|
+
const at = now();
|
|
721
|
+
if (current !== void 0 && current.expires_at > at && current.owner !== owner) return false;
|
|
722
|
+
claims.set(key, {
|
|
723
|
+
owner,
|
|
724
|
+
expires_at: at + ttl_ms
|
|
725
|
+
});
|
|
726
|
+
return true;
|
|
727
|
+
},
|
|
728
|
+
release: async (key, owner) => {
|
|
729
|
+
const claims = space_at(path).claims;
|
|
730
|
+
if (claims.get(key)?.owner === owner) claims.delete(key);
|
|
731
|
+
},
|
|
732
|
+
get_versioned: async (key) => {
|
|
733
|
+
const entry = space_at(path).values.get(key);
|
|
734
|
+
if (entry === void 0) return void 0;
|
|
735
|
+
return {
|
|
736
|
+
value: entry.value === null ? void 0 : structuredClone(entry.value),
|
|
737
|
+
version: entry.version
|
|
738
|
+
};
|
|
739
|
+
},
|
|
740
|
+
set_if: async (key, value, expected) => {
|
|
741
|
+
if ((space_at(path).values.get(key)?.version ?? null) !== expected) return false;
|
|
742
|
+
write(path, key, value);
|
|
743
|
+
return true;
|
|
744
|
+
}
|
|
745
|
+
});
|
|
746
|
+
const dump = () => {
|
|
747
|
+
const out = {};
|
|
748
|
+
for (const [id, space] of spaces) {
|
|
749
|
+
if (space.values.size === 0) continue;
|
|
750
|
+
out[id] = Object.fromEntries([...space.values].map(([key, entry]) => [key, entry.value]));
|
|
751
|
+
}
|
|
752
|
+
return out;
|
|
753
|
+
};
|
|
754
|
+
return {
|
|
755
|
+
...store_at([]),
|
|
756
|
+
dump
|
|
757
|
+
};
|
|
758
|
+
}
|
|
759
|
+
// src/adapters/sqlite_store.ts
|
|
760
|
+
/**
|
|
761
|
+
* SQLite-backed checkpoint store.
|
|
762
|
+
*
|
|
763
|
+
* Satisfies `CheckpointStore` from `core`, every optional capability
|
|
764
|
+
* included, on `node:sqlite`, which is built into Node and needs no native
|
|
765
|
+
* module. One file holds every run, and several processes on one machine can
|
|
766
|
+
* share it, since SQLite runs each statement atomically across connections.
|
|
767
|
+
*
|
|
768
|
+
* `node:sqlite` is loaded when `sqlite_store` is called and not before, so
|
|
769
|
+
* importing `fascicle/adapters` never loads it, and never prints the warning
|
|
770
|
+
* that an older Node 24 prints for an experimental module.
|
|
771
|
+
*
|
|
772
|
+
* Values and claims sit in a table each, keyed by scope and key. A scope is
|
|
773
|
+
* a path of percent-encoded segments, each followed by `/`, so `clear`
|
|
774
|
+
* deletes the range of paths that start with the scope's own and can't reach
|
|
775
|
+
* a sibling whose name only looks alike. A value's version is drawn fresh on
|
|
776
|
+
* every write, which is what `set_if` compares.
|
|
777
|
+
*
|
|
778
|
+
* A claim is one statement: an insert that updates on conflict only when the
|
|
779
|
+
* current claim is the same owner's or has expired. The claimer has won when
|
|
780
|
+
* the statement changed a row.
|
|
781
|
+
*
|
|
782
|
+
* The database opens in WAL mode with a busy timeout, so a second process
|
|
783
|
+
* waits for a lock instead of failing at once.
|
|
784
|
+
*/
|
|
785
|
+
const DEFAULT_TIMEOUT_MS = 5e3;
|
|
786
|
+
const SCHEMA = `
|
|
787
|
+
CREATE TABLE IF NOT EXISTS fascicle_values (
|
|
788
|
+
scope TEXT NOT NULL,
|
|
789
|
+
key TEXT NOT NULL,
|
|
790
|
+
value TEXT NOT NULL,
|
|
791
|
+
version TEXT NOT NULL,
|
|
792
|
+
PRIMARY KEY (scope, key)
|
|
793
|
+
) WITHOUT ROWID;
|
|
794
|
+
CREATE TABLE IF NOT EXISTS fascicle_claims (
|
|
795
|
+
scope TEXT NOT NULL,
|
|
796
|
+
key TEXT NOT NULL,
|
|
797
|
+
owner TEXT NOT NULL,
|
|
798
|
+
expires_at INTEGER NOT NULL,
|
|
799
|
+
PRIMARY KEY (scope, key)
|
|
800
|
+
) WITHOUT ROWID;
|
|
801
|
+
`;
|
|
802
|
+
/**
|
|
803
|
+
* Open the database at `path` in WAL mode, with `timeout_ms` as its busy
|
|
804
|
+
* timeout.
|
|
805
|
+
*/
|
|
806
|
+
function open$1(path, timeout_ms) {
|
|
807
|
+
const db = new (process.getBuiltinModule("node:sqlite")).DatabaseSync(path);
|
|
808
|
+
db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.trunc(timeout_ms))}`);
|
|
809
|
+
db.exec("PRAGMA journal_mode = WAL");
|
|
810
|
+
db.exec(SCHEMA);
|
|
811
|
+
return db;
|
|
812
|
+
}
|
|
813
|
+
/**
|
|
814
|
+
* Prepare every statement the store runs.
|
|
815
|
+
*/
|
|
816
|
+
function prepare(db) {
|
|
817
|
+
return {
|
|
818
|
+
get: db.prepare("SELECT value, version FROM fascicle_values WHERE scope = ? AND key = ?"),
|
|
819
|
+
put: db.prepare(`INSERT INTO fascicle_values (scope, key, value, version) VALUES (?, ?, ?, ?)
|
|
820
|
+
ON CONFLICT (scope, key) DO UPDATE SET value = excluded.value, version = excluded.version`),
|
|
821
|
+
remove: db.prepare("DELETE FROM fascicle_values WHERE scope = ? AND key = ?"),
|
|
822
|
+
create: db.prepare(`INSERT INTO fascicle_values (scope, key, value, version) VALUES (?, ?, ?, ?)
|
|
823
|
+
ON CONFLICT (scope, key) DO NOTHING`),
|
|
824
|
+
replace: db.prepare("UPDATE fascicle_values SET value = ?, version = ? WHERE scope = ? AND key = ? AND version = ?"),
|
|
825
|
+
claim: db.prepare(`INSERT INTO fascicle_claims (scope, key, owner, expires_at) VALUES (?, ?, ?, ?)
|
|
826
|
+
ON CONFLICT (scope, key) DO UPDATE SET owner = excluded.owner, expires_at = excluded.expires_at
|
|
827
|
+
WHERE fascicle_claims.owner = excluded.owner OR fascicle_claims.expires_at <= ?`),
|
|
828
|
+
release: db.prepare("DELETE FROM fascicle_claims WHERE scope = ? AND key = ? AND owner = ?"),
|
|
829
|
+
clear_values: db.prepare("DELETE FROM fascicle_values WHERE scope >= ? AND scope < ?"),
|
|
830
|
+
clear_claims: db.prepare("DELETE FROM fascicle_claims WHERE scope >= ? AND scope < ?")
|
|
831
|
+
};
|
|
832
|
+
}
|
|
833
|
+
/**
|
|
834
|
+
* Serialize a value for a row. A value JSON has no text for (`undefined`, a
|
|
835
|
+
* bare function) is written as `null`, which reads back as a miss.
|
|
836
|
+
*/
|
|
837
|
+
function to_json$1(value) {
|
|
838
|
+
return JSON.stringify(value) ?? "null";
|
|
839
|
+
}
|
|
840
|
+
/**
|
|
841
|
+
* Parse a row's text, or `undefined` when it isn't JSON or holds `null`.
|
|
842
|
+
*/
|
|
843
|
+
function from_json(text) {
|
|
844
|
+
if (typeof text !== "string") return void 0;
|
|
845
|
+
try {
|
|
846
|
+
const value = JSON.parse(text);
|
|
847
|
+
return value === null ? void 0 : value;
|
|
848
|
+
} catch {
|
|
849
|
+
return;
|
|
850
|
+
}
|
|
851
|
+
}
|
|
852
|
+
/**
|
|
853
|
+
* The path of the scope that `prefix` names under `parent`. Each segment is
|
|
854
|
+
* percent-encoded, which leaves no `/` inside it, and ends in one.
|
|
855
|
+
*/
|
|
856
|
+
function child_path(parent, prefix) {
|
|
857
|
+
return `${parent}${encodeURIComponent(prefix)}/`;
|
|
858
|
+
}
|
|
859
|
+
/**
|
|
860
|
+
* The first path that sorts after every path starting with `path`. A scope's
|
|
861
|
+
* path ends in `/`, and `0` is the character after it.
|
|
862
|
+
*/
|
|
863
|
+
function path_end(path) {
|
|
864
|
+
return `${path.slice(0, -1)}0`;
|
|
865
|
+
}
|
|
866
|
+
/**
|
|
867
|
+
* The store over the rows of one scope path.
|
|
868
|
+
*/
|
|
869
|
+
function store_at$1(db, sql, path) {
|
|
870
|
+
return {
|
|
871
|
+
get: async (key) => from_json(sql.get.get(path, key)?.["value"]) ?? null,
|
|
872
|
+
set: async (key, value) => {
|
|
873
|
+
sql.put.run(path, key, to_json$1(value), randomUUID());
|
|
874
|
+
},
|
|
875
|
+
delete: async (key) => {
|
|
876
|
+
sql.remove.run(path, key);
|
|
877
|
+
},
|
|
878
|
+
scope: (prefix) => {
|
|
879
|
+
const inner = child_path(path, prefix);
|
|
880
|
+
return {
|
|
881
|
+
...store_at$1(db, sql, inner),
|
|
882
|
+
clear: async () => {
|
|
883
|
+
db.exec("BEGIN IMMEDIATE");
|
|
884
|
+
try {
|
|
885
|
+
sql.clear_values.run(inner, path_end(inner));
|
|
886
|
+
sql.clear_claims.run(inner, path_end(inner));
|
|
887
|
+
db.exec("COMMIT");
|
|
888
|
+
} catch (err) {
|
|
889
|
+
db.exec("ROLLBACK");
|
|
890
|
+
throw err;
|
|
891
|
+
}
|
|
892
|
+
}
|
|
893
|
+
};
|
|
894
|
+
},
|
|
895
|
+
claim: async (key, owner, ttl_ms) => {
|
|
896
|
+
const at = Date.now();
|
|
897
|
+
return sql.claim.run(path, key, owner, at + ttl_ms, at).changes === 1;
|
|
898
|
+
},
|
|
899
|
+
release: async (key, owner) => {
|
|
900
|
+
sql.release.run(path, key, owner);
|
|
901
|
+
},
|
|
902
|
+
get_versioned: async (key) => {
|
|
903
|
+
const row = sql.get.get(path, key);
|
|
904
|
+
if (row === void 0) return void 0;
|
|
905
|
+
return {
|
|
906
|
+
value: from_json(row["value"]),
|
|
907
|
+
version: String(row["version"])
|
|
908
|
+
};
|
|
909
|
+
},
|
|
910
|
+
set_if: async (key, value, expected) => {
|
|
911
|
+
const text = to_json$1(value);
|
|
912
|
+
const version = randomUUID();
|
|
913
|
+
return (expected === null ? sql.create.run(path, key, text, version) : sql.replace.run(text, version, path, key, expected)).changes === 1;
|
|
914
|
+
}
|
|
915
|
+
};
|
|
916
|
+
}
|
|
917
|
+
/**
|
|
918
|
+
* Build a `CheckpointStore` over a SQLite database, with scopes, claims, and
|
|
919
|
+
* conditional writes.
|
|
920
|
+
*
|
|
921
|
+
* The file is created when it doesn't exist, and so are the store's two
|
|
922
|
+
* tables, which leaves room for other tables beside them. `close` closes the
|
|
923
|
+
* database.
|
|
924
|
+
*/
|
|
925
|
+
function sqlite_store(config) {
|
|
926
|
+
const db = open$1(config.path, config.timeout_ms ?? DEFAULT_TIMEOUT_MS);
|
|
927
|
+
return {
|
|
928
|
+
...store_at$1(db, prepare(db), ""),
|
|
929
|
+
close: () => {
|
|
930
|
+
db.close();
|
|
931
|
+
}
|
|
932
|
+
};
|
|
933
|
+
}
|
|
934
|
+
// src/adapters/object_store.ts
|
|
935
|
+
/**
|
|
936
|
+
* Object-store-backed checkpoint store.
|
|
937
|
+
*
|
|
938
|
+
* Satisfies `CheckpointStore` from `core`, every optional capability
|
|
939
|
+
* included, over a small client interface, so a durable run can live in a
|
|
940
|
+
* bucket that every host in a fleet reaches. The store needs four things of
|
|
941
|
+
* the service: get, put, delete, and a paginated list by prefix, plus the two
|
|
942
|
+
* conditional puts that S3 and the services shaped like it have.
|
|
943
|
+
* `If-None-Match: *` creates a key only while it's absent, and `If-Match`
|
|
944
|
+
* replaces one only while its ETag still matches. Fascicle ships no client
|
|
945
|
+
* and depends on no cloud SDK. `ObjectClient` is the seam, and
|
|
946
|
+
* `docs/human-in-the-loop.md` shows one for `@aws-sdk/client-s3`.
|
|
947
|
+
*
|
|
948
|
+
* A scope is a key prefix, which makes `clear` a paginated list and a delete
|
|
949
|
+
* per key, with the scope's own claims deleted last, so whoever holds a claim
|
|
950
|
+
* on the scope (the lease that `durable` deletes a run under) holds it until
|
|
951
|
+
* everything else is gone. Every name is percent-encoded before it joins a key, dots
|
|
952
|
+
* included, and values, claims, and nested scopes each take a segment of
|
|
953
|
+
* their own (`v/`, `c/`, `s/`), so two names can't land on one object however
|
|
954
|
+
* alike they look. A name whose encoding runs past `MAX_SEGMENT` characters
|
|
955
|
+
* is cut and given a hash of the whole name, which keeps a key under S3's
|
|
956
|
+
* 1,024-byte limit through several scopes.
|
|
957
|
+
*
|
|
958
|
+
* A value's version is its ETag. A claim is an object holding its owner and
|
|
959
|
+
* expiry, and every change to it is a conditional put on the ETag the
|
|
960
|
+
* claimer read, so when claimers race, the bucket accepts exactly one of
|
|
961
|
+
* them. The store never asks for a conditional delete, which not every
|
|
962
|
+
* service has, so a release overwrites the claim as expired.
|
|
963
|
+
*
|
|
964
|
+
* A failed condition is read again before it counts. A client that retries
|
|
965
|
+
* a put whose answer got lost sees its own earlier write as the conflict, so
|
|
966
|
+
* when the object's body is the one this call tried to write, the write
|
|
967
|
+
* landed. That reading is safe as long as no two writers send the same body,
|
|
968
|
+
* which holds for a claim (it carries its owner and expiry) and for a
|
|
969
|
+
* durable run's record (it carries its revision).
|
|
970
|
+
*
|
|
971
|
+
* The store needs a read, and a list, to see the last write. A bucket whose
|
|
972
|
+
* reads lag its writes (some multi-region setups) can't hold a run.
|
|
973
|
+
*/
|
|
974
|
+
const VALUE = "v/";
|
|
975
|
+
const CLAIM = "c/";
|
|
976
|
+
const SCOPE = "s/";
|
|
977
|
+
const MAX_SEGMENT = 128;
|
|
978
|
+
const KEPT = 64;
|
|
979
|
+
/**
|
|
980
|
+
* Encode a key or a scope prefix as one segment of an object key.
|
|
981
|
+
*
|
|
982
|
+
* Percent encoding leaves no `/` inside a name, so a value's key can never
|
|
983
|
+
* pass for a nested scope's prefix, and dots are encoded too, because some
|
|
984
|
+
* HTTP layers rewrite `.` and `..` segments in a path. A long name keeps the
|
|
985
|
+
* start of its encoding and takes a hash of the whole name after a dot.
|
|
986
|
+
* Nothing else puts a dot in a segment, so a hashed name can't land on a
|
|
987
|
+
* short one.
|
|
988
|
+
*/
|
|
989
|
+
function segment(name) {
|
|
990
|
+
const encoded = encodeURIComponent(name).replaceAll(".", "%2E");
|
|
991
|
+
if (encoded.length <= MAX_SEGMENT) return encoded;
|
|
992
|
+
const hash = createHash("sha256").update(name).digest("hex");
|
|
993
|
+
return `${encoded.slice(0, KEPT).replaceAll("%", "_")}.${hash}`;
|
|
994
|
+
}
|
|
995
|
+
/**
|
|
996
|
+
* Parse a stored body, reading anything that isn't whole JSON as a miss.
|
|
997
|
+
*/
|
|
998
|
+
function parse(body) {
|
|
999
|
+
try {
|
|
1000
|
+
return JSON.parse(body);
|
|
1001
|
+
} catch {
|
|
1002
|
+
return null;
|
|
1003
|
+
}
|
|
1004
|
+
}
|
|
1005
|
+
/**
|
|
1006
|
+
* Serialize a value as JSON. A value that JSON has no text for (`undefined`,
|
|
1007
|
+
* a bare function) is written as `null`, which reads back as a miss.
|
|
1008
|
+
*/
|
|
1009
|
+
function to_json(value) {
|
|
1010
|
+
return JSON.stringify(value) ?? "null";
|
|
1011
|
+
}
|
|
1012
|
+
/**
|
|
1013
|
+
* Read a claim object back, or `null` when its body isn't a claim.
|
|
1014
|
+
*/
|
|
1015
|
+
function read_claim(body) {
|
|
1016
|
+
const parsed = parse(body);
|
|
1017
|
+
if (typeof parsed !== "object" || parsed === null) return null;
|
|
1018
|
+
const owner = Reflect.get(parsed, "owner");
|
|
1019
|
+
const expires_at = Reflect.get(parsed, "expires_at");
|
|
1020
|
+
return typeof owner === "string" && typeof expires_at === "number" ? {
|
|
1021
|
+
owner,
|
|
1022
|
+
expires_at
|
|
1023
|
+
} : null;
|
|
1024
|
+
}
|
|
1025
|
+
/**
|
|
1026
|
+
* Put `body` under `key` if `condition` holds, resolving whether the object
|
|
1027
|
+
* now holds this call's write.
|
|
1028
|
+
*
|
|
1029
|
+
* A failed condition usually means another writer got there first. It can
|
|
1030
|
+
* also be this call's own write, landed by an attempt whose answer was lost
|
|
1031
|
+
* and refused on the retry, so the object is read again, and a body
|
|
1032
|
+
* identical to `body` counts as the write landing.
|
|
1033
|
+
*/
|
|
1034
|
+
async function put_if(client, key, body, condition) {
|
|
1035
|
+
if (await client.put(key, body, condition)) return true;
|
|
1036
|
+
return (await client.get(key))?.body === body;
|
|
1037
|
+
}
|
|
1038
|
+
/**
|
|
1039
|
+
* Take or renew the claim at `key` for `owner`.
|
|
1040
|
+
*
|
|
1041
|
+
* A key nobody has claimed is created with `If-None-Match: *`. Anything else
|
|
1042
|
+
* that isn't a live claim held by another owner is replaced with `If-Match`
|
|
1043
|
+
* on the ETag just read, which covers both a renewal and the takeover of an
|
|
1044
|
+
* expired claim. Either way, a claimer that read a state someone else has
|
|
1045
|
+
* since changed loses the put.
|
|
1046
|
+
*/
|
|
1047
|
+
async function claim_at(client, key, owner, ttl_ms) {
|
|
1048
|
+
const current = await client.get(key);
|
|
1049
|
+
const now = Date.now();
|
|
1050
|
+
const held = current === void 0 ? null : read_claim(current.body);
|
|
1051
|
+
if (held !== null && held.expires_at > now && held.owner !== owner) return false;
|
|
1052
|
+
return put_if(client, key, JSON.stringify({
|
|
1053
|
+
owner,
|
|
1054
|
+
expires_at: now + ttl_ms
|
|
1055
|
+
}), current === void 0 ? { if_none_match: "*" } : { if_match: current.etag });
|
|
1056
|
+
}
|
|
1057
|
+
/**
|
|
1058
|
+
* Release the claim at `key` when `owner` holds it.
|
|
1059
|
+
*
|
|
1060
|
+
* The claim is overwritten as expired, on the ETag just read, and never
|
|
1061
|
+
* deleted. A plain delete could erase a claim that another owner took after
|
|
1062
|
+
* the read, and a conditional delete isn't something every service has. A
|
|
1063
|
+
* put that loses means the claim changed hands, which leaves nothing to
|
|
1064
|
+
* release.
|
|
1065
|
+
*/
|
|
1066
|
+
async function release_at(client, key, owner) {
|
|
1067
|
+
const current = await client.get(key);
|
|
1068
|
+
if (current === void 0 || read_claim(current.body)?.owner !== owner) return;
|
|
1069
|
+
await client.put(key, JSON.stringify({
|
|
1070
|
+
owner,
|
|
1071
|
+
expires_at: 0
|
|
1072
|
+
}), { if_match: current.etag });
|
|
1073
|
+
}
|
|
1074
|
+
/**
|
|
1075
|
+
* Delete every object whose key starts with `prefix`, a page at a time, and
|
|
1076
|
+
* the claims directly under it after everything else.
|
|
1077
|
+
*
|
|
1078
|
+
* A listing is sorted, and `c/` sorts ahead of `s/` and `v/`, so deleting in
|
|
1079
|
+
* listing order would free a claim on the scope while later pages still held
|
|
1080
|
+
* its values. A caller that clears under a claim, as `durable` deletes a run
|
|
1081
|
+
* under its lease, keeps that claim until the rest of the scope is gone.
|
|
1082
|
+
*/
|
|
1083
|
+
async function delete_prefix(client, prefix) {
|
|
1084
|
+
const claims = `${prefix}${CLAIM}`;
|
|
1085
|
+
const held = [];
|
|
1086
|
+
let start_after;
|
|
1087
|
+
for (;;) {
|
|
1088
|
+
const page = await client.list(prefix, start_after);
|
|
1089
|
+
held.push(...page.keys.filter((key) => key.startsWith(claims)));
|
|
1090
|
+
await Promise.all(page.keys.filter((key) => !key.startsWith(claims)).map((key) => client.delete(key)));
|
|
1091
|
+
if (page.next === void 0) break;
|
|
1092
|
+
start_after = page.next;
|
|
1093
|
+
}
|
|
1094
|
+
await Promise.all(held.map((key) => client.delete(key)));
|
|
1095
|
+
}
|
|
1096
|
+
/**
|
|
1097
|
+
* Build the store whose keys live under `base`.
|
|
1098
|
+
*/
|
|
1099
|
+
function store_at(client, base) {
|
|
1100
|
+
const value_key = (key) => `${base}${VALUE}${segment(key)}`;
|
|
1101
|
+
const claim_key = (key) => `${base}${CLAIM}${segment(key)}`;
|
|
1102
|
+
const scope = (prefix) => {
|
|
1103
|
+
const dir = `${base}${SCOPE}${segment(prefix)}/`;
|
|
1104
|
+
return {
|
|
1105
|
+
...store_at(client, dir),
|
|
1106
|
+
clear: () => delete_prefix(client, dir)
|
|
1107
|
+
};
|
|
1108
|
+
};
|
|
1109
|
+
return {
|
|
1110
|
+
get: async (key) => {
|
|
1111
|
+
const object = await client.get(value_key(key));
|
|
1112
|
+
return object === void 0 ? null : parse(object.body);
|
|
1113
|
+
},
|
|
1114
|
+
set: async (key, value) => {
|
|
1115
|
+
await client.put(value_key(key), to_json(value));
|
|
1116
|
+
},
|
|
1117
|
+
delete: (key) => client.delete(value_key(key)),
|
|
1118
|
+
scope,
|
|
1119
|
+
claim: (key, owner, ttl_ms) => claim_at(client, claim_key(key), owner, ttl_ms),
|
|
1120
|
+
release: (key, owner) => release_at(client, claim_key(key), owner),
|
|
1121
|
+
get_versioned: async (key) => {
|
|
1122
|
+
const object = await client.get(value_key(key));
|
|
1123
|
+
if (object === void 0) return void 0;
|
|
1124
|
+
const parsed = parse(object.body);
|
|
1125
|
+
return {
|
|
1126
|
+
value: parsed === null ? void 0 : parsed,
|
|
1127
|
+
version: object.etag
|
|
1128
|
+
};
|
|
1129
|
+
},
|
|
1130
|
+
set_if: (key, value, expected) => put_if(client, value_key(key), to_json(value), expected === null ? { if_none_match: "*" } : { if_match: expected })
|
|
1131
|
+
};
|
|
1132
|
+
}
|
|
1133
|
+
/**
|
|
1134
|
+
* Create a `CheckpointStore` that keeps its values, claims, and scopes as
|
|
1135
|
+
* objects behind `config.client`, under `config.prefix`.
|
|
1136
|
+
*
|
|
1137
|
+
* Run `checkpoint_store_conformance` from `fascicle/testing` against a real
|
|
1138
|
+
* bucket once before trusting a service with it. A service that accepts a
|
|
1139
|
+
* condition and ignores it lets two writers both win, and that suite is what
|
|
1140
|
+
* catches it.
|
|
1141
|
+
*/
|
|
1142
|
+
function object_store(config) {
|
|
1143
|
+
return store_at(config.client, config.prefix ?? "");
|
|
1144
|
+
}
|
|
1145
|
+
export { tee_logger as a, http_logger as c, filesystem_store as i, filesystem_logger as l, sqlite_store as n, stderr_logger as o, memory_store as r, noop_logger as s, object_store as t };
|
|
1146
|
+
|
|
1147
|
+
//# sourceMappingURL=adapters-DYFauXE1.js.map
|