@pikku/core 0.12.4 → 0.12.5

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

@@ -0,0 +1,210 @@
+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 type { CoreChannel, RunChannelOptions } from '../channel.types.js'
+import { PikkuLocalChannelHandler } from './local-channel-handler.js'
+import type { PikkuWire, WireServices } from '../../../types/core.types.js'
+import { handleHTTPError } from '../../../handle-error.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 ({
+  channelId,
+  request,
+  response,
+  route,
+  skipUserSession = false,
+  respondWith404 = true,
+  coerceDataFromSchema = true,
+  logWarningsForStatusCodes = [],
+  bubbleErrors = false,
+}: Partial<Pick<CoreChannel<unknown, any>, 'route'>> &
+  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()
+
+  let http: PikkuHTTP | undefined
+  if (request) {
+    http = createHTTPWire(request, response)
+    route = http?.request?.path()
+  }
+
+  let openingData, channelConfig, meta
+  try {
+    ;({ openingData, channelConfig, meta } = await openChannel({
+      channelId,
+      respondWith404,
+      request,
+      response,
+      route,
+      skipUserSession,
+      coerceDataFromSchema,
+      userSession,
+    }))
+  } catch (e) {
+    handleHTTPError(
+      e,
+      http,
+      channelId,
+      singletonServices.logger,
+      logWarningsForStatusCodes,
+      respondWith404,
+      bubbleErrors
+    )
+    return
+  }
+
+  const main = async () => {
+    try {
+      channelHandler = new PikkuLocalChannelHandler(
+        channelId,
+        channelConfig.name,
+        openingData
+      )
+      const channel = channelHandler.getChannel()
+      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 () => {
+        if (channelConfig.onConnect && meta.connect) {
+          try {
+            const result = await runChannelLifecycleWithMiddleware({
+              channelConfig,
+              meta: meta.connect,
+              lifecycleConfig: channelConfig.onConnect,
+              lifecycleType: 'connect',
+              services,
+              channel,
+              data: openingData,
+              channelMiddlewareMeta: meta.channelMiddleware,
+            })
+            if (result !== undefined) {
+              await channel.send(result)
+            }
+          } catch (e: any) {
+            singletonServices.logger.error(`Error handling onConnect: ${e}`)
+            channel.send({
+              error: e.message || 'Unknown error',
+              errorName: e.constructor?.name,
+            })
+          }
+        }
+      })
+
+      channelHandler.registerOnClose(async () => {
+        if (channelConfig.onDisconnect && meta.disconnect) {
+          try {
+            await runChannelLifecycleWithMiddleware({
+              channelConfig,
+              meta: meta.disconnect,
+              lifecycleConfig: channelConfig.onDisconnect,
+              lifecycleType: 'disconnect',
+              services,
+              channel,
+              channelMiddlewareMeta: meta.channelMiddleware,
+            })
+          } catch (e: any) {
+            singletonServices.logger.error(`Error handling onDisconnect: ${e}`)
+            channel.send({
+              error: e.message || 'Unknown error',
+              errorName: e.constructor?.name,
+            })
+          }
+        }
+
+        await closeServices()
+      })
+
+      const { onMessage, onBinaryMessage } = processMessageHandlers(
+        services,
+        channelConfig as any,
+        channelHandler,
+        userSession
+      )
+      channelHandler.registerOnMessage(async (data) => {
+        try {
+          const result = await onMessage(data)
+          await channel.send(result)
+        } catch (e: any) {
+          singletonServices.logger.error(e)
+          channel.send({
+            error: e.message || 'Unknown error',
+            errorName: e.constructor?.name,
+          })
+          setTimeout(() => channel.close(), 200)
+        }
+      })
+      if (onBinaryMessage) {
+        channelHandler.registerOnBinaryMessage(async (data) => {
+          try {
+            const result = await onBinaryMessage(data)
+            if (result) {
+              await channel.sendBinary(result)
+            }
+          } catch (e) {
+            singletonServices.logger.error(
+              `Error handling binary message: ${e.message}`
+            )
+          }
+        })
+      }
+    } catch (e: any) {
+      handleHTTPError(
+        e,
+        http,
+        channelId,
+        singletonServices.logger,
+        logWarningsForStatusCodes,
+        respondWith404,
+        bubbleErrors
+      )
+    } finally {
+      if (!channelHandler && wireServices && !closedWireServices) {
+        closedWireServices = true
+        await closeWireServices(singletonServices.logger, wireServices)
+      }
+    }
+  }
+
+  await main()
+
+  return channelHandler
+}

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

