@pikku/core 0.9.3 → 0.9.4

package/src/permissions.ts

@@ -1,5 +1,6 @@
 import { CoreServices, CoreUserSession } from './types/core.types.js'
 import { CorePermissionGroup } from './function/functions.types.js'
+import { pikkuState } from './pikku-state.js'
 
 /**
  * This function validates permissions by iterating over permission groups and executing the corresponding permission functions. If all functions in at least one group return true, the permission is considered valid.
@@ -41,3 +42,73 @@ export const verifyPermissions = async (
   }
   return false
 }
+
+/**
+ * Adds global permissions for a specific tag.
+ *
+ * This function allows you to register permissions that will be applied to
+ * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
+ *
+ * @param {string} tag - The tag that the permissions should apply to.
+ * @param {any[]} permissions - The permissions array to apply for the specified tag.
+ *
+ * @throws {Error} If permissions for the tag already exist.
+ *
+ * @example
+ * ```typescript
+ * // Add admin permissions for admin endpoints
+ * addPermission('admin', [adminPermission])
+ *
+ * // Add authentication permissions for auth endpoints
+ * addPermission('auth', [authPermission])
+ *
+ * // Add read permissions for all API endpoints
+ * addPermission('api', [readPermission])
+ * ```
+ */
+export const addPermission = (tag: string, permissions: any[]) => {
+  const permissionsStore = pikkuState('misc', 'permissions')
+
+  // Check if tag already exists
+  if (permissionsStore[tag]) {
+    throw new Error(
+      `Permissions for tag '${tag}' already exist. Use a different tag or remove the existing permissions first.`
+    )
+  }
+
+  permissionsStore[tag] = permissions
+}
+
+/**
+ * Retrieves permissions for a given set of tags.
+ *
+ * This function looks up all permissions registered for any of the provided tags
+ * and returns them as a flattened array.
+ *
+ * @param {string[]} tags - Array of tags to look up permissions for.
+ * @returns {any[]} Array of permission functions that apply to the given tags.
+ *
+ * @example
+ * ```typescript
+ * // Get all permissions for tags 'api' and 'auth'
+ * const permissions = getPermissionsForTags(['api', 'auth'])
+ * ```
+ */
+export const getPermissionsForTags = (tags?: string[]): any[] => {
+  if (!tags || tags.length === 0) {
+    return []
+  }
+
+  const permissionsStore = pikkuState('misc', 'permissions')
+  const applicablePermissions: any[] = []
+
+  // Collect permissions for all matching tags
+  for (const tag of new Set(tags)) {
+    const tagPermissions = permissionsStore[tag]
+    if (tagPermissions) {
+      applicablePermissions.push(...tagPermissions)
+    }
+  }
+
+  return applicablePermissions
+}

package/src/pikku-state.ts

@@ -67,6 +67,8 @@ interface PikkuState {
   misc: {
     errors: Map<PikkuError, ErrorDetails>
     schemas: Map<string, any>
+    middleware: Record<string, CorePikkuMiddleware[]>
+    permissions: Record<string, any[]>
   }
 }
 
@@ -108,6 +110,8 @@ export const resetPikkuState = () => {
     misc: {
       errors: globalThis.pikkuState?.misc?.errors || new Map(),
       schemas: globalThis.pikkuState?.misc?.schema || new Map(),
+      middleware: globalThis.pikkuState?.misc?.middleware || {},
+      permissions: globalThis.pikkuState?.misc?.permissions || {},
     },
   } as PikkuState
 }

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,15 @@ 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 = Partial<{
+  http: PikkuHTTP
+  mcp: PikkuMCP
+  rpc: PikkuRPC
+  channel: PikkuChannel<unknown, unknown>
+  scheduledTask: PikkuScheduledTask
+  queue: PikkuQueue
+  s
+}>
 
 /**
  * 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,10 @@ 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 {
+  addMiddlewareForTags,
+  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 +45,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 +84,7 @@ export const runLocalChannel = async ({
       if (createSessionServices) {
         sessionServices = await createSessionServices(
           singletonServices,
-          { http },
+          { http, channel },
           session
         )
       }
@@ -132,7 +149,7 @@ export const runLocalChannel = async ({
       userSession,
     },
     { http },
-    route.middleware || [],
+    addMiddlewareForTags(channelConfig.middleware, channelConfig.tags),
     main
   )
 

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

@@ -12,7 +12,10 @@ 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 {
+  addMiddlewareForTags,
+  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 +149,7 @@ export const runChannelConnect = async ({
       userSession,
     },
     { http },
-    channelConfig.middleware || [],
+    addMiddlewareForTags(channelConfig.middleware, 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 { addMiddlewareForTags, 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
@@ -362,7 +372,7 @@ const executeRouteWithMiddleware = async (
   await runMiddleware(
     { ...singletonServices, userSession },
     { http },
-    middleware,
+    addMiddlewareForTags(middleware, route.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

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) {
@@ -228,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
  */
@@ -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,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>
 }