@pikku/core 0.10.1 → 0.11.0

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

@@ -0,0 +1,80 @@
+import {
+  CoreServices,
+  PikkuWiringTypes,
+  CorePikkuMiddleware,
+} from '../../types/core.types.js'
+import { CoreChannel, ChannelMessageMeta } from './channel.types.js'
+import { combineMiddleware, runMiddleware } from '../../middleware-runner.js'
+import { runPikkuFuncDirectly } from '../../function/function-runner.js'
+
+/**
+ * Runs a channel lifecycle function (onConnect or onDisconnect) with proper middleware handling.
+ *
+ * This function:
+ * 1. Extracts inline middleware from the lifecycle config if present
+ * 2. Combines metadata middleware with inline middleware using combineMiddleware()
+ * 3. Runs the lifecycle function with middleware support
+ *
+ * @param channelConfig - The channel configuration
+ * @param meta - Metadata for the lifecycle function (connect or disconnect)
+ * @param lifecycleConfig - The onConnect or onDisconnect config (can be function or object with middleware)
+ * @param lifecycleType - Type of lifecycle for cache key ('connect' or 'disconnect')
+ * @param services - All services (singleton + session)
+ * @param channel - The channel instance
+ * @param data - Optional data to pass to the lifecycle function (for onConnect)
+ * @returns Promise<unknown> - Result from the lifecycle function (if any)
+ */
+export const runChannelLifecycleWithMiddleware = async ({
+  channelConfig,
+  meta,
+  lifecycleConfig,
+  lifecycleType,
+  services,
+  channel,
+  data,
+}: {
+  channelConfig: CoreChannel<unknown, any>
+  meta: ChannelMessageMeta
+  lifecycleConfig: any
+  lifecycleType: 'connect' | 'disconnect'
+  services: CoreServices
+  channel: any
+  data?: unknown
+}): Promise<unknown> => {
+  // Extract middleware if lifecycle config is an object
+  const lifecycleMiddleware =
+    typeof lifecycleConfig === 'object' && 'middleware' in lifecycleConfig
+      ? (lifecycleConfig.middleware as CorePikkuMiddleware[]) || []
+      : []
+
+  // Use combineMiddleware to properly resolve metadata + inline middleware
+  const allMiddleware = combineMiddleware(
+    PikkuWiringTypes.channel,
+    `${channelConfig.name}:${lifecycleType}`,
+    {
+      wireInheritedMiddleware: meta.middleware,
+      wireMiddleware: lifecycleMiddleware,
+    }
+  )
+
+  // Run the lifecycle function
+  const runLifecycle = async () => {
+    return await runPikkuFuncDirectly(
+      meta.pikkuFuncName,
+      { ...services, channel },
+      data
+    )
+  }
+
+  // Run with middleware if any
+  if (allMiddleware.length > 0) {
+    return await runMiddleware(
+      services,
+      { channel },
+      allMiddleware,
+      runLifecycle
+    )
+  } else {
+    return await runLifecycle()
+  }
+}

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

