@pikku/core 0.12.4 → 0.12.5

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

@@ -0,0 +1,172 @@
+import type {
+  HTTPFunctionMetaInputTypes,
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
+} from '../http/http.types.js'
+import type {
+  CorePikkuMiddleware,
+  MiddlewareMetadata,
+  PermissionMetadata,
+} from '../../types/core.types.js'
+
+export type BinaryData = ArrayBuffer | Uint8Array
+
+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,
+  CorePikkuFunctionSessionless,
+  CorePikkuPermission,
+} from '../../function/functions.types.js'
+
+export type RunChannelOptions = Partial<{
+  skipUserSession: boolean
+  respondWith404: boolean
+  coerceDataFromSchema: boolean
+  logWarningsForStatusCodes: number[]
+  bubbleErrors: boolean
+}>
+
+export type RunChannelParams<ChannelData> = {
+  channelId: string
+  request?: PikkuHTTPRequest<ChannelData>
+  response?: PikkuHTTPResponse
+}
+
+export interface ChannelMessageMeta {
+  pikkuFuncId: string
+  packageName?: string
+  summary?: string
+  description?: string
+  errors?: string[]
+  tags?: string[]
+  middleware?: MiddlewareMetadata[]
+  permissions?: PermissionMetadata[]
+}
+
+export interface ChannelMeta {
+  name: string
+  route: string
+  params?: string[]
+  query?: string[]
+  input: string | null
+  inputTypes?: HTTPFunctionMetaInputTypes
+  connect: ChannelMessageMeta | null
+  disconnect: ChannelMessageMeta | null
+  message: ChannelMessageMeta | null
+  messageWirings: Record<string, Record<string, ChannelMessageMeta>>
+  binary?: boolean | null
+  summary?: string
+  description?: string
+  errors?: string[]
+  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>
+
+export type CoreChannel<
+  ChannelData,
+  Channel extends string,
+  ChannelConnect = CorePikkuFunctionConfig<
+    | CorePikkuFunction<void, unknown>
+    | CorePikkuFunctionSessionless<void, unknown>,
+    CorePikkuPermission<void>,
+    CorePikkuMiddleware
+  >,
+  ChannelDisconnect = CorePikkuFunctionConfig<
+    CorePikkuFunction<void, void> | CorePikkuFunctionSessionless<void, void>,
+    CorePikkuPermission<void>,
+    CorePikkuMiddleware
+  >,
+  ChannelFunctionMessage = CorePikkuFunctionConfig<
+    | CorePikkuFunction<unknown, unknown>
+    | CorePikkuFunctionSessionless<unknown, unknown>,
+    CorePikkuPermission<unknown>,
+    CorePikkuMiddleware
+  >,
+  PikkuPermission = CorePikkuPermission<ChannelData>,
+  PikkuMiddleware = CorePikkuMiddleware,
+> = {
+  name: string
+  route: Channel
+  onConnect?:
+    | ChannelConnect
+    | {
+        func?: ChannelConnect
+        middleware?: PikkuMiddleware[]
+      }
+  onDisconnect?:
+    | ChannelDisconnect
+    | {
+        func?: ChannelDisconnect
+        middleware?: PikkuMiddleware[]
+      }
+  onMessage?: ChannelFunctionMessage
+  onMessageWiring?: Record<
+    string,
+    Record<
+      string,
+      | ChannelFunctionMessage
+      | {
+          func: ChannelFunctionMessage
+          permissions?: CorePermissionGroup<PikkuPermission>
+          auth?: boolean
+          middleware?: PikkuMiddleware[]
+        }
+    >
+  >
+  middleware?: PikkuMiddleware[]
+  channelMiddleware?: Array<
+    CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory
+  >
+  permissions?: CorePermissionGroup<PikkuPermission>
+  auth?: boolean
+  binary?: boolean | null
+  onBinaryMessage?: (
+    services: any,
+    data: BinaryData,
+    channel: PikkuChannel<ChannelData, any>
+  ) => Promise<BinaryData | void> | BinaryData | void
+  tags?: string[]
+}
+
+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
+  sendBinary(data: BinaryData): Promise<void> | void
+  // This will close the channel.
+  close(): Promise<void> | void
+  // The current state of the channel
+  state: 'initial' | 'open' | 'closed'
+}
+
+export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {
+  send(message: Out, isBinary?: boolean): Promise<void> | void
+  sendBinary(data: BinaryData): Promise<void> | void
+  getChannel(): PikkuChannel<OpeningData, Out>
+}
+
+export type PikkuChannelHandlerFactory<OpeningData = unknown, Out = unknown> = (
+  channelId: string,
+  channelName: string,
+  openingData: OpeningData
+) => PikkuChannelHandler<OpeningData, Out>

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/eventhub-service.ts

