@pikku/core 0.12.107 → 0.12.112

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

@@ -1,259 +0,0 @@
-import type { CoreServices, CoreUserSession } from '../../types/core.types.js'
-import type { JSONValue } from '../../utils.js'
-import type {
-  CorePikkuChannelMiddleware,
-  BinaryData,
-  ChannelMessageMeta,
-  CoreChannel,
-  PikkuChannelHandler,
-} from './channel.types.js'
-import { pikkuState } from '../../pikku-state.js'
-import { runPikkuFunc } from '../../function/function-runner.js'
-import { isChannelRPCPending, isChannelRPCResponse } from './channel-rpc.js'
-import { handleChannelRPCResponse } from './channel-host-rpc.js'
-import type { SessionService } from '../../services/user-session-service.js'
-import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js'
-const getChannelMeta = (channelName: string) => {
-  return pikkuState(null, 'channel', 'meta')[channelName]
-}
-
-const getRouteMeta = (
-  channelName: string,
-  routingProperty?: string,
-  routerValue?: string
-): ChannelMessageMeta => {
-  const channelMeta = pikkuState(null, 'channel', 'meta')[channelName]
-  if (!channelMeta) {
-    throw new Error(`Channel ${channelName} not found`)
-  }
-  if (!routingProperty) {
-    if (!channelMeta.message) {
-      throw new Error(`Channel ${channelName} has no default message route`)
-    }
-    return channelMeta.message
-  }
-  if (!routerValue) {
-    throw new Error(
-      `Channel ${channelName} requires a router value for ${routingProperty}`
-    )
-  }
-  const route = channelMeta.messageWirings[routingProperty]?.[routerValue]
-  if (!route) {
-    throw new Error(
-      `Channel ${channelName} has no route for ${routingProperty}:${routerValue}`
-    )
-  }
-  return route
-}
-
-const validateAuth = (
-  requiresSession: boolean,
-  session: CoreUserSession | undefined,
-  onMessage: any
-) => {
-  const auth =
-    typeof onMessage === 'function'
-      ? requiresSession
-      : onMessage.auth === undefined
-        ? requiresSession
-        : onMessage.auth
-
-  if (auth && !session) {
-    return false
-  }
-  return true
-}
-
-export const processMessageHandlers = (
-  services: CoreServices,
-  channelConfig: CoreChannel<any, any>,
-  channelHandler: PikkuChannelHandler,
-  userSession?: SessionService<CoreUserSession>
-) => {
-  const logger = services.logger
-  const requiresSession = channelConfig.auth !== false
-
-  const processMessage = async (
-    data: JSONValue,
-    onMessage: any,
-    routingProperty?: string,
-    routerValue?: string
-  ): Promise<unknown> => {
-    if (
-      !validateAuth(
-        requiresSession,
-        userSession?.get() as CoreUserSession | undefined,
-        onMessage
-      )
-    ) {
-      const routeMessage = routingProperty
-        ? `route '${routingProperty}:${routerValue}'`
-        : 'the default message route'
-      logger.error(
-        `Channel ${channelConfig.name} with id ${channelHandler.getChannel().channelId} requires a session for ${routeMessage}. No session is attached to this websocket connection. Ensure auth middleware establishes a session during websocket upgrade, and configure sessionStore when the runtime needs persisted sessions.`
-      )
-      // knowledge: questions/unauthorized-channel-replies-escape-the-declared-out-type.md
-      channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`)
-      return
-    }
-
-    const routeMeta = getRouteMeta(
-      channelConfig.name,
-      routingProperty,
-      routerValue
-    )
-    const { packageName, middleware: routeInheritedMiddleware } = routeMeta
-
-    const pikkuFuncId = routeMeta.pikkuFuncId
-
-    // Get wire middleware: channel-level middleware + message-specific middleware
-    const channelWireMiddleware = channelConfig.middleware || []
-
-    // knowledge: decisions/internals/channel-message-handlers-accept-three-config-shapes.md
-    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 || []
-
-    // 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`
-
-    const channelMeta = getChannelMeta(channelConfig.name)
-    const wireChannelMiddleware = channelConfig.channelMiddleware || []
-
-    return await runPikkuFunc('channel', cacheKey, pikkuFuncId, {
-      singletonServices: services,
-      data: () => data,
-      inheritedMiddleware,
-      wireMiddleware,
-      inheritedChannelMiddleware: channelMeta?.channelMiddleware,
-      // knowledge: questions/channel-middleware-accepts-bare-factories-that-nothing-resolves.md
-      wireChannelMiddleware:
-        wireChannelMiddleware as CorePikkuChannelMiddleware[],
-      coerceDataFromSchema: true,
-      tags: channelConfig.tags,
-      sessionService: userSession,
-      wire: {
-        channel: channelHandler.getChannel(),
-        ...(userSession && createMiddlewareSessionWireProps(userSession)),
-      },
-      packageName,
-    })
-  }
-
-  const onMessage = async (rawData: unknown): Promise<unknown> => {
-    let result: unknown
-    let processed = false
-
-    let frame: any
-    if (typeof rawData === 'string') {
-      try {
-        frame = JSON.parse(rawData)
-      } catch {
-        // Most likely a json error.. ignore
-      }
-    }
-
-    // Taken ahead of routing so every channel gets reverse RPC without
-    // declaring a route for replies, and so an answer to a call someone is
-    // still awaiting can never be mistaken for a new message.
-    if (isChannelRPCResponse(frame) || isChannelRPCPending(frame)) {
-      handleChannelRPCResponse(channelHandler.getChannel().channelId, frame)
-      return
-    }
-
-    // Route-specific handling
-    if (typeof rawData === 'string' && channelConfig.onMessageWiring) {
-      const messageData: any = frame
-
-      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
-            const routeResult = await processMessage(
-              data,
-              routes[routerValue],
-              routingProperty,
-              routerValue
-            )
-            // The routing key is echoed so the client can match the reply.
-            // Assigning it to a primitive throws under ESM strict mode, so a
-            // primitive result is wrapped rather than mutated.
-            result =
-              routeResult !== null && typeof routeResult === 'object'
-                ? Object.assign(routeResult, { [routingProperty]: routerValue })
-                : routeResult === undefined
-                  ? { [routingProperty]: routerValue }
-                  : { [routingProperty]: routerValue, result: routeResult }
-            break
-          }
-        }
-
-        // Default handler if no routes matched but json data was parsed
-        if (!processed && channelConfig.onMessage) {
-          processed = true
-          result = await processMessage(messageData, channelConfig.onMessage)
-        }
-      }
-    }
-
-    // Default handler if no routes matched and json data wasn't parsed
-    if (!processed && channelConfig.onMessage) {
-      processed = true
-      result = await processMessage(
-        rawData as JSONValue,
-        channelConfig.onMessage
-      )
-    }
-
-    if (!processed) {
-      logger.error(
-        `No handler found for message in channel ${channelConfig.name} for ${JSON.stringify(rawData)}`
-      )
-      logger.error(`Channel config name: ${channelConfig.name}`)
-    }
-
-    return result
-  }
-
-  const onBinaryMessage = channelConfig.onBinaryMessage
-    ? async (data: BinaryData): Promise<BinaryData | void> => {
-        if (
-          !validateAuth(
-            requiresSession,
-            userSession?.get() as CoreUserSession | undefined,
-            channelConfig
-          )
-        ) {
-          logger.error(
-            `Channel ${channelConfig.name} with id ${channelHandler.getChannel().channelId} requires a session for binary message`
-          )
-          return
-        }
-        return channelConfig.onBinaryMessage!(
-          services,
-          data,
-          channelHandler.getChannel()
-        )
-      }
-    : undefined
-
-  return { onMessage, onBinaryMessage }
-}