@@ -0,0 +1,95 @@
+import * as assert from 'assert'
+import { test } from 'node:test'
+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 {
+  private channelId: string
+
+  constructor(channelId: string) {
+    this.channelId = channelId
+  }
+
+  setUserSession(session: CoreUserSession): Promise<void> | void {
+    throw new Error('Method not needed.')
+  }
+
+  getChannel() {
+    return { channelId: this.channelId } as any
+  }
+
+  send(data: unknown, isBinary?: boolean) {
+    // Mock send functionality
+    console.log(`Sent to ${this.channelId}:`, { data, isBinary })
+  }
+}
+
+test('LocalEventHubService: subscribe and unsubscribe', () => {
+  const eventHub = new LocalEventHubService()
+
+  // Subscribe a channel to a topic
+  eventHub.subscribe('topic1', 'channel1')
+  assert.strictEqual(eventHub['subscriptions'].get('topic1')!.size, 1)
+
+  // Unsubscribe the channel
+  eventHub.unsubscribe('topic1', 'channel1')
+  assert.strictEqual(eventHub['subscriptions'].has('topic1'), false)
+})
+
+test('LocalEventHubService: publish messages', () => {
+  const eventHub = new LocalEventHubService()
+
+  // Register mock channels
+  const channel1 = new MockChannelHandler('channel1')
+  const channel2 = new MockChannelHandler('channel2')
+  eventHub.onChannelOpened(channel1)
+  eventHub.onChannelOpened(channel2)
+
+  // Subscribe channels to a topic
+  eventHub.subscribe('topic1', 'channel1')
+  eventHub.subscribe('topic1', 'channel2')
+
+  // Mock `send` method to track calls
+  let sendCallCount = 0
+  channel1.send = () => {
+    sendCallCount++
+  }
+  channel2.send = () => {
+    sendCallCount++
+  }
+
+  // Publish a message
+  eventHub.publish('topic1', 'channel1', { message: 'Hello!' })
+
+  // Ensure the message was sent only to channel2
+  assert.strictEqual(sendCallCount, 1)
+})
+
+test('LocalEventHubService: onChannelOpened and onChannelClosed', () => {
+  const eventHub = new LocalEventHubService()
+
+  // Register and verify channel
+  const channel1 = new MockChannelHandler('channel1')
+  eventHub.onChannelOpened(channel1)
+  assert.strictEqual(eventHub['channels'].has('channel1'), true)
+
+  // Close and verify removal
+  eventHub.onChannelClosed('channel1')
+  assert.strictEqual(eventHub['channels'].has('channel1'), false)
+})
+
+test('LocalEventHubService: clean up empty topics on channel close', () => {
+  const eventHub = new LocalEventHubService()
+
+  // Register and subscribe channels
+  const channel1 = new MockChannelHandler('channel1')
+  eventHub.onChannelOpened(channel1)
+  eventHub.subscribe('topic1', 'channel1')
+
+  // Close channel
+  eventHub.onChannelClosed('channel1')
+
+  // Ensure topic1 is removed
+  assert.strictEqual(eventHub['subscriptions'].has('topic1'), false)
+})

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

