@spfn/core 0.2.0-beta.9 → 0.3.0-beta.10

package/dist/event/ws/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/event/ws/handler.ts","../../../src/event/ws/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * WebSocket Handler\n *\n * Attaches a WebSocket server to an existing Node.js http.Server.\n * Handles authentication, event subscription, and client message routing.\n */\n\nimport type { Server } from 'node:http';\nimport type { EventDef } from '../types';\nimport type {\n    WSRouterDef,\n    WSHandlerConfig,\n    WSHandlerAuthConfig,\n    WSMessageHandlers,\n    WSRawConnection,\n} from './types';\nimport type { SSETokenManager } from '../sse/token-manager';\nimport { logger } from '@spfn/core/logger';\n\nconst wsLogger = logger.child('@spfn/core:ws');\n\n/**\n * Decide whether a WebSocket upgrade's Origin is permitted.\n *\n * - no allow-list configured → allowed (check disabled)\n * - no Origin header (native/non-browser client) → allowed\n * - Origin present → must be in the allow-list\n */\nexport function isOriginAllowed(\n    origin: string | undefined,\n    allowList: Set<string> | null,\n): boolean\n{\n    if (!allowList)\n    {\n        return true;\n    }\n\n    if (!origin)\n    {\n        return true;\n    }\n\n    return allowList.has(origin);\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Attach a WebSocket server to a Node.js http.Server\n *\n * @returns cleanup function that closes the WebSocket server\n */\nexport async function attachWSHandler<\n    TEvents extends Record<string, EventDef<any>>,\n    TMessages extends WSMessageHandlers,\n>(\n    server: Server,\n    router: WSRouterDef<TEvents, TMessages>,\n    config: WSHandlerConfig & { path?: string } = {},\n    tokenManager?: SSETokenManager,\n): Promise<() => Promise<void>>\n{\n    const WebSocketServer = await loadWSServer();\n\n    const {\n        pingInterval = 30000,\n        path = '/ws',\n        maxPayload = 1_048_576,\n        maxBufferedBytes = 1_048_576,\n        maxConnections = 10_000,\n        maxConnectionsPerSubject = 0,\n        allowedOrigins,\n        auth: authConfig,\n    } = config;\n\n    const originAllowList = allowedOrigins && allowedOrigins.length > 0\n        ? new Set(allowedOrigins)\n        : null;\n\n    if (authConfig?.enabled && !tokenManager)\n    {\n        throw new Error(\n            'WebSocket auth.enabled=true requires a tokenManager. ' +\n            'Pass tokenManager or use .websockets(router, { auth: { enabled: true } }) via startServer.',\n        );\n    }\n\n    const wss = new WebSocketServer({ server, path, maxPayload });\n\n    // Track live connections for graceful shutdown\n    const clients = new Set<any>();\n    // Live connection count per authenticated subject (for the per-subject cap)\n    const subjectCounts = new Map<string, number>();\n\n    wss.on('connection', (ws: any, req: any) =>\n    {\n        // Origin allow-list (cross-site WebSocket hijacking protection). Browsers\n        // always send Origin on the upgrade; reject one that isn't allowed before\n        // doing any work. A missing Origin (native/non-browser client, which can't\n        // be CSRF'd into using ambient cookies) passes through.\n        if (!isOriginAllowed(req.headers?.origin, originAllowList))\n        {\n            wsLogger.warn('WebSocket rejected: disallowed origin', { origin: req.headers?.origin });\n            ws.close(1008, 'Origin not allowed');\n\n            return;\n        }\n\n        // Global connection cap — reject before doing any work\n        if (clients.size >= maxConnections)\n        {\n            ws.close(1013, 'Server at capacity');\n\n            return;\n        }\n\n        clients.add(ws);\n        ws.on('close', () => clients.delete(ws));\n        handleConnection(ws, req, router, authConfig, tokenManager, {\n            pingInterval,\n            maxBufferedBytes,\n            maxConnectionsPerSubject,\n            subjectCounts,\n        })\n            .catch((err: Error) =>\n            {\n                wsLogger.error('WebSocket connection handler error', err);\n                if (ws.readyState === 1) ws.close(1011, 'Internal server error');\n            });\n    });\n\n    wss.on('error', (err: Error) =>\n    {\n        wsLogger.error('WebSocket server error', err);\n    });\n\n    wsLogger.info(`✓ WebSocket endpoint registered at ${path}`, {\n        events: router.eventNames,\n        auth: !!authConfig?.enabled,\n    });\n\n    return () => new Promise<void>((resolve, reject) =>\n    {\n        // Close all existing connections with 1001 Going Away\n        for (const client of clients)\n        {\n            client.close(1001, 'Server shutting down');\n        }\n        clients.clear();\n\n        wss.close((err?: Error) =>\n        {\n            if (err) reject(err);\n            else resolve();\n        });\n    });\n}\n\n// ============================================================================\n// Connection Handler\n// ============================================================================\n\ninterface ConnectionOptions\n{\n    pingInterval: number;\n    maxBufferedBytes: number;\n    maxConnectionsPerSubject: number;\n    subjectCounts: Map<string, number>;\n}\n\nasync function handleConnection(\n    ws: any,\n    req: any,\n    router: WSRouterDef<any, any>,\n    authConfig: WSHandlerAuthConfig | undefined,\n    tokenManager: SSETokenManager | undefined,\n    opts: ConnectionOptions,\n): Promise<void>\n{\n    const { pingInterval, maxBufferedBytes, maxConnectionsPerSubject, subjectCounts } = opts;\n    // Register close handler before any await — ensures we never miss the event even during auth\n    let pingTimer: ReturnType<typeof setInterval> | undefined;\n    let connectionUnsubscribes: (() => void)[] = [];\n    let subscribedEvents: string[] = [];\n    ws.on('close', () =>\n    {\n        clearInterval(pingTimer);\n        connectionUnsubscribes.forEach(fn => fn());\n        if (subscribedEvents.length > 0)\n            wsLogger.info('WebSocket connection closed', { events: subscribedEvents });\n    });\n\n    const url = parseURL(req);\n    if (!url)\n    {\n        ws.close(1002, 'Invalid request URL');\n\n        return;\n    }\n\n    // ── 1. Authenticate ──\n    const subject = await resolveSubject(url, authConfig?.enabled ? tokenManager : undefined);\n    if (subject === false)\n    {\n        ws.close(4001, 'Missing token');\n\n        return;\n    }\n    if (subject === null)\n    {\n        ws.close(4001, 'Invalid or expired token');\n\n        return;\n    }\n\n    // ── 2. Resolve subscribed events ──\n    const requestedEvents = parseRequestedEvents(url, router.eventNames as string[]);\n    if (requestedEvents.length === 0)\n    {\n        ws.close(4000, 'No valid event names specified');\n\n        return;\n    }\n\n    // ── 3. Authorize ──\n    const allowedEvents = await resolveAllowedEvents(subject, requestedEvents, authConfig);\n    if (allowedEvents === null)\n    {\n        ws.close(4003, 'Not authorized for any requested events');\n\n        return;\n    }\n\n    // ── Per-subject connection cap (authenticated subjects only) ──\n    if (maxConnectionsPerSubject > 0 && typeof subject === 'string')\n    {\n        const current = subjectCounts.get(subject) ?? 0;\n        if (current >= maxConnectionsPerSubject)\n        {\n            ws.close(1013, 'Too many connections for this subject');\n\n            return;\n        }\n\n        subjectCounts.set(subject, current + 1);\n        ws.on('close', () =>\n        {\n            const remaining = (subjectCounts.get(subject) ?? 1) - 1;\n            if (remaining <= 0) subjectCounts.delete(subject);\n            else subjectCounts.set(subject, remaining);\n        });\n    }\n\n    subscribedEvents = allowedEvents;\n    wsLogger.info('WebSocket connection established', {\n        events: allowedEvents,\n        subject: subject ?? undefined,\n    });\n\n    // ── 4. Build connection wrapper ──\n    const connection = createConnection(ws, maxBufferedBytes);\n\n    // ── 5. Subscribe to server-push events ──\n    connectionUnsubscribes = subscribeEvents(ws, router, allowedEvents, subject, authConfig, maxBufferedBytes);\n\n    // If socket closed during auth awaits, clean up and bail\n    if (ws.readyState !== 1)\n    {\n        connectionUnsubscribes.forEach(fn => fn());\n        connectionUnsubscribes = [];\n\n        return;\n    }\n\n    // ── 6. Handle incoming messages ──\n    ws.on('message', (data: Buffer | string) =>\n    {\n        onClientMessage(data, router, connection, subject)\n            .catch((err: Error) => wsLogger.error('Unhandled message error', err));\n    });\n\n    // ── 7. Keep-alive ping with liveness (pong) tracking ──\n    // Without reaping un-ponged sockets, a half-open connection (sleeping device,\n    // NAT drop with no FIN) lingers with its subscriptions, timer, and buffers.\n    if (pingInterval > 0)\n    {\n        ws.isAlive = true;\n        ws.on('pong', () =>\n        {\n            ws.isAlive = true;\n        });\n\n        pingTimer = setInterval(() =>\n        {\n            if (ws.readyState !== 1) return;\n\n            if (ws.isAlive === false)\n            {\n                // No pong since the previous tick — drop the dead/half-open socket\n                ws.terminate();\n\n                return;\n            }\n\n            ws.isAlive = false;\n            ws.ping();\n        }, pingInterval);\n    }\n\n    // ── 9. Send connected ack ──\n    connection.send('__connected', {\n        subscribedEvents: allowedEvents,\n        timestamp: Date.now(),\n    });\n}\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\nfunction parseURL(req: any): URL | null\n{\n    try\n    {\n        return new URL(req.url ?? '/', 'ws://localhost');\n    }\n    catch\n    {\n        return null;\n    }\n}\n\n/**\n * Resolve subject from token\n * - undefined: no auth required\n * - false: token param missing (when required)\n * - null: token invalid/expired\n * - string: authenticated subject\n */\nasync function resolveSubject(\n    url: URL,\n    tokenManager?: SSETokenManager,\n): Promise<string | undefined | false | null>\n{\n    if (!tokenManager)\n    {\n        return undefined;\n    }\n\n    const token = url.searchParams.get('token');\n    if (!token)\n    {\n        return false;\n    }\n\n    return await tokenManager.verify(token);\n}\n\nfunction parseRequestedEvents(url: URL, validEventNames: string[]): string[]\n{\n    const eventsParam = url.searchParams.get('events');\n    if (!eventsParam)\n    {\n        return [];\n    }\n\n    return eventsParam\n        .split(',')\n        .map(e => e.trim())\n        .filter(e => validEventNames.includes(e));\n}\n\nasync function resolveAllowedEvents(\n    subject: string | undefined,\n    requestedEvents: string[],\n    authConfig?: WSHandlerAuthConfig,\n): Promise<string[] | null>\n{\n    if (!subject || !authConfig?.authorize)\n    {\n        return requestedEvents;\n    }\n\n    const allowed = await authConfig.authorize(subject, requestedEvents);\n\n    return allowed.length === 0 ? null : allowed;\n}\n\n/**\n * Send a JSON frame with backpressure protection. If the socket's outbound\n * buffer is already past the cap, the consumer is too slow — close the\n * connection (1013) instead of buffering more and risking OOM. The client\n * reconnects and re-subscribes.\n */\nexport function safeSend(ws: any, frame: unknown, maxBufferedBytes: number): void\n{\n    if (ws.readyState !== 1) return;\n\n    if (ws.bufferedAmount > maxBufferedBytes)\n    {\n        ws.close(1013, 'Send buffer overflow');\n\n        return;\n    }\n\n    try\n    {\n        ws.send(JSON.stringify(frame));\n    }\n    catch\n    {\n        // Socket closed between the readyState check and send — ignore\n    }\n}\n\nfunction createConnection(ws: any, maxBufferedBytes: number): WSRawConnection\n{\n    return {\n        send: (type, payload) => safeSend(ws, { type, data: payload }, maxBufferedBytes),\n        close: (code, reason) => ws.close(code, reason),\n    };\n}\n\nfunction subscribeEvents(\n    ws: any,\n    router: WSRouterDef<any, any>,\n    allowedEvents: string[],\n    subject: string | undefined,\n    authConfig: WSHandlerAuthConfig | undefined,\n    maxBufferedBytes: number,\n): (() => void)[]\n{\n    const unsubscribes: (() => void)[] = [];\n\n    for (const eventName of allowedEvents)\n    {\n        const eventDef = router.events[eventName];\n        if (!eventDef) continue;\n\n        const unsubscribe = eventDef.subscribe((payload: unknown) =>\n        {\n            if (ws.readyState !== 1) return;\n\n            if (subject && authConfig?.filter?.[eventName])\n            {\n                if (!authConfig.filter[eventName](subject, payload)) return;\n            }\n\n            safeSend(ws, { type: eventName, data: payload }, maxBufferedBytes);\n        });\n\n        unsubscribes.push(unsubscribe);\n    }\n\n    return unsubscribes;\n}\n\nasync function onClientMessage(\n    data: Buffer | string,\n    router: WSRouterDef<any, any>,\n    connection: WSRawConnection,\n    subject: string | undefined,\n): Promise<void>\n{\n    let message: { type?: string; data?: unknown };\n\n    try\n    {\n        message = JSON.parse(data.toString());\n    }\n    catch\n    {\n        return;\n    }\n\n    const { type, data: payload } = message;\n    if (!type) return;\n\n    const handler = router.messages[type];\n    if (!handler) return;\n\n    try\n    {\n        await handler({ payload, subject, ws: connection });\n    }\n    catch (err)\n    {\n        wsLogger.error(`WebSocket message handler error: ${type}`, err as Error);\n    }\n}\n\n// ============================================================================\n// Dynamic import for optional 'ws' dependency\n// ============================================================================\n\n/**\n * Resolve the WebSocketServer constructor from the 'ws' module object.\n *\n * ws is a dual package, so the module shape depends on the loader path:\n * - ESM (exports.import → wrapper.mjs): WebSocketServer is a named export;\n *   the default export is the bare WebSocket class with no properties on it.\n * - CJS (require interop): module.exports = WebSocket with\n *   WebSocket.WebSocketServer attached, surfaced under .default.\n * Named exports must win — checking .default first crashes on the ESM path.\n */\nexport function resolveWSServerCtor(mod: any): any\n{\n    return mod.WebSocketServer ?? mod.Server\n        ?? mod.default?.WebSocketServer ?? mod.default?.Server;\n}\n\nasync function loadWSServer(): Promise<any>\n{\n    let mod: any;\n\n    try\n    {\n        mod = await import('ws');\n    }\n    catch\n    {\n        throw new Error(\n            '@spfn/core WebSocket support requires the \"ws\" package.\\n' +\n            'Install it with: pnpm add ws',\n        );\n    }\n\n    const WSS = resolveWSServerCtor(mod);\n\n    if (typeof WSS !== 'function')\n    {\n        throw new Error(\n            'WebSocketServer not found in ws module. ' +\n            'Ensure ws@^8 is installed: pnpm add ws',\n        );\n    }\n\n    return WSS;\n}\n","/**\n * WebSocket Module\n *\n * Type-safe WebSocket server with event-based pub/sub and bidirectional messaging.\n *\n * @example Server setup\n * ```typescript\n * // src/server/ws.ts\n * import { defineWSRouter } from '@spfn/core/event/ws';\n * import { defineEvent } from '@spfn/core/event';\n * import { Type } from '@sinclair/typebox';\n *\n * const userUpdated = defineEvent('user.updated', Type.Object({ userId: Type.String() }));\n * const notification = defineEvent('notification', Type.Object({ message: Type.String() }));\n *\n * export const wsRouter = defineWSRouter({\n *     events: { userUpdated, notification },\n *     messages: {\n *         ping: ({ ws }) => ws.send('pong', {}),\n *     },\n * });\n *\n * export type WSRouter = typeof wsRouter;\n *\n * // server.config.ts\n * defineServerConfig()\n *     .websockets(wsRouter)\n *     .build();\n * ```\n *\n * @example Client usage\n * ```typescript\n * import { createWSClient } from '@spfn/core/event/ws/client';\n * import type { WSRouter } from '@/server/ws';\n *\n * const client = createWSClient<WSRouter>();\n *\n * client.subscribe({\n *     events: ['userUpdated', 'notification'],\n *     handlers: {\n *         userUpdated: ({ userId }) => console.log(userId),\n *         notification: ({ message }) => console.log(message),\n *     },\n * });\n *\n * client.send('ping', {});\n * ```\n */\n\nimport type { EventDef } from '../types';\nimport type { WSRouterDef, WSMessageHandlers } from './types';\n\nexport { attachWSHandler } from './handler';\nexport type {\n    WSRouterDef,\n    WSHandlerConfig,\n    WSAuthConfig,\n    WSHandlerAuthConfig,\n    WSMessageContext,\n    WSMessageHandlerFn,\n    WSMessageHandlers,\n    WSRawConnection,\n    WSClientConfig,\n    WSConnectionState,\n    WSEventHandlers,\n    WSSubscribeOptions,\n    WSUnsubscribe,\n} from './types';\n\n/**\n * Define a WebSocket router\n *\n * Combines server→client event push with client→server message handlers.\n *\n * @example\n * ```typescript\n * export const wsRouter = defineWSRouter({\n *     events: { userUpdated, notification },\n *     messages: {\n *         ping: ({ ws }) => ws.send('pong', {}),\n *         'chat.send': ({ payload, subject }) => handleChat(payload, subject),\n *     },\n * });\n * ```\n */\nexport function defineWSRouter<\n    TEvents extends Record<string, EventDef<any>>,\n    TMessages extends WSMessageHandlers = WSMessageHandlers,\n>(def: {\n    events: TEvents;\n    messages?: TMessages;\n}): WSRouterDef<TEvents, TMessages>\n{\n    return {\n        events: def.events,\n        eventNames: Object.keys(def.events) as (keyof TEvents)[],\n        messages: (def.messages ?? {}) as TMessages,\n        _types: {} as WSRouterDef<TEvents, TMessages>['_types'],\n    };\n}\n"]}

package/dist/job/index.d.ts

@@ -1,5 +1,5 @@
-import { a as JobOptions, C as CompensateHandler, b as JobHandler, c as JobDef, d as JobRouterEntry, J as JobRouter } from '../boss-DI1r4kTS.js';
-export { k as BossConfig, B as BossOptions, I as InferJobInput, f as InferJobOutput, e as JobSendOptions, g as getBoss, i as initBoss, h as isBossRunning, j as shouldClearOnStart, s as stopBoss } from '../boss-DI1r4kTS.js';
+import { J as JobOptions, C as CompensateHandler, a as JobHandler, b as JobDef, c as JobRouter, d as JobRouterEntry, e as JobQueuePolicy } from '../boss-BiDCbbAQ.js';
+export { B as BossConfig, f as BossOptions, I as InferJobInput, g as InferJobOutput, h as JobSendOptions, i as getBoss, j as initBoss, k as isBossRunning, s as shouldClearOnStart, l as stopBoss } from '../boss-BiDCbbAQ.js';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
 import { EventDef, InferEventPayload } from '@spfn/core/event';
@@ -168,11 +168,56 @@ declare function isJobRouter(value: unknown): value is JobRouter<any>;
  * ```
  */
 declare function defineJobRouter<TJobs extends Record<string, JobRouterEntry>>(jobs: TJobs): JobRouter<TJobs>;
+/**
+ * Merge two job routers into a new one
+ *
+ * `defineServerConfig().jobs()` may be called once per domain router, the way
+ * `.routes()` is; each call merges into what is already registered instead of
+ * replacing it. Keys are the router's own namespace, so a key present in both
+ * routers is a mistake the app cannot recover from silently — one of the two
+ * would disappear.
+ *
+ * Neither input is mutated: a fresh router is returned.
+ *
+ * @throws if a top-level key exists in both routers
+ */
+declare function mergeJobRouters(base: JobRouter<any>, extra: JobRouter<any>): JobRouter<any>;
 /**
  * Collect all JobDefs from a JobRouter (including nested)
  */
 declare function collectJobs(router: JobRouter<any>, prefix?: string): JobDef<any>[];
 
+/**
+ * Queue Policy Resolution
+ *
+ * Lives apart from register-jobs.ts and job-builder.ts so both can read the
+ * policy of a job definition without importing each other.
+ */
+
+/**
+ * The part of a job definition that decides its queue policy
+ *
+ * `JobDef` satisfies this; the builder can also pass its own fields before the
+ * definition object exists.
+ */
+interface QueuePolicySource {
+    readonly runOnce?: boolean;
+    readonly options?: JobOptions;
+}
+/**
+ * Resolve the pg-boss queue policy for a job definition
+ *
+ * An explicit `.options({ policy })` always wins. Otherwise a job that asks
+ * for deduplication — `.runOnce()` or an `options.singletonKey` — gets
+ * `exclusive`, the only policy under which a second enqueue is dropped while
+ * the first is still pending or running.
+ *
+ * Everything else stays `standard`: `exclusive` without a `singletonKey`
+ * deduplicates on `COALESCE(singleton_key, '')` and would collapse a plain
+ * queue to a single pending job.
+ */
+declare function resolveQueuePolicy(job: QueuePolicySource): JobQueuePolicy;
+
 /**
  * Job Registration
  *
@@ -215,4 +260,4 @@ declare function collectJobs(router: JobRouter<any>, prefix?: string): JobDef<an
  */
 declare function registerJobs(router: JobRouter<any>): Promise<void>;
 
-export { CompensateHandler, JobDef, JobHandler, JobOptions, JobRouter, JobRouterEntry, collectJobs, defineJobRouter, isJobDef, isJobRouter, job, registerJobs };
+export { CompensateHandler, JobDef, JobHandler, JobOptions, JobQueuePolicy, JobRouter, JobRouterEntry, collectJobs, defineJobRouter, isJobDef, isJobRouter, job, mergeJobRouters, registerJobs, resolveQueuePolicy };

package/dist/job/index.js

@@ -1,60 +1,122 @@
-import PgBoss from 'pg-boss';
 import { logger } from '@spfn/core/logger';
+import PgBoss from 'pg-boss';
+import { env } from '@spfn/core/config';
 
-// src/job/boss.ts
+// src/job/job-builder.ts
 var jobLogger = logger.child("@spfn/core:job");
-var bossInstance = null;
-var bossConfig = null;
+function requiresSSLWithoutVerification(connectionString) {
+  try {
+    const url = new URL(connectionString);
+    const sslmode = url.searchParams.get("sslmode");
+    return sslmode === "require" || sslmode === "prefer";
+  } catch {
+    return false;
+  }
+}
+function stripSslModeFromUrl(connectionString) {
+  const url = new URL(connectionString);
+  url.searchParams.delete("sslmode");
+  return url.toString();
+}
+var BOSS_KEY = Symbol.for("spfn:boss-instance");
+var CONFIG_KEY = Symbol.for("spfn:boss-config");
+var g = globalThis;
+function getBossInstance() {
+  return g[BOSS_KEY] ?? null;
+}
+function setBossInstance(instance) {
+  g[BOSS_KEY] = instance;
+}
+function getBossConfig() {
+  return g[CONFIG_KEY] ?? null;
+}
+function setBossConfig(config) {
+  g[CONFIG_KEY] = config;
+}
 async function initBoss(options) {
-  if (bossInstance) {
+  const existing = getBossInstance();
+  if (existing) {
     jobLogger.warn("pg-boss already initialized, returning existing instance");
-    return bossInstance;
+    return existing;
   }
   jobLogger.info("Initializing pg-boss...");
-  bossConfig = options;
+  setBossConfig(options);
+  const needsSSL = requiresSSLWithoutVerification(options.connectionString);
   const pgBossOptions = {
-    connectionString: options.connectionString,
+    // pg 드라이버가 URL의 sslmode=require를 verify-full로 해석해서
+    // ssl 옵션을 무시하므로, URL에서 sslmode를 빼고 ssl 객체만 전달
+    connectionString: needsSSL ? stripSslModeFromUrl(options.connectionString) : options.connectionString,
     schema: options.schema ?? "spfn_queue",
     maintenanceIntervalSeconds: options.maintenanceIntervalSeconds ?? 120
   };
+  if (needsSSL) {
+    pgBossOptions.ssl = { rejectUnauthorized: false };
+  }
   if (options.monitorIntervalSeconds !== void 0 && options.monitorIntervalSeconds >= 1) {
     pgBossOptions.monitorIntervalSeconds = options.monitorIntervalSeconds;
   }
-  bossInstance = new PgBoss(pgBossOptions);
-  bossInstance.on("error", (error) => {
+  const boss = new PgBoss(pgBossOptions);
+  boss.on("error", (error) => {
     jobLogger.error("pg-boss error:", error);
   });
-  await bossInstance.start();
+  await boss.start();
+  setBossInstance(boss);
   jobLogger.info("pg-boss started successfully");
-  return bossInstance;
+  return boss;
 }
 function getBoss() {
-  return bossInstance;
+  return getBossInstance();
 }
 async function stopBoss() {
-  if (!bossInstance) {
+  const boss = getBossInstance();
+  if (!boss) {
     return;
   }
   jobLogger.info("Stopping pg-boss...");
   try {
-    await bossInstance.stop({ graceful: true, timeout: 3e4 });
+    await boss.stop({ graceful: true, timeout: 3e4 });
     jobLogger.info("pg-boss stopped gracefully");
   } catch (error) {
     jobLogger.error("Error stopping pg-boss:", error);
     throw error;
   } finally {
-    bossInstance = null;
-    bossConfig = null;
+    setBossInstance(null);
+    setBossConfig(null);
   }
 }
 function isBossRunning() {
-  return bossInstance !== null;
+  return getBossInstance() !== null;
 }
 function shouldClearOnStart() {
-  return bossConfig?.clearOnStart ?? false;
+  return getBossConfig()?.clearOnStart ?? false;
+}
+function shouldSweepOrphanSchedules() {
+  return getBossConfig()?.sweepOrphanSchedules ?? false;
+}
+
+// src/job/queue-policy.ts
+function resolveQueuePolicy(job2) {
+  if (job2.options?.policy) {
+    return job2.options.policy;
+  }
+  if (job2.runOnce || job2.options?.singletonKey) {
+    return "exclusive";
+  }
+  return "standard";
 }
 
 // src/job/job-builder.ts
+var jobLogger2 = logger.child("@spfn/core:job");
+var warnedIgnoredSingletonKeys = /* @__PURE__ */ new Set();
+function warnIfSingletonKeyIgnored(name, source) {
+  if (resolveQueuePolicy(source) !== "standard" || warnedIgnoredSingletonKeys.has(name)) {
+    return;
+  }
+  warnedIgnoredSingletonKeys.add(name);
+  jobLogger2.warn(
+    `[Job:${name}] singletonKey ignored: queue policy is "standard"; set .options({ policy: 'exclusive' }) (or another non-standard policy) to deduplicate`
+  );
+}
 function buildPgBossOptions(defaults, sendOptions) {
   const options = {};
   if (sendOptions?.startAfter) {
@@ -215,6 +277,9 @@ var JobBuilder = class _JobBuilder {
         );
       }
       const [input, sendOptions] = inputSchema ? [inputOrOptions, maybeOptions] : [void 0, inputOrOptions];
+      if (sendOptions?.singletonKey) {
+        warnIfSingletonKeyIgnored(name, { runOnce, options });
+      }
       return await boss.send(
         name,
         input ?? {},
@@ -228,6 +293,25 @@ var JobBuilder = class _JobBuilder {
         return await handler();
       }
     };
+    const sendBatch = async (inputsOrOptions, maybeOptions) => {
+      const boss = getBoss();
+      if (!boss) {
+        throw new Error(
+          `[Job:${name}] pg-boss not initialized. Ensure jobs are registered with defineServerConfig().jobs()`
+        );
+      }
+      const [inputs, sendOptions] = inputSchema ? [inputsOrOptions, maybeOptions] : [void 0, inputsOrOptions];
+      if (sendOptions?.singletonKey) {
+        warnIfSingletonKeyIgnored(name, { runOnce, options });
+      }
+      const pgBossOptions = buildPgBossOptions(options, sendOptions);
+      const jobs = (inputs ?? [{}]).map((data) => ({
+        name,
+        ...pgBossOptions,
+        data
+      }));
+      await boss.insert(name, jobs);
+    };
     return {
       name,
       inputSchema,
@@ -240,6 +324,7 @@ var JobBuilder = class _JobBuilder {
       handler,
       compensate,
       send,
+      sendBatch,
       run,
       _input: void 0,
       _output: void 0
@@ -263,19 +348,32 @@ function defineJobRouter(jobs) {
     _jobs: jobs
   };
 }
-function collectJobs(router, prefix = "") {
-  const jobs = [];
+function mergeJobRouters(base, extra) {
+  for (const key of Object.keys(extra.jobs)) {
+    if (key in base.jobs) {
+      throw new Error(
+        `jobs(): key "${key}" is already registered by an earlier .jobs() call; rename it or nest it under a domain router`
+      );
+    }
+  }
+  return defineJobRouter({ ...base.jobs, ...extra.jobs });
+}
+function collectJobEntries(router, prefix = "") {
+  const entries = [];
   for (const [key, value] of Object.entries(router.jobs)) {
-    const name = prefix ? `${prefix}.${key}` : key;
+    const path = prefix ? `${prefix}.${key}` : key;
     if (isJobRouter(value)) {
-      jobs.push(...collectJobs(value, name));
+      entries.push(...collectJobEntries(value, path));
     } else if (isJobDef(value)) {
-      jobs.push(value);
+      entries.push({ key: path, job: value });
     }
   }
-  return jobs;
+  return entries;
 }
-var jobLogger2 = logger.child("@spfn/core:job");
+function collectJobs(router, prefix = "") {
+  return collectJobEntries(router, prefix).map((entry) => entry.job);
+}
+var jobLogger3 = logger.child("@spfn/core:job");
 function getEventQueueName(eventName) {
   return `event:${eventName}`;
 }
@@ -283,6 +381,9 @@ function getDefaultJobOptions(options) {
   return {
     retryLimit: options?.retryLimit ?? 3,
     retryDelay: options?.retryDelay ?? 1e3,
+    // Exponential backoff by default — a failed cohort (e.g. a provider 429)
+    // would otherwise all retry at the same fixed offset (thundering herd).
+    retryBackoff: options?.retryBackoff ?? true,
     expireInSeconds: options?.expireInSeconds ?? 300
   };
 }
@@ -293,11 +394,12 @@ async function registerJobs(router) {
       "pg-boss not initialized. Call initBoss() before registerJobs()"
     );
   }
+  assertUniqueJobNames(router);
   const jobs = collectJobs(router);
   const clearOnStart = shouldClearOnStart();
-  jobLogger2.info(`Registering ${jobs.length} job(s)...`);
+  jobLogger3.info(`Registering ${jobs.length} job(s)...`);
   if (clearOnStart) {
-    jobLogger2.info("Clearing existing jobs before registration...");
+    jobLogger3.info("Clearing existing jobs before registration...");
     for (const job2 of jobs) {
       await boss.deleteAllJobs(job2.name);
       if (job2.subscribedEvent) {
@@ -305,46 +407,134 @@ async function registerJobs(router) {
         await boss.deleteAllJobs(eventQueue);
       }
     }
-    jobLogger2.info("Existing jobs cleared");
+    jobLogger3.info("Existing jobs cleared");
   }
+  await Promise.all(jobs.map((job2) => registerJob(job2)));
   for (const job2 of jobs) {
-    await registerJob(job2);
+    if (job2.cronExpression) {
+      registeredCronNames.add(job2.name);
+    }
+  }
+  if (shouldSweepOrphanSchedules()) {
+    await sweepOrphanSchedules(boss);
+  }
+  jobLogger3.info("All jobs registered successfully");
+}
+function assertUniqueJobNames(router) {
+  const keysByName = /* @__PURE__ */ new Map();
+  for (const { key, job: job2 } of collectJobEntries(router)) {
+    const existingKey = keysByName.get(job2.name);
+    if (existingKey) {
+      throw new Error(
+        `registerJobs(): job name "${job2.name}" is defined twice (keys "${existingKey}" and "${key}"); job names are pg-boss queue names and must be unique`
+      );
+    }
+    keysByName.set(job2.name, key);
+  }
+}
+var registeredCronNames = /* @__PURE__ */ new Set();
+async function sweepOrphanSchedules(boss) {
+  if (registeredCronNames.size === 0) {
+    jobLogger3.debug("No cron jobs declared; skipping orphan schedule sweep");
+    return;
+  }
+  try {
+    const schedules = await boss.getSchedules();
+    const orphans = schedules.filter((schedule) => !registeredCronNames.has(schedule.name));
+    if (orphans.length === 0) {
+      jobLogger3.debug("No orphan schedules found");
+      return;
+    }
+    await Promise.all(orphans.map(async (orphan) => {
+      try {
+        await boss.unschedule(orphan.name, orphan.key);
+        jobLogger3.info(`Removed orphan schedule: ${orphan.name}`);
+      } catch (error) {
+        jobLogger3.error(`Failed to remove orphan schedule: ${orphan.name}`, {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }));
+  } catch (error) {
+    jobLogger3.error("Orphan schedule sweep failed", {
+      error: error instanceof Error ? error.message : String(error)
+    });
   }
-  jobLogger2.info("All jobs registered successfully");
 }
-async function ensureQueue(boss, queueName) {
-  await boss.createQueue(queueName);
+async function ensureQueue(boss, queueName, policy) {
+  await boss.createQueue(queueName, { policy });
+  const existing = await boss.getQueue(queueName);
+  if (!existing || existing.policy === policy) {
+    return;
+  }
+  if (shouldClearOnStart()) {
+    await boss.deleteQueue(queueName);
+    await boss.createQueue(queueName, { policy });
+    jobLogger3.info(`[Queue:${queueName}] policy ${existing.policy} \u2192 ${policy} (recreated: clearOnStart)`);
+    return;
+  }
+  jobLogger3.error(
+    `[Queue:${queueName}] policy mismatch: the queue exists as "${existing.policy}" but its jobs require "${policy}". Delete the queue in a quiet window (getBoss().deleteQueue('${queueName}') drops its job rows) or set clearOnStart in development; until then singletonKey/runOnce on this queue do not deduplicate`
+  );
+}
+function createQueueEnsurer(boss, policy) {
+  const ensured = /* @__PURE__ */ new Set();
+  return async (queueName) => {
+    if (ensured.has(queueName)) {
+      return;
+    }
+    ensured.add(queueName);
+    await ensureQueue(boss, queueName, policy);
+  };
+}
+async function executeJobHandler(job2, pgBossJob) {
+  jobLogger3.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
+  const startTime = Date.now();
+  try {
+    if (job2.inputSchema) {
+      await job2.handler(pgBossJob.data);
+    } else {
+      await job2.handler();
+    }
+    const duration = Date.now() - startTime;
+    jobLogger3.info(`[Job:${job2.name}] Completed in ${duration}ms`, {
+      jobId: pgBossJob.id,
+      duration
+    });
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    jobLogger3.error(`[Job:${job2.name}] Failed after ${duration}ms`, {
+      jobId: pgBossJob.id,
+      duration,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
 }
-async function registerWorker(boss, job2, queueName) {
-  await ensureQueue(boss, queueName);
+async function registerWorker(boss, job2, queueName, ensureQueueOnce) {
+  await ensureQueueOnce(queueName);
+  const batchSize = job2.options?.batchSize ?? 1;
+  const pollingIntervalSeconds = job2.options?.pollingIntervalSeconds ?? env.JOB_POLLING_INTERVAL_SECONDS;
   await boss.work(
     queueName,
-    { batchSize: 1 },
-    async (jobs) => {
-      for (const pgBossJob of jobs) {
-        jobLogger2.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
-        const startTime = Date.now();
-        try {
-          if (job2.inputSchema) {
-            await job2.handler(pgBossJob.data);
-          } else {
-            await job2.handler();
-          }
-          const duration = Date.now() - startTime;
-          jobLogger2.info(`[Job:${job2.name}] Completed in ${duration}ms`, {
-            jobId: pgBossJob.id,
-            duration
-          });
-        } catch (error) {
-          const duration = Date.now() - startTime;
-          jobLogger2.error(`[Job:${job2.name}] Failed after ${duration}ms`, {
-            jobId: pgBossJob.id,
-            duration,
-            error: error instanceof Error ? error.message : String(error)
-          });
-          throw error;
+    { batchSize, pollingIntervalSeconds },
+    async (pgBossJobs) => {
+      if (batchSize <= 1) {
+        await executeJobHandler(job2, pgBossJobs[0]);
+        return;
+      }
+      const results = await Promise.allSettled(
+        pgBossJobs.map((pgBossJob) => executeJobHandler(job2, pgBossJob))
+      );
+      const failedIds = [];
+      for (let i = 0; i < results.length; i++) {
+        if (results[i].status === "rejected") {
+          failedIds.push(pgBossJobs[i].id);
         }
       }
+      if (failedIds.length > 0) {
+        await boss.fail(queueName, failedIds);
+      }
     }
   );
 }
@@ -356,28 +546,28 @@ function connectEventToQueue(boss, job2, queueName) {
   eventDef._registerJobQueue(queueName, async (queue, payload) => {
     await boss.send(queue, payload, getDefaultJobOptions(job2.options));
   });
-  jobLogger2.debug(`[Job:${job2.name}] Connected to event: ${job2.subscribedEvent}`);
+  jobLogger3.debug(`[Job:${job2.name}] Connected to event: ${job2.subscribedEvent}`);
 }
-async function registerCronSchedule(boss, job2) {
+async function registerCronSchedule(boss, job2, ensureQueueOnce) {
   if (!job2.cronExpression) {
     return;
   }
-  jobLogger2.debug(`[Job:${job2.name}] Scheduling cron: ${job2.cronExpression}`);
-  await ensureQueue(boss, job2.name);
+  jobLogger3.debug(`[Job:${job2.name}] Scheduling cron: ${job2.cronExpression}`);
+  await ensureQueueOnce(job2.name);
   await boss.schedule(
     job2.name,
     job2.cronExpression,
     {},
     getDefaultJobOptions(job2.options)
   );
-  jobLogger2.info(`[Job:${job2.name}] Cron scheduled: ${job2.cronExpression}`);
+  jobLogger3.info(`[Job:${job2.name}] Cron scheduled: ${job2.cronExpression}`);
 }
-async function queueRunOnceJob(boss, job2) {
+async function queueRunOnceJob(boss, job2, ensureQueueOnce) {
   if (!job2.runOnce) {
     return;
   }
-  jobLogger2.debug(`[Job:${job2.name}] Queuing runOnce job`);
-  await ensureQueue(boss, job2.name);
+  jobLogger3.debug(`[Job:${job2.name}] Queuing runOnce job`);
+  await ensureQueueOnce(job2.name);
   await boss.send(
     job2.name,
     {},
@@ -386,7 +576,7 @@ async function queueRunOnceJob(boss, job2) {
       singletonKey: `runOnce:${job2.name}`
     }
   );
-  jobLogger2.info(`[Job:${job2.name}] runOnce job queued`);
+  jobLogger3.info(`[Job:${job2.name}] runOnce job queued`);
 }
 async function registerJob(job2) {
   const boss = getBoss();
@@ -394,17 +584,18 @@ async function registerJob(job2) {
     throw new Error("pg-boss not initialized");
   }
   const queueName = job2.subscribedEvent ? getEventQueueName(job2.subscribedEvent) : job2.name;
-  jobLogger2.debug(`Registering job: ${job2.name}`, {
+  jobLogger3.debug(`Registering job: ${job2.name}`, {
     queueName,
     subscribedEvent: job2.subscribedEvent
   });
-  await registerWorker(boss, job2, queueName);
+  const ensureQueueOnce = createQueueEnsurer(boss, resolveQueuePolicy(job2));
+  await registerWorker(boss, job2, queueName, ensureQueueOnce);
   connectEventToQueue(boss, job2, queueName);
-  await registerCronSchedule(boss, job2);
-  await queueRunOnceJob(boss, job2);
-  jobLogger2.debug(`Job registered: ${job2.name}`);
+  await registerCronSchedule(boss, job2, ensureQueueOnce);
+  await queueRunOnceJob(boss, job2, ensureQueueOnce);
+  jobLogger3.debug(`Job registered: ${job2.name}`);
 }
 
-export { collectJobs, defineJobRouter, getBoss, initBoss, isBossRunning, isJobDef, isJobRouter, job, registerJobs, shouldClearOnStart, stopBoss };
+export { collectJobs, defineJobRouter, getBoss, initBoss, isBossRunning, isJobDef, isJobRouter, job, mergeJobRouters, registerJobs, resolveQueuePolicy, shouldClearOnStart, stopBoss };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map