@wats/persistence 0.3.19 → 0.3.20
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/dist/index.d.ts +41 -2
- package/dist/index.js +2 -1
- package/dist/outbox.d.ts +13 -0
- package/dist/outbox.js +27 -0
- package/dist/sqlite.js +126 -0
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
export declare const CURRENT_SCHEMA_VERSION:
|
|
1
|
+
export declare const CURRENT_SCHEMA_VERSION: 2;
|
|
2
2
|
export declare const REDACTED_SQLITE_LOCATION: "[REDACTED_SQLITE_DATABASE]";
|
|
3
3
|
export type PersistenceBackend = "sqlite" | "postgres";
|
|
4
|
-
export type PersistenceErrorCode = "invalid_options" | "invalid_filename" | "invalid_record" | "migration_failed" | "migration_checksum_mismatch" | "migration_lock_failed" | "store_closed";
|
|
4
|
+
export type PersistenceErrorCode = "invalid_options" | "invalid_filename" | "invalid_record" | "migration_failed" | "migration_checksum_mismatch" | "migration_lock_failed" | "outbox_failed" | "store_closed";
|
|
5
5
|
export interface MigrationReport {
|
|
6
6
|
readonly currentVersion: number;
|
|
7
7
|
readonly appliedMigrations: readonly string[];
|
|
@@ -30,6 +30,39 @@ export interface ServiceRequestRecordInput extends ServiceRequestLookupInput {
|
|
|
30
30
|
export type ServiceRequestLookupResult = null | "conflict" | {
|
|
31
31
|
readonly responseJson: string;
|
|
32
32
|
};
|
|
33
|
+
export type OutboxStatus = "pending" | "processing" | "succeeded";
|
|
34
|
+
export interface OutboxItem {
|
|
35
|
+
readonly id: string;
|
|
36
|
+
readonly status: OutboxStatus;
|
|
37
|
+
readonly attempts: number;
|
|
38
|
+
readonly leaseId: number;
|
|
39
|
+
readonly payloadHash: string;
|
|
40
|
+
readonly nextAttemptAt: string | null;
|
|
41
|
+
readonly createdAt: string;
|
|
42
|
+
readonly updatedAt: string;
|
|
43
|
+
}
|
|
44
|
+
export interface OutboxEnqueueInput {
|
|
45
|
+
readonly id: string;
|
|
46
|
+
readonly payloadHash: string;
|
|
47
|
+
readonly createdAt: string;
|
|
48
|
+
readonly nextAttemptAt?: string | null;
|
|
49
|
+
}
|
|
50
|
+
export type OutboxEnqueueResult = "enqueued" | "duplicate";
|
|
51
|
+
export interface OutboxClaimInput {
|
|
52
|
+
readonly now: string;
|
|
53
|
+
readonly limit: number;
|
|
54
|
+
}
|
|
55
|
+
export interface OutboxFailedInput {
|
|
56
|
+
readonly id: string;
|
|
57
|
+
readonly leaseId: number;
|
|
58
|
+
readonly nextAttemptAt: string;
|
|
59
|
+
readonly updatedAt: string;
|
|
60
|
+
}
|
|
61
|
+
export interface OutboxSucceededInput {
|
|
62
|
+
readonly id: string;
|
|
63
|
+
readonly leaseId: number;
|
|
64
|
+
readonly updatedAt: string;
|
|
65
|
+
}
|
|
33
66
|
export interface PersistenceStore {
|
|
34
67
|
readonly backend: PersistenceBackend;
|
|
35
68
|
migrate(): Promise<MigrationReport>;
|
|
@@ -37,6 +70,10 @@ export interface PersistenceStore {
|
|
|
37
70
|
recordWebhookEvent(input: WebhookEventRecordInput): Promise<WebhookEventRecordResult>;
|
|
38
71
|
getServiceRequest(input: ServiceRequestLookupInput): Promise<ServiceRequestLookupResult>;
|
|
39
72
|
recordServiceRequest(input: ServiceRequestRecordInput): Promise<void>;
|
|
73
|
+
enqueueOutboxItem(input: OutboxEnqueueInput): Promise<OutboxEnqueueResult>;
|
|
74
|
+
claimOutboxItems(input: OutboxClaimInput): Promise<readonly OutboxItem[]>;
|
|
75
|
+
markOutboxItemFailed(input: OutboxFailedInput): Promise<void>;
|
|
76
|
+
markOutboxItemSucceeded(input: OutboxSucceededInput): Promise<void>;
|
|
40
77
|
close(): Promise<void>;
|
|
41
78
|
}
|
|
42
79
|
export declare class PersistenceError extends Error {
|
|
@@ -45,3 +82,5 @@ export declare class PersistenceError extends Error {
|
|
|
45
82
|
}
|
|
46
83
|
export { createSqlitePersistence } from "./sqlite";
|
|
47
84
|
export type { SqlitePersistenceOptions } from "./sqlite";
|
|
85
|
+
export { runOutboxWorkerOnce } from "./outbox";
|
|
86
|
+
export type { OutboxWorkerOptions, OutboxWorkerReport } from "./outbox";
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export const CURRENT_SCHEMA_VERSION =
|
|
1
|
+
export const CURRENT_SCHEMA_VERSION = 2;
|
|
2
2
|
export const REDACTED_SQLITE_LOCATION = "[REDACTED_SQLITE_DATABASE]";
|
|
3
3
|
|
|
4
4
|
export class PersistenceError extends Error {
|
|
@@ -10,3 +10,4 @@ export class PersistenceError extends Error {
|
|
|
10
10
|
}
|
|
11
11
|
}
|
|
12
12
|
export { createSqlitePersistence } from "./sqlite";
|
|
13
|
+
export { runOutboxWorkerOnce } from "./outbox";
|
package/dist/outbox.d.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { OutboxItem, PersistenceStore } from "./index";
|
|
2
|
+
export interface OutboxWorkerOptions {
|
|
3
|
+
readonly now: string;
|
|
4
|
+
readonly limit: number;
|
|
5
|
+
readonly retryDelayMs: number;
|
|
6
|
+
readonly handler: (item: OutboxItem) => Promise<void>;
|
|
7
|
+
}
|
|
8
|
+
export interface OutboxWorkerReport {
|
|
9
|
+
readonly processed: number;
|
|
10
|
+
readonly succeeded: number;
|
|
11
|
+
readonly failed: number;
|
|
12
|
+
}
|
|
13
|
+
export declare function runOutboxWorkerOnce(store: PersistenceStore, options: OutboxWorkerOptions): Promise<OutboxWorkerReport>;
|
package/dist/outbox.js
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
function nextAttemptIso(now, retryDelayMs) {
|
|
2
|
+
if (!Number.isInteger(retryDelayMs) || retryDelayMs < 0 || retryDelayMs > 86400000) {
|
|
3
|
+
throw new RangeError("retryDelayMs must be an integer from 0 to 86400000.");
|
|
4
|
+
}
|
|
5
|
+
return new Date(new Date(now).getTime() + retryDelayMs).toISOString();
|
|
6
|
+
}
|
|
7
|
+
export async function runOutboxWorkerOnce(store, options) {
|
|
8
|
+
const claimed = await store.claimOutboxItems({ now: options.now, limit: options.limit });
|
|
9
|
+
let succeeded = 0;
|
|
10
|
+
let failed = 0;
|
|
11
|
+
for (const item of claimed) {
|
|
12
|
+
try {
|
|
13
|
+
await options.handler(item);
|
|
14
|
+
await store.markOutboxItemSucceeded({ id: item.id, leaseId: item.leaseId, updatedAt: options.now });
|
|
15
|
+
succeeded += 1;
|
|
16
|
+
} catch {
|
|
17
|
+
await store.markOutboxItemFailed({
|
|
18
|
+
id: item.id,
|
|
19
|
+
leaseId: item.leaseId,
|
|
20
|
+
nextAttemptAt: nextAttemptIso(options.now, options.retryDelayMs),
|
|
21
|
+
updatedAt: options.now
|
|
22
|
+
});
|
|
23
|
+
failed += 1;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
return Object.freeze({ processed: claimed.length, succeeded, failed });
|
|
27
|
+
}
|
package/dist/sqlite.js
CHANGED
|
@@ -89,6 +89,60 @@ class SqlitePersistenceStore {
|
|
|
89
89
|
const record = validateServiceRequestRecord(input);
|
|
90
90
|
this.#database.run("INSERT OR IGNORE INTO wats_service_requests (idempotency_key, request_hash, response_json, created_at) VALUES (?, ?, ?, ?)", record.idempotencyKey, record.requestHash, record.responseJson, record.createdAt);
|
|
91
91
|
}
|
|
92
|
+
async enqueueOutboxItem(input) {
|
|
93
|
+
this.#assertOpen();
|
|
94
|
+
const item = validateOutboxEnqueue(input);
|
|
95
|
+
try {
|
|
96
|
+
this.#database.run("INSERT INTO wats_outbox (id, status, attempts, next_attempt_at, payload_hash, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)", item.id, "pending", 0, item.nextAttemptAt, item.payloadHash, item.createdAt, item.createdAt);
|
|
97
|
+
return "enqueued";
|
|
98
|
+
} catch (cause) {
|
|
99
|
+
const message = cause instanceof Error ? cause.message : String(cause);
|
|
100
|
+
if (/UNIQUE|constraint/i.test(message))
|
|
101
|
+
return "duplicate";
|
|
102
|
+
throw new PersistenceError("outbox_failed", "SQLite outbox enqueue failed.", { cause });
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
async claimOutboxItems(input) {
|
|
106
|
+
this.#assertOpen();
|
|
107
|
+
const claim = validateOutboxClaim(input);
|
|
108
|
+
this.#database.exec("BEGIN IMMEDIATE");
|
|
109
|
+
try {
|
|
110
|
+
const leaseExpiredAt = subtractMillisecondsIso(claim.now, OUTBOX_PROCESSING_LEASE_MS);
|
|
111
|
+
const rows = this.#database.query(`SELECT id, status, attempts, lease_id, next_attempt_at, payload_hash, created_at, updated_at
|
|
112
|
+
FROM wats_outbox
|
|
113
|
+
WHERE (status = 'pending' AND (next_attempt_at IS NULL OR next_attempt_at <= ?))
|
|
114
|
+
OR (status = 'processing' AND updated_at <= ?)
|
|
115
|
+
ORDER BY created_at ASC, id ASC
|
|
116
|
+
LIMIT ?`).all(claim.now, leaseExpiredAt, claim.limit);
|
|
117
|
+
for (const row of rows) {
|
|
118
|
+
const result = this.#database.run("UPDATE wats_outbox SET status = ?, attempts = attempts + 1, lease_id = lease_id + 1, next_attempt_at = NULL, updated_at = ? WHERE id = ? AND status = ? AND lease_id = ?", "processing", claim.now, row.id, row.status, row.lease_id);
|
|
119
|
+
if (result.changes !== 1) {
|
|
120
|
+
throw new PersistenceError("outbox_failed", "SQLite outbox claim lease changed during claim.");
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
this.#database.exec("COMMIT");
|
|
124
|
+
return Object.freeze(rows.map((row) => outboxRowToItem({ ...row, status: "processing", attempts: row.attempts + 1, lease_id: row.lease_id + 1, next_attempt_at: null, updated_at: claim.now })));
|
|
125
|
+
} catch (cause) {
|
|
126
|
+
this.#database.exec("ROLLBACK");
|
|
127
|
+
throw new PersistenceError("outbox_failed", "SQLite outbox claim failed.", { cause });
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
async markOutboxItemFailed(input) {
|
|
131
|
+
this.#assertOpen();
|
|
132
|
+
const failure = validateOutboxFailed(input);
|
|
133
|
+
const result = this.#database.run("UPDATE wats_outbox SET status = ?, next_attempt_at = ?, updated_at = ? WHERE id = ? AND status = ? AND lease_id = ?", "pending", failure.nextAttemptAt, failure.updatedAt, failure.id, "processing", failure.leaseId);
|
|
134
|
+
if (result.changes !== 1) {
|
|
135
|
+
throw new PersistenceError("outbox_failed", "SQLite outbox failure lease is stale.");
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
async markOutboxItemSucceeded(input) {
|
|
139
|
+
this.#assertOpen();
|
|
140
|
+
const success = validateOutboxSucceeded(input);
|
|
141
|
+
const result = this.#database.run("UPDATE wats_outbox SET status = ?, next_attempt_at = NULL, updated_at = ? WHERE id = ? AND status = ? AND lease_id = ?", "succeeded", success.updatedAt, success.id, "processing", success.leaseId);
|
|
142
|
+
if (result.changes !== 1) {
|
|
143
|
+
throw new PersistenceError("outbox_failed", "SQLite outbox success lease is stale.");
|
|
144
|
+
}
|
|
145
|
+
}
|
|
92
146
|
async close() {
|
|
93
147
|
if (this.#closed)
|
|
94
148
|
return;
|
|
@@ -137,6 +191,7 @@ import {
|
|
|
137
191
|
const SQLITE_MEMORY = ":memory:";
|
|
138
192
|
const MAX_FILENAME_LENGTH = 4096;
|
|
139
193
|
const MIGRATION_LOCK_ID = 1;
|
|
194
|
+
const OUTBOX_PROCESSING_LEASE_MS = 300000;
|
|
140
195
|
const MIGRATIONS = Object.freeze([
|
|
141
196
|
{
|
|
142
197
|
id: "001_initial",
|
|
@@ -175,6 +230,14 @@ const MIGRATIONS = Object.freeze([
|
|
|
175
230
|
updated_at TEXT NOT NULL
|
|
176
231
|
)`
|
|
177
232
|
])
|
|
233
|
+
},
|
|
234
|
+
{
|
|
235
|
+
id: "002_outbox_lease_id",
|
|
236
|
+
version: 2,
|
|
237
|
+
checksum: "sha256:wats-persistence-002-outbox-lease-id-v1",
|
|
238
|
+
statements: Object.freeze([
|
|
239
|
+
"ALTER TABLE wats_outbox ADD COLUMN lease_id INTEGER NOT NULL DEFAULT 0"
|
|
240
|
+
])
|
|
178
241
|
}
|
|
179
242
|
]);
|
|
180
243
|
function hasControlChars(value) {
|
|
@@ -275,6 +338,69 @@ function validateServiceRequestRecord(input) {
|
|
|
275
338
|
createdAt: validateTimestamp(record.createdAt, "createdAt")
|
|
276
339
|
});
|
|
277
340
|
}
|
|
341
|
+
function validatePayloadHash(value) {
|
|
342
|
+
const raw = validateRecordString(value, "payloadHash");
|
|
343
|
+
if (!/^sha256:[a-f0-9]{64}$/u.test(raw)) {
|
|
344
|
+
throw new PersistenceError("invalid_record", "payloadHash must be a sha256 hex digest.");
|
|
345
|
+
}
|
|
346
|
+
return raw;
|
|
347
|
+
}
|
|
348
|
+
function validateOutboxEnqueue(input) {
|
|
349
|
+
const record = validateRecordInput(input, "outbox item");
|
|
350
|
+
const createdAt = validateTimestamp(record.createdAt, "createdAt");
|
|
351
|
+
const nextAttemptAt = record.nextAttemptAt === undefined || record.nextAttemptAt === null ? createdAt : validateTimestamp(record.nextAttemptAt, "nextAttemptAt");
|
|
352
|
+
return Object.freeze({
|
|
353
|
+
id: validateRecordString(record.id, "id"),
|
|
354
|
+
payloadHash: validatePayloadHash(record.payloadHash),
|
|
355
|
+
createdAt,
|
|
356
|
+
nextAttemptAt
|
|
357
|
+
});
|
|
358
|
+
}
|
|
359
|
+
function validateOutboxClaim(input) {
|
|
360
|
+
const record = validateRecordInput(input, "outbox claim");
|
|
361
|
+
if (typeof record.limit !== "number" || !Number.isInteger(record.limit) || record.limit < 1 || record.limit > 100) {
|
|
362
|
+
throw new PersistenceError("invalid_record", "limit must be an integer from 1 to 100.");
|
|
363
|
+
}
|
|
364
|
+
return Object.freeze({ now: validateTimestamp(record.now, "now"), limit: record.limit });
|
|
365
|
+
}
|
|
366
|
+
function validateLeaseId(value) {
|
|
367
|
+
if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > Number.MAX_SAFE_INTEGER) {
|
|
368
|
+
throw new PersistenceError("invalid_record", "leaseId must be a positive safe integer.");
|
|
369
|
+
}
|
|
370
|
+
return value;
|
|
371
|
+
}
|
|
372
|
+
function validateOutboxFailed(input) {
|
|
373
|
+
const record = validateRecordInput(input, "outbox failure");
|
|
374
|
+
return Object.freeze({
|
|
375
|
+
id: validateRecordString(record.id, "id"),
|
|
376
|
+
leaseId: validateLeaseId(record.leaseId),
|
|
377
|
+
nextAttemptAt: validateTimestamp(record.nextAttemptAt, "nextAttemptAt"),
|
|
378
|
+
updatedAt: validateTimestamp(record.updatedAt, "updatedAt")
|
|
379
|
+
});
|
|
380
|
+
}
|
|
381
|
+
function validateOutboxSucceeded(input) {
|
|
382
|
+
const record = validateRecordInput(input, "outbox success");
|
|
383
|
+
return Object.freeze({
|
|
384
|
+
id: validateRecordString(record.id, "id"),
|
|
385
|
+
leaseId: validateLeaseId(record.leaseId),
|
|
386
|
+
updatedAt: validateTimestamp(record.updatedAt, "updatedAt")
|
|
387
|
+
});
|
|
388
|
+
}
|
|
389
|
+
function outboxRowToItem(row) {
|
|
390
|
+
return Object.freeze({
|
|
391
|
+
id: row.id,
|
|
392
|
+
status: row.status,
|
|
393
|
+
attempts: row.attempts,
|
|
394
|
+
leaseId: row.lease_id,
|
|
395
|
+
payloadHash: row.payload_hash,
|
|
396
|
+
nextAttemptAt: row.next_attempt_at,
|
|
397
|
+
createdAt: row.created_at,
|
|
398
|
+
updatedAt: row.updated_at
|
|
399
|
+
});
|
|
400
|
+
}
|
|
401
|
+
function subtractMillisecondsIso(timestamp, milliseconds) {
|
|
402
|
+
return new Date(new Date(timestamp).getTime() - milliseconds).toISOString();
|
|
403
|
+
}
|
|
278
404
|
function nowIso() {
|
|
279
405
|
return new Date().toISOString();
|
|
280
406
|
}
|