bunsane 0.2.9 → 0.3.0

package/core/decorators/EntityHooks.ts

@@ -114,6 +114,10 @@ export function ComponentTargetHook(
     };
 }
 
+/** Per-instance registry of hook IDs created by registerDecoratedHooks.
+ *  Used by unregisterDecoratedHooks to undo registration (H-HOOK-3). */
+const REGISTERED_IDS = new WeakMap<object, string[]>();
+
 /**
  * Register all decorated hooks for a service class
  * Call this method after instantiating a service to register its decorated hooks
@@ -121,17 +125,18 @@ export function ComponentTargetHook(
  */
 export function registerDecoratedHooks(serviceInstance: any): void {
     const constructor = serviceInstance.constructor;
+    const ids: string[] = REGISTERED_IDS.get(serviceInstance) ?? [];
 
     // Register entity hooks
     if (constructor.__entityHooks) {
         for (const hookInfo of constructor.__entityHooks) {
             const hookMethod = serviceInstance[hookInfo.methodName].bind(serviceInstance);
 
-            EntityHookManager.registerEntityHook(
+            ids.push(EntityHookManager.registerEntityHook(
                 hookInfo.eventType,
                 hookMethod,
                 hookInfo.options
-            );
+            ));
         }
     }
 
@@ -140,11 +145,11 @@ export function registerDecoratedHooks(serviceInstance: any): void {
         for (const hookInfo of constructor.__componentHooks) {
             const hookMethod = serviceInstance[hookInfo.methodName].bind(serviceInstance);
 
-            EntityHookManager.registerComponentHook(
+            ids.push(EntityHookManager.registerComponentHook(
                 hookInfo.eventType,
                 hookMethod,
                 hookInfo.options
-            );
+            ));
         }
     }
 
@@ -153,14 +158,14 @@ export function registerDecoratedHooks(serviceInstance: any): void {
         for (const hookInfo of constructor.__componentTargetHooks) {
             const hookMethod = serviceInstance[hookInfo.methodName].bind(serviceInstance);
 
-            EntityHookManager.registerEntityHook(
+            ids.push(EntityHookManager.registerEntityHook(
                 hookInfo.eventType,
                 hookMethod,
                 {
                     ...hookInfo.options,
                     componentTarget: hookInfo.componentTarget
                 }
-            );
+            ));
         }
     }
 
@@ -169,19 +174,26 @@ export function registerDecoratedHooks(serviceInstance: any): void {
         for (const hookInfo of constructor.__lifecycleHooks) {
             const hookMethod = serviceInstance[hookInfo.methodName].bind(serviceInstance);
 
-            EntityHookManager.registerLifecycleHook(
+            ids.push(EntityHookManager.registerLifecycleHook(
                 hookMethod,
                 hookInfo.options
-            );
+            ));
         }
     }
+
+    REGISTERED_IDS.set(serviceInstance, ids);
 }
 
 /**
- * Unregister all decorated hooks for a service class
- * Call this method before destroying a service to clean up its hooks
- * @param serviceInstance The service instance to unregister hooks for
+ * Unregister all decorated hooks for a service instance.
+ * Call during teardown (service destruction, test isolation) to prevent
+ * hook leaks across repeated instantiations (H-HOOK-3).
  */
 export function unregisterDecoratedHooks(serviceInstance: any): void {
-    console.warn('unregisterDecoratedHooks is not fully implemented. Use EntityHookManager.removeHook() for individual hook removal.');
+    const ids = REGISTERED_IDS.get(serviceInstance);
+    if (!ids) return;
+    for (const id of ids) {
+        EntityHookManager.removeHook(id);
+    }
+    REGISTERED_IDS.delete(serviceInstance);
 }

package/core/middleware/RateLimit.ts