@@ -87,19 +87,43 @@ export const processMessageHandlers = (
 
     const {
       pikkuFuncName,
-      middleware: inheritedMiddleware,
+      middleware: routeInheritedMiddleware,
       permissions: inheritedPermissions,
     } = getRouteMeta(channelConfig.name, routingProperty, routerValue)
 
-    const wirePermissions =
-      typeof onMessage === 'function' ? undefined : onMessage.permissions
+    // Get wire middleware: channel-level middleware + message-specific middleware
+    const channelWireMiddleware = channelConfig.middleware || []
 
-    const wireMiddleware =
-      typeof onMessage === 'function' ? [] : onMessage.middleware
+    // Check if onMessage is a wrapper object vs direct function config:
+    // - Direct config: onMessage.func is a plain Function
+    // - Wrapper: onMessage.func is a CorePikkuFunctionConfig (has onMessage.func.func)
+    // - Simple wrapper: onMessage has both func (plain Function) and middleware properties
+    const isWrapper =
+      onMessage &&
+      typeof onMessage === 'object' &&
+      'func' in onMessage &&
+      ((typeof onMessage.func === 'object' && 'func' in onMessage.func) ||
+        'middleware' in onMessage)
+    const messageWireMiddleware = isWrapper ? onMessage.middleware || [] : []
+
+    // Combine channel middleware with message middleware (actual functions)
+    // Channel middleware runs first, then message middleware
+    const wireMiddleware = [...channelWireMiddleware, ...messageWireMiddleware]
+
+    // Inherited middleware comes from metadata (tag groups, non-inline wire)
+    const inheritedMiddleware = routeInheritedMiddleware || []
+
+    const wirePermissions = isWrapper ? onMessage.permissions : undefined
+
+    // Create unique cache key that includes routing info to avoid cache collisions
+    // when multiple message handlers use the same function
+    const cacheKey = routingProperty
+      ? `${channelConfig.name}:${routingProperty}:${routerValue}`
+      : `${channelConfig.name}:default`
 
     return await runPikkuFunc(
       PikkuWiringTypes.channel,
-      channelConfig.name,
+      cacheKey,
       pikkuFuncName,
       {
         singletonServices: services,
@@ -119,25 +143,35 @@ export const processMessageHandlers = (
     )
   }
 
-  const onMessage = async (rawData): Promise<unknown> => {
+  return async (rawData): Promise<unknown> => {
     let result: unknown
     let processed = false
 
     // Route-specific handling
     if (typeof rawData === 'string' && channelConfig.onMessageWiring) {
+      let messageData: any
       try {
-        const messageData = JSON.parse(rawData)
+        messageData = JSON.parse(rawData)
+      } catch (error) {
+        // Most likely a json error.. ignore
+      }
+
+      if (messageData) {
         const entries = Object.entries(channelConfig.onMessageWiring)
         for (const [routingProperty, routes] of entries) {
           const routerValue = messageData[routingProperty]
           if (routerValue && routes[routerValue]) {
+            const { [routingProperty]: _, ...data } = messageData
+
             processed = true
-            result = await processMessage(
-              messageData,
-              routes[routerValue],
-              routingProperty,
-              routerValue
-            )
+            result =
+              (await processMessage(
+                data as any,
+                routes[routerValue],
+                routingProperty,
+                routerValue
+              )) || {}
+            ;(result as any)[routingProperty] = routerValue
             break
           }
         }
@@ -147,8 +181,6 @@ export const processMessageHandlers = (
           processed = true
           result = await processMessage(messageData, channelConfig.onMessage)
         }
-      } catch (error) {
-        // Most likely a json error.. ignore
       }
     }
 
@@ -167,6 +199,4 @@ export const processMessageHandlers = (
 
     return result
   }
-
-  return onMessage
 }

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

@@ -56,7 +56,12 @@ export const wireChannel = <
 
   // Register onMessage function if provided
   if (channel.onMessage && channelMeta.message?.pikkuFuncName) {
-    addFunction(channelMeta.message.pikkuFuncName, channel.onMessage as any)
+    addFunction(
+      channelMeta.message.pikkuFuncName,
+      (channel.onMessage as any).func instanceof Function
+        ? channel.onMessage
+        : (channel.onMessage as any).func
+    )
   }
 
   // Register functions in onMessageWiring
@@ -72,7 +77,13 @@ export const wireChannel = <
         if (!wiringMeta) return
 
         // Register the function using the pikku name from metadata
-        addFunction(wiringMeta.pikkuFuncName, handler as any)
+        // It could be a FuncConfig or a wiring override with a funcConfig
+        addFunction(
+          wiringMeta.pikkuFuncName,
+          (handler as any).func instanceof Function
+            ? handler
+            : (handler as any).func
+        )
       })
     })
   }
@@ -81,8 +92,8 @@ export const wireChannel = <
   pikkuState('channel', 'channels').set(channel.name, channel as any)
 }
 
