@spfn/core 0.2.0-beta.52 → 0.2.0-beta.54

package/dist/{boss-Cxqc-Oiw.d.ts → boss-CEik0yq-.d.ts}

@@ -47,6 +47,13 @@ interface JobOptions {
      * @default 1
      */
     batchSize?: number;
+    /**
+     * How often this worker polls the DB for new jobs, in seconds. Lower =
+     * faster pickup but more idle SELECT load; higher = less DB chatter but
+     * slower pickup. Overrides the JOB_POLLING_INTERVAL_SECONDS default.
+     * @default 2 (pg-boss default) or JOB_POLLING_INTERVAL_SECONDS
+     */
+    pollingIntervalSeconds?: number;
 }
 /**
  * Send options for individual job dispatch

package/dist/cache/index.js

@@ -1,12 +1,19 @@
 import { logger } from '@spfn/core/logger';
+import { env } from '@spfn/core/config';
 
 // src/cache/cache-factory.ts
+function resilienceOptions() {
+  return {
+    maxRetriesPerRequest: env.CACHE_MAX_RETRIES_PER_REQUEST,
+    enableOfflineQueue: env.CACHE_ENABLE_OFFLINE_QUEUE
+  };
+}
 var cacheLogger = logger.child("@spfn/core:cache");
 function hasCacheConfig() {
   return !!(process.env.CACHE_URL || process.env.CACHE_WRITE_URL || process.env.CACHE_READ_URL || process.env.CACHE_SENTINEL_HOSTS || process.env.CACHE_CLUSTER_NODES);
 }
 function createClient(RedisClient, url) {
-  const options = {};
+  const options = { ...resilienceOptions() };
   if (url.startsWith("rediss://")) {
     options.tls = {
       rejectUnauthorized: process.env.CACHE_TLS_REJECT_UNAUTHORIZED !== "false"
@@ -46,6 +53,7 @@ async function createCacheFromEnv() {
         return { host: hostname, port: Number(port) || 26379 };
       });
       const options = {
+        ...resilienceOptions(),
         sentinels,
         name: masterName,
         password
@@ -61,6 +69,7 @@ async function createCacheFromEnv() {
       });
       const clusterOptions = {
         redisOptions: {
+          ...resilienceOptions(),
           password
         }
       };

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/cache/cache-factory.ts","../../src/cache/cache-manager.ts"],"names":["cacheLogger","logger"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Cache factory with automatic environment variable detection\n */\n\nimport type { Redis, Cluster, RedisOptions, ClusterOptions } from 'ioredis';\nimport { logger } from '@spfn/core/logger';\n\nconst cacheLogger = logger.child('@spfn/core:cache');\n\nexport interface CacheClients {\n    /** Primary cache for writes (or both read/write if no replica) */\n    write?: Redis | Cluster;\n    /** Replica cache for reads (optional, falls back to write) */\n    read?: Redis | Cluster;\n}\n\n/**\n * Check if any cache configuration exists in environment\n */\nfunction hasCacheConfig(): boolean\n{\n    return !!(\n        process.env.CACHE_URL ||\n        process.env.CACHE_WRITE_URL ||\n        process.env.CACHE_READ_URL ||\n        process.env.CACHE_SENTINEL_HOSTS ||\n        process.env.CACHE_CLUSTER_NODES\n    );\n}\n\n/**\n * Create cache client with TLS support\n */\nfunction createClient(\n    RedisClient: new (url: string, options?: RedisOptions) => Redis,\n    url: string,\n): Redis\n{\n    const options: RedisOptions = {};\n\n    // TLS support for secure connections\n    if (url.startsWith('rediss://'))\n    {\n        options.tls = {\n            rejectUnauthorized: process.env.CACHE_TLS_REJECT_UNAUTHORIZED !== 'false',\n        };\n    }\n\n    return new RedisClient(url, options);\n}\n\n/**\n * Create cache client(s) from environment variables\n *\n * Supported patterns (priority order):\n * 1. Single instance: CACHE_URL\n * 2. Master-Replica: CACHE_WRITE_URL + CACHE_READ_URL\n * 3. Sentinel: CACHE_SENTINEL_HOSTS + CACHE_MASTER_NAME\n * 4. Cluster: CACHE_CLUSTER_NODES\n *\n * @returns Cache client(s) or undefined if no configuration found\n *\n * @example\n * ```bash\n * # Single (most common)\n * CACHE_URL=redis://localhost:6379\n * CACHE_URL=rediss://secure.cache.com:6380  # TLS\n *\n * # Master-Replica\n * CACHE_WRITE_URL=redis://master:6379\n * CACHE_READ_URL=redis://replica:6379\n *\n * # Sentinel\n * CACHE_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379\n * CACHE_MASTER_NAME=mymaster\n * CACHE_PASSWORD=secret\n *\n * # Cluster\n * CACHE_CLUSTER_NODES=node1:6379,node2:6379,node3:6379\n * CACHE_PASSWORD=secret\n * ```\n */\nexport async function createCacheFromEnv(): Promise<CacheClients>\n{\n    // Quick exit if no cache config\n    if (!hasCacheConfig())\n    {\n        cacheLogger.info('No cache configuration found - running without cache');\n\n        return { write: undefined, read: undefined };\n    }\n\n    try\n    {\n        // Dynamic import to avoid bundling if not used\n        const ioredis = await import('ioredis');\n        const RedisClient = ioredis.default;\n\n        // Get environment variables\n        const singleUrl = process.env.CACHE_URL;\n        const writeUrl = process.env.CACHE_WRITE_URL;\n        const readUrl = process.env.CACHE_READ_URL;\n        const clusterNodes = process.env.CACHE_CLUSTER_NODES;\n        const sentinelHosts = process.env.CACHE_SENTINEL_HOSTS;\n        const masterName = process.env.CACHE_MASTER_NAME;\n        const password = process.env.CACHE_PASSWORD;\n\n        // 1. Single instance (most common - highest priority)\n        if (singleUrl && !writeUrl && !readUrl && !clusterNodes)\n        {\n            const client = createClient(RedisClient, singleUrl);\n            cacheLogger.debug('Created single cache instance', { url: singleUrl.replace(/:[^:@]+@/, ':***@') });\n\n            return { write: client, read: client };\n        }\n\n        // 2. Master-Replica pattern (both URLs required)\n        if (writeUrl && readUrl)\n        {\n            const write = createClient(RedisClient, writeUrl);\n            const read = createClient(RedisClient, readUrl);\n            cacheLogger.debug('Created master-replica cache instances');\n\n            return { write, read };\n        }\n\n        // 3. Sentinel pattern\n        if (sentinelHosts && masterName)\n        {\n            const sentinels = sentinelHosts.split(',').map((host) =>\n            {\n                const [hostname, port] = host.trim().split(':');\n\n                return { host: hostname, port: Number(port) || 26379 };\n            });\n\n            const options: RedisOptions = {\n                sentinels,\n                name: masterName,\n                password,\n            };\n\n            const client = new RedisClient(options);\n            cacheLogger.debug('Created sentinel cache instance', { masterName, sentinels: sentinels.length });\n\n            return { write: client, read: client };\n        }\n\n        // 4. Cluster pattern\n        if (clusterNodes)\n        {\n            const nodes = clusterNodes.split(',').map((node) =>\n            {\n                const [host, port] = node.trim().split(':');\n\n                return { host, port: Number(port) || 6379 };\n            });\n\n            const clusterOptions: ClusterOptions = {\n                redisOptions: {\n                    password,\n                },\n            };\n\n            const cluster = new RedisClient.Cluster(nodes, clusterOptions);\n            cacheLogger.debug('Created cluster cache instance', { nodes: nodes.length });\n\n            return { write: cluster, read: cluster };\n        }\n\n        // 5. Fallback: Single URL with other configs present\n        if (singleUrl)\n        {\n            const client = createClient(RedisClient, singleUrl);\n            cacheLogger.debug('Created cache instance (fallback)', { url: singleUrl.replace(/:[^:@]+@/, ':***@') });\n\n            return { write: client, read: client };\n        }\n\n        // No valid configuration\n        cacheLogger.info('No valid cache configuration found - running without cache');\n\n        return { write: undefined, read: undefined };\n    }\n    catch (error)\n    {\n        if (error instanceof Error)\n        {\n            // Check if it's a missing dependency error\n            if (error.message.includes('Cannot find module'))\n            {\n                cacheLogger.warn(\n                    'Cache client library not installed',\n                    error,\n                    {\n                        suggestion: 'Install ioredis to enable cache: pnpm install ioredis',\n                        mode: 'disabled',\n                    },\n                );\n            }\n            else\n            {\n                cacheLogger.warn(\n                    'Failed to create cache client',\n                    error,\n                    { mode: 'disabled' },\n                );\n            }\n        }\n        else\n        {\n            cacheLogger.warn(\n                'Failed to create cache client',\n                { error: String(error), mode: 'disabled' },\n            );\n        }\n\n        return { write: undefined, read: undefined };\n    }\n}\n\n/**\n * Create single cache client (backward compatibility)\n * Only returns write instance\n */\nexport async function createSingleCacheFromEnv(): Promise<Redis | Cluster | undefined>\n{\n    const { write } = await createCacheFromEnv();\n\n    return write;\n}\n","/**\n * Global cache instance manager\n * Provides singleton access to cache (Valkey/Redis) across all modules\n * Supports Master-Replica pattern with separate read/write instances\n *\n * When cache is unavailable, falls back to disabled mode gracefully\n */\n\nimport type { Redis, Cluster } from 'ioredis';\n\nimport { createCacheFromEnv } from './cache-factory';\nimport { logger } from '@spfn/core/logger';\n\nconst cacheLogger = logger.child('@spfn/core:cache');\n\n// ── globalThis singleton ──────────────────────────────────────────\n// CJS/ESM dual-package hazard: 모듈이 두 번 로드되어도\n// Symbol.for() + globalThis로 동일 상태를 공유한다.\ninterface CacheState\n{\n    write: Redis | Cluster | undefined;\n    read: Redis | Cluster | undefined;\n    disabled: boolean;\n}\n\nconst CACHE_KEY = Symbol.for('@spfn/core:cache');\n\nconst state: CacheState = ((globalThis as any)[CACHE_KEY] ??= {\n    write: undefined,\n    read: undefined,\n    disabled: false,\n});\n\n/**\n * Get global cache write instance\n *\n * @returns Cache write instance or undefined if disabled/not initialized\n *\n * @example\n * ```typescript\n * import { getCache } from '@spfn/core/cache';\n *\n * const cache = getCache();\n * if (cache) {\n *   await cache.set('key', 'value');\n * } else {\n *   // Cache disabled - handle gracefully\n *   console.log('Cache unavailable, skipping...');\n * }\n * ```\n */\nexport function getCache(): Redis | Cluster | undefined\n{\n    return state.write;\n}\n\n/**\n * Get global cache read instance (falls back to write if no replica)\n *\n * @returns Cache read instance or write instance as fallback, undefined if disabled\n *\n * @example\n * ```typescript\n * import { getCacheRead } from '@spfn/core/cache';\n *\n * const cache = getCacheRead();\n * if (cache) {\n *   const value = await cache.get('key');\n * }\n * ```\n */\nexport function getCacheRead(): Redis | Cluster | undefined\n{\n    return state.read ?? state.write;\n}\n\n/**\n * Check if cache is disabled (connection failed or not configured)\n *\n * @example\n * ```typescript\n * import { isCacheDisabled } from '@spfn/core/cache';\n *\n * if (isCacheDisabled()) {\n *   // Use alternative strategy (e.g., in-memory cache, database)\n *   return await fetchFromDatabase();\n * }\n * ```\n */\nexport function isCacheDisabled(): boolean\n{\n    return state.disabled;\n}\n\n/**\n * Set global cache instances (for testing or manual configuration)\n *\n * @param write - Cache write instance\n * @param read - Cache read instance (optional, defaults to write)\n *\n * @example\n * ```typescript\n * import { setCache } from '@spfn/core/cache';\n * import Redis from 'ioredis';\n *\n * const write = new Redis('redis://master:6379');\n * const read = new Redis('redis://replica:6379');\n * setCache(write, read);\n * ```\n */\nexport function setCache(\n    write: Redis | Cluster | undefined,\n    read?: Redis | Cluster | undefined,\n): void\n{\n    state.write = write;\n    state.read = read ?? write;\n    state.disabled = !write;\n}\n\n/**\n * Initialize cache from environment variables\n * Automatically called by startServer()\n *\n * Supported environment variables (priority order):\n * - VALKEY_URL / CACHE_URL (single instance)\n * - VALKEY_WRITE_URL + VALKEY_READ_URL (master-replica)\n * - VALKEY_SENTINEL_HOSTS + VALKEY_MASTER_NAME (sentinel)\n * - VALKEY_CLUSTER_NODES (cluster)\n * - VALKEY_TLS_REJECT_UNAUTHORIZED (TLS config)\n * - Legacy: REDIS_* (backward compatibility)\n *\n * @returns Object with write and read instances, or undefined if disabled\n *\n * @example\n * ```typescript\n * import { initCache } from '@spfn/core/cache';\n *\n * // Manual initialization (not needed if using startServer)\n * const { write, read, disabled } = await initCache();\n * if (!disabled) {\n *   console.log('Cache available');\n * }\n * ```\n */\nexport async function initCache(): Promise<{\n    write?: Redis | Cluster;\n    read?: Redis | Cluster;\n    disabled: boolean;\n}>\n{\n    // Already initialized\n    if (state.write)\n    {\n        return { write: state.write, read: state.read, disabled: state.disabled };\n    }\n\n    // Auto-detect from environment\n    const { write, read } = await createCacheFromEnv();\n\n    if (write)\n    {\n        try\n        {\n            // Test connection\n            await write.ping();\n\n            // Test read instance if different\n            if (read && read !== write)\n            {\n                await read.ping();\n            }\n\n            state.write = write;\n            state.read = read;\n            state.disabled = false;\n\n            const hasReplica = read && read !== write;\n            cacheLogger.info(\n                hasReplica\n                    ? 'Cache connected (Master-Replica)'\n                    : 'Cache connected',\n                { mode: 'enabled' },\n            );\n\n            return { write: state.write, read: state.read, disabled: false };\n        }\n        catch (error)\n        {\n            cacheLogger.error(\n                'Cache connection failed - running in disabled mode',\n                error instanceof Error ? error : new Error(String(error)),\n                { mode: 'disabled' },\n            );\n\n            // Clean up failed connections\n            try\n            {\n                await write.quit();\n                if (read && read !== write)\n                {\n                    await read.quit();\n                }\n            }\n            catch\n            {\n                // Ignore cleanup errors\n            }\n\n            state.disabled = true;\n\n            return { write: undefined, read: undefined, disabled: true };\n        }\n    }\n\n    // No configuration or library not installed\n    state.disabled = true;\n    cacheLogger.info('Cache disabled - no configuration or library not installed', { mode: 'disabled' });\n\n    return { write: undefined, read: undefined, disabled: true };\n}\n\n/**\n * Close all cache connections and cleanup\n *\n * @example\n * ```typescript\n * import { closeCache } from '@spfn/core/cache';\n *\n * // During graceful shutdown\n * await closeCache();\n * ```\n */\nexport async function closeCache(): Promise<void>\n{\n    if (state.disabled)\n    {\n        cacheLogger.debug('Cache already disabled, nothing to close');\n\n        return;\n    }\n\n    const closePromises: Promise<unknown>[] = [];\n\n    if (state.write)\n    {\n        closePromises.push(\n            state.write.quit().catch((err: Error) =>\n            {\n                cacheLogger.error('Error closing cache write instance', err);\n            }),\n        );\n    }\n\n    if (state.read && state.read !== state.write)\n    {\n        closePromises.push(\n            state.read.quit().catch((err: Error) =>\n            {\n                cacheLogger.error('Error closing cache read instance', err);\n            }),\n        );\n    }\n\n    await Promise.all(closePromises);\n\n    state.write = undefined;\n    state.read = undefined;\n    state.disabled = true;\n\n    cacheLogger.info('Cache connections closed', { mode: 'disabled' });\n}\n\n/**\n * Get cache connection info (for debugging)\n *\n * @example\n * ```typescript\n * import { getCacheInfo } from '@spfn/core/cache';\n *\n * const info = getCacheInfo();\n * console.log(info);\n * // {\n * //   hasWrite: true,\n * //   hasRead: true,\n * //   isReplica: true,\n * //   disabled: false\n * // }\n * ```\n */\nexport function getCacheInfo(): {\n    hasWrite: boolean;\n    hasRead: boolean;\n    isReplica: boolean;\n    disabled: boolean;\n}\n{\n    return {\n        hasWrite: !!state.write,\n        hasRead: !!state.read,\n        isReplica: !!(state.read && state.read !== state.write),\n        disabled: state.disabled,\n    };\n}\n"]}
+{"version":3,"sources":["../../src/cache/cache-factory.ts","../../src/cache/cache-manager.ts"],"names":["cacheLogger","logger"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Cache factory with automatic environment variable detection\n */\n\nimport type { Redis, Cluster, RedisOptions, ClusterOptions } from 'ioredis';\nimport { logger } from '@spfn/core/logger';\nimport { env } from '@spfn/core/config';\n\n/**\n * Connection-resilience options applied to every cache client.\n *\n * ioredis defaults to an unbounded offline command queue and 20 retries per\n * request, so a post-startup cache outage can buffer every command and hang\n * awaits. Bound retries (CACHE_MAX_RETRIES_PER_REQUEST, default 3) so commands\n * fail fast instead of hanging; CACHE_ENABLE_OFFLINE_QUEUE (default true) can be\n * set false for strict fail-fast (reject immediately while disconnected).\n */\nfunction resilienceOptions(): Pick<RedisOptions, 'maxRetriesPerRequest' | 'enableOfflineQueue'>\n{\n    return {\n        maxRetriesPerRequest: env.CACHE_MAX_RETRIES_PER_REQUEST,\n        enableOfflineQueue: env.CACHE_ENABLE_OFFLINE_QUEUE,\n    };\n}\n\nconst cacheLogger = logger.child('@spfn/core:cache');\n\nexport interface CacheClients {\n    /** Primary cache for writes (or both read/write if no replica) */\n    write?: Redis | Cluster;\n    /** Replica cache for reads (optional, falls back to write) */\n    read?: Redis | Cluster;\n}\n\n/**\n * Check if any cache configuration exists in environment\n */\nfunction hasCacheConfig(): boolean\n{\n    return !!(\n        process.env.CACHE_URL ||\n        process.env.CACHE_WRITE_URL ||\n        process.env.CACHE_READ_URL ||\n        process.env.CACHE_SENTINEL_HOSTS ||\n        process.env.CACHE_CLUSTER_NODES\n    );\n}\n\n/**\n * Create cache client with TLS support\n */\nfunction createClient(\n    RedisClient: new (url: string, options?: RedisOptions) => Redis,\n    url: string,\n): Redis\n{\n    const options: RedisOptions = { ...resilienceOptions() };\n\n    // TLS support for secure connections\n    if (url.startsWith('rediss://'))\n    {\n        options.tls = {\n            rejectUnauthorized: process.env.CACHE_TLS_REJECT_UNAUTHORIZED !== 'false',\n        };\n    }\n\n    return new RedisClient(url, options);\n}\n\n/**\n * Create cache client(s) from environment variables\n *\n * Supported patterns (priority order):\n * 1. Single instance: CACHE_URL\n * 2. Master-Replica: CACHE_WRITE_URL + CACHE_READ_URL\n * 3. Sentinel: CACHE_SENTINEL_HOSTS + CACHE_MASTER_NAME\n * 4. Cluster: CACHE_CLUSTER_NODES\n *\n * @returns Cache client(s) or undefined if no configuration found\n *\n * @example\n * ```bash\n * # Single (most common)\n * CACHE_URL=redis://localhost:6379\n * CACHE_URL=rediss://secure.cache.com:6380  # TLS\n *\n * # Master-Replica\n * CACHE_WRITE_URL=redis://master:6379\n * CACHE_READ_URL=redis://replica:6379\n *\n * # Sentinel\n * CACHE_SENTINEL_HOSTS=sentinel1:26379,sentinel2:26379\n * CACHE_MASTER_NAME=mymaster\n * CACHE_PASSWORD=secret\n *\n * # Cluster\n * CACHE_CLUSTER_NODES=node1:6379,node2:6379,node3:6379\n * CACHE_PASSWORD=secret\n * ```\n */\nexport async function createCacheFromEnv(): Promise<CacheClients>\n{\n    // Quick exit if no cache config\n    if (!hasCacheConfig())\n    {\n        cacheLogger.info('No cache configuration found - running without cache');\n\n        return { write: undefined, read: undefined };\n    }\n\n    try\n    {\n        // Dynamic import to avoid bundling if not used\n        const ioredis = await import('ioredis');\n        const RedisClient = ioredis.default;\n\n        // Get environment variables\n        const singleUrl = process.env.CACHE_URL;\n        const writeUrl = process.env.CACHE_WRITE_URL;\n        const readUrl = process.env.CACHE_READ_URL;\n        const clusterNodes = process.env.CACHE_CLUSTER_NODES;\n        const sentinelHosts = process.env.CACHE_SENTINEL_HOSTS;\n        const masterName = process.env.CACHE_MASTER_NAME;\n        const password = process.env.CACHE_PASSWORD;\n\n        // 1. Single instance (most common - highest priority)\n        if (singleUrl && !writeUrl && !readUrl && !clusterNodes)\n        {\n            const client = createClient(RedisClient, singleUrl);\n            cacheLogger.debug('Created single cache instance', { url: singleUrl.replace(/:[^:@]+@/, ':***@') });\n\n            return { write: client, read: client };\n        }\n\n        // 2. Master-Replica pattern (both URLs required)\n        if (writeUrl && readUrl)\n        {\n            const write = createClient(RedisClient, writeUrl);\n            const read = createClient(RedisClient, readUrl);\n            cacheLogger.debug('Created master-replica cache instances');\n\n            return { write, read };\n        }\n\n        // 3. Sentinel pattern\n        if (sentinelHosts && masterName)\n        {\n            const sentinels = sentinelHosts.split(',').map((host) =>\n            {\n                const [hostname, port] = host.trim().split(':');\n\n                return { host: hostname, port: Number(port) || 26379 };\n            });\n\n            const options: RedisOptions = {\n                ...resilienceOptions(),\n                sentinels,\n                name: masterName,\n                password,\n            };\n\n            const client = new RedisClient(options);\n            cacheLogger.debug('Created sentinel cache instance', { masterName, sentinels: sentinels.length });\n\n            return { write: client, read: client };\n        }\n\n        // 4. Cluster pattern\n        if (clusterNodes)\n        {\n            const nodes = clusterNodes.split(',').map((node) =>\n            {\n                const [host, port] = node.trim().split(':');\n\n                return { host, port: Number(port) || 6379 };\n            });\n\n            const clusterOptions: ClusterOptions = {\n                redisOptions: {\n                    ...resilienceOptions(),\n                    password,\n                },\n            };\n\n            const cluster = new RedisClient.Cluster(nodes, clusterOptions);\n            cacheLogger.debug('Created cluster cache instance', { nodes: nodes.length });\n\n            return { write: cluster, read: cluster };\n        }\n\n        // 5. Fallback: Single URL with other configs present\n        if (singleUrl)\n        {\n            const client = createClient(RedisClient, singleUrl);\n            cacheLogger.debug('Created cache instance (fallback)', { url: singleUrl.replace(/:[^:@]+@/, ':***@') });\n\n            return { write: client, read: client };\n        }\n\n        // No valid configuration\n        cacheLogger.info('No valid cache configuration found - running without cache');\n\n        return { write: undefined, read: undefined };\n    }\n    catch (error)\n    {\n        if (error instanceof Error)\n        {\n            // Check if it's a missing dependency error\n            if (error.message.includes('Cannot find module'))\n            {\n                cacheLogger.warn(\n                    'Cache client library not installed',\n                    error,\n                    {\n                        suggestion: 'Install ioredis to enable cache: pnpm install ioredis',\n                        mode: 'disabled',\n                    },\n                );\n            }\n            else\n            {\n                cacheLogger.warn(\n                    'Failed to create cache client',\n                    error,\n                    { mode: 'disabled' },\n                );\n            }\n        }\n        else\n        {\n            cacheLogger.warn(\n                'Failed to create cache client',\n                { error: String(error), mode: 'disabled' },\n            );\n        }\n\n        return { write: undefined, read: undefined };\n    }\n}\n\n/**\n * Create single cache client (backward compatibility)\n * Only returns write instance\n */\nexport async function createSingleCacheFromEnv(): Promise<Redis | Cluster | undefined>\n{\n    const { write } = await createCacheFromEnv();\n\n    return write;\n}\n","/**\n * Global cache instance manager\n * Provides singleton access to cache (Valkey/Redis) across all modules\n * Supports Master-Replica pattern with separate read/write instances\n *\n * When cache is unavailable, falls back to disabled mode gracefully\n */\n\nimport type { Redis, Cluster } from 'ioredis';\n\nimport { createCacheFromEnv } from './cache-factory';\nimport { logger } from '@spfn/core/logger';\n\nconst cacheLogger = logger.child('@spfn/core:cache');\n\n// ── globalThis singleton ──────────────────────────────────────────\n// CJS/ESM dual-package hazard: 모듈이 두 번 로드되어도\n// Symbol.for() + globalThis로 동일 상태를 공유한다.\ninterface CacheState\n{\n    write: Redis | Cluster | undefined;\n    read: Redis | Cluster | undefined;\n    disabled: boolean;\n}\n\nconst CACHE_KEY = Symbol.for('@spfn/core:cache');\n\nconst state: CacheState = ((globalThis as any)[CACHE_KEY] ??= {\n    write: undefined,\n    read: undefined,\n    disabled: false,\n});\n\n/**\n * Get global cache write instance\n *\n * @returns Cache write instance or undefined if disabled/not initialized\n *\n * @example\n * ```typescript\n * import { getCache } from '@spfn/core/cache';\n *\n * const cache = getCache();\n * if (cache) {\n *   await cache.set('key', 'value');\n * } else {\n *   // Cache disabled - handle gracefully\n *   console.log('Cache unavailable, skipping...');\n * }\n * ```\n */\nexport function getCache(): Redis | Cluster | undefined\n{\n    return state.write;\n}\n\n/**\n * Get global cache read instance (falls back to write if no replica)\n *\n * @returns Cache read instance or write instance as fallback, undefined if disabled\n *\n * @example\n * ```typescript\n * import { getCacheRead } from '@spfn/core/cache';\n *\n * const cache = getCacheRead();\n * if (cache) {\n *   const value = await cache.get('key');\n * }\n * ```\n */\nexport function getCacheRead(): Redis | Cluster | undefined\n{\n    return state.read ?? state.write;\n}\n\n/**\n * Check if cache is disabled (connection failed or not configured)\n *\n * @example\n * ```typescript\n * import { isCacheDisabled } from '@spfn/core/cache';\n *\n * if (isCacheDisabled()) {\n *   // Use alternative strategy (e.g., in-memory cache, database)\n *   return await fetchFromDatabase();\n * }\n * ```\n */\nexport function isCacheDisabled(): boolean\n{\n    return state.disabled;\n}\n\n/**\n * Set global cache instances (for testing or manual configuration)\n *\n * @param write - Cache write instance\n * @param read - Cache read instance (optional, defaults to write)\n *\n * @example\n * ```typescript\n * import { setCache } from '@spfn/core/cache';\n * import Redis from 'ioredis';\n *\n * const write = new Redis('redis://master:6379');\n * const read = new Redis('redis://replica:6379');\n * setCache(write, read);\n * ```\n */\nexport function setCache(\n    write: Redis | Cluster | undefined,\n    read?: Redis | Cluster | undefined,\n): void\n{\n    state.write = write;\n    state.read = read ?? write;\n    state.disabled = !write;\n}\n\n/**\n * Initialize cache from environment variables\n * Automatically called by startServer()\n *\n * Supported environment variables (priority order):\n * - VALKEY_URL / CACHE_URL (single instance)\n * - VALKEY_WRITE_URL + VALKEY_READ_URL (master-replica)\n * - VALKEY_SENTINEL_HOSTS + VALKEY_MASTER_NAME (sentinel)\n * - VALKEY_CLUSTER_NODES (cluster)\n * - VALKEY_TLS_REJECT_UNAUTHORIZED (TLS config)\n * - Legacy: REDIS_* (backward compatibility)\n *\n * @returns Object with write and read instances, or undefined if disabled\n *\n * @example\n * ```typescript\n * import { initCache } from '@spfn/core/cache';\n *\n * // Manual initialization (not needed if using startServer)\n * const { write, read, disabled } = await initCache();\n * if (!disabled) {\n *   console.log('Cache available');\n * }\n * ```\n */\nexport async function initCache(): Promise<{\n    write?: Redis | Cluster;\n    read?: Redis | Cluster;\n    disabled: boolean;\n}>\n{\n    // Already initialized\n    if (state.write)\n    {\n        return { write: state.write, read: state.read, disabled: state.disabled };\n    }\n\n    // Auto-detect from environment\n    const { write, read } = await createCacheFromEnv();\n\n    if (write)\n    {\n        try\n        {\n            // Test connection\n            await write.ping();\n\n            // Test read instance if different\n            if (read && read !== write)\n            {\n                await read.ping();\n            }\n\n            state.write = write;\n            state.read = read;\n            state.disabled = false;\n\n            const hasReplica = read && read !== write;\n            cacheLogger.info(\n                hasReplica\n                    ? 'Cache connected (Master-Replica)'\n                    : 'Cache connected',\n                { mode: 'enabled' },\n            );\n\n            return { write: state.write, read: state.read, disabled: false };\n        }\n        catch (error)\n        {\n            cacheLogger.error(\n                'Cache connection failed - running in disabled mode',\n                error instanceof Error ? error : new Error(String(error)),\n                { mode: 'disabled' },\n            );\n\n            // Clean up failed connections\n            try\n            {\n                await write.quit();\n                if (read && read !== write)\n                {\n                    await read.quit();\n                }\n            }\n            catch\n            {\n                // Ignore cleanup errors\n            }\n\n            state.disabled = true;\n\n            return { write: undefined, read: undefined, disabled: true };\n        }\n    }\n\n    // No configuration or library not installed\n    state.disabled = true;\n    cacheLogger.info('Cache disabled - no configuration or library not installed', { mode: 'disabled' });\n\n    return { write: undefined, read: undefined, disabled: true };\n}\n\n/**\n * Close all cache connections and cleanup\n *\n * @example\n * ```typescript\n * import { closeCache } from '@spfn/core/cache';\n *\n * // During graceful shutdown\n * await closeCache();\n * ```\n */\nexport async function closeCache(): Promise<void>\n{\n    if (state.disabled)\n    {\n        cacheLogger.debug('Cache already disabled, nothing to close');\n\n        return;\n    }\n\n    const closePromises: Promise<unknown>[] = [];\n\n    if (state.write)\n    {\n        closePromises.push(\n            state.write.quit().catch((err: Error) =>\n            {\n                cacheLogger.error('Error closing cache write instance', err);\n            }),\n        );\n    }\n\n    if (state.read && state.read !== state.write)\n    {\n        closePromises.push(\n            state.read.quit().catch((err: Error) =>\n            {\n                cacheLogger.error('Error closing cache read instance', err);\n            }),\n        );\n    }\n\n    await Promise.all(closePromises);\n\n    state.write = undefined;\n    state.read = undefined;\n    state.disabled = true;\n\n    cacheLogger.info('Cache connections closed', { mode: 'disabled' });\n}\n\n/**\n * Get cache connection info (for debugging)\n *\n * @example\n * ```typescript\n * import { getCacheInfo } from '@spfn/core/cache';\n *\n * const info = getCacheInfo();\n * console.log(info);\n * // {\n * //   hasWrite: true,\n * //   hasRead: true,\n * //   isReplica: true,\n * //   disabled: false\n * // }\n * ```\n */\nexport function getCacheInfo(): {\n    hasWrite: boolean;\n    hasRead: boolean;\n    isReplica: boolean;\n    disabled: boolean;\n}\n{\n    return {\n        hasWrite: !!state.write,\n        hasRead: !!state.read,\n        isReplica: !!(state.read && state.read !== state.write),\n        disabled: state.disabled,\n    };\n}\n"]}

package/dist/config/index.d.ts

@@ -72,6 +72,16 @@ declare const coreEnvSchema: {
     } & {
         key: "DB_POOL_MAX";
     };
+    DB_POOL_READ_MAX: {
+        description: string;
+        required: boolean;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "DB_POOL_READ_MAX";
+    };
     DB_POOL_IDLE_TIMEOUT: {
         description: string;
         default: number;
@@ -212,6 +222,26 @@ declare const coreEnvSchema: {
     } & {
         key: "TRANSACTION_TIMEOUT";
     };
+    TRANSACTION_IDLE_TIMEOUT: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "TRANSACTION_IDLE_TIMEOUT";
+    };
+    JOB_POLLING_INTERVAL_SECONDS: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "JOB_POLLING_INTERVAL_SECONDS";
+    };
     DB_DEBUG_TRACE: {
         description: string;
         default: boolean;
@@ -337,6 +367,36 @@ declare const coreEnvSchema: {
     } & {
         key: "CACHE_TLS_REJECT_UNAUTHORIZED";
     };
+    CACHE_MAX_RETRIES_PER_REQUEST: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "CACHE_MAX_RETRIES_PER_REQUEST";
+    };
+    CACHE_ENABLE_OFFLINE_QUEUE: {
+        description: string;
+        default: boolean;
+        examples: boolean[];
+    } & {
+        type: "boolean";
+        validator: (value: string) => boolean;
+    } & {
+        key: "CACHE_ENABLE_OFFLINE_QUEUE";
+    };
+    DB_MAX_ROWS: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "DB_MAX_ROWS";
+    };
     PORT: {
         description: string;
         default: number;
@@ -469,6 +529,41 @@ declare const coreEnvSchema: {
     } & {
         key: "RPC_PROXY_TIMEOUT";
     };
+    SPFN_PROXY_SECRET: {
+        description: string;
+        required: boolean;
+        sensitive: boolean;
+        nextjs: boolean;
+        examples: string[];
+    } & {
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_PROXY_SECRET";
+    };
+    SPFN_PROXY_SECRET_PREVIOUS: {
+        description: string;
+        required: boolean;
+        sensitive: boolean;
+        nextjs: boolean;
+        examples: string[];
+    } & {
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_PROXY_SECRET_PREVIOUS";
+    };
+    TRUSTED_PROXY_HOPS: {
+        description: string;
+        default: number;
+        nextjs: boolean;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "TRUSTED_PROXY_HOPS";
+    };
 };
 
 /**
@@ -533,6 +628,16 @@ declare const registry: _spfn_core_env.EnvRegistry<{
     } & {
         key: "DB_POOL_MAX";
     };
+    DB_POOL_READ_MAX: {
+        description: string;
+        required: boolean;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "DB_POOL_READ_MAX";
+    };
     DB_POOL_IDLE_TIMEOUT: {
         description: string;
         default: number;
@@ -673,6 +778,26 @@ declare const registry: _spfn_core_env.EnvRegistry<{
     } & {
         key: "TRANSACTION_TIMEOUT";
     };
+    TRANSACTION_IDLE_TIMEOUT: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "TRANSACTION_IDLE_TIMEOUT";
+    };
+    JOB_POLLING_INTERVAL_SECONDS: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "JOB_POLLING_INTERVAL_SECONDS";
+    };
     DB_DEBUG_TRACE: {
         description: string;
         default: boolean;
@@ -798,6 +923,36 @@ declare const registry: _spfn_core_env.EnvRegistry<{
     } & {
         key: "CACHE_TLS_REJECT_UNAUTHORIZED";
     };
+    CACHE_MAX_RETRIES_PER_REQUEST: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "CACHE_MAX_RETRIES_PER_REQUEST";
+    };
+    CACHE_ENABLE_OFFLINE_QUEUE: {
+        description: string;
+        default: boolean;
+        examples: boolean[];
+    } & {
+        type: "boolean";
+        validator: (value: string) => boolean;
+    } & {
+        key: "CACHE_ENABLE_OFFLINE_QUEUE";
+    };
+    DB_MAX_ROWS: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "DB_MAX_ROWS";
+    };
     PORT: {
         description: string;
         default: number;
@@ -930,6 +1085,41 @@ declare const registry: _spfn_core_env.EnvRegistry<{
     } & {
         key: "RPC_PROXY_TIMEOUT";
     };
+    SPFN_PROXY_SECRET: {
+        description: string;
+        required: boolean;
+        sensitive: boolean;
+        nextjs: boolean;
+        examples: string[];
+    } & {
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_PROXY_SECRET";
+    };
+    SPFN_PROXY_SECRET_PREVIOUS: {
+        description: string;
+        required: boolean;
+        sensitive: boolean;
+        nextjs: boolean;
+        examples: string[];
+    } & {
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_PROXY_SECRET_PREVIOUS";
+    };
+    TRUSTED_PROXY_HOPS: {
+        description: string;
+        default: number;
+        nextjs: boolean;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "TRUSTED_PROXY_HOPS";
+    };
 }>;
 /**
  * Validated environment configuration
@@ -987,6 +1177,16 @@ declare const env: _spfn_core_env.InferEnvType<{
     } & {
         key: "DB_POOL_MAX";
     };
+    DB_POOL_READ_MAX: {
+        description: string;
+        required: boolean;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "DB_POOL_READ_MAX";
+    };
     DB_POOL_IDLE_TIMEOUT: {
         description: string;
         default: number;
@@ -1127,6 +1327,26 @@ declare const env: _spfn_core_env.InferEnvType<{
     } & {
         key: "TRANSACTION_TIMEOUT";
     };
+    TRANSACTION_IDLE_TIMEOUT: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "TRANSACTION_IDLE_TIMEOUT";
+    };
+    JOB_POLLING_INTERVAL_SECONDS: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "JOB_POLLING_INTERVAL_SECONDS";
+    };
     DB_DEBUG_TRACE: {
         description: string;
         default: boolean;
@@ -1252,6 +1472,36 @@ declare const env: _spfn_core_env.InferEnvType<{
     } & {
         key: "CACHE_TLS_REJECT_UNAUTHORIZED";
     };
+    CACHE_MAX_RETRIES_PER_REQUEST: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "CACHE_MAX_RETRIES_PER_REQUEST";
+    };
+    CACHE_ENABLE_OFFLINE_QUEUE: {
+        description: string;
+        default: boolean;
+        examples: boolean[];
+    } & {
+        type: "boolean";
+        validator: (value: string) => boolean;
+    } & {
+        key: "CACHE_ENABLE_OFFLINE_QUEUE";
+    };
+    DB_MAX_ROWS: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "DB_MAX_ROWS";
+    };
     PORT: {
         description: string;
         default: number;
@@ -1384,6 +1634,41 @@ declare const env: _spfn_core_env.InferEnvType<{
     } & {
         key: "RPC_PROXY_TIMEOUT";
     };
+    SPFN_PROXY_SECRET: {
+        description: string;
+        required: boolean;
+        sensitive: boolean;
+        nextjs: boolean;
+        examples: string[];
+    } & {
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_PROXY_SECRET";
+    };
+    SPFN_PROXY_SECRET_PREVIOUS: {
+        description: string;
+        required: boolean;
+        sensitive: boolean;
+        nextjs: boolean;
+        examples: string[];
+    } & {
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_PROXY_SECRET_PREVIOUS";
+    };
+    TRUSTED_PROXY_HOPS: {
+        description: string;
+        default: number;
+        nextjs: boolean;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "TRUSTED_PROXY_HOPS";
+    };
 }>;
 
 export { env, coreEnvSchema as envSchema, registry };

package/dist/config/index.js

@@ -1,4 +1,4 @@
-import { defineEnvSchema, envNumber, envUrl, envString, envBoolean, envEnum, parseRedisUrl, parsePostgresUrl, createEnvRegistry } from '@spfn/core/env';
+import { defineEnvSchema, envNumber, envString, envUrl, envBoolean, envEnum, parseRedisUrl, parsePostgresUrl, createEnvRegistry } from '@spfn/core/env';
 
 // src/config/index.ts
 var coreEnvSchema = defineEnvSchema({
@@ -42,6 +42,11 @@ var coreEnvSchema = defineEnvSchema({
     default: 10,
     examples: [10, 20, 50]
   }),
+  DB_POOL_READ_MAX: envNumber({
+    description: "Maximum connections for the read-replica pool. Defaults to DB_POOL_MAX. Set lower so write.max + read.max stays under the server max_connections (each process otherwise opens up to 2 \xD7 DB_POOL_MAX when a replica is configured).",
+    required: false,
+    examples: [5, 10, 20]
+  }),
   DB_POOL_IDLE_TIMEOUT: envNumber({
     description: "Database connection idle timeout in seconds",
     default: 30,
@@ -124,6 +129,19 @@ var coreEnvSchema = defineEnvSchema({
     default: 3e4,
     examples: [1e4, 3e4, 6e4]
   }),
+  TRANSACTION_IDLE_TIMEOUT: envNumber({
+    description: "Max time (ms) a transaction may sit idle (no running query) before Postgres terminates it and reclaims the pooled connection. Guards against external I/O held inside a transaction starving the connection pool. 0 disables.",
+    default: 3e4,
+    examples: [1e4, 3e4, 0]
+  }),
+  // ========================================================================
+  // Jobs (pg-boss)
+  // ========================================================================
+  JOB_POLLING_INTERVAL_SECONDS: envNumber({
+    description: "How often each pg-boss worker polls the DB for new jobs (seconds). Lower = faster pickup, more idle SELECT load; higher = less DB chatter, slower pickup. Per-job override via job options.",
+    default: 2,
+    examples: [1, 2, 10]
+  }),
   // ========================================================================
   // Database - Development
   // ========================================================================
@@ -204,6 +222,24 @@ var coreEnvSchema = defineEnvSchema({
     default: true,
     examples: [true, false]
   }),
+  CACHE_MAX_RETRIES_PER_REQUEST: envNumber({
+    description: "Max ioredis retries per command before it rejects (fail fast instead of hanging on a cache outage). ioredis default is 20.",
+    default: 3,
+    examples: [1, 3, 20]
+  }),
+  CACHE_ENABLE_OFFLINE_QUEUE: envBoolean({
+    description: "Queue commands while the cache is disconnected (true) vs reject immediately for strict fail-fast (false). Default true keeps resilience to brief blips.",
+    default: true,
+    examples: [true, false]
+  }),
+  // ========================================================================
+  // Database - Query limits
+  // ========================================================================
+  DB_MAX_ROWS: envNumber({
+    description: "Safety ceiling for rows returned by repository findMany (0 = unlimited). When >0, an unbounded query is capped and an explicit limit is clamped, guarding against accidentally loading a whole large table.",
+    default: 0,
+    examples: [0, 1e3, 1e4]
+  }),
   // ========================================================================
   // Server - Core
   // ========================================================================
@@ -285,6 +321,29 @@ var coreEnvSchema = defineEnvSchema({
     default: 12e4,
     nextjs: true,
     examples: [6e4, 12e4, 28e4]
+  }),
+  // ========================================================================
+  // Proxy → Backend trust (HMAC signing)
+  // ========================================================================
+  SPFN_PROXY_SECRET: envString({
+    description: "Shared secret for signing proxy\u2192backend requests (HMAC-SHA256). Read by BOTH processes \u2014 the Next.js proxy (to sign) and the SPFN backend (to verify) \u2014 so it belongs in .env.local (loaded by both; the backend reads it via loadEnv, Next.js reads it server-side without exposing it to the browser). Set the SAME value on both. Leave unset to disable proxy-guard signing.",
+    required: false,
+    sensitive: true,
+    nextjs: true,
+    examples: ["<32+ byte random hex>", "v2:<32+ byte random hex>"]
+  }),
+  SPFN_PROXY_SECRET_PREVIOUS: envString({
+    description: "Previous (grace) proxy keys still accepted for verification during rotation \u2014 comma-separated <keyId>:<secret>. The proxy never signs with these; they only keep requests signed with the prior key verifying until a rollout settles. Backend-only (verification), so it belongs in .env.server, NOT exposed to the Next.js process.",
+    required: false,
+    sensitive: true,
+    nextjs: false,
+    examples: ["v1:<old secret>", "v1:<old>,v0:<older>"]
+  }),
+  TRUSTED_PROXY_HOPS: envNumber({
+    description: "Number of trusted reverse proxies in front of the Next.js proxy (e.g. cloud LB + nginx = 2). Read by the proxy to extract the real client IP from the inbound X-Forwarded-For (counting from the right, which your own infra appends and a client cannot spoof) and forward it to the backend for rate limiting. Set it to your actual hop count; too low trusts a client-spoofable entry, too high collapses users behind a shared proxy IP.",
+    default: 1,
+    nextjs: true,
+    examples: [1, 2, 3]
   })
 });