bunsane 0.3.1 → 0.3.2

package/core/Entity.ts

@@ -1,6 +1,7 @@
 import type { ComponentDataType, ComponentGetter, BaseComponent } from "./components";
 import { logger } from "./Logger";
 import db, { QUERY_TIMEOUT_MS } from "../database";
+import { runWithSignal } from "../database/cancellable";
 import EntityManager from "./EntityManager";
 import ComponentRegistry from "./components/ComponentRegistry";
 import { uuidv7 } from "../utils/uuid";
@@ -763,26 +764,14 @@ export class Entity implements IEntity {
             return true;
         }
 
-        // Execute a Bun SQL query with AbortSignal support. On abort, the
-        // in-flight query is cancelled (SQL.Query.cancel()) which causes the
-        // transaction callback to throw, triggering Bun's automatic ROLLBACK
-        // and releasing the pooled backend connection. Without this, a wall-
-        // clock timeout leaks backends into `idle in transaction` state —
-        // fatal under pgbouncer transaction-mode pooling.
-        const run = async <T>(q: any): Promise<T> => {
-            if (!signal) return await q;
-            if (signal.aborted) {
-                try { q.cancel?.(); } catch { /* ignore */ }
-                throw signal.reason ?? new Error('Entity.save aborted');
-            }
-            const onAbort = () => { try { q.cancel?.(); } catch { /* ignore */ } };
-            signal.addEventListener('abort', onAbort, { once: true });
-            try {
-                return await q;
-            } finally {
-                signal.removeEventListener('abort', onAbort);
-            }
-        };
+        // Cancellation goes through the shared `runWithSignal` helper so
+        // every db.unsafe / trx`...` callsite in the framework uses the same
+        // pattern: on abort the in-flight Bun SQL Query is cancelled, the
+        // transaction callback throws, Bun emits ROLLBACK, and the pooled
+        // backend connection is released. Without this a wall-clock timeout
+        // leaks the backend into `idle in transaction` under pgbouncer
+        // transaction-mode pooling.
+        const run = <T>(q: any): Promise<T> => runWithSignal<T>(q, signal);
 
         const executeSave = async (saveTrx: SQL) => {
             if (!this._persisted) {
@@ -917,19 +906,7 @@ export class Entity implements IEntity {
         }, timeoutMs);
 
         const signal = controller.signal;
-        const run = async <T>(q: any): Promise<T> => {
-            if (signal.aborted) {
-                try { q.cancel?.(); } catch { /* ignore */ }
-                throw signal.reason ?? new Error('Entity.doDelete aborted');
-            }
-            const onAbort = () => { try { q.cancel?.(); } catch { /* ignore */ } };
-            signal.addEventListener('abort', onAbort, { once: true });
-            try {
-                return await q;
-            } finally {
-                signal.removeEventListener('abort', onAbort);
-            }
-        };
+        const run = <T>(q: any): Promise<T> => runWithSignal<T>(q, signal);
 
         try {
             await db.transaction(async (trx) => {

package/core/RequestContext.ts

@@ -1,36 +1,85 @@
-import type { Plugin } from 'graphql-yoga';
-import { createRequestLoaders } from './RequestLoaders';
-import type { RequestLoaders } from './RequestLoaders';
-import db from '../database';
-import { CacheManager } from './cache/CacheManager';
-import { getRequestId } from './middleware/RequestId';
-
-declare module 'graphql-yoga' {
-  interface Context {
-    // Loaders mounted at top-level context for ArcheType resolver access
-    loaders: RequestLoaders;
-    requestId: string;
-    cacheManager: CacheManager;
-  }
-}
-
-/**
- * GraphQL Yoga plugin that creates per-request DataLoaders for batching.
- *
- * IMPORTANT: Loaders are mounted at context.loaders (NOT context.locals.loaders)
- * to match what ArcheType.ts resolvers expect. This enables DataLoader batching
- * for BelongsTo/HasMany relations, preventing N+1 queries.
- */
-export function createRequestContextPlugin(): Plugin {
-  return {
-    onExecute: ({ args }) => {
-      const cacheManager = CacheManager.getInstance();
-      // Mount loaders at context.loaders to match ArcheType.ts resolver access pattern
-      (args as any).contextValue.loaders = createRequestLoaders(db, cacheManager);
-      // Prefer the HTTP-layer request id (from requestId() middleware's
-      // AsyncLocalStorage) so access log + GraphQL logs share the same id.
-      (args as any).contextValue.requestId = getRequestId() ?? crypto.randomUUID();
-      (args as any).contextValue.cacheManager = cacheManager;
-    },
-  };
-}
+import type { Plugin } from 'graphql-yoga';
+import { createRequestLoaders } from './RequestLoaders';
+import type { RequestLoaders } from './RequestLoaders';
+import db from '../database';
+import { CacheManager } from './cache/CacheManager';
+import { getRequestId } from './middleware/RequestId';
+
+export interface RequestStats {
+  operationName: string;
+  dataLoaderCalls: { entity: number; component: number; relation: number };
+  dbQueryCount: number;
+  startTime: number;
+}
+
+declare module 'graphql-yoga' {
+  interface Context {
+    // Loaders mounted at top-level context for ArcheType resolver access
+    loaders: RequestLoaders;
+    requestId: string;
+    cacheManager: CacheManager;
+    requestStats: RequestStats;
+    signal?: AbortSignal;
+  }
+}
+
+/**
+ * GraphQL Yoga plugin that creates per-request DataLoaders for batching.
+ *
+ * IMPORTANT: Loaders are mounted at context.loaders (NOT context.locals.loaders)
+ * to match what ArcheType.ts resolvers expect. This enables DataLoader batching
+ * for BelongsTo/HasMany relations, preventing N+1 queries.
+ *
+ * Also threads the request `AbortSignal` into Query/DataLoader DB calls so
+ * the framework's wall-clock timeout (handled in core/app/requestRouter.ts)
+ * cancels in-flight Postgres queries via Bun's `Query.cancel()`. Without
+ * this, an aborted request leaks its backend connection into
+ * `idle in transaction` under pgbouncer transaction-mode pooling.
+ *
+ * Captures per-request stats (operationName, DataLoader call counts,
+ * dbQueryCount) and attaches them to the underlying Request via
+ * `__bunsaneStats` so the HTTP router's catch handler + AccessLog
+ * middleware can read them after the GraphQL pipeline rejects.
+ */
+export function createRequestContextPlugin(): Plugin {
+  return {
+    onExecute: ({ args }) => {
+      const cacheManager = CacheManager.getInstance();
+      const ctx: any = (args as any).contextValue;
+      const request: Request | undefined = ctx?.request;
+      const signal: AbortSignal | undefined = request?.signal;
+
+      // GraphQL operation name. Falls back to first named operation in the
+      // document, or 'anonymous' if the client supplied an inline query
+      // with no name.
+      const operationName: string =
+        (typeof args.operationName === 'string' && args.operationName)
+        || (args.document?.definitions?.find?.(
+              (d: any) => d?.kind === 'OperationDefinition' && d?.name?.value,
+           ) as any)?.name?.value
+        || 'anonymous';
+
+      const stats: RequestStats = {
+        operationName,
+        dataLoaderCalls: { entity: 0, component: 0, relation: 0 },
+        dbQueryCount: 0,
+        startTime: performance.now(),
+      };
+
+      // Mount loaders at context.loaders to match ArcheType.ts resolver access pattern.
+      ctx.loaders = createRequestLoaders(db, cacheManager, signal, stats);
+      // Prefer the HTTP-layer request id (from requestId() middleware's
+      // AsyncLocalStorage) so access log + GraphQL logs share the same id.
+      ctx.requestId = getRequestId() ?? crypto.randomUUID();
+      ctx.cacheManager = cacheManager;
+      ctx.requestStats = stats;
+      ctx.signal = signal;
+
+      // Attach to the raw Request so the HTTP router catch block + access
+      // log middleware can read stats after Yoga rejects.
+      if (request) {
+        (request as any).__bunsaneStats = stats;
+      }
+    },
+  };
+}

package/core/RequestLoaders.ts

@@ -2,10 +2,12 @@ import DataLoader from 'dataloader';
 import { Entity } from './Entity';
 import db from '../database';
 import { inList } from '../database/sqlHelpers';
+import { timedUnsafe, incrementDataLoaderCall, type PerRequestCounters } from '../database/instrumentedDb';
 import {logger as MainLogger} from './Logger';
 const logger = MainLogger.child({ module: 'RequestLoaders' });
 import { getMetadataStorage } from './metadata';
 import type { CacheManager } from './cache/CacheManager';
+import { COMPONENT_TOMBSTONE } from './cache/CacheManager';
 
 export type ComponentData = {
   id: string;  // Component ID for updates
@@ -23,8 +25,14 @@ export type RequestLoaders = {
   relationsByEntityField: DataLoader<{ entityId: string; relationField: string; relatedType: string; foreignKey?: string }, Entity[]>;
 };
 
-export function createRequestLoaders(db: any, cacheManager?: CacheManager): RequestLoaders {
+export function createRequestLoaders(
+  db: any,
+  cacheManager?: CacheManager,
+  signal?: AbortSignal,
+  perRequest?: PerRequestCounters,
+): RequestLoaders {
   const entityById = new DataLoader<string, Entity | null>(async (ids: readonly string[]) => {
+    incrementDataLoaderCall('entity', perRequest);
     const startTime = Date.now();
     try {
       // Filter out empty/invalid IDs to prevent PostgreSQL UUID parsing errors
@@ -44,12 +52,12 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
       
       if (missingIds.length > 0) {
         const idList = inList(missingIds, 1);
-        const rows = await db.unsafe(`
+        const rows = await timedUnsafe<any[]>(db, `
           SELECT id
           FROM entities
           WHERE id IN ${idList.sql}
             AND deleted_at IS NULL
-        `, idList.params);
+        `, idList.params, signal, perRequest);
         
         const entities = rows.map((row: any) => {
           const entity = new Entity(row.id);
@@ -89,6 +97,7 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
 
   const componentsByEntityType = new DataLoader<{ entityId: string; typeId: string }, ComponentData | null>(
     async (keys: readonly { entityId: string; typeId: string }[]) => {
+      incrementDataLoaderCall('component', perRequest);
       const startTime = Date.now();
       try {
         // Filter out keys with empty/invalid entity IDs to prevent PostgreSQL UUID parsing errors
@@ -99,16 +108,20 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
 
         const results = new Map<string, ComponentData | null>();
 
-        // Check cache first if cache manager is available
+        // Check cache first if cache manager is available. Tombstone hits
+        // are recorded as null in `results` so the DB-fetch step skips them.
         let cacheHits = 0;
         let cacheMisses = 0;
         if (cacheManager && cacheManager.getConfig().enabled && cacheManager.getConfig().component?.enabled) {
           try {
             const cachedComponents = await cacheManager.getComponents(validKeys);
-            cachedComponents.forEach((component, index) => {
-              if (component) {
-                const key = `${validKeys[index]!.entityId}-${validKeys[index]!.typeId}`;
-                results.set(key, component);
+            cachedComponents.forEach((value, index) => {
+              const key = `${validKeys[index]!.entityId}-${validKeys[index]!.typeId}`;
+              if (value === COMPONENT_TOMBSTONE) {
+                results.set(key, null);
+                cacheHits++;
+              } else if (value) {
+                results.set(key, value);
                 cacheHits++;
               } else {
                 cacheMisses++;
@@ -122,17 +135,16 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           cacheMisses += validKeys.length;
         }
 
-        // Log cache hit/miss rates for monitoring
         if (validKeys.length > 0) {
           const hitRate = (cacheHits / validKeys.length) * 100;
-          logger.debug({ 
-            scope: 'cache', 
-            component: 'RequestLoaders', 
-            msg: 'Component cache statistics', 
-            total: validKeys.length, 
-            hits: cacheHits, 
-            misses: cacheMisses, 
-            hitRate: `${hitRate.toFixed(1)}%` 
+          logger.trace({
+            scope: 'cache',
+            component: 'RequestLoaders',
+            msg: 'Component cache statistics',
+            total: validKeys.length,
+            hits: cacheHits,
+            misses: cacheMisses,
+            hitRate: `${hitRate.toFixed(1)}%`,
           });
         }
 
@@ -144,13 +156,13 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           const typeIds = [...new Set(missingKeys.map(k => k.typeId))];
           const entityIdList = inList(entityIds, 1);
           const typeIdList = inList(typeIds, entityIdList.newParamIndex);
-          const rows = await db.unsafe(`
+          const rows = await timedUnsafe<any[]>(db, `
             SELECT id, entity_id, type_id, data, created_at, updated_at, deleted_at
             FROM components
             WHERE entity_id IN ${entityIdList.sql}
               AND type_id IN ${typeIdList.sql}
               AND deleted_at IS NULL
-          `, [...entityIdList.params, ...typeIdList.params]);
+          `, [...entityIdList.params, ...typeIdList.params], signal, perRequest);
           
           const components: ComponentData[] = rows.map((row: any) => ({
             id: row.id,
@@ -162,10 +174,15 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
             deletedAt: row.deleted_at,
           }));
 
-          // Cache the loaded components if cache is enabled
+          // Cache the loaded components + tombstone any requested keys whose
+          // row was absent (single setMany — see CacheManager.setComponentsWriteThrough).
           if (cacheManager && cacheManager.getConfig().enabled && cacheManager.getConfig().component?.enabled) {
             try {
-              await cacheManager.setComponentsWriteThrough(components, cacheManager.getConfig().component!.ttl);
+              await cacheManager.setComponentsWriteThrough(
+                components,
+                missingKeys,
+                cacheManager.getConfig().component!.ttl,
+              );
             } catch (error: any) {
               logger.warn({ scope: 'cache', component: 'RequestLoaders', msg: 'Cache write failed for components', error });
             }
@@ -199,6 +216,7 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
 
   const relationsByEntityField = new DataLoader<{ entityId: string; relationField: string; relatedType: string; foreignKey?: string }, Entity[]>(
     async (keys: readonly { entityId: string; relationField: string; relatedType: string; foreignKey?: string }[]) => {
+      incrementDataLoaderCall('relation', perRequest);
       const startTime = Date.now();
       try {
         // Filter valid keys
@@ -207,9 +225,35 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           return keys.map(() => []);
         }
 
+        const resultMap = new Map<string, Entity[]>();
+
+        // Negative-cache lookup: skip DB for keys recorded as empty.
+        let keysToQuery = validKeys;
+        const relCacheEnabled = !!(cacheManager
+          && cacheManager.getConfig().enabled
+          && cacheManager.getConfig().relation?.negativeCacheEnabled);
+        if (relCacheEnabled) {
+          try {
+            const tombstones = await cacheManager!.getRelationsEmpty(validKeys);
+            const remaining: typeof validKeys = [];
+            tombstones.forEach((isEmpty, i) => {
+              const k = validKeys[i]!;
+              if (isEmpty) {
+                const mapKey = `${k.entityId}\x00${k.relationField}\x00${k.relatedType}`;
+                resultMap.set(mapKey, []);
+              } else {
+                remaining.push(k);
+              }
+            });
+            keysToQuery = remaining;
+          } catch (error) {
+            logger.warn({ scope: 'cache', component: 'RequestLoaders', msg: 'Cache read failed for relation tombstones', error });
+          }
+        }
+
         // Group keys by foreign key for efficient batching
-        const keysByForeignKey = new Map<string, typeof validKeys>();
-        for (const key of validKeys) {
+        const keysByForeignKey = new Map<string, typeof keysToQuery>();
+        for (const key of keysToQuery) {
           const fk = key.foreignKey || 'default';
           if (!keysByForeignKey.has(fk)) {
             keysByForeignKey.set(fk, []);
@@ -217,8 +261,6 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           keysByForeignKey.get(fk)!.push(key);
         }
 
-        const resultMap = new Map<string, Entity[]>();
-
         // OPTIMIZED: Batch query for each foreign key type (instead of N separate queries)
         for (const [foreignKey, groupedKeys] of keysByForeignKey) {
           const entityIds = [...new Set(groupedKeys.map(k => k.entityId))];
@@ -240,19 +282,19 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           logger.trace(`[RelationLoader] Batched query for ${groupedKeys.length} keys with foreign key ${foreignKey}`);
 
           // SINGLE BATCHED QUERY for all entities in this group
-          const rows = await db.unsafe(`
-            SELECT DISTINCT 
-              c.entity_id, 
-              c.data, 
+          const rows = await timedUnsafe<any[]>(db, `
+            SELECT DISTINCT
+              c.entity_id,
+              c.data,
               c.type_id,
               c.data->>'${foreignKeyField}' as fk_value,
               COALESCE(c.data->>'user_id', c.data->>'parent_id') as fallback_fk_value
             FROM components c
             INNER JOIN entities e ON c.entity_id = e.id
-            WHERE e.deleted_at IS NULL 
+            WHERE e.deleted_at IS NULL
               AND c.deleted_at IS NULL
               AND ${whereClause}
-          `, [entityIds]);
+          `, [entityIds], signal, perRequest);
 
           logger.trace(`[RelationLoader] Found ${rows.length} total components for ${entityIds.length} entities`);
 
@@ -281,6 +323,22 @@ export function createRequestLoaders(db: any, cacheManager?: CacheManager): Requ
           }
         }
 
+        // Write tombstones for queried keys whose result was empty.
+        if (relCacheEnabled && keysToQuery.length > 0) {
+          const emptyKeys = keysToQuery.filter(k => {
+            const mapKey = `${k.entityId}\x00${k.relationField}\x00${k.relatedType}`;
+            const r = resultMap.get(mapKey);
+            return !r || r.length === 0;
+          });
+          if (emptyKeys.length > 0) {
+            try {
+              await cacheManager!.setRelationsEmpty(emptyKeys);
+            } catch (error) {
+              logger.warn({ scope: 'cache', component: 'RequestLoaders', msg: 'Cache write failed for relation tombstones', error });
+            }
+          }
+        }
+
         const duration = Date.now() - startTime;
         if (duration > 1000) {
           logger.warn(`Slow relationsByEntityField query: ${duration}ms for ${keys.length} keys`);

package/core/app/bootstrap.ts

@@ -0,0 +1,133 @@
+import ApplicationLifecycle, {
+    ApplicationPhase,
+    type PhaseChangeEvent,
+} from "../ApplicationLifecycle";
+import { logger as MainLogger } from "../Logger";
+import ServiceRegistry from "../../service/ServiceRegistry";
+import { SchedulerManager } from "../SchedulerManager";
+import { registerScheduledTasks } from "../../scheduler";
+import {
+    RemoteManager,
+    registerRemoteHandlers,
+    setRemoteManager,
+    type RemoteManagerConfig,
+} from "../remote";
+import { setupGraphQL } from "./graphqlSetup";
+import { collectRestEndpoints } from "./restRegistry";
+
+const logger = MainLogger.child({ scope: "App" });
+
+export function createPhaseListener(app: any): (event: PhaseChangeEvent) => Promise<void> {
+    return async (event: PhaseChangeEvent) => {
+        const phase = event.detail;
+        logger.info(`Application phase changed to: ${phase}`);
+        for (const plugin of app.plugins) {
+            if (plugin.onPhaseChange) {
+                await plugin.onPhaseChange(phase, app);
+            }
+        }
+        switch (phase) {
+            case ApplicationPhase.DATABASE_READY:
+                await runDatabaseReadyPhase(app);
+                break;
+            case ApplicationPhase.SYSTEM_READY:
+                await runSystemReadyPhase(app);
+                break;
+            case ApplicationPhase.APPLICATION_READY:
+                await runApplicationReadyPhase(app);
+                break;
+        }
+    };
+}
+
+export async function runDatabaseReadyPhase(app: any): Promise<void> {
+    try {
+        await app.warmUpPreparedStatementCache();
+    } catch (error) {
+        logger.warn("Failed to warm up prepared statement cache:", error as any);
+    }
+}
+
+export async function runSystemReadyPhase(app: any): Promise<void> {
+    try {
+        const { CacheManager } = await import('../cache/CacheManager');
+        const cacheManager = CacheManager.getInstance();
+        const config = cacheManager.getConfig();
+
+        if (config.enabled) {
+            const isHealthy = await cacheManager.getProvider().ping();
+            if (isHealthy) {
+                logger.info({ scope: 'cache', component: 'App', msg: 'Cache health check passed' });
+            } else {
+                logger.warn({ scope: 'cache', component: 'App', msg: 'Cache health check failed' });
+            }
+        }
+    } catch (error) {
+        logger.warn({ scope: 'cache', component: 'App', msg: 'Cache health check error', error });
+    }
+
+    try {
+        setupGraphQL(app);
+
+        const services = ServiceRegistry.getServices();
+
+        const scheduler = SchedulerManager.getInstance();
+        scheduler.config.enableLogging = app.config.scheduler.logging;
+
+        for (const service of services) {
+            try {
+                registerScheduledTasks(service);
+            } catch (error) {
+                logger.warn(`Failed to register scheduled tasks for service ${service.constructor.name}`);
+                logger.warn(error);
+            }
+        }
+        logger.info(`Registered scheduled tasks for ${services.length} services`);
+
+        if (app.remoteConfig) {
+            try {
+                const rmConfig: RemoteManagerConfig = {
+                    appName: app.remoteConfig.appName || app.name,
+                    ...app.remoteConfig,
+                };
+                app.remote = new RemoteManager(rmConfig);
+                setRemoteManager(app.remote);
+                await app.remote.start();
+
+                for (const service of services) {
+                    try {
+                        registerRemoteHandlers(service);
+                    } catch (error) {
+                        logger.warn(`Failed to register remote handlers for service ${service.constructor.name}`);
+                        logger.warn(error);
+                    }
+                }
+                logger.info(`RemoteManager initialized for app "${rmConfig.appName}"`);
+            } catch (error) {
+                logger.error("Failed to start RemoteManager:");
+                logger.error(error);
+            }
+        }
+
+        collectRestEndpoints(app, services);
+
+        ApplicationLifecycle.setPhase(ApplicationPhase.APPLICATION_READY);
+    } catch (error) {
+        // SYSTEM_READY failures must not be swallowed silently. Without this,
+        // the app stays forever in SYSTEM_READY (isReady=false,
+        // /health/ready → 503 forever) and k8s rollout hangs with no
+        // observable cause. Surface so readiness probe reports it (C09).
+        app.isReady = false;
+        logger.fatal({ scope: 'app', component: 'App', err: error }, 'Fatal error during SYSTEM_READY phase — marking app unready');
+        if (process.env.NODE_ENV === 'test') {
+            throw error;
+        }
+        setTimeout(() => process.exit(1), 100).unref?.();
+    }
+}
+
+export async function runApplicationReadyPhase(app: any): Promise<void> {
+    if (process.env.NODE_ENV !== "test") {
+        app.start();
+    }
+}

package/core/app/cors.ts

@@ -0,0 +1,94 @@
+import type { CorsConfig } from "../App";
+
+export function assertValidCorsConfig(cors: CorsConfig): void {
+    if (cors.origin === undefined) {
+        throw new Error('[CORS] `origin` is required. Pass an explicit string, array, function, or "*" if you truly want to allow everyone.');
+    }
+    if (cors.credentials && cors.origin === '*') {
+        console.warn('[CORS] Warning: credentials=true with origin="*" is invalid per spec. Origin will be reflected from request.');
+    }
+}
+
+export function validateOrigin(
+    cors: CorsConfig | undefined,
+    requestOrigin: string | null | undefined,
+): string | null {
+    if (!cors || !requestOrigin) return null;
+
+    const configOrigin = cors.origin;
+
+    if (configOrigin === undefined) return null;
+
+    if (configOrigin === '*') {
+        return cors.credentials ? requestOrigin : '*';
+    }
+
+    if (typeof configOrigin === 'string') {
+        return requestOrigin === configOrigin ? configOrigin : null;
+    }
+
+    if (Array.isArray(configOrigin)) {
+        return configOrigin.includes(requestOrigin) ? requestOrigin : null;
+    }
+
+    if (typeof configOrigin === 'function') {
+        return configOrigin(requestOrigin) ? requestOrigin : null;
+    }
+
+    return null;
+}
+
+export function getCorsHeaders(
+    cors: CorsConfig | undefined,
+    req?: Request,
+): Record<string, string> {
+    if (!cors) return {};
+
+    const requestOrigin = req?.headers.get('Origin');
+    const allowedOrigin = validateOrigin(cors, requestOrigin);
+
+    if (requestOrigin && !allowedOrigin) return {};
+
+    const headers: Record<string, string> = {
+        'Access-Control-Allow-Methods': cors.methods?.join(', ') || 'GET, POST, PUT, DELETE, OPTIONS',
+        'Access-Control-Allow-Headers': cors.allowedHeaders?.join(', ') || 'Content-Type, Authorization',
+        'Vary': 'Origin',
+    };
+    if (allowedOrigin) {
+        headers['Access-Control-Allow-Origin'] = allowedOrigin;
+    }
+
+    if (cors.credentials) {
+        headers['Access-Control-Allow-Credentials'] = 'true';
+    }
+
+    if (cors.exposedHeaders?.length) {
+        headers['Access-Control-Expose-Headers'] = cors.exposedHeaders.join(', ');
+    }
+
+    if (cors.maxAge !== undefined) {
+        headers['Access-Control-Max-Age'] = String(cors.maxAge);
+    }
+
+    return headers;
+}
+
+export function addCorsHeaders(
+    response: Response,
+    cors: CorsConfig | undefined,
+    req?: Request,
+): Response {
+    const corsHeaders = getCorsHeaders(cors, req);
+    if (Object.keys(corsHeaders).length === 0) return response;
+
+    const newHeaders = new Headers(response.headers);
+    for (const [key, value] of Object.entries(corsHeaders)) {
+        newHeaders.set(key, value);
+    }
+
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: newHeaders,
+    });
+}