@pikku/core 0.9.3 → 0.9.5

package/src/types/core.types.ts

@@ -6,6 +6,8 @@ import { UserSessionService } from '../services/user-session-service.js'
 import { PikkuChannel } from '../wirings/channel/channel.types.js'
 import { PikkuRPC } from '../wirings/rpc/rpc-types.js'
 import { PikkuMCP } from '../wirings/mcp/mcp.types.js'
+import { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js'
+import { PikkuQueue } from '../wirings/queue/queue.types.js'
 
 export enum PikkuWiringTypes {
   http = 'http',
@@ -112,11 +114,14 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
 /**
  * Represents different forms of interaction within Pikku and the outside world.
  */
-export interface PikkuInteraction {
-  http?: PikkuHTTP
-  mcp?: PikkuMCP
-  rpc?: PikkuRPC
-}
+export type PikkuInteraction<In = unknown, Out = unknown> = Partial<{
+  http: PikkuHTTP<In>
+  mcp: PikkuMCP
+  rpc: PikkuRPC
+  channel: PikkuChannel<unknown, Out>
+  scheduledTask: PikkuScheduledTask
+  queue: PikkuQueue
+}>
 
 /**
  * A function that can wrap an interaction and be called before or after

package/src/wirings/channel/channel-handler.ts

@@ -107,6 +107,7 @@ export const processMessageHandlers = (
       session,
       permissions,
       middleware,
+      tags: channelConfig.tags,
     })
   }
 

package/src/wirings/channel/local/local-channel-runner.ts

@@ -10,7 +10,7 @@ import {
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
 import { SessionServices } from '../../../types/core.types.js'
 import { handleHTTPError } from '../../../handle-error.js'
-import { runMiddleware } from '../../../middleware-runner.js'
+import { combineMiddleware, runMiddleware } from '../../../middleware-runner.js'
 import { PikkuUserSessionService } from '../../../services/user-session-service.js'
 import { PikkuHTTP } from '../../http/http.types.js'
 import { runPikkuFuncDirectly } from '../../../function/function-runner.js'
@@ -42,21 +42,35 @@ export const runLocalChannel = async ({
     route = http?.request?.path()
   }
 
+  let openingData, channelConfig, meta
+  try {
+    ;({ openingData, channelConfig, meta } = await openChannel({
+      channelId,
+      createSessionServices,
+      respondWith404,
+      request,
+      response,
+      route,
+      singletonServices,
+      skipUserSession,
+      coerceDataFromSchema,
+      userSession,
+    }))
+  } catch (e) {
+    handleHTTPError(
+      e,
+      http,
+      channelId,
+      singletonServices.logger,
+      logWarningsForStatusCodes,
+      respondWith404,
+      bubbleErrors
+    )
+    return
+  }
+
   const main = async () => {
     try {
-      const { openingData, channelConfig, meta } = await openChannel({
-        channelId,
-        createSessionServices,
-        respondWith404,
-        request,
-        response,
-        route,
-        singletonServices,
-        skipUserSession,
-        coerceDataFromSchema,
-        userSession,
-      })
-
       channelHandler = new PikkuLocalChannelHandler(
         channelId,
         channelConfig.name,
@@ -67,7 +81,7 @@ export const runLocalChannel = async ({
       if (createSessionServices) {
         sessionServices = await createSessionServices(
           singletonServices,
-          { http },
+          { http, channel },
           session
         )
       }
@@ -132,7 +146,10 @@ export const runLocalChannel = async ({
       userSession,
     },
     { http },
-    route.middleware || [],
+    combineMiddleware({
+      wiringMiddleware: channelConfig.middleware,
+      wiringTags: channelConfig.tags,
+    }),
     main
   )
 

package/src/wirings/channel/serverless/serverless-channel-runner.ts

@@ -12,7 +12,7 @@ import { createHTTPInteraction } from '../../http/http-runner.js'
 import { ChannelStore } from '../channel-store.js'
 import { handleHTTPError } from '../../../handle-error.js'
 import { PikkuUserSessionService } from '../../../services/user-session-service.js'
-import { runMiddleware } from '../../../middleware-runner.js'
+import { combineMiddleware, runMiddleware } from '../../../middleware-runner.js'
 import { pikkuState } from '../../../pikku-state.js'
 import { PikkuFetchHTTPRequest } from '../../http/pikku-fetch-http-request.js'
 import { PikkuHTTP } from '../../http/http.types.js'
@@ -146,7 +146,10 @@ export const runChannelConnect = async ({
       userSession,
     },
     { http },
-    channelConfig.middleware || [],
+    combineMiddleware({
+      wiringMiddleware: channelConfig.middleware,
+      wiringTags: channelConfig.tags,
+    }),
     main
   )
 }

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

@@ -24,7 +24,7 @@ import {
   PikkuUserSessionService,
   UserSessionService,
 } from '../../services/user-session-service.js'
-import { runMiddleware } from '../../middleware-runner.js'
+import { combineMiddleware, runMiddleware } from '../../middleware-runner.js'
 import { handleHTTPError } from '../../handle-error.js'
 import { pikkuState } from '../../pikku-state.js'
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
@@ -213,7 +213,16 @@ export const createHTTPInteraction = (
 /**
  * Validates the input data and executes the route handler with associated middleware.
  *
- * This function is the central execution point for a route. It performs these steps:
+ * NOTE: HTTP wiring handles middleware differently from other wirings (RPC, MCP, Queue, etc.)
+ * because HTTP needs to:
+ * 1. Check session early for performance (before expensive body parsing)
+ * 2. Handle HTTP-specific concerns (headers, cookies, SSE setup)
+ * 3. Process middleware that may set up authentication/session state
+ *
+ * Other wirings (RPC/MCP/Queue/Scheduler) simply pass middleware/permissions/auth
+ * directly to runPikkuFunc without processing them.
+ *
+ * This function performs these steps:
  *  1. Sets URL parameters on the request.
  *  2. Validates the user session if required.
  *  3. Creates session-specific services.
@@ -344,6 +353,7 @@ const executeRouteWithMiddleware = async (
       data,
       permissions: route.permissions,
       coerceDataFromSchema: options.coerceDataFromSchema,
+      tags: route.tags,
     })
 
     // Respond with either a binary or JSON response based on configuration
@@ -358,11 +368,19 @@ const executeRouteWithMiddleware = async (
     // http?.response?.end()
   }
 
+  // Get function config for middleware and tags
+  const funcConfig = pikkuState('function', 'functions').get(meta.pikkuFuncName)
+
   // Execute middleware, then run the main logic
   await runMiddleware(
     { ...singletonServices, userSession },
     { http },
-    middleware,
+    combineMiddleware({
+      wiringMiddleware: middleware,
+      wiringTags: route.tags,
+      funcMiddleware: funcConfig?.middleware,
+      funcTags: funcConfig?.tags,
+    }),
     runMain
   )
 

package/src/wirings/http/http.types.ts

@@ -72,6 +72,7 @@ export type CoreHTTPFunction = {
   eventChannel?: false
   returnsJSON?: false
   timeout?: number
+  tags?: string[]
   docs?: Partial<{
     description: string
     response: string
@@ -82,8 +83,8 @@ export type CoreHTTPFunction = {
 /**
  * Represents a http interaction within Pikku, including a request and response.
  */
-export interface PikkuHTTP {
-  request?: PikkuHTTPRequest
+export interface PikkuHTTP<In = unknown> {
+  request?: PikkuHTTPRequest<In>
   response?: PikkuHTTPResponse
 }
 
@@ -233,7 +234,7 @@ export interface PikkuHTTPRequest<In = unknown> {
   query(): PikkuQuery
 }
 
-export interface PikkuHTTPResponse {
+export interface PikkuHTTPResponse<Out = unknown> {
   status(code: number): this
   cookie(name: string, value: string | null, options: SerializeOptions): this
   header(name: string, value: string | string[]): this
@@ -247,7 +248,7 @@ export interface PikkuHTTPResponse {
       | URLSearchParams
       | ReadableStream
   ): this
-  json(data: unknown): this
+  json(data: Out): this
   redirect(location: string, status?: number): this
   close?: () => void
   setMode?: (mode: 'stream') => void

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 { combineMiddleware, runMiddleware } from '../../middleware-runner.js'
 
 export class MCPError extends Error {
   constructor(public readonly error: JsonRpcErrorResponse) {
@@ -228,31 +229,50 @@ 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,
-    })
+    const funcConfig = pikkuState('function', 'functions').get(pikkuFuncName!)
+    await runMiddleware(
+      singletonServices,
+      { mcp: interaction },
+      combineMiddleware({
+        wiringMiddleware: mcp.middleware,
+        wiringTags: mcp.tags,
+        funcMiddleware: funcConfig?.middleware,
+        funcTags: funcConfig?.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 { combineMiddleware, 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
  */
@@ -72,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
 
@@ -85,26 +108,76 @@ 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 function config for middleware and tags
+    const funcConfig = pikkuState('function', 'functions').get(
+      processorMeta.pikkuFuncName
     )
+
+    // Get middleware for tags and combine with queue-specific middleware
+    await runMiddleware(
+      singletonServices,
+      { queue },
+      combineMiddleware({
+        wiringMiddleware: queueWorker.middleware,
+        wiringTags: queueWorker.tags,
+        funcMiddleware: funcConfig?.middleware,
+        funcTags: funcConfig?.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>
 }