bunsane 0.3.1 → 0.4.0

package/core/remote/types.ts

@@ -1,151 +1,153 @@
-/**
- * Remote Communication: Types
- *
- * Standalone types for cross-app events over Redis Streams.
- * RemoteContext is NOT derived from GraphQLContext — remote handlers run
- * outside request scope.
- */
-
-export interface RemoteContext {
-    sourceApp: string;
-    messageId: string;
-    timestamp: Date;
-    attempt: number;
-    correlationId?: string;
-    deadline?: Date;
-}
-
-export type RemoteHandler<T = unknown> = (
-    data: T,
-    ctx: RemoteContext
-) => Promise<void> | void;
-
-export type RemoteKind = "event" | "rpc_request";
-
-export interface RemoteHandlerInfo {
-    event: string;
-    methodName: string;
-    handlerId: string;
-    /** "event" for @RemoteEvent, "rpc_request" for @RemoteRpc */
-    kind: RemoteKind;
-}
-
-export interface RemoteEnvelope {
-    /** Discriminator — absent/`"event"` = fire-and-forget, `"rpc_request"` = RPC */
-    kind?: RemoteKind;
-    sourceApp: string;
-    event: string;
-    data: unknown;
-    emittedAt: number;
-
-    /** RPC-only */
-    correlationId?: string;
-    replyTo?: string;
-    deadline?: number;
-}
-
-export type RpcHandler<TIn = unknown, TOut = unknown> = (
-    data: TIn,
-    ctx: RemoteContext
-) => Promise<TOut> | TOut;
-
-export interface RpcSuccessResponse {
-    correlationId: string;
-    sourceApp: string;
-    success: true;
-    result: unknown;
-    respondedAt: number;
-}
-
-export interface RpcErrorResponse {
-    correlationId: string;
-    sourceApp: string;
-    success: false;
-    error: {
-        code: string;
-        message: string;
-        extensions?: Record<string, unknown>;
-    };
-    respondedAt: number;
-}
-
-export type RpcResponse = RpcSuccessResponse | RpcErrorResponse;
-
-export interface CallOptions {
-    /** Timeout in ms (default: 5000) */
-    timeout?: number;
-}
-
-/**
- * emit() options. Passing `trx` routes the event through the transactional
- * outbox — the row is inserted within the caller's transaction and
- * published by the OutboxWorker after commit.
- */
-export interface EmitOptions {
-    /** Transaction handle from `db.begin()` / `db.transaction()`. */
-    trx?: import("bun").SQL;
-}
-
-export interface RemoteErrorOptions {
-    code: string;
-    sourceApp?: string;
-    extensions?: Record<string, unknown>;
-}
-
-export class RemoteError extends Error {
-    public readonly code: string;
-    public readonly sourceApp?: string;
-    public readonly extensions?: Record<string, unknown>;
-
-    constructor(message: string, options: RemoteErrorOptions) {
-        super(message);
-        this.name = "RemoteError";
-        this.code = options.code;
-        this.sourceApp = options.sourceApp;
-        this.extensions = options.extensions;
-    }
-}
-
-export interface RemoteManagerConfig {
-    /** This app's identity — used as stream name and sourceApp field */
-    appName: string;
-    /** Consumer group (defaults to appName) */
-    consumerGroup?: string;
-    /** Unique consumer id within the group (defaults to pid + timestamp) */
-    consumerId?: string;
-    /** Stream key prefix (default: "remote:") */
-    streamPrefix?: string;
-    /** Enable verbose logging */
-    enableLogging?: boolean;
-    /** Max messages per XREADGROUP batch (default: 10) */
-    batchSize?: number;
-    /** XREADGROUP BLOCK timeout in ms (default: 2000) */
-    blockMs?: number;
-    /** XAUTOCLAIM idle threshold in ms on startup (default: 60000). 0 disables */
-    autoClaimIdleMs?: number;
-    /** Max response stream length cap per XADD MAXLEN ~ (default: 1000) */
-    responseStreamMaxLen?: number;
-    /** Default RPC call timeout in ms (default: 5000) */
-    defaultCallTimeout?: number;
-    /** Grace window for pending RPC calls during shutdown (default: 2000) */
-    shutdownDrainMs?: number;
-    /** Enable transactional outbox (default: false) */
-    enableOutbox?: boolean;
-    /** Outbox polling interval in ms (default: 1000) */
-    outboxPollIntervalMs?: number;
-    /** Max rows processed per outbox tick (default: 100) */
-    outboxBatchSize?: number;
-    /** Circuit breaker failure threshold before opening (default: 5) */
-    circuitBreakerThreshold?: number;
-    /** Circuit breaker reset timeout in ms (default: 30000) */
-    circuitBreakerResetMs?: number;
-    /** Max deliveries before routing a message to DLQ (default: 3, 0 disables) */
-    dlqMaxDeliveries?: number;
-    /**
-     * Test-only: override how Redis clients are constructed. Return a
-     * connected client compatible with the ioredis `Redis` interface.
-     * `blocking` is `true` for connections that will issue BLOCK commands
-     * (consumer + RPC listener), `false` for the publisher.
-     */
-    redisFactory?: (blocking: boolean) => any;
-}
+/**
+ * Remote Communication: Types
+ *
+ * Standalone types for cross-app events over Redis Streams.
+ * RemoteContext is NOT derived from GraphQLContext — remote handlers run
+ * outside request scope.
+ */
+
+export interface RemoteContext {
+    sourceApp: string;
+    messageId: string;
+    timestamp: Date;
+    attempt: number;
+    correlationId?: string;
+    deadline?: Date;
+}
+
+export type RemoteHandler<T = unknown> = (
+    data: T,
+    ctx: RemoteContext
+) => Promise<void> | void;
+
+export type RemoteKind = "event" | "rpc_request";
+
+export interface RemoteHandlerInfo {
+    event: string;
+    methodName: string;
+    handlerId: string;
+    /** "event" for @RemoteEvent, "rpc_request" for @RemoteRpc */
+    kind: RemoteKind;
+}
+
+export interface RemoteEnvelope {
+    /** Discriminator — absent/`"event"` = fire-and-forget, `"rpc_request"` = RPC */
+    kind?: RemoteKind;
+    sourceApp: string;
+    event: string;
+    data: unknown;
+    emittedAt: number;
+
+    /** RPC-only */
+    correlationId?: string;
+    replyTo?: string;
+    deadline?: number;
+}
+
+export type RpcHandler<TIn = unknown, TOut = unknown> = (
+    data: TIn,
+    ctx: RemoteContext
+) => Promise<TOut> | TOut;
+
+export interface RpcSuccessResponse {
+    correlationId: string;
+    sourceApp: string;
+    success: true;
+    result: unknown;
+    respondedAt: number;
+}
+
+export interface RpcErrorResponse {
+    correlationId: string;
+    sourceApp: string;
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        extensions?: Record<string, unknown>;
+    };
+    respondedAt: number;
+}
+
+export type RpcResponse = RpcSuccessResponse | RpcErrorResponse;
+
+export interface CallOptions {
+    /** Timeout in ms (default: 5000) */
+    timeout?: number;
+}
+
+/**
+ * emit() options. Passing `trx` routes the event through the transactional
+ * outbox — the row is inserted within the caller's transaction and
+ * published by the OutboxWorker after commit.
+ */
+export interface EmitOptions {
+    /** Transaction handle from `db.begin()` / `db.transaction()`. */
+    trx?: import("bun").SQL;
+}
+
+export interface RemoteErrorOptions {
+    code: string;
+    sourceApp?: string;
+    extensions?: Record<string, unknown>;
+}
+
+export class RemoteError extends Error {
+    public readonly code: string;
+    public readonly sourceApp?: string;
+    public readonly extensions?: Record<string, unknown>;
+
+    constructor(message: string, options: RemoteErrorOptions) {
+        super(message);
+        this.name = "RemoteError";
+        this.code = options.code;
+        this.sourceApp = options.sourceApp;
+        this.extensions = options.extensions;
+    }
+}
+
+export interface RemoteManagerConfig {
+    /** This app's identity — used as stream name and sourceApp field */
+    appName: string;
+    /** Consumer group (defaults to appName) */
+    consumerGroup?: string;
+    /** Unique consumer id within the group (defaults to pid + timestamp) */
+    consumerId?: string;
+    /** Stream key prefix (default: "remote:") */
+    streamPrefix?: string;
+    /** Enable verbose logging */
+    enableLogging?: boolean;
+    /** Max messages per XREADGROUP batch (default: 10) */
+    batchSize?: number;
+    /** XREADGROUP BLOCK timeout in ms (default: 2000) */
+    blockMs?: number;
+    /** XAUTOCLAIM idle threshold in ms on startup (default: 60000). 0 disables */
+    autoClaimIdleMs?: number;
+    /** Max response stream length cap per XADD MAXLEN ~ (default: 1000) */
+    responseStreamMaxLen?: number;
+    /** Default RPC call timeout in ms (default: 5000) */
+    defaultCallTimeout?: number;
+    /** Grace window for pending RPC calls during shutdown (default: 2000) */
+    shutdownDrainMs?: number;
+    /** Enable transactional outbox (default: false) */
+    enableOutbox?: boolean;
+    /** Outbox polling interval in ms (default: 1000) */
+    outboxPollIntervalMs?: number;
+    /** Max rows processed per outbox tick (default: 100) */
+    outboxBatchSize?: number;
+    /** How long to keep published outbox rows before deletion in ms (default: 86400000 / 24h, 0 disables) */
+    outboxRetentionMs?: number;
+    /** Circuit breaker failure threshold before opening (default: 5) */
+    circuitBreakerThreshold?: number;
+    /** Circuit breaker reset timeout in ms (default: 30000) */
+    circuitBreakerResetMs?: number;
+    /** Max deliveries before routing a message to DLQ (default: 3, 0 disables) */
+    dlqMaxDeliveries?: number;
+    /**
+     * Test-only: override how Redis clients are constructed. Return a
+     * connected client compatible with the ioredis `Redis` interface.
+     * `blocking` is `true` for connections that will issue BLOCK commands
+     * (consumer + RPC listener), `false` for the publisher.
+     */
+    redisFactory?: (blocking: boolean) => any;
+}

