bunsane 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to bunsane are documented here.
 
+## 0.5.0 — 2026-06-15
+
+### Added
+
+- **`/health` write probe** — the deep health check now exercises a real write
+  through the same `db.transaction()` path `Entity.save` uses (a temp-table
+  insert dropped on commit, no persistent side effect), instead of a read-only
+  `SELECT 1`. A wedged write pool — one where reads stay healthy but writes hang
+  — now fails liveness so orchestrators restart the container instead of it
+  serving timeouts indefinitely. Configurable via `HEALTH_DB_WRITE_PROBE`
+  (default on) and `DB_HEALTH_WRITE_TIMEOUT` (default 5000 ms). When the probe
+  fails or times out, `/health` returns 503.
+- **`DB_DISABLE_PREPARE`** — set to `true` to disable Bun SQL's automatic
+  server-side prepared statements (`prepare: false`). **Required behind PgBouncer
+  in transaction pooling mode**, where per-connection prepared statements break
+  across pooled backends and can wedge the write path. Default behavior is
+  unchanged (prepared statements remain on).
+- **`docs/CONFIGURATION.md`** — full environment-variable reference, including a
+  PgBouncer deployment section and the health-check/liveness guidance above.
+
+### Behavior change
+
+- `/health` now performs a database write by default. If you point a liveness
+  probe at `/health`, ensure the write path is reachable, or set
+  `HEALTH_DB_WRITE_PROBE=false` to keep the previous read-only behavior.
+
 ## 0.4.0 — 2026-06-11
 
 ### Performance (2026-06-10 overhaul)

package/core/Entity.ts