package/src/wirings/channel/channel-host-rpc.test.ts

@@ -1,150 +0,0 @@
-import { describe, test } from 'node:test'
-import * as assert from 'node:assert/strict'
-
-import { CHANNEL_RPC_RESPONSE } from './channel-rpc.js'
-import {
-  getChannelHostRPC,
-  handleChannelRPCResponse,
-  releaseChannelHostRPC,
-} from './channel-host-rpc.js'
-import type { PikkuChannel } from './channel.types.js'
-
-/**
- * A channel stripped to what the host RPC registry touches: an id to key the
- * transport by, and a send it writes requests to.
- */
-const fakeChannel = (channelId: string) => {
-  const sent: unknown[] = []
-  const channel = {
-    channelId,
-    send: async (data: unknown) => {
-      sent.push(data)
-    },
-  } as unknown as PikkuChannel<unknown, any>
-  return { channel, sent }
-}
-
-describe('channel host RPC', () => {
-  test('one transport per connection, reused across commands', async () => {
-    const { channel } = fakeChannel('reuse')
-    try {
-      assert.equal(getChannelHostRPC(channel), getChannelHostRPC(channel))
-    } finally {
-      await releaseChannelHostRPC('reuse')
-    }
-  })
-
-  test('separate connections get separate transports', async () => {
-    const a = fakeChannel('a')
-    const b = fakeChannel('b')
-    try {
-      assert.notEqual(
-        getChannelHostRPC(a.channel),
-        getChannelHostRPC(b.channel)
-      )
-
-      // Requests must land on their own socket, not the other connection's.
-      // Nothing answers this one, so it is rejected by the release below.
-      getChannelHostRPC(a.channel)
-        .invoke('localCheckout', {})
-        .catch(() => {})
-      assert.equal(a.sent.length, 1)
-      assert.equal(b.sent.length, 0)
-    } finally {
-      await releaseChannelHostRPC('a')
-      await releaseChannelHostRPC('b')
-    }
-  })
-
-  test('a response is routed back to the call it belongs to', async () => {
-    const { channel, sent } = fakeChannel('routed')
-    try {
-      const service = getChannelHostRPC(channel)
-      const call = service.invoke('localCheckout', {})
-      const { id } = sent[0] as { id: string }
-
-      assert.equal(
-        handleChannelRPCResponse('routed', {
-          action: CHANNEL_RPC_RESPONSE,
-          id,
-          ok: true,
-          result: { sha: 'deadbeef' },
-        }),
-        true
-      )
-      assert.deepEqual(await call, { sha: 'deadbeef' })
-    } finally {
-      await releaseChannelHostRPC('routed')
-    }
-  })
-
-  test('a frame for an unknown connection or id is dropped, not thrown', async () => {
-    const { channel, sent } = fakeChannel('dropped')
-    try {
-      const service = getChannelHostRPC(channel)
-      const call = service.invoke('localCheckout', {})
-      const { id } = sent[0] as { id: string }
-
-      // No transport for that connection at all.
-      assert.equal(
-        handleChannelRPCResponse('never-connected', {
-          action: CHANNEL_RPC_RESPONSE,
-          id,
-          ok: true,
-          result: null,
-        }),
-        false
-      )
-      // Right connection, but an id that was never registered — a late frame
-      // from a call that already timed out looks exactly like this.
-      assert.equal(
-        handleChannelRPCResponse('dropped', {
-          action: CHANNEL_RPC_RESPONSE,
-          id: 'not-an-id',
-          ok: true,
-          result: null,
-        }),
-        false
-      )
-
-      handleChannelRPCResponse('dropped', {
-        action: CHANNEL_RPC_RESPONSE,
-        id,
-        ok: true,
-        result: 'ok',
-      })
-      assert.equal(await call, 'ok')
-    } finally {
-      await releaseChannelHostRPC('dropped')
-    }
-  })
-
-  test('releasing rejects everything still in flight', async () => {
-    const { channel } = fakeChannel('released')
-    const call = getChannelHostRPC(channel).invoke('localCheckout', {})
-
-    await releaseChannelHostRPC('released')
-
-    // Without this a caller waits out the full timeout on a socket that is
-    // already gone.
-    await assert.rejects(call)
-  })
-
-  test('releasing forgets the connection', async () => {
-    const { channel } = fakeChannel('forgotten')
-    const first = getChannelHostRPC(channel)
-    await releaseChannelHostRPC('forgotten')
-
-    try {
-      // A stale entry would hand a reconnecting channel a stopped transport,
-      // and the map would grow for the life of the process.
-      assert.notEqual(getChannelHostRPC(channel), first)
-    } finally {
-      await releaseChannelHostRPC('forgotten')
-    }
-  })
-
-  test('releasing an unknown connection is a no-op', async () => {
-    await releaseChannelHostRPC('was-never-here')
-  })
-})