package/core/requestScope.ts

@@ -0,0 +1,34 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { RequestLoaders } from "./RequestLoaders";
+import type { PerRequestCounters } from "../database/instrumentedDb";
+
+/**
+ * Ambient per-request context carrying the request's DataLoaders,
+ * AbortSignal and per-request counters via AsyncLocalStorage.
+ *
+ * Why: explicit `context` threading only reaches call sites that accept a
+ * context parameter. `@ArcheTypeFunction` bodies, `Unwrap()`, and service
+ * helpers call `entity.get(Component)` bare — without this scope every such
+ * call is an individual SELECT (N+1 per parent row). The GraphQL request
+ * plugin (`createRequestContextPlugin`) wraps execution in
+ * `runWithRequestScope`, so `Entity._loadComponent` and the relation
+ * population helpers can fall back to the request's batching DataLoaders
+ * when no explicit context is provided.
+ *
+ * Imports are type-only — no runtime dependency cycle with Entity/loaders.
+ */
+export interface RequestScope {
+    loaders: RequestLoaders;
+    signal?: AbortSignal;
+    perRequest?: PerRequestCounters;
+}
+
+const storage = new AsyncLocalStorage<RequestScope>();
+
+export function runWithRequestScope<T>(scope: RequestScope, fn: () => T): T {
+    return storage.run(scope, fn);
+}
+
+export function getRequestScope(): RequestScope | undefined {
+    return storage.getStore();
+}

