@pikku/core 0.6.9

package/run-tests.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# Enable nullglob to handle cases where no files match the pattern
+shopt -s nullglob
+
+# Initialize variables for options
+watch_mode=false
+coverage_mode=false
+
+# Parse command-line options
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --watch)
+      watch_mode=true
+      shift
+      ;;
+    --coverage)
+      coverage_mode=true
+      shift
+      ;;
+    *)
+      echo "Unknown option: $1"
+      exit 1
+      ;;
+  esac
+done
+
+# Define the pattern to match your test files
+pattern="src/*.test.ts"
+
+# Expand the pattern into an array of files
+files=($(find src -type f -name "*.test.ts"))
+
+# Check if any files matched the pattern
+if [ ${#files[@]} -eq 0 ]; then
+  echo "No test files found matching pattern: $pattern"
+  exit 0
+fi
+
+# Construct the node command
+node_cmd="node --import tsx --test"
+
+# Append options based on flags
+if [ "$watch_mode" = true ]; then
+  node_cmd="$node_cmd --watch"
+fi
+
+if [ "$coverage_mode" = true ]; then
+  node_cmd="$node_cmd --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info"
+fi
+
+# Execute the node command with the expanded list of files
+$node_cmd "${files[@]}"

package/src/channel/channel-handler.ts

@@ -0,0 +1,179 @@
+import {
+  CoreSingletonServices,
+  CoreServices,
+  CoreUserSession,
+  JSONValue,
+} from '../types/core.types.js'
+import { CoreAPIChannel, PikkuChannelHandler } from './channel.types.js'
+import { verifyPermissions } from '../permissions.js'
+import { getChannels } from './channel-runner.js'
+
+const validateSchema = (
+  logger: CoreSingletonServices['logger'],
+  data: JSONValue,
+  channelName: string,
+  routingProperty?: string,
+  routerValue?: string
+) => {
+  const { channelsMeta } = getChannels()
+  for (const channelMeta of channelsMeta) {
+    if (routingProperty && routerValue) {
+      const channelRoute =
+        channelMeta.messageRoutes[routingProperty]?.[routerValue]
+      if (channelRoute) {
+        const schemaNames = channelRoute.inputs
+        if (schemaNames) {
+          // TODO
+          // loadSchema(schemaNames, logger)
+          // validateJson(schemaNames, data)
+        }
+        return
+      }
+    }
+  }
+}
+
+const validateAuth = (
+  requiresSession: boolean,
+  channelHandler: PikkuChannelHandler,
+  onMessage: any
+) => {
+  const auth =
+    typeof onMessage === 'function'
+      ? requiresSession
+      : onMessage.auth === undefined
+        ? requiresSession
+        : onMessage.auth
+
+  if (auth && !channelHandler.getChannel().userSession) {
+    return false
+  }
+  return true
+}
+
+const validatePermissions = async (
+  services: CoreServices,
+  channelHandler: PikkuChannelHandler,
+  onMessage: any,
+  data: unknown
+) => {
+  const permissions =
+    typeof onMessage === 'function' ? {} : onMessage.permissions
+  return await verifyPermissions(
+    permissions,
+    services,
+    data,
+    channelHandler.getChannel().userSession
+  )
+}
+
+const runFunction = async (
+  services: CoreServices,
+  channelHandler: PikkuChannelHandler,
+  onMessage: any,
+  data: unknown
+) => {
+  const func: any = typeof onMessage === 'function' ? onMessage : onMessage.func
+  return await func(services, channelHandler.getChannel(), data)
+}
+
+export const processMessageHandlers = (
+  services: CoreServices,
+  channelConfig: CoreAPIChannel<any, any>,
+  channelHandler: PikkuChannelHandler<CoreUserSession, unknown>
+) => {
+  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, 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
+    }
+
+    validateSchema(
+      services.logger,
+      data,
+      channelConfig.name,
+      routingProperty,
+      routerValue
+    )
+
+    const hasPermission = await validatePermissions(
+      services,
+      channelHandler,
+      onMessage,
+      data
+    )
+    if (!hasPermission) {
+      logger.error(
+        `Channel ${channelConfig.name} requires permissions for ${routingProperty || 'default message route'}`
+      )
+    }
+
+    return await runFunction(services, channelHandler, onMessage, data)
+  }
+
+  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],
+              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)
+        }
+      } 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)
+    }
+
+    if (!processed) {
+      logger.error(
+        `No handler found for message in channel ${channelConfig.name} for ${rawData}`
+      )
+      logger.error(`Channel ${channelConfig}`)
+    }
+
+    return result
+  }
+
+  return onMessage
+}

