@k2b/cloud 0.6.0-rc.0

package/src/services/settings/snapshot.ts

@@ -0,0 +1,49 @@
+/**
+ * Per-request settings snapshot.
+ *
+ * Loads every known setting via `bulkRead` (one Redis MGET + DB fallback for
+ * misses) and builds a frozen nested object keyed by dotted-path segments.
+ *
+ * Used by the middleware that runs at request start (see `define-app.ts`).
+ * Exposed on the Hono context as `c.get("settings")` — typed per-app via
+ * `AppContext<typeof app>`.
+ *
+ * The snapshot is read-only and stable for the duration of one request:
+ * later writes (in this or other containers) do not mutate this snapshot.
+ * If a long-running handler needs fresh values, it should use the typed
+ * async API (`app.settings.get(key)`) instead.
+ */
+
+import { allKnownKeys, bulkRead } from "./store";
+
+/** Build a frozen nested object from the registered settings. */
+export const loadSnapshot = async (): Promise<Readonly<Record<string, unknown>>> => {
+  const flat = await bulkRead(allKnownKeys());
+
+  const tree: Record<string, unknown> = {};
+  for (const [key, value] of flat) {
+    const parts = key.split(".");
+    let cursor = tree;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+      const part = parts[i]!;
+      const existing = cursor[part];
+      if (typeof existing !== "object" || existing === null || Array.isArray(existing)) {
+        cursor[part] = {};
+      }
+      cursor = cursor[part] as Record<string, unknown>;
+    }
+    cursor[parts[parts.length - 1]!] = value;
+  }
+
+  return deepFreeze(tree);
+};
+
+const deepFreeze = <T>(obj: T): Readonly<T> => {
+  if (obj === null || typeof obj !== "object") return obj;
+  for (const value of Object.values(obj as Record<string, unknown>)) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+      deepFreeze(value);
+    }
+  }
+  return Object.freeze(obj);
+};

package/src/services/settings/store.ts

