@pikku/core 0.9.2 → 0.9.4

package/src/function/function-runner.ts

@@ -1,6 +1,6 @@
 import { ForbiddenError } from '../errors/errors.js'
 import { runMiddleware } from '../middleware-runner.js'
-import { verifyPermissions } from '../permissions.js'
+import { verifyPermissions, getPermissionsForTags } from '../permissions.js'
 import { pikkuState } from '../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
 import {
@@ -10,13 +10,21 @@ import {
 } from '../types/core.types.js'
 import {
   CorePermissionGroup,
+  CorePikkuFunction,
   CorePikkuFunctionConfig,
+  CorePikkuFunctionSessionless,
 } from './functions.types.js'
 
 export const addFunction = (
   funcName: string,
-  funcConfig: CorePikkuFunctionConfig<any, any>
+  funcConfig:
+    | CorePikkuFunctionConfig<any, any>
+    | CorePikkuFunctionSessionless<any, any>
+    | CorePikkuFunction<any, any>
 ) => {
+  if (funcConfig instanceof Function) {
+    funcConfig = { func: funcConfig }
+  }
   pikkuState('function', 'functions').set(funcName, funcConfig)
 }
 
@@ -42,6 +50,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     permissions: transportPermissions,
     middleware: transportMiddleware,
     coerceDataFromSchema,
+    tags = [],
   }: {
     getAllServices: () => Promise<CoreServices> | CoreServices
     data: In
@@ -49,6 +58,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
     permissions?: CorePermissionGroup
     middleware?: CorePikkuMiddleware[]
     coerceDataFromSchema?: boolean
+    tags?: string[]
   }
 ): Promise<Out> => {
   const funcConfig = pikkuState('function', 'functions').get(funcName)
@@ -68,23 +78,39 @@ export const runPikkuFunc = async <In = any, Out = any>(
 
   const allServices = await getAllServices()
 
-  const schemaName = funcMeta.schemaName
-  if (schemaName) {
+  const inputSchemaName = funcMeta.inputSchemaName
+  if (inputSchemaName) {
     // Validate request data against the defined schema, if any
     await validateSchema(
       allServices.logger,
       allServices.schema,
-      schemaName,
+      inputSchemaName,
       data
     )
     // Coerce (top level) query string parameters or date objects if specified by the schema
     if (coerceDataFromSchema) {
-      coerceTopLevelDataFromSchema(schemaName, data)
+      coerceTopLevelDataFromSchema(inputSchemaName, data)
     }
   }
 
   let permissioned = true
-  if (funcConfig.permissions) {
+
+  // Check tagged permissions first - ALL must pass
+  const taggedPermissions = getPermissionsForTags([
+    ...tags,
+    ...(funcConfig.tags || []),
+  ])
+  if (taggedPermissions.length > 0) {
+    const taggedResults = await Promise.all(
+      taggedPermissions.map((permission) =>
+        permission(allServices, data, session)
+      )
+    )
+    permissioned = taggedResults.every((result) => result)
+  }
+
+  // Only check function permissions if tagged permissions passed
+  if (permissioned && funcConfig.permissions) {
     permissioned = await verifyPermissions(
       funcConfig.permissions,
       allServices,
@@ -92,6 +118,7 @@ export const runPikkuFunc = async <In = any, Out = any>(
       session
     )
   }
+
   if (!permissioned && transportPermissions) {
     permissioned = await verifyPermissions(
       transportPermissions,

package/src/function/functions.types.ts

@@ -87,12 +87,14 @@ export type CorePikkuFunctionConfig<
     any,
     any
   > = CorePikkuPermission<any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any> = CorePikkuMiddleware<any>,
 > = {
   name?: string
   expose?: boolean
   func: PikkuFunction
   auth?: boolean
   permissions?: CorePermissionGroup<PikkuPermission>
-  middleware?: CorePikkuMiddleware[]
+  middleware?: PikkuMiddleware[]
+  tags?: string[]
   docs?: PikkuDocs
 }

package/src/index.ts

@@ -21,7 +21,12 @@ export * from './middleware/index.js'
 export * from './time-utils.js'
 export * from './utils.js'
 export { pikkuState } from './pikku-state.js'
-export { runMiddleware } from './middleware-runner.js'
+export {
+  runMiddleware,
+  addMiddleware,
+  addMiddlewareForTags,
+} from './middleware-runner.js'
+export { addPermission, getPermissionsForTags } from './permissions.js'
 export { wireHTTP, addHTTPMiddleware } from './wirings/http/http-runner.js'
 export { wireChannel } from './wirings/channel/channel-runner.js'
 export { wireScheduler } from './wirings/scheduler/scheduler-runner.js'

package/src/middleware-runner.ts

@@ -4,6 +4,7 @@ import {
   PikkuInteraction,
   CorePikkuMiddleware,
 } from './types/core.types.js'
+import { pikkuState } from './pikku-state.js'
 
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
@@ -30,10 +31,13 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   middlewares: Middleware[],
   main?: () => Promise<unknown>
 ): Promise<unknown> => {
+  // Deduplicate middleware using Set to avoid running the same middleware multiple times
+  const uniqueMiddleware = Array.from(new Set(middlewares))
+
   let result: any
   const dispatch = async (index: number): Promise<any> => {
-    if (middlewares && index < middlewares.length) {
-      return await middlewares[index]!(services as any, interaction, () =>
+    if (uniqueMiddleware && index < uniqueMiddleware.length) {
+      return await uniqueMiddleware[index]!(services as any, interaction, () =>
         dispatch(index + 1)
       )
     } else if (main) {
@@ -43,3 +47,107 @@ export const runMiddleware = async <Middleware extends CorePikkuMiddleware>(
   await dispatch(0)
   return result
 }
+
+/**
+ * Adds global middleware for a specific tag.
+ *
+ * This function allows you to register middleware that will be applied to
+ * any wiring (HTTP, Channel, Queue, Scheduler, MCP) that includes the matching tag.
+ *
+ * @template PikkuMiddleware The middleware type.
+ * @param {string} tag - The tag that the middleware should apply to.
+ * @param {PikkuMiddleware[]} middleware - The middleware array to apply for the specified tag.
+ *
+ * @throws {Error} If middleware for the tag already exists.
+ *
+ * @example
+ * ```typescript
+ * // Add admin middleware for admin endpoints
+ * addMiddleware('admin', [adminMiddleware])
+ *
+ * // Add authentication middleware for auth endpoints
+ * addMiddleware('auth', [authMiddleware])
+ *
+ * // Add logging middleware for all API endpoints
+ * addMiddleware('api', [loggingMiddleware])
+ * ```
+ */
+export const addMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
+  tag: string,
+  middleware: PikkuMiddleware[]
+) => {
+  const middlewareStore = pikkuState('misc', 'middleware')
+
+  // Check if tag already exists
+  if (middlewareStore[tag]) {
+    throw new Error(
+      `Middleware for tag '${tag}' already exists. Use a different tag or remove the existing middleware first.`
+    )
+  }
+
+  middlewareStore[tag] = middleware as CorePikkuMiddleware[]
+}
+
+/**
+ * Retrieves middleware for a given set of tags.
+ *
+ * This function looks up all middleware registered for any of the provided tags
+ * and returns them as a flattened array.
+ *
+ * @param {string[]} tags - Array of tags to look up middleware for.
+ * @returns {CorePikkuMiddleware[]} Array of middleware functions that apply to the given tags.
+ *
+ * @example
+ * ```typescript
+ * // Get all middleware for tags 'api' and 'auth'
+ * const middleware = getMiddlewareForTags(['api', 'auth'])
+ * ```
+ */
+export const getMiddlewareForTags = (
+  tags?: string[]
+): CorePikkuMiddleware[] => {
+  if (!tags || tags.length === 0) {
+    return []
+  }
+
+  const middlewareStore = pikkuState('misc', 'middleware')
+  const applicableMiddleware: CorePikkuMiddleware[] = []
+
+  // Collect middleware for all matching tags
+  for (const tag of tags) {
+    const tagMiddleware = middlewareStore[tag]
+    if (tagMiddleware) {
+      applicableMiddleware.push(...tagMiddleware)
+    }
+  }
+
+  return applicableMiddleware
+}
+
+/**
+ * Combines tag-based middleware with wiring-specific middleware.
+ *
+ * This helper function gets middleware for tags and combines it with any
+ * wiring-specific middleware, avoiding the need for manual spreading.
+ *
+ * @param {CorePikkuMiddleware[] | undefined} wiringMiddleware - Wiring-specific middleware.
+ * @param {string[] | undefined} tags - Array of tags to look up middleware for.
+ * @returns {CorePikkuMiddleware[]} Combined array of tag-based and wiring-specific middleware.
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * const taggedMiddleware = getMiddlewareForTags(tags)
+ * const combined = [...taggedMiddleware, ...(middleware || [])]
+ *
+ * // Use:
+ * const combined = addMiddlewareForTags(middleware, tags)
+ * ```
+ */
+export const addMiddlewareForTags = (
+  wiringMiddleware?: CorePikkuMiddleware[],
+  tags?: string[]
+): CorePikkuMiddleware[] => {
+  const taggedMiddleware = getMiddlewareForTags(tags)
+  return [...taggedMiddleware, ...(wiringMiddleware || [])]
+}

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

@@ -11,7 +11,6 @@ import {
 } from './wirings/scheduler/scheduler.types.js'
 import { ErrorDetails, PikkuError } from './errors/error-handler.js'
 import { CorePikkuFunctionConfig } from './function/functions.types.js'
-import { RPCMeta } from './wirings/rpc/rpc-types.js'
 import {
   queueWorkersMeta,
   CoreQueueWorker,
@@ -31,7 +30,7 @@ interface PikkuState {
     functions: Map<string, CorePikkuFunctionConfig<any, any>>
   }
   rpc: {
-    meta: Record<string, RPCMeta>
+    meta: Record<string, string>
     files: Map<
       string,
       {
@@ -68,6 +67,8 @@ interface PikkuState {
   misc: {
     errors: Map<PikkuError, ErrorDetails>
     schemas: Map<string, any>
+    middleware: Record<string, CorePikkuMiddleware[]>
+    permissions: Record<string, any[]>
   }
 }
 
@@ -109,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',
@@ -21,20 +23,28 @@ export interface FunctionServicesMeta {
   services: string[]
 }
 
-export type FunctionsMeta = Record<
-  string,
-  {
-    pikkuFuncName: string
-    name?: string
+export type FunctionRuntimeMeta = {
+  pikkuFuncName: string
+  inputSchemaName: string | null
+  outputSchemaName: string | null
+  expose?: boolean
+}
+
+export type FunctionMeta = FunctionRuntimeMeta &
+  Partial<{
+    name: string
     services: FunctionServicesMeta
-    schemaName: string | null
     inputs: string[] | null
     outputs: string[] | null
-    expose?: boolean
-    tags?: string[]
-    docs?: PikkuDocs
-  }
->
+    tags: string[]
+    docs: PikkuDocs
+    isDirectFunction: boolean // true if it's pikkuFunc(fn), false if it's pikkuFunc({ func: fn })
+  }>
+
+export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>
+export type FunctionsMeta = Record<string, FunctionMeta>
+
+// Optimized runtime metadata with only essential fields
 
 export type MakeRequired<T, K extends keyof T> = Omit<T, K> &
   Required<Pick<T, K>>
@@ -104,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'
@@ -120,9 +120,7 @@ export const wireHTTP = <
   if (!routeMeta) {
     throw new Error('Route metadata not found')
   }
-  addFunction(routeMeta.pikkuFuncName, {
-    func: httpWiring.func,
-  })
+  addFunction(routeMeta.pikkuFuncName, httpWiring.func as any)
   const routes = pikkuState('http', 'routes')
   if (!routes.has(httpWiring.method)) {
     routes.set(httpWiring.method, new Map())
@@ -215,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.
@@ -346,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
@@ -364,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