@pikku/core 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

package/src/channel/channel-handler.ts

@@ -0,0 +1,165 @@
+import {
+  CoreServices,
+  JSONValue,
+  CoreUserSession,
+} from '../types/core.types.js'
+import {
+  ChannelMessageMeta,
+  CoreAPIChannel,
+  PikkuChannelHandler,
+} from './channel.types.js'
+import { pikkuState } from '../pikku-state.js'
+import { runPikkuFunc } from '../function/function-runner.js'
+
+const getRouteMeta = (
+  channelName: string,
+  routingProperty?: string,
+  routerValue?: string
+): ChannelMessageMeta => {
+  const channelMeta = pikkuState('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.messageRoutes[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,
+  session: CoreUserSession | undefined,
+  channelConfig: CoreAPIChannel<any, any>,
+  channelHandler: PikkuChannelHandler
+) => {
+  const logger = services.logger
+  const requiresSession = channelConfig.auth !== false
+
+  const processMessage = async (
+    data: JSONValue,
+    onMessage: any,
+    session: CoreUserSession | undefined,
+    routingProperty?: string,
+    routerValue?: string
+  ): Promise<unknown> => {
+    if (!validateAuth(requiresSession, channelHandler, 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}`
+      )
+      // TODO: Send error message back breaks typescript, but should be implemented somehow
+      channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`)
+      return
+    }
+
+    const { pikkuFuncName } = getRouteMeta(
+      channelConfig.name,
+      routingProperty,
+      routerValue
+    )
+
+    const permissions =
+      typeof onMessage === 'function' ? {} : onMessage.permissions
+
+    return await runPikkuFunc(pikkuFuncName, {
+      singletonServices: services,
+      getAllServices: () => ({
+        ...services,
+        channel: channelHandler.getChannel(),
+      }),
+      data,
+      session,
+      permissions,
+    })
+  }
+
+  const onMessage = async (rawData): Promise<unknown> => {
+    let result: unknown
+    let processed = false
+
+    // Route-specific handling
+    if (typeof rawData === 'string' && channelConfig.onMessageRoute) {
+      try {
+        const messageData = JSON.parse(rawData)
+        const entries = Object.entries(channelConfig.onMessageRoute)
+        for (const [routingProperty, routes] of entries) {
+          const routerValue = messageData[routingProperty]
+          if (routerValue && routes[routerValue]) {
+            processed = true
+            result = await processMessage(
+              messageData,
+              routes[routerValue],
+              session,
+              routingProperty,
+              routerValue
+            )
+            break
+          }
+        }
+
+        // Default handler if no routes matched but json data was parsed
+        if (!processed && channelConfig.onMessage) {
+          processed = true
+          result = await processMessage(
+            messageData,
+            channelConfig.onMessage,
+            session
+          )
+        }
+      } catch (error) {
+        // Most likely a json error.. ignore
+      }
+    }
+
+    // Default handler if no routes matched and json data wasn't parsed
+    if (!processed && channelConfig.onMessage) {
+      processed = true
+      result = await processMessage(rawData, channelConfig.onMessage, session)
+    }
+
+    if (!processed) {
+      logger.error(
+        `No handler found for message in channel ${channelConfig.name} for ${JSON.stringify(rawData)}`
+      )
+      logger.error(`Channel ${JSON.stringify(channelConfig)}`)
+    }
+
+    return result
+  }
+
+  return onMessage
+}

package/src/channel/channel-runner.ts

