@pikku/core 0.9.2 → 0.9.4

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

@@ -20,6 +20,7 @@ import { pikkuState } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { rpcService } from '../rpc/rpc-runner.js'
 import { BadRequestError, NotFoundError } from '../../errors/errors.js'
+import { addMiddlewareForTags, runMiddleware } from '../../middleware-runner.js'
 
 export class MCPError extends Error {
   constructor(public readonly error: JsonRpcErrorResponse) {
@@ -56,9 +57,7 @@ export const wireMCPResource = <
   if (!mcpResourceMeta) {
     throw new Error(`MCP resource metadata not found for '${mcpResource.uri}'`)
   }
-  addFunction(mcpResourceMeta.pikkuFuncName, {
-    func: mcpResource.func,
-  })
+  addFunction(mcpResourceMeta.pikkuFuncName, mcpResource.func)
   const resources = pikkuState('mcp', 'resources')
   if (resources.has(mcpResource.uri)) {
     throw new Error(`MCP resource already exists: ${mcpResource.uri}`)
@@ -76,9 +75,7 @@ export const wireMCPTool = <
   if (!mcpToolMeta) {
     throw new Error(`MCP tool metadata not found for '${mcpTool.name}'`)
   }
-  addFunction(mcpToolMeta.pikkuFuncName, {
-    func: mcpTool.func,
-  })
+  addFunction(mcpToolMeta.pikkuFuncName, mcpTool.func as any)
   const tools = pikkuState('mcp', 'tools')
   if (tools.has(mcpTool.name)) {
     throw new Error(`MCP tool already exists: ${mcpTool.name}`)
@@ -96,9 +93,7 @@ export const wireMCPPrompt = <
   if (!mcpPromptMeta) {
     throw new Error(`MCP prompt metadata not found for '${mcpPrompt.name}'`)
   }
-  addFunction(mcpPromptMeta.pikkuFuncName, {
-    func: mcpPrompt.func,
-  })
+  addFunction(mcpPromptMeta.pikkuFuncName, mcpPrompt.func as any)
   const prompts = pikkuState('mcp', 'prompts')
   if (prompts.has(mcpPrompt.name)) {
     throw new Error(`MCP prompt already exists: ${mcpPrompt.name}`)
@@ -234,31 +229,45 @@ async function runMCPPikkuFunc(
 
     singletonServices.logger.debug(`Running MCP ${type}: ${name}`)
 
-    const getAllServices = async () => {
-      if (createSessionServices) {
-        const services = await createSessionServices(
-          singletonServices,
-          { mcp: interaction },
-          session
-        )
-        sessionServices = services
+    let result: any
+
+    // Main MCP execution logic wrapped for middleware handling
+    const runMain = async () => {
+      const getAllServices = async () => {
+        if (createSessionServices) {
+          const services = await createSessionServices(
+            singletonServices,
+            { mcp: interaction },
+            session
+          )
+          sessionServices = services
+          return rpcService.injectRPCService({
+            ...singletonServices,
+            ...services,
+            mcp: interaction,
+          })
+        }
         return rpcService.injectRPCService({
           ...singletonServices,
-          ...services,
           mcp: interaction,
         })
       }
-      return rpcService.injectRPCService({
-        ...singletonServices,
-        mcp: interaction,
+
+      result = await runPikkuFunc(pikkuFuncName, {
+        getAllServices,
+        session,
+        data: request.params,
+        tags: mcp.tags,
       })
     }
 
-    const result = await runPikkuFunc(pikkuFuncName, {
-      getAllServices,
-      session,
-      data: request.params,
-    })
+    // Get middleware for tags and run middleware
+    await runMiddleware(
+      singletonServices,
+      { mcp: interaction },
+      addMiddlewareForTags(mcp.middleware, mcp.tags),
+      runMain
+    )
 
     return {
       id: request.id,

package/src/wirings/mcp/mcp.types.ts

@@ -1,4 +1,5 @@
 import { CorePikkuFunctionSessionless } from '../../function/functions.types.js'
+import { CorePikkuMiddleware } from '../../types/core.types.js'
 
 export type PikkuMCP<Tools extends string = any> = {
   // elicitInput: <Input>(message: string) => Promise<{ action: string, content: Input }>
@@ -55,6 +56,7 @@ export type MCPPromptMeta = Record<
  */
 export type CoreMCPResource<
   PikkuFunction = CorePikkuFunctionSessionless<any, any>,
+  PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
   uri: string
   title: string
@@ -64,6 +66,7 @@ export type CoreMCPResource<
   streaming?: boolean
   func: PikkuFunction
   tags?: string[]
+  middleware?: PikkuMiddleware[]
 }
 
 /**
@@ -71,6 +74,7 @@ export type CoreMCPResource<
  */
 export type CoreMCPTool<
   PikkuFunction = CorePikkuFunctionSessionless<any, any>,
+  PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
   name: string
   title?: string
@@ -79,6 +83,7 @@ export type CoreMCPTool<
   func: PikkuFunction
   tags?: string[]
   streaming?: boolean
+  middleware?: PikkuMiddleware[]
 }
 
 /**
@@ -86,11 +91,13 @@ export type CoreMCPTool<
  */
 export type CoreMCPPrompt<
   PikkuFunction = CorePikkuFunctionSessionless<any, MCPPromptResponse>,
+  PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
   name: string
   description?: string
   func: PikkuFunction
   tags?: string[]
+  middleware?: PikkuMiddleware[]
 }
 
 export type JsonRpcRequest = {

package/src/wirings/queue/index.ts

@@ -7,6 +7,8 @@ export {
   runQueueJob,
   getQueueWorkers,
   removeQueueWorker,
+  QueueJobDiscardedError,
+  QueueJobFailedError,
 } from './queue-runner.js'
 
 // Configuration validation

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

@@ -1,19 +1,40 @@
 import type { CoreServices } from '../../types/core.types.js'
-import type { CoreQueueWorker, QueueJob } from './queue.types.js'
+import type { CoreQueueWorker, QueueJob, PikkuQueue } from './queue.types.js'
 import type { CorePikkuFunctionSessionless } from '../../function/functions.types.js'
-import { getErrorResponse } from '../../errors/error-handler.js'
+import { getErrorResponse, PikkuError } from '../../errors/error-handler.js'
 import { pikkuState } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { CreateSessionServices } from '../../types/core.types.js'
+import { addMiddlewareForTags, runMiddleware } from '../../middleware-runner.js'
 
 /**
  * Error class for queue processor not found
  */
-class QueueWorkerNotFoundError extends Error {
+class QueueWorkerNotFoundError extends PikkuError {
   constructor(name: string) {
     super(`Queue processor not found: ${name}`)
   }
 }
+
+/**
+ * Error class for when a queue job is explicitly failed
+ */
+export class QueueJobFailedError extends PikkuError {
+  constructor(jobId: string, reason?: string) {
+    super(`Queue job ${jobId} failed${reason ? `: ${reason}` : ''}`)
+    this.name = 'QueueJobFailedError'
+  }
+}
+
+/**
+ * Error class for when a queue job is explicitly discarded
+ */
+export class QueueJobDiscardedError extends PikkuError {
+  constructor(jobId: string, reason?: string) {
+    super(`Queue job ${jobId} discarded${reason ? `: ${reason}` : ''}`)
+    this.name = 'QueueJobDiscardedError'
+  }
+}
 /**
  * Add a queue processor to the system
  */
@@ -37,9 +58,7 @@ export const wireQueueWorker = <
   }
 
   // Register the function with pikku
-  addFunction(processorMeta.pikkuFuncName, {
-    func: queueWorker.func,
-  })
+  addFunction(processorMeta.pikkuFuncName, queueWorker.func)
 
   // Store processor definition in state - runtime adapters will pick this up
   const registrations = pikkuState('queue', 'registrations')
@@ -74,10 +93,12 @@ export async function runQueueJob({
   singletonServices,
   createSessionServices,
   job,
+  updateProgress,
 }: {
   singletonServices: CoreServices
   createSessionServices?: CreateSessionServices
   job: QueueJob
+  updateProgress?: (progress: number | string | object) => Promise<void>
 }): Promise<void> {
   const logger = singletonServices.logger
 
@@ -87,26 +108,66 @@ export async function runQueueJob({
     throw new Error(`Processor metadata not found for: ${job.queueName}`)
   }
 
+  // Get the queue worker registration to access middleware
+  const registrations = pikkuState('queue', 'registrations')
+  const queueWorker = registrations.get(job.queueName)
+  if (!queueWorker) {
+    throw new Error(`Queue worker registration not found for: ${job.queueName}`)
+  }
+
+  // Create the queue interaction object
+  const queue: PikkuQueue = {
+    queueName: job.queueName,
+    jobId: job.id,
+    updateProgress:
+      updateProgress ||
+      (async (progress: number | string | object) => {
+        logger.info(`Job ${job.id} progress: ${progress}`)
+        // Default implementation - just log the progress
+      }),
+    fail: async (reason?: string) => {
+      throw new QueueJobFailedError(job.id, reason)
+    },
+    discard: async (reason?: string) => {
+      throw new QueueJobDiscardedError(job.id, reason)
+    },
+  }
+
   try {
     logger.info(`Processing job ${job.id} in queue ${job.queueName}`)
 
-    // Use provided singleton services
-    const getAllServices = () => ({
-      ...singletonServices,
-      ...(createSessionServices
-        ? createSessionServices(singletonServices, {}, undefined)
-        : {}),
-    })
-
-    // Execute the pikku function with the job data
-    const result = await runPikkuFunc(processorMeta.pikkuFuncName, {
-      getAllServices,
-      data: job.data,
-    })
-
-    logger.debug(
-      `Successfully processed job ${job.id} in queue ${job.queueName}`
+    let result: any
+
+    // Main job execution logic wrapped for middleware handling
+    const runMain = async () => {
+      // Use provided singleton services
+      const getAllServices = () => ({
+        ...singletonServices,
+        ...(createSessionServices
+          ? createSessionServices(singletonServices, { queue }, undefined)
+          : {}),
+      })
+
+      // Execute the pikku function with the job data
+      result = await runPikkuFunc(processorMeta.pikkuFuncName, {
+        getAllServices,
+        data: job.data,
+        tags: queueWorker.tags,
+      })
+
+      logger.debug(
+        `Successfully processed job ${job.id} in queue ${job.queueName}`
+      )
+    }
+
+    // Get middleware for tags and combine with queue-specific middleware
+    await runMiddleware(
+      singletonServices,
+      { queue },
+      addMiddlewareForTags(queueWorker.middleware, queueWorker.tags),
+      runMain
     )
+
     return result
   } catch (error: any) {
     logger.error(

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

@@ -1,4 +1,4 @@
-import { PikkuDocs } from '../../types/core.types.js'
+import { PikkuDocs, CorePikkuMiddleware } from '../../types/core.types.js'
 import { CorePikkuFunctionSessionless } from '../../function/functions.types.js'
 import { QueueConfigMapping } from './validate-worker-config.js'
 
@@ -166,6 +166,7 @@ export type queueWorkersMeta = Record<
  */
 export type CoreQueueWorker<
   PikkuFunction = CorePikkuFunctionSessionless<any, any>,
+  PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
   queueName: string
   func: PikkuFunction
@@ -173,4 +174,22 @@ export type CoreQueueWorker<
   docs?: PikkuDocs
   session?: undefined
   tags?: string[]
+  middleware?: PikkuMiddleware[]
+}
+
+/**
+ * Represents a queue interaction object for middleware
+ * Provides information and actions for the current queue job execution
+ */
+export interface PikkuQueue {
+  /** The name of the queue being processed */
+  queueName: string
+  /** The current job ID */
+  jobId: string
+  /** Update job progress (0-100 or custom value) */
+  updateProgress: (progress: number | string | object) => Promise<void>
+  /** Fail the current job with optional reason */
+  fail: (reason?: string) => Promise<void>
+  /** Discard/delete the job without retrying */
+  discard: (reason?: string) => Promise<void>
 }

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

@@ -1,14 +1,14 @@
 import { CoreServices } from '../../types/core.types.js'
 import { runPikkuFunc } from '../../function/function-runner.js'
 import { pikkuState } from '../../pikku-state.js'
-import { RPCMeta } from './rpc-types.js'
+import { ForbiddenError } from '../../errors/errors.js'
 
 // Type for the RPC service configuration
 type RPCServiceConfig = {
   coerceDataFromSchema: boolean
 }
 
-const getRPCMeta = (rpcName: string): RPCMeta => {
+const getPikkuFunctionName = (rpcName: string): string => {
   const rpc = pikkuState('rpc', 'meta')
   const rpcMeta = rpc[rpcName]
   if (!rpcMeta) {
@@ -26,14 +26,25 @@ class ContextAwareRPCService {
     }
   ) {}
 
+  public async rpcExposed(funcName: string, data: any): Promise<any> {
+    const functionMeta = pikkuState('function', 'meta')[funcName]
+    if (!functionMeta) {
+      throw new Error(`Function not found: ${funcName}`)
+    }
+    if (!functionMeta.expose) {
+      throw new ForbiddenError()
+    }
+    return await this.rpc(funcName, data)
+  }
+
   public async rpc<In = any, Out = any>(
     funcName: string,
     data: In
   ): Promise<Out> {
     const session = await this.services.userSession?.get()
     const rpcDepth = this.services.rpc?.depth || 0
-    const rpcMeta = getRPCMeta(funcName)
-    return runPikkuFunc<In, Out>(rpcMeta.pikkuFuncName, {
+    const pikkuFuncName = getPikkuFunctionName(funcName)
+    return runPikkuFunc<In, Out>(pikkuFuncName, {
       getAllServices: () => {
         this.services.rpc = this.services.rpc
           ? ({
@@ -72,6 +83,7 @@ export class PikkuRPCService {
       depth,
       global: false,
       invoke: serviceRPC.rpc.bind(serviceRPC),
+      invokeExposed: serviceRPC.rpc.bind(serviceRPC),
     } as any
     return serviceCopy
   }

package/src/wirings/rpc/rpc-types.ts

@@ -6,7 +6,7 @@ export type PikkuRPC<invoke extends Function = any> = {
 
 export type RPCMeta = {
   pikkuFuncName: string
-  exposed: boolean
+  expose: boolean
 }
 
 /**

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

@@ -4,13 +4,17 @@ import type {
   CoreUserSession,
   CreateSessionServices,
 } from '../../types/core.types.js'
-import type { CoreScheduledTask } from './scheduler.types.js'
+import type {
+  CoreScheduledTask,
+  PikkuScheduledTask,
+} from './scheduler.types.js'
 import type { CorePikkuFunctionSessionless } from '../../function/functions.types.js'
-import { getErrorResponse } from '../../errors/error-handler.js'
+import { getErrorResponse, PikkuError } from '../../errors/error-handler.js'
 import { closeSessionServices } from '../../utils.js'
 import { pikkuState } from '../../pikku-state.js'
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js'
 import { rpcService } from '../rpc/rpc-runner.js'
+import { addMiddlewareForTags, runMiddleware } from '../../middleware-runner.js'
 
 export type RunScheduledTasksParams = {
   name: string
@@ -33,9 +37,7 @@ export const wireScheduler = <
   if (!taskMeta) {
     throw new Error('Task metadata not found')
   }
-  addFunction(taskMeta.pikkuFuncName, {
-    func: scheduledTask.func,
-  })
+  addFunction(taskMeta.pikkuFuncName, scheduledTask.func)
 
   const tasks = pikkuState('scheduler', 'tasks')
   if (tasks.has(scheduledTask.name)) {
@@ -44,55 +46,92 @@ export const wireScheduler = <
   tasks.set(scheduledTask.name, scheduledTask)
 }
 
-class ScheduledTaskNotFoundError extends Error {
+class ScheduledTaskNotFoundError extends PikkuError {
   constructor(title: string) {
     super(`Scheduled task not found: ${title}`)
   }
 }
 
+class ScheduledTaskSkippedError extends PikkuError {
+  constructor(taskName: string, reason?: string) {
+    super(
+      `Scheduled task '${taskName}' was skipped${reason ? `: ${reason}` : ''}`
+    )
+    this.name = 'ScheduledTaskSkippedError'
+  }
+}
+
 export async function runScheduledTask({
   name,
   session,
   singletonServices,
   createSessionServices,
 }: RunScheduledTasksParams): Promise<void> {
-  let sessionServices: CoreServices | undefined
-  try {
-    const task = pikkuState('scheduler', 'tasks').get(name)
-    const meta = pikkuState('scheduler', 'meta')[name]
-    if (!task) {
-      throw new ScheduledTaskNotFoundError(`Scheduled task not found: ${name}`)
-    }
-    if (!meta) {
-      throw new ScheduledTaskNotFoundError(
-        `Scheduled task meta not found: ${name}`
-      )
-    }
+  let sessionServices: any
+  const task = pikkuState('scheduler', 'tasks').get(name)
+  const meta = pikkuState('scheduler', 'meta')[name]
 
+  if (!task) {
+    throw new ScheduledTaskNotFoundError(`Scheduled task not found: ${name}`)
+  }
+  if (!meta) {
+    throw new ScheduledTaskNotFoundError(
+      `Scheduled task meta not found: ${name}`
+    )
+  }
+
+  // Create the scheduled task interaction object
+  const scheduledTask: PikkuScheduledTask = {
+    name,
+    schedule: task.schedule,
+    executionTime: new Date(),
+    skip: (reason?: string) => {
+      throw new ScheduledTaskSkippedError(name, reason)
+    },
+  }
+
+  try {
     singletonServices.logger.info(
       `Running schedule task: ${name} | schedule: ${task.schedule}`
     )
 
-    const getAllServices = async () => {
-      if (createSessionServices) {
-        const sessionServices = await createSessionServices(
-          singletonServices,
-          {},
-          session
-        )
-        return rpcService.injectRPCService({
-          ...singletonServices,
-          ...sessionServices,
-        })
+    let result: any
+
+    // Main scheduled task execution logic wrapped for middleware handling
+    const runMain = async () => {
+      const getAllServices = async () => {
+        if (createSessionServices) {
+          const services = await createSessionServices(
+            singletonServices,
+            { scheduledTask },
+            session
+          )
+          sessionServices = services
+          return rpcService.injectRPCService({
+            ...singletonServices,
+            ...services,
+          })
+        }
+        return singletonServices
       }
-      return singletonServices
+
+      result = await runPikkuFunc(meta.pikkuFuncName, {
+        getAllServices,
+        session,
+        data: undefined,
+        tags: task.tags,
+      })
     }
 
-    return await runPikkuFunc(meta.pikkuFuncName, {
-      getAllServices,
-      session,
-      data: undefined,
-    })
+    // Get middleware for tags and run middleware
+    await runMiddleware(
+      singletonServices,
+      { scheduledTask },
+      addMiddlewareForTags(task.middleware, task.tags),
+      runMain
+    )
+
+    return result
   } catch (e: any) {
     const errorResponse = getErrorResponse(e)
     if (errorResponse != null) {

package/src/wirings/scheduler/scheduler.types.ts

@@ -1,4 +1,8 @@
-import { PikkuDocs, CoreUserSession } from '../../types/core.types.js'
+import {
+  PikkuDocs,
+  CoreUserSession,
+  CorePikkuMiddleware,
+} from '../../types/core.types.js'
 import { CorePikkuFunctionSessionless } from '../../function/functions.types.js'
 
 /**
@@ -22,10 +26,27 @@ export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> =
  */
 export type CoreScheduledTask<
   PikkuFunction = CorePikkuFunctionSessionless<void, void>,
+  PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
   name: string
   schedule: string
   func: PikkuFunction
   docs?: PikkuDocs
   tags?: string[]
+  middleware?: PikkuMiddleware[]
+}
+
+/**
+ * Represents a scheduled task interaction object for middleware
+ * Provides information about the current scheduled task execution
+ */
+export interface PikkuScheduledTask {
+  /** The name of the scheduled task being executed */
+  name: string
+  /** The cron schedule expression */
+  schedule: string
+  /** Current execution timestamp */
+  executionTime: Date
+  /** Skip the current task execution */
+  skip: (reason?: string) => void
 }