@vobase/core 0.10.0 → 0.11.0

package/src/infra/index.ts

@@ -0,0 +1,35 @@
+export {
+  conflict,
+  dbBusy,
+  ERROR_CODES,
+  type ErrorCode,
+  errorHandler,
+  forbidden,
+  notFound,
+  unauthorized,
+  VobaseError,
+  validation,
+} from './errors';
+export { logger } from './logger';
+export {
+  createScheduler,
+  configureQueueDataPath,
+  DEFAULT_QUEUE_DB_PATH,
+  DEFAULT_QUEUE_NAME,
+  type JobOptions,
+  type Scheduler,
+  type SchedulerOptions,
+} from './queue';
+export type { JobDefinition, JobHandler, WorkerOptions } from './job';
+export { createWorker, defineJob, jobRegistry } from './job';
+export { CircuitBreaker, type CircuitBreakerOptions } from './circuit-breaker';
+export {
+  createHttpClient,
+  type HttpClient,
+  type HttpClientOptions,
+  type HttpResponse,
+  type RequestOptions,
+} from './http-client';
+export { createThrowProxy } from './throw-proxy';
+export { type WebhookConfig, verifyHmacSignature, createWebhookRoutes, webhookDedup } from './webhooks';
+export { webhookDedup as webhookDedupSchema } from './webhooks-schema';

package/src/infra/job.test.ts

