actorctl 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.
@@ -0,0 +1,103 @@
1
+ // Event export for actors built on tardie 0.41.1 and hosted on Tardigrade Cloud.
2
+ // It copies committed thread journal rows from Durable Object SQLite into Aurora's actor_events table through the
3
+ // ANALYTICS binding, keeping the source_id and cursor scheme of the platform's built-in exporter so the API, the
4
+ // events view, and SQL read both kinds of actor the same way.
5
+
6
+ export type AnalyticsParameter = string | number | null
7
+
8
+ export interface AnalyticsBinding {
9
+ readonly execute: (sql: string, parameters: ReadonlyArray<AnalyticsParameter>) => Promise<void>
10
+ }
11
+
12
+ // SqlStorage is the slice of DurableObjectStorage this module uses.
13
+ export interface SqlStorage {
14
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
15
+ readonly sql: { exec(query: string, ...bindings: any[]): Iterable<unknown> }
16
+ }
17
+
18
+ export interface EventExporterOptions {
19
+ readonly storage: SqlStorage
20
+ readonly analytics: AnalyticsBinding | undefined
21
+ readonly accountId: string | undefined
22
+ readonly actorName: string | undefined
23
+ readonly batchSize?: number
24
+ }
25
+
26
+ export const DEFAULT_EXPORT_BATCH_SIZE = 100
27
+ const DESTINATION = "aurora"
28
+ // Bounds one flush so a large backlog drains across several requests and alarms.
29
+ const MAX_BATCHES_PER_FLUSH = 50
30
+
31
+ let auroraReady: Promise<void> | undefined
32
+
33
+ // eventExporter returns a single-flight flush; overlapping calls coalesce into one follow-up run.
34
+ export function eventExporter(options: EventExporterOptions) {
35
+ const batchSize = options.batchSize ?? DEFAULT_EXPORT_BATCH_SIZE
36
+ let running: Promise<void> | undefined
37
+ let again = false
38
+
39
+ const rows = <Row extends Record<string, unknown>>(query: string, ...bindings: ReadonlyArray<unknown>) => [...options.storage.sql.exec(query, ...bindings)] as Row[]
40
+
41
+ const generation = () => {
42
+ rows("CREATE TABLE IF NOT EXISTS event_export_identity (id INTEGER PRIMARY KEY CHECK (id = 1), account TEXT NOT NULL, actor TEXT NOT NULL, generation TEXT NOT NULL)")
43
+ rows("INSERT INTO event_export_identity VALUES (1, ?, ?, ?) ON CONFLICT (id) DO NOTHING", options.accountId, options.actorName, crypto.randomUUID())
44
+ const identity = rows<{ account: string; actor: string; generation: string }>("SELECT account, actor, generation FROM event_export_identity WHERE id = 1")[0]!
45
+ if (identity.account !== options.accountId || identity.actor !== options.actorName) throw new Error("Journal database belongs to a different account or actor.")
46
+ return identity.generation
47
+ }
48
+
49
+ const run = async () => {
50
+ const { analytics, accountId, actorName } = options
51
+ if (!analytics || !accountId || !actorName) return
52
+ auroraReady ??= analytics.execute(`CREATE TABLE IF NOT EXISTS actor_events (
53
+ account_id VARCHAR NOT NULL, actor VARCHAR NOT NULL, source_id VARCHAR NOT NULL,
54
+ position BIGINT NOT NULL, payload JSON NOT NULL,
55
+ PRIMARY KEY (account_id, source_id, position)
56
+ )`, []).catch(error => { auroraReady = undefined; throw error })
57
+ await auroraReady
58
+ const tables = rows<{ name: string }>("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'experimental_events'")
59
+ if (tables.length === 0) return
60
+ const current = generation()
61
+ rows("CREATE TABLE IF NOT EXISTS event_export_cursors (id TEXT PRIMARY KEY, position INTEGER NOT NULL CHECK (position >= 0))")
62
+ const prefix = JSON.stringify([actorName, accountId, "thread"]).slice(0, -1) + ","
63
+ const journals = rows<{ actor: string }>("SELECT DISTINCT actor FROM experimental_events WHERE substr(actor, 1, ?) = ? ORDER BY actor", prefix.length, prefix)
64
+ .map(row => row.actor).filter(key => key.endsWith(',"events"]'))
65
+ let batches = 0
66
+ for (const journal of journals) {
67
+ const sourceId = JSON.stringify([current, journal])
68
+ const cursorKey = JSON.stringify([accountId, sourceId, DESTINATION])
69
+ rows("INSERT INTO event_export_cursors (id, position) VALUES (?, 0) ON CONFLICT (id) DO NOTHING", cursorKey)
70
+ while (batches < MAX_BATCHES_PER_FLUSH) {
71
+ const cursor = rows<{ position: number }>("SELECT position FROM event_export_cursors WHERE id = ?", cursorKey)[0]!.position
72
+ const batch = rows<{ seq: number; event: string }>("SELECT seq, event FROM experimental_events WHERE actor = ? AND seq >= ? ORDER BY seq LIMIT ?", journal, cursor, batchSize)
73
+ if (batch.length === 0) break
74
+ if (batch.some((row, index) => row.seq !== cursor + index)) throw new Error("Journal export page has a gap.")
75
+ const values = batch.map((_, index) => `(${Array.from({ length: 5 }, (_, field) => `$${index * 5 + field + 1}`).join(", ")})`).join(", ")
76
+ await analytics.execute(
77
+ `INSERT INTO actor_events (account_id, actor, source_id, position, payload) VALUES ${values} ON CONFLICT (account_id, source_id, position) DO NOTHING`,
78
+ batch.flatMap(row => [accountId, actorName, sourceId, row.seq, row.event])
79
+ )
80
+ rows("UPDATE event_export_cursors SET position = ? WHERE id = ? AND position = ?", cursor + batch.length, cursorKey, cursor)
81
+ batches++
82
+ if (batch.length < batchSize) break
83
+ }
84
+ }
85
+ if (batches >= MAX_BATCHES_PER_FLUSH) again = true
86
+ }
87
+
88
+ const flush = (): Promise<void> => {
89
+ if (running) { again = true; return running }
90
+ running = (async () => {
91
+ try {
92
+ do { again = false; await run() } while (again)
93
+ } catch (error) {
94
+ console.warn("Actor event export failed; the cursor is retained for the next flush.", String(error))
95
+ } finally {
96
+ running = undefined
97
+ }
98
+ })()
99
+ return running
100
+ }
101
+
102
+ return { flush }
103
+ }
package/package.json ADDED
@@ -0,0 +1,31 @@
1
+ {
2
+ "name": "actorctl",
3
+ "version": "0.1.0",
4
+ "description": "Deploy actors, run threads, and read events on Tardigrade Cloud.",
5
+ "type": "module",
6
+ "license": "UNLICENSED",
7
+ "bin": {
8
+ "actorctl": "./dist/actorctl.js"
9
+ },
10
+ "files": [
11
+ "dist"
12
+ ],
13
+ "engines": {
14
+ "bun": ">=1.2"
15
+ },
16
+ "scripts": {
17
+ "build": "bun build.ts",
18
+ "prepublishOnly": "bun build.ts"
19
+ },
20
+ "dependencies": {
21
+ "esbuild": "^0.28.2"
22
+ },
23
+ "devDependencies": {
24
+ "@effect/platform-bun": "4.0.0-rc.115",
25
+ "effect": "4.0.0-rc.115"
26
+ },
27
+ "peerDependencies": {
28
+ "effect": "4.0.0-rc.115",
29
+ "tardie": "*"
30
+ }
31
+ }