bunsane 0.3.1 → 0.3.2

package/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"302022ef-825d-48c8-8ef6-656f1cd141e0","pid":60520,"procStart":"639139204827053470","acquiredAt":1778489386099}

package/CHANGELOG.md

@@ -4,6 +4,58 @@ All notable changes to bunsane are documented here.
 
 ## Unreleased
 
+### Added (v0.3.2 — AbortSignal propagation + DB observability)
+
+- **AbortSignal threading into `Query.exec` + DataLoaders.** Resolvers
+  invoked from a GraphQL request now receive the request's `AbortSignal`
+  via the request-context plugin. When the framework's 30s wall-clock
+  fires (`core/app/requestRouter.ts`), in-flight `db.unsafe()` queries
+  are cancelled through Bun's `SQL.Query.cancel()`. Without this an
+  aborted request leaked its backend connection into
+  `idle in transaction` under pgbouncer transaction-mode pooling,
+  cascading into pool starvation under sustained timeout pressure.
+  Public surface: `Query.exec({ signal })`, `Query.count({ signal })`,
+  `Query.estimatedCount(component, { signal })`,
+  `Query.findOneById(id, { signal })`,
+  `Query.explainAnalyze(buffers, { signal })`,
+  `createRequestLoaders(db, cache?, signal?, perRequest?)`.
+  Reuses helper `runWithSignal` extracted to `database/cancellable.ts`
+  and shared with the existing `Entity.doSave` / `Entity.doDelete`
+  abort paths.
+
+- **DB roundtrip observability (`database/instrumentedDb.ts`).** Every
+  `db.unsafe()` callsite in `Query.ts`, `RequestLoaders.ts` and the
+  shared `PreparedStatementCache.execute` now routes through
+  `timedUnsafe`. Tracks `totalCount`, `totalMs`, `maxMs`, `avgMs`,
+  `slowCount`, `abortedCount`, `inFlightMax`, plus per-DataLoader-kind
+  counters. Exposed at `/metrics` under the new `db` key. Calls over
+  `BUNSANE_DB_SLOW_MS` (default 500ms, set 0 to disable warn) log a
+  structured `Slow DB call` warning with a SQL snippet.
+
+- **Per-request stats on access + timeout logs.** GraphQL request
+  context now captures `operationName`, `dataLoaderCalls`
+  (entity / component / relation), and `dbQueryCount`. These attach to
+  the underlying `Request` via `__bunsaneStats` so the HTTP router's
+  catch block and `AccessLog` middleware can include them in every
+  log line. The previous `Request failed after 30004ms: POST /graphql`
+  log now carries enough fields to identify the offending operation
+  without re-running production with a debug build. Timeout warn log
+  also includes operation name when reachable.
+
+### Env vars added
+
+- `BUNSANE_DB_SLOW_MS` (default `500`) — per-call DB threshold for
+  slow log + `slowCount` metric. Set `0` to suppress the warn (stats
+  still accumulate).
+
+### Backward compatibility
+
+All additions are opt-in. Existing apps see no behavior change:
+`Query.exec()`, `Query.count()`, `createRequestLoaders(db, cache)`,
+and `preparedStatementCache.execute(s, p, db)` retain their pre-0.3.2
+signatures. `/metrics` gains a `db` key (pure addition). Log lines
+gain fields but preserve existing ones.
+
 ### Added (HR-Screening ticket batch — BUNSANE-002..006)
 
 - **`@ScheduledTask` allows entity-less time-based tasks.** Previously

package/config/cache.config.ts

@@ -31,6 +31,29 @@ export interface CacheConfig {
     component?: {
         enabled: boolean;
         ttl: number;
+        /**
+         * Cache "absent" component lookups (negative cache) so repeated reads
+         * of optional components on the same entity do not re-hit the DB.
+         * Default false (opt-in) to preserve prior behavior.
+         */
+        negativeCacheEnabled?: boolean;
+        /**
+         * TTL in ms for tombstone entries written for absent components.
+         * Defaults to min(component.ttl, 60_000). Keep ≤ ttl so a created
+         * row supersedes the tombstone within bounded staleness.
+         */
+        negativeCacheTtl?: number;
+    };
+
+    /**
+     * Negative-only cache for relation lookups (e.g. @HasMany returning []).
+     * Empty results are cached with a short TTL; positive results are not
+     * cached here (cross-entity invalidation is non-trivial — see RFC
+     * H-CACHE-NEG). Bounded staleness window equal to negativeCacheTtl.
+     */
+    relation?: {
+        negativeCacheEnabled?: boolean;
+        negativeCacheTtl?: number;
     };
 
     query?: {
@@ -76,7 +99,18 @@ export const defaultCacheConfig: CacheConfig = {
 
     component: {
         enabled: process.env.CACHE_COMPONENT_ENABLED !== 'false', // Default true
-        ttl: parseInt(process.env.CACHE_COMPONENT_TTL || '1800000') // 30 minutes
+        ttl: parseInt(process.env.CACHE_COMPONENT_TTL || '1800000'), // 30 minutes
+        negativeCacheEnabled: process.env.CACHE_COMPONENT_NEGATIVE_ENABLED === 'true',
+        negativeCacheTtl: process.env.CACHE_COMPONENT_NEGATIVE_TTL
+            ? parseInt(process.env.CACHE_COMPONENT_NEGATIVE_TTL)
+            : undefined
+    },
+
+    relation: {
+        negativeCacheEnabled: process.env.CACHE_RELATION_NEGATIVE_ENABLED === 'true',
+        negativeCacheTtl: process.env.CACHE_RELATION_NEGATIVE_TTL
+            ? parseInt(process.env.CACHE_RELATION_NEGATIVE_TTL)
+            : 60_000
     },
 
     query: {