@backendkit-labs/agent-flow-sql 0.0.0-stage → 0.1.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/README.md +82 -3
- package/dist/client.d.ts +47 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +56 -0
- package/dist/client.js.map +1 -0
- package/dist/index.d.ts +9 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +14 -0
- package/dist/index.js.map +1 -0
- package/dist/postgres.d.ts +49 -0
- package/dist/postgres.d.ts.map +1 -0
- package/dist/postgres.js +91 -0
- package/dist/postgres.js.map +1 -0
- package/dist/sql-run-journal.d.ts +56 -0
- package/dist/sql-run-journal.d.ts.map +1 -0
- package/dist/sql-run-journal.js +198 -0
- package/dist/sql-run-journal.js.map +1 -0
- package/dist/sqlite.d.ts +22 -0
- package/dist/sqlite.d.ts.map +1 -0
- package/dist/sqlite.js +26 -0
- package/dist/sqlite.js.map +1 -0
- package/package.json +46 -4
package/README.md
CHANGED
|
@@ -1,3 +1,82 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# @backendkit-labs/agent-flow-sql
|
|
2
|
+
|
|
3
|
+
A `RunJournal` on SQL for the flows of [`@backendkit-labs/agent-core`](https://www.npmjs.com/package/@backendkit-labs/agent-core): the runs of a flow survive the process, and any process that shares the database can resume them. **SQLite and Postgres** ([SPEC-0028](../../docs/specs/SPEC-0028-journals-en-sqlite-y-postgres.md)).
|
|
4
|
+
|
|
5
|
+
Use it when you want one file and no service (SQLite), or the database you already run (Postgres). For one process that must not lose a run, `NdjsonRunJournal` in core is enough; this package is for runs that several processes or a restarted process share.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @backendkit-labs/agent-flow-sql @backendkit-labs/agent-core
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Node 22.13 or newer (`engines`). There is no driver dependency: you give it an open handle, `node:sqlite` (built in) or `better-sqlite3` (any handle with `prepare(sql).all/run` and `exec`).
|
|
14
|
+
|
|
15
|
+
## Use
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { DatabaseSync } from 'node:sqlite';
|
|
19
|
+
import { runFlow, loadFlow } from '@backendkit-labs/agent-core';
|
|
20
|
+
import { SqliteRunJournal } from '@backendkit-labs/agent-flow-sql';
|
|
21
|
+
|
|
22
|
+
const journal = new SqliteRunJournal(new DatabaseSync('./flows.db'));
|
|
23
|
+
await journal.migrate(); // creates the tables if they do not exist; safe on every start
|
|
24
|
+
|
|
25
|
+
await runFlow(await loadFlow('./flows/invoices.yaml'), { journal, runId: 'invoices-2026-11', executor });
|
|
26
|
+
// after a crash or a deploy: the same call resumes; steps that are done are not run again
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Postgres
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
import { Pool } from 'pg';
|
|
33
|
+
import { PostgresRunJournal } from '@backendkit-labs/agent-flow-sql';
|
|
34
|
+
|
|
35
|
+
const journal = new PostgresRunJournal(new Pool({ connectionString }), { schema: 'flows' });
|
|
36
|
+
await journal.migrate(); // CREATE SCHEMA and the tables, if they do not exist
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
It takes a `pg.Pool` (anything with `query` and `connect`; `pg` is not a dependency of this package). Each transaction uses its own connection from the pool, so the transactions of one process run in parallel and Postgres keeps them apart. `schema` is optional.
|
|
40
|
+
|
|
41
|
+
**Tested with** Postgres 15, 16, 17 and 18; behind pgbouncer 1.22 in `transaction` mode (a transaction keeps its server connection from `BEGIN` to `COMMIT`, which is all it needs); and over SSL with `sslmode=verify-full`. Postgres 14 and older are untested.
|
|
42
|
+
|
|
43
|
+
**Another driver** needs a `SqlClient`: `query` and `transaction`, with `?` placeholders (`toPositional` converts them). This one, for [`postgres`](https://www.npmjs.com/package/postgres) (postgres.js), passes the whole journal battery:
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
import postgres from 'postgres';
|
|
47
|
+
import { SqlRunJournal, toPositional } from '@backendkit-labs/agent-flow-sql';
|
|
48
|
+
import type { SqlClient } from '@backendkit-labs/agent-flow-sql';
|
|
49
|
+
|
|
50
|
+
function postgresJsClient(sql: postgres.Sql): SqlClient {
|
|
51
|
+
const run = async (q: postgres.Sql, text: string, params: readonly unknown[] = []) => {
|
|
52
|
+
const res = await q.unsafe(toPositional(text), params.map(p => (p === undefined ? null : p)) as never[]);
|
|
53
|
+
return { rows: Array.from(res) as Array<Record<string, unknown>>, rowCount: res.count ?? res.length };
|
|
54
|
+
};
|
|
55
|
+
return {
|
|
56
|
+
query: (text, params) => run(sql, text, params),
|
|
57
|
+
transaction: fn => sql.begin(tx => fn({ query: (text, params) => run(tx as never, text, params) })) as never,
|
|
58
|
+
};
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
const journal = new SqlRunJournal(postgresJsClient(postgres(url)), { schema: 'flows' });
|
|
62
|
+
await journal.migrate(); // with a schema, create it first: CREATE SCHEMA IF NOT EXISTS flows
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`migrate()` is explicit: the journal never creates tables by itself. `journal.ddl()` returns the statements if you apply migrations with your own tool, and `tablePrefix` (default `flow_`) keeps several journals in one database apart.
|
|
66
|
+
|
|
67
|
+
## What it guarantees
|
|
68
|
+
|
|
69
|
+
- **A run is a log of events**, the same as the file, ndjson and Redis journals: `get` folds it, so what a run is does not depend on where it is kept.
|
|
70
|
+
- **One owner per run** (`claim`, with expiry). Of several processes racing for a run, one wins; the others get `FlowClaimError` from `runFlow`.
|
|
71
|
+
- **One writer per run.** If another journal object wrote to a run after yours did, your next write fails with `JournalConflict` and the flow stops: the run is no longer yours. A write that was acknowledged is never lost.
|
|
72
|
+
- **`list` is oldest first** and filters by status, flow and tenant through an index that is updated in the same transaction as the event.
|
|
73
|
+
- It passes the shared journal battery of core (`@backendkit-labs/agent-core/testing`), and it is tested with real processes over one file.
|
|
74
|
+
|
|
75
|
+
## Notes
|
|
76
|
+
|
|
77
|
+
- **`node:sqlite` is still marked as under development in Node.** The package only needs the small `prepare` / `exec` interface, so a `better-sqlite3` handle works the same way: the journal passes its tests over both, with `better-sqlite3` 12.11 and 13.2.
|
|
78
|
+
- **Transactions of one process are serialized.** A synchronous SQLite driver blocks the thread while it waits for another connection's lock, and a transaction suspended at an `await` would never release it; so every transaction of the process goes through one queue. Other processes wait in SQLite's own lock (`busyTimeoutMs`, default 5000) and are not affected.
|
|
79
|
+
- **The claim expires by the clock of the process that takes it**, in both databases. Keep the TTL well above the clock difference between your processes; a running flow renews its claim every third of the TTL.
|
|
80
|
+
- **WAL is on by default** (`wal: false` to turn it off), so readers do not wait for the writer.
|
|
81
|
+
- **Retention is yours.** The journal keeps every run; delete finished ones with your own job (`DELETE` from the three tables by `run_id`).
|
|
82
|
+
- The payload of a run is not stored, only a cut and masked preview (`redact` in `runFlow`): pass it again when you resume.
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The smallest SQL client the journal needs. It is injected, so the package imposes no driver and no driver version: a
|
|
3
|
+
* driver is wrapped in a few lines (`sqliteClient` below for SQLite; the Postgres client of SPEC-0028 F2 for `pg`).
|
|
4
|
+
*
|
|
5
|
+
* Statements are written with `?` placeholders. A client for a database that uses another style (`$1` in Postgres)
|
|
6
|
+
* converts them.
|
|
7
|
+
*/
|
|
8
|
+
export interface SqlRows {
|
|
9
|
+
/** Rows of a statement that returns them (`SELECT`); empty otherwise. */
|
|
10
|
+
rows: Array<Record<string, unknown>>;
|
|
11
|
+
/** Rows returned by a `SELECT`, or rows changed by an `INSERT`, `UPDATE` or `DELETE` (including an upsert that took effect). */
|
|
12
|
+
rowCount: number;
|
|
13
|
+
}
|
|
14
|
+
export interface SqlQueryable {
|
|
15
|
+
query(sql: string, params?: readonly unknown[]): Promise<SqlRows>;
|
|
16
|
+
}
|
|
17
|
+
export interface SqlClient extends SqlQueryable {
|
|
18
|
+
/**
|
|
19
|
+
* Runs `fn` in one transaction: committed if it resolves, rolled back if it throws. Two transactions of the same client
|
|
20
|
+
* never interleave their statements.
|
|
21
|
+
*/
|
|
22
|
+
transaction<T>(fn: (tx: SqlQueryable) => Promise<T>): Promise<T>;
|
|
23
|
+
}
|
|
24
|
+
/** What a synchronous SQLite handle must offer. `node:sqlite` (`DatabaseSync`) and `better-sqlite3` both do. */
|
|
25
|
+
export interface SyncSqliteStatement {
|
|
26
|
+
all(...params: unknown[]): unknown[];
|
|
27
|
+
run(...params: unknown[]): {
|
|
28
|
+
changes: number | bigint;
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
export interface SyncSqliteDb {
|
|
32
|
+
prepare(sql: string): SyncSqliteStatement;
|
|
33
|
+
exec(sql: string): void;
|
|
34
|
+
}
|
|
35
|
+
export interface SqliteClientOptions {
|
|
36
|
+
/** How long a statement waits for another connection's lock before failing. Default 5000 ms. */
|
|
37
|
+
busyTimeoutMs?: number;
|
|
38
|
+
/** Use the write-ahead log, which lets readers and a writer work at the same time. Default true; ignored by an in-memory database. */
|
|
39
|
+
wal?: boolean;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* A `SqlClient` over a synchronous SQLite handle (`new DatabaseSync(file)` from `node:sqlite`, or a `better-sqlite3`
|
|
43
|
+
* `Database`). Statements and transactions of this process run one at a time (see `queue`); connections of other processes to the
|
|
44
|
+
* same file are kept apart by SQLite's own lock, with `busyTimeoutMs` to wait for it.
|
|
45
|
+
*/
|
|
46
|
+
export declare function sqliteClient(db: SyncSqliteDb, opts?: SqliteClientOptions): SqlClient;
|
|
47
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACpB,yEAAyE;IACzE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrC,gIAAgI;IAChI,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IACzB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,SAAU,SAAQ,YAAY;IAC3C;;;OAGG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACpE;AAED,gHAAgH;AAChH,MAAM,WAAW,mBAAmB;IAChC,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAC;IACrC,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG;QAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CAC3D;AAED,MAAM,WAAW,YAAY;IACzB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAAC;IAC1C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAChC,gGAAgG;IAChG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sIAAsI;IACtI,GAAG,CAAC,EAAE,OAAO,CAAC;CACjB;AAkBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,GAAE,mBAAwB,GAAG,SAAS,CA6BxF"}
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.sqliteClient = sqliteClient;
|
|
4
|
+
/**
|
|
5
|
+
* One queue for every SQLite client of the process, not one per client. A synchronous driver blocks the thread while it waits for
|
|
6
|
+
* another connection's lock, and a transaction that is suspended at an `await` holds its lock without being able to run: a second
|
|
7
|
+
* connection of the same process that waited for it would wait for ever (`database is locked` after the busy timeout). With one
|
|
8
|
+
* queue, transactions of this process never overlap, whatever connection they use. Another PROCESS is not affected: it waits in
|
|
9
|
+
* SQLite's own lock while this one carries on.
|
|
10
|
+
*/
|
|
11
|
+
let queue = Promise.resolve();
|
|
12
|
+
function exclusive(fn) {
|
|
13
|
+
const next = queue.then(fn, fn);
|
|
14
|
+
queue = next.catch(() => undefined);
|
|
15
|
+
return next;
|
|
16
|
+
}
|
|
17
|
+
const RETURNS_ROWS = /^\s*(select|with|pragma)\b|\breturning\b/i;
|
|
18
|
+
/**
|
|
19
|
+
* A `SqlClient` over a synchronous SQLite handle (`new DatabaseSync(file)` from `node:sqlite`, or a `better-sqlite3`
|
|
20
|
+
* `Database`). Statements and transactions of this process run one at a time (see `queue`); connections of other processes to the
|
|
21
|
+
* same file are kept apart by SQLite's own lock, with `busyTimeoutMs` to wait for it.
|
|
22
|
+
*/
|
|
23
|
+
function sqliteClient(db, opts = {}) {
|
|
24
|
+
db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(opts.busyTimeoutMs ?? 5000))}`);
|
|
25
|
+
if (opts.wal ?? true)
|
|
26
|
+
db.exec('PRAGMA journal_mode = WAL');
|
|
27
|
+
const run = (sql, params = []) => {
|
|
28
|
+
const bound = params.map(p => (p === undefined ? null : p));
|
|
29
|
+
const stmt = db.prepare(sql);
|
|
30
|
+
if (RETURNS_ROWS.test(sql)) {
|
|
31
|
+
const rows = stmt.all(...bound);
|
|
32
|
+
return { rows, rowCount: rows.length };
|
|
33
|
+
}
|
|
34
|
+
return { rows: [], rowCount: Number(stmt.run(...bound).changes) };
|
|
35
|
+
};
|
|
36
|
+
return {
|
|
37
|
+
query: (sql, params) => exclusive(() => run(sql, params)),
|
|
38
|
+
transaction: (fn) => exclusive(async () => {
|
|
39
|
+
// IMMEDIATE takes the write lock at once: a transaction that will write must not discover it cannot half way through.
|
|
40
|
+
db.exec('BEGIN IMMEDIATE');
|
|
41
|
+
try {
|
|
42
|
+
const result = await fn({ query: async (sql, params) => run(sql, params) });
|
|
43
|
+
db.exec('COMMIT');
|
|
44
|
+
return result;
|
|
45
|
+
}
|
|
46
|
+
catch (err) {
|
|
47
|
+
try {
|
|
48
|
+
db.exec('ROLLBACK');
|
|
49
|
+
}
|
|
50
|
+
catch { /* the transaction is already gone */ }
|
|
51
|
+
throw err;
|
|
52
|
+
}
|
|
53
|
+
}),
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
//# sourceMappingURL=client.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;AAiEA,oCA6BC;AAlDD;;;;;;GAMG;AACH,IAAI,KAAK,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;AAChD,SAAS,SAAS,CAAI,EAAwB;IAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAChC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACpC,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,MAAM,YAAY,GAAG,2CAA2C,CAAC;AAEjE;;;;GAIG;AACH,SAAgB,YAAY,CAAC,EAAgB,EAAE,OAA4B,EAAE;IACzE,EAAE,CAAC,IAAI,CAAC,yBAAyB,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IACxF,IAAI,IAAI,CAAC,GAAG,IAAI,IAAI;QAAE,EAAE,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IAE3D,MAAM,GAAG,GAAG,CAAC,GAAW,EAAE,SAA6B,EAAE,EAAW,EAAE;QAClE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAmC,CAAC;YAClE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;QAC3C,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACtE,CAAC,CAAC;IAEF,OAAO;QACH,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACzD,WAAW,EAAE,CAAI,EAAoC,EAAc,EAAE,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE;YACvF,sHAAsH;YACtH,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YAC3B,IAAI,CAAC;gBACD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;gBAC5E,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBAClB,OAAO,MAAM,CAAC;YAClB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,IAAI,CAAC;oBAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,qCAAqC,CAAC,CAAC;gBAC5E,MAAM,GAAG,CAAC;YACd,CAAC;QACL,CAAC,CAAC;KACL,CAAC;AACN,CAAC"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
export { SqlRunJournal } from './sql-run-journal';
|
|
2
|
+
export type { SqlRunJournalOptions } from './sql-run-journal';
|
|
3
|
+
export { SqliteRunJournal } from './sqlite';
|
|
4
|
+
export type { SqliteRunJournalOptions } from './sqlite';
|
|
5
|
+
export { sqliteClient } from './client';
|
|
6
|
+
export type { SqlClient, SqlQueryable, SqlRows, SyncSqliteDb, SyncSqliteStatement, SqliteClientOptions } from './client';
|
|
7
|
+
export { PostgresRunJournal, pgClient, toPositional } from './postgres';
|
|
8
|
+
export type { PgPoolLike, PgPoolClient, PgQueryable, PgQueryResult } from './postgres';
|
|
9
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC5C,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACzH,OAAO,EAAE,kBAAkB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACxE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.toPositional = exports.pgClient = exports.PostgresRunJournal = exports.sqliteClient = exports.SqliteRunJournal = exports.SqlRunJournal = void 0;
|
|
4
|
+
var sql_run_journal_1 = require("./sql-run-journal");
|
|
5
|
+
Object.defineProperty(exports, "SqlRunJournal", { enumerable: true, get: function () { return sql_run_journal_1.SqlRunJournal; } });
|
|
6
|
+
var sqlite_1 = require("./sqlite");
|
|
7
|
+
Object.defineProperty(exports, "SqliteRunJournal", { enumerable: true, get: function () { return sqlite_1.SqliteRunJournal; } });
|
|
8
|
+
var client_1 = require("./client");
|
|
9
|
+
Object.defineProperty(exports, "sqliteClient", { enumerable: true, get: function () { return client_1.sqliteClient; } });
|
|
10
|
+
var postgres_1 = require("./postgres");
|
|
11
|
+
Object.defineProperty(exports, "PostgresRunJournal", { enumerable: true, get: function () { return postgres_1.PostgresRunJournal; } });
|
|
12
|
+
Object.defineProperty(exports, "pgClient", { enumerable: true, get: function () { return postgres_1.pgClient; } });
|
|
13
|
+
Object.defineProperty(exports, "toPositional", { enumerable: true, get: function () { return postgres_1.toPositional; } });
|
|
14
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qDAAkD;AAAzC,gHAAA,aAAa,OAAA;AAEtB,mCAA4C;AAAnC,0GAAA,gBAAgB,OAAA;AAEzB,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AAErB,uCAAwE;AAA/D,8GAAA,kBAAkB,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,wGAAA,YAAY,OAAA"}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { SqlRunJournal } from './sql-run-journal';
|
|
2
|
+
import type { SqlRunJournalOptions } from './sql-run-journal';
|
|
3
|
+
import type { SqlClient } from './client';
|
|
4
|
+
/** What `pg` returns from a query. `rowCount` is null for statements that have no count (DDL). */
|
|
5
|
+
export interface PgQueryResult {
|
|
6
|
+
rows: Array<Record<string, unknown>>;
|
|
7
|
+
rowCount: number | null;
|
|
8
|
+
}
|
|
9
|
+
export interface PgQueryable {
|
|
10
|
+
query(text: string, values?: unknown[]): Promise<PgQueryResult>;
|
|
11
|
+
}
|
|
12
|
+
/** A client checked out of a pool. `release(true)` throws the connection away instead of returning it. */
|
|
13
|
+
export interface PgPoolClient extends PgQueryable {
|
|
14
|
+
release(destroy?: boolean | Error): void;
|
|
15
|
+
}
|
|
16
|
+
/** The part of `pg.Pool` the journal uses. A `pg.Pool` satisfies it as it is. */
|
|
17
|
+
export interface PgPoolLike extends PgQueryable {
|
|
18
|
+
connect(): Promise<PgPoolClient>;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* `?` placeholders to `$1, $2...`. A `?` inside a single-quoted literal is text, not a parameter. The journal writes no `?` inside
|
|
22
|
+
* a literal and no operator that uses one, so this is all the conversion it needs.
|
|
23
|
+
*/
|
|
24
|
+
export declare function toPositional(sql: string): string;
|
|
25
|
+
/**
|
|
26
|
+
* A `SqlClient` over a `pg.Pool` (or anything shaped like one). A transaction takes its own connection from the pool, so
|
|
27
|
+
* transactions of one process run in parallel and Postgres keeps them apart; unlike SQLite there is no process-wide queue.
|
|
28
|
+
*/
|
|
29
|
+
export declare function pgClient(pool: PgPoolLike): SqlClient;
|
|
30
|
+
/**
|
|
31
|
+
* `RunJournal` on Postgres (SPEC-0028 F2): the runs live in the database you already run, and any process that shares it can resume
|
|
32
|
+
* them. Give it a `pg.Pool` and call `migrate()` once.
|
|
33
|
+
*
|
|
34
|
+
* ```ts
|
|
35
|
+
* import { Pool } from 'pg';
|
|
36
|
+
* const journal = new PostgresRunJournal(new Pool({ connectionString }), { schema: 'flows' });
|
|
37
|
+
* await journal.migrate();
|
|
38
|
+
* await runFlow(def, { journal, runId, executor });
|
|
39
|
+
* ```
|
|
40
|
+
*
|
|
41
|
+
* The claim expires by the clock of the process that takes it (as in the SQLite journal): keep the TTL well above the clock
|
|
42
|
+
* difference between your processes. The pool is yours; the journal never closes it.
|
|
43
|
+
*/
|
|
44
|
+
export declare class PostgresRunJournal extends SqlRunJournal {
|
|
45
|
+
constructor(pool: PgPoolLike, opts?: SqlRunJournalOptions);
|
|
46
|
+
/** As the base, plus `CREATE SCHEMA IF NOT EXISTS` when a schema was given. */
|
|
47
|
+
ddl(): string[];
|
|
48
|
+
}
|
|
49
|
+
//# sourceMappingURL=postgres.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAyB,MAAM,UAAU,CAAC;AAEjE,kGAAkG;AAClG,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACnE;AAED,0GAA0G;AAC1G,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC7C,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAAC;CAC5C;AAED,iFAAiF;AACjF,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC3C,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAchD;AAKD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,CAsBpD;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACrC,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE,oBAAyB;IAI7D,+EAA+E;IACtE,GAAG,IAAI,MAAM,EAAE;CAI3B"}
|
package/dist/postgres.js
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.PostgresRunJournal = void 0;
|
|
4
|
+
exports.toPositional = toPositional;
|
|
5
|
+
exports.pgClient = pgClient;
|
|
6
|
+
const sql_run_journal_1 = require("./sql-run-journal");
|
|
7
|
+
/**
|
|
8
|
+
* `?` placeholders to `$1, $2...`. A `?` inside a single-quoted literal is text, not a parameter. The journal writes no `?` inside
|
|
9
|
+
* a literal and no operator that uses one, so this is all the conversion it needs.
|
|
10
|
+
*/
|
|
11
|
+
function toPositional(sql) {
|
|
12
|
+
let n = 0;
|
|
13
|
+
let out = '';
|
|
14
|
+
let inLiteral = false;
|
|
15
|
+
for (let i = 0; i < sql.length; i++) {
|
|
16
|
+
const ch = sql[i];
|
|
17
|
+
if (ch === "'") {
|
|
18
|
+
// `''` inside a literal is an escaped quote: stay inside.
|
|
19
|
+
if (inLiteral && sql[i + 1] === "'") {
|
|
20
|
+
out += "''";
|
|
21
|
+
i++;
|
|
22
|
+
continue;
|
|
23
|
+
}
|
|
24
|
+
inLiteral = !inLiteral;
|
|
25
|
+
}
|
|
26
|
+
out += ch === '?' && !inLiteral ? `$${++n}` : ch;
|
|
27
|
+
}
|
|
28
|
+
return out;
|
|
29
|
+
}
|
|
30
|
+
const rows = (r) => ({ rows: r.rows, rowCount: r.rowCount ?? r.rows.length });
|
|
31
|
+
const bind = (params) => params?.map(p => (p === undefined ? null : p));
|
|
32
|
+
/**
|
|
33
|
+
* A `SqlClient` over a `pg.Pool` (or anything shaped like one). A transaction takes its own connection from the pool, so
|
|
34
|
+
* transactions of one process run in parallel and Postgres keeps them apart; unlike SQLite there is no process-wide queue.
|
|
35
|
+
*/
|
|
36
|
+
function pgClient(pool) {
|
|
37
|
+
const on = (q) => ({
|
|
38
|
+
query: async (sql, params) => rows(await q.query(toPositional(sql), bind(params))),
|
|
39
|
+
});
|
|
40
|
+
return {
|
|
41
|
+
...on(pool),
|
|
42
|
+
transaction: async (fn) => {
|
|
43
|
+
const conn = await pool.connect();
|
|
44
|
+
let broken = false;
|
|
45
|
+
try {
|
|
46
|
+
await conn.query('BEGIN');
|
|
47
|
+
const result = await fn(on(conn));
|
|
48
|
+
await conn.query('COMMIT');
|
|
49
|
+
return result;
|
|
50
|
+
}
|
|
51
|
+
catch (err) {
|
|
52
|
+
try {
|
|
53
|
+
await conn.query('ROLLBACK');
|
|
54
|
+
}
|
|
55
|
+
catch {
|
|
56
|
+
broken = true;
|
|
57
|
+
} // a connection that cannot roll back is not reused
|
|
58
|
+
throw err;
|
|
59
|
+
}
|
|
60
|
+
finally {
|
|
61
|
+
conn.release(broken);
|
|
62
|
+
}
|
|
63
|
+
},
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* `RunJournal` on Postgres (SPEC-0028 F2): the runs live in the database you already run, and any process that shares it can resume
|
|
68
|
+
* them. Give it a `pg.Pool` and call `migrate()` once.
|
|
69
|
+
*
|
|
70
|
+
* ```ts
|
|
71
|
+
* import { Pool } from 'pg';
|
|
72
|
+
* const journal = new PostgresRunJournal(new Pool({ connectionString }), { schema: 'flows' });
|
|
73
|
+
* await journal.migrate();
|
|
74
|
+
* await runFlow(def, { journal, runId, executor });
|
|
75
|
+
* ```
|
|
76
|
+
*
|
|
77
|
+
* The claim expires by the clock of the process that takes it (as in the SQLite journal): keep the TTL well above the clock
|
|
78
|
+
* difference between your processes. The pool is yours; the journal never closes it.
|
|
79
|
+
*/
|
|
80
|
+
class PostgresRunJournal extends sql_run_journal_1.SqlRunJournal {
|
|
81
|
+
constructor(pool, opts = {}) {
|
|
82
|
+
super(pgClient(pool), opts);
|
|
83
|
+
}
|
|
84
|
+
/** As the base, plus `CREATE SCHEMA IF NOT EXISTS` when a schema was given. */
|
|
85
|
+
ddl() {
|
|
86
|
+
const statements = super.ddl();
|
|
87
|
+
return this.schema ? [`CREATE SCHEMA IF NOT EXISTS ${this.schema}`, ...statements] : statements;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
exports.PostgresRunJournal = PostgresRunJournal;
|
|
91
|
+
//# sourceMappingURL=postgres.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import type { JournalRun, JournalRunStatus, NewJournalRun, RunJournal, RunPatch, StepPatch } from '@backendkit-labs/agent-core';
|
|
2
|
+
import type { SqlClient } from './client';
|
|
3
|
+
/**
|
|
4
|
+
* `RunJournal` on SQL (SPEC-0028). The state of a run is the fold of an append-only event log, as in the file, ndjson and Redis
|
|
5
|
+
* journals, so what a run is does not depend on where it is kept.
|
|
6
|
+
*
|
|
7
|
+
* - `<prefix>run_events(run_id, seq, recorded_at, kind, payload)`: the log. `(run_id, seq)` is the key, which is what makes a second
|
|
8
|
+
* writer visible (see below).
|
|
9
|
+
* - `<prefix>runs(run_id, flow, tenant_id, status, started_at, updated_at)`: an index for `list`, written in the same
|
|
10
|
+
* transaction as the event that changes it.
|
|
11
|
+
* - `<prefix>run_claims(run_id, owner, token, expires_at)`: one owner per run, with expiry.
|
|
12
|
+
*
|
|
13
|
+
* **One writer per run.** A journal object remembers the sequence number of the last event it wrote for a run. If another
|
|
14
|
+
* object wrote in between, the next insert collides on `(run_id, seq)` and fails with `JournalConflict`: the run is no longer
|
|
15
|
+
* the caller's, and `runFlow` stops (SPEC-0024). An acknowledged write is never lost.
|
|
16
|
+
*
|
|
17
|
+
* It works on any database whose `SqlClient` runs `INSERT ... ON CONFLICT DO NOTHING / DO UPDATE ... WHERE`.
|
|
18
|
+
*/
|
|
19
|
+
export interface SqlRunJournalOptions {
|
|
20
|
+
/** Prefix of the three table names. Letters, digits and `_`, starting with a letter or `_`. Default `flow_`. */
|
|
21
|
+
tablePrefix?: string;
|
|
22
|
+
/** Schema that holds the tables (`flows` makes `flows.flow_runs`). Same character rules as the prefix. Default: the connection's own. */
|
|
23
|
+
schema?: string;
|
|
24
|
+
}
|
|
25
|
+
export declare class SqlRunJournal implements RunJournal {
|
|
26
|
+
protected readonly client: SqlClient;
|
|
27
|
+
protected readonly events: string;
|
|
28
|
+
protected readonly runs: string;
|
|
29
|
+
protected readonly claims: string;
|
|
30
|
+
protected readonly schema: string | undefined;
|
|
31
|
+
/** Index names are not schema-qualified: an index lives in the schema of its table. */
|
|
32
|
+
private readonly indexPrefix;
|
|
33
|
+
/** The sequence number of the last event this object wrote or saw written by itself, per run. */
|
|
34
|
+
private readonly tails;
|
|
35
|
+
/** Writes of one run, one after another: an object's own concurrent writes must not collide with each other. */
|
|
36
|
+
private readonly chains;
|
|
37
|
+
constructor(client: SqlClient, opts?: SqlRunJournalOptions);
|
|
38
|
+
/** Creates the tables and indexes if they do not exist. Safe to call on every start. The journal never creates them by itself. */
|
|
39
|
+
migrate(): Promise<void>;
|
|
40
|
+
/** The statements `migrate` runs, for an integrator who applies migrations with their own tool. */
|
|
41
|
+
ddl(): string[];
|
|
42
|
+
begin(run: NewJournalRun): Promise<void>;
|
|
43
|
+
step(runId: string, stepId: string, patch: StepPatch): Promise<void>;
|
|
44
|
+
update(runId: string, patch: RunPatch): Promise<void>;
|
|
45
|
+
claim(runId: string, owner: string, ttlMs: number): Promise<(() => Promise<void>) | null>;
|
|
46
|
+
get(runId: string): Promise<JournalRun | undefined>;
|
|
47
|
+
list(filter?: {
|
|
48
|
+
status?: JournalRunStatus[];
|
|
49
|
+
flow?: string;
|
|
50
|
+
tenantId?: string;
|
|
51
|
+
}): Promise<JournalRun[]>;
|
|
52
|
+
private append;
|
|
53
|
+
private serial;
|
|
54
|
+
private checkId;
|
|
55
|
+
}
|
|
56
|
+
//# sourceMappingURL=sql-run-journal.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sql-run-journal.d.ts","sourceRoot":"","sources":["../src/sql-run-journal.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACM,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAC7F,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,oBAAoB;IACjC,gHAAgH;IAChH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yIAAyI;IACzI,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD,qBAAa,aAAc,YAAW,UAAU;IAYhC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS;IAXhD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAChC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,iGAAiG;IACjG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,gHAAgH;IAChH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAE/B,MAAM,EAAE,SAAS,EAAE,IAAI,GAAE,oBAAyB;IAajF,kIAAkI;IAC5H,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B,mGAAmG;IACnG,GAAG,IAAI,MAAM,EAAE;IA8BT,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBxC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;IAkBzF,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAOnD,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;YA6B/F,MAAM;IAkCpB,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,OAAO;CAGlB"}
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.SqlRunJournal = void 0;
|
|
4
|
+
const node_crypto_1 = require("node:crypto");
|
|
5
|
+
const agent_core_1 = require("@backendkit-labs/agent-core");
|
|
6
|
+
const ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
|
|
7
|
+
const PREFIX = /^[A-Za-z_][A-Za-z0-9_]{0,40}$/;
|
|
8
|
+
const SCHEMA = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
|
|
9
|
+
class SqlRunJournal {
|
|
10
|
+
client;
|
|
11
|
+
events;
|
|
12
|
+
runs;
|
|
13
|
+
claims;
|
|
14
|
+
schema;
|
|
15
|
+
/** Index names are not schema-qualified: an index lives in the schema of its table. */
|
|
16
|
+
indexPrefix;
|
|
17
|
+
/** The sequence number of the last event this object wrote or saw written by itself, per run. */
|
|
18
|
+
tails = new Map();
|
|
19
|
+
/** Writes of one run, one after another: an object's own concurrent writes must not collide with each other. */
|
|
20
|
+
chains = new Map();
|
|
21
|
+
constructor(client, opts = {}) {
|
|
22
|
+
this.client = client;
|
|
23
|
+
const prefix = opts.tablePrefix ?? 'flow_';
|
|
24
|
+
// A table name cannot be a bound parameter, so the prefix is checked, never escaped.
|
|
25
|
+
if (!PREFIX.test(prefix))
|
|
26
|
+
throw new Error(`invalid table prefix "${prefix}"`);
|
|
27
|
+
if (opts.schema !== undefined && !SCHEMA.test(opts.schema))
|
|
28
|
+
throw new Error(`invalid schema "${opts.schema}"`);
|
|
29
|
+
this.schema = opts.schema;
|
|
30
|
+
const table = (name) => (opts.schema ? `${opts.schema}.${prefix}${name}` : `${prefix}${name}`);
|
|
31
|
+
this.events = table('run_events');
|
|
32
|
+
this.runs = table('runs');
|
|
33
|
+
this.claims = table('run_claims');
|
|
34
|
+
this.indexPrefix = `${prefix}runs`;
|
|
35
|
+
}
|
|
36
|
+
/** Creates the tables and indexes if they do not exist. Safe to call on every start. The journal never creates them by itself. */
|
|
37
|
+
async migrate() {
|
|
38
|
+
await this.client.transaction(async (tx) => {
|
|
39
|
+
for (const sql of this.ddl())
|
|
40
|
+
await tx.query(sql);
|
|
41
|
+
});
|
|
42
|
+
}
|
|
43
|
+
/** The statements `migrate` runs, for an integrator who applies migrations with their own tool. */
|
|
44
|
+
ddl() {
|
|
45
|
+
return [
|
|
46
|
+
`CREATE TABLE IF NOT EXISTS ${this.events} (
|
|
47
|
+
run_id TEXT NOT NULL,
|
|
48
|
+
seq BIGINT NOT NULL,
|
|
49
|
+
recorded_at TEXT NOT NULL,
|
|
50
|
+
kind TEXT NOT NULL,
|
|
51
|
+
payload TEXT NOT NULL,
|
|
52
|
+
PRIMARY KEY (run_id, seq)
|
|
53
|
+
)`,
|
|
54
|
+
`CREATE TABLE IF NOT EXISTS ${this.runs} (
|
|
55
|
+
run_id TEXT PRIMARY KEY,
|
|
56
|
+
flow TEXT NOT NULL,
|
|
57
|
+
tenant_id TEXT,
|
|
58
|
+
status TEXT NOT NULL,
|
|
59
|
+
started_at TEXT NOT NULL,
|
|
60
|
+
updated_at TEXT NOT NULL
|
|
61
|
+
)`,
|
|
62
|
+
`CREATE INDEX IF NOT EXISTS ${this.indexPrefix}_flow_idx ON ${this.runs} (flow, started_at)`,
|
|
63
|
+
`CREATE INDEX IF NOT EXISTS ${this.indexPrefix}_status_idx ON ${this.runs} (status, started_at)`,
|
|
64
|
+
`CREATE INDEX IF NOT EXISTS ${this.indexPrefix}_tenant_idx ON ${this.runs} (tenant_id, started_at)`,
|
|
65
|
+
`CREATE TABLE IF NOT EXISTS ${this.claims} (
|
|
66
|
+
run_id TEXT PRIMARY KEY,
|
|
67
|
+
owner TEXT NOT NULL,
|
|
68
|
+
token TEXT NOT NULL,
|
|
69
|
+
expires_at BIGINT NOT NULL
|
|
70
|
+
)`,
|
|
71
|
+
];
|
|
72
|
+
}
|
|
73
|
+
async begin(run) {
|
|
74
|
+
this.checkId(run.runId);
|
|
75
|
+
const at = new Date().toISOString();
|
|
76
|
+
const ev = { kind: 'begin', at, run };
|
|
77
|
+
await this.serial(run.runId, () => this.client.transaction(async (tx) => {
|
|
78
|
+
const created = await tx.query(`INSERT INTO ${this.runs} (run_id, flow, tenant_id, status, started_at, updated_at) VALUES (?, ?, ?, 'running', ?, ?)
|
|
79
|
+
ON CONFLICT (run_id) DO NOTHING`, [run.runId, run.flow, run.tenantId ?? null, at, at]);
|
|
80
|
+
if (created.rowCount !== 1)
|
|
81
|
+
throw new Error(`run "${run.runId}" already exists`);
|
|
82
|
+
await tx.query(`INSERT INTO ${this.events} (run_id, seq, recorded_at, kind, payload) VALUES (?, 0, ?, 'begin', ?)`, [run.runId, at, JSON.stringify(ev)]);
|
|
83
|
+
}));
|
|
84
|
+
this.tails.set(run.runId, 0);
|
|
85
|
+
}
|
|
86
|
+
async step(runId, stepId, patch) {
|
|
87
|
+
await this.append(runId, { kind: 'step', at: new Date().toISOString(), stepId, patch });
|
|
88
|
+
}
|
|
89
|
+
async update(runId, patch) {
|
|
90
|
+
await this.append(runId, { kind: 'update', at: new Date().toISOString(), patch });
|
|
91
|
+
}
|
|
92
|
+
async claim(runId, owner, ttlMs) {
|
|
93
|
+
this.checkId(runId);
|
|
94
|
+
const now = Date.now();
|
|
95
|
+
const token = (0, node_crypto_1.randomBytes)(8).toString('hex');
|
|
96
|
+
// One statement: take the claim if it is free, expired or already this owner's. Another owner's valid claim leaves it
|
|
97
|
+
// untouched and the statement changes no row. A renewal replaces the token, so the previous release no longer matches.
|
|
98
|
+
const taken = await this.client.query(`INSERT INTO ${this.claims} AS c (run_id, owner, token, expires_at) VALUES (?, ?, ?, ?)
|
|
99
|
+
ON CONFLICT (run_id) DO UPDATE SET owner = excluded.owner, token = excluded.token, expires_at = excluded.expires_at
|
|
100
|
+
WHERE c.expires_at <= ? OR c.owner = excluded.owner`, [runId, owner, token, now + Math.max(1, Math.ceil(ttlMs)), now]);
|
|
101
|
+
if (taken.rowCount !== 1)
|
|
102
|
+
return null;
|
|
103
|
+
return async () => {
|
|
104
|
+
await this.client.query(`DELETE FROM ${this.claims} WHERE run_id = ? AND token = ?`, [runId, token]);
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
async get(runId) {
|
|
108
|
+
this.checkId(runId);
|
|
109
|
+
const res = await this.client.query(`SELECT payload FROM ${this.events} WHERE run_id = ? ORDER BY seq`, [runId]);
|
|
110
|
+
if (res.rows.length === 0)
|
|
111
|
+
return undefined;
|
|
112
|
+
return (0, agent_core_1.foldEvents)(res.rows.map(r => JSON.parse(String(r.payload))));
|
|
113
|
+
}
|
|
114
|
+
async list(filter) {
|
|
115
|
+
if (filter?.status && filter.status.length === 0)
|
|
116
|
+
return [];
|
|
117
|
+
const where = [];
|
|
118
|
+
const params = [];
|
|
119
|
+
if (filter?.flow !== undefined) {
|
|
120
|
+
where.push('r.flow = ?');
|
|
121
|
+
params.push(filter.flow);
|
|
122
|
+
}
|
|
123
|
+
if (filter?.tenantId !== undefined) {
|
|
124
|
+
where.push('r.tenant_id = ?');
|
|
125
|
+
params.push(filter.tenantId);
|
|
126
|
+
}
|
|
127
|
+
if (filter?.status) {
|
|
128
|
+
where.push(`r.status IN (${filter.status.map(() => '?').join(', ')})`);
|
|
129
|
+
params.push(...filter.status);
|
|
130
|
+
}
|
|
131
|
+
const res = await this.client.query(`SELECT e.run_id AS run_id, e.payload AS payload
|
|
132
|
+
FROM ${this.events} e JOIN ${this.runs} r ON r.run_id = e.run_id
|
|
133
|
+
${where.length ? `WHERE ${where.join(' AND ')}` : ''}
|
|
134
|
+
ORDER BY r.started_at, e.run_id, e.seq`, params);
|
|
135
|
+
const byRun = new Map();
|
|
136
|
+
for (const row of res.rows) {
|
|
137
|
+
const id = String(row.run_id);
|
|
138
|
+
const events = byRun.get(id) ?? [];
|
|
139
|
+
events.push(JSON.parse(String(row.payload)));
|
|
140
|
+
byRun.set(id, events);
|
|
141
|
+
}
|
|
142
|
+
const out = [];
|
|
143
|
+
for (const events of byRun.values()) {
|
|
144
|
+
const run = (0, agent_core_1.foldEvents)(events);
|
|
145
|
+
if (run)
|
|
146
|
+
out.push(run);
|
|
147
|
+
}
|
|
148
|
+
return out;
|
|
149
|
+
}
|
|
150
|
+
async append(runId, ev) {
|
|
151
|
+
this.checkId(runId);
|
|
152
|
+
await this.serial(runId, async () => {
|
|
153
|
+
let seq = 0;
|
|
154
|
+
try {
|
|
155
|
+
await this.client.transaction(async (tx) => {
|
|
156
|
+
let tail = this.tails.get(runId);
|
|
157
|
+
if (tail === undefined) {
|
|
158
|
+
// First write by this object: continue after whatever the log holds now.
|
|
159
|
+
const max = await tx.query(`SELECT MAX(seq) AS seq FROM ${this.events} WHERE run_id = ?`, [runId]);
|
|
160
|
+
const found = max.rows[0]?.seq;
|
|
161
|
+
if (found === null || found === undefined)
|
|
162
|
+
throw new Error(`run "${runId}" does not exist`);
|
|
163
|
+
tail = Number(found);
|
|
164
|
+
}
|
|
165
|
+
seq = tail + 1;
|
|
166
|
+
const written = await tx.query(`INSERT INTO ${this.events} (run_id, seq, recorded_at, kind, payload) VALUES (?, ?, ?, ?, ?)
|
|
167
|
+
ON CONFLICT (run_id, seq) DO NOTHING`, [runId, seq, ev.at, ev.kind, JSON.stringify(ev)]);
|
|
168
|
+
if (written.rowCount !== 1) {
|
|
169
|
+
throw new agent_core_1.JournalConflict(runId, `the journal of "${runId}" changed under this writer: someone else wrote to it`);
|
|
170
|
+
}
|
|
171
|
+
const status = ev.kind === 'update' ? ev.patch.status ?? null : null;
|
|
172
|
+
await tx.query(`UPDATE ${this.runs} SET updated_at = ?, status = COALESCE(?, status) WHERE run_id = ?`, [ev.at, status, runId]);
|
|
173
|
+
});
|
|
174
|
+
}
|
|
175
|
+
catch (err) {
|
|
176
|
+
if (err instanceof agent_core_1.JournalConflict)
|
|
177
|
+
this.tails.delete(runId);
|
|
178
|
+
throw err;
|
|
179
|
+
}
|
|
180
|
+
this.tails.set(runId, seq);
|
|
181
|
+
});
|
|
182
|
+
}
|
|
183
|
+
serial(key, fn) {
|
|
184
|
+
const prev = this.chains.get(key) ?? Promise.resolve();
|
|
185
|
+
const next = prev.then(fn, fn);
|
|
186
|
+
const tracked = next.catch(() => undefined);
|
|
187
|
+
this.chains.set(key, tracked);
|
|
188
|
+
void tracked.then(() => { if (this.chains.get(key) === tracked)
|
|
189
|
+
this.chains.delete(key); });
|
|
190
|
+
return next;
|
|
191
|
+
}
|
|
192
|
+
checkId(id) {
|
|
193
|
+
if (!ID.test(id))
|
|
194
|
+
throw new Error(`invalid run id "${id}"`);
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
exports.SqlRunJournal = SqlRunJournal;
|
|
198
|
+
//# sourceMappingURL=sql-run-journal.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sql-run-journal.js","sourceRoot":"","sources":["../src/sql-run-journal.ts"],"names":[],"mappings":"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"}
|
package/dist/sqlite.d.ts
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { SqlRunJournal } from './sql-run-journal';
|
|
2
|
+
import type { SqlRunJournalOptions } from './sql-run-journal';
|
|
3
|
+
import type { SqliteClientOptions, SyncSqliteDb } from './client';
|
|
4
|
+
export type SqliteRunJournalOptions = SqlRunJournalOptions & SqliteClientOptions;
|
|
5
|
+
/**
|
|
6
|
+
* `RunJournal` on SQLite (SPEC-0028 F1): one file, no service. Give it an open handle, `new DatabaseSync(path)` from
|
|
7
|
+
* `node:sqlite` or a `better-sqlite3` `Database`, and call `migrate()` once.
|
|
8
|
+
*
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { DatabaseSync } from 'node:sqlite';
|
|
11
|
+
* const journal = new SqliteRunJournal(new DatabaseSync('./flows.db'));
|
|
12
|
+
* await journal.migrate();
|
|
13
|
+
* await runFlow(def, { journal, runId, executor });
|
|
14
|
+
* ```
|
|
15
|
+
*
|
|
16
|
+
* Several processes can open the same file: SQLite's lock keeps their writes apart, and the claim keeps one process per run.
|
|
17
|
+
* One handle serves one journal; the caller closes it.
|
|
18
|
+
*/
|
|
19
|
+
export declare class SqliteRunJournal extends SqlRunJournal {
|
|
20
|
+
constructor(db: SyncSqliteDb, opts?: SqliteRunJournalOptions);
|
|
21
|
+
}
|
|
22
|
+
//# sourceMappingURL=sqlite.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../src/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAElE,MAAM,MAAM,uBAAuB,GAAG,oBAAoB,GAAG,mBAAmB,CAAC;AAEjF;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAiB,SAAQ,aAAa;gBACnC,EAAE,EAAE,YAAY,EAAE,IAAI,GAAE,uBAA4B;CAGnE"}
|
package/dist/sqlite.js
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.SqliteRunJournal = void 0;
|
|
4
|
+
const sql_run_journal_1 = require("./sql-run-journal");
|
|
5
|
+
const client_1 = require("./client");
|
|
6
|
+
/**
|
|
7
|
+
* `RunJournal` on SQLite (SPEC-0028 F1): one file, no service. Give it an open handle, `new DatabaseSync(path)` from
|
|
8
|
+
* `node:sqlite` or a `better-sqlite3` `Database`, and call `migrate()` once.
|
|
9
|
+
*
|
|
10
|
+
* ```ts
|
|
11
|
+
* import { DatabaseSync } from 'node:sqlite';
|
|
12
|
+
* const journal = new SqliteRunJournal(new DatabaseSync('./flows.db'));
|
|
13
|
+
* await journal.migrate();
|
|
14
|
+
* await runFlow(def, { journal, runId, executor });
|
|
15
|
+
* ```
|
|
16
|
+
*
|
|
17
|
+
* Several processes can open the same file: SQLite's lock keeps their writes apart, and the claim keeps one process per run.
|
|
18
|
+
* One handle serves one journal; the caller closes it.
|
|
19
|
+
*/
|
|
20
|
+
class SqliteRunJournal extends sql_run_journal_1.SqlRunJournal {
|
|
21
|
+
constructor(db, opts = {}) {
|
|
22
|
+
super((0, client_1.sqliteClient)(db, opts), opts);
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
exports.SqliteRunJournal = SqliteRunJournal;
|
|
26
|
+
//# sourceMappingURL=sqlite.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../src/sqlite.ts"],"names":[],"mappings":";;;AAAA,uDAAkD;AAElD,qCAAwC;AAKxC;;;;;;;;;;;;;GAaG;AACH,MAAa,gBAAiB,SAAQ,+BAAa;IAC/C,YAAY,EAAgB,EAAE,OAAgC,EAAE;QAC5D,KAAK,CAAC,IAAA,qBAAY,EAAC,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC;CACJ;AAJD,4CAIC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,48 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@backendkit-labs/agent-flow-sql",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "RunJournal on SQL for @backendkit-labs/agent-core flows: SQLite and Postgres. Runs survive the process and any process sharing the database can resume them",
|
|
5
|
+
"main": "dist/index.js",
|
|
6
|
+
"types": "dist/index.d.ts",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": {
|
|
9
|
+
"types": "./dist/index.d.ts",
|
|
10
|
+
"default": "./dist/index.js"
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"dist/",
|
|
15
|
+
"README.md"
|
|
16
|
+
],
|
|
17
|
+
"scripts": {
|
|
18
|
+
"build": "tsc",
|
|
19
|
+
"dev": "tsc --watch",
|
|
20
|
+
"typecheck": "tsc --noEmit",
|
|
21
|
+
"prepublishOnly": "npm run build",
|
|
22
|
+
"test": "jest"
|
|
23
|
+
},
|
|
24
|
+
"peerDependencies": {
|
|
25
|
+
"@backendkit-labs/agent-core": ">=0.46.0 <0.48.0"
|
|
26
|
+
},
|
|
27
|
+
"devDependencies": {
|
|
28
|
+
"@types/jest": "^29.0.0",
|
|
29
|
+
"@types/node": "^20.0.0",
|
|
30
|
+
"better-sqlite3": "^12.11.1",
|
|
31
|
+
"jest": "^29.0.0",
|
|
32
|
+
"pg": "^8.23.1",
|
|
33
|
+
"ts-jest": "^29.0.0",
|
|
34
|
+
"typescript": "^5.4.0"
|
|
35
|
+
},
|
|
36
|
+
"engines": {
|
|
37
|
+
"node": ">=22.13.0"
|
|
38
|
+
},
|
|
39
|
+
"repository": {
|
|
40
|
+
"type": "git",
|
|
41
|
+
"url": "git+https://github.com/BackendKit-labs/backendkit-agent-framework.git",
|
|
42
|
+
"directory": "packages/flow-sql"
|
|
43
|
+
},
|
|
44
|
+
"license": "MIT",
|
|
45
|
+
"publishConfig": {
|
|
46
|
+
"access": "public"
|
|
47
|
+
}
|
|
48
|
+
}
|