@pikku/core 0.6.9

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

@@ -0,0 +1,56 @@
+import { CoreUserSession } from '../../types/core.types.js'
+import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js'
+
+export class PikkuLocalChannelHandler<
+  UserSession extends CoreUserSession = CoreUserSession,
+  OpeningData = unknown,
+  Out = unknown,
+> extends PikkuAbstractChannelHandler<UserSession, OpeningData, Out> {
+  private onMessageCallback?: (message: unknown) => void
+  private openCallBack?: () => void
+  private closeCallback?: () => void
+  private sendCallback?: (message: Out, isBinary?: boolean) => 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 registerOnClose(callback: () => void): void {
+    this.closeCallback = callback
+  }
+
+  public close() {
+    super.close()
+    this.closeCallback?.()
+  }
+
+  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 setUserSession(userSession: UserSession): void {
+    this.getChannel().userSession = userSession
+  }
+}

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

@@ -0,0 +1,128 @@
+import { test, beforeEach, afterEach } from 'node:test'
+import * as assert from 'node:assert/strict'
+import { JSONValue } from '../../types/core.types.js'
+import { PikkuHTTPAbstractRequest } from '../../http/pikku-http-abstract-request.js'
+import { PikkuHTTPAbstractResponse } from '../../http/pikku-http-abstract-response.js'
+import { runLocalChannel } from './local-channel-runner.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,
+  // Provide a mock channelPermissionService only when needed
+  // e.g., channelPermissionService: { verifyChannelAccess: async () => {} },
+  httpSessionService: {},
+} as any
+
+// Mock request and response objects
+class MockRequest extends PikkuHTTPAbstractRequest {
+  public getBody(): Promise<unknown> {
+    throw new Error('Method not implemented.')
+  }
+  public getHeader(headerName: string): string | undefined {
+    throw new Error('Method not implemented.')
+  }
+  public async getData() {
+    return { test: 'data' }
+  }
+}
+
+class MockResponse extends PikkuHTTPAbstractResponse {
+  public statusSet: boolean | undefined
+  public ended: boolean | undefined
+
+  public setJson(body: JSONValue): void {}
+  public setResponse(response: string | Buffer): void {}
+  public setStatus(code) {
+    this.statusSet = code
+  }
+  public end() {
+    this.ended = true
+  }
+}
+
+const mockCreateSessionServices = async () => ({ sessionServiceMock: true })
+function resetGlobalChannels(channels: any[] = [], channelsMeta: any[] = []) {
+  // If necessary, reinitialize globalThis.pikku
+  if (!globalThis.pikku) {
+    globalThis.pikku = {}
+  }
+  globalThis.pikku.channels = channels
+  globalThis.pikku.channelsMeta = channelsMeta
+  globalThis.pikku.openChannels = new Map()
+}
+
+beforeEach(() => {
+  resetGlobalChannels()
+})
+
+afterEach(() => {
+  resetGlobalChannels()
+})
+
+test('runChannel should return undefined and 404 if no matching channel is found', async () => {
+  // No channels configured
+  resetGlobalChannels()
+
+  const mockResponse = new MockResponse()
+
+  const result = await runLocalChannel({
+    singletonServices: mockSingletonServices,
+    channelId: 'test-channel-id',
+    request: new MockRequest(),
+    response: mockResponse,
+    route: '/non-existent-channel',
+    createSessionServices: mockCreateSessionServices,
+  })
+
+  assert.equal(
+    result,
+    undefined,
+    'Should return undefined if no channel matches'
+  )
+  assert.equal(mockResponse.statusSet, 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 () => {
+  resetGlobalChannels([
+    {
+      route: '/test-channel',
+      auth: false,
+    },
+  ])
+
+  // Provide a fake channelPermissionService if needed
+  const singletonServicesWithPerm = {
+    ...mockSingletonServices,
+    channelPermissionService: {
+      verifyChannelAccess: async () => {},
+    },
+  }
+
+  const result = await runLocalChannel({
+    singletonServices: singletonServicesWithPerm,
+    channelId: 'test-channel-id',
+    request: new MockRequest(),
+    response: new MockResponse(),
+    route: '/test-channel',
+    createSessionServices: mockCreateSessionServices,
+  })
+
+  assert.ok(result, 'Should return a PikkuChannelHandler instance')
+
+  // Simulate opening the channel
+  result.open()
+
+  // TODO: Test that the opened channel works
+})

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

@@ -0,0 +1,94 @@
+import { openChannel } from '../channel-runner.js'
+import {
+  createHTTPInteraction,
+  handleError,
+} from '../../http/http-route-runner.js'
+import { closeSessionServices } from '../../utils.js'
+import { processMessageHandlers } from '../channel-handler.js'
+import {
+  CoreAPIChannel,
+  RunChannelOptions,
+  RunChannelParams,
+} from '../channel.types.js'
+import { PikkuLocalChannelHandler } from './local-channel-handler.js'
+import { SessionServices } from '../../types/core.types.js'
+
+export const runLocalChannel = async ({
+  singletonServices,
+  channelId,
+  request,
+  response,
+  route,
+  createSessionServices,
+  skipUserSession = false,
+  respondWith404 = true,
+  coerceToArray = false,
+  logWarningsForStatusCodes = [],
+  bubbleErrors = false,
+}: Pick<CoreAPIChannel<unknown, any>, 'route'> &
+  RunChannelOptions &
+  RunChannelParams<unknown>): Promise<PikkuLocalChannelHandler | void> => {
+  let sessionServices: SessionServices<typeof singletonServices> | undefined
+
+  const http = createHTTPInteraction(request, response)
+  try {
+    const { userSession, openingData, channelConfig } = await openChannel({
+      channelId,
+      createSessionServices,
+      respondWith404,
+      http,
+      route,
+      singletonServices,
+      skipUserSession,
+      coerceToArray,
+    })
+
+    const channelHandler = new PikkuLocalChannelHandler(
+      channelId,
+      channelConfig.name,
+      userSession,
+      openingData
+    )
+    const channel = channelHandler.getChannel()
+
+    if (createSessionServices) {
+      sessionServices = await createSessionServices(
+        singletonServices,
+        { http },
+        userSession
+      )
+    }
+    const allServices = { ...singletonServices, ...sessionServices }
+
+    channelHandler.registerOnOpen(() => {
+      channelConfig.onConnect?.(allServices, channel)
+    })
+
+    channelHandler.registerOnClose(async () => {
+      channelConfig.onDisconnect?.(allServices, channel)
+      if (sessionServices) {
+        await closeSessionServices(singletonServices.logger, sessionServices)
+      }
+    })
+
+    channelHandler.registerOnMessage(
+      processMessageHandlers(allServices, channelConfig, channelHandler)
+    )
+
+    return channelHandler
+  } catch (e: any) {
+    handleError(
+      e,
+      http,
+      channelId,
+      singletonServices.logger,
+      logWarningsForStatusCodes,
+      respondWith404,
+      bubbleErrors
+    )
+  } finally {
+    if (sessionServices) {
+      await closeSessionServices(singletonServices.logger, sessionServices)
+    }
+  }
+}

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

@@ -0,0 +1,95 @@
+import * as assert from 'assert'
+import { test } from 'node:test'
+import { PikkuChannelHandler } from '../channel.types.js'
+import { 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/channel/local/local-eventhub-service.ts

@@ -0,0 +1,95 @@
+import { PikkuChannelHandler } from '../channel.types.js'
+import { EventHubService } from '../eventhub-service.js'
+
+/**
+ * Implementation of the SubscriptionService interface.
+ * Manages subscriptions and publishes messages to subscribers.
+ */
+export class LocalEventHubService<Data = unknown>
+  implements EventHubService<Data>
+{
+  private channels = new Map<string, PikkuChannelHandler>()
+
+  /**
+   * A map storing topics and their associated connection IDs.
+   */
+  private subscriptions: Map<string, 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(topic: string, channelId: string): 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(topic: string, channelId: string): void {
+    const topicSubscriptions = this.subscriptions.get(topic)
+    if (topicSubscriptions) {
+      topicSubscriptions.delete(channelId)
+      if (topicSubscriptions.size === 0) {
+        this.subscriptions.delete(topic) // Cleanup empty subscriptions
+      }
+    }
+  }
+
+  /**
+   * 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(
+    topic: string,
+    channelId: string,
+    data: Data,
+    isBinary?: boolean
+  ): 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/channel/log-channels.ts

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

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

@@ -0,0 +1,77 @@
+import { test, beforeEach } from 'node:test'
+import * as assert from 'node:assert/strict'
+import { CoreUserSession } from '../types/core.types.js'
+import { PikkuAbstractChannelHandler } from './pikku-abstract-channel-handler.js'
+
+// A concrete implementation of the abstract class for testing
+class TestChannelHandler extends PikkuAbstractChannelHandler<
+  CoreUserSession,
+  { param: string },
+  { msg: string }
+> {
+  public async setUserSession(session: CoreUserSession): Promise<void> {
+    this.userSession = session
+  }
+
+  public async send(message: { msg: string }, isBinary = false): Promise<void> {
+    // Mock send implementation
+  }
+}
+
+let handler: TestChannelHandler
+
+beforeEach(() => {
+  handler = new TestChannelHandler(
+    'test-channel-id',
+    'channel-name',
+    undefined,
+    { 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'
+  )
+  assert.equal(
+    channel.userSession,
+    undefined,
+    'Session should initially be undefined'
+  )
+})
+
+test('setUserSession should update the channel session', async () => {
+  const session = { userId: 'user123' } as CoreUserSession
+  await handler.setUserSession(session)
+  const channel = handler.getChannel()
+  assert.deepEqual(
+    channel.userSession,
+    session,
+    'Session should be updated correctly'
+  )
+})
+
+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/channel/pikku-abstract-channel-handler.ts

@@ -0,0 +1,44 @@
+import { CoreUserSession } from '../types/core.types.js'
+import { PikkuChannel, PikkuChannelHandler } from './channel.types.js'
+
+export abstract class PikkuAbstractChannelHandler<
+  UserSession extends CoreUserSession = CoreUserSession,
+  OpeningData = unknown,
+  Out = unknown,
+> implements PikkuChannelHandler<UserSession, OpeningData, Out>
+{
+  protected channel?: PikkuChannel<UserSession, OpeningData, Out>
+
+  constructor(
+    public channelId: string,
+    public channelName: string,
+    protected userSession: UserSession | undefined,
+    protected openingData: OpeningData
+  ) {}
+
+  public abstract setUserSession(userSession: UserSession): Promise<void> | void
+  public abstract send(message: Out, isBinary?: boolean): Promise<void> | void
+
+  public getChannel(): PikkuChannel<UserSession, OpeningData, Out> {
+    if (!this.channel) {
+      this.channel = {
+        channelId: this.channelId,
+        userSession: this.userSession,
+        openingData: this.openingData,
+        setUserSession: this.setUserSession.bind(this),
+        send: this.send.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/channel/serverless/index.ts

@@ -0,0 +1 @@
+export * from './serverless-channel-runner.js'