@@ -0,0 +1,241 @@
+/**
+ * Settings store — Redis cache-aside read/write primitives.
+ *
+ * Pattern: each key is cached in Redis with a 5-minute TTL. Reads try Redis
+ * first, fall back to DB on miss, and populate Redis. Writes update DB and
+ * delete the Redis key (next reader repopulates with fresh DB state).
+ *
+ * This achieves cross-container coherence without polling or pubsub: a write
+ * in container A invalidates the shared Redis cache; container B's next read
+ * hits Redis (miss after del), goes to DB, sees the new value, repopulates.
+ *
+ * Reads/writes here are async — sync callers should use the per-request
+ * snapshot exposed via `c.get("settings")` (built by snapshot.ts middleware).
+ */
+
+import { redis, sql } from "bun";
+import { toPgTextArray } from "../postgres";
+import { decryptValue, encryptValue } from "./crypto";
+import { SETTINGS, SETTINGS_MAP, type SettingDef, validateSettingValue } from "./defaults";
+
+const REDIS_KEY = (k: string) => `settings:${k}`;
+
+type SqlClient = typeof sql;
+
+/**
+ * Forget cached values so every container re-reads on next access.
+ *
+ * Separate from the write because ordering matters: dropping the cache while a
+ * transaction is still open lets another container miss, read the pre-commit
+ * row and cache *that* for the full TTL. Callers writing inside a transaction
+ * therefore invalidate after it commits.
+ */
+export const invalidateSettingsCache = async (keys: readonly string[]): Promise<void> => {
+  await Promise.all(keys.map((key) => redis.del(REDIS_KEY(key))));
+};
+const REDIS_TTL_SEC = 300;
+
+type StoredRow = { key: string; value: string };
+type LegacyStoredRow = { key: string; value: string; updated_at: Date | string | null };
+
+export type LegacySettingRow = {
+  key: string;
+  updatedAt: string | null;
+  decryptable: boolean;
+};
+
+/**
+ * Resolve the env-fallback or default value for a key whose DB row is missing
+ * or invalid. Mirrors the existing `resolve()` logic in services/settings/index.ts
+ * but takes a SettingDef directly (no global state).
+ */
+const resolveFallback = (def: SettingDef | undefined): unknown => {
+  if (!def) return undefined;
+  const raw = def.envFallback?.();
+  if (raw !== undefined) {
+    const validated = validateSettingValue(def, raw);
+    if (validated.ok) return validated.value;
+  }
+  return def.default;
+};
+
+/**
+ * Read a single setting key. Tries Redis first, falls back to DB.
+ * On DB hit, populates Redis with TTL. On miss, returns env-fallback or default.
+ */
+export const readKey = async (key: string): Promise<unknown> => {
+  const def = SETTINGS_MAP.get(key);
+
+  const cached = await redis.get(REDIS_KEY(key));
+  if (cached !== null) {
+    try {
+      return JSON.parse(cached);
+    } catch {
+      // Corrupt cache entry — drop and re-read from DB.
+      await redis.del(REDIS_KEY(key));
+    }
+  }
+
+  const rows = await sql<StoredRow[]>`SELECT value FROM settings.entries WHERE key = ${key}`;
+  if (rows.length > 0 && rows[0]) {
+    try {
+      const decrypted = await decryptValue(rows[0].value);
+      if (def) {
+        const validated = validateSettingValue(def, decrypted);
+        if (validated.ok) {
+          await redis.set(REDIS_KEY(key), JSON.stringify(validated.value), "EX", REDIS_TTL_SEC);
+          return validated.value;
+        }
+      } else {
+        // No def known — still cache the decrypted value (caller's responsibility to interpret).
+        await redis.set(REDIS_KEY(key), JSON.stringify(decrypted), "EX", REDIS_TTL_SEC);
+        return decrypted;
+      }
+    } catch {
+      // Decryption failure — legacy row encrypted with a different APP_SECRET.
+      // Skip silently and fall through to env/default fallback.
+    }
+  }
+
+  return resolveFallback(def);
+};
+
+/**
+ * Bulk read for snapshot construction. One Redis MGET round-trip, DB fallback
+ * for misses (single SELECT with key = ANY), populates Redis for missed keys.
+ *
+ * Returns a Map keyed by the input keys; every input key is present in the
+ * result (with env-fallback or default as last resort).
+ */
+export const bulkRead = async (keys: readonly string[]): Promise<Map<string, unknown>> => {
+  const result = new Map<string, unknown>();
+  if (keys.length === 0) return result;
+
+  // 1. Redis MGET — one round-trip
+  const cached = await redis.mget(...keys.map(REDIS_KEY));
+  const missing: string[] = [];
+  for (let i = 0; i < keys.length; i += 1) {
+    const k = keys[i]!;
+    const c = cached[i];
+    if (c !== null && c !== undefined) {
+      try {
+        result.set(k, JSON.parse(c));
+        continue;
+      } catch {
+        // Drop corrupt cache entry, treat as missing.
+      }
+    }
+    missing.push(k);
+  }
+
+  // 2. Fetch missing from DB in one query (Bun sql can't serialize JS arrays
+  // for ANY(), so we hand-build the Postgres TEXT[] literal).
+  if (missing.length > 0) {
+    const rows = await sql<StoredRow[]>`SELECT key, value FROM settings.entries WHERE key = ANY(${toPgTextArray(missing)}::text[])`;
+    for (const row of rows) {
+      try {
+        const decrypted = await decryptValue(row.value);
+        const def = SETTINGS_MAP.get(row.key);
+        if (def) {
+          const validated = validateSettingValue(def, decrypted);
+          if (validated.ok) {
+            result.set(row.key, validated.value);
+            await redis.set(REDIS_KEY(row.key), JSON.stringify(validated.value), "EX", REDIS_TTL_SEC);
+          }
+        } else {
+          result.set(row.key, decrypted);
+          await redis.set(REDIS_KEY(row.key), JSON.stringify(decrypted), "EX", REDIS_TTL_SEC);
+        }
+      } catch {
+        // Legacy row with mismatched key — silent skip.
+      }
+    }
+  }
+
+  // 3. Apply env-fallback / default for keys that are still missing
+  for (const k of keys) {
+    if (!result.has(k)) {
+      result.set(k, resolveFallback(SETTINGS_MAP.get(k)));
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Get every known setting key (across all registered defs).
+ * Used by snapshot loader to determine what to bulk-read.
+ */
+export const allKnownKeys = (): string[] => SETTINGS.map((d) => d.key);
+
+const knownKeysWith = (extraKnownKeys: readonly string[]) => Array.from(new Set([...allKnownKeys(), ...extraKnownKeys]));
+
+export const listLegacyKeys = async (extraKnownKeys: readonly string[] = []): Promise<LegacySettingRow[]> => {
+  const knownKeys = knownKeysWith(extraKnownKeys);
+  const rows = await sql<LegacyStoredRow[]>`
+    SELECT key, value, updated_at
+    FROM settings.entries
+    WHERE NOT (key = ANY(${toPgTextArray(knownKeys)}::text[]))
+    ORDER BY updated_at DESC NULLS LAST, key ASC
+  `;
+
+  const legacy: LegacySettingRow[] = [];
+  for (const row of rows) {
+    let decryptable = true;
+    try {
+      await decryptValue(row.value);
+    } catch {
+      decryptable = false;
+    }
+    legacy.push({
+      key: row.key,
+      updatedAt: row.updated_at ? new Date(row.updated_at).toISOString() : null,
+      decryptable,
+    });
+  }
+  return legacy;
+};
+
+export const deleteLegacyKeys = async (extraKnownKeys: readonly string[] = []): Promise<{ deleted: string[] }> => {
+  const knownKeys = knownKeysWith(extraKnownKeys);
+  const rows = await sql<{ key: string }[]>`
+    DELETE FROM settings.entries
+    WHERE NOT (key = ANY(${toPgTextArray(knownKeys)}::text[]))
+    RETURNING key
+  `;
+  const deleted = rows.map((row) => row.key);
+  if (deleted.length > 0) await redis.del(...deleted.map(REDIS_KEY));
+  return { deleted };
+};
+
+/**
+ * Encrypt the value, upsert the DB row, invalidate the Redis key.
+ *
+ * Validation is the caller's responsibility — the typed wrapper API
+ * (createSettingsAPI) validates against the declared SettingDef before reaching
+ * here. Direct callers must ensure the value matches the setting's kind.
+ */
+export const writeKey = async (key: string, value: unknown, db?: SqlClient): Promise<void> => {
+  const def = SETTINGS_MAP.get(key);
+  if (!def) throw new Error(`Unknown setting: ${key}`);
+  const validated = validateSettingValue(def, value);
+  if (!validated.ok) throw new Error(validated.error);
+
+  const encrypted = await encryptValue(validated.value);
+  await (db ?? sql)`
+    INSERT INTO settings.entries (key, value, updated_at)
+    VALUES (${key}, ${encrypted}, now())
+    ON CONFLICT (key)
+    DO UPDATE SET value = ${encrypted}, updated_at = now()
+  `;
+
+  // Passing a transaction means the caller owns invalidation, because the row
+  // is not visible to anyone else until they commit.
+  if (!db) await invalidateSettingsCache([key]);
+};
+
+/** Delete the DB row and invalidate Redis. See writeKey for the `db` contract. */
+export const deleteKey = async (key: string, db?: SqlClient): Promise<void> => {
+  await (db ?? sql)`DELETE FROM settings.entries WHERE key = ${key}`;
+  if (!db) await invalidateSettingsCache([key]);
+};

package/src/services/settings/templates.ts

@@ -0,0 +1,4 @@
+import { renderLiquidTemplate } from "../../shared/template-rendering";
+
+/** Render a Liquid template with Cloud's legacy-compatible HTML escaping. */
+export const renderTemplate = (template: string, vars: Record<string, unknown>): string => renderLiquidTemplate(template, vars);