@gobing-ai/ts-infra 0.3.9 → 0.3.11

package/src/event-bus/event-bus.ts

@@ -1,8 +1,9 @@
-import type { JobQueue } from '../job-queue/types';
+import type { JobHandler, JobQueue } from '../job-queue/types';
 import { getLogger, type Logger } from '../logger';
 import { getEventbusEmitsTotal, getEventbusErrorsTotal } from '../telemetry/metrics';
 import type {
     AsyncEnqueuedDetail,
+    AsyncEventJobPayload,
     BusLifecycleEvents,
     EmitDoneDetail,
     EventMap,
@@ -23,22 +24,25 @@ function busLogger(): Logger {
 export class EventBus<TEvents extends EventMap> {
     private readonly syncHandlers = new Map<keyof TEvents, Set<TEvents[keyof TEvents]>>();
     private readonly asyncHandlers = new Map<keyof TEvents, Set<TEvents[keyof TEvents]>>();
-    private readonly asyncHandlerIds = new WeakMap<TEvents[keyof TEvents], string>();
+    private readonly asyncHandlerIds = new Map<TEvents[keyof TEvents], string>();
+    private readonly asyncHandlersById = new Map<string, TEvents[keyof TEvents]>();
     private readonly jobQueue: JobQueue | null;
     private readonly lifecycleBus: EventBus<BusLifecycleEvents> | null;
+    private readonly logger: Logger | undefined;
     private nextAsyncHandlerId = 0;
-
     constructor(opts?: {
         jobQueue?: JobQueue;
         lifecycleBus?: EventBus<BusLifecycleEvents>;
+        logger?: Logger;
     }) {
         this.jobQueue = opts?.jobQueue ?? null;
         this.lifecycleBus = opts?.lifecycleBus ?? null;
+        this.logger = opts?.logger;
     }
 
     on<K extends keyof TEvents>(event: K, handler: TEvents[K], opts?: SubscribeOptions): void {
         if (opts?.async) {
-            this.registerAsync(event, handler);
+            this.registerAsync(event, handler, opts.name);
         } else {
             this.registerSync(event, handler);
         }
@@ -68,16 +72,23 @@ export class EventBus<TEvents extends EventMap> {
             if (asyncSet.size === 0) {
                 this.asyncHandlers.delete(event);
             }
+            this.releaseAsyncIdIfUnsubscribed(handler);
         }
     }
 
     removeAllListeners<K extends keyof TEvents>(event?: K): void {
         if (event !== undefined) {
             this.syncHandlers.delete(event);
+            const asyncSet = this.asyncHandlers.get(event);
             this.asyncHandlers.delete(event);
+            if (asyncSet) {
+                for (const handler of asyncSet) this.releaseAsyncIdIfUnsubscribed(handler);
+            }
         } else {
             this.syncHandlers.clear();
             this.asyncHandlers.clear();
+            this.asyncHandlerIds.clear();
+            this.asyncHandlersById.clear();
         }
     }
 
@@ -88,6 +99,12 @@ export class EventBus<TEvents extends EventMap> {
         let asyncCount = 0;
         let errors = 0;
 
+        this.logger?.debug('event.emit', {
+            event: eventName,
+            syncHandlers: this.syncHandlers.get(event)?.size ?? 0,
+            asyncHandlers: this.asyncHandlers.get(event)?.size ?? 0,
+        });
+
         const syncSet = this.syncHandlers.get(event);
         if (syncSet) {
             syncCount = syncSet.size;
@@ -179,13 +196,22 @@ export class EventBus<TEvents extends EventMap> {
         set.add(handler);
     }
 
-    private registerAsync<K extends keyof TEvents>(event: K, handler: TEvents[K]): void {
+    private registerAsync<K extends keyof TEvents>(event: K, handler: TEvents[K], name?: string): void {
         let set = this.asyncHandlers.get(event);
         if (!set) {
             set = new Set();
             this.asyncHandlers.set(event, set);
         }
         set.add(handler);
+
+        if (!this.asyncHandlerIds.has(handler)) {
+            const id = name ?? `handler-${++this.nextAsyncHandlerId}`;
+            if (this.asyncHandlersById.has(id)) {
+                throw new Error(`Duplicate async handler name: "${id}"`);
+            }
+            this.asyncHandlerIds.set(handler, id);
+            this.asyncHandlersById.set(id, handler);
+        }
     }
 
     private getAsyncHandlerId(handler: TEvents[keyof TEvents]): string {
@@ -194,9 +220,50 @@ export class EventBus<TEvents extends EventMap> {
 
         const id = `handler-${++this.nextAsyncHandlerId}`;
         this.asyncHandlerIds.set(handler, id);
+        this.asyncHandlersById.set(id, handler);
         return id;
     }
 
+    /** Drop a handler's id mappings once it is subscribed to no event at all. */
+    private releaseAsyncIdIfUnsubscribed(handler: TEvents[keyof TEvents]): void {
+        for (const set of this.asyncHandlers.values()) {
+            if (set.has(handler)) return;
+        }
+        const id = this.asyncHandlerIds.get(handler);
+        if (id !== undefined) {
+            this.asyncHandlerIds.delete(handler);
+            this.asyncHandlersById.delete(id);
+        }
+    }
+
+    /**
+     * Bridge for queue-backed async dispatch: returns a `JobHandler` to
+     * register on a queue consumer for each async event's job type. It
+     * dispatches the enqueued `{ event, args, handlerId }` payload back to the
+     * matching async handler on THIS bus instance.
+     *
+     * Use named async subscriptions (`SubscribeOptions.name`) when jobs may be
+     * consumed after a process restart — anonymous handler ids are
+     * process-local and not stable across restarts.
+     *
+     * @throws when the payload references an unknown handler id, so the job
+     * lands in the queue's retry/fail path instead of vanishing silently.
+     */
+    createJobHandler(): JobHandler<AsyncEventJobPayload> {
+        return async (job) => {
+            const { event, args, handlerId } = job.payload;
+            const handler = this.asyncHandlersById.get(handlerId);
+            if (!handler) {
+                throw new Error(`No async handler registered for id "${handlerId}" (event "${event}")`);
+            }
+            // Serialization round-trips args through unknown[]; the handler type
+            // is `TEvents[K] & ((...args: unknown[]) => void)` — both satisfy the
+            // same constraint. Use unknown => unknown to bridge the covariance gap.
+            type AnyHandler = (...args: unknown[]) => unknown;
+            await (handler as unknown as AnyHandler)(...args);
+        };
+    }
+
     private publishEmitDone(detail: EmitDoneDetail): void {
         if (this.lifecycleBus) {
             try {

package/src/event-bus/index.ts

@@ -8,6 +8,7 @@ export { EventBus } from './event-bus';
 export { attachFileObserver, type FileObserverWriter } from './file-observer';
 export type {
     AsyncEnqueuedDetail,
+    AsyncEventJobPayload,
     BusLifecycleEvents,
     EmitDoneDetail,
     EventMap,

package/src/event-bus/types.ts

@@ -9,6 +9,25 @@ export type EventMap = Record<string, (...args: never[]) => void>;
 export interface SubscribeOptions {
     /** When true, the handler is dispatched through the async handler path. */
     async?: boolean;
+    /**
+     * Stable identifier for an async handler. Used as the `handlerId` in jobs
+     * enqueued through an injected `JobQueue`, so a queue consumer (see
+     * `EventBus.createJobHandler`) can dispatch jobs back to this handler —
+     * including after a process restart. Anonymous async handlers get a
+     * process-local generated id that is NOT stable across restarts.
+     * Must be unique per bus instance.
+     */
+    name?: string;
+}
+
+/** Payload shape the bus enqueues for queue-backed async handlers. */
+export interface AsyncEventJobPayload {
+    /** Event name the handler was subscribed to. */
+    event: string;
+    /** Arguments the event was emitted with. */
+    args: unknown[];
+    /** Async handler id (subscription `name` or a generated id). */
+    handlerId: string;
 }
 
 // ── Lifecycle events ────────────────────────────────────────────────

package/src/events.ts

@@ -2,8 +2,11 @@
  * Infrastructure-level event definitions for ts-infra observability.
  *
  * Mirrors the package-local pattern in `@gobing-ai/ts-ai-runner` (`events.ts`):
- * only the events ts-infra components actually emit live here. Application-domain
- * events (history import, HTTP server, …) belong to the consuming app, not this
+ * these maps define the infra-level event *contract*. ts-infra itself currently
+ * emits only `queue.stats` (`QueueStatsAction`) and `scheduler.job.executed`
+ * (`wrapScheduledHandler`); the remaining events are contracts for the consuming
+ * app or higher-level wiring to emit on the same bus. Application-domain events
+ * (history import, HTTP server, …) belong to the consuming app, not this
  * library. Process events belong to `@gobing-ai/ts-runtime` (the owner of
  * `ProcessExecutor`) and are intentionally not re-exported here.
  *

package/src/index.ts

@@ -1,8 +1,16 @@
 // API Client
-export { APIClient, type APIClientConfig, APIError, type RequestOptions } from './api-client';
+export {
+    APIClient,
+    type APIClientConfig,
+    APIError,
+    type RawHttpResponse,
+    type RawRequestOptions,
+    type RequestOptions,
+} from './api-client';
 
 // Event Bus
 export {
+    type AsyncEventJobPayload,
     attachDefaultObservers,
     attachFileObserver,
     attachLogObserver,

package/src/job-queue/db-job-queue.ts

@@ -1,4 +1,7 @@
 import type { QueueJobDao, QueueJobRecord, QueueStats } from '@gobing-ai/ts-db';
+import type { EventBus } from '../event-bus/event-bus';
+import type { QueueEvents } from '../events';
+import { getLogger, type Logger } from '../logger';
 import {
     getQueueJobCompletedTotal,
     getQueueJobEnqueuedTotal,
@@ -8,19 +11,34 @@ import {
 import { addSpanAttributes, traceAsync } from '../telemetry/tracing';
 import type { EnqueueOptions, Job, JobHandler, JobQueue, QueueConsumer, QueueConsumerConfig } from './types';
 
+let _queueLogger: Logger | undefined;
+function queueLogger(): Logger {
+    if (!_queueLogger) _queueLogger = getLogger('job-queue');
+    return _queueLogger;
+}
+
 /** DB-backed job queue implementation over `@gobing-ai/ts-db`'s `QueueJobDao`. */
 export class DBJobQueue<T = unknown> implements JobQueue<T> {
-    constructor(readonly dao: QueueJobDao) {}
+    constructor(
+        readonly dao: QueueJobDao,
+        private readonly events?: EventBus<QueueEvents>,
+    ) {}
 
     async enqueue(type: string, payload: T, options?: EnqueueOptions): Promise<string> {
         const id = await this.dao.enqueue(type, payload, options);
         getQueueJobEnqueuedTotal().add(1, { type });
+        await this.events?.emit('queue.job.enqueued', { jobId: id, type });
         return id;
     }
 
     async enqueueBatch(jobs: Array<{ type: string; payload: T } & EnqueueOptions>): Promise<string[]> {
         const ids = await this.dao.enqueueBatch(jobs);
         getQueueJobEnqueuedTotal().add(jobs.length);
+        if (this.events) {
+            for (const [index, jobId] of ids.entries()) {
+                await this.events.emit('queue.job.enqueued', { jobId, type: jobs[index]?.type ?? 'unknown' });
+            }
+        }
         return ids;
     }
 
@@ -39,6 +57,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
     private readonly baseDelay: number;
     private readonly maxDelay: number;
     private readonly drainTimeoutMs: number;
+    private readonly events: EventBus<QueueEvents> | undefined;
     private timer: ReturnType<typeof setTimeout> | null = null;
     private running = false;
     private inFlight = 0;
@@ -54,6 +73,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         this.baseDelay = config.baseDelay ?? 1_000;
         this.maxDelay = config.maxDelay ?? 60_000;
         this.drainTimeoutMs = config.drainTimeoutMs ?? 30_000;
+        this.events = config.events;
     }
 
     register(type: string, handler: JobHandler<T>): void {
@@ -64,9 +84,11 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         if (this.running) return;
         this.running = true;
         this.schedule(0);
+        await this.events?.emit('queue.consumer.started');
     }
 
     async stop(): Promise<void> {
+        const wasRunning = this.running;
         this.running = false;
         if (this.timer !== null) {
             clearTimeout(this.timer);
@@ -77,6 +99,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         while (this.inFlight > 0 && Date.now() < deadline) {
             await sleep(10);
         }
+        if (wasRunning) await this.events?.emit('queue.consumer.stopped');
     }
 
     async stats(): Promise<QueueStats> {
@@ -122,13 +145,28 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         if (!this.running) return;
         try {
             await this.processOnce();
+        } catch (error) {
+            // The timer fires poll() as a floating promise — a DAO/processing error
+            // must be contained here or it becomes an unhandled rejection that can
+            // kill the process. Log and let the next cycle retry.
+            queueLogger().error('queue poll cycle failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
         } finally {
             if (this.running) this.schedule(this.pollInterval);
         }
     }
 
     private async processJob(record: QueueJobRecord): Promise<void> {
-        const job = toJob<T>(record);
+        let job: Job<T>;
+        try {
+            job = toJob<T>(record);
+        } catch (error) {
+            // Corrupt payload — the job can never parse; route it through the
+            // retry/fail path instead of rejecting the whole batch.
+            await this.failOrRetry(record, error);
+            return;
+        }
         return traceAsync('queue.job.process', async () => {
             addSpanAttributes({
                 'queue.job_id': job.id,
@@ -148,6 +186,7 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
                 await this.dao.markCompleted(job.id);
                 getQueueJobCompletedTotal().add(1, { type: job.type });
                 getQueueJobProcessingDuration().record(performance.now() - startMs, { type: job.type });
+                await this.events?.emit('queue.job.completed', { jobId: job.id, type: job.type });
             } catch (error) {
                 getQueueJobProcessingDuration().record(performance.now() - startMs, { type: job.type });
                 await this.failOrRetry(job, error);
@@ -155,17 +194,33 @@ export class DBQueueConsumer<T = unknown> implements QueueConsumer<T> {
         });
     }
 
-    private async failOrRetry(job: Job<T>, error: unknown): Promise<void> {
+    private async failOrRetry(
+        job: Pick<Job<T>, 'id' | 'type' | 'attempts' | 'maxRetries'>,
+        error: unknown,
+    ): Promise<void> {
         const attempts = job.attempts + 1;
         const message = error instanceof Error ? error.message : String(error);
         if (attempts >= job.maxRetries) {
             await this.dao.markFailed(job.id, attempts, message);
             getQueueJobFailedTotal().add(1, { type: job.type });
+            await this.events?.emit('queue.job.failed', {
+                jobId: job.id,
+                type: job.type,
+                error: message,
+                attempt: attempts,
+            });
             return;
         }
 
         const delay = Math.min(this.maxDelay, this.baseDelay * 2 ** Math.max(0, attempts - 1));
-        await this.dao.markForRetry(job.id, attempts, message, Date.now() + delay);
+        const nextRetryAt = Date.now() + delay;
+        await this.dao.markForRetry(job.id, attempts, message, nextRetryAt);
+        await this.events?.emit('queue.job.retrying', {
+            jobId: job.id,
+            type: job.type,
+            attempt: attempts,
+            nextRetryAt,
+        });
     }
 }
 

package/src/job-queue/types.ts

@@ -5,6 +5,9 @@
  * `DBJobQueue` and `DBQueueConsumer`.
  */
 
+import type { EventBus } from '../event-bus/event-bus';
+import type { QueueEvents } from '../events';
+
 /** A queued job with status tracking, retry metadata, and timestamps. */
 export interface Job<T = unknown> {
     id: string;
@@ -54,6 +57,12 @@ export interface QueueConsumerConfig {
     baseDelay?: number;
     maxDelay?: number;
     drainTimeoutMs?: number;
+    /**
+     * Optional bus for queue lifecycle events: `queue.consumer.started` /
+     * `queue.consumer.stopped` and `queue.job.completed` / `queue.job.failed` /
+     * `queue.job.retrying`. Omitting it leaves the consumer silent (default).
+     */
+    events?: EventBus<QueueEvents>;
 }
 
 /** Consumer interface for the job queue — register handlers and control the processing loop. */

package/src/scheduler/action.ts

@@ -110,7 +110,7 @@ export class QueueStatsAction implements SchedulerAction {
         const dao = await this.daoProvider();
         const stats = await dao.getStats();
         logger.info('Queue stats snapshot', { action: this.name, ...stats });
-        this.systemBus?.emit('queue.stats', stats);
+        await this.systemBus?.emit('queue.stats', stats);
     }
 }
 

package/src/scheduler/node.ts

@@ -2,6 +2,7 @@
  * Node.js scheduler adapter using a simple setInterval-based approach.
  * No external cron library dependency — cron expressions are parsed minimally.
  */
+import { getLogger } from '../logger';
 import {
     getSchedulerJobDuration,
     getSchedulerJobExecutedTotal,
@@ -13,21 +14,28 @@ import type { ScheduledAction, SchedulerAdapter } from './types';
 function parseInterval(cron: string): number {
     // Support simple patterns: "* * * * *" (every minute), "*/5 * * * *" (every 5 min)
     // Also support direct ms strings like "60000"
-    const num = Number(cron);
-    if (!Number.isNaN(num)) return num;
-
-    const parts = cron.trim().split(/\s+/);
-    if (parts.length === 5 && parts[0] === '*') {
-        return 60_000; // every minute default
-    }
+    const trimmed = cron.trim();
+    const num = Number(trimmed);
+    if (trimmed !== '' && !Number.isNaN(num)) {
+        // Guard against 0/negative intervals — setInterval would spin hot.
+        if (num > 0) return num;
+    } else {
+        const parts = trimmed.split(/\s+/);
+        if (parts.length === 5 && parts[0] === '*') {
+            return 60_000; // every minute
+        }
 
-    // */N pattern
-    const match = parts[0]?.match(/^\*\/(\d+)$/);
-    if (match) {
-        return Number(match[1]) * 60_000;
+        // */N pattern
+        const match = parts[0]?.match(/^\*\/(\d+)$/);
+        if (match && Number(match[1]) > 0) {
+            return Number(match[1]) * 60_000;
+        }
     }
 
-    return 60_000; // fallback: every minute
+    // Real cron field expressions ("0 3 * * *") are NOT supported — running
+    // them every minute silently would badly misfire, so warn on fallback.
+    getLogger('scheduler.node').warn('Unsupported cron expression — falling back to a 60s interval', { cron });
+    return 60_000;
 }
 
 interface ScheduledEntry {

package/src/scheduler/wrap-handler.ts

@@ -43,7 +43,7 @@ export function wrapScheduledHandler(
                 const durationMs = Math.round(performance.now() - startTime);
                 addSpanAttributes({ 'scheduler.duration_ms': durationMs });
 
-                systemBus?.emit('scheduler.job.executed', {
+                void systemBus?.emit('scheduler.job.executed', {
                     name,
                     durationMs,
                     ...(execError !== undefined ? { error: execError } : {}),

package/src/telemetry/metrics.ts

@@ -2,7 +2,8 @@
  * OpenTelemetry metrics — lazy-initialized instruments.
  * All degrade to no-ops when telemetry is disabled.
  */
-import { type Counter, type Histogram, metrics } from '@opentelemetry/api';
+import { type Counter, createNoopMeter, type Histogram, metrics } from '@opentelemetry/api';
+import { getResolvedConfig } from './sdk';
 
 export type { Counter, Histogram } from '@opentelemetry/api';
 
@@ -25,7 +26,24 @@ function getMeter() {
 
 const instruments: Record<string, Counter | Histogram | undefined> = {};
 
+// Master switch (`TelemetryConfig.enabled`): when explicitly disabled, getters
+// return shared no-op instruments WITHOUT touching the cache, so a later
+// re-enable rebuilds real instruments against the live meter.
+let _noopCounter: Counter | undefined;
+let _noopHistogram: Histogram | undefined;
+
+function noopCounter(): Counter {
+    if (!_noopCounter) _noopCounter = createNoopMeter().createCounter('noop');
+    return _noopCounter;
+}
+
+function noopHistogram(): Histogram {
+    if (!_noopHistogram) _noopHistogram = createNoopMeter().createHistogram('noop');
+    return _noopHistogram;
+}
+
 function getOrCreateCounter(key: string, name: string, description: string, unit = '{operation}'): Counter {
+    if (!getResolvedConfig().enabled) return noopCounter();
     if (!instruments[key]) {
         instruments[key] = getMeter().createCounter(name, { description, unit });
     }
@@ -33,6 +51,7 @@ function getOrCreateCounter(key: string, name: string, description: string, unit
 }
 
 function getOrCreateHistogram(key: string, name: string, description: string, unit = 'ms'): Histogram {
+    if (!getResolvedConfig().enabled) return noopHistogram();
     if (!instruments[key]) {
         instruments[key] = getMeter().createHistogram(name, { description, unit });
     }

package/src/telemetry/sdk.ts

@@ -16,7 +16,11 @@ import { type Tracer, trace } from '@opentelemetry/api';
  * environment, and debug-level DB statement capture.
  */
 export interface TelemetryConfig {
-    /** Master switch — when false, all tracing degrades to no-ops. */
+    /**
+     * Master switch — when false, infra-created spans and metric instruments
+     * degrade to no-ops even if a global OTel provider is registered.
+     * Explicitly injected tracer ports (ADR-009 addendum) are unaffected.
+     */
     enabled: boolean;
     /** Logical service name emitted on every span. */
     serviceName: string;
@@ -29,7 +33,8 @@ export interface TelemetryConfig {
      * attribute. SQL text is redacted — parameter values, literals, and
      * identifiers are stripped before capture.
      *
-     * Default: `false`. Controlled by `OTEL_DB_STATEMENT_DEBUG` env var.
+     * Default: `false`. Set via config — ts-infra core never reads env vars
+     * (ADR-011); map an env var to this flag in your bootstrap if desired.
      */
     dbStatementDebug: boolean;
 }

package/src/telemetry/tracing.ts

@@ -2,8 +2,22 @@
  * High-level tracing helpers for application code.
  */
 
-import { context, type Span, type SpanOptions, type Tracer, trace } from '@opentelemetry/api';
-import { getTracer } from './sdk';
+import { context, INVALID_SPAN_CONTEXT, type Span, type SpanOptions, type Tracer, trace } from '@opentelemetry/api';
+import { getResolvedConfig, getTracer } from './sdk';
+
+/**
+ * Master switch (`TelemetryConfig.enabled`): when explicitly disabled, infra
+ * helpers bypass the global provider entirely. An explicitly injected tracer
+ * (ADR-009 addendum structural port) is honored regardless — the caller opted in.
+ */
+function isSuppressed(tracer: Tracer | undefined): boolean {
+    return tracer === undefined && !getResolvedConfig().enabled;
+}
+
+/** A non-recording span satisfying the `Span` interface — every method is a no-op. */
+function nonRecordingSpan(): Span {
+    return trace.wrapSpanContext(INVALID_SPAN_CONTEXT);
+}
 
 /**
  * Execute an async function within an active OTel span.
@@ -15,6 +29,8 @@ export async function traceAsync<T>(
     options?: SpanOptions,
     tracer?: Tracer,
 ): Promise<T> {
+    if (isSuppressed(tracer)) return fn(nonRecordingSpan());
+
     const resolvedTracer = tracer ?? getTracer();
     return resolvedTracer.startActiveSpan(name, options ?? {}, async (span) => {
         try {
@@ -33,6 +49,8 @@ export async function traceAsync<T>(
  * The span is automatically ended and its status set on error.
  */
 export function traceSync<T>(name: string, fn: (span: Span) => T, options?: SpanOptions, tracer?: Tracer): T {
+    if (isSuppressed(tracer)) return fn(nonRecordingSpan());
+
     const resolvedTracer = tracer ?? getTracer();
     return resolvedTracer.startActiveSpan(name, options ?? {}, (span) => {
         try {