@@ -0,0 +1,34 @@
+/**
+ * Interface defining the methods of a EventHub Service.
+ */
+export interface EventHubService<Topics extends Record<string, any>> {
+  /**
+   * Subscribes a connection to a specific topic.
+   * @param topic - The topic to subscribe to.
+   * @param channelId - The unique ID of the connection to subscribe.
+   */
+  subscribe<T extends keyof Topics>(
+    topic: T,
+    channelId: string
+  ): Promise<void> | void
+  /**
+   * Unsubscribes a connection from a specific topic.
+   * @param topic - The topic to unsubscribe from.
+   * @param channelId - The unique ID of the connection to unsubscribe.
+   */
+  unsubscribe<T extends keyof Topics>(
+    topic: T,
+    channelId: string
+  ): Promise<void> | void
+  /**
+   * Sends data to all connections subscribed to a topic.
+   * @param topic - The topic to send data to.
+   * @param data - The data to send to the subscribers.
+   */
+  publish<T extends keyof Topics>(
+    topic: T,
+    channelId: string | null,
+    data: Topics[T],
+    isBinary?: boolean
+  ): Promise<void> | void
+}

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

@@ -0,0 +1,13 @@
+export abstract class EventHubStore<
+  EventTopics extends Record<string, any> = {},
+> {
+  public abstract getChannelIdsForTopic(topic: string): Promise<string[]>
+  public abstract subscribe<T extends keyof EventTopics>(
+    topic: T,
+    channelId: string
+  ): Promise<boolean>
+  public abstract unsubscribe<T extends keyof EventTopics>(
+    topic: T,
+    channelId: string
+  ): Promise<boolean>
+}

package/src/wirings/channel/index.ts

