@pikku/core 0.11.2 → 0.12.1

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

@@ -1,12 +1,12 @@
-import { NotFoundError } from '../../errors/errors.js'
+import { NotFoundError, PikkuMissingMetaError } 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 type { CorePikkuPermission } from '../../function/functions.types.js'
+import { pikkuState, getSingletonServices } from '../../pikku-state.js'
 import { coerceTopLevelDataFromSchema, validateSchema } from '../../schema.js'
-import { SessionService } from '../../services/user-session-service.js'
-import { CorePikkuMiddleware } from '../../types/core.types.js'
+import type { SessionService } from '../../services/user-session-service.js'
+import type { CorePikkuMiddleware } from '../../types/core.types.js'
 import { httpRouter } from '../http/routers/http-router.js'
-import {
+import type {
   ChannelMeta,
   CoreChannel,
   RunChannelOptions,
@@ -36,28 +36,27 @@ export const wireChannel = <
   const channelsMeta = pikkuState(null, 'channel', 'meta')
   const channelMeta = channelsMeta[channel.name]
   if (!channelMeta) {
-    throw new Error(`Channel metadata not found for channel: ${channel.name}`)
+    throw new PikkuMissingMetaError(
+      `Missing generated metadata for channel '${channel.name}'`
+    )
   }
 
   pikkuState(null, 'channel', 'channels').set(channel.name, channel as any)
 
   // Register onConnect function if provided
   if (channel.onConnect && channelMeta.connect) {
-    addFunction(channelMeta.connect.pikkuFuncName, channel.onConnect as any)
+    addFunction(channelMeta.connect.pikkuFuncId, channel.onConnect as any)
   }
 
   // Register onDisconnect function if provided
   if (channel.onDisconnect && channelMeta.disconnect) {
-    addFunction(
-      channelMeta.disconnect.pikkuFuncName,
-      channel.onDisconnect as any
-    )
+    addFunction(channelMeta.disconnect.pikkuFuncId, channel.onDisconnect as any)
   }
 
   // Register onMessage function if provided
-  if (channel.onMessage && channelMeta.message?.pikkuFuncName) {
+  if (channel.onMessage && channelMeta.message?.pikkuFuncId) {
     addFunction(
-      channelMeta.message.pikkuFuncName,
+      channelMeta.message.pikkuFuncId,
       (channel.onMessage as any).func instanceof Function
         ? channel.onMessage
         : (channel.onMessage as any).func
@@ -79,7 +78,7 @@ export const wireChannel = <
         // Register the function using the pikku name from metadata
         // It could be a FuncConfig or a wiring override with a funcConfig
         addFunction(
-          wiringMeta.pikkuFuncName,
+          wiringMeta.pikkuFuncId,
           (handler as any).func instanceof Function
             ? handler
             : (handler as any).func
@@ -123,7 +122,6 @@ const getMatchingChannelConfig = (path: string) => {
 
 export const openChannel = async ({
   route,
-  singletonServices,
   coerceDataFromSchema = true,
   request,
 }: Pick<CoreChannel<unknown, string>, 'route'> &
@@ -134,6 +132,7 @@ export const openChannel = async ({
   channelConfig: CoreChannel<unknown, any>
   meta: ChannelMeta
 }> => {
+  const singletonServices = getSingletonServices()
   const matchingChannel = getMatchingChannelConfig(route)
   if (!matchingChannel) {
     singletonServices.logger.info(`Channel not found: ${route}`)

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

@@ -1,4 +1,4 @@
-import { CoreUserSession } from '../../types/core.types.js'
+import type { CoreUserSession } from '../../types/core.types.js'
 
 export type Channel<ChannelType = unknown, OpeningData = unknown> = {
   channelId: string

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

@@ -1,17 +1,27 @@
-import { PikkuError } from '../../errors/error-handler.js'
-import {
+import type { PikkuError } from '../../errors/error-handler.js'
+import type {
   HTTPFunctionMetaInputTypes,
   PikkuHTTPRequest,
   PikkuHTTPResponse,
 } from '../http/http.types.js'
-import {
-  CoreSingletonServices,
-  CreateWireServices,
+import type {
   CorePikkuMiddleware,
   MiddlewareMetadata,
   PermissionMetadata,
 } from '../../types/core.types.js'
-import {
+
+export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (
+  services: Services,
+  event: Event,
+  next: (event: Event | Event[] | null) => Promise<void> | void
+) => Promise<void> | void
+
+export type CorePikkuChannelMiddlewareFactory<
+  In = any,
+  Services = any,
+  Event = unknown,
+> = (input: In) => CorePikkuChannelMiddleware<Services, Event>
+import type {
   CorePermissionGroup,
   CorePikkuFunction,
   CorePikkuFunctionConfig,
@@ -29,14 +39,12 @@ export type RunChannelOptions = Partial<{
 
 export type RunChannelParams<ChannelData> = {
   channelId: string
-  singletonServices: CoreSingletonServices
   request?: PikkuHTTPRequest<ChannelData>
   response?: PikkuHTTPResponse
-  createWireServices?: CreateWireServices
 }
 
 export interface ChannelMessageMeta {
-  pikkuFuncName: string
+  pikkuFuncId: string
   summary?: string
   description?: string
   errors?: string[]
@@ -62,6 +70,7 @@ export interface ChannelMeta {
   tags?: string[]
   middleware?: MiddlewareMetadata[] // Pre-resolved middleware chain (tag + explicit)
   permissions?: PermissionMetadata[] // Pre-resolved permission chain (tag + explicit)
+  channelMiddleware?: MiddlewareMetadata[]
 }
 
 export type ChannelsMeta = Record<string, ChannelMeta>
@@ -118,6 +127,9 @@ export type CoreChannel<
     >
   >
   middleware?: PikkuMiddleware[]
+  channelMiddleware?: Array<
+    CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory
+  >
   permissions?: CorePermissionGroup<PikkuPermission>
   auth?: boolean
   docs?: Partial<{

package/src/wirings/channel/define-channel-routes.ts

@@ -0,0 +1,25 @@
+/**
+ * Type-safe helper for defining channel message routes that can be composed.
+ * Returns the routes record as-is (identity function) for use with `wireChannel`.
+ *
+ * @example
+ * ```typescript
+ * export const chatRoutes = defineChannelRoutes({
+ *   greet: pikkuChannelFunc({ func: greetFunc }),
+ *   farewell: pikkuChannelFunc({ func: farewellFunc }),
+ * })
+ *
+ * wireChannel({
+ *   name: 'chat',
+ *   route: '/ws/chat',
+ *   onMessageWiring: {
+ *     command: chatRoutes,
+ *   }
+ * })
+ * ```
+ */
+export function defineChannelRoutes<T extends Record<string, any>>(
+  routes: T
+): T {
+  return routes
+}

package/src/wirings/channel/index.ts

@@ -1,8 +1,23 @@
-export * from './channel-runner.js'
-export * from './channel.types.js'
-export * from './log-channels.js'
-export * from './pikku-abstract-channel-handler.js'
-export * from './eventhub-service.js'
-export * from './eventhub-service.js'
-export * from './channel-store.js'
-export * from './eventhub-store.js'
+export { wireChannel, openChannel } from './channel-runner.js'
+export {
+  addChannelMiddleware,
+  combineChannelMiddleware,
+  wrapChannelWithMiddleware,
+} from './channel-middleware-runner.js'
+export { logChannels } from './log-channels.js'
+export { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js'
+export type { EventHubService } from './eventhub-service.js'
+export { ChannelStore } from './channel-store.js'
+export type { Channel } from './channel-store.js'
+export { EventHubStore } from './eventhub-store.js'
+export type {
+  ChannelsMeta,
+  CoreChannel,
+  CorePikkuChannelMiddleware,
+  CorePikkuChannelMiddlewareFactory,
+  ChannelMessageMeta,
+  ChannelMeta,
+  PikkuChannel,
+  PikkuChannelHandlerFactory,
+} from './channel.types.js'
+export { defineChannelRoutes } from './define-channel-routes.js'

package/src/wirings/channel/local/index.ts

@@ -1,3 +1,3 @@
-export * from './local-channel-handler.js'
-export * from './local-channel-runner.js'
-export * from './local-eventhub-service.js'
+export { PikkuLocalChannelHandler } from './local-channel-handler.js'
+export { runLocalChannel } from './local-channel-runner.js'
+export { LocalEventHubService } from './local-eventhub-service.js'

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

@@ -3,13 +3,13 @@ import * as assert from 'node:assert/strict'
 import { runLocalChannel } from './local-channel-runner.js'
 import { pikkuState, resetPikkuState } from '../../../pikku-state.js'
 import { wireChannel } from '../channel-runner.js'
-import {
+import type {
   HTTPMethod,
   PikkuHTTPRequest,
   PikkuHTTPResponse,
   PikkuQuery,
 } from '../../http/http.types.js'
-import { SerializeOptions } from 'cookie'
+import type { SerializeOptions } from 'cookie'
 import { httpRouter } from '../../http/routers/http-router.js'
 
 /**
@@ -102,6 +102,10 @@ const mockCreateWireServices = async () => ({
 beforeEach(() => {
   resetPikkuState()
   httpRouter.reset()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: mockCreateWireServices,
+  } as any)
 })
 
 afterEach(() => {
@@ -113,11 +117,9 @@ test('runChannel should return undefined and 404 if no matching channel is found
   const mockResponse = new PikkuMockResponse()
 
   const result = await runLocalChannel({
-    singletonServices: mockSingletonServices,
     channelId: 'test-channel-id',
     request: new PikkuMockRequest('/non-existent-channel', 'get'),
     response: mockResponse,
-    createWireServices: mockCreateWireServices,
   })
 
   assert.equal(
@@ -131,6 +133,10 @@ test('runChannel should return undefined and 404 if no matching channel is found
 
 test('runChannel should return a channel handler if channel matches and no auth required', async () => {
   resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: mockCreateWireServices,
+  } as any)
 
   pikkuState(null, 'channel', 'meta', {
     test: {
@@ -148,18 +154,62 @@ test('runChannel should return a channel handler if channel matches and no auth
   httpRouter.initialize()
 
   const result = await runLocalChannel({
-    singletonServices: mockSingletonServices,
     channelId: 'test-channel-id',
     request: new PikkuMockRequest('/test-channel', 'get'),
     response: new PikkuMockResponse(),
     route: '/test-channel',
-    createWireServices: mockCreateWireServices,
   })
 
   assert.ok(result, 'Should return a PikkuChannelHandler instance')
 
   // Simulate opening the channel
   result.open()
+})
+
+test('runChannel should close wire services once when channel closes', async () => {
+  resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
+  let closeCount = 0
+
+  pikkuState(null, 'channel', 'meta', {
+    test: {
+      name: 'test',
+      route: '/test-channel',
+    },
+  } as any)
+  wireChannel({
+    name: 'test',
+    route: '/test-channel',
+    auth: false,
+  })
+
+  httpRouter.initialize()
+
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: async () => ({
+      tracked: {
+        close: async () => {
+          closeCount += 1
+        },
+      },
+    }),
+  } as any)
+
+  const result = await runLocalChannel({
+    channelId: 'test-channel-id',
+    request: new PikkuMockRequest('/test-channel', 'get'),
+    response: new PikkuMockResponse(),
+    route: '/test-channel',
+  })
+
+  assert.ok(result)
+  assert.equal(closeCount, 0)
+
+  result.close()
+  await new Promise((resolve) => setTimeout(resolve, 0))
+  assert.equal(closeCount, 1)
 
-  // TODO: Test that the opened channel works
+  result.close()
+  await new Promise((resolve) => setTimeout(resolve, 0))
+  assert.equal(closeCount, 1)
 })

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

@@ -2,34 +2,45 @@ import { openChannel } from '../channel-runner.js'
 import { createHTTPWire } from '../../http/http-runner.js'
 import { closeWireServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
-import {
-  CoreChannel,
-  RunChannelOptions,
-  RunChannelParams,
-} from '../channel.types.js'
+import type { CoreChannel, RunChannelOptions } from '../channel.types.js'
 import { PikkuLocalChannelHandler } from './local-channel-handler.js'
-import { PikkuWire, WireServices } from '../../../types/core.types.js'
+import type { PikkuWire, WireServices } from '../../../types/core.types.js'
 import { handleHTTPError } from '../../../handle-error.js'
-import { PikkuSessionService } from '../../../services/user-session-service.js'
-import { PikkuHTTP } from '../../http/http.types.js'
+import {
+  PikkuSessionService,
+  createMiddlewareSessionWireProps,
+} from '../../../services/user-session-service.js'
+import type {
+  PikkuHTTP,
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
+} from '../../http/http.types.js'
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
+import {
+  getSingletonServices,
+  getCreateWireServices,
+} from '../../../pikku-state.js'
 
 export const runLocalChannel = async ({
-  singletonServices,
   channelId,
   request,
   response,
   route,
-  createWireServices,
   skipUserSession = false,
   respondWith404 = true,
   coerceDataFromSchema = true,
   logWarningsForStatusCodes = [],
   bubbleErrors = false,
 }: Partial<Pick<CoreChannel<unknown, any>, 'route'>> &
-  RunChannelOptions &
-  RunChannelParams<unknown>): Promise<PikkuLocalChannelHandler | void> => {
+  RunChannelOptions & {
+    channelId: string
+    request?: PikkuHTTPRequest
+    response?: PikkuHTTPResponse
+  }): Promise<PikkuLocalChannelHandler | void> => {
+  const singletonServices = getSingletonServices()
+  const createWireServices = getCreateWireServices()
   let wireServices: WireServices<typeof singletonServices> | undefined
+  let closedWireServices = false
 
   let channelHandler: PikkuLocalChannelHandler | undefined
   const userSession = new PikkuSessionService()
@@ -44,12 +55,10 @@ export const runLocalChannel = async ({
   try {
     ;({ openingData, channelConfig, meta } = await openChannel({
       channelId,
-      createWireServices,
       respondWith404,
       request,
       response,
       route,
-      singletonServices,
       skipUserSession,
       coerceDataFromSchema,
       userSession,
@@ -75,12 +84,23 @@ export const runLocalChannel = async ({
         openingData
       )
       const channel = channelHandler.getChannel()
-      const wire: PikkuWire = { channel, session: userSession }
+      const wire: PikkuWire = {
+        channel,
+        ...createMiddlewareSessionWireProps(userSession),
+      }
 
       if (createWireServices) {
         wireServices = await createWireServices(singletonServices, wire)
       }
 
+      const closeServices = async () => {
+        if (!wireServices || closedWireServices) {
+          return
+        }
+        closedWireServices = true
+        await closeWireServices(singletonServices.logger, wireServices)
+      }
+
       const services = { ...singletonServices, ...wireServices }
 
       channelHandler.registerOnOpen(async () => {
@@ -94,6 +114,7 @@ export const runLocalChannel = async ({
               services,
               channel,
               data: openingData,
+              channelMiddlewareMeta: meta.channelMiddleware,
             })
             if (result !== undefined) {
               await channel.send(result)
@@ -115,6 +136,7 @@ export const runLocalChannel = async ({
               lifecycleType: 'disconnect',
               services,
               channel,
+              channelMiddlewareMeta: meta.channelMiddleware,
             })
           } catch (e) {
             singletonServices.logger.error(`Error handling onDisconnect: ${e}`)
@@ -122,9 +144,7 @@ export const runLocalChannel = async ({
           }
         }
 
-        if (wireServices) {
-          await closeWireServices(singletonServices.logger, wireServices)
-        }
+        await closeServices()
       })
 
       const onMessage = processMessageHandlers(
@@ -153,7 +173,8 @@ export const runLocalChannel = async ({
         bubbleErrors
       )
     } finally {
-      if (wireServices) {
+      if (!channelHandler && wireServices && !closedWireServices) {
+        closedWireServices = true
         await closeWireServices(singletonServices.logger, wireServices)
       }
     }

package/src/wirings/channel/local/local-eventhub-service.test.ts

@@ -1,7 +1,7 @@
 import * as assert from 'assert'
 import { test } from 'node:test'
-import { PikkuChannelHandler } from '../channel.types.js'
-import { CoreUserSession } from '../../../types/core.types.js'
+import type { PikkuChannelHandler } from '../channel.types.js'
+import type { CoreUserSession } from '../../../types/core.types.js'
 import { LocalEventHubService } from './local-eventhub-service.js'
 
 class MockChannelHandler implements PikkuChannelHandler {

package/src/wirings/channel/local/local-eventhub-service.ts

@@ -1,5 +1,5 @@
-import { PikkuChannelHandler } from '../channel.types.js'
-import { EventHubService } from '../eventhub-service.js'
+import type { PikkuChannelHandler } from '../channel.types.js'
+import type { EventHubService } from '../eventhub-service.js'
 
 /**
  * Implementation of the SubscriptionService interface.

package/src/wirings/channel/log-channels.ts

@@ -1,5 +1,5 @@
 import { pikkuState } from '../../pikku-state.js'
-import { Logger } from '../../services/index.js'
+import type { Logger } from '../../services/index.js'
 
 /**
  * Logs all the loaded channels.

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

@@ -1,4 +1,4 @@
-import { PikkuChannel, PikkuChannelHandler } from './channel.types.js'
+import type { PikkuChannel, PikkuChannelHandler } from './channel.types.js'
 
 export abstract class PikkuAbstractChannelHandler<
   OpeningData = unknown,

package/src/wirings/channel/serverless/index.ts

@@ -1 +1,5 @@
-export * from './serverless-channel-runner.js'
+export {
+  runChannelConnect,
+  runChannelDisconnect,
+  runChannelMessage,
+} from './serverless-channel-runner.js'