@valentinkolb/cloud 0.1.0

package/src/services/settings/index.ts

@@ -0,0 +1,203 @@
+/**
+ * Settings service — runtime-configurable settings backed by Postgres.
+ *
+ * Resolution order: DB value -> env fallback -> code default.
+ *
+ * Custom DB values are encrypted at rest using APP_SECRET. All read/write
+ * goes through the Redis cache-aside layer in `./store.ts` (5-minute TTL).
+ * `loadCache()` runs once at boot to normalize legacy rows and bootstrap
+ * env-backed entries into Postgres.
+ */
+
+import { sql } from "bun";
+import { env } from "../../config/env";
+import { encryptValue, decryptValue, getAppSecret } from "./crypto";
+import {
+  SETTINGS,
+  SETTINGS_MAP,
+  getSettingLabel,
+  type SettingDef,
+  type SettingKind,
+  type SettingOption,
+  validateSettingValue,
+} from "./defaults";
+import { readKey, writeKey, deleteKey, bulkRead } from "./store";
+
+type StoredRow = { key: string; value: string };
+type PendingRow = { key: string; value: unknown; rewrite: boolean; existed: boolean };
+type NormalizationStats = {
+  encryptedLoaded: number;
+  normalizedUpdated: number;
+  envBootstrapped: number;
+  invalidSkipped: number;
+};
+
+const isEqual = (left: unknown, right: unknown): boolean => JSON.stringify(left) === JSON.stringify(right);
+
+const resolveEnvValue = (def: SettingDef | undefined, mode: "fallback" | "bootstrap"): unknown => {
+  const raw = mode === "fallback" ? def?.envFallback?.() : def?.envBootstrap?.();
+  if (!def || raw === undefined) return undefined;
+
+  const validated = validateSettingValue(def, raw);
+  if (!validated.ok) {
+    console.warn(`[settings] ignoring invalid ${mode} value for "${def.key}": ${validated.error}`);
+    return undefined;
+  }
+
+  return validated.value;
+};
+
+const shouldBootstrapValue = (def: SettingDef, value: unknown): boolean => {
+  if (value === undefined || value === null) return false;
+
+  switch (def.kind) {
+    case "boolean":
+      return value === true;
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "string_list":
+    case "number_list":
+      return Array.isArray(value) && value.length > 0;
+    default:
+      return typeof value === "string" && value.trim().length > 0;
+  }
+};
+
+const upsertEncryptedRow = async (key: string, value: unknown): Promise<void> => {
+  const encryptedValue = await encryptValue(value);
+  await sql`
+    INSERT INTO settings.entries (key, value, updated_at)
+    VALUES (${key}, ${encryptedValue}, now())
+    ON CONFLICT (key)
+    DO UPDATE SET value = ${encryptedValue}, updated_at = now()
+  `;
+};
+
+const normalizeStoredEntries = async (): Promise<{ rows: Array<{ key: string; value: unknown }>; stats: NormalizationStats }> => {
+  const rows = await sql<StoredRow[]>`SELECT key, value FROM settings.entries`;
+  const stats: NormalizationStats = {
+    encryptedLoaded: 0,
+    normalizedUpdated: 0,
+    envBootstrapped: 0,
+    invalidSkipped: 0,
+  };
+  const pendingRows = new Map<string, PendingRow>();
+
+  for (const row of rows) {
+    try {
+      const value = await decryptValue(row.value);
+      pendingRows.set(row.key, { key: row.key, value, rewrite: false, existed: true });
+      stats.encryptedLoaded += 1;
+    } catch {
+      console.warn(`[settings] skipping invalid stored value for "${row.key}"`);
+      stats.invalidSkipped += 1;
+    }
+  }
+
+  const normalized: Array<{ key: string; value: unknown }> = [];
+
+  for (const [key, row] of pendingRows.entries()) {
+    const def = SETTINGS_MAP.get(key);
+    if (!def) {
+      console.warn(`[settings] skipping unknown stored key "${key}"`);
+      stats.invalidSkipped += 1;
+      continue;
+    }
+
+    const validated = validateSettingValue(def, row.value);
+    if (!validated.ok) {
+      console.warn(`[settings] skipping invalid value for "${key}": ${validated.error}`);
+      stats.invalidSkipped += 1;
+      continue;
+    }
+
+    normalized.push({ key, value: validated.value });
+
+    if (row.rewrite || !row.existed || !isEqual(row.value, validated.value)) {
+      await upsertEncryptedRow(key, validated.value);
+      stats.normalizedUpdated += 1;
+    }
+  }
+
+  return { rows: normalized, stats };
+};
+
+const bootstrapEnvBackedEntries = async (config: {
+  rows: Array<{ key: string; value: unknown }>;
+  stats: NormalizationStats;
+}): Promise<Array<{ key: string; value: unknown }>> => {
+  const rowsByKey = new Map(config.rows.map((row) => [row.key, row.value]));
+
+  for (const def of SETTINGS) {
+    if (rowsByKey.has(def.key)) continue;
+
+    const envValue = resolveEnvValue(def, "bootstrap");
+    if (!shouldBootstrapValue(def, envValue)) continue;
+
+    await upsertEncryptedRow(def.key, envValue);
+    rowsByKey.set(def.key, envValue);
+    config.stats.envBootstrapped += 1;
+  }
+
+  return [...rowsByKey.entries()].map(([key, value]) => ({ key, value }));
+};
+
+/**
+ * Boot-time normalization + env-bootstrap. Runs once at startup. Does NOT
+ * populate any in-process cache — every read goes through Redis cache-aside
+ * (`store.ts`) at request time.
+ */
+export async function loadCache(): Promise<void> {
+  getAppSecret();
+  const { rows, stats } = await normalizeStoredEntries();
+  const bootstrappedRows = await bootstrapEnvBackedEntries({ rows, stats });
+
+  console.log(
+    `[settings] loaded ${bootstrappedRows.length} custom setting(s) (${stats.encryptedLoaded} encrypted, ${stats.normalizedUpdated} normalized, ${stats.envBootstrapped} env-bootstrapped, ${stats.invalidSkipped} skipped)`,
+  );
+}
+
+/**
+ * Read a setting via the Redis cache-aside layer (always within Redis-TTL
+ * fresh). Resolution: Redis cache → Postgres → env-fallback → code default.
+ */
+export async function get<T = unknown>(key: string): Promise<T> {
+  return readKey(key) as Promise<T>;
+}
+
+export async function set(key: string, value: unknown): Promise<void> {
+  await writeKey(key, value);
+}
+
+export async function remove(key: string): Promise<void> {
+  await deleteKey(key);
+}
+
+import type { SettingEntry } from "../../contracts/shared";
+export type { SettingEntry } from "../../contracts/shared";
+
+export async function getAll(): Promise<SettingEntry[]> {
+  // Determine which keys have a custom row in Postgres (vs. falling back to
+  // env / code default). One indexed scan, then bulk-read all values.
+  const customRows = await sql<{ key: string }[]>`SELECT key FROM settings.entries`;
+  const customKeys = new Set(customRows.map((row) => row.key));
+
+  const allKeys = SETTINGS.map((def) => def.key);
+  const values = await bulkRead(allKeys);
+
+  return SETTINGS.map((def) => ({
+    key: def.key,
+    label: getSettingLabel(def),
+    kind: def.kind,
+    description: def.description,
+    placeholder: def.placeholder,
+    group: def.group,
+    value: values.get(def.key),
+    default: def.default,
+    isCustom: customKeys.has(def.key),
+    templateVars: "templateVars" in def ? def.templateVars : undefined,
+    options: "options" in def ? def.options : undefined,
+    min: "min" in def ? def.min : undefined,
+    max: "max" in def ? def.max : undefined,
+  }));
+}