@@ -0,0 +1,105 @@
+import type { Middleware } from '../Middleware';
+import { logger as MainLogger } from '../Logger';
+
+const logger = MainLogger.child({ scope: 'RateLimit' });
+
+export type RateLimitOptions = {
+    /** Maximum requests in the window. Default: 100 */
+    max?: number;
+    /** Window length in milliseconds. Default: 60_000 (1 min) */
+    windowMs?: number;
+    /** Only apply to paths matching this prefix list. Default: all */
+    pathPrefixes?: string[];
+    /** Extract client key (override default: X-Forwarded-For → remote). */
+    keyExtractor?: (req: Request) => string;
+    /** Response status for rejection. Default: 429 */
+    status?: number;
+    /** Trust X-Forwarded-For header. Default: false */
+    trustProxy?: boolean;
+};
+
+type Bucket = {
+    count: number;
+    resetAt: number;
+};
+
+/**
+ * In-memory token-bucket rate limiter. Per-instance only — for multi-instance
+ * deployments use a shared Redis-backed limiter. Sweeps expired buckets on
+ * each increment to keep memory bounded.
+ */
+export function rateLimit(options: RateLimitOptions = {}): Middleware {
+    const max = options.max ?? 100;
+    const windowMs = options.windowMs ?? 60_000;
+    const pathPrefixes = options.pathPrefixes;
+    const status = options.status ?? 429;
+    const trustProxy = options.trustProxy ?? false;
+    const keyExtractor = options.keyExtractor ?? ((req: Request) => {
+        if (trustProxy) {
+            const xff = req.headers.get('x-forwarded-for');
+            if (xff) return xff.split(',')[0]!.trim();
+        }
+        const realIp = req.headers.get('x-real-ip');
+        if (realIp) return realIp;
+        return 'anonymous';
+    });
+
+    const buckets = new Map<string, Bucket>();
+    let lastSweep = Date.now();
+
+    return async (req, next) => {
+        if (pathPrefixes && pathPrefixes.length > 0) {
+            const url = new URL(req.url);
+            const match = pathPrefixes.some((p) => url.pathname.startsWith(p));
+            if (!match) return next();
+        }
+
+        const now = Date.now();
+        const key = keyExtractor(req);
+
+        if (now - lastSweep > windowMs) {
+            for (const [k, v] of buckets) {
+                if (v.resetAt <= now) buckets.delete(k);
+            }
+            lastSweep = now;
+        }
+
+        let bucket = buckets.get(key);
+        if (!bucket || bucket.resetAt <= now) {
+            bucket = { count: 0, resetAt: now + windowMs };
+            buckets.set(key, bucket);
+        }
+
+        bucket.count++;
+        const remaining = Math.max(0, max - bucket.count);
+        const retryAfterSec = Math.ceil((bucket.resetAt - now) / 1000);
+
+        if (bucket.count > max) {
+            logger.warn({ key, path: new URL(req.url).pathname, count: bucket.count, max }, 'rate limit exceeded');
+            return new Response(
+                JSON.stringify({ error: 'Too many requests', retryAfter: retryAfterSec }),
+                {
+                    status,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Retry-After': String(retryAfterSec),
+                        'X-RateLimit-Limit': String(max),
+                        'X-RateLimit-Remaining': '0',
+                        'X-RateLimit-Reset': String(Math.floor(bucket.resetAt / 1000)),
+                    },
+                },
+            );
+        }
+
+        const response = await next();
+        const newHeaders = new Headers(response.headers);
+        newHeaders.set('X-RateLimit-Limit', String(max));
+        newHeaders.set('X-RateLimit-Remaining', String(remaining));
+        newHeaders.set('X-RateLimit-Reset', String(Math.floor(bucket.resetAt / 1000)));
+        return new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: newHeaders,
+        });
+    };
+}

package/core/middleware/index.ts

@@ -1,3 +1,4 @@
 export { securityHeaders, type SecurityHeadersOptions } from './SecurityHeaders';
 export { requestId, getRequestId, requestStore } from './RequestId';
 export { accessLog, type AccessLogOptions } from './AccessLog';
+export { rateLimit, type RateLimitOptions } from './RateLimit';

package/core/remote/CircuitBreaker.ts