package/src/wirings/channel/channel-host-rpc.ts

@@ -1,69 +0,0 @@
-import {
-  ChannelDeploymentService,
-  createChannelRPCInputValidator,
-  createChannelRPCResultValidator,
-} from './channel-rpc.js'
-import type { ChannelRPCValidator } from './channel-rpc.js'
-import type { PikkuChannel } from './channel.types.js'
-import { getSingletonServices } from '../../pikku-state.js'
-
-/** Reverse-RPC transports, one per open connection. */
-const hostRPCByChannel = new Map<string, ChannelDeploymentService>()
-
-/**
- * The transport for a connection, created on first use. `options` apply only
- * to the call that creates it — one connection has one transport, so the first
- * caller's timeout and validators become the connection's.
- */
-export const getChannelHostRPC = (
-  channel: PikkuChannel<unknown, any>,
-  options: {
-    timeoutMs?: number
-    validateInput?: ChannelRPCValidator
-    validateResult?: ChannelRPCValidator
-  } = {}
-): ChannelDeploymentService => {
-  let service = hostRPCByChannel.get(channel.channelId)
-  if (!service) {
-    service = new ChannelDeploymentService(
-      (data) => channel.send(data),
-      options
-    )
-    hostRPCByChannel.set(channel.channelId, service)
-  }
-  return service
-}
-
-/**
- * Kept out of the channel handler so a channel nobody calls back on pays for no
- * registry, and because a handler has no services to build a validator with.
- */
-export const channelRemote = async (
-  channel: PikkuChannel<unknown, any, any>,
-  funcName: string,
-  data?: unknown
-): Promise<unknown> =>
-  getChannelHostRPC(channel, {
-    validateInput: createChannelRPCInputValidator(getSingletonServices()),
-    validateResult: createChannelRPCResultValidator(getSingletonServices()),
-  }).invoke(funcName, data)
-
-/** False for an unknown connection or id, so a stray frame is dropped. */
-export const handleChannelRPCResponse = (
-  channelId: string,
-  message: unknown
-): boolean => hostRPCByChannel.get(channelId)?.handleResponse(message) ?? false
-
-/**
- * Must run on disconnect: without it a caller waits out the full timeout on a
- * dead socket, and the map grows for the life of the process.
- */
-export const releaseChannelHostRPC = async (
-  channelId: string
-): Promise<void> => {
-  const service = hostRPCByChannel.get(channelId)
-  if (service) {
-    hostRPCByChannel.delete(channelId)
-    await service.stop()
-  }
-}

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

