@rfc0/patty 1.0.2 → 1.2.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,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
- export const NEVER_BLOCK_IN_SQLITE_MS = 0;
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
- cachedByUser.set(userId, locale);
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;
@@ -2,6 +2,9 @@ import { z } from 'zod';
2
2
  import { reasonOf } from './error.js';
3
3
  /** Why a client's configuration file could not be used (expected failures of `setup`). */
4
4
  export const ClientConfigFailureCode = z.enum(['read_failed', 'write_failed']);
5
+ /** What every refusal of an unusable client file says first, and last. */
6
+ export const INVALID_ROOT_MESSAGE = 'does not contain a JSON object at the root';
7
+ export const LEFT_UNCHANGED = ' — left unchanged';
5
8
  export const clientConfigFailures = {
6
9
  readFailed: (path, cause) => ({
7
10
  code: ClientConfigFailureCode.enum.read_failed,
@@ -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() });
@@ -1,2 +1,14 @@
1
1
  import { z } from 'zod';
2
2
  export const ServersKey = z.enum(['mcpServers', 'servers']);
3
+ /** Where a client's MCP entry keeps its environment variables. */
4
+ export const EnvKey = z.enum(['env', 'environment']);
5
+ /** What an OpenCode config's `mcp` key says about its layout. */
6
+ export const McpLayout = z.enum([
7
+ /** No `mcp` key, or an empty one: the V2 shape is created. */
8
+ 'fresh',
9
+ 'v2',
10
+ /** Servers directly under `mcp`, no `mcp.servers`. */
11
+ 'v1',
12
+ /** `mcp` or `mcp.servers` exists but is not an object. */
13
+ 'malformed',
14
+ ]);
@@ -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`);