-const getMatchingChannelConfig = (request: string) => {
-  const matchedPath = httpRouter.match('get', request)
+const getMatchingChannelConfig = (path: string) => {
+  const matchedPath = httpRouter.match('get', path)
   if (!matchedPath) {
     return null
   }

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

@@ -88,8 +88,18 @@ export type CoreChannel<
 > = {
   name: string
   route: Channel
-  onConnect?: ChannelConnect
-  onDisconnect?: ChannelDisconnect
+  onConnect?:
+    | ChannelConnect
+    | {
+        func?: ChannelConnect
+        middleware?: PikkuMiddleware[]
+      }
+  onDisconnect?:
+    | ChannelDisconnect
+    | {
+        func?: ChannelDisconnect
+        middleware?: PikkuMiddleware[]
+      }
   onMessage?: ChannelFunctionMessage
   onMessageWiring?: Record<
     string,

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

@@ -33,6 +33,9 @@ export class PikkuLocalChannelHandler<
   }
 
   public close() {
+    if (this.getChannel().state === 'closed') {
+      return
+    }
     super.close()
     this.closeCallback?.()
   }

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

@@ -8,17 +8,12 @@ import {
   RunChannelParams,
 } from '../channel.types.js'
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
-import {
-  PikkuInteraction,
-  PikkuWiringTypes,
-  SessionServices,
-} from '../../../types/core.types.js'
+import { PikkuInteraction, 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'
 import { PikkuHTTP } from '../../http/http.types.js'
-import { runPikkuFuncDirectly } from '../../../function/function-runner.js'
 import { rpcService } from '../../rpc/rpc-runner.js'
+import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
 
 export const runLocalChannel = async ({
   singletonServices,
@@ -95,6 +90,7 @@ export const runLocalChannel = async ({
           {
             ...singletonServices,
             ...sessionServices,
+            channel,
             userSession,
           },
           interaction,
@@ -103,23 +99,43 @@ export const runLocalChannel = async ({
 
       const interaction: PikkuInteraction = { channel }
 
-      channelHandler.registerOnOpen(() => {
+      channelHandler.registerOnOpen(async () => {
         if (channelConfig.onConnect && meta.connect) {
-          runPikkuFuncDirectly(
-            meta.connect.pikkuFuncName,
-            getAllServices(channel, false),
-            openingData
-          )
+          try {
+            const result = await runChannelLifecycleWithMiddleware({
+              channelConfig,
+              meta: meta.connect,
+              lifecycleConfig: channelConfig.onConnect,
+              lifecycleType: 'connect',
+              services: getAllServices(channel, false),
+              channel,
+              data: openingData,
+            })
+            if (result !== undefined) {
+              await channel.send(result)
+            }
+          } catch (e) {
+            singletonServices.logger.error(`Error handling onConnect: ${e}`)
+            channel.send({ error: e.message || 'Unknown error' })
+          }
         }
       })
 
       channelHandler.registerOnClose(async () => {
         if (channelConfig.onDisconnect && meta.disconnect) {
-          runPikkuFuncDirectly(
-            meta.disconnect.pikkuFuncName,
-            getAllServices(channel, false),
-            openingData
-          )
+          try {
+            await runChannelLifecycleWithMiddleware({
+              channelConfig,
+              meta: meta.disconnect,
+              lifecycleConfig: channelConfig.onDisconnect,
+              lifecycleType: 'disconnect',
+              services: getAllServices(channel, false),
+              channel,
+            })
+          } catch (e) {
+            singletonServices.logger.error(`Error handling onDisconnect: ${e}`)
+            channel.send({ error: e.message || 'Unknown error' })
+          }
         }
 
         if (sessionServices) {
@@ -127,13 +143,20 @@ export const runLocalChannel = async ({
         }
       })
 
-      channelHandler.registerOnMessage(
-        processMessageHandlers(
-          getAllServices(channel),
-          channelConfig as any,
-          channelHandler
-        )
+      const onMessage = processMessageHandlers(
+        getAllServices(channel),
+        channelConfig as any,
+        channelHandler
       )
+      channelHandler.registerOnMessage(async (data) => {
+        try {
+          const result = await onMessage(data)
+          await channel.send(result)
+        } catch (e) {
+          singletonServices.logger.error(`Error handling message: ${e.message}`)
+          channel.send({ error: e.message || 'Unknown error' })
+        }
+      })
     } catch (e: any) {
       handleHTTPError(
         e,
@@ -151,18 +174,7 @@ export const runLocalChannel = async ({
     }
   }
 
-  await runMiddleware(
-    {
-      ...singletonServices,
-      userSession,
-    },
-    { http },
-    combineMiddleware(PikkuWiringTypes.channel, channelConfig.name, {
-      wireInheritedMiddleware: meta.middleware,
-      wireMiddleware: channelConfig.middleware,
-    }),
-    main
-  )
+  await main()
 
   return channelHandler
 }

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

@@ -1,4 +1,4 @@
-import { PikkuWiringTypes, SessionServices } from '../../../types/core.types.js'
+import { PikkuInteraction, SessionServices } from '../../../types/core.types.js'
 import { closeSessionServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
 import { openChannel } from '../channel-runner.js'
@@ -12,11 +12,11 @@ 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 { 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'
-import { runPikkuFuncDirectly } from '../../../function/function-runner.js'
+import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
+import { rpcService } from '../../rpc/rpc-runner.js'
 
 export interface RunServerlessChannelParams<ChannelData>
   extends RunChannelParams<ChannelData> {
@@ -37,7 +37,7 @@ const getVariablesForChannel = ({
   openingData?: unknown
 }) => {
   const channels = pikkuState('channel', 'channels')
-  const channelConfig = channels[channelName]
+  const channelConfig = channels.get(channelName)
   const channelsMeta = pikkuState('channel', 'meta')
   const meta = channelsMeta[channelName]
   if (!channelConfig) {
@@ -95,63 +95,66 @@ export const runChannelConnect = async ({
     userSession,
   })
 
-  const main = async () => {
-    try {
-      await channelStore.addChannel({
-        channelId,
-        channelName: channelConfig.name,
-        openingData,
-        channelObject,
-      })
-      const { channel } = getVariablesForChannel({
-        channelId,
-        channelHandlerFactory,
-        channelName: channelConfig.name,
-      })
-      if (createSessionServices) {
-        sessionServices = await createSessionServices(
-          singletonServices,
-          { http },
-          await userSession.get()
-        )
-      }
-      if (channelConfig.onConnect && meta.connect) {
-        await runPikkuFuncDirectly(
-          meta.connect.pikkuFuncName,
-          { ...singletonServices, ...sessionServices, channel },
-          openingData
-        )
-      }
-      http?.response?.status(101)
-    } catch (e: any) {
-      handleHTTPError(
-        e,
-        http,
-        channelId,
-        singletonServices.logger,
-        logWarningsForStatusCodes,
-        respondWith404,
-        bubbleErrors
+  try {
+    await channelStore.addChannel({
+      channelId,
+      channelName: channelConfig.name,
+      openingData,
+      channelObject,
+    })
+    const { channel } = getVariablesForChannel({
+      channelId,
+      channelHandlerFactory,
+      channelName: channelConfig.name,
+    })
+    if (createSessionServices) {
+      sessionServices = await createSessionServices(
+        singletonServices,
+        { http },
+        await userSession.get()
       )
-    } finally {
-      if (sessionServices) {
-        await closeSessionServices(singletonServices.logger, sessionServices)
-      }
     }
-  }
 
-  await runMiddleware(
-    {
-      ...singletonServices,
-      userSession,
-    },
-    { http },
-    combineMiddleware(PikkuWiringTypes.channel, channelConfig.name, {
-      wireInheritedMiddleware: meta.middleware,
-      wireMiddleware: channelConfig.middleware,
-    }),
-    main
-  )
+    const interaction: PikkuInteraction = { channel }
+    const getAllServices = (requiresAuth?: boolean) =>
+      rpcService.injectRPCService(
+        {
+          ...singletonServices,
+          ...sessionServices,
+          channel,
+          userSession,
+        },
+        interaction,
+        requiresAuth
+      )
+
+    if (channelConfig.onConnect && meta.connect) {
+      await runChannelLifecycleWithMiddleware({
+        channelConfig,
+        meta: meta.connect,
+        lifecycleConfig: channelConfig.onConnect,
+        lifecycleType: 'connect',
+        services: getAllServices(false),
+        channel,
+        data: openingData,
+      })
+    }
+    http?.response?.status(101)
+  } catch (e: any) {
+    handleHTTPError(
+      e,
+      http,
+      channelId,
+      singletonServices.logger,
+      logWarningsForStatusCodes,
+      respondWith404,
+      bubbleErrors
+    )
+  } finally {
+    if (sessionServices) {
+      await closeSessionServices(singletonServices.logger, sessionServices)
+    }
+  }
 }
 
 export const runChannelDisconnect = async ({
@@ -159,13 +162,33 @@ export const runChannelDisconnect = async ({
   ...params
 }: RunServerlessChannelParams<unknown>): Promise<void> => {
   let sessionServices: SessionServices | undefined
-  const { openingData, channelName, session } =
-    await params.channelStore.getChannelAndSession(params.channelId)
+
+  // Try to get channel from store. In serverless environments (especially with
+  // serverless-offline or worker threads), disconnect can be called multiple times
+  // or after the channel has already been cleaned up. If channel doesn't exist,
+  // there's nothing to disconnect, so we can return early.
+  let channelData
+  try {
+    channelData = await params.channelStore.getChannelAndSession(
+      params.channelId
+    )
+  } catch (error) {
+    singletonServices.logger.info(
+      `Channel ${params.channelId} not found during disconnect - already cleaned up`
+    )
+    return
+  }
+
+  const { openingData, channelName, session } = channelData
   const { channel, channelConfig, meta } = getVariablesForChannel({
     ...params,
     openingData,
     channelName,
   })
+  const userSession = new PikkuUserSessionService(
+    params.channelStore,
+    params.channelId
+  )
   if (!sessionServices && params.createSessionServices) {
     sessionServices = await params.createSessionServices(
       singletonServices,
@@ -173,12 +196,35 @@ export const runChannelDisconnect = async ({
       session
     )
   }
-  if (channelConfig.onDisconnect && meta.disconnect) {
-    await runPikkuFuncDirectly(
-      meta.disconnect.pikkuFuncName,
-      { ...singletonServices, ...sessionServices, channel },
-      undefined
+
+  const interaction: PikkuInteraction = { channel }
+  const getAllServices = (requiresAuth?: boolean) =>
+    rpcService.injectRPCService(
+      {
+        ...singletonServices,
+        ...sessionServices,
+        channel,
+        userSession,
+      },
+      interaction,
+      requiresAuth
     )
+
+  if (channelConfig.onDisconnect && meta.disconnect) {
+    try {
+      await runChannelLifecycleWithMiddleware({
+        channelConfig,
+        meta: meta.disconnect,
+        lifecycleConfig: channelConfig.onDisconnect,
+        lifecycleType: 'disconnect',
+        services: getAllServices(false),
+        channel,
+      })
+    } catch (e: any) {
+      singletonServices.logger.error(
+        `Error handling onDisconnect: ${e.message || e}`
+      )
+    }
   }
   await params.channelStore.removeChannels([channel.channelId])
   if (sessionServices) {
@@ -199,6 +245,10 @@ export const runChannelMessage = async (
     openingData,
     channelName,
   })
+  const userSession = new PikkuUserSessionService(
+    params.channelStore,
+    params.channelId
+  )
   if (params.createSessionServices) {
     sessionServices = await params.createSessionServices(
       singletonServices,
@@ -206,14 +256,32 @@ export const runChannelMessage = async (
       session
     )
   }
+
+  const interaction: PikkuInteraction = { channel }
+  const getAllServices = () =>
+    rpcService.injectRPCService(
+      {
+        ...singletonServices,
+        ...sessionServices,
+        channel,
+        userSession,
+      },
+      interaction
+    )
+
   let response: unknown
   try {
     const onMessage = processMessageHandlers(
-      { ...singletonServices, ...sessionServices },
+      getAllServices(),
       channelConfig,
       channelHandler
     )
     response = await onMessage(data)
+  } catch (e: any) {
+    singletonServices.logger.error(
+      `Error processing message: ${e.message || e}`
+    )
+    return { error: e.message || 'Unknown error' }
   } finally {
     if (sessionServices) {
       await closeSessionServices(singletonServices.logger, sessionServices)

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

@@ -30,7 +30,7 @@ export async function executeCLIViaChannel({
   const allCLIMeta = pikkuState('cli', 'meta') as unknown as CLIMeta | undefined
   if (!allCLIMeta) {
     throw new Error(
-      '[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/errors/pku342 for more information.'
+      '[PKU342] CLI metadata not found. No CLI wirings were registered. See https://pikku.dev/docs/pikku-cli/errors/pku342 for more information.'
     )
   }
   const programMeta = allCLIMeta.programs[programName]
@@ -92,6 +92,18 @@ export async function executeCLIViaChannel({
     const commandRoute = pikkuWS.getRoute('command')
 
     const responseHandler = (response: any) => {
+      // Check if this is a control message
+      if (
+        response?.action === 'cli-control' &&
+        response?.event === 'complete'
+      ) {
+        // Server signals command is complete, close the connection client-side
+        commandRoute.unsubscribe(commandId, responseHandler)
+        pikkuWS.ws.close()
+        resolve(undefined)
+        return
+      }
+
       // Call renderer for any output
       renderer(null as any, response, undefined)
     }