@@ -0,0 +1,153 @@
+import { NotFoundError } from '../errors/errors.js'
+import { addFunction } from '../function/function-runner.js'
+import { pikkuState } from '../pikku-state.js'
+import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
+import { UserSessionService } from '../services/user-session-service.js'
+import {
+  ChannelMeta,
+  CoreAPIChannel,
+  RunChannelOptions,
+  RunChannelParams,
+} from './channel.types.js'
+import { match } from 'path-to-regexp'
+
+/**
+ * Adds a channel and registers all functions referenced in it using the
+ * function names already stored in the channel metadata
+ */
+export const addChannel = <
+  In,
+  Channel extends string,
+  ChannelFunction,
+  ChannelFunctionSessionless,
+  APIPermission,
+>(
+  channel: CoreAPIChannel<In, Channel, ChannelFunction, APIPermission>
+) => {
+  // Get the channel metadata
+  const channelsMeta = pikkuState('channel', 'meta')
+  const channelMeta = channelsMeta[channel.name]
+  if (!channelMeta) {
+    throw new Error(`Channel metadata not found for channel: ${channel.name}`)
+  }
+
+  pikkuState('channel', 'channels').set(channel.name, channel as any)
+
+  // Register onConnect function if provided
+  if (channel.onConnect && channelMeta.connectPikkuFuncName) {
+    addFunction(channelMeta.connectPikkuFuncName, channel.onConnect as any)
+  }
+
+  // Register onDisconnect function if provided
+  if (channel.onDisconnect && channelMeta.disconnectPikkuFuncName) {
+    addFunction(
+      channelMeta.disconnectPikkuFuncName,
+      channel.onDisconnect as any
+    )
+  }
+
+  // Register onMessage function if provided
+  if (channel.onMessage && channelMeta.message?.pikkuFuncName) {
+    const messageFunc =
+      typeof channel.onMessage === 'function'
+        ? channel.onMessage
+        : channel.onMessage.func
+    addFunction(channelMeta.message.pikkuFuncName, messageFunc as any)
+  }
+
+  // Register functions in onMessageRoute
+  if (channel.onMessageRoute && channelMeta.messageRoutes) {
+    // Iterate through each channel in onMessageRoute
+    Object.entries(channel.onMessageRoute).forEach(([channelKey, routes]) => {
+      const channelRoutes = channelMeta.messageRoutes[channelKey]
+      if (!channelRoutes) return
+
+      // Iterate through each route in the channel
+      Object.entries(routes).forEach(([routeKey, handler]) => {
+        const routeMeta = channelRoutes[routeKey]
+        if (!routeMeta) return
+
+        // Extract the function from the handler
+        const routeFunc = typeof handler === 'function' ? handler : handler.func
+
+        // Register the function using the pikku name from metadata
+        addFunction(routeMeta.pikkuFuncName, routeFunc as any)
+      })
+    })
+  }
+
+  // Store the channel configuration
+  pikkuState('channel', 'channels').set(channel.name, channel as any)
+}
+
+const getMatchingChannelConfig = (request: string) => {
+  const channels = pikkuState('channel', 'channels')
+  const channelsMeta = pikkuState('channel', 'meta')
+  for (const channelConfig of channels.values()) {
+    const cleanedRoute = channelConfig.route.replace(/^\/\//, '/')
+    const cleanedRequest = request.replace(/^\/\//, '/')
+    const matchFunc = match(cleanedRoute, {
+      decode: decodeURIComponent,
+    })
+    const matchedPath = matchFunc(cleanedRequest)
+    if (matchedPath) {
+      const channelMeta = channelsMeta[channelConfig.name]
+      if (!channelMeta) {
+        throw new Error(`Channel ${channelConfig.name} not found in metadata`)
+      }
+      return {
+        matchedPath,
+        params: matchedPath.params,
+        channelConfig,
+        schemaName: channelMeta.input,
+        meta: channelMeta,
+      }
+    }
+  }
+  return null
+}
+
+export const openChannel = async ({
+  route,
+  singletonServices,
+  coerceDataFromSchema = true,
+  request,
+}: Pick<CoreAPIChannel<unknown, string>, 'route'> &
+  RunChannelParams<unknown> & {
+    userSession: UserSessionService<any>
+  } & RunChannelOptions): Promise<{
+  openingData: unknown
+  channelConfig: CoreAPIChannel<unknown, any>
+  meta: ChannelMeta
+}> => {
+  const matchingChannel = getMatchingChannelConfig(route)
+  if (!matchingChannel) {
+    singletonServices.logger.info(`Channel not found: ${route}`)
+    throw new NotFoundError(`Channel not found: ${route}`)
+  }
+
+  const { params, channelConfig, schemaName, meta } = matchingChannel
+
+  const requiresSession = channelConfig.auth !== false
+  request?.setParams(params)
+
+  singletonServices.logger.info(
+    `Matched channel: ${channelConfig.name} | route: ${channelConfig.route} | auth: ${requiresSession.toString()}`
+  )
+
+  let openingData: any | undefined
+  if (request) {
+    openingData = await request.data()
+    if (coerceDataFromSchema && schemaName) {
+      coerceTopLevelDataFromSchema(schemaName, openingData)
+    }
+    await validateSchema(
+      singletonServices.logger,
+      singletonServices.schema,
+      schemaName,
+      openingData
+    )
+  }
+
+  return { openingData, channelConfig, meta }
+}

package/src/channel/channel-store.ts

@@ -0,0 +1,29 @@
+import { CoreUserSession } from '../types/core.types.js'
+
+export type Channel<ChannelType = unknown, OpeningData = unknown> = {
+  channelId: string
+  channelName: string
+  channelObject?: ChannelType
+  openingData?: OpeningData
+}
+
+export abstract class ChannelStore<
+  ChannelType = unknown,
+  OpeningData = unknown,
+  UserSession extends CoreUserSession = CoreUserSession,
+  TypedChannel = Channel<ChannelType, OpeningData>,
+> {
+  public abstract addChannel(
+    channel: Channel<ChannelType, OpeningData>
+  ): Promise<void> | void
+  public abstract removeChannels(channelId: string[]): Promise<void> | void
+  public abstract setUserSession(
+    channelId: string,
+    userSession: UserSession | null
+  ): Promise<void> | void
+  public abstract getChannelAndSession(
+    channelId: string
+  ):
+    | Promise<TypedChannel & { session: UserSession }>
+    | (TypedChannel & { session: UserSession })
+}

package/src/channel/channel.types.ts

@@ -0,0 +1,133 @@
+import { PikkuError } from '../errors/error-handler.js'
+import {
+  HTTPFunctionMetaInputTypes,
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
+} from '../http/http.types.js'
+import {
+  APIDocs,
+  CoreSingletonServices,
+  CreateSessionServices,
+  PikkuMiddleware,
+} from '../types/core.types.js'
+import {
+  CoreAPIFunction,
+  CoreAPIFunctionSessionless,
+  CoreAPIPermission,
+} 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
+  singletonServices: CoreSingletonServices
+  request?: PikkuHTTPRequest<ChannelData>
+  response?: PikkuHTTPResponse
+  createSessionServices?: CreateSessionServices
+}
+
+export interface ChannelMessageMeta {
+  pikkuFuncName: string
+  inputs: string[] | null
+  outputs: string[] | null
+  docs?: APIDocs
+}
+
+export interface ChannelMeta {
+  name: string
+  route: string
+  params?: string[]
+  query?: string[]
+  input: string | null
+  inputTypes?: HTTPFunctionMetaInputTypes
+  connect: boolean
+  connectPikkuFuncName: string | null
+  disconnect: boolean
+  disconnectPikkuFuncName: string | null
+  message: ChannelMessageMeta | null
+  messageRoutes: Record<string, Record<string, ChannelMessageMeta>>
+  docs?: APIDocs
+  tags?: string[]
+}
+
+export type ChannelsMeta = Record<string, ChannelMeta>
+
+export type CoreAPIChannel<
+  ChannelData,
+  Channel extends string,
+  ChannelConnect =
+    | CoreAPIFunction<void, unknown, ChannelData>
+    | CoreAPIFunctionSessionless<void, unknown, ChannelData>,
+  ChannelDisconnect =
+    | CoreAPIFunction<void, void, ChannelData>
+    | CoreAPIFunctionSessionless<void, void, ChannelData>,
+  ChannelFunctionMessage =
+    | CoreAPIFunction<unknown, unknown, ChannelData>
+    | CoreAPIFunctionSessionless<unknown, unknown, ChannelData>,
+  APIPermission = CoreAPIPermission<ChannelData>,
+> = {
+  name: string
+  route: Channel
+  onConnect?: ChannelConnect
+  onDisconnect?: ChannelDisconnect
+  onMessage?:
+    | {
+        func: ChannelFunctionMessage
+        permissions?: Record<string, APIPermission[] | APIPermission>
+        auth?: boolean
+      }
+    | ChannelFunctionMessage
+  onMessageRoute?: Record<
+    string,
+    Record<
+      string,
+      | ChannelFunctionMessage
+      | {
+          func: ChannelFunctionMessage
+          permissions?: Record<string, APIPermission[] | APIPermission>
+          auth?: boolean
+        }
+    >
+  >
+  middleware?: PikkuMiddleware[]
+  permissions?: Record<string, APIPermission[] | APIPermission>
+  auth?: boolean
+  docs?: Partial<{
+    description: string
+    response: string
+    errors: Array<typeof PikkuError>
+    tags: string[]
+  }>
+  tags?: string[]
+}
+
+export interface PikkuChannel<OpeningData, 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
+  // 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
+  getChannel(): PikkuChannel<OpeningData, Out>
+}
+
+export type PikkuChannelHandlerFactory<OpeningData = unknown, Out = unknown> = (
+  channelId: string,
+  channelName: string,
+  openingData: OpeningData
+) => PikkuChannelHandler<OpeningData, Out>