@@ -0,0 +1,85 @@
+import { rmSync } from 'node:fs';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'bun:test';
+import { shutdownManager } from 'bunqueue/client';
+
+import { createWorker, defineJob, jobRegistry } from './job';
+import { createScheduler } from './queue';
+
+const TEST_DB_PATH = `/tmp/vobase-bunqueue-${process.pid}.db`;
+const globalScope = globalThis as typeof globalThis & {
+  __vobaseBunqueueTestRefs__?: number;
+};
+
+function makeQueueName(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+beforeAll(() => {
+  globalScope.__vobaseBunqueueTestRefs__ =
+    (globalScope.__vobaseBunqueueTestRefs__ ?? 0) + 1;
+});
+
+afterAll(() => {
+  const refs = (globalScope.__vobaseBunqueueTestRefs__ ?? 1) - 1;
+  globalScope.__vobaseBunqueueTestRefs__ = refs;
+
+  if (refs === 0) {
+    shutdownManager();
+    rmSync(TEST_DB_PATH, { force: true });
+    rmSync(`${TEST_DB_PATH}-shm`, { force: true });
+    rmSync(`${TEST_DB_PATH}-wal`, { force: true });
+  }
+});
+
+afterEach(() => {
+  jobRegistry.clear();
+});
+
+describe('defineJob()', () => {
+  it('registers a job definition in the module registry', async () => {
+    const handler = async (): Promise<void> => {
+      await Bun.sleep(0);
+    };
+
+    const definition = defineJob('report.generate', handler);
+
+    expect(definition.name).toBe('report.generate');
+    expect(definition.handler).toBe(handler);
+    expect(jobRegistry.get('report.generate')).toBe(handler);
+  });
+});
+
+describe('createWorker()', () => {
+  it('processes an enqueued job end-to-end', async () => {
+    const queueName = makeQueueName('worker-roundtrip');
+    const scheduler = await createScheduler({ dbPath: TEST_DB_PATH, queueName });
+
+    let processedData: unknown;
+    let resolveProcessed!: () => void;
+    const processed = new Promise<void>((resolve) => {
+      resolveProcessed = resolve;
+    });
+
+    const job = defineJob('invoice.sync', async (data) => {
+      processedData = data;
+      resolveProcessed();
+    });
+
+    const worker = await createWorker([job], { dbPath: TEST_DB_PATH, queueName });
+
+    try {
+      await scheduler.add('invoice.sync', { id: 'inv_1' });
+
+      await Promise.race([
+        processed,
+        Bun.sleep(1_500).then(() => {
+          throw new Error('Timed out waiting for invoice.sync to be processed');
+        }),
+      ]);
+
+      expect(processedData).toEqual({ id: 'inv_1' });
+    } finally {
+      await worker.close();
+    }
+  });
+});

package/src/infra/job.ts

@@ -0,0 +1,94 @@
+import type {
+  WorkerOptions as BunqueueWorkerOptions,
+  Job,
+  Worker,
+} from 'bunqueue/client';
+
+import { validation } from './errors';
+import {
+  configureQueueDataPath,
+  DEFAULT_QUEUE_DB_PATH,
+  DEFAULT_QUEUE_NAME,
+  type SchedulerOptions,
+} from './queue';
+
+export type JobHandler = (data: unknown) => Promise<void>;
+
+export interface JobDefinition {
+  name: string;
+  handler: JobHandler;
+}
+
+export interface WorkerOptions
+  extends Pick<SchedulerOptions, 'dbPath' | 'queueName'> {
+  concurrency?: number;
+}
+
+export const jobRegistry = new Map<string, JobHandler>();
+
+function assertJobName(name: string): void {
+  if (!name.trim()) {
+    throw validation({ name }, 'Job name must be a non-empty string');
+  }
+}
+
+function assertConcurrency(concurrency: number): void {
+  if (!Number.isInteger(concurrency) || concurrency < 1) {
+    throw validation(
+      { concurrency },
+      'Worker concurrency must be a positive integer',
+    );
+  }
+}
+
+function registerJob(definition: JobDefinition): void {
+  assertJobName(definition.name);
+  jobRegistry.set(definition.name, definition.handler);
+}
+
+async function processJob(job: Job<unknown>): Promise<void> {
+  const handler = jobRegistry.get(job.name);
+  if (!handler) {
+    throw validation(
+      { jobName: job.name },
+      `No registered handler for job "${job.name}"`,
+    );
+  }
+
+  await handler(job.data);
+}
+
+export function defineJob(name: string, handler: JobHandler): JobDefinition {
+  assertJobName(name);
+
+  const definition = { name, handler };
+  registerJob(definition);
+  return definition;
+}
+
+export async function createWorker(
+  jobs: JobDefinition[],
+  options?: WorkerOptions,
+): Promise<Worker> {
+  const { Worker } = await import('bunqueue/client');
+
+  for (const job of jobs) {
+    registerJob(job);
+  }
+
+  const concurrency = options?.concurrency ?? 5;
+  assertConcurrency(concurrency);
+
+  await configureQueueDataPath(options?.dbPath ?? DEFAULT_QUEUE_DB_PATH);
+
+  const workerOptions: BunqueueWorkerOptions = {
+    embedded: true,
+    concurrency,
+  };
+
+  return new Worker(
+    options?.queueName ?? DEFAULT_QUEUE_NAME,
+    processJob,
+    workerOptions,
+  );
+}

package/src/infra/logger.test.ts

@@ -0,0 +1,65 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+
+import { logger } from './logger';
+
+describe('logger', () => {
+  let logs: string[] = [];
+  const originalLog = console.log;
+
+  beforeEach(() => {
+    logs = [];
+    console.log = (msg: string) => logs.push(msg);
+  });
+
+  afterEach(() => {
+    console.log = originalLog;
+  });
+
+  it('should log info messages', () => {
+    logger.info('test message', { foo: 'bar' });
+    expect(logs.length).toBe(1);
+    const parsed = JSON.parse(logs[0]);
+    expect(parsed.level).toBe('info');
+    expect(parsed.msg).toBe('test message');
+    expect(parsed.data).toEqual({ foo: 'bar' });
+    expect(typeof parsed.ts).toBe('number');
+  });
+
+  it('should log warn messages', () => {
+    logger.warn('warning');
+    const parsed = JSON.parse(logs[0]);
+    expect(parsed.level).toBe('warn');
+    expect(parsed.msg).toBe('warning');
+  });
+
+  it('should log error messages', () => {
+    logger.error('error occurred', { code: 500 });
+    const parsed = JSON.parse(logs[0]);
+    expect(parsed.level).toBe('error');
+    expect(parsed.msg).toBe('error occurred');
+    expect(parsed.data).toEqual({ code: 500 });
+  });
+
+  it('should log debug messages when DEBUG env is set', () => {
+    const oldDebug = Bun.env.DEBUG;
+    Bun.env.DEBUG = 'true';
+    logger.debug('debug info');
+    Bun.env.DEBUG = oldDebug;
+    expect(logs.length).toBe(1);
+    const parsed = JSON.parse(logs[0]);
+    expect(parsed.level).toBe('debug');
+  });
+
+  it('should include timestamp as number', () => {
+    logger.info('test');
+    const parsed = JSON.parse(logs[0]);
+    expect(typeof parsed.ts).toBe('number');
+    expect(parsed.ts).toBeGreaterThan(0);
+  });
+
+  it('should have data field in output', () => {
+    logger.info('message with data', { key: 'value' });
+    const parsed = JSON.parse(logs[0]);
+    expect(parsed.data).toEqual({ key: 'value' });
+  });
+});

package/src/infra/logger.ts

@@ -0,0 +1,18 @@
+type LogLevel = 'info' | 'warn' | 'error' | 'debug';
+
+function log(level: LogLevel, msg: string, data?: unknown): void {
+  if (
+    level === 'debug' &&
+    !Bun.env.DEBUG &&
+    process.env.NODE_ENV === 'production'
+  )
+    return;
+  console.log(JSON.stringify({ level, msg, data, ts: Date.now() }));
+}
+
+export const logger = {
+  info: (msg: string, data?: unknown) => log('info', msg, data),
+  warn: (msg: string, data?: unknown) => log('warn', msg, data),
+  error: (msg: string, data?: unknown) => log('error', msg, data),
+  debug: (msg: string, data?: unknown) => log('debug', msg, data),
+};

package/src/infra/queue.test.ts

@@ -0,0 +1,46 @@
+import { rmSync } from 'node:fs';
+import { afterAll, beforeAll, describe, expect, it } from 'bun:test';
+import { Queue, shutdownManager } from 'bunqueue/client';
+
+import { createScheduler } from './queue';
+
+const TEST_DB_PATH = `/tmp/vobase-bunqueue-${process.pid}.db`;
+const globalScope = globalThis as typeof globalThis & {
+  __vobaseBunqueueTestRefs__?: number;
+};
+
+function makeQueueName(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+beforeAll(() => {
+  globalScope.__vobaseBunqueueTestRefs__ =
+    (globalScope.__vobaseBunqueueTestRefs__ ?? 0) + 1;
+});
+
+afterAll(() => {
+  const refs = (globalScope.__vobaseBunqueueTestRefs__ ?? 1) - 1;
+  globalScope.__vobaseBunqueueTestRefs__ = refs;
+
+  if (refs === 0) {
+    shutdownManager();
+    rmSync(TEST_DB_PATH, { force: true });
+    rmSync(`${TEST_DB_PATH}-shm`, { force: true });
+    rmSync(`${TEST_DB_PATH}-wal`, { force: true });
+  }
+});
+
+describe('createScheduler()', () => {
+  it('enqueues a job via scheduler.add()', async () => {
+    const queueName = makeQueueName('scheduler-add');
+    const scheduler = await createScheduler({ dbPath: TEST_DB_PATH, queueName });
+
+    await scheduler.add('email.send', { to: 'user@example.com' });
+
+    const queue = new Queue(queueName, { embedded: true });
+    const waitingCount = await queue.getWaitingCount();
+    queue.close();
+
+    expect(waitingCount).toBe(1);
+  });
+});

package/src/infra/queue.ts

@@ -0,0 +1,147 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { JobOptions as BunqueueJobOptions } from 'bunqueue/client';
+
+import { validation } from './errors';
+
+export const DEFAULT_QUEUE_DB_PATH = '/data/bunqueue.db';
+export const DEFAULT_QUEUE_NAME = 'vobase-jobs';
+
+export interface JobOptions {
+  delay?: number | string;
+  priority?: number;
+  retry?: number;
+  retries?: number;
+}
+
+export interface SchedulerOptions {
+  dbPath?: string;
+  queueName?: string;
+}
+
+export interface Scheduler {
+  add(jobName: string, data: unknown, options?: JobOptions): Promise<void>;
+}
+
+const DELAY_MULTIPLIER: Record<string, number> = {
+  ms: 1,
+  s: 1000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+function parseDelay(delay?: number | string): number | undefined {
+  if (delay === undefined) {
+    return undefined;
+  }
+
+  if (typeof delay === 'number') {
+    if (!Number.isFinite(delay) || delay < 0) {
+      throw validation({ delay }, 'Job delay must be a non-negative number');
+    }
+    return Math.floor(delay);
+  }
+
+  const value = delay.trim().toLowerCase();
+  if (!value) {
+    throw validation({ delay }, 'Job delay string cannot be empty');
+  }
+
+  if (/^\d+$/.test(value)) {
+    return Number.parseInt(value, 10);
+  }
+
+  const match = value.match(/^(\d+)(ms|s|m|h|d)$/);
+  if (!match) {
+    throw validation(
+      { delay },
+      'Invalid delay format. Use milliseconds or duration suffixes: ms, s, m, h, d',
+    );
+  }
+
+  const amount = Number.parseInt(match[1], 10);
+  const multiplier = DELAY_MULTIPLIER[match[2]];
+  return amount * multiplier;
+}
+
+function parseAttempts(options?: JobOptions): number | undefined {
+  const retryCount = options?.retries ?? options?.retry;
+  if (retryCount === undefined) {
+    return undefined;
+  }
+
+  if (!Number.isInteger(retryCount) || retryCount < 0) {
+    throw validation(
+      { retryCount },
+      'Retry count must be a non-negative integer',
+    );
+  }
+
+  return retryCount + 1;
+}
+
+function toBunqueueJobOptions(
+  options?: JobOptions,
+): BunqueueJobOptions | undefined {
+  if (!options) {
+    return undefined;
+  }
+
+  if (options.priority !== undefined) {
+    if (!Number.isInteger(options.priority) || options.priority < 0) {
+      throw validation(
+        { priority: options.priority },
+        'Job priority must be a non-negative integer',
+      );
+    }
+  }
+
+  const delay = parseDelay(options.delay);
+  const attempts = parseAttempts(options);
+
+  return {
+    delay,
+    priority: options.priority,
+    attempts,
+  };
+}
+
+export async function configureQueueDataPath(dbPath: string): Promise<string> {
+  if (!dbPath.trim()) {
+    throw validation({ dbPath }, 'Queue dbPath must be a non-empty string');
+  }
+
+  const existingDataPath = Bun.env.DATA_PATH;
+  if (existingDataPath && existingDataPath !== dbPath) {
+    const { shutdownManager } = await import('bunqueue/client');
+    shutdownManager();
+  }
+
+  mkdirSync(dirname(dbPath), { recursive: true });
+  Bun.env.DATA_PATH = dbPath;
+  return dbPath;
+}
+
+export async function createScheduler(options?: SchedulerOptions): Promise<Scheduler> {
+  const { Queue } = await import('bunqueue/client');
+
+  await configureQueueDataPath(options?.dbPath ?? DEFAULT_QUEUE_DB_PATH);
+  const queue = new Queue(options?.queueName ?? DEFAULT_QUEUE_NAME, {
+    embedded: true,
+  });
+
+  return {
+    async add(
+      jobName: string,
+      data: unknown,
+      options?: JobOptions,
+    ): Promise<void> {
+      if (!jobName.trim()) {
+        throw validation({ jobName }, 'Job name must be a non-empty string');
+      }
+
+      await queue.add(jobName, data, toBunqueueJobOptions(options));
+    },
+  };
+}

package/src/infra/throw-proxy.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test';
+import { createThrowProxy } from './throw-proxy';
+
+interface FakeService {
+  doSomething(): void;
+  value: string;
+}
+
+describe('createThrowProxy', () => {
+  test('throws on property access with service name in message', () => {
+    const proxy = createThrowProxy<FakeService>('storage');
+    expect(() => proxy.value).toThrow('storage is not configured');
+  });
+
+  test('throws on method call with service name in message', () => {
+    const proxy = createThrowProxy<FakeService>('notify');
+    expect(() => proxy.doSomething()).toThrow('notify is not configured');
+  });
+
+  test('error message includes configuration hint', () => {
+    const proxy = createThrowProxy<FakeService>('storage');
+    expect(() => proxy.value).toThrow('Add storage configuration');
+  });
+
+  test('does not throw for Symbol.toPrimitive', () => {
+    const proxy = createThrowProxy<FakeService>('storage');
+    expect((proxy as unknown as Record<symbol, unknown>)[Symbol.toPrimitive]).toBeUndefined();
+  });
+
+  test('does not throw for Symbol.toStringTag', () => {
+    const proxy = createThrowProxy<FakeService>('storage');
+    expect((proxy as unknown as Record<symbol, unknown>)[Symbol.toStringTag]).toBeUndefined();
+  });
+});

package/src/infra/throw-proxy.ts

@@ -0,0 +1,17 @@
+/**
+ * Creates a proxy that throws a descriptive error when any property is accessed.
+ * Used for optional services (storage, notify) that are typed as non-optional
+ * in VobaseCtx but may not be configured.
+ */
+export function createThrowProxy<T>(serviceName: string): T {
+  return new Proxy(Object.create(null), {
+    get(_target, prop) {
+      if (prop === Symbol.toPrimitive || prop === Symbol.toStringTag || prop === 'inspect') {
+        return undefined;
+      }
+      throw new Error(
+        `${serviceName} is not configured. Add ${serviceName.toLowerCase()} configuration to your createApp() config to use ctx.${serviceName.toLowerCase()}.`,
+      );
+    },
+  }) as T;
+}

package/src/infra/webhooks-schema.ts

@@ -0,0 +1,17 @@
+import { integer, primaryKey, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+/**
+ * Webhook deduplication table. Tracks processed webhook IDs
+ * to prevent duplicate processing.
+ */
+export const webhookDedup = sqliteTable(
+  '_webhook_dedup',
+  {
+    id: text('id').notNull(),
+    source: text('source').notNull(),
+    receivedAt: integer('received_at', { mode: 'timestamp_ms' })
+      .notNull()
+      .$defaultFn(() => new Date()),
+  },
+  (table) => [primaryKey({ columns: [table.id, table.source] })],
+);