package/core/scheduler/cronEvaluator.ts

@@ -0,0 +1,174 @@
+import { logger } from "../Logger";
+import { CronParser } from "../../utils/cronParser";
+import { ScheduleInterval } from "../../types/scheduler.types";
+import type { ScheduledTaskInfo } from "../../types/scheduler.types";
+import type { SchedulerManager } from "../SchedulerManager";
+
+const loggerInstance = logger.child({ scope: "SchedulerManager" });
+
+export function getIntervalMilliseconds(interval: ScheduleInterval): number {
+    switch (interval) {
+        case ScheduleInterval.MINUTE:
+            return 60 * 1000; // 1 minute
+        case ScheduleInterval.HOUR:
+            return 60 * 60 * 1000; // 1 hour
+        case ScheduleInterval.DAILY:
+            return 24 * 60 * 60 * 1000; // 24 hours
+        case ScheduleInterval.WEEKLY:
+            return 7 * 24 * 60 * 60 * 1000; // 7 days
+        case ScheduleInterval.MONTHLY:
+            return 30 * 24 * 60 * 60 * 1000; // 30 days (approximate)
+        default:
+            throw new Error(`Unsupported interval: ${interval}`);
+    }
+}
+
+export function scheduleLongIntervalTask(manager: SchedulerManager, taskInfo: ScheduledTaskInfo, intervalMs: number): void {
+    // For very long intervals, use a shorter check interval to avoid timeout overflow
+    const checkInterval = Math.min(intervalMs, 24 * 60 * 60 * 1000); // Max 24 hours check interval
+    const nextExecution = new Date(Date.now() + intervalMs);
+    taskInfo.nextExecution = nextExecution;
+
+    const intervalId = setInterval(async () => {
+        const now = Date.now();
+        if (now >= nextExecution.getTime()) {
+            await (manager as any).executeTask(taskInfo.id);
+            // Reschedule for next execution
+            taskInfo.nextExecution = new Date(now + intervalMs);
+        }
+    }, checkInterval);
+
+    manager.intervals.set(taskInfo.id, intervalId);
+}
+
+export function scheduleIntervalTask(manager: SchedulerManager, taskInfo: ScheduledTaskInfo): void {
+    const intervalMs = getIntervalMilliseconds(taskInfo.interval);
+
+    // Clear any existing interval for this task before creating a new one
+    const existingInterval = manager.intervals.get(taskInfo.id);
+    if (existingInterval) {
+        clearInterval(existingInterval);
+        manager.intervals.delete(taskInfo.id);
+    }
+
+    // For very long intervals (monthly), use a different approach
+    if (intervalMs > 24 * 60 * 60 * 1000) { // More than 24 hours
+        scheduleLongIntervalTask(manager, taskInfo, intervalMs);
+    } else {
+        const intervalId = setInterval(async () => {
+            await (manager as any).executeTask(taskInfo.id);
+        }, intervalMs);
+
+        manager.intervals.set(taskInfo.id, intervalId);
+        taskInfo.nextExecution = new Date(Date.now() + intervalMs);
+    }
+
+    if (manager.config.enableLogging) {
+        loggerInstance.info(`Scheduled task ${taskInfo.name} to run every ${intervalMs}ms`);
+    }
+}
+
+export function scheduleCronTask(manager: SchedulerManager, taskInfo: ScheduledTaskInfo): void {
+    if (!taskInfo.cronExpression) {
+        throw new Error(`Cron expression is required for CRON interval tasks`);
+    }
+
+    // Validate cron expression
+    const validation = CronParser.validate(taskInfo.cronExpression);
+    if (!validation.isValid) {
+        throw new Error(`Invalid cron expression: ${validation.error}`);
+    }
+
+    // Calculate next execution time
+    const nextExecution = CronParser.getNextExecution(validation.fields!, new Date());
+    if (!nextExecution) {
+        throw new Error(`Unable to calculate next execution time for cron expression: ${taskInfo.cronExpression}`);
+    }
+
+    taskInfo.nextExecution = nextExecution;
+
+    // Clear any existing timeout for this task before creating a new one
+    const existingTimeout = manager.intervals.get(taskInfo.id);
+    if (existingTimeout) {
+        clearTimeout(existingTimeout as any);
+    }
+
+    // Schedule the task to run at the calculated time
+    const timeoutId = setTimeout(async () => {
+        await (manager as any).executeTask(taskInfo.id);
+        // Reschedule for next execution
+        scheduleCronTask(manager, taskInfo);
+    }, nextExecution.getTime() - Date.now());
+
+    manager.intervals.set(taskInfo.id, timeoutId as any);
+
+    if (manager.config.enableLogging) {
+        loggerInstance.info(`Scheduled cron task ${taskInfo.name} to run at ${nextExecution.toISOString()}`);
+    }
+}
+
+export function scheduleTask(manager: SchedulerManager, taskInfo: ScheduledTaskInfo): void {
+    try {
+        if (taskInfo.interval === ScheduleInterval.CRON) {
+            scheduleCronTask(manager, taskInfo);
+        } else {
+            scheduleIntervalTask(manager, taskInfo);
+        }
+    } catch (error) {
+        loggerInstance.error(`Failed to schedule task ${taskInfo.name}: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
+    }
+}
+
+export function scheduleJob(
+    manager: SchedulerManager,
+    name: string,
+    cronExpression: string,
+    callback: () => Promise<void> | void
+): { cancel: () => void } {
+    const jobId = `job_${name}_${Date.now()}`;
+
+    // Validate cron expression
+    const validation = CronParser.validate(cronExpression);
+    if (!validation.isValid) {
+        throw new Error(`Invalid cron expression for job "${name}": ${validation.error}`);
+    }
+
+    let timeoutId: ReturnType<typeof setTimeout> | null = null;
+    let cancelled = false;
+
+    const scheduleNextExecution = () => {
+        if (cancelled) return;
+
+        const nextExecution = CronParser.getNextExecution(validation.fields!, new Date());
+        if (!nextExecution) {
+            loggerInstance.warn(`Unable to calculate next execution for job "${name}"`);
+            return;
+        }
+
+        const delay = nextExecution.getTime() - Date.now();
+        timeoutId = setTimeout(async () => {
+            if (cancelled) return;
+            try {
+                await callback();
+            } catch (error) {
+                loggerInstance.error(`Job "${name}" failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            scheduleNextExecution();
+        }, delay);
+
+        manager.intervals.set(jobId, timeoutId as any);
+    };
+
+    scheduleNextExecution();
+
+    return {
+        cancel: () => {
+            cancelled = true;
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                manager.intervals.delete(jobId);
+            }
+        }
+    };
+}