@@ -0,0 +1,24 @@
+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 {
+  BinaryData,
+  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

@@ -0,0 +1,3 @@
+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-handler.ts

@@ -0,0 +1,81 @@
+import type { BinaryData } from '../channel.types.js'
+import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js'
+
+export class PikkuLocalChannelHandler<
+  OpeningData = unknown,
+  Out = unknown,
+> extends PikkuAbstractChannelHandler<OpeningData, Out> {
+  private onMessageCallback?: (message: unknown) => void
+  private onBinaryMessageCallback?: (data: BinaryData) => void
+  private openCallBack?: () => void
+  private closeCallbacks: (() => void)[] = []
+  private sendCallback?: (message: Out, isBinary?: boolean) => void
+  private sendBinaryCallback?: (data: BinaryData) => void
+
+  public registerOnOpen(callback: () => void): void {
+    this.openCallBack = callback
+  }
+
+  public open() {
+    this.getChannel().state = 'open'
+    if (this.openCallBack) {
+      this.openCallBack()
+    }
+  }
+
+  public registerOnMessage(callback: (data: any) => Promise<unknown>): void {
+    this.onMessageCallback = callback
+  }
+
+  public async message(data: unknown): Promise<unknown> {
+    return this.onMessageCallback?.(data)
+  }
+
+  public registerOnBinaryMessage(
+    callback: (
+      data: BinaryData
+    ) => Promise<BinaryData | void> | BinaryData | void
+  ): void {
+    this.onBinaryMessageCallback = callback
+  }
+
+  public async binaryMessage(data: BinaryData): Promise<BinaryData | void> {
+    return this.onBinaryMessageCallback?.(data)
+  }
+
+  public registerOnClose(callback: () => void): void {
+    this.closeCallbacks.push(callback)
+  }
+
+  public close() {
+    if (this.getChannel().state === 'closed') {
+      return
+    }
+    super.close()
+    for (const cb of this.closeCallbacks) {
+      cb()
+    }
+  }
+
+  public registerOnSend(send: (message: Out) => void) {
+    this.sendCallback = send
+  }
+
+  public send(message: Out, isBinary?: boolean): void {
+    if (!this.sendCallback) {
+      throw new Error('No send callback registered')
+    }
+    return this.sendCallback?.(message, isBinary)
+  }
+
+  public registerOnSendBinary(send: (data: BinaryData) => void) {
+    this.sendBinaryCallback = send
+  }
+
+  public sendBinary(data: BinaryData): void {
+    if (!this.sendBinaryCallback) {
+      throw new Error('No sendBinary callback registered')
+    }
+    this.sendBinaryCallback(data)
+  }
+}

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

@@ -0,0 +1,215 @@
+import { test, beforeEach, afterEach } from 'node:test'
+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 type {
+  HTTPMethod,
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
+  PikkuQuery,
+} from '../../http/http.types.js'
+import type { SerializeOptions } from 'cookie'
+import { httpRouter } from '../../http/routers/http-router.js'
+
+/**
+ * Minimal stubs for dependencies that runChannel expects.
+ * In a real test setup, you may provide more comprehensive mocks
+ * or refactor your code to allow dependency injection.
+ */
+const mockLogger = {
+  info: () => {},
+  error: () => {},
+  warn: () => {},
+  debug: () => {},
+}
+
+const mockSingletonServices = {
+  logger: mockLogger,
+} as any
+
+// Mock request and response objects
+export class PikkuMockRequest implements PikkuHTTPRequest {
+  private _params: Record<string, string | string[] | undefined> = {}
+
+  constructor(
+    private _route: string,
+    private _method: HTTPMethod
+  ) {}
+
+  method(): HTTPMethod {
+    return this._method
+  }
+  path(): string {
+    return this._route
+  }
+  json(): Promise<unknown> {
+    throw new Error('Method not implemented.')
+  }
+  arrayBuffer(): Promise<ArrayBuffer> {
+    throw new Error('Method not implemented.')
+  }
+  header(headerName: string): string | null {
+    throw new Error('Method not implemented.')
+  }
+  cookie(name?: string): string | null {
+    throw new Error('Method not implemented.')
+  }
+  params(): Partial<Record<string, string | string[]>> {
+    return this._params
+  }
+  setParams(params: Record<string, string | string[] | undefined>): void {
+    this._params = params
+  }
+  query(): PikkuQuery {
+    throw new Error('Method not implemented.')
+  }
+  public async data() {
+    return { test: 'data' }
+  }
+}
+
+export class PikkuMockResponse implements PikkuHTTPResponse {
+  public _status: number | undefined
+
+  status(code: number): this {
+    this._status = code
+    return this
+  }
+
+  cookie(name: string, value: string | null, options: SerializeOptions): this {
+    throw new Error('Method not implemented.')
+  }
+  header(name: string, value: string | string[]): this {
+    throw new Error('Method not implemented.')
+  }
+  arrayBuffer(data: XMLHttpRequestBodyInit): this {
+    throw new Error('Method not implemented.')
+  }
+  json(data: unknown): this {
+    // We don't need to implement this for our test
+    return this
+  }
+  redirect(location: string, status?: number): this {
+    throw new Error('Method not implemented.')
+  }
+}
+
+const mockCreateWireServices = async () => ({
+  wireServiceMock: true,
+})
+
+beforeEach(() => {
+  resetPikkuState()
+  httpRouter.reset()
+  pikkuState(null, 'package', 'singletonServices', mockSingletonServices as any)
+  pikkuState(null, 'package', 'factories', {
+    createWireServices: mockCreateWireServices,
+  } as any)
+})
+
+afterEach(() => {
+  resetPikkuState()
+  httpRouter.reset()
+})
+
+test('runChannel should return undefined and 404 if no matching channel is found', async () => {
+  const mockResponse = new PikkuMockResponse()
+
+  const result = await runLocalChannel({
+    channelId: 'test-channel-id',
+    request: new PikkuMockRequest('/non-existent-channel', 'get'),
+    response: mockResponse,
+  })
+
+  assert.equal(
+    result,
+    undefined,
+    'Should return undefined if no channel matches'
+  )
+  assert.equal(mockResponse._status, 404, 'Should set response status to 404')
+  // assert.equal(mockResponse._ended, true, 'Should end the response')
+})
+
+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: {
+      name: 'test',
+      route: '/test-channel',
+    },
+  } as any)
+  wireChannel({
+    name: 'test',
+    route: '/test-channel',
+    auth: false,
+  })
+
+  // Initialize router after adding channel (for tests)
+  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, '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)
+
+  result.close()
+  await new Promise((resolve) => setTimeout(resolve, 0))
+  assert.equal(closeCount, 1)
+})