@pikku/core 0.11.1 → 0.12.0

package/src/wirings/queue/queue-runner.test.ts

@@ -5,6 +5,7 @@ import {
   getQueueWorkers,
   removeQueueWorker,
   runQueueJob,
+  createQueueJobRunner,
   QueueJobFailedError,
   QueueJobDiscardedError,
 } from './queue-runner.js'
@@ -38,9 +39,9 @@ const createMockJob = (
   data,
 })
 
-const addTestQueueFunction = (pikkuFuncName: string) => {
-  pikkuState('function', 'meta')[pikkuFuncName] = {
-    pikkuFuncName,
+const addTestQueueFunction = (pikkuFuncId: string) => {
+  pikkuState(null, 'function', 'meta')[pikkuFuncId] = {
+    pikkuFuncId,
     inputSchemaName: null,
     outputSchemaName: null,
     middleware: undefined,
@@ -51,7 +52,7 @@ const addTestQueueFunction = (pikkuFuncName: string) => {
 describe('wireQueueWorker', () => {
   test('should successfully wire a queue worker', () => {
     const mockWorker: CoreQueueWorker = {
-      queueName: 'test-queue',
+      name: 'test-queue',
       func: {
         func: async (services: any, data: any, wire: any) => {
           return { processed: true }
@@ -60,22 +61,21 @@ describe('wireQueueWorker', () => {
       },
     }
 
-    // Set up metadata first
-    pikkuState('queue', 'meta')['test-queue'] = {
-      pikkuFuncName: 'queue_test-queue',
-      queueName: 'test-queue',
+    pikkuState(null, 'queue', 'meta')['test-queue'] = {
+      pikkuFuncId: 'queue_test-queue',
+      name: 'test-queue',
     }
     addTestQueueFunction('queue_test-queue')
     wireQueueWorker(mockWorker)
 
-    const registrations = pikkuState('queue', 'registrations')
+    const registrations = pikkuState(null, 'queue', 'registrations')
     assert.equal(registrations.has('test-queue'), true)
     assert.equal(registrations.get('test-queue'), mockWorker)
   })
 
   test('should throw error when processor metadata not found', () => {
     const mockWorker: CoreQueueWorker = {
-      queueName: 'missing-meta-queue',
+      name: 'missing-meta-queue',
       func: {
         func: async () => {},
         auth: false,
@@ -85,7 +85,9 @@ describe('wireQueueWorker', () => {
     assert.throws(
       () => wireQueueWorker(mockWorker),
       (error: any) => {
-        assert(error.message.includes('Queue processor metadata not found'))
+        assert(
+          error.message.includes('Missing generated metadata for queue worker')
+        )
         assert(error.message.includes('missing-meta-queue'))
         return true
       }
@@ -98,7 +100,7 @@ describe('wireQueueWorker', () => {
     }
 
     const mockWorker: CoreQueueWorker = {
-      queueName: 'worker-with-middleware',
+      name: 'worker-with-middleware',
       func: {
         func: async () => {},
         auth: false,
@@ -109,14 +111,14 @@ describe('wireQueueWorker', () => {
       tags: ['queue'],
     }
 
-    pikkuState('queue', 'meta')['worker-with-middleware'] = {
-      pikkuFuncName: 'queue_worker-with-middleware',
-      queueName: 'worker-with-middleware',
+    pikkuState(null, 'queue', 'meta')['worker-with-middleware'] = {
+      pikkuFuncId: 'queue_worker-with-middleware',
+      name: 'worker-with-middleware',
     }
     addTestQueueFunction('queue_worker-with-middleware')
     wireQueueWorker(mockWorker)
 
-    const registrations = pikkuState('queue', 'registrations')
+    const registrations = pikkuState(null, 'queue', 'registrations')
     const worker = registrations.get('worker-with-middleware')
     assert.equal(worker?.middleware?.length, 1)
     assert.deepEqual(worker?.tags, ['queue'])
@@ -126,16 +128,16 @@ describe('wireQueueWorker', () => {
 describe('getQueueWorkers', () => {
   test('should return the registrations map', () => {
     const mockWorker: CoreQueueWorker = {
-      queueName: 'test-queue',
+      name: 'test-queue',
       func: {
         func: async () => {},
         auth: false,
       },
     }
 
-    pikkuState('queue', 'meta')['test-queue'] = {
-      pikkuFuncName: 'queue_test-queue',
-      queueName: 'test-queue',
+    pikkuState(null, 'queue', 'meta')['test-queue'] = {
+      pikkuFuncId: 'queue_test-queue',
+      name: 'test-queue',
     }
     addTestQueueFunction('queue_test-queue')
     wireQueueWorker(mockWorker)
@@ -155,16 +157,16 @@ describe('getQueueWorkers', () => {
 describe('removeQueueWorker', () => {
   test('should successfully remove a queue worker', async () => {
     const mockWorker: CoreQueueWorker = {
-      queueName: 'removable-queue',
+      name: 'removable-queue',
       func: {
         func: async () => {},
         auth: false,
       },
     }
 
-    pikkuState('queue', 'meta')['removable-queue'] = {
-      pikkuFuncName: 'queue_removable-queue',
-      queueName: 'removable-queue',
+    pikkuState(null, 'queue', 'meta')['removable-queue'] = {
+      pikkuFuncId: 'queue_removable-queue',
+      name: 'removable-queue',
     }
     addTestQueueFunction('queue_removable-queue')
     wireQueueWorker(mockWorker)
@@ -198,7 +200,7 @@ describe('runQueueJob', () => {
     let receivedData: any
 
     const mockWorker: CoreQueueWorker = {
-      queueName: 'simple-queue',
+      name: 'simple-queue',
       func: {
         func: async (services: any, data: any, wire: any) => {
           jobProcessed = true
@@ -209,9 +211,9 @@ describe('runQueueJob', () => {
       },
     }
 
-    pikkuState('queue', 'meta')['simple-queue'] = {
-      pikkuFuncName: 'queue_simple-queue',
-      queueName: 'simple-queue',
+    pikkuState(null, 'queue', 'meta')['simple-queue'] = {
+      pikkuFuncId: 'queue_simple-queue',
+      name: 'simple-queue',
     }
     addTestQueueFunction('queue_simple-queue')
     wireQueueWorker(mockWorker)
@@ -238,7 +240,7 @@ describe('runQueueJob', () => {
 
   test('should handle job.fail() by throwing QueueJobFailedError', async () => {
     const mockWorker: CoreQueueWorker = {
-      queueName: 'fail-queue',
+      name: 'fail-queue',
       func: {
         func: async (services: any, data: any, wire: any) => {
           await wire.queue.fail('Processing failed')
@@ -247,9 +249,9 @@ describe('runQueueJob', () => {
       },
     }
 
-    pikkuState('queue', 'meta')['fail-queue'] = {
-      pikkuFuncName: 'queue_fail-queue',
-      queueName: 'fail-queue',
+    pikkuState(null, 'queue', 'meta')['fail-queue'] = {
+      pikkuFuncId: 'queue_fail-queue',
+      name: 'fail-queue',
     }
     addTestQueueFunction('queue_fail-queue')
     wireQueueWorker(mockWorker)
@@ -276,7 +278,7 @@ describe('runQueueJob', () => {
 
   test('should handle job.fail() without reason', async () => {
     const mockWorker: CoreQueueWorker = {
-      queueName: 'fail-no-reason-queue',
+      name: 'fail-no-reason-queue',
       func: {
         func: async (services: any, data: any, wire: any) => {
           await wire.queue.fail()
@@ -285,9 +287,9 @@ describe('runQueueJob', () => {
       },
     }
 
-    pikkuState('queue', 'meta')['fail-no-reason-queue'] = {
-      pikkuFuncName: 'queue_fail-no-reason-queue',
-      queueName: 'fail-no-reason-queue',
+    pikkuState(null, 'queue', 'meta')['fail-no-reason-queue'] = {
+      pikkuFuncId: 'queue_fail-no-reason-queue',
+      name: 'fail-no-reason-queue',
     }
     addTestQueueFunction('queue_fail-no-reason-queue')
     wireQueueWorker(mockWorker)
@@ -312,7 +314,7 @@ describe('runQueueJob', () => {
 
   test('should handle job.discard() by throwing QueueJobDiscardedError', async () => {
     const mockWorker: CoreQueueWorker = {
-      queueName: 'discard-queue',
+      name: 'discard-queue',
       func: {
         func: async (services: any, data: any, wire: any) => {
           await wire.queue.discard('Invalid data')
@@ -321,9 +323,9 @@ describe('runQueueJob', () => {
       },
     }
 
-    pikkuState('queue', 'meta')['discard-queue'] = {
-      pikkuFuncName: 'queue_discard-queue',
-      queueName: 'discard-queue',
+    pikkuState(null, 'queue', 'meta')['discard-queue'] = {
+      pikkuFuncId: 'queue_discard-queue',
+      name: 'discard-queue',
     }
     addTestQueueFunction('queue_discard-queue')
     wireQueueWorker(mockWorker)
@@ -352,7 +354,7 @@ describe('runQueueJob', () => {
     const progressUpdates: Array<number | string | object> = []
 
     const mockWorker: CoreQueueWorker = {
-      queueName: 'progress-queue',
+      name: 'progress-queue',
       func: {
         func: async (services: any, data: any, wire: any) => {
           await wire.queue.updateProgress(25)
@@ -364,9 +366,9 @@ describe('runQueueJob', () => {
       },
     }
 
-    pikkuState('queue', 'meta')['progress-queue'] = {
-      pikkuFuncName: 'queue_progress-queue',
-      queueName: 'progress-queue',
+    pikkuState(null, 'queue', 'meta')['progress-queue'] = {
+      pikkuFuncId: 'queue_progress-queue',
+      name: 'progress-queue',
     }
     addTestQueueFunction('queue_progress-queue')
     wireQueueWorker(mockWorker)
@@ -387,7 +389,7 @@ describe('runQueueJob', () => {
 
   test('should use default updateProgress when not provided', async () => {
     const mockWorker: CoreQueueWorker = {
-      queueName: 'default-progress-queue',
+      name: 'default-progress-queue',
       func: {
         func: async (services: any, data: any, wire: any) => {
           await wire.queue.updateProgress(50)
@@ -397,9 +399,9 @@ describe('runQueueJob', () => {
       },
     }
 
-    pikkuState('queue', 'meta')['default-progress-queue'] = {
-      pikkuFuncName: 'queue_default-progress-queue',
-      queueName: 'default-progress-queue',
+    pikkuState(null, 'queue', 'meta')['default-progress-queue'] = {
+      pikkuFuncId: 'queue_default-progress-queue',
+      name: 'default-progress-queue',
     }
     addTestQueueFunction('queue_default-progress-queue')
     wireQueueWorker(mockWorker)
@@ -421,7 +423,7 @@ describe('runQueueJob', () => {
     let capturedWire: any
 
     const mockWorker: CoreQueueWorker = {
-      queueName: 'wire-queue',
+      name: 'wire-queue',
       func: {
         func: async (services: any, data: any, wire: any) => {
           capturedWire = wire
@@ -431,9 +433,9 @@ describe('runQueueJob', () => {
       },
     }
 
-    pikkuState('queue', 'meta')['wire-queue'] = {
-      pikkuFuncName: 'queue_wire-queue',
-      queueName: 'wire-queue',
+    pikkuState(null, 'queue', 'meta')['wire-queue'] = {
+      pikkuFuncId: 'queue_wire-queue',
+      name: 'wire-queue',
     }
     addTestQueueFunction('queue_wire-queue')
     wireQueueWorker(mockWorker)
@@ -465,7 +467,9 @@ describe('runQueueJob', () => {
         })
       },
       (error: any) => {
-        assert(error.message.includes('Processor metadata not found'))
+        assert(
+          error.message.includes('Missing generated metadata for queue worker')
+        )
         assert(error.message.includes('missing-meta-queue'))
         return true
       }
@@ -473,10 +477,9 @@ describe('runQueueJob', () => {
   })
 
   test('should throw error when queue worker registration not found', async () => {
-    // Add metadata but not registration
-    pikkuState('queue', 'meta')['no-registration-queue'] = {
-      pikkuFuncName: 'queue_no-registration-queue',
-      queueName: 'no-registration-queue',
+    pikkuState(null, 'queue', 'meta')['no-registration-queue'] = {
+      pikkuFuncId: 'queue_no-registration-queue',
+      name: 'no-registration-queue',
     }
 
     const mockLogger = createMockLogger()
@@ -502,16 +505,16 @@ describe('runQueueJob', () => {
     const mockWireService = { custom: 'service' }
 
     const mockWorker: CoreQueueWorker = {
-      queueName: 'session-services-queue',
+      name: 'session-services-queue',
       func: {
         func: async () => 'ok',
         auth: false,
       },
     }
 
-    pikkuState('queue', 'meta')['session-services-queue'] = {
-      pikkuFuncName: 'queue_session-services-queue',
-      queueName: 'session-services-queue',
+    pikkuState(null, 'queue', 'meta')['session-services-queue'] = {
+      pikkuFuncId: 'queue_session-services-queue',
+      name: 'session-services-queue',
     }
     addTestQueueFunction('queue_session-services-queue')
     wireQueueWorker(mockWorker)
@@ -533,7 +536,7 @@ describe('runQueueJob', () => {
 
   test('should log errors when job processing fails', async () => {
     const mockWorker: CoreQueueWorker = {
-      queueName: 'error-queue',
+      name: 'error-queue',
       func: {
         func: async () => {
           throw new Error('Processing error')
@@ -542,9 +545,9 @@ describe('runQueueJob', () => {
       },
     }
 
-    pikkuState('queue', 'meta')['error-queue'] = {
-      pikkuFuncName: 'queue_error-queue',
-      queueName: 'error-queue',
+    pikkuState(null, 'queue', 'meta')['error-queue'] = {
+      pikkuFuncId: 'queue_error-queue',
+      name: 'error-queue',
     }
     addTestQueueFunction('queue_error-queue')
     wireQueueWorker(mockWorker)
@@ -580,7 +583,7 @@ describe('runQueueJob', () => {
     }
 
     const mockWorker: CoreQueueWorker = {
-      queueName: 'middleware-queue',
+      name: 'middleware-queue',
       func: {
         func: async () => {
           executionOrder.push('job')
@@ -591,9 +594,9 @@ describe('runQueueJob', () => {
       middleware: [middleware],
     }
 
-    pikkuState('queue', 'meta')['middleware-queue'] = {
-      pikkuFuncName: 'queue_middleware-queue',
-      queueName: 'middleware-queue',
+    pikkuState(null, 'queue', 'meta')['middleware-queue'] = {
+      pikkuFuncId: 'queue_middleware-queue',
+      name: 'middleware-queue',
     }
     addTestQueueFunction('queue_middleware-queue')
     wireQueueWorker(mockWorker)
@@ -611,16 +614,16 @@ describe('runQueueJob', () => {
 
   test('should log debug message on successful job completion', async () => {
     const mockWorker: CoreQueueWorker = {
-      queueName: 'debug-queue',
+      name: 'debug-queue',
       func: {
         func: async () => 'success',
         auth: false,
       },
     }
 
-    pikkuState('queue', 'meta')['debug-queue'] = {
-      pikkuFuncName: 'queue_debug-queue',
-      queueName: 'debug-queue',
+    pikkuState(null, 'queue', 'meta')['debug-queue'] = {
+      pikkuFuncId: 'queue_debug-queue',
+      name: 'debug-queue',
     }
     addTestQueueFunction('queue_debug-queue')
     wireQueueWorker(mockWorker)
@@ -639,3 +642,42 @@ describe('runQueueJob', () => {
     assert(debugLogs[0].message.includes('Successfully processed job job-777'))
   })
 })
+
+describe('createQueueJobRunner', () => {
+  test('delegates queue job execution using bound services', async () => {
+    const mockWorker: CoreQueueWorker = {
+      name: 'bound-runner-queue',
+      func: {
+        func: async (_services: any, data: any) => {
+          return data.value + 1
+        },
+        auth: false,
+      },
+    }
+
+    pikkuState(null, 'queue', 'meta')['bound-runner-queue'] = {
+      pikkuFuncId: 'queue_bound-runner-queue',
+      name: 'bound-runner-queue',
+    }
+    addTestQueueFunction('queue_bound-runner-queue')
+    wireQueueWorker(mockWorker)
+
+    const mockLogger = createMockLogger()
+    const runJob = createQueueJobRunner({
+      singletonServices: { logger: mockLogger } as any,
+    })
+
+    await runJob({
+      job: createMockJob('bound-runner-queue', 'job-888', { value: 41 }),
+    })
+
+    const logs = mockLogger.getLogs()
+    assert(
+      logs.some(
+        (log) =>
+          log.level === 'debug' &&
+          String(log.message).includes('Successfully processed job job-888')
+      )
+    )
+  })
+})

package/src/wirings/queue/queue-runner.ts

@@ -5,6 +5,7 @@ import type {
   CorePikkuFunctionSessionless,
 } from '../../function/functions.types.js'
 import { getErrorResponse, PikkuError } from '../../errors/error-handler.js'
+import { PikkuMissingMetaError } from '../../errors/errors.js'
 import { pikkuState } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { CreateWireServices } from '../../types/core.types.js'
@@ -52,16 +53,16 @@ export const wireQueueWorker = <
   queueWorker: CoreQueueWorker<PikkuFunctionConfig>
 ) => {
   // Get processor metadata
-  const meta = pikkuState('queue', 'meta')
-  const processorMeta = meta[queueWorker.queueName]
+  const meta = pikkuState(null, 'queue', 'meta')
+  const processorMeta = meta[queueWorker.name]
   if (!processorMeta) {
-    throw new Error(
-      `Queue processor metadata not found for '${queueWorker.queueName}'. Make sure to run the CLI to generate metadata.`
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for queue worker '${queueWorker.name}'`
     )
   }
 
   // Register the function with pikku
-  addFunction(processorMeta.pikkuFuncName, {
+  addFunction(processorMeta.pikkuFuncId, {
     func: queueWorker.func.func,
     auth: queueWorker.func.auth,
     permissions: queueWorker.func.permissions,
@@ -70,22 +71,22 @@ export const wireQueueWorker = <
   })
 
   // Store processor definition in state - runtime adapters will pick this up
-  const registrations = pikkuState('queue', 'registrations')
-  registrations.set(queueWorker.queueName, queueWorker)
+  const registrations = pikkuState(null, 'queue', 'registrations')
+  registrations.set(queueWorker.name, queueWorker)
 }
 
 /**
  * Get all registered queue processors
  */
 export function getQueueWorkers(): Map<string, CoreQueueWorker> {
-  return pikkuState('queue', 'registrations')
+  return pikkuState(null, 'queue', 'registrations')
 }
 
 /**
  * Stop and remove a queue processor
  */
 export async function removeQueueWorker(name: string): Promise<void> {
-  const registrations = pikkuState('queue', 'registrations')
+  const registrations = pikkuState(null, 'queue', 'registrations')
   const registration = registrations.get(name)
 
   if (!registration) {
@@ -111,14 +112,16 @@ export async function runQueueJob({
 }): Promise<void> {
   const logger = singletonServices.logger
 
-  const meta = pikkuState('queue', 'meta')
+  const meta = pikkuState(null, 'queue', 'meta')
   const processorMeta = meta[job.queueName]
   if (!processorMeta) {
-    throw new Error(`Processor metadata not found for: ${job.queueName}`)
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for queue worker '${job.queueName}'`
+    )
   }
 
   // Get the queue worker registration to access middleware
-  const registrations = pikkuState('queue', 'registrations')
+  const registrations = pikkuState(null, 'queue', 'registrations')
   const queueWorker = registrations.get(job.queueName)
   if (!queueWorker) {
     throw new Error(`Queue worker registration not found for: ${job.queueName}`)
@@ -153,7 +156,7 @@ export async function runQueueJob({
     const result = await runPikkuFunc(
       'queue',
       job.queueName,
-      processorMeta.pikkuFuncName,
+      processorMeta.pikkuFuncId,
       {
         singletonServices,
         createWireServices,
@@ -186,3 +189,26 @@ export async function runQueueJob({
     throw error
   }
 }
+
+export const createQueueJobRunner = ({
+  singletonServices,
+  createWireServices,
+}: {
+  singletonServices: CoreServices
+  createWireServices?: CreateWireServices
+}) => {
+  return async ({
+    job,
+    updateProgress,
+  }: {
+    job: QueueJob
+    updateProgress?: (progress: number | string | object) => Promise<void>
+  }) => {
+    await runQueueJob({
+      singletonServices,
+      createWireServices,
+      job,
+      updateProgress,
+    })
+  }
+}

package/src/wirings/queue/queue.types.ts

@@ -1,6 +1,7 @@
 import { CommonWireMeta } from '../../types/core.types.js'
 import { CorePikkuFunctionConfig } from '../../function/functions.types.js'
 import { QueueConfigMapping } from './validate-worker-config.js'
+import { Logger } from '../../services/logger.js'
 
 /**
  * Configuration for queue workers - how jobs are processed
@@ -138,6 +139,15 @@ export interface QueueWorkers {
   /** Configuration mapping for validation */
   configMappings: QueueConfigMapping
 
+  /** Set runtime queue job runner callback and logger */
+  setJobRunner(
+    runJob: (params: {
+      job: QueueJob
+      updateProgress?: (progress: number | string | object) => Promise<void>
+    }) => Promise<void>,
+    logger: Logger
+  ): void
+
   /** Scan state and register all compatible processors */
   registerQueues(): Promise<Record<string, ConfigValidationResult[]>>
 }
@@ -148,7 +158,7 @@ export interface QueueWorkers {
 export type QueueWorkersMeta = Record<
   string,
   CommonWireMeta & {
-    queueName: string
+    name: string
     config?: PikkuWorkerConfig
   }
 >
@@ -163,7 +173,7 @@ export type CoreQueueWorker<
     any
   > = CorePikkuFunctionConfig<any, any, any>,
 > = {
-  queueName: string
+  name: string
   func: PikkuFunctionConfig
   config?: PikkuWorkerConfig
   errors?: string[]

package/src/wirings/rpc/index.ts

@@ -1,2 +1,2 @@
-export { initialize, PikkuRPCService, rpcService } from './rpc-runner.js'
+export { PikkuRPCService, rpcService, RPCNotFoundError } from './rpc-runner.js'
 export type { PikkuRPC, RPCMeta } from './rpc-types.js'