package/core/scheduler/lifecycleHooks.ts

@@ -0,0 +1,21 @@
+import ApplicationLifecycle, { ApplicationPhase } from "../ApplicationLifecycle";
+import type { SchedulerManager } from "../SchedulerManager";
+
+export function initializeLifecycleIntegration(manager: SchedulerManager): void {
+    manager.phaseListener = (event) => {
+        const phase = event.detail;
+        if (phase === ApplicationPhase.APPLICATION_READY) {
+            if (manager.config.runOnStart) {
+                manager.start();
+            }
+        }
+    };
+    ApplicationLifecycle.addPhaseListener(manager.phaseListener);
+}
+
+export function disposeLifecycleIntegration(manager: SchedulerManager): void {
+    if (manager.phaseListener) {
+        ApplicationLifecycle.removePhaseListener(manager.phaseListener);
+        manager.phaseListener = null;
+    }
+}

package/core/scheduler/lockCoordinator.ts

@@ -0,0 +1,27 @@
+import type { DistributedLockConfig } from "./DistributedLock";
+import type { SchedulerManager } from "../SchedulerManager";
+
+export function getDistributedLockInfo(manager: SchedulerManager): {
+    enabled: boolean;
+    heldLocks: number;
+    config: DistributedLockConfig;
+} {
+    return {
+        enabled: manager.config.distributedLocking !== false,
+        heldLocks: manager.distributedLock.getHeldLockCount(),
+        config: manager.distributedLock.getConfig(),
+    };
+}
+
+export function isDistributedLockingEnabled(manager: SchedulerManager): boolean {
+    return manager.config.distributedLocking !== false;
+}
+
+export function syncLockConfig(manager: SchedulerManager): void {
+    manager.distributedLock.updateConfig({
+        enabled: manager.config.distributedLocking ?? true,
+        enableLogging: manager.config.enableLogging,
+        lockTimeout: manager.config.lockTimeout ?? 0,
+        retryInterval: manager.config.lockRetryInterval ?? 100,
+    });
+}

package/core/scheduler/metrics.ts

@@ -0,0 +1,14 @@
+import type { SchedulerMetrics, TaskMetrics } from "../../types/scheduler.types";
+import type { SchedulerManager } from "../SchedulerManager";
+
+export function getMetrics(manager: SchedulerManager): SchedulerMetrics {
+    return { ...manager.metrics };
+}
+
+export function getTaskMetrics(manager: SchedulerManager, taskId: string): TaskMetrics | null {
+    return manager.metrics.taskMetrics[taskId] || null;
+}
+
+export function getAllTaskMetrics(manager: SchedulerManager): Record<string, TaskMetrics> {
+    return { ...manager.metrics.taskMetrics };
+}