@pikku/core 0.12.20 → 0.12.21

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

@@ -0,0 +1,163 @@
+import { beforeEach, describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import {
+  addChannelMiddleware,
+  clearChannelMiddlewareCache,
+  combineChannelMiddleware,
+  wrapChannelWithMiddleware,
+} from './channel-middleware-runner.js'
+
+beforeEach(() => {
+  resetPikkuState()
+  clearChannelMiddlewareCache()
+})
+
+describe('addChannelMiddleware', () => {
+  test('registers tag-scoped channel middleware for a package', () => {
+    const middleware = [async () => {}]
+
+    const result = addChannelMiddleware(
+      'chat:outbound',
+      middleware,
+      '@addon/pkg'
+    )
+
+    assert.strictEqual(result, middleware)
+    assert.strictEqual(
+      pikkuState('@addon/pkg', 'channelMiddleware', 'tagGroup')[
+        'chat:outbound'
+      ],
+      middleware
+    )
+  })
+})
+
+describe('combineChannelMiddleware', () => {
+  test('combines tag, named wire middleware, and inline channel middleware', () => {
+    const execution: string[] = []
+    const tagMiddleware = async () => {
+      execution.push('tag')
+    }
+    const namedMiddleware = async () => {
+      execution.push('named')
+    }
+    const inlineMiddleware = async () => {
+      execution.push('inline')
+    }
+
+    addChannelMiddleware('chat:outbound', [tagMiddleware], '@addon/pkg')
+    pikkuState(null, 'misc', 'channelMiddleware').named = [
+      namedMiddleware,
+    ] as never
+
+    const combined = combineChannelMiddleware('channel', 'combined-1', {
+      packageName: '@addon/pkg',
+      wireInheritedChannelMiddleware: [
+        { type: 'tag', tag: 'chat:outbound' },
+        { type: 'wire', name: 'named' },
+      ],
+      wireChannelMiddleware: [inlineMiddleware],
+    })
+
+    assert.deepEqual(combined, [
+      tagMiddleware,
+      namedMiddleware,
+      inlineMiddleware,
+    ])
+    void execution
+  })
+
+  test('deduplicates middleware and returns cached results until the cache is cleared', () => {
+    const shared = async () => {}
+    addChannelMiddleware('chat:outbound', [shared])
+
+    const first = combineChannelMiddleware('channel', 'cached-1', {
+      wireInheritedChannelMiddleware: [{ type: 'tag', tag: 'chat:outbound' }],
+      wireChannelMiddleware: [shared],
+    })
+
+    assert.deepEqual(first, [shared])
+
+    addChannelMiddleware('chat:outbound', [async () => {}])
+
+    const cached = combineChannelMiddleware('channel', 'cached-1', {
+      wireInheritedChannelMiddleware: [{ type: 'tag', tag: 'chat:outbound' }],
+    })
+    assert.strictEqual(cached, first)
+
+    clearChannelMiddlewareCache()
+
+    const refreshed = combineChannelMiddleware('channel', 'cached-1', {
+      wireInheritedChannelMiddleware: [{ type: 'tag', tag: 'chat:outbound' }],
+    })
+    assert.notStrictEqual(refreshed, first)
+    assert.equal(refreshed.length, 1)
+    assert.notStrictEqual(refreshed[0], shared)
+  })
+
+  test('ignores missing named middleware references', () => {
+    const combined = combineChannelMiddleware('channel', 'missing-wire', {
+      wireInheritedChannelMiddleware: [{ type: 'wire', name: 'missing' }],
+    })
+
+    assert.deepEqual(combined, [])
+  })
+})
+
+describe('wrapChannelWithMiddleware', () => {
+  test('returns the original wire when there is no channel or middleware', () => {
+    const wireWithoutChannel = { traceId: 'trace-1' }
+    const wireWithChannel = {
+      channel: {
+        send: async () => {},
+        sendBinary: async () => {},
+      },
+    }
+
+    assert.strictEqual(
+      wrapChannelWithMiddleware(wireWithoutChannel as never, {} as never, [
+        async () => {},
+      ]),
+      wireWithoutChannel
+    )
+    assert.strictEqual(
+      wrapChannelWithMiddleware(wireWithChannel as never, {} as never, []),
+      wireWithChannel
+    )
+  })
+
+  test('wraps outbound channel sends and supports transformed arrays and null drops', async () => {
+    const sent: string[] = []
+    const wrapped = wrapChannelWithMiddleware(
+      {
+        channel: {
+          send: async (data: string) => {
+            sent.push(data)
+          },
+          sendBinary: async () => {},
+        },
+      } as never,
+      {} as never,
+      [
+        async (_services, event: string, next) => {
+          if (event === 'drop') {
+            await next(null)
+            return
+          }
+          await next([`${event}:a`, `${event}:b`])
+        },
+        async (_services, event: string, next) => {
+          await next(event.toUpperCase())
+        },
+      ]
+    )
+
+    await wrapped.channel!.send('hello')
+    await wrapped.channel!.send('drop')
+
+    assert.deepEqual(sent, ['HELLO:A', 'HELLO:B'])
+    assert.strictEqual(wrapped.channel!.sendBinary, wrapped.channel!.sendBinary)
+  })
+})

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

@@ -23,4 +23,23 @@ export abstract class ChannelStore<
   ):
     | Promise<TypedChannel & { pikkuUserId?: string }>
     | (TypedChannel & { pikkuUserId?: string })