@@ -0,0 +1,101 @@
+import type { PikkuChannelHandler } from '../channel.types.js'
+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>
+{
+  private channels = new Map<string, PikkuChannelHandler>()
+
+  /**
+   * A map storing topics and their associated connection IDs.
+   */
+  private subscriptions: Map<keyof Data, Set<string>> = new Map()
+
+  /**
+   * Subscribes a connection to a specific topic.
+   * Creates the topic if it does not already exist.
+   * @param topic - The topic to subscribe to.
+   * @param channelId - The unique ID of the connection to subscribe.
+   */
+  public subscribe<T extends keyof Data>(
+    topic: T,
+    channelId: string
+  ): void | Promise<void> {
+    if (!this.subscriptions.has(topic)) {
+      this.subscriptions.set(topic, new Set())
+    }
+    this.subscriptions.get(topic)!.add(channelId)
+  }
+
+  /**
+   * Unsubscribes a connection from a specific topic.
+   * Removes the topic if it has no more subscribers.
+   * @param topic - The topic to unsubscribe from.
+   * @param channelId - The unique ID of the connection to unsubscribe.
+   */
+  public unsubscribe<T extends keyof Data>(
+    topic: T,
+    channelId: string
+  ): void | Promise<void> {
+    const topicSubscriptions = this.subscriptions.get(topic)
+    if (topicSubscriptions) {
+      topicSubscriptions.delete(channelId)
+      if (topicSubscriptions.size === 0) {
+        this.subscriptions.delete(topic)
+      }
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public publish<T extends keyof Data>(
+    topic: T,
+    channelId: string | null,
+    data: Data[T],
+    isBinary?: boolean
+  ): void | Promise<void> {
+    const subscribedChannelIds = this.subscriptions.get(topic)
+    if (!subscribedChannelIds) {
+      return
+    }
+    for (const toChannelId of subscribedChannelIds) {
+      if (channelId === toChannelId) continue // Skip sending to the sender
+      const channel = this.channels.get(toChannelId)
+      if (channel) {
+        channel.send(data, isBinary)
+      } else {
+        // TODO: Websocket is closed, remove the channel from the topic
+      }
+    }
+  }
+
+  /**
+   * Registers a channel on open
+   */
+  public onChannelOpened(channelHandler: PikkuChannelHandler): void {
+    this.channels.set(channelHandler.getChannel().channelId, channelHandler)
+  }
+
+  /**
+   * Handles cleanup when a channel is closed.
+   * Removes the channel from all topics it is subscribed to.
+   * Deletes the topic if no more channels are subscribed to it.
+   * @param channelId - The ID of the channel that was closed.
+   */
+  public onChannelClosed(channelId: string): void {
+    for (const [topic, channelIds] of this.subscriptions.entries()) {
+      channelIds.delete(channelId)
+      if (channelIds.size === 0) {
+        this.subscriptions.delete(topic) // Cleanup empty topics
+      }
+    }
+    this.channels.delete(channelId)
+  }
+}

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

@@ -0,0 +1,20 @@
+import { pikkuState } from '../../pikku-state.js'
+import type { Logger } from '../../services/index.js'
+
+/**
+ * Logs all the loaded channels.
+ * @param logger - A logger for logging information.
+ */
+export const logChannels = (logger: Logger) => {
+  const channels = pikkuState(null, 'channel', 'channels')
+  if (channels.size === 0) {
+    logger.info('No channels added')
+    return
+  }
+
+  let scheduledChannels = 'Channels:'
+  channels.forEach((channel) => {
+    scheduledChannels += `\n\t- ${channel.name} at ${channel.route}`
+  })
+  logger.info(scheduledChannels)
+}

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

@@ -0,0 +1,54 @@
+import { test, beforeEach } from 'node:test'
+import * as assert from 'node:assert/strict'
+import { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js'
+
+// A concrete implementation of the abstract class for testing
+class TestChannelHandler extends PikkuAbstractChannelHandler<
+  { param: string },
+  { msg: string }
+> {
+  public async send(message: { msg: string }, isBinary = false): Promise<void> {
+    // Mock send implementation
+  }
+
+  public sendBinary(_data: ArrayBuffer | Uint8Array): void {}
+}
+
+let handler: TestChannelHandler
+
+beforeEach(() => {
+  handler = new TestChannelHandler('test-channel-id', 'channel-name', {
+    param: 'testParam',
+  })
+})
+
+test('getChannel should return a channel with initial state', () => {
+  const channel = handler.getChannel()
+  assert.equal(channel.channelId, 'test-channel-id', 'Channel ID should match')
+  assert.equal(channel.state, 'initial', 'Initial state should be "initial"')
+  assert.deepEqual(
+    channel.openingData,
+    { param: 'testParam' },
+    'Opening data should be accessible'
+  )
+})
+
+test('open should change channel state to open', () => {
+  handler.open()
+  const channel = handler.getChannel()
+  assert.equal(
+    channel.state,
+    'open',
+    'State should be "open" after calling open()'
+  )
+})
+
+test('close should change channel state to closed', () => {
+  handler.close()
+  const channel = handler.getChannel()
+  assert.equal(
+    channel.state,
+    'closed',
+    'State should be "closed" after calling close()'
+  )
+})

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

@@ -0,0 +1,45 @@
+import type {
+  BinaryData,
+  PikkuChannel,
+  PikkuChannelHandler,
+} from './channel.types.js'
+
+export abstract class PikkuAbstractChannelHandler<
+  OpeningData = unknown,
+  Out = unknown,
+> implements PikkuChannelHandler<OpeningData, Out>
+{
+  protected channel?: PikkuChannel<OpeningData, Out>
+
+  constructor(
+    public channelId: string,
+    public channelName: string,
+    protected openingData: OpeningData
+  ) {}
+
+  public abstract send(message: Out, isBinary?: boolean): Promise<void> | void
+
+  public abstract sendBinary(data: BinaryData): Promise<void> | void
+
+  public getChannel(): PikkuChannel<OpeningData, Out> {
+    if (!this.channel) {
+      this.channel = {
+        channelId: this.channelId,
+        openingData: this.openingData,
+        send: this.send.bind(this),
+        sendBinary: this.sendBinary.bind(this),
+        close: this.close.bind(this),
+        state: 'initial',
+      }
+    }
+    return this.channel
+  }
+
+  public open(): void {
+    this.getChannel().state = 'open'
+  }
+
+  public close(): Promise<void> | void {
+    this.getChannel().state = 'closed'
+  }
+}

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

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