package/src/services/settings/namespace.ts

@@ -0,0 +1,9 @@
+import { get, getAll, loadCache, remove, set } from "./index";
+
+export const settings = {
+  loadCache,
+  get,
+  set,
+  remove,
+  getAll,
+};

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,179 @@
+/**
+ * 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 { decryptValue, encryptValue } from "./crypto";
+import { SETTINGS, SETTINGS_MAP, validateSettingValue, type SettingDef } from "./defaults";
+import { toPgTextArray } from "../postgres";
+
+const REDIS_KEY = (k: string) => `settings:${k}`;
+const REDIS_TTL_SEC = 300;
+
+type StoredRow = { key: string; value: string };
+
+/**
+ * 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);
+
+/**
+ * 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): 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 sql`
+    INSERT INTO settings.entries (key, value, updated_at)
+    VALUES (${key}, ${encrypted}, now())
+    ON CONFLICT (key)
+    DO UPDATE SET value = ${encrypted}, updated_at = now()
+  `;
+
+  // Invalidate the cache so other containers re-read on next access.
+  await redis.del(REDIS_KEY(key));
+};
+
+/** Delete the DB row and invalidate Redis. */
+export const deleteKey = async (key: string): Promise<void> => {
+  await sql`DELETE FROM settings.entries WHERE key = ${key}`;
+  await redis.del(REDIS_KEY(key));
+};

package/src/services/settings/templates.ts

@@ -0,0 +1,10 @@
+/**
+ * Mustache-based template rendering for email templates stored in settings.
+ */
+
+import Mustache from "mustache";
+
+/** Render a mustache template with variables. */
+export function renderTemplate(template: string, vars: Record<string, string>): string {
+  return Mustache.render(template, vars);
+}