+
+  /**
+   * Persist per-socket scratch state scoped to a single channel (keyed by
+   * channelId). This is intentionally separate from `SessionStore` (which is
+   * keyed by `pikkuUserId` and holds the user session — shared across HTTP
+   * and channel transports).
+   *
+   * Use this for ephemeral, channel-local data: a per-socket subscription
+   * filter, a step in a connection-bound state machine, the last command sent
+   * on this socket, etc. It is cleared when the channel is removed.
+   */
+  public abstract setState(
+    channelId: string,
+    state: unknown
+  ): Promise<void> | void
+  public abstract getState(
+    channelId: string
+  ): Promise<unknown | undefined> | unknown | undefined
+  public abstract clearState(channelId: string): Promise<void> | void
 }

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

@@ -157,6 +157,10 @@ export interface PikkuChannel<OpeningData, out Out> {
   close(): Promise<void> | void
   // The current state of the channel
   state: 'initial' | 'open' | 'closed'
+  // Per-socket ephemeral state scoped to this channel connection.
+  setState<T>(state: T): Promise<void> | void
+  getState<T>(): Promise<T | undefined> | T | undefined
+  clearState(): Promise<void> | void
 }
 
 export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {

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

@@ -3,6 +3,7 @@ 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 { addHTTPMiddleware } from '../../http/http-runner.js'
 import type {
   HTTPMethod,
   PikkuHTTPRequest,
@@ -11,6 +12,7 @@ import type {
 } from '../../http/http.types.js'
 import type { SerializeOptions } from 'cookie'
 import { httpRouter } from '../../http/routers/http-router.js'
+import { pikkuMiddleware } from '../../../types/core.types.js'
 
 /**
  * Minimal stubs for dependencies that runChannel expects.
@@ -217,3 +219,64 @@ test('runChannel should close wire services once when channel closes', async ()
   await new Promise((resolve) => setTimeout(resolve, 0))
   assert.equal(closeCount, 1)
 })
+
+test('runChannel should run HTTP middleware on websocket upgrade and establish session', async () => {
+  resetPikkuState()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: mockCreateWireServices,
+  } as any)
+
+  addHTTPMiddleware(
+    '*',
+    [
+      pikkuMiddleware(async (_services, { setSession }, next) => {
+        setSession?.({ userId: 'user-1' } as any)
+        await next()
+      }),
+    ],
+    null
+  )
+
+  pikkuState(null, 'channel', 'meta', {
+    test: {
+      name: 'test',
+      route: '/test-channel',
+      messageWirings: {
+        action: {
+          ping: {
+            pikkuFuncId: 'test:ping',
+          },
+        },
+      },
+    },
+  } as any)
+  wireChannel({
+    name: 'test',
+    route: '/test-channel',
+    onMessageWiring: {
+      action: {
+        ping: {
+          func: async (_services, data) => data,
+        },
+      },
+    },
+  } as any)
+
+  httpRouter.initialize()
+
+  const result = await runLocalChannel({
+    channelId: 'test-channel-id',
+    request: new PikkuMockRequest('/test-channel', 'get'),
+    response: new PikkuMockResponse(),
+    route: '/test-channel',
+  })
+
+  assert.ok(result)
+  let sent: unknown
+  result.registerOnSend((message) => {
+    sent = message
+  })
+  await result.message(JSON.stringify({ action: 'ping' }))
+  assert.deepEqual(sent, { action: 'ping' })
+})

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

@@ -12,6 +12,7 @@ import {
   PikkuSessionService,
   createMiddlewareSessionWireProps,
 } from '../../../services/user-session-service.js'
+import { combineMiddleware, runMiddleware } from '../../../middleware-runner.js'
 import type {
   PikkuHTTP,
   PikkuHTTPRequest,
@@ -21,8 +22,38 @@ import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
 import {
   getSingletonServices,
   getCreateWireServices,
+  pikkuState,
 } from '../../../pikku-state.js'
 
+const runUpgradeMiddleware = async (
+  singletonServices: ReturnType<typeof getSingletonServices>,
+  request: PikkuHTTPRequest,
+  response: PikkuHTTPResponse | undefined,
+  userSession: PikkuSessionService<any>
+) => {
+  const http = createHTTPWire(request, response)
+  const httpGroups = pikkuState(null, 'middleware', 'httpGroup')
+  const wireInheritedMiddleware = httpGroups['*']
+    ? [{ type: 'http' as const, route: '*' }]
+    : undefined
+  const middleware = combineMiddleware('channel', `upgrade:${request.path()}`, {
+    wireInheritedMiddleware,
+  })
+
+  if (middleware.length > 0) {
+    await runMiddleware(
+      singletonServices,
+      {
+        http,
+        ...createMiddlewareSessionWireProps(userSession),
+      },
+      middleware
+    )
+  }
+
+  return http
+}
+
 export const runLocalChannel = async ({
   channelId,
   request,
@@ -48,13 +79,18 @@ export const runLocalChannel = async ({
   const userSession = new PikkuSessionService(singletonServices.sessionStore)
 
   let http: PikkuHTTP | undefined
-  if (request) {
-    http = createHTTPWire(request, response)
-    route = http?.request?.path()
-  }
-
   let openingData, channelConfig, meta
   try {
+    if (request) {
+      http = await runUpgradeMiddleware(
+        singletonServices,
+        request,
+        response,
+        userSession
+      )
+      route = request.path()
+    }
+
     ;({ openingData, channelConfig, meta } = await openChannel({
       channelId,
       respondWith404,

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

@@ -5,9 +5,9 @@ import type { EventHubService } from '../eventhub-service.js'
  * Implementation of the SubscriptionService interface.
  * Manages subscriptions and publishes messages to subscribers.
  */
-export class LocalEventHubService<Data extends Record<string, any> = {}>
-  implements EventHubService<Data>
-{
+export class LocalEventHubService<
+  Data extends Record<string, any> = {},
+> implements EventHubService<Data> {
   private channels = new Map<string, PikkuChannelHandler>()
 
   /**

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

@@ -7,8 +7,7 @@ import type {
 export abstract class PikkuAbstractChannelHandler<
   OpeningData = unknown,
   Out = unknown,
-> implements PikkuChannelHandler<OpeningData, Out>
-{
+> implements PikkuChannelHandler<OpeningData, Out> {
   protected channel?: PikkuChannel<OpeningData, Out>
 
   constructor(
@@ -23,6 +22,7 @@ export abstract class PikkuAbstractChannelHandler<
 
   public getChannel(): PikkuChannel<OpeningData, Out> {
     if (!this.channel) {
+      let channelState: unknown
       this.channel = {
         channelId: this.channelId,
         openingData: this.openingData,
@@ -30,6 +30,13 @@ export abstract class PikkuAbstractChannelHandler<
         sendBinary: this.sendBinary.bind(this),
         close: this.close.bind(this),
         state: 'initial',
+        setState: (s) => {
+          channelState = s
+        },
+        getState: () => channelState as any,
+        clearState: () => {
+          channelState = undefined
+        },
       }
     }
     return this.channel

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

@@ -1,4 +1,8 @@
-import type { PikkuWire, WireServices } from '../../../types/core.types.js'
+import type {
+  CoreUserSession,
+  PikkuWire,
+  WireServices,
+} from '../../../types/core.types.js'
 import { closeWireServices } from '../../../utils.js'
 import { processMessageHandlers } from '../channel-handler.js'
 import { openChannel } from '../channel-runner.js'
@@ -24,8 +28,9 @@ import { PikkuFetchHTTPRequest } from '../../http/pikku-fetch-http-request.js'
 import type { PikkuHTTP } from '../../http/http.types.js'
 import { runChannelLifecycleWithMiddleware } from '../channel-common.js'
 
-export interface RunServerlessChannelParams<ChannelData>
-  extends RunChannelParams<ChannelData> {
+export interface RunServerlessChannelParams<
+  ChannelData,
+> extends RunChannelParams<ChannelData> {
   channelStore: ChannelStore
   channelHandlerFactory: PikkuChannelHandlerFactory
   channelObject?: unknown
@@ -111,6 +116,9 @@ export const runChannelConnect = async ({
       channelHandlerFactory,
       channelName: channelConfig.name,
     })
+    channel.setState = (state) => channelStore.setState(channelId, state)
+    channel.getState = () => channelStore.getState(channelId) as any
+    channel.clearState = () => channelStore.clearState(channelId)
 
     const wire: PikkuWire = {
       channel,
@@ -193,8 +201,13 @@ export const runChannelDisconnect = async ({
     openingData,
     channelName,
   })
+  channel.setState = (state) => channelStore.setState(channelId, state)
+  channel.getState = () => channelStore.getState(channelId) as any
+  channel.clearState = () => channelStore.clearState(channelId)
 
-  const userSession = new PikkuSessionService(singletonServices.sessionStore)
+  const userSession = new PikkuSessionService<CoreUserSession>(
+    singletonServices.sessionStore
+  )
   if (pikkuUserId) {
     userSession.setPikkuUserId(pikkuUserId)
     const session = await singletonServices.sessionStore?.get(pikkuUserId)
@@ -260,8 +273,13 @@ export const runChannelMessage = async (
     openingData,
     channelName,
   })
+  channel.setState = (state) => channelStore.setState(channelId, state)
+  channel.getState = () => channelStore.getState(channelId) as any
+  channel.clearState = () => channelStore.clearState(channelId)
 
-  const userSession = new PikkuSessionService(singletonServices.sessionStore)
+  const userSession = new PikkuSessionService<CoreUserSession>(
+    singletonServices.sessionStore
+  )
   if (pikkuUserId) {
     userSession.setPikkuUserId(pikkuUserId)
     const session = await singletonServices.sessionStore?.get(pikkuUserId)

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

@@ -2,7 +2,10 @@ import { pikkuState } from '../../../pikku-state.js'
 import type { CLIMeta } from '../cli.types.js'
 import { parseCLIArguments, generateCommandHelp } from '../command-parser.js'
 import { runCLICommand } from '../cli-runner.js'
-import type { CoreSingletonServices, CreateWireServices } from '../../../types/core.types.js'
+import type {
+  CoreSingletonServices,
+  CreateWireServices,
+} from '../../../types/core.types.js'
 
 /**
  * Handles raw CLI input from a WebSocket channel.
@@ -57,7 +60,9 @@ export async function handleRawCLI({
   }
 
   // Check if the resolved command has a pikkuFuncId (is executable)
-  let current: { pikkuFuncId?: string; subcommands?: Record<string, any> } | undefined = programMeta.commands[parsed.commandPath[0]]
+  let current:
+    | { pikkuFuncId?: string; subcommands?: Record<string, any> }
+    | undefined = programMeta.commands[parsed.commandPath[0]]
   for (let i = 1; i < parsed.commandPath.length; i++) {
     current = current?.subcommands?.[parsed.commandPath[i]]
   }