package/src/channel/eventhub-service.ts

@@ -0,0 +1,30 @@
+/**
+ * Interface defining the methods of a EventHub Service.
+ */
+export interface EventHubService<Out = unknown> {
+  /**
+   * 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(topic: string, 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(topic: string, 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(
+    topic: string,
+    channelId: string | null,
+    data: Out,
+    isBinary?: boolean
+  ): Promise<void> | void
+}

package/src/channel/eventhub-store.ts

@@ -0,0 +1,8 @@
+export abstract class EventHubStore {
+  public abstract getChannelIdsForTopic(topic: string): Promise<string[]>
+  public abstract subscribe(topic: string, channelId: string): Promise<boolean>
+  public abstract unsubscribe(
+    topic: string,
+    channelId: string
+  ): Promise<boolean>
+}

package/src/channel/index.ts

@@ -0,0 +1,8 @@
+export * from './channel-runner.js'
+export * from './channel.types.js'
+export * from './log-channels.js'
+export * from './pikku-abstract-channel-handler.js'
+export * from './eventhub-service.js'
+export * from './eventhub-service.js'
+export * from './channel-store.js'
+export * from './eventhub-store.js'

package/src/channel/local/index.ts

@@ -0,0 +1,3 @@
+export * from './local-channel-handler.js'
+export * from './local-channel-runner.js'
+export * from './local-eventhub-service.js'

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

@@ -0,0 +1,50 @@
+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 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)
+  }
+}