@rfc0/patty 1.0.0 → 1.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 +1 -1
- package/dist/adapters/change-events.js +14 -0
- package/dist/common/time.js +1 -0
- package/dist/composition/boot.js +1 -0
- package/dist/composition/change-log.js +47 -0
- package/dist/composition/demo/seed.js +10 -0
- package/dist/composition/http.js +12 -3
- package/dist/composition/runtime.js +11 -5
- package/dist/composition/sign-in/server.js +8 -1
- package/dist/composition/stdio.js +10 -3
- package/dist/config.js +10 -7
- package/dist/diplomat/db/change-events.js +83 -0
- package/dist/diplomat/db/driver.js +32 -0
- package/dist/diplomat/db/file-lock.js +2 -2
- package/dist/diplomat/db/locale-cache.js +8 -2
- package/dist/diplomat/db/schema.js +11 -0
- package/dist/logic/change-events.js +3 -0
- package/dist/models/change-events.js +11 -0
- package/dist/wire/db/change-events.js +25 -0
- package/drizzle/0029_change_events.sql +10 -0
- package/drizzle/meta/0029_snapshot.json +2393 -0
- package/drizzle/meta/_journal.json +7 -0
- package/package.json +5 -5
- package/ui/app.js +72 -22
- package/ui/dashboards/accounts.html +1 -1
- package/ui/dashboards/budget.html +20 -2
- package/ui/dashboards/cards.html +1 -1
- package/ui/dashboards/comparative.html +12 -1
- package/ui/dashboards/overview.html +1 -1
- package/ui/dashboards/pending.html +1 -1
- package/ui/dashboards/projections.html +13 -2
package/README.md
CHANGED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { ChangeEventRowSchema, RowIdSchema } from '../wire/db/change-events.js';
|
|
2
|
+
const NO_ID = 0;
|
|
3
|
+
const idOf = (row) => RowIdSchema.safeParse(row).data?.id ?? NO_ID;
|
|
4
|
+
/** A stored row as the relay's entry: the decoded event, or the reason it could not be decoded (never thrown). */
|
|
5
|
+
export const dbToModel = (row) => {
|
|
6
|
+
const decoded = ChangeEventRowSchema.safeParse(row);
|
|
7
|
+
return decoded.success
|
|
8
|
+
? {
|
|
9
|
+
id: decoded.data.id,
|
|
10
|
+
origin: decoded.data.origin,
|
|
11
|
+
event: { userId: decoded.data.userId, entities: decoded.data.entities },
|
|
12
|
+
}
|
|
13
|
+
: { id: idOf(row), skipped: decoded.error.issues.map(({ message }) => message).join('; ') };
|
|
14
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export const sleep = (ms) => new Promise((resume) => setTimeout(resume, ms));
|
package/dist/composition/boot.js
CHANGED
|
@@ -23,5 +23,6 @@ export const boot = (config) => safeTry(async function* () {
|
|
|
23
23
|
return err(demoNotReady(config.DB_PATH));
|
|
24
24
|
}
|
|
25
25
|
const prepared = await prepareAuth(config, db, runtime.authRunEffects);
|
|
26
|
+
await runtime.changeLog.prune();
|
|
26
27
|
return ok({ db, runtime, prepared });
|
|
27
28
|
});
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { randomUUID } from 'node:crypto';
|
|
2
|
+
import { createRelayedChangeBus, pruneCutoff, startChangeRelay, } from '@rfc0/effect-runner';
|
|
3
|
+
import { changeLogStore } from '../diplomat/db/change-events.js';
|
|
4
|
+
import { isWorthAnnouncing } from '../logic/change-events.js';
|
|
5
|
+
import { CHANGE_EVENT_PRUNE_EVERY_MS, CHANGE_NOTIFICATION_FAILED, CHANGE_EVENT_RETENTION_MS, CHANGE_RELAY_BATCH_LIMIT, CHANGE_RELAY_POLL_MS, } from '../models/change-events.js';
|
|
6
|
+
import { LOG_PREFIX } from '../models/package.js';
|
|
7
|
+
/** stderr only — stdout carries the stdio MCP protocol (ADR-007). */
|
|
8
|
+
export const reportChangeError = (cause) => {
|
|
9
|
+
console.error(`${LOG_PREFIX} ${CHANGE_NOTIFICATION_FAILED}:`, cause);
|
|
10
|
+
};
|
|
11
|
+
/** The process's change bus (ADR-036 §2): `@rfc0/effect-runner`'s relayed bus over the SQLite store, so a publish
|
|
12
|
+
* reaches this process's subscribers first and the other processes' relays after. A subscriber's failure and a failed
|
|
13
|
+
* append go to `onError`, never to the write. */
|
|
14
|
+
export const createChangeLog = (db, onError, clock = () => new Date()) => {
|
|
15
|
+
const origin = randomUUID();
|
|
16
|
+
const store = changeLogStore(db);
|
|
17
|
+
const { bus, publishLocal, settled } = createRelayedChangeBus({
|
|
18
|
+
store,
|
|
19
|
+
origin,
|
|
20
|
+
onError,
|
|
21
|
+
shouldAppend: isWorthAnnouncing,
|
|
22
|
+
});
|
|
23
|
+
// Only a relay prunes on a timer, so every process prunes once at startup.
|
|
24
|
+
const prune = () => store.pruneBefore(pruneCutoff(clock(), CHANGE_EVENT_RETENTION_MS)).catch(onError);
|
|
25
|
+
const close = async () => {
|
|
26
|
+
await settled();
|
|
27
|
+
await store.close();
|
|
28
|
+
};
|
|
29
|
+
return { changeBus: bus, changeLog: { origin, onError, store, publishLocal, settled, prune, close } };
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* The relay of a process that serves a dashboard, with PATTY's values (ADR-036 §3). One that cannot start is reported
|
|
33
|
+
* and answers `null`; the dashboard then updates from this process's writes only.
|
|
34
|
+
*/
|
|
35
|
+
export const startServingRelay = ({ changeLog }) => startChangeRelay({
|
|
36
|
+
store: changeLog.store,
|
|
37
|
+
publishLocal: changeLog.publishLocal,
|
|
38
|
+
origin: changeLog.origin,
|
|
39
|
+
pollMs: CHANGE_RELAY_POLL_MS,
|
|
40
|
+
retentionMs: CHANGE_EVENT_RETENTION_MS,
|
|
41
|
+
pruneEveryMs: CHANGE_EVENT_PRUNE_EVERY_MS,
|
|
42
|
+
batchLimit: CHANGE_RELAY_BATCH_LIMIT,
|
|
43
|
+
onError: changeLog.onError,
|
|
44
|
+
}).catch((cause) => {
|
|
45
|
+
changeLog.onError(cause);
|
|
46
|
+
return null;
|
|
47
|
+
});
|
|
@@ -72,6 +72,16 @@ const runPlan = async (scoped, plan, clock, today) => {
|
|
|
72
72
|
export const seedDemo = async (db, options) => {
|
|
73
73
|
const clock = { now: options.today };
|
|
74
74
|
const runtime = createRuntime(db, { ...options.config, PATTY_LOCALE: undefined }, { clock: () => clock.now });
|
|
75
|
+
try {
|
|
76
|
+
return await seedOn(runtime, db, options, clock);
|
|
77
|
+
}
|
|
78
|
+
finally {
|
|
79
|
+
// The seed's writes queued change announcements: drain them and release the log connection before the caller
|
|
80
|
+
// closes or removes the database.
|
|
81
|
+
await runtime.changeLog.close();
|
|
82
|
+
}
|
|
83
|
+
};
|
|
84
|
+
const seedOn = async (runtime, db, options, clock) => {
|
|
75
85
|
const scoped = scopedFor(runtime, OWNER_PRINCIPAL);
|
|
76
86
|
const instanceSettings = instanceSettingsRepo(db);
|
|
77
87
|
const start = await demoSeedStatus({ instance: scoped.deps.instance, instanceSettings });
|
package/dist/composition/http.js
CHANGED
|
@@ -2,6 +2,7 @@ import { ok, safeTry } from 'neverthrow';
|
|
|
2
2
|
import Fastify from 'fastify';
|
|
3
3
|
import { version } from '../common/build-version.js';
|
|
4
4
|
import { boot } from './boot.js';
|
|
5
|
+
import { startServingRelay } from './change-log.js';
|
|
5
6
|
import { DASHBOARD_PATH, httpOrigin, isPortInUse, LOOPBACK_HOST, portInUseReason } from '../common/net.js';
|
|
6
7
|
import { DISABLED_AUTH } from '../diplomat/http/context.js';
|
|
7
8
|
import { redactSecretQuery } from '../logic/auth/redact.js';
|
|
@@ -88,18 +89,26 @@ export const runHttp = (config) => safeTry(async function* () {
|
|
|
88
89
|
const app = buildHttpApp(runtime, version, { auth: prepared.auth, trustProxy: config.TRUST_PROXY });
|
|
89
90
|
// A repeated signal (or SIGINT followed by SIGTERM) must not double-close/double-exit.
|
|
90
91
|
let shuttingDown = false;
|
|
92
|
+
let relay = null;
|
|
91
93
|
const shutdown = () => {
|
|
92
94
|
if (shuttingDown)
|
|
93
95
|
return;
|
|
94
96
|
shuttingDown = true;
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
97
|
+
// Each stage is logged when it fails and never skips the next: a relay that fails to stop must not leave the
|
|
98
|
+
// listening socket and the change-log connection open.
|
|
99
|
+
const stage = (work) => Promise.resolve()
|
|
100
|
+
.then(work)
|
|
101
|
+
.then(() => undefined)
|
|
102
|
+
.catch((err) => app.log.error(err));
|
|
103
|
+
void stage(() => relay?.stop())
|
|
104
|
+
.then(() => stage(() => app.close()))
|
|
105
|
+
.then(() => stage(() => runtime.changeLog.close()))
|
|
98
106
|
.finally(() => process.exit(0));
|
|
99
107
|
};
|
|
100
108
|
process.on('SIGINT', shutdown);
|
|
101
109
|
process.on('SIGTERM', shutdown);
|
|
102
110
|
await app.listen({ port: config.PORT, host: config.HOST });
|
|
111
|
+
relay = await startServingRelay(runtime);
|
|
103
112
|
// config.PORT may be 0 (OS-assigned); read back the address actually bound for the banner.
|
|
104
113
|
const boundPort = app.server.address().port;
|
|
105
114
|
const origin = httpOrigin(config.HOST, boundPort);
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { randomUUID } from 'node:crypto';
|
|
2
|
-
import {
|
|
2
|
+
import { runEffects, runEffectsSequence } from '@rfc0/effect-runner';
|
|
3
3
|
import { AUTH_APPLIERS } from './auth.js';
|
|
4
|
+
import { createChangeLog, reportChangeError } from './change-log.js';
|
|
4
5
|
import { createEngineContext } from '../diplomat/db/engine.js';
|
|
5
6
|
import { createLocaleResolver } from '../diplomat/db/locale-cache.js';
|
|
6
7
|
import { accountApplier, accountsRepo } from '../diplomat/db/repos/accounts.js';
|
|
@@ -34,9 +35,6 @@ import { RECURRING_ENTITY_TAG } from '../models/recurring.js';
|
|
|
34
35
|
import { TAG_ENTITY_TAG } from '../models/tag.js';
|
|
35
36
|
import { TRANSACTION_ENTITY_TAG } from '../models/transaction.js';
|
|
36
37
|
import { TRANSACTION_TAG_ENTITY_TAG } from '../models/transaction-tag.js';
|
|
37
|
-
const reportChangeError = (cause) => {
|
|
38
|
-
console.error('[patty] change notification failed:', cause);
|
|
39
|
-
};
|
|
40
38
|
const applierRegistryFor = (userId) => ({
|
|
41
39
|
[ACCOUNT_ENTITY_TAG]: accountApplier(userId),
|
|
42
40
|
[TRANSACTION_ENTITY_TAG]: transactionApplier(userId),
|
|
@@ -82,10 +80,17 @@ const runnersOn = (engineContext, changeBus) => {
|
|
|
82
80
|
authRunEffects: (flow) => runEffects(engineContext, AUTH_APPLIERS, flow, publishFor(null)),
|
|
83
81
|
};
|
|
84
82
|
};
|
|
83
|
+
const dropStaleLocale = (localeResolver) => ({ userId, entities }) => {
|
|
84
|
+
if (userId !== null && entities.includes(USER_SETTINGS_ENTITY_TAG))
|
|
85
|
+
localeResolver.resetLocale(userId);
|
|
86
|
+
};
|
|
85
87
|
export const createRuntime = (db, config, options = {}) => {
|
|
86
88
|
const onChangeError = options.onChangeError ?? reportChangeError;
|
|
87
89
|
const localeResolver = createLocaleResolver(config.PATTY_LOCALE);
|
|
88
|
-
const changeBus =
|
|
90
|
+
const { changeBus, changeLog } = createChangeLog(db, onChangeError, options.clock);
|
|
91
|
+
// First subscriber, so it runs before any dashboard stream: another process's `set_locale` reaches this one as a
|
|
92
|
+
// relayed event, and the cached language must be gone by the time the refetch it triggers resolves a locale.
|
|
93
|
+
changeBus.subscribe(dropStaleLocale(localeResolver));
|
|
89
94
|
const health = healthRepo(db);
|
|
90
95
|
const instance = instanceRepo(db);
|
|
91
96
|
const depsFor = ({ userId }) => {
|
|
@@ -111,5 +116,6 @@ export const createRuntime = (db, config, options = {}) => {
|
|
|
111
116
|
...runnersOn(createEngineContext(db, onChangeError), changeBus),
|
|
112
117
|
resetLocaleFor: ({ userId }) => localeResolver.resetLocale(userId),
|
|
113
118
|
changeBus,
|
|
119
|
+
changeLog,
|
|
114
120
|
};
|
|
115
121
|
};
|
|
@@ -29,8 +29,15 @@ export const startSignInServer = async (config, db) => {
|
|
|
29
29
|
// Fastify binds `localhost` to both its IPv4 and IPv6 loopback addresses.
|
|
30
30
|
await app.listen({ port: 0, host: LOCALHOST_NAME }).catch(async (cause) => {
|
|
31
31
|
await app.close();
|
|
32
|
+
await runtime.changeLog.close();
|
|
32
33
|
throw cause;
|
|
33
34
|
});
|
|
34
35
|
const { port } = app.server.address();
|
|
35
|
-
return {
|
|
36
|
+
return {
|
|
37
|
+
origin: httpOrigin(LOCALHOST_NAME, port),
|
|
38
|
+
close: async () => {
|
|
39
|
+
await app.close();
|
|
40
|
+
await runtime.changeLog.close();
|
|
41
|
+
},
|
|
42
|
+
};
|
|
36
43
|
};
|
|
@@ -5,6 +5,7 @@ import { connectStdio } from '../diplomat/mcp/stdio.js';
|
|
|
5
5
|
import { signInOrigin } from '../logic/auth/origin.js';
|
|
6
6
|
import { AuthMode } from '../models/auth/mode.js';
|
|
7
7
|
import { boot } from './boot.js';
|
|
8
|
+
import { startServingRelay } from './change-log.js';
|
|
8
9
|
import { loadHttpModule } from './lazy-modules.js';
|
|
9
10
|
const maybeStartSidecar = async (config, runtime, auth) => {
|
|
10
11
|
if (!config.PATTY_HTTP)
|
|
@@ -35,7 +36,7 @@ const stdioAuthFor = (config, stdio, linkOrigin) => stdio
|
|
|
35
36
|
}
|
|
36
37
|
: { mode: AuthMode.enum.disabled };
|
|
37
38
|
const closeLogged = (closing) => closing.catch((err) => console.error(err));
|
|
38
|
-
const shutdownOf = ({ server, session }, sidecar) => {
|
|
39
|
+
const shutdownOf = ({ server, session }, sidecar, relay, { changeLog }) => {
|
|
39
40
|
let shuttingDown = false;
|
|
40
41
|
return () => {
|
|
41
42
|
if (shuttingDown)
|
|
@@ -45,7 +46,11 @@ const shutdownOf = ({ server, session }, sidecar) => {
|
|
|
45
46
|
closeLogged(server.close()),
|
|
46
47
|
sidecar?.listening ? closeLogged(sidecar.app.close()) : Promise.resolve(),
|
|
47
48
|
session?.close(),
|
|
48
|
-
])
|
|
49
|
+
])
|
|
50
|
+
// Writers have stopped: stop listening, then let the last write's queued announcement land.
|
|
51
|
+
.then(() => closeLogged(Promise.resolve(relay?.stop())))
|
|
52
|
+
.then(() => closeLogged(changeLog.close()))
|
|
53
|
+
.finally(() => process.exit(0));
|
|
49
54
|
};
|
|
50
55
|
};
|
|
51
56
|
const shutDownOnDisconnect = (shutdown) => {
|
|
@@ -59,11 +64,13 @@ export const runStdio = (config) => safeTry(async function* () {
|
|
|
59
64
|
const link = signInLink(config);
|
|
60
65
|
const connection = await connectStdio(runtime, version, stdioAuthFor(config, prepared.stdio, link.origin));
|
|
61
66
|
const sidecar = await maybeStartSidecar(config, runtime, prepared.auth);
|
|
67
|
+
// Only a process that serves a dashboard listens for the others' writes (ADR-036 §3).
|
|
68
|
+
const relay = sidecar?.listening ? await startServingRelay(runtime) : null;
|
|
62
69
|
if (sidecar?.listening) {
|
|
63
70
|
const boundOrigin = httpOrigin(config.HOST, sidecar.app.server.address().port);
|
|
64
71
|
link.bind(boundOrigin);
|
|
65
72
|
await prepared.issueAndAnnounceSetup(boundOrigin);
|
|
66
73
|
}
|
|
67
|
-
shutDownOnDisconnect(shutdownOf(connection, sidecar));
|
|
74
|
+
shutDownOnDisconnect(shutdownOf(connection, sidecar, relay, runtime));
|
|
68
75
|
return ok(undefined);
|
|
69
76
|
});
|
package/dist/config.js
CHANGED
|
@@ -24,15 +24,13 @@ const DEFAULT_KEY_LOCK_PATH = join(DATA_DIRECTORY, 'db-key.lock');
|
|
|
24
24
|
// published package; `npm run dev` overrides PORT back to the familiar 3001 (package.json), so
|
|
25
25
|
// a contributor's local dev instance never collides with an already-running installed instance.
|
|
26
26
|
const DEFAULT_PORT = 51737;
|
|
27
|
-
// `TRUST_PROXY=0` trusts zero proxy hops: no proxy.
|
|
28
|
-
const NO_PROXY_HOPS = 0;
|
|
29
27
|
/** Whether anything besides this machine can reach the instance: a non-loopback bind, or a reverse proxy
|
|
30
28
|
* configured in front of it (`PUBLIC_URL` names its external origin; `TRUST_PROXY` says to believe it). A
|
|
31
29
|
* proxy typically connects to a loopback bind, so `HOST` alone would call that instance private. Only used to
|
|
32
30
|
* refuse `PATTY_AUTH=disabled` on such an instance. */
|
|
33
31
|
export const isExposed = (env) => !isLoopbackHost(env.HOST) ||
|
|
34
32
|
env.PUBLIC_URL !== undefined ||
|
|
35
|
-
(env.TRUST_PROXY !== undefined && env.TRUST_PROXY !== false
|
|
33
|
+
(env.TRUST_PROXY !== undefined && env.TRUST_PROXY !== false);
|
|
36
34
|
// An empty string (`PUBLIC_URL=` from a compose file or shell) means "unset", not "invalid".
|
|
37
35
|
const unsetWhenEmpty = (value) => (value === '' ? undefined : value);
|
|
38
36
|
const optionalEnv = (schema) => z.preprocess(unsetWhenEmpty, schema.optional());
|
|
@@ -44,18 +42,23 @@ const PublicUrl = z
|
|
|
44
42
|
.refine((value) => /^https?:\/\//.test(value) && new URL(value).origin === value, {
|
|
45
43
|
message: 'PUBLIC_URL must be an http(s) origin with no path or trailing slash, e.g. https://patty.example.com',
|
|
46
44
|
});
|
|
47
|
-
// Fastify's `trustProxy`: `true`/`false`,
|
|
48
|
-
//
|
|
45
|
+
// Fastify's `trustProxy`: `true`/`false`, or a comma-separated list of trusted addresses/CIDRs (anything else is
|
|
46
|
+
// passed through for Fastify (proxy-addr) to interpret). A hop count is refused: Fastify trusts nobody for one,
|
|
47
|
+
// because a client that reaches the instance directly could spoof X-Forwarded-*; `0` keeps meaning "no proxy".
|
|
49
48
|
const HOP_COUNT = /^\d+$/;
|
|
49
|
+
const NO_PROXY_HOPS = '0';
|
|
50
|
+
export const HOP_COUNT_REFUSED_MESSAGE = 'TRUST_PROXY cannot be a hop count: a client that reaches PATTY directly could spoof X-Forwarded-For. ' +
|
|
51
|
+
"Name the proxy instead — an address or CIDR list such as 'loopback' or '10.0.0.0/8' — or 'true' to trust every proxy.";
|
|
50
52
|
const TrustProxy = z
|
|
51
53
|
.string()
|
|
52
54
|
.min(1)
|
|
55
|
+
.refine((value) => !HOP_COUNT.test(value) || value === NO_PROXY_HOPS, { message: HOP_COUNT_REFUSED_MESSAGE })
|
|
53
56
|
.transform((value) => {
|
|
54
57
|
if (value === 'true')
|
|
55
58
|
return true;
|
|
56
|
-
if (value === 'false')
|
|
59
|
+
if (value === 'false' || value === NO_PROXY_HOPS)
|
|
57
60
|
return false;
|
|
58
|
-
return
|
|
61
|
+
return value;
|
|
59
62
|
});
|
|
60
63
|
const Env = z
|
|
61
64
|
.object({
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import { asc, and, gt, ne, lt, sql } from 'drizzle-orm';
|
|
2
|
+
import { sleep } from '../../common/time.js';
|
|
3
|
+
import * as changeEventAdapters from '../../adapters/change-events.js';
|
|
4
|
+
import { DataVersionRowSchema, LatestIdRowSchema } from '../../wire/db/change-events.js';
|
|
5
|
+
import { closeDatabase, NEVER_BLOCK_IN_SQLITE_MS, openSibling } from './driver.js';
|
|
6
|
+
import { changeEvents } from './schema.js';
|
|
7
|
+
import { isSqliteBusy } from './sqlite-errors.js';
|
|
8
|
+
/** The change log's own connection: no lock wait, and one stable identity (`data_version` is per connection).
|
|
9
|
+
* Never run a transaction on it. */
|
|
10
|
+
export const openChangeLog = (db) => openSibling(db, NEVER_BLOCK_IN_SQLITE_MS);
|
|
11
|
+
const insertRow = async (log, { event, origin, createdAt }) => {
|
|
12
|
+
await log.insert(changeEvents).values({
|
|
13
|
+
userId: event.userId,
|
|
14
|
+
entities: JSON.stringify(event.entities),
|
|
15
|
+
origin,
|
|
16
|
+
createdAt,
|
|
17
|
+
});
|
|
18
|
+
};
|
|
19
|
+
/** Pauses between append attempts while the database is busy; the loop stays free meanwhile (ADR-036 §2). */
|
|
20
|
+
export const CHANGE_EVENT_APPEND_BACKOFF_MS = [5, 10, 20, 40, 80];
|
|
21
|
+
/** Appends one row; while the database is busy, retries after each pause, then fails. */
|
|
22
|
+
export const append = async (log, record, pauses = CHANGE_EVENT_APPEND_BACKOFF_MS) => {
|
|
23
|
+
try {
|
|
24
|
+
await insertRow(log, record);
|
|
25
|
+
}
|
|
26
|
+
catch (cause) {
|
|
27
|
+
const [next, ...rest] = pauses;
|
|
28
|
+
if (next === undefined || !isSqliteBusy(cause))
|
|
29
|
+
throw cause;
|
|
30
|
+
await sleep(next);
|
|
31
|
+
await append(log, record, rest);
|
|
32
|
+
}
|
|
33
|
+
};
|
|
34
|
+
/** The newest row's id, 0 for an empty table: where a relay starts, so it never replays what came before it. */
|
|
35
|
+
export const latestId = async (log) => {
|
|
36
|
+
const [row] = await log.all(sql `SELECT MAX(${changeEvents.id}) AS latest FROM ${changeEvents}`);
|
|
37
|
+
return LatestIdRowSchema.parse(row).latest ?? 0;
|
|
38
|
+
};
|
|
39
|
+
/** Rows after `afterId` written by a process other than `excludeOrigin`, in id order, at most `limit`. A row that
|
|
40
|
+
* does not decode is returned as a skipped entry carrying its id and the reason, never thrown. */
|
|
41
|
+
export const readAfter = async (log, afterId, excludeOrigin, limit) => {
|
|
42
|
+
const rows = await log
|
|
43
|
+
.select()
|
|
44
|
+
.from(changeEvents)
|
|
45
|
+
.where(and(gt(changeEvents.id, afterId), ne(changeEvents.origin, excludeOrigin)))
|
|
46
|
+
.orderBy(asc(changeEvents.id))
|
|
47
|
+
.limit(limit);
|
|
48
|
+
return rows.map(changeEventAdapters.dbToModel);
|
|
49
|
+
};
|
|
50
|
+
/** Deletes rows created before the instant (ISO-8601, so text order is time order). */
|
|
51
|
+
export const pruneBefore = async (log, isoInstant) => {
|
|
52
|
+
await log.delete(changeEvents).where(lt(changeEvents.createdAt, isoInstant));
|
|
53
|
+
};
|
|
54
|
+
/** SQLite's `data_version` on this connection: it changes only when another connection committed. */
|
|
55
|
+
export const dataVersion = async (log) => {
|
|
56
|
+
const [row] = await log.all(sql `PRAGMA data_version`);
|
|
57
|
+
return DataVersionRowSchema.parse(row).data_version;
|
|
58
|
+
};
|
|
59
|
+
/**
|
|
60
|
+
* The package's `ChangeLogStore` over `change_events`. It meets the package's id contract: AUTOINCREMENT never reuses
|
|
61
|
+
* an id, and with one writer at a time rows become readable in id order. It runs on one lazily opened sibling
|
|
62
|
+
* connection; `close` releases it.
|
|
63
|
+
*/
|
|
64
|
+
export const changeLogStore = (db) => {
|
|
65
|
+
const link = { opened: undefined };
|
|
66
|
+
const connection = () => (link.opened ??= openChangeLog(db).catch((cause) => {
|
|
67
|
+
link.opened = undefined;
|
|
68
|
+
throw cause;
|
|
69
|
+
}));
|
|
70
|
+
return {
|
|
71
|
+
append: async (record) => append(await connection(), record),
|
|
72
|
+
latestId: async () => latestId(await connection()),
|
|
73
|
+
readAfter: async (afterId, excludeOrigin, limit) => readAfter(await connection(), afterId, excludeOrigin, limit),
|
|
74
|
+
pruneBefore: async (isoInstant) => pruneBefore(await connection(), isoInstant),
|
|
75
|
+
changeToken: async () => dataVersion(await connection()),
|
|
76
|
+
close: async () => {
|
|
77
|
+
const opened = link.opened;
|
|
78
|
+
link.opened = undefined;
|
|
79
|
+
if (opened)
|
|
80
|
+
closeDatabase(await opened);
|
|
81
|
+
},
|
|
82
|
+
};
|
|
83
|
+
};
|
|
@@ -16,6 +16,8 @@ import { LOG_PREFIX } from '../../models/package.js';
|
|
|
16
16
|
// (ADR-007) when more than one is connected to the same file at once.
|
|
17
17
|
const JOURNAL_MODE_WAL = 'WAL';
|
|
18
18
|
export const BUSY_TIMEOUT_MS = 5000;
|
|
19
|
+
/** No lock wait inside SQLite: libsql is synchronous, so any wait blocks the event loop (ADR-036 §2). */
|
|
20
|
+
export const NEVER_BLOCK_IN_SQLITE_MS = 0;
|
|
19
21
|
/** `busy_timeout` is per connection (ADR-024) and libsql opens a fresh connection after every transaction, so
|
|
20
22
|
* anything that has just run one re-asserts it on the connection that follows. */
|
|
21
23
|
export const assertBusyTimeout = (client) => client.execute(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
|
|
@@ -149,8 +151,38 @@ export const openDatabaseWithKey = async (config, encryptionKey, { initializeJou
|
|
|
149
151
|
await enableWal(client);
|
|
150
152
|
// busy_timeout is per-connection (ADR-024), so it is asserted unconditionally on every open.
|
|
151
153
|
await assertBusyTimeout(client);
|
|
154
|
+
const db = drizzle(client, { schema });
|
|
155
|
+
siblingOpeners.set(db, (busyTimeoutMs) => openSiblingClient(config, encryptionKey, busyTimeoutMs));
|
|
156
|
+
return db;
|
|
157
|
+
};
|
|
158
|
+
// A `Db` does not expose the key it was opened with; the opener closes over it here, in the adapter, so nothing else
|
|
159
|
+
// ever holds the key just to open a second connection.
|
|
160
|
+
const siblingOpeners = new WeakMap();
|
|
161
|
+
const openSiblingClient = async (config, encryptionKey, busyTimeoutMs) => {
|
|
162
|
+
const client = createClient({ url: pathToFileURL(config.DB_PATH).href, encryptionKey });
|
|
163
|
+
try {
|
|
164
|
+
await client.execute(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
|
|
165
|
+
}
|
|
166
|
+
catch (cause) {
|
|
167
|
+
// Nothing will hold this handle, so a failed setup releases its native connection and file handles itself.
|
|
168
|
+
client.close();
|
|
169
|
+
throw cause;
|
|
170
|
+
}
|
|
152
171
|
return drizzle(client, { schema });
|
|
153
172
|
};
|
|
173
|
+
/** A second, independent connection to the same database file, waiting at most `busyTimeoutMs` for a lock. libsql
|
|
174
|
+
* replaces a client's connection after every transaction, so anything that needs one stable connection (SQLite's
|
|
175
|
+
* `data_version` is per connection) or must not disturb the engine's own (a short lock wait) takes this one and
|
|
176
|
+
* never runs a transaction on it. Close it with `closeDatabase`. */
|
|
177
|
+
export const openSibling = (db, busyTimeoutMs) => {
|
|
178
|
+
if (!Number.isInteger(busyTimeoutMs) || busyTimeoutMs < 0) {
|
|
179
|
+
return Promise.reject(new RangeError(`${LOG_PREFIX} busyTimeoutMs must be a non-negative integer, got ${busyTimeoutMs}`));
|
|
180
|
+
}
|
|
181
|
+
const open = siblingOpeners.get(db);
|
|
182
|
+
if (!open)
|
|
183
|
+
return Promise.reject(new Error(`${LOG_PREFIX} this database handle was not opened by openDatabase`));
|
|
184
|
+
return open(busyTimeoutMs);
|
|
185
|
+
};
|
|
154
186
|
/** Releases the libSQL connection a short-lived process (the CLI) opened, so it can end by itself. Drizzle keeps
|
|
155
187
|
* the client on `$client` at runtime without typing it on `LibSQLDatabase`. */
|
|
156
188
|
export const closeDatabase = (db) => {
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import { pathToFileURL } from 'node:url';
|
|
2
2
|
import { createClient } from '@libsql/client';
|
|
3
3
|
import { isSqliteBusy } from './sqlite-errors.js';
|
|
4
|
-
|
|
4
|
+
import { sleep } from '../../common/time.js';
|
|
5
|
+
import { NEVER_BLOCK_IN_SQLITE_MS } from './driver.js';
|
|
5
6
|
export const openLockFile = async (lockPath) => {
|
|
6
7
|
const client = createClient({ url: pathToFileURL(lockPath).href });
|
|
7
8
|
try {
|
|
@@ -60,7 +61,6 @@ const attemptExclusiveLock = async (lockPath) => {
|
|
|
60
61
|
};
|
|
61
62
|
};
|
|
62
63
|
export const tryExclusiveLock = async (lockPath) => (await attemptExclusiveLock(lockPath)).lock;
|
|
63
|
-
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
64
64
|
const acquireWithin = async (lockPath, deadline, wait) => {
|
|
65
65
|
const attempt = await attemptExclusiveLock(lockPath);
|
|
66
66
|
if (attempt.lock !== null)
|
|
@@ -1,9 +1,12 @@
|
|
|
1
1
|
import { Locale } from '../../models/locale.js';
|
|
2
2
|
// resetLocale is shell-only — never a Deps field; a diplomat handler calls it after its own
|
|
3
3
|
// setLocale write commits. configLocale (PATTY_LOCALE) always wins, for every user, and is never cached.
|
|
4
|
-
// Keyed by user, so one person's language never becomes another's.
|
|
4
|
+
// Keyed by user, so one person's language never becomes another's. A reset also bumps the user's generation: a lookup
|
|
5
|
+
// that started before it (it may have read the old language) must not put its result back in the cache.
|
|
5
6
|
export const createLocaleResolver = (configLocale) => {
|
|
6
7
|
const cachedByUser = new Map();
|
|
8
|
+
const generationByUser = new Map();
|
|
9
|
+
const generationOf = (userId) => generationByUser.get(userId) ?? 0;
|
|
7
10
|
return {
|
|
8
11
|
locale: async (userId, settings) => {
|
|
9
12
|
if (configLocale)
|
|
@@ -11,12 +14,15 @@ export const createLocaleResolver = (configLocale) => {
|
|
|
11
14
|
const cached = cachedByUser.get(userId);
|
|
12
15
|
if (cached)
|
|
13
16
|
return cached;
|
|
17
|
+
const generation = generationOf(userId);
|
|
14
18
|
const row = await settings.getLocale();
|
|
15
19
|
const locale = row?.locale ?? Locale.enum.en;
|
|
16
|
-
|
|
20
|
+
if (generationOf(userId) === generation)
|
|
21
|
+
cachedByUser.set(userId, locale);
|
|
17
22
|
return locale;
|
|
18
23
|
},
|
|
19
24
|
resetLocale: (userId) => {
|
|
25
|
+
generationByUser.set(userId, generationOf(userId) + 1);
|
|
20
26
|
cachedByUser.delete(userId);
|
|
21
27
|
},
|
|
22
28
|
};
|
|
@@ -346,3 +346,14 @@ export const clientGrants = sqliteTable('client_grants', {
|
|
|
346
346
|
.where(sql `${table.status} = ${sql.raw(`'${GrantStatus.enum.pending}'`)}`),
|
|
347
347
|
index('client_grants_user_code_idx').on(table.userCode),
|
|
348
348
|
]);
|
|
349
|
+
// ADR-036 §1: change notifications between the processes that share this file. Infrastructure, not a domain
|
|
350
|
+
// table: no repo, no applier, no `user_id` ownership (the column only says whose change it announces), not in
|
|
351
|
+
// `Tenancy`. It holds entity tags, never data; only `diplomat/db/change-events.ts` and the composition root's
|
|
352
|
+
// relay and appending bus touch it. Rows live minutes (`CHANGE_EVENT_RETENTION_MS`).
|
|
353
|
+
export const changeEvents = sqliteTable('change_events', {
|
|
354
|
+
id: integer('id').primaryKey({ autoIncrement: true }),
|
|
355
|
+
userId: text('user_id'),
|
|
356
|
+
entities: text('entities').notNull(),
|
|
357
|
+
origin: text('origin').notNull(),
|
|
358
|
+
createdAt: text('created_at').notNull(),
|
|
359
|
+
}, (table) => [index('change_events_created_at_idx').on(table.createdAt)]);
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
/** An event no stream can receive is neither appended nor relayed: one with no user (instance bookkeeping, `userId`
|
|
2
|
+
* null, reaches no one — `/ui/events` forwards only a user's own events) and one naming no entity. */
|
|
3
|
+
export const isWorthAnnouncing = ({ userId, entities }) => userId !== null && entities.length > 0;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** How often a serving process asks whether another process committed (ADR-036 §3, §5: the cross-process latency). */
|
|
2
|
+
export const CHANGE_RELAY_POLL_MS = 1000;
|
|
3
|
+
/** A change-log row older than this is deleted: the log only bridges the seconds between two processes (§4). The
|
|
4
|
+
* package requires at least twice the poll interval. */
|
|
5
|
+
export const CHANGE_EVENT_RETENTION_MS = 10 * 60 * 1000;
|
|
6
|
+
/** How often the relay deletes rows past retention. */
|
|
7
|
+
export const CHANGE_EVENT_PRUNE_EVERY_MS = 60 * 1000;
|
|
8
|
+
/** Reported with `LOG_PREFIX` when a change notification (a subscriber, an append, the relay) fails. */
|
|
9
|
+
export const CHANGE_NOTIFICATION_FAILED = 'change notification failed';
|
|
10
|
+
/** Rows one relay tick reads; a backlog drains over the following ticks, in id order. */
|
|
11
|
+
export const CHANGE_RELAY_BATCH_LIMIT = 200;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
/** `entities` is stored as a JSON array of tags; a value that is not one fails here, at the boundary. */
|
|
3
|
+
const EntityTagsSchema = z
|
|
4
|
+
.string()
|
|
5
|
+
.transform((text, context) => {
|
|
6
|
+
try {
|
|
7
|
+
return JSON.parse(text);
|
|
8
|
+
}
|
|
9
|
+
catch {
|
|
10
|
+
context.addIssue({ code: 'custom', message: 'entities is not valid JSON' });
|
|
11
|
+
return z.NEVER;
|
|
12
|
+
}
|
|
13
|
+
})
|
|
14
|
+
.pipe(z.array(z.string()));
|
|
15
|
+
export const ChangeEventRowSchema = z.object({
|
|
16
|
+
id: z.number().int(),
|
|
17
|
+
userId: z.string().nullable(),
|
|
18
|
+
entities: EntityTagsSchema,
|
|
19
|
+
origin: z.string(),
|
|
20
|
+
createdAt: z.string(),
|
|
21
|
+
});
|
|
22
|
+
/** What can be read of a row that failed to decode: its id, to report it and move past it. */
|
|
23
|
+
export const RowIdSchema = z.object({ id: z.number().int() });
|
|
24
|
+
export const DataVersionRowSchema = z.object({ data_version: z.number().int() });
|
|
25
|
+
export const LatestIdRowSchema = z.object({ latest: z.number().int().nullable() });
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
-- ADR-036: change notifications between the processes sharing this database (entity tags only, never data; rows live minutes). Infrastructure: no repo, no applier, no owner.
|
|
2
|
+
CREATE TABLE `change_events` (
|
|
3
|
+
`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
|
|
4
|
+
`user_id` text,
|
|
5
|
+
`entities` text NOT NULL,
|
|
6
|
+
`origin` text NOT NULL,
|
|
7
|
+
`created_at` text NOT NULL
|
|
8
|
+
);
|
|
9
|
+
--> statement-breakpoint
|
|
10
|
+
CREATE INDEX `change_events_created_at_idx` ON `change_events` (`created_at`);
|