package/src/channel/channel-runner.ts

@@ -0,0 +1,156 @@
+import { NotFoundError } from '../errors/errors.js'
+import { loadUserSession } from '../http/http-route-runner.js'
+import { validateAndCoerce } from '../schema.js'
+import { CoreUserSession } from '../types/core.types.js'
+import {
+  CoreAPIChannel,
+  ChannelsMeta,
+  CoreAPIChannels,
+  RunChannelOptions,
+  RunChannelParams,
+} from './channel.types.js'
+import { match } from 'path-to-regexp'
+
+if (!globalThis.pikku?.channels) {
+  globalThis.pikku = globalThis.pikku || {}
+  globalThis.pikku.channels = []
+  globalThis.pikku.channelsMeta = []
+}
+
+const channels = (data?: any): CoreAPIChannels => {
+  if (data) {
+    globalThis.pikku.channels = data
+  }
+  return globalThis.pikku.channels
+}
+
+const channelsMeta = (data?: any): ChannelsMeta => {
+  if (data) {
+    globalThis.pikku.channelsMeta = data
+  }
+  return globalThis.pikku.channelsMeta
+}
+
+/**
+ * Returns all the registered routes and associated metadata.
+ * @internal
+ */
+export const getChannels = () => {
+  return {
+    channels: channels(),
+    channelsMeta: channelsMeta(),
+  }
+}
+
+export const addChannel = <
+  In,
+  Channel extends string,
+  ChannelFunction,
+  ChannelFunctionSessionless,
+  APIPermission,
+>(
+  channel: CoreAPIChannel<
+    In,
+    Channel,
+    ChannelFunction,
+    ChannelFunctionSessionless,
+    APIPermission
+  >
+) => {
+  channels().push(channel as any)
+}
+
+/**
+ * @ignore
+ */
+export const setChannelsMeta = (_channelsMeta: ChannelsMeta) => {
+  channelsMeta(_channelsMeta)
+}
+
+export const getMatchingChannelConfig = (request: string) => {
+  const { channels, channelsMeta } = getChannels()
+  for (const channelConfig of channels) {
+    const cleanedRoute = channelConfig.route.replace(/^\/\//, '/')
+    const cleanedRequest = request.replace(/^\/\//, '/')
+    const matchFunc = match(cleanedRoute, {
+      decode: decodeURIComponent,
+    })
+    const matchedPath = matchFunc(cleanedRequest)
+    if (matchedPath) {
+      const schemaName = channelsMeta.find(
+        (channelMeta) => channelMeta.route === channelConfig.route
+      )?.input
+      return {
+        matchedPath,
+        params: matchedPath.params,
+        channelConfig,
+        schemaName,
+      }
+    }
+  }
+
+  return null
+}
+
+export const openChannel = async ({
+  route,
+  singletonServices,
+  skipUserSession = false,
+  coerceToArray = false,
+  http,
+}: Pick<CoreAPIChannel<unknown, string>, 'route'> &
+  Omit<RunChannelParams<unknown>, 'response' | 'request'> &
+  RunChannelOptions): Promise<{
+  userSession?: CoreUserSession
+  openingData: unknown
+  channelConfig: CoreAPIChannel<unknown, any>
+}> => {
+  const matchingChannel = getMatchingChannelConfig(route)
+  if (!matchingChannel) {
+    singletonServices.logger.info(`Channel not found: ${route}`)
+    throw new NotFoundError(`Channel not found: ${route}`)
+  }
+
+  const { matchedPath, params, channelConfig, schemaName } = matchingChannel
+
+  const requiresSession = channelConfig.auth !== false
+  http?.request?.setParams(params)
+
+  singletonServices.logger.info(
+    `Matched channel: ${channelConfig.name} | route: ${channelConfig.route} | auth: ${requiresSession.toString()}`
+  )
+
+  const userSession = await loadUserSession(
+    skipUserSession,
+    // We may require a session, but we don't actually need it
+    // on connect since channels can authenticate later given
+    // how websocket sessions work (cookie or queryParam based)
+    false,
+    http,
+    matchedPath,
+    channelConfig,
+    singletonServices.logger,
+    singletonServices.httpSessionService
+  )
+
+  if (singletonServices.enforceChannelAccess) {
+    await singletonServices.enforceChannelAccess(
+      matchingChannel.channelConfig,
+      userSession
+    )
+  }
+
+  let openingData: any | undefined
+  if (http?.request) {
+    openingData = await http.request.getData()
+    validateAndCoerce(
+      singletonServices.logger,
+      singletonServices.schemaService,
+      schemaName,
+      openingData,
+      coerceToArray
+    )
+  }
+
+  return { userSession, openingData, channelConfig }
+}

package/src/channel/channel-store.ts

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

package/src/channel/channel.types.ts

@@ -0,0 +1,202 @@
+import { EError } from '../errors/error-handler.js'
+import {
+  HTTPFunctionMetaInputTypes,
+  PikkuHTTP,
+} from '../http/http-routes.types.js'
+import { PikkuHTTPAbstractRequest } from '../http/pikku-http-abstract-request.js'
+import { PikkuHTTPAbstractResponse } from '../http/pikku-http-abstract-response.js'
+import {
+  APIDocs,
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+  CreateSessionServices,
+  MakeRequired,
+} from '../types/core.types.js'
+import { CoreAPIPermission } from '../types/functions.types.js'
+import { PikkuRequest } from '../pikku-request.js'
+import { PikkuResponse } from '../pikku-response.js'
+
+export type RunChannelOptions = Partial<{
+  skipUserSession: boolean
+  respondWith404: boolean
+  coerceToArray: boolean
+  logWarningsForStatusCodes: number[]
+  bubbleErrors: boolean
+}>
+
+export type RunChannelParams<ChannelData> = {
+  channelId: string
+  singletonServices: MakeRequired<CoreSingletonServices, 'eventHub'>
+  request?: PikkuRequest<ChannelData> | PikkuHTTPAbstractRequest<ChannelData>
+  response?: PikkuResponse | PikkuHTTPAbstractResponse
+  http?: PikkuHTTP
+  createSessionServices?: CreateSessionServices
+}
+
+export interface HandlerMeta {}
+
+export interface ChannelMeta {
+  name: string
+  route: string
+  params?: string[]
+  query?: string[]
+  input: string | null
+  inputTypes?: HTTPFunctionMetaInputTypes
+  connect: boolean
+  disconnect: boolean
+  message: { inputs: string[] | null; outputs: string[] | null } | null
+  messageRoutes: Record<
+    string,
+    Record<
+      string,
+      {
+        inputs: string[] | null
+        outputs: string[] | null
+      }
+    >
+  >
+  docs?: APIDocs
+}
+
+export type ChannelsMeta = ChannelMeta[]
+
+export type CoreChannelConnection<
+  ChannelData,
+  Out = unknown,
+  Services extends CoreServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = (
+  services: MakeRequired<Services, 'eventHub'>,
+  channel: PikkuChannel<Session, ChannelData, Out>
+) => Promise<void>
+
+export type CoreChannelDisconnection<
+  ChannelData,
+  Services extends CoreServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = (
+  services: MakeRequired<Services, 'eventHub'>,
+  channel: PikkuChannel<Session, ChannelData, never>
+) => Promise<void>
+
+/**
+ * Represents a core channel function that performs an operation using core services and a user session.
+ *
+ * @template In - The input type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CoreChannelMessage<
+  In,
+  Out,
+  ChannelData,
+  Services extends CoreServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = (
+  services: MakeRequired<Services, 'eventHub'>,
+  channel: PikkuChannel<Session, ChannelData, Out>,
+  data: In
+) => Promise<void | Out>
+
+export type CoreAPIChannelMessage<
+  ChannelFunctionMessage = CoreChannelMessage<unknown, unknown, unknown>,
+> = {
+  func: ChannelFunctionMessage
+  route: string
+}
+
+export type CoreAPIChannel<
+  ChannelData,
+  Channel extends string,
+  ChannelFunctionConnection = CoreChannelConnection<ChannelData>,
+  ChannelFunctionDisconnection = CoreChannelConnection<ChannelData>,
+  ChannelFunctionDefaultMessage = CoreChannelMessage<unknown, unknown, unknown>,
+  ChannelFunctionMessageRoute = CoreChannelMessage<unknown, unknown, unknown>,
+  APIPermission = CoreAPIPermission<ChannelData>,
+> = {
+  name: string
+  route: Channel
+  onConnect?: ChannelFunctionConnection
+  onDisconnect?: ChannelFunctionDisconnection
+  onMessage?:
+    | {
+        func: ChannelFunctionDefaultMessage
+        permissions?: Record<string, APIPermission[] | APIPermission>
+        auth?: boolean
+      }
+    | ChannelFunctionDefaultMessage
+  onMessageRoute?: Record<
+    string,
+    Record<
+      string,
+      | ChannelFunctionMessageRoute
+      | {
+          func: ChannelFunctionMessageRoute
+          permissions?: Record<string, APIPermission[] | APIPermission>
+          auth?: boolean
+        }
+    >
+  >
+  permissions?: Record<string, APIPermission[] | APIPermission>
+  auth?: boolean
+  docs?: Partial<{
+    description: string
+    response: string
+    errors: Array<typeof EError>
+    tags: string[]
+  }>
+}
+
+export type CoreAPIChannels = CoreAPIChannel<any, string>[]
+
+export interface PikkuChannel<UserSession, OpeningData, Out> {
+  // The channel identifier
+  channelId: string
+  // The user session, if available
+  userSession?: UserSession
+  // Update the user session, useful if you deal with auth on the
+  // stream side
+  setUserSession: (userSession: UserSession) => Promise<void> | void
+  // 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<
+  UserSession extends CoreUserSession = CoreUserSession,
+  OpeningData = unknown,
+  Out = unknown,
+> {
+  setUserSession(session: UserSession): Promise<void> | void
+  send(message: Out, isBinary?: boolean): Promise<void> | void
+  getChannel(): PikkuChannel<UserSession, OpeningData, Out>
+}
+
+export type PikkuChannelHandlerFactory<
+  OpeningData = unknown,
+  UserSession extends CoreUserSession = CoreUserSession,
+  Out = unknown,
+> = (
+  channelId: string,
+  channelName: string,
+  openingData: OpeningData,
+  userSession: UserSession | undefined
+) => PikkuChannelHandler<UserSession, OpeningData, Out>
+
+/**
+ * Enfore access to a channel.
+ * @param route - The channel to verify access for.
+ * @param session - The user session.
+ * @returns A promise that resolves if access is granted.
+ */
+export type enforceChannelAccess = (
+  channel: CoreAPIChannel<unknown, any>,
+  session?: CoreUserSession
+) => Promise<void> | void

package/src/channel/eventhub-forwarder.ts

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

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,9 @@
+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-forwarder.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'