@@ -0,0 +1,115 @@
+/**
+ * Remote Communication: CircuitBreaker
+ *
+ * Three-state breaker: closed -> open -> half-open -> closed.
+ *
+ * closed: pass through; increment failure count on error; trip to open at N.
+ * open:   reject immediately (fail-fast) until reset timeout elapses.
+ * half:   one trial call allowed; success -> closed, failure -> open again.
+ *
+ * Wraps Redis publish operations so a sustained Redis outage does not stall
+ * callers waiting for command timeouts on every request.
+ */
+
+export type CircuitState = "closed" | "open" | "half-open";
+
+export interface CircuitBreakerConfig {
+    /** Consecutive failures before opening (default 5) */
+    threshold?: number;
+    /** ms after opening before a half-open trial is allowed (default 30000) */
+    resetTimeoutMs?: number;
+}
+
+export class CircuitOpenError extends Error {
+    public readonly code = "CIRCUIT_OPEN";
+    constructor(message = "Circuit breaker is open") {
+        super(message);
+        this.name = "CircuitOpenError";
+    }
+}
+
+export class CircuitBreaker {
+    private state: CircuitState = "closed";
+    private failures = 0;
+    private openedAt = 0;
+    private threshold: number;
+    private resetTimeoutMs: number;
+
+    /** Hooks for metrics. */
+    public onTrip?: () => void;
+    public onReject?: () => void;
+
+    constructor(config: CircuitBreakerConfig = {}) {
+        this.threshold = config.threshold ?? 5;
+        this.resetTimeoutMs = config.resetTimeoutMs ?? 30_000;
+    }
+
+    getState(): CircuitState {
+        // Lazy transition from open -> half-open when reset window elapses.
+        if (
+            this.state === "open" &&
+            Date.now() - this.openedAt >= this.resetTimeoutMs
+        ) {
+            this.state = "half-open";
+        }
+        return this.state;
+    }
+
+    async exec<T>(fn: () => Promise<T>): Promise<T> {
+        const state = this.getState();
+        if (state === "open") {
+            this.onReject?.();
+            throw new CircuitOpenError();
+        }
+
+        try {
+            const result = await fn();
+            this.recordSuccess();
+            return result;
+        } catch (err) {
+            this.recordFailure();
+            throw err;
+        }
+    }
+
+    recordSuccess(): void {
+        const current = this.getState();
+        if (current === "half-open") {
+            this.state = "closed";
+        }
+        this.failures = 0;
+    }
+
+    recordFailure(): void {
+        // Force lazy open->half-open transition before deciding what to do.
+        const current = this.getState();
+        this.failures++;
+        if (current === "half-open") {
+            // Trial failed — back to open.
+            this.state = "open";
+            this.openedAt = Date.now();
+            this.onTrip?.();
+            return;
+        }
+        if (current === "closed" && this.failures >= this.threshold) {
+            this.state = "open";
+            this.openedAt = Date.now();
+            this.onTrip?.();
+        }
+    }
+
+    /** Force reset (useful for tests or manual recovery). */
+    reset(): void {
+        this.state = "closed";
+        this.failures = 0;
+        this.openedAt = 0;
+    }
+
+    getStats() {
+        return {
+            state: this.getState(),
+            failures: this.failures,
+            openedAt: this.openedAt,
+        };
+    }
+}

package/core/remote/OutboxWorker.ts