@@ -20,6 +20,14 @@ export class Entity implements IEntity {
     // This persists after save() so resolvers can detect removed components
     /** @internal Promoted from private for the core/entity/ submodule split (RFC §3.2). Not part of the public API. */
     public savedRemovedComponents: Set<string> = new Set<string>();
+    /**
+     * @internal Type IDs confirmed absent from the DB during this entity's
+     * lifetime. Used as a negative cache in loadComponent() so repeated
+     * get() probes for optional components skip the SELECT. Invalidated
+     * whenever a component is added (addComponent) or the entity is
+     * reloaded. Not part of the public API.
+     */
+    public _missingComponents: Set<string> = new Set<string>();
     protected _dirty: boolean = false;
 
     constructor(id?: string) {

package/core/cache/RedisCache.ts

@@ -270,18 +270,19 @@ export class RedisCache implements CacheProvider {
      */
     async setMany<T>(entries: Array<{key: string, value: T, ttl?: number}>): Promise<void> {
         try {
+            const compressed = await Promise.all(entries.map(e => CompressionUtils.compressForStorage(e.value)));
+
             const pipeline = this.client.pipeline();
 
-            for (const entry of entries) {
+            entries.forEach((entry, i) => {
                 const prefixedKey = this.prefixKey(entry.key);
-                const serializedValue = await CompressionUtils.compressForStorage(entry.value);
-
+                const serializedValue = compressed[i] as string;
                 if (entry.ttl) {
                     pipeline.setex(prefixedKey, Math.floor(entry.ttl / 1000), serializedValue);
                 } else {
                     pipeline.set(prefixedKey, serializedValue);
                 }
-            }
+            });
 
             await pipeline.exec();
         } catch (error) {

package/core/components/BaseComponent.ts

@@ -7,6 +7,10 @@ import { uuidv7 } from '../../utils/uuid';
 import { getMetadataStorage } from '../metadata';
 const logger = MainLogger.child({ scope: "Components" });
 
+// Cached property-name arrays keyed by typeId. Metadata is immutable after
+// decorator registration, so allocating once per class is safe.
+const _propNamesCache = new Map<string, string[]>();
+
 export class BaseComponent {
     public id: string = "";
     protected _comp_name: string = "";
@@ -26,10 +30,13 @@ export class BaseComponent {
     }
 
     properties(): string[] {
+        const cached = _propNamesCache.get(this._typeId);
+        if (cached) return cached;
         const storage = getMetadataStorage();
         const props = storage.componentProperties.get(this._typeId);
-        if(!props) return [];
-        return props.map(p => p.propertyKey);
+        const names = Object.freeze(props ? props.map(p => p.propertyKey) : []) as string[];
+        _propNamesCache.set(this._typeId, names);
+        return names;
     }
 
     /**

package/core/entity/cacheStrategies.ts

@@ -6,6 +6,7 @@ import { logger } from "../Logger";
 import EntityHookManager from "../EntityHookManager";
 import { EntityDeletedEvent } from "../events/EntityLifecycleEvents";
 import type { SQL } from "bun";
+import { getCacheManager } from "./getCacheManager";
 import type { Entity } from "../Entity";
 
 /**
@@ -15,8 +16,7 @@ import type { Entity } from "../Entity";
  */
 export async function handleCacheAfterSave(entity: Entity, changedComponentTypeIds: string[], removedComponentTypeIds: string[], context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<void> {
     try {
-        // Import CacheManager dynamically to avoid circular dependency
-        const { CacheManager } = await import('../cache/CacheManager');
+        const CacheManager = getCacheManager();
         const cacheManager = CacheManager.getInstance();
         const config = cacheManager.getConfig();
 
@@ -81,7 +81,7 @@ export async function runPostDeleteSideEffects(entity: Entity, softDelete: boole
     }
 
     try {
-        const { CacheManager } = await import('../cache/CacheManager');
+        const CacheManager = getCacheManager();
         const cacheManager = CacheManager.getInstance();
         const config = cacheManager.getConfig();
 

package/core/entity/componentAccess.ts

@@ -14,10 +14,15 @@ import { getMetadataStorage } from "../metadata";
 import { ComponentAddedEvent, ComponentUpdatedEvent, ComponentRemovedEvent } from "../events/EntityLifecycleEvents";
 import { getRequestScope } from "../requestScope";
 import { trackCacheOp } from "./pendingOps";
+import { getCacheManager } from "./getCacheManager";
 import type { Entity } from "../Entity";
 
 export function addComponent(entity: Entity, component: BaseComponent): Entity {
-    entity.components.set(component.getTypeID(), component);
+    const typeId = component.getTypeID();
+    entity.components.set(typeId, component);
+    // A component that just arrived can never be "missing" — clear any
+    // previously recorded absence so future get() calls see the new data.
+    entity._missingComponents.delete(typeId);
     return entity;
 }
 
@@ -55,8 +60,6 @@ export function add<T extends BaseComponent>(entity: Entity, ctor: new (...args:
     const instance = new ctor();
     if (data) {
         Object.assign(instance, data);
-    } else {
-        Object.assign(instance, {});
     }
     addComponent(entity, instance);
     entity.setDirty(true);
@@ -109,7 +112,7 @@ export async function set<T extends BaseComponent>(entity: Entity, ctor: new (..
         // App.shutdown can await it (H-CACHE-1).
         trackCacheOp((async () => {
             try {
-                const { CacheManager } = await import('../cache/CacheManager');
+                const CacheManager = getCacheManager();
                 const cacheManager = CacheManager.getInstance();
                 const config = cacheManager.getConfig();
 
@@ -167,7 +170,7 @@ export function remove<T extends BaseComponent>(entity: Entity, ctor: new (...ar
         // (H-CACHE-1).
         trackCacheOp((async () => {
             try {
-                const { CacheManager } = await import('../cache/CacheManager');
+                const CacheManager = getCacheManager();
                 const cacheManager = CacheManager.getInstance();
                 const config = cacheManager.getConfig();
 
@@ -222,6 +225,7 @@ export async function reload(entity: Entity, opts?: { trx?: SQL; signal?: AbortS
     entity.components.clear();
     entity.removedComponents.clear();
     entity.savedRemovedComponents.clear();
+    entity._missingComponents.clear();
 
     const dbConn = opts?.trx ?? db;
     const rows = await runWithSignal<any[]>(
@@ -291,6 +295,15 @@ async function loadComponent<T extends BaseComponent>(entity: Entity, ctor: new
     // just to read the type id.
     const typeId = typeIdOf(ctor);
 
+    // Negative-cache short-circuit: if we previously confirmed this component
+    // is absent from the DB (and no explicit transaction is in scope that
+    // could see a different snapshot), skip the SELECT entirely.
+    // Skipped when a trx is provided — within a transaction the visibility
+    // horizon may differ from the outer read (stale-read hazard).
+    if (!context?.trx && entity._missingComponents.has(typeId)) {
+        return null;
+    }
+
     // Use transaction if provided, otherwise use default db
     const dbConn = context?.trx ?? db;
 
@@ -353,6 +366,12 @@ async function loadComponent<T extends BaseComponent>(entity: Entity, ctor: new
             addComponent(entity, comp);
             return comp as T;
         } else {
+            // Record the confirmed absence so repeated probes skip the DB.
+            // Only when no explicit trx — within a transaction the caller
+            // may insert the component and probe again in the same scope.
+            if (!context?.trx) {
+                entity._missingComponents.add(typeId);
+            }
             return null;
         }
     } catch (error) {

package/core/entity/getCacheManager.ts

@@ -0,0 +1,10 @@
+// Static import of CacheManager for hot-path use in componentAccess and
+// cacheStrategies. CacheManager's imports are all type-only references back
+// to core/Entity, so there is no runtime circular dependency — static import
+// is safe and avoids the microtask + Promise allocation of a dynamic import
+// on every set/remove/save/delete call.
+import { CacheManager } from '../cache/CacheManager';
+
+export function getCacheManager(): typeof CacheManager {
+    return CacheManager;
+}

package/core/entity/saveEntity.ts

@@ -268,9 +268,11 @@ export async function doSave(entity: Entity, trx: SQL, signal?: AbortSignal): Pr
         }
 
         // Perform updates. Validate all ids up front (synchronous, fails
-        // fast), then fire the UPDATEs together via Promise.all so they
-        // pipeline on the transaction connection instead of paying one
-        // serial round-trip per dirty component.
+        // fast), then issue the UPDATEs sequentially. They were previously
+        // fired together via Promise.all to "pipeline" on the transaction
+        // connection, but multiple concurrent in-flight queries on one
+        // connection deadlock single-backend servers (PGlite test harness),
+        // and a single wire serializes them regardless — no real gain.
         if (componentsToUpdate.length > 0) {
             const traceEnabled = logger.isLevelEnabled?.('trace') === true;
             for (const comp of componentsToUpdate) {
@@ -285,11 +287,9 @@ export async function doSave(entity: Entity, trx: SQL, signal?: AbortSignal): Pr
                     logger.trace({ componentId: comp.id, data: comp.data }, `[Entity.doSave] Updating component`);
                 }
             }
-            await Promise.all(
-                componentsToUpdate.map(comp =>
-                    run(saveTrx`UPDATE components SET data = ${comp.data} WHERE id = ${comp.id}`)
-                )
-            );
+            for (const comp of componentsToUpdate) {
+                await run(saveTrx`UPDATE components SET data = ${comp.data} WHERE id = ${comp.id}`);
+            }
         }
     };
 
@@ -322,19 +322,17 @@ export async function doDelete(entity: Entity, force: boolean = false): Promise<
 
     try {
         await db.transaction(async (trx) => {
-            // Independent tables, no FK constraints — pipeline the
-            // statements on the transaction connection instead of paying
-            // serial round-trips while holding the connection.
+            // Independent tables, no FK constraints. Issued sequentially:
+            // multiple concurrent in-flight queries on one connection
+            // deadlock single-backend servers (PGlite test harness), and a
+            // single wire serializes them anyway — Promise.all gave no real
+            // pipelining here.
             if (force) {
-                await Promise.all([
-                    run(trx`DELETE FROM components WHERE entity_id = ${entity.id}`),
-                    run(trx`DELETE FROM entities WHERE id = ${entity.id}`),
-                ]);
+                await run(trx`DELETE FROM components WHERE entity_id = ${entity.id}`);
+                await run(trx`DELETE FROM entities WHERE id = ${entity.id}`);
             } else {
-                await Promise.all([
-                    run(trx`UPDATE entities SET deleted_at = CURRENT_TIMESTAMP WHERE id = ${entity.id} AND deleted_at IS NULL`),
-                    run(trx`UPDATE components SET deleted_at = CURRENT_TIMESTAMP WHERE entity_id = ${entity.id} AND deleted_at IS NULL`),
-                ]);
+                await run(trx`UPDATE entities SET deleted_at = CURRENT_TIMESTAMP WHERE id = ${entity.id} AND deleted_at IS NULL`);
+                await run(trx`UPDATE components SET deleted_at = CURRENT_TIMESTAMP WHERE entity_id = ${entity.id} AND deleted_at IS NULL`);
             }
         });
         clearTimeout(timeoutHandle);

package/core/health.ts

@@ -1,4 +1,5 @@
 import db from "../database";
+import { runWithSignal } from "../database/cancellable";
 import { CacheManager } from "./cache/CacheManager";
 
 export interface CheckResult {
@@ -13,6 +14,14 @@ export interface HealthResponse {
     checks: {
         database: CheckResult;
         cache: CheckResult;
+        /**
+         * Present only when the DB write probe is enabled (default on).
+         * Exercises the real `db.transaction()` write path so a wedged write
+         * pool — a stuck pooled client or exhausted pool that leaves reads
+         * (`SELECT 1`) healthy — fails the liveness check and the orchestrator
+         * restarts the container instead of it serving 504s indefinitely.
+         */
+        database_write?: CheckResult;
     };
 }
 
@@ -24,6 +33,71 @@ export interface HealthResult {
 export interface HealthDeps {
     pingDb: () => Promise<boolean>;
     pingCache: () => Promise<boolean>;
+    /**
+     * Write-path probe. Optional: when omitted (e.g. tests passing custom
+     * deps) the write check is skipped and behavior matches the read-only
+     * health check. `defaultDeps` supplies the real probe.
+     */
+    pingDbWrite?: () => Promise<boolean>;
+}
+
+// Independent, short timeout for the write probe so a wedged write path is
+// caught fast (and the container restarted) rather than blocking on the 30s
+// request/save timeout. Configurable via DB_HEALTH_WRITE_TIMEOUT.
+const WRITE_PROBE_TIMEOUT_MS = parseInt(process.env.DB_HEALTH_WRITE_TIMEOUT ?? "5000", 10);
+
+function writeProbeDisabled(): boolean {
+    return process.env.HEALTH_DB_WRITE_PROBE === "false";
+}
+
+/**
+ * Exercises a genuine write through the same `db.transaction()` acquisition
+ * path `Entity.save` uses. A wedged write pool (stuck pooled client, pool
+ * exhausted by leaked transactions) hangs here while `SELECT 1` stays healthy
+ * on any idle read connection — exactly the false-healthy scenario that kept a
+ * timed-out container "healthy" and unrestarted.
+ *
+ * The whole transaction is raced against an independent timeout so even a hang
+ * during connection *acquisition* (which runWithSignal alone cannot interrupt,
+ * since it only wraps in-flight queries) is caught. The temp table is dropped
+ * at COMMIT, so the probe has no persistent side effect.
+ */
+async function probeDbWrite(): Promise<boolean> {
+    const timeoutMs = WRITE_PROBE_TIMEOUT_MS;
+    const controller = new AbortController();
+    let handle: ReturnType<typeof setTimeout> | undefined;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+        handle = setTimeout(() => {
+            const err = new Error(`DB write health probe timeout after ${timeoutMs}ms`);
+            controller.abort(err);
+            reject(err);
+        }, timeoutMs);
+        (handle as any).unref?.();
+    });
+
+    const txn = db.transaction(async (trx) => {
+        await runWithSignal(
+            trx`CREATE TEMP TABLE IF NOT EXISTS _bunsane_health_write (probed_at timestamptz NOT NULL) ON COMMIT DROP`,
+            controller.signal,
+        );
+        await runWithSignal(
+            trx`INSERT INTO _bunsane_health_write (probed_at) VALUES (now())`,
+            controller.signal,
+        );
+    });
+
+    try {
+        await Promise.race([txn, timeoutPromise]);
+        return true;
+    } finally {
+        if (handle) clearTimeout(handle);
+        // Abort any in-flight query so the transaction rolls back and the
+        // pooled connection is released even when the timeout won the race.
+        if (!controller.signal.aborted) controller.abort();
+        // Swallow a late transaction settle after a lost race so it cannot
+        // surface as an unhandled rejection.
+        Promise.resolve(txn).catch(() => { /* ignore post-timeout settle */ });
+    }
 }
 
 const defaultDeps: HealthDeps = {
@@ -32,6 +106,7 @@ const defaultDeps: HealthDeps = {
         return true;
     },
     pingCache: () => CacheManager.getInstance().ping(),
+    pingDbWrite: probeDbWrite,
 };
 
 async function checkDatabase(pingDb: () => Promise<boolean>): Promise<CheckResult> {
@@ -55,24 +130,30 @@ async function checkCache(pingCache: () => Promise<boolean>): Promise<CheckResul
 }
 
 export async function deepHealthCheck(deps: HealthDeps = defaultDeps): Promise<HealthResult> {
-    const [database, cache] = await Promise.all([
+    const runWrite = !!deps.pingDbWrite && !writeProbeDisabled();
+
+    const [database, cache, databaseWrite] = await Promise.all([
         checkDatabase(deps.pingDb),
         checkCache(deps.pingCache),
+        runWrite ? checkDatabase(deps.pingDbWrite!) : Promise.resolve(undefined),
     ]);
 
     const dbUp = database.status === "up";
+    const writeUp = !databaseWrite || databaseWrite.status === "up";
     const cacheUp = cache.status === "up";
 
     let status: HealthResponse["status"];
     let httpStatus: number;
 
-    if (dbUp && cacheUp) {
+    if (dbUp && writeUp && cacheUp) {
         status = "ok";
         httpStatus = 200;
-    } else if (dbUp && !cacheUp) {
+    } else if (dbUp && writeUp && !cacheUp) {
         status = "degraded";
         httpStatus = 200;
     } else {
+        // DB read OR write down → unavailable. A wedged write path (reads fine,
+        // writes hang) lands here so liveness fails and the container restarts.
         status = "unavailable";
         httpStatus = 503;
     }
@@ -82,7 +163,11 @@ export async function deepHealthCheck(deps: HealthDeps = defaultDeps): Promise<H
             status,
             timestamp: new Date().toISOString(),
             uptime: process.uptime(),
-            checks: { database, cache },
+            checks: {
+                database,
+                cache,
+                ...(databaseWrite ? { database_write: databaseWrite } : {}),
+            },
         },
         httpStatus,
     };
@@ -94,6 +179,7 @@ export async function readinessCheck(
     deps: HealthDeps = defaultDeps,
 ): Promise<HealthResult> {
     if (!isReady || isShuttingDown) {
+        const includeWrite = !!deps.pingDbWrite && !writeProbeDisabled();
         return {
             result: {
                 status: "unavailable",
@@ -102,6 +188,9 @@ export async function readinessCheck(
                 checks: {
                     database: { status: "unknown", latency_ms: 0 },
                     cache: { status: "unknown", latency_ms: 0 },
+                    ...(includeWrite
+                        ? { database_write: { status: "unknown", latency_ms: 0 } }
+                        : {}),
                 },
             },
             httpStatus: 503,