@@ -1,188 +0,0 @@
-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('caches the statically-resolved inherited middleware until the cache is cleared', () => {
-    const shared = async () => {}
-    addChannelMiddleware('chat:outbound', [shared])
-
-    const first = combineChannelMiddleware('channel', 'cached-1', {
-      wireInheritedChannelMiddleware: [{ type: 'tag', tag: 'chat:outbound' }],
-    })
-
-    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('does not cache per-run wireChannelMiddleware across calls (C4 cross-run leak)', () => {
-    const shared = async () => {}
-    addChannelMiddleware('chat:outbound', [shared])
-
-    const runA = async () => {}
-    const first = combineChannelMiddleware('agent', 'stream:bot', {
-      wireInheritedChannelMiddleware: [{ type: 'tag', tag: 'chat:outbound' }],
-      wireChannelMiddleware: [runA],
-    })
-    assert.deepEqual(first, [shared, runA])
-
-    const runB = async () => {}
-    const second = combineChannelMiddleware('agent', 'stream:bot', {
-      wireInheritedChannelMiddleware: [{ type: 'tag', tag: 'chat:outbound' }],
-      wireChannelMiddleware: [runB],
-    })
-    assert.deepEqual(second, [shared, runB])
-    assert.strictEqual(second[1], runB)
-    assert.notStrictEqual(second[1], runA)
-
-    const third = combineChannelMiddleware('agent', 'stream:bot', {
-      wireInheritedChannelMiddleware: [{ type: 'tag', tag: 'chat:outbound' }],
-    })
-    assert.deepEqual(third, [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)
-  })
-})