@pikku/core 0.9.11 → 0.10.0

package/src/types/core.types.ts

@@ -1,6 +1,7 @@
 import type { Logger, LogLevel } from '../services/logger.js'
 import { VariablesService } from '../services/variables-service.js'
 import { SchemaService } from '../services/schema-service.js'
+import { JWTService } from '../services/jwt-service.js'
 import { PikkuHTTP } from '../wirings/http/http.types.js'
 import { UserSessionService } from '../services/user-session-service.js'
 import { PikkuChannel } from '../wirings/channel/channel.types.js'
@@ -8,6 +9,7 @@ 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'
+import { PikkuCLI } from '../wirings/cli/cli.types.js'
 
 export enum PikkuWiringTypes {
   http = 'http',
@@ -16,6 +18,7 @@ export enum PikkuWiringTypes {
   rpc = 'rpc',
   queue = 'queue',
   mcp = 'mcp',
+  cli = 'cli',
 }
 
 export interface FunctionServicesMeta {
@@ -23,6 +26,48 @@ export interface FunctionServicesMeta {
   services: string[]
 }
 
+/**
+ * Metadata for middleware at any level
+ * - type: 'http' = HTTP route middleware group (references httpGroup in pikkuState)
+ * - type: 'tag' = Tag-based middleware group (references tagGroup in pikkuState)
+ * - type: 'wire' = Wire-level individual middleware
+ */
+export type MiddlewareMetadata =
+  | {
+      type: 'http'
+      route: string // Route pattern (e.g., '*' for all, '/api/*' for specific)
+    }
+  | {
+      type: 'tag'
+      tag: string // Tag name
+    }
+  | {
+      type: 'wire'
+      name: string
+      inline?: boolean // true if inline middleware
+    }
+
+/**
+ * Metadata for permissions at any level
+ * - type: 'http' = HTTP route permission group (references httpGroup in pikkuState)
+ * - type: 'tag' = Tag-based permission group (references tagGroup in pikkuState)
+ * - type: 'wire' = Wire-level individual permission
+ */
+export type PermissionMetadata =
+  | {
+      type: 'http'
+      route: string // Route pattern (e.g., '*' for all, '/api/*' for specific)
+    }
+  | {
+      type: 'tag'
+      tag: string // Tag name
+    }
+  | {
+      type: 'wire'
+      name: string
+      inline?: boolean // true if inline permission
+    }
+
 export type FunctionRuntimeMeta = {
   pikkuFuncName: string
   inputSchemaName: string | null
@@ -39,6 +84,8 @@ export type FunctionMeta = FunctionRuntimeMeta &
     tags: string[]
     docs: PikkuDocs
     isDirectFunction: boolean // true if it's pikkuFunc(fn), false if it's pikkuFunc({ func: fn })
+    middleware: MiddlewareMetadata[] // Function-level middleware
+    permissions: PermissionMetadata[] // Function-level permissions
   }>
 
 export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>
@@ -103,6 +150,8 @@ export interface CoreUserSession {}
 export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
   /** The schema library used to validate data */
   schema?: SchemaService
+  /** The JWT service used to encode and decode tokens */
+  jwt?: JWTService
   /** The core configuration for the application. */
   config: Config
   /** The logger used by the application. */
@@ -121,6 +170,7 @@ export type PikkuInteraction<In = unknown, Out = unknown> = Partial<{
   channel: PikkuChannel<unknown, Out>
   scheduledTask: PikkuScheduledTask
   queue: PikkuQueue
+  cli: PikkuCLI
 }>
 
 /**
@@ -137,16 +187,103 @@ export type CorePikkuMiddleware<
   next: () => Promise<void>
 ) => Promise<void>
 
+/**
+ * Configuration object for creating middleware with metadata
+ *
+ * @template SingletonServices - The singleton services type
+ * @template UserSession - The user session type
+ */
+export type CorePikkuMiddlewareConfig<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = {
+  /** The middleware function */
+  func: CorePikkuMiddleware<SingletonServices, UserSession>
+  /** Optional human-readable name for the middleware */
+  name?: string
+  /** Optional description of what the middleware does */
+  description?: string
+}
+
+/**
+ * A factory function that takes input and returns middleware
+ * Used when middleware needs configuration/input parameters
+ */
+export type CorePikkuMiddlewareFactory<
+  In = any,
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = (input: In) => CorePikkuMiddleware<SingletonServices, UserSession>
+
+/**
+ * A group of middleware (combination of regular middleware and factories)
+ * Used with addMiddleware() and addHTTPMiddleware() to group related middleware together
+ */
+export type CorePikkuMiddlewareGroup<
+  SingletonServices extends CoreSingletonServices = CoreSingletonServices,
+  UserSession extends CoreUserSession = CoreUserSession,
+> = Array<
+  | CorePikkuMiddleware<SingletonServices, UserSession>
+  | CorePikkuMiddlewareFactory<any, SingletonServices, UserSession>
+>
+
 /**
  * Factory function for creating middleware with tree-shaking support
+ * Supports both direct function and configuration object syntax
+ *
+ * @example
+ * ```typescript
+ * // Direct function syntax
+ * export const logMiddleware = pikkuMiddleware(
+ *   async ({ logger }, _interaction, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * )
+ *
+ * // Configuration object syntax with metadata
+ * export const logMiddleware = pikkuMiddleware({
+ *   name: 'Request Logger',
+ *   description: 'Logs request information',
+ *   func: async ({ logger }, _interaction, next) => {
+ *     logger.info('Request started')
+ *     await next()
+ *   }
+ * })
+ * ```
  */
 export const pikkuMiddleware = <
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   UserSession extends CoreUserSession = CoreUserSession,
 >(
-  middleware: CorePikkuMiddleware<SingletonServices, UserSession>
+  middleware:
+    | CorePikkuMiddleware<SingletonServices, UserSession>
+    | CorePikkuMiddlewareConfig<SingletonServices, UserSession>
 ): CorePikkuMiddleware<SingletonServices, UserSession> => {
-  return middleware
+  return typeof middleware === 'function' ? middleware : middleware.func
+}
+
+/**
+ * Factory function for creating middleware factories
+ * Use this when your middleware needs configuration/input parameters
+ *
+ * @example
+ * ```typescript
+ * export const logMiddleware = pikkuMiddlewareFactory<LogOptions>(({
+ *   message,
+ *   level = 'info'
+ * }) => {
+ *   return pikkuMiddleware(async ({ logger }, _interaction, next) => {
+ *     logger[level](message)
+ *     await next()
+ *   })
+ * })
+ * ```
+ */
+export const pikkuMiddlewareFactory = <In = any>(
+  factory: CorePikkuMiddlewareFactory<In>
+): CorePikkuMiddlewareFactory<In> => {
+  return factory
 }
 
 /**
@@ -193,9 +330,10 @@ export type CreateSessionServices<
 /**
  * Defines a function type for creating config.
  */
-export type CreateConfig<Config extends CoreConfig> = (
-  variables?: VariablesService
-) => Promise<Config>
+export type CreateConfig<
+  Config extends CoreConfig,
+  RemainingArgs extends any[] = unknown[],
+> = (variables?: VariablesService, ...args: RemainingArgs) => Promise<Config>
 
 /**
  * Represents the documentation for a route, including summary, description, tags, and errors.

package/src/utils.ts

@@ -41,7 +41,7 @@ export const isSerializable = (data: any): boolean => {
 
 const EMPTY_ARRAY = Object.freeze([])
 
-export const freezeDedupe = <T extends Function>(
+export const freezeDedupe = <T>(
   arr?: readonly T[] | T[] | undefined
 ): readonly T[] => {
   if (!arr || arr.length === 0) return EMPTY_ARRAY

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

@@ -61,7 +61,6 @@ const validateAuth = (
 
 export const processMessageHandlers = (
   services: CoreServices,
-  session: CoreUserSession | undefined,
   channelConfig: CoreChannel<any, any>,
   channelHandler: PikkuChannelHandler
 ) => {
@@ -71,7 +70,6 @@ export const processMessageHandlers = (
   const processMessage = async (
     data: JSONValue,
     onMessage: any,
-    session: CoreUserSession | undefined,
     routingProperty?: string,
     routerValue?: string
   ): Promise<unknown> => {
@@ -87,16 +85,16 @@ export const processMessageHandlers = (
       return
     }
 
-    const { pikkuFuncName } = getRouteMeta(
-      channelConfig.name,
-      routingProperty,
-      routerValue
-    )
+    const {
+      pikkuFuncName,
+      middleware: inheritedMiddleware,
+      permissions: inheritedPermissions,
+    } = getRouteMeta(channelConfig.name, routingProperty, routerValue)
 
-    const permissions =
-      typeof onMessage === 'function' ? {} : onMessage.permissions
+    const wirePermissions =
+      typeof onMessage === 'function' ? undefined : onMessage.permissions
 
-    const middleware =
+    const wireMiddleware =
       typeof onMessage === 'function' ? [] : onMessage.middleware
 
     return await runPikkuFunc(
@@ -104,15 +102,19 @@ export const processMessageHandlers = (
       channelConfig.name,
       pikkuFuncName,
       {
+        singletonServices: services,
         getAllServices: () => ({
           ...services,
           channel: channelHandler.getChannel(),
         }),
-        data,
-        session,
-        permissions,
-        middleware,
+        data: () => data,
+        userSession: services.userSession,
+        inheritedMiddleware,
+        wireMiddleware,
+        inheritedPermissions,
+        wirePermissions,
         tags: channelConfig.tags,
+        interaction: { channel: channelHandler.getChannel() },
       }
     )
   }
@@ -133,7 +135,6 @@ export const processMessageHandlers = (
             result = await processMessage(
               messageData,
               routes[routerValue],
-              session,
               routingProperty,
               routerValue
             )
@@ -144,11 +145,7 @@ export const processMessageHandlers = (
         // Default handler if no routes matched but json data was parsed
         if (!processed && channelConfig.onMessage) {
           processed = true
-          result = await processMessage(
-            messageData,
-            channelConfig.onMessage,
-            session
-          )
+          result = await processMessage(messageData, channelConfig.onMessage)
         }
       } catch (error) {
         // Most likely a json error.. ignore
@@ -158,7 +155,7 @@ export const processMessageHandlers = (
     // Default handler if no routes matched and json data wasn't parsed
     if (!processed && channelConfig.onMessage) {
       processed = true
-      result = await processMessage(rawData, channelConfig.onMessage, session)
+      result = await processMessage(rawData, channelConfig.onMessage)
     }
 
     if (!processed) {

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

@@ -1,5 +1,6 @@
 import { NotFoundError } from '../../errors/errors.js'
 import { addFunction } from '../../function/function-runner.js'
+import { CorePikkuPermission } from '../../function/functions.types.js'
 import { pikkuState } from '../../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js'
 import { UserSessionService } from '../../services/user-session-service.js'
@@ -19,11 +20,17 @@ import {
 export const wireChannel = <
   In,
   Channel extends string,
+  PikkuPermission extends CorePikkuPermission<In>,
+  PikkuMiddleware extends CorePikkuMiddleware,
   ChannelFunction,
-  ChannelFunctionSessionless,
-  PikkuPermission,
 >(
-  channel: CoreChannel<In, Channel, ChannelFunction, PikkuPermission>
+  channel: CoreChannel<
+    In,
+    Channel,
+    PikkuPermission,
+    PikkuMiddleware,
+    ChannelFunction
+  >
 ) => {
   // Get the channel metadata
   const channelsMeta = pikkuState('channel', 'meta')
@@ -36,27 +43,20 @@ export const wireChannel = <
 
   // Register onConnect function if provided
   if (channel.onConnect && channelMeta.connect) {
-    addFunction(channelMeta.connect.pikkuFuncName, {
-      func: channel.onConnect as any,
-    })
+    addFunction(channelMeta.connect.pikkuFuncName, channel.onConnect as any)
   }
 
   // Register onDisconnect function if provided
   if (channel.onDisconnect && channelMeta.disconnect) {
-    addFunction(channelMeta.disconnect.pikkuFuncName, {
-      func: channel.onDisconnect,
-    })
+    addFunction(
+      channelMeta.disconnect.pikkuFuncName,
+      channel.onDisconnect as any
+    )
   }
 
   // Register onMessage function if provided
   if (channel.onMessage && channelMeta.message?.pikkuFuncName) {
-    const messageFunc =
-      typeof channel.onMessage === 'function'
-        ? channel.onMessage
-        : channel.onMessage.func
-    addFunction(channelMeta.message.pikkuFuncName, {
-      func: messageFunc,
-    })
+    addFunction(channelMeta.message.pikkuFuncName, channel.onMessage as any)
   }
 
   // Register functions in onMessageWiring
@@ -71,18 +71,8 @@ export const wireChannel = <
         const wiringMeta = channelWirings[wiringKey]
         if (!wiringMeta) return
 
-        // Extract the function from the handler
-        const wiringFunc =
-          typeof handler === 'function'
-            ? { func: handler }
-            : {
-                func: handler.func,
-                auth: handler.auth,
-                permissions: handler.permissions,
-              }
-
         // Register the function using the pikku name from metadata
-        addFunction(wiringMeta.pikkuFuncName, wiringFunc)
+        addFunction(wiringMeta.pikkuFuncName, handler as any)
       })
     })
   }
@@ -117,7 +107,6 @@ const getMatchingChannelConfig = (request: string) => {
     channelConfig,
     schemaName: channelMeta.input,
     meta: channelMeta,
-    httpMiddleware: matchedPath.middleware,
   }
 }
 
@@ -133,7 +122,6 @@ export const openChannel = async ({
   openingData: unknown
   channelConfig: CoreChannel<unknown, any>
   meta: ChannelMeta
-  httpMiddleware: CorePikkuMiddleware[] | undefined
 }> => {
   const matchingChannel = getMatchingChannelConfig(route)
   if (!matchingChannel) {
@@ -141,8 +129,7 @@ export const openChannel = async ({
     throw new NotFoundError(`Channel not found: ${route}`)
   }
 
-  const { params, channelConfig, schemaName, meta, httpMiddleware } =
-    matchingChannel
+  const { params, channelConfig, schemaName, meta } = matchingChannel
 
   const requiresSession = channelConfig.auth !== false
   request?.setParams(params)
@@ -165,5 +152,5 @@ export const openChannel = async ({
     )
   }
 
-  return { openingData, channelConfig, meta, httpMiddleware }
+  return { openingData, channelConfig, meta }
 }

package/src/wirings/channel/channel.types.ts

@@ -9,9 +9,13 @@ import {
   CoreSingletonServices,
   CreateSessionServices,
   CorePikkuMiddleware,
+  MiddlewareMetadata,
+  PermissionMetadata,
 } from '../../types/core.types.js'
 import {
+  CorePermissionGroup,
   CorePikkuFunction,
+  CorePikkuFunctionConfig,
   CorePikkuFunctionSessionless,
   CorePikkuPermission,
 } from '../../function/functions.types.js'
@@ -35,6 +39,8 @@ export type RunChannelParams<ChannelData> = {
 export interface ChannelMessageMeta {
   pikkuFuncName: string
   docs?: PikkuDocs
+  middleware?: MiddlewareMetadata[]
+  permissions?: PermissionMetadata[]
 }
 
 export interface ChannelMeta {
@@ -50,6 +56,8 @@ export interface ChannelMeta {
   messageWirings: Record<string, Record<string, ChannelMessageMeta>>
   docs?: PikkuDocs
   tags?: string[]
+  middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
+  permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
 }
 
 export type ChannelsMeta = Record<string, ChannelMeta>
@@ -57,28 +65,32 @@ export type ChannelsMeta = Record<string, ChannelMeta>
 export type CoreChannel<
   ChannelData,
   Channel extends string,
-  ChannelConnect =
+  ChannelConnect = CorePikkuFunctionConfig<
     | CorePikkuFunction<void, unknown, ChannelData>
     | CorePikkuFunctionSessionless<void, unknown, ChannelData>,
-  ChannelDisconnect =
+    CorePikkuPermission<void>,
+    CorePikkuMiddleware
+  >,
+  ChannelDisconnect = CorePikkuFunctionConfig<
     | CorePikkuFunction<void, void, ChannelData>
     | CorePikkuFunctionSessionless<void, void, ChannelData>,
-  ChannelFunctionMessage =
+    CorePikkuPermission<void>,
+    CorePikkuMiddleware
+  >,
+  ChannelFunctionMessage = CorePikkuFunctionConfig<
     | CorePikkuFunction<unknown, unknown, ChannelData>
     | CorePikkuFunctionSessionless<unknown, unknown, ChannelData>,
+    CorePikkuPermission<unknown>,
+    CorePikkuMiddleware
+  >,
   PikkuPermission = CorePikkuPermission<ChannelData>,
+  PikkuMiddleware = CorePikkuMiddleware,
 > = {
   name: string
   route: Channel
   onConnect?: ChannelConnect
   onDisconnect?: ChannelDisconnect
-  onMessage?:
-    | {
-        func: ChannelFunctionMessage
-        permissions?: Record<string, PikkuPermission[] | PikkuPermission>
-        auth?: boolean
-      }
-    | ChannelFunctionMessage
+  onMessage?: ChannelFunctionMessage
   onMessageWiring?: Record<
     string,
     Record<
@@ -86,13 +98,14 @@ export type CoreChannel<
       | ChannelFunctionMessage
       | {
           func: ChannelFunctionMessage
-          permissions?: Record<string, PikkuPermission[] | PikkuPermission>
+          permissions?: CorePermissionGroup<PikkuPermission>
           auth?: boolean
+          middleware?: PikkuMiddleware[]
         }
     >
   >
-  middleware?: CorePikkuMiddleware[]
-  permissions?: Record<string, PikkuPermission[] | PikkuPermission>
+  middleware?: PikkuMiddleware[]
+  permissions?: CorePermissionGroup<PikkuPermission>
   auth?: boolean
   docs?: Partial<{
     description: string
@@ -103,16 +116,16 @@ export type CoreChannel<
   tags?: string[]
 }
 
-export interface PikkuChannel<OpeningData, Out> {
+export interface PikkuChannel<OpeningData, out Out> {
   // The channel identifier
   channelId: string
   // The data the channel was created with. This could be query parameters
   // or parameters in the url.
   openingData: OpeningData
   // The data to send. This will fail is the stream has been closed.
-  send: (data: Out, isBinary?: boolean) => Promise<void> | void
+  send(data: Out, isBinary?: boolean): Promise<void> | void
   // This will close the channel.
-  close: () => Promise<void> | void
+  close(): Promise<void> | void
   // The current state of the channel
   state: 'initial' | 'open' | 'closed'
 }

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

@@ -8,7 +8,11 @@ import {
   RunChannelParams,
 } from '../channel.types.js'
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
-import { PikkuWiringTypes, SessionServices } from '../../../types/core.types.js'
+import {
+  PikkuInteraction,
+  PikkuWiringTypes,
+  SessionServices,
+} from '../../../types/core.types.js'
 import { handleHTTPError } from '../../../handle-error.js'
 import { combineMiddleware, runMiddleware } from '../../../middleware-runner.js'
 import { PikkuUserSessionService } from '../../../services/user-session-service.js'
@@ -42,9 +46,9 @@ export const runLocalChannel = async ({
     route = http?.request?.path()
   }
 
-  let openingData, channelConfig, meta, httpMiddleware
+  let openingData, channelConfig, meta
   try {
-    ;({ openingData, channelConfig, meta, httpMiddleware } = await openChannel({
+    ;({ openingData, channelConfig, meta } = await openChannel({
       channelId,
       createSessionServices,
       respondWith404,
@@ -86,17 +90,24 @@ export const runLocalChannel = async ({
         )
       }
 
-      const allServices = rpcService.injectRPCService({
-        ...singletonServices,
-        ...sessionServices,
-        userSession: userSession,
-      })
+      const getAllServices = (channel: any, requiresAuth?: boolean) =>
+        rpcService.injectRPCService(
+          {
+            ...singletonServices,
+            ...sessionServices,
+            userSession,
+          },
+          interaction,
+          requiresAuth
+        )
+
+      const interaction: PikkuInteraction = { channel }
 
       channelHandler.registerOnOpen(() => {
         if (channelConfig.onConnect && meta.connect) {
           runPikkuFuncDirectly(
             meta.connect.pikkuFuncName,
-            { ...allServices, channel },
+            getAllServices(channel, false),
             openingData
           )
         }
@@ -106,10 +117,11 @@ export const runLocalChannel = async ({
         if (channelConfig.onDisconnect && meta.disconnect) {
           runPikkuFuncDirectly(
             meta.disconnect.pikkuFuncName,
-            { ...allServices, channel },
+            getAllServices(channel, false),
             openingData
           )
         }
+
         if (sessionServices) {
           await closeSessionServices(singletonServices.logger, sessionServices)
         }
@@ -117,8 +129,7 @@ export const runLocalChannel = async ({
 
       channelHandler.registerOnMessage(
         processMessageHandlers(
-          allServices,
-          session,
+          getAllServices(channel),
           channelConfig as any,
           channelHandler
         )
@@ -147,9 +158,8 @@ export const runLocalChannel = async ({
     },
     { http },
     combineMiddleware(PikkuWiringTypes.channel, channelConfig.name, {
-      wiringMiddleware: channelConfig.middleware,
-      wiringTags: channelConfig.tags,
-      httpMiddleware,
+      wireInheritedMiddleware: meta.middleware,
+      wireMiddleware: channelConfig.middleware,
     }),
     main
   )