@gloom-sh/terminal 0.19.1 → 0.19.3

package/src/data/resource-store.ts

@@ -1,8 +1,9 @@
 import type { Database } from "bun:sqlite";
 import type { CachePolicy, PersistedResourceValue } from "../types/persistence";
 import type { JsonValue } from "./sqlite/json";
+import { createSqliteAccess, type SqliteAccess } from "./sqlite/access";
 import { safeParseJson, serializeJson } from "./sqlite/json";
-import { trySqliteBusyOperation, withSqliteBusyRetry } from "./sqlite/retry";
+import { logFailure } from "../utils/log-failure";
 
 const RESOURCE_CACHE_SOFT_ROW_LIMIT = 25_000;
 const RESOURCE_CACHE_SOFT_SIZE_LIMIT = 100 * 1024 * 1024;
@@ -13,6 +14,13 @@ const RESOURCE_CACHE_MAINTENANCE_BYTE_INTERVAL = Math.floor(
 const RESOURCE_CACHE_MAINTENANCE_TIME_INTERVAL_MS = 5 * 60_000;
 /** Rows read per eviction pass, so a full cache is evicted in slices. */
 const RESOURCE_CACHE_PRUNE_BATCH_SIZE = 512;
+/**
+ * A read moves its row up the eviction order in memory, and the rows read
+ * since are written in one transaction this often, before an eviction and
+ * at close: a read writes nothing. A crash loses at most this much of the
+ * order, which only decides what is evicted first.
+ */
+const RESOURCE_CACHE_TOUCH_FLUSH_MS = 30_000;
 const DEFAULT_RESOURCE_SCHEMA_VERSION = 1;
 const EMPTY_VARIANT_KEY = "";
 const EMPTY_SOURCE_KEY = "";
@@ -93,6 +101,10 @@ function isStale(staleAt: number): boolean {
   return staleAt < Date.now();
 }
 
+function rowMapKey(key: ResourceCacheKey): string {
+  return [key.namespace, key.kind, key.entityKey, normalizeVariantKey(key.variantKey), normalizeSourceKey(key.sourceKey)].join("\u0000");
+}
+
 function sortRows(rows: ResourceCacheRow[]): ResourceCacheRow[] {
   return [...rows].sort((a, b) => {
     if (a.expires_at !== b.expires_at) return b.expires_at - a.expires_at;
@@ -106,8 +118,18 @@ export class ResourceStore {
   private writesSinceMaintenance = 0;
   private bytesWrittenSinceMaintenance = 0;
   private lastMaintenanceAt = 0;
+  /** Reads not yet written to the eviction order, by row. */
+  private readonly pendingTouches = new Map<string, { key: ResourceCacheKey; touchedAt: number }>();
+  private touchTimer: ReturnType<typeof setTimeout> | null = null;
 
-  constructor(private readonly db: Database) {}
+  /**
+   * Everything here can be fetched again, so no statement waits for another
+   * program's lock: a locked read is a miss, and a locked write is skipped.
+   */
+  constructor(
+    private readonly db: Database,
+    private readonly access: SqliteAccess = createSqliteAccess(db),
+  ) {}
 
   private toCachedResource<T>(row: ResourceCacheRow): CachedResourceRecord<T> | null {
     const value = safeParseJson<T>(row.payload);
@@ -132,7 +154,8 @@ export class ResourceStore {
   }
 
   private deleteExact(key: ResourceCacheKey): void {
-    withSqliteBusyRetry("delete cached resource", () => {
+    this.pendingTouches.delete(rowMapKey(key));
+    this.access.writeCache("delete cached resource", () => {
       this.db
         .query(
           `DELETE FROM resource_cache
@@ -148,74 +171,124 @@ export class ResourceStore {
     });
   }
 
-  private touchDue(record: { lastAccessedAt: number }, options: GetResourceOptions): boolean {
-    return options.touchIntervalMs == null || Date.now() - record.lastAccessedAt >= options.touchIntervalMs;
+  /** Moves a read row up the eviction order, unless it moved within `touchIntervalMs`. */
+  private touchRead(record: CachedResourceRecord, options: GetResourceOptions): void {
+    const mapKey = rowMapKey(record);
+    record.lastAccessedAt = Math.max(record.lastAccessedAt, this.pendingTouches.get(mapKey)?.touchedAt ?? 0);
+    if (options.touch === false) return;
+    const now = Date.now();
+    if (options.touchIntervalMs != null && now - record.lastAccessedAt < options.touchIntervalMs) return;
+    const { namespace, kind, entityKey, variantKey, sourceKey } = record;
+    this.pendingTouches.set(mapKey, { key: { namespace, kind, entityKey, variantKey, sourceKey }, touchedAt: now });
+    record.lastAccessedAt = now;
+    if (this.touchTimer) return;
+    this.touchTimer = setTimeout(() => {
+      this.touchTimer = null;
+      try {
+        this.flushTouches();
+      } catch (error) {
+        logFailure("data.resource-store", "Saving the cache's eviction order failed")(error);
+      }
+    }, RESOURCE_CACHE_TOUCH_FLUSH_MS);
+    (this.touchTimer as { unref?: () => void }).unref?.();
   }
 
-  private touch(key: ResourceCacheKey): number | null {
-    const touchedAt = Date.now();
-    const result = trySqliteBusyOperation("touch cached resource", () => {
-      this.db
-        .query(
-          `UPDATE resource_cache
-           SET last_accessed_at = ?
-           WHERE namespace = ? AND kind = ? AND entity_key = ? AND variant_key = ? AND source_key = ?`,
-        )
-        .run(
-          touchedAt,
-          key.namespace,
-          key.kind,
-          key.entityKey,
-          normalizeVariantKey(key.variantKey),
-          normalizeSourceKey(key.sourceKey),
-        );
-      return touchedAt;
+  /**
+   * Writes the reads since the last flush into the eviction order, in one
+   * transaction. False when another program had the cache locked; they are
+   * kept for the next one.
+   */
+  flushTouches(): boolean {
+    if (this.touchTimer) {
+      clearTimeout(this.touchTimer);
+      this.touchTimer = null;
+    }
+    if (this.pendingTouches.size === 0) return true;
+    const touches = [...this.pendingTouches.values()];
+    const written = this.access.writeCache("touch cached resources", () => {
+      const update = this.db.query(
+        `UPDATE resource_cache
+         SET last_accessed_at = MAX(last_accessed_at, ?)
+         WHERE namespace = ? AND kind = ? AND entity_key = ? AND variant_key = ? AND source_key = ?`,
+      );
+      this.db.transaction(() => {
+        for (const { key, touchedAt } of touches) {
+          update.run(
+            touchedAt,
+            key.namespace,
+            key.kind,
+            key.entityKey,
+            normalizeVariantKey(key.variantKey),
+            normalizeSourceKey(key.sourceKey),
+          );
+        }
+      })();
     });
-    return result;
+    if (written) this.pendingTouches.clear();
+    return written;
+  }
+
+  /**
+   * Writes the reads still held in memory; the connection closes after. A
+   * failure loses only that order: the queued user writes and the
+   * connection still have to close.
+   */
+  close(): void {
+    try {
+      this.flushTouches();
+    } catch (error) {
+      logFailure("data.resource-store", "Saving the cache's eviction order at close failed")(error);
+    }
+    if (this.touchTimer) clearTimeout(this.touchTimer);
+    this.touchTimer = null;
   }
 
-  private readCacheFootprint(operationName: string): { count: number; totalSize: number } {
-    const stats = withSqliteBusyRetry(operationName, () => (
+  /** Null when another program has the cache locked; maintenance waits for the next write. */
+  private readCacheFootprint(operationName: string): { count: number; totalSize: number } | null {
+    const stats = this.access.readCache(operationName, () => (
       this.db
         .query<{ count: number; total_size: number }, []>(
           "SELECT COUNT(*) as count, COALESCE(SUM(size_bytes), 0) as total_size FROM resource_cache",
         )
         .get()
     ));
-    return { count: stats?.count ?? 0, totalSize: stats?.total_size ?? 0 };
+    return stats ? { count: stats.count ?? 0, totalSize: stats.total_size ?? 0 } : null;
   }
 
   private withinSoftLimits(count: number, totalSize: number): boolean {
     return count <= RESOURCE_CACHE_SOFT_ROW_LIMIT && totalSize <= RESOURCE_CACHE_SOFT_SIZE_LIMIT;
   }
 
-  private pruneIfNeeded(): void {
-    const { count, totalSize } = this.readCacheFootprint("read resource cache size");
-    if (this.withinSoftLimits(count, totalSize)) return;
+  /** False when another program had the cache locked and pruning has to try again later. */
+  private pruneIfNeeded(): boolean {
+    const footprint = this.readCacheFootprint("read resource cache size");
+    if (!footprint) return false;
+    if (this.withinSoftLimits(footprint.count, footprint.totalSize)) return true;
 
-    withSqliteBusyRetry("prune expired cached resources", () => {
+    const prunedExpired = this.access.writeCache("prune expired cached resources", () => {
       this.db.query("DELETE FROM resource_cache WHERE expires_at < ?").run(Date.now());
     });
-
-    let { count: remainingCount, totalSize: remainingSize } = this.readCacheFootprint("read pruned resource cache size");
-    if (this.withinSoftLimits(remainingCount, remainingSize)) return;
-
-    const candidates = this.db.query<{
-      namespace: string;
-      kind: string;
-      entity_key: string;
-      variant_key: string;
-      source_key: string;
-      size_bytes: number;
-    }, [number]>(
-      `SELECT namespace, kind, entity_key, variant_key, source_key, size_bytes
+    if (!prunedExpired) return false;
+
+    const remaining = this.readCacheFootprint("read pruned resource cache size");
+    if (!remaining) return false;
+    let { count: remainingCount, totalSize: remainingSize } = remaining;
+    if (this.withinSoftLimits(remainingCount, remainingSize)) return true;
+    // Eviction goes by the order on disk, which has to hold the latest reads.
+    if (!this.flushTouches()) return false;
+
+    // Only the row ids, which the recency index holds: a row's size sits
+    // after its payload, and reading it walks the whole payload from disk.
+    // Asking it of the oldest 512 rows read 10 MB to pick what to evict.
+    const candidates = this.db.query<{ rowid: number }, [number]>(
+      `SELECT rowid
        FROM resource_cache
        ORDER BY last_accessed_at ASC, fetched_at ASC
        LIMIT ?`,
     );
-    const remove = this.db.query(
-      `DELETE FROM resource_cache
-       WHERE namespace = ? AND kind = ? AND entity_key = ? AND variant_key = ? AND source_key = ?`,
+    // Deleting a row reads its payload anyway, to free it: the size comes along.
+    const remove = this.db.query<{ size_bytes: number }, [number]>(
+      "DELETE FROM resource_cache WHERE rowid = ? RETURNING size_bytes",
     );
 
     // A cache at its limit holds tens of thousands of rows, so eviction reads
@@ -223,29 +296,31 @@ export class ResourceStore {
     // for more only if it is still over. Reading every row first turned the
     // moment the cache filled up into a multi-second pause.
     while (!this.withinSoftLimits(remainingCount, remainingSize)) {
-      const batch = withSqliteBusyRetry("select cached resources to prune", () => (
+      const batch = this.access.readCache("select cached resources to prune", () => (
         candidates.all(RESOURCE_CACHE_PRUNE_BATCH_SIZE)
       ));
-      if (batch.length === 0) return;
-
-      const rowsToDelete = [] as typeof batch;
-      for (const row of batch) {
-        if (this.withinSoftLimits(remainingCount, remainingSize)) break;
-        rowsToDelete.push(row);
-        remainingCount -= 1;
-        remainingSize -= row.size_bytes;
-      }
-      if (rowsToDelete.length === 0) return;
+      if (!batch) return false;
+      if (batch.length === 0) return true;
 
-      withSqliteBusyRetry("prune least recently used cached resources", () => {
+      let left = { count: remainingCount, size: remainingSize };
+      const pruned = this.access.writeCache("prune least recently used cached resources", () => {
+        left = { count: remainingCount, size: remainingSize };
         const tx = this.db.transaction(() => {
-          for (const row of rowsToDelete) {
-            remove.run(row.namespace, row.kind, row.entity_key, row.variant_key, row.source_key);
+          for (const { rowid } of batch) {
+            if (this.withinSoftLimits(left.count, left.size)) break;
+            const removed = remove.get(rowid);
+            if (!removed) continue;
+            left.count -= 1;
+            left.size -= removed.size_bytes;
           }
         });
         tx();
       });
+      if (!pruned) return false;
+      remainingCount = left.count;
+      remainingSize = left.size;
     }
+    return true;
   }
 
   private maintainCacheAfterWrite(now: number, sizeBytes: number): void {
@@ -257,14 +332,14 @@ export class ResourceStore {
       || now - this.lastMaintenanceAt >= RESOURCE_CACHE_MAINTENANCE_TIME_INTERVAL_MS;
     if (!maintenanceDue) return;
 
-    this.pruneIfNeeded();
+    if (!this.pruneIfNeeded()) return;
     this.writesSinceMaintenance = 0;
     this.bytesWrittenSinceMaintenance = 0;
     this.lastMaintenanceAt = now;
   }
 
   get<T>(key: ResourceCacheKey, options: GetResourceOptions = {}): CachedResourceRecord<T> | null {
-    const row = withSqliteBusyRetry("load cached resource", () => (
+    const row = this.access.readCache("load cached resource", () => (
       this.db
         .query<ResourceCacheRow, [string, string, string, string, string]>(
           `SELECT namespace, kind, entity_key, variant_key, source_key, schema_version, payload, provenance,
@@ -294,12 +369,7 @@ export class ResourceStore {
       return null;
     }
 
-    if (options.touch !== false && this.touchDue(record, options)) {
-      const touchedAt = this.touch(key);
-      if (touchedAt != null) {
-        record.lastAccessedAt = touchedAt;
-      }
-    }
+    this.touchRead(record, options);
     return record;
   }
 
@@ -307,25 +377,33 @@ export class ResourceStore {
     key: Pick<ResourceCacheKey, "namespace" | "kind" | "entityKey">,
     options: ListResourceOptions = {},
   ): CachedResourceRecord<T>[] {
-    const rows = withSqliteBusyRetry("list cached resources", () => (
+    const variantKeys = options.variantKeys ? [...new Set(options.variantKeys.map(normalizeVariantKey))] : null;
+    const sourceKeys = options.sourceKeys ? [...new Set(options.sourceKeys.map(normalizeSourceKey))] : null;
+    if (variantKeys?.length === 0 || sourceKeys?.length === 0) return [];
+    // The rows asked for only: an entity can hold dozens of variants (every
+    // range of a price history, from every source), megabytes of payload
+    // that a filter after the read threw away. The keys come from the
+    // primary key's index. Expiry stays below: the column sits after the
+    // payload, and checking it here walked a 10 MB payload twice.
+    const filters = [
+      ...(variantKeys ? [`variant_key IN (${variantKeys.map(() => "?").join(", ")})`] : []),
+      ...(sourceKeys ? [`source_key IN (${sourceKeys.map(() => "?").join(", ")})`] : []),
+    ];
+    const params: string[] = [key.namespace, key.kind, key.entityKey, ...(variantKeys ?? []), ...(sourceKeys ?? [])];
+    const rows = this.access.readCache("list cached resources", () => (
       this.db
-        .query<ResourceCacheRow, [string, string, string]>(
+        .query<ResourceCacheRow, string[]>(
           `SELECT namespace, kind, entity_key, variant_key, source_key, schema_version, payload, provenance,
                   fetched_at, stale_at, expires_at, last_accessed_at, size_bytes
            FROM resource_cache
-           WHERE namespace = ? AND kind = ? AND entity_key = ?`,
+           WHERE ${["namespace = ?", "kind = ?", "entity_key = ?", ...filters].join(" AND ")}`,
         )
-        .all(key.namespace, key.kind, key.entityKey)
-    ));
-
-    const allowedVariantKeys = options.variantKeys ? new Set(options.variantKeys.map(normalizeVariantKey)) : null;
-    const allowedSourceKeys = options.sourceKeys ? new Set(options.sourceKeys.map(normalizeSourceKey)) : null;
+        .all(...params)
+    )) ?? [];
 
     const records: CachedResourceRecord<T>[] = [];
     for (const row of sortRows(rows)) {
       if (!options.allowExpired && isExpired(row.expires_at)) continue;
-      if (allowedVariantKeys && !allowedVariantKeys.has(row.variant_key)) continue;
-      if (allowedSourceKeys && !allowedSourceKeys.has(row.source_key)) continue;
       if (options.schemaVersion != null && row.schema_version !== options.schemaVersion) {
         this.deleteExact({
           namespace: row.namespace,
@@ -349,13 +427,7 @@ export class ResourceStore {
       }
       records.push(record);
     }
-    if (options.touch !== false) {
-      for (const record of records) {
-        if (!this.touchDue(record, options)) continue;
-        const touchedAt = this.touch(record);
-        if (touchedAt != null) record.lastAccessedAt = touchedAt;
-      }
-    }
+    for (const record of records) this.touchRead(record, options);
     return records;
   }
 
@@ -375,7 +447,8 @@ export class ResourceStore {
       sourceKey: normalizeSourceKey(key.sourceKey),
     };
 
-    withSqliteBusyRetry("save cached resource", () => {
+    this.pendingTouches.delete(rowMapKey(rowKey));
+    const saved = this.access.writeCache("save cached resource", () => {
       this.db
         .query(
           `INSERT OR REPLACE INTO resource_cache (
@@ -400,7 +473,7 @@ export class ResourceStore {
         );
     });
 
-    this.maintainCacheAfterWrite(Date.now(), sizeBytes);
+    if (saved) this.maintainCacheAfterWrite(Date.now(), sizeBytes);
     return {
       ...rowKey,
       value: JSON.parse(payload) as T,
@@ -420,14 +493,16 @@ export class ResourceStore {
     this.deleteExact(key);
   }
 
+  /** Asked for by the user, so it waits for another program's lock, and throws when it cannot get it. */
   clear(namespace?: string): void {
     if (!namespace) {
-      withSqliteBusyRetry("clear cached resources", () => {
+      this.pendingTouches.clear();
+      this.access.run("clear cached resources", () => {
         this.db.query("DELETE FROM resource_cache").run();
       });
       return;
     }
-    withSqliteBusyRetry("clear namespaced cached resources", () => {
+    this.access.run("clear namespaced cached resources", () => {
       this.db.query("DELETE FROM resource_cache WHERE namespace = ?").run(namespace);
     });
   }

package/src/data/session-store.ts

@@ -1,6 +1,6 @@
 import type { Database } from "bun:sqlite";
+import { createSqliteAccess, type SqliteAccess } from "./sqlite/access";
 import { safeParseJson, serializeJson } from "./sqlite/json";
-import { withSqliteBusyRetry } from "./sqlite/retry";
 
 const DEFAULT_SESSION_SCHEMA_VERSION = 1;
 
@@ -11,11 +11,23 @@ export interface SessionSnapshotRecord<T = unknown> {
   updatedAt: number;
 }
 
+/** A queued write's row (null for a delete), one object per write. */
+interface PendingSession {
+  row: { schema_version: number; value: string; updated_at: number } | null;
+}
+
 export class SessionStore {
-  constructor(private readonly db: Database) {}
+  /** Writes queued behind another program's lock, read back until they land. */
+  private readonly pending = new Map<string, PendingSession>();
+
+  constructor(
+    private readonly db: Database,
+    private readonly access: SqliteAccess = createSqliteAccess(db),
+  ) {}
 
   get<T>(sessionId = "app", schemaVersion = DEFAULT_SESSION_SCHEMA_VERSION): SessionSnapshotRecord<T> | null {
-    const row = withSqliteBusyRetry("load session snapshot", () => (
+    const pending = this.pending.get(sessionId);
+    const row = pending ? pending.row : this.access.run("load session snapshot", () => (
       this.db
         .query<{ schema_version: number; value: string; updated_at: number }, [string]>(
           "SELECT schema_version, value, updated_at FROM session_snapshots WHERE session_id = ?",
@@ -24,12 +36,12 @@ export class SessionStore {
     ));
     if (!row) return null;
     if (row.schema_version !== schemaVersion) {
-      this.delete(sessionId);
+      if (!pending) this.delete(sessionId);
       return null;
     }
     const value = safeParseJson<T>(row.value);
     if (value == null) {
-      this.delete(sessionId);
+      if (!pending) this.delete(sessionId);
       return null;
     }
     return {
@@ -41,19 +53,30 @@ export class SessionStore {
   }
 
   set(sessionId: string, value: unknown, schemaVersion = DEFAULT_SESSION_SCHEMA_VERSION): void {
-    withSqliteBusyRetry("save session snapshot", () => {
+    const row = { schema_version: schemaVersion, value: serializeJson(value), updated_at: Date.now() };
+    this.write("save session snapshot", sessionId, { row }, () => {
       this.db
         .query(
           `INSERT OR REPLACE INTO session_snapshots (session_id, schema_version, value, updated_at)
            VALUES (?, ?, ?, ?)`,
         )
-        .run(sessionId, schemaVersion, serializeJson(value), Date.now());
+        .run(sessionId, row.schema_version, row.value, row.updated_at);
     });
   }
 
   delete(sessionId: string): void {
-    withSqliteBusyRetry("delete session snapshot", () => {
+    this.write("delete session snapshot", sessionId, { row: null }, () => {
       this.db.query("DELETE FROM session_snapshots WHERE session_id = ?").run(sessionId);
     });
   }
+
+  private write(operationName: string, sessionId: string, entry: PendingSession, statement: () => void): void {
+    this.pending.set(sessionId, entry);
+    this.access.write(operationName, statement, {
+      key: `session_snapshots\u0000${sessionId}`,
+      settled: () => {
+        if (this.pending.get(sessionId) === entry) this.pending.delete(sessionId);
+      },
+    });
+  }
 }