@@ -0,0 +1,183 @@
+/**
+ * Remote Communication: OutboxWorker
+ *
+ * Polls `remote_outbox` for unpublished rows, publishes each to Redis, and
+ * marks the row published. Uses `FOR UPDATE SKIP LOCKED` so multiple
+ * instances can run workers concurrently without double-publishing:
+ * each row is claimed by exactly one worker per batch.
+ *
+ * At-least-once semantics: if the worker crashes after XADD but before the
+ * UPDATE commits, the row stays pending and will be republished. Consumers
+ * must be idempotent — enforce this at the handler level (e.g., dedup on
+ * `ctx.messageId` or domain-level idempotency keys).
+ */
+
+import type Redis from "ioredis";
+import { sql as sqlHelper, type SQL } from "bun";
+import { logger } from "../Logger";
+import type { RemoteMetrics } from "./metrics";
+
+const loggerInstance = logger.child({ scope: "OutboxWorker" });
+
+export interface OutboxWorkerConfig {
+    sourceApp: string;
+    streamPrefix: string;
+    pollIntervalMs: number;
+    batchSize: number;
+    enableLogging: boolean;
+}
+
+interface OutboxRow {
+    id: string;
+    target: string;
+    event: string;
+    data: unknown;
+    created_at: Date;
+}
+
+export class OutboxWorker {
+    private db: SQL;
+    private publisher: Redis;
+    private config: OutboxWorkerConfig;
+    private running = false;
+    private timer: ReturnType<typeof setTimeout> | null = null;
+    private currentTick: Promise<void> | null = null;
+    private metrics?: RemoteMetrics;
+
+    constructor(
+        db: SQL,
+        publisher: Redis,
+        config: OutboxWorkerConfig,
+        metrics?: RemoteMetrics
+    ) {
+        this.db = db;
+        this.publisher = publisher;
+        this.config = config;
+        this.metrics = metrics;
+    }
+
+    async start(): Promise<void> {
+        if (this.running) return;
+        this.running = true;
+        this.scheduleNext(0);
+        loggerInstance.info(
+            `OutboxWorker started pollMs=${this.config.pollIntervalMs} batch=${this.config.batchSize}`
+        );
+    }
+
+    async stop(): Promise<void> {
+        if (!this.running) return;
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.currentTick) {
+            await this.currentTick.catch(() => {});
+        }
+        loggerInstance.info("OutboxWorker stopped");
+    }
+
+    /**
+     * Force an immediate tick. Used during shutdown to flush any
+     * committed-but-unpublished rows before the process exits.
+     */
+    async flush(): Promise<void> {
+        await this.tick();
+    }
+
+    private scheduleNext(delayMs: number): void {
+        if (!this.running) return;
+        this.timer = setTimeout(() => {
+            this.currentTick = this.tick().finally(() => {
+                this.currentTick = null;
+                this.scheduleNext(this.config.pollIntervalMs);
+            });
+        }, delayMs);
+    }
+
+    private async tick(): Promise<void> {
+        if (!this.running) return;
+        try {
+            await this.processBatch();
+        } catch (error: any) {
+            loggerInstance.error(
+                { err: error, msg: "OutboxWorker tick error" }
+            );
+        }
+    }
+
+    private async processBatch(): Promise<void> {
+        const db = this.db as any;
+        await db.begin(async (trx: any) => {
+            const rows: OutboxRow[] = await trx`
+                SELECT id, target, event, data, created_at
+                FROM remote_outbox
+                WHERE published_at IS NULL
+                ORDER BY created_at
+                LIMIT ${this.config.batchSize}
+                FOR UPDATE SKIP LOCKED
+            `;
+
+            if (rows.length === 0) return;
+
+            this.metrics?.outboxClaimed(rows.length);
+            if (this.config.enableLogging) {
+                loggerInstance.debug(`Claimed ${rows.length} outbox rows`);
+            }
+
+            // Publish concurrently rather than serially. Each xadd is bounded
+            // by the publisher client's `commandTimeout`; with serial awaits a
+            // batch of N slow rows would hold PG row locks for N × timeout.
+            // Parallel keeps worst-case lock hold ≈ single-xadd timeout.
+            // (H-DB-1 partial — full fix requires a claim-via-column design
+            // so Redis latency no longer sits inside a PG transaction at all.)
+            const publishResults = await Promise.allSettled(
+                rows.map((row) => {
+                    const stream = `${this.config.streamPrefix}${row.target}`;
+                    const envelope = JSON.stringify({
+                        kind: "event",
+                        sourceApp: this.config.sourceApp,
+                        event: row.event,
+                        data: row.data,
+                        emittedAt: row.created_at.getTime(),
+                    });
+                    return this.publisher.xadd(stream, "*", "data", envelope);
+                })
+            );
+
+            const successIds: string[] = [];
+            for (let i = 0; i < publishResults.length; i++) {
+                const r = publishResults[i];
+                const row = rows[i]!;
+                if (r!.status === "fulfilled") {
+                    successIds.push(row.id);
+                } else {
+                    this.metrics?.outboxPublishFailed();
+                    loggerInstance.error({
+                        err: r!.reason,
+                        outboxId: row.id,
+                        target: row.target,
+                        event: row.event,
+                        msg: "Outbox XADD failed — row will retry next tick",
+                    });
+                    // Leave row unpublished; SKIP LOCKED releases on tx end
+                    // so next tick (or another instance) picks it up.
+                }
+            }
+
+            if (successIds.length > 0) {
+                // Single bulk UPDATE instead of N round-trips holding row
+                // locks (H-DB-3). Previously each success fired its own
+                // UPDATE statement serially. Uses Bun SQL's `sql(...)` helper
+                // for the IN-list so ids are parameterised individually.
+                await trx`
+                    UPDATE remote_outbox
+                    SET published_at = NOW()
+                    WHERE id IN ${sqlHelper(successIds)}
+                `;
+                this.metrics?.outboxPublished(successIds.length);
+            }
+        });
+    }
+}