@pikku/core 0.6.9

package/src/http/http-routes.types.ts

@@ -0,0 +1,189 @@
+import { EError } from '../errors/error-handler.js'
+import {
+  APIDocs,
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+  CreateSessionServices,
+} from '../types/core.types.js'
+import {
+  CoreAPIFunction,
+  CoreAPIFunctionSessionless,
+  CoreAPIPermission,
+} from '../types/functions.types.js'
+import { PikkuRequest } from '../pikku-request.js'
+import { PikkuResponse } from '../pikku-response.js'
+import { PikkuHTTPAbstractRequest } from './pikku-http-abstract-request.js'
+import { PikkuHTTPAbstractResponse } from './pikku-http-abstract-response.js'
+
+type ExtractRouteParams<S extends string> =
+  S extends `${string}:${infer Param}/${infer Rest}`
+    ? Param | ExtractRouteParams<`/${Rest}`>
+    : S extends `${string}:${infer Param}`
+      ? Param
+      : never
+
+export type AssertRouteParams<In, Route extends string> =
+  ExtractRouteParams<Route> extends keyof In
+    ? unknown
+    : ['Error: Route parameters', ExtractRouteParams<Route>, 'not in', keyof In]
+
+export type RunRouteOptions = Partial<{
+  skipUserSession: boolean
+  respondWith404: boolean
+  logWarningsForStatusCodes: number[]
+  coerceToArray: boolean
+  bubbleErrors: boolean
+}>
+
+export type RunRouteParams<In> = {
+  singletonServices: CoreSingletonServices
+  request: PikkuRequest<In> | PikkuHTTPAbstractRequest<In>
+  response?: PikkuResponse | PikkuHTTPAbstractResponse | undefined
+  createSessionServices: CreateSessionServices<
+    CoreSingletonServices,
+    CoreServices<CoreSingletonServices>,
+    CoreUserSession
+  >
+}
+
+/**
+ * Represents the HTTP methods supported for API routes.
+ */
+export type HTTPMethod =
+  | 'post'
+  | 'get'
+  | 'delete'
+  | 'patch'
+  | 'head'
+  | 'put'
+  | 'options'
+
+/**
+ * Represents an API route without a function, including metadata such as content type, route, and timeout settings.
+ */
+export type CoreHTTPFunction = {
+  contentType?: 'xml' | 'json'
+  route: string
+  eventChannel?: false
+  returnsJSON?: false
+  timeout?: number
+  docs?: Partial<{
+    description: string
+    response: string
+    errors: Array<typeof EError>
+    tags: string[]
+  }>
+}
+/**
+ * Represents a http interaction within Pikku, including a request and response.
+ */
+export interface PikkuHTTP {
+  request?: PikkuHTTPAbstractRequest
+  response?: PikkuHTTPAbstractResponse
+}
+
+/**
+ * Represents request headers as either a record or a function to get headers by name.
+ */
+export type RequestHeaders =
+  | Record<string, string | string[] | undefined>
+  | ((headerName: string) => string | string[] | undefined)
+
+/**
+ * Represents a query object for Pikku, where each key can be a string, a value, or an array of values.
+ */
+export type PikkuQuery<T = Record<string, string | undefined>> = Record<
+  string,
+  string | T | null | Array<T | null>
+>
+
+/**
+ * Represents a core API route, which can have different configurations depending on whether it requires authentication and permissions.
+ *
+ * @template In - The input type.
+ * @template Out - The output type.
+ * @template R - The route string type.
+ * @template APIFunction - The API function type, defaults to `CoreAPIFunction`.
+ * @template APIFunctionSessionless - The sessionless API function type, defaults to `CoreAPIFunctionSessionless`.
+ * @template APIPermission - The permission function type, defaults to `CoreAPIPermission`.
+ */
+export type CoreHTTPFunctionRoute<
+  In,
+  Out,
+  R extends string,
+  APIFunction = CoreAPIFunction<In, Out>,
+  APIFunctionSessionless = CoreAPIFunctionSessionless<In, Out>,
+  APIPermission = CoreAPIPermission<In>,
+> =
+  | (CoreHTTPFunction & {
+      route: R
+      method: HTTPMethod
+      func: APIFunction
+      permissions?: Record<string, APIPermission[] | APIPermission>
+      auth?: true
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: HTTPMethod
+      func: APIFunctionSessionless
+      permissions?: undefined
+      auth?: false
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: 'post'
+      func: APIFunction
+      permissions?: Record<string, APIPermission[] | APIPermission>
+      auth?: true
+      query?: Array<keyof In>
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: 'post'
+      func: APIFunctionSessionless
+      permissions?: undefined
+      auth?: false
+      query?: Array<keyof In>
+    })
+
+/**
+ * Represents an array of core API routes.
+ */
+export type CoreHTTPFunctionRoutes = Array<
+  CoreHTTPFunctionRoute<any, any, string>
+>
+
+/**
+ * Represents the input types for route metadata, including parameters, query, and body types.
+ */
+export type HTTPFunctionMetaInputTypes = {
+  params?: string
+  query?: string
+  body?: string
+}
+
+/**
+ * Represents metadata for a set of routes, including route details, methods, input/output types, and documentation.
+ */
+export type HTTPRoutesMeta = Array<{
+  route: string
+  method: HTTPMethod
+  params?: string[]
+  query?: string[]
+  input: string | null
+  output: string | null
+  inputTypes?: HTTPFunctionMetaInputTypes
+  docs?: APIDocs
+}>
+
+/**
+ * Verifies access to a route.
+ * @param route - The route to verify access for.
+ * @param session - The user session.
+ * @returns A promise that resolves if access is granted.
+ */
+export type enforceHTTPAccess = (
+  route: CoreHTTPFunctionRoute<unknown, unknown, any>,
+  session?: CoreUserSession
+) => Promise<void> | void

package/src/http/http-session-service.ts

@@ -0,0 +1,19 @@
+import { CoreUserSession } from '../types/core.types.js'
+import { PikkuHTTPAbstractRequest } from './pikku-http-abstract-request.js'
+
+/**
+ * Interface for handling user sessions.
+ * @template UserSession - The type of the user session.
+ */
+export interface HTTPSessionService<UserSession = CoreUserSession> {
+  /**
+   * Retrieves the user session.
+   * @param credentialsRequired - A flag indicating whether credentials are required.
+   * @param pikkuRequest - The request object.
+   * @returns A promise that resolves to the user session or undefined.
+   */
+  getUserSession: (
+    credentialsRequired: boolean,
+    pikkuRequest: PikkuHTTPAbstractRequest
+  ) => Promise<UserSession | undefined>
+}

package/src/http/index.ts

@@ -0,0 +1,16 @@
+export * from './pikku-http-session-service.js'
+
+export * from './pikku-http-abstract-request.js'
+
+export * from './pikku-http-abstract-response.js'
+
+export * from './log-http-routes.js'
+
+export {
+  runHTTPRoute,
+  getRoutes,
+  setHTTPRoutesMeta,
+  addRoute,
+} from './http-route-runner.js'
+
+export type * from './http-routes.types.js'

package/src/http/log-http-routes.ts

@@ -0,0 +1,20 @@
+import { Logger } from '../services/index.js'
+import { getRoutes } from './http-route-runner.js'
+
+/**
+ * Logs all the loaded routes.
+ * @param logger - A logger for logging information.
+ */
+export const logRoutes = (logger: Logger) => {
+  const { routes } = getRoutes()
+  if (routes.length === 0) {
+    logger.info('No routes added')
+    return
+  }
+
+  let routesMessage = 'Routes loaded:'
+  for (const { method, route } of routes) {
+    routesMessage += `\n\t- ${method.toUpperCase()} -> ${route}`
+  }
+  logger.info(routesMessage)
+}

package/src/http/pikku-http-abstract-request.ts

@@ -0,0 +1,95 @@
+import { parse as parseCookie } from 'cookie'
+import { PikkuRequest } from '../pikku-request.js'
+import { PikkuQuery } from './http-routes.types.js'
+
+/**
+ * Abstract class representing a pikku request.
+ * @template In - The type of the request body.
+ * @group RequestResponse
+ */
+export abstract class PikkuHTTPAbstractRequest<
+  In = unknown,
+> extends PikkuRequest<In> {
+  private params: Partial<Record<string, string | string[]>> = {}
+
+  /**
+   * Retrieves the request body.
+   * @returns A promise that resolves to the request body.
+   */
+  public abstract getBody(): Promise<In>
+
+  /**
+   * Retrieves the raw request body as a Buffer.
+   * @returns A promise that resolves to the raw request body.
+   */
+  public getRawBody(): Promise<Buffer> {
+    throw new Error('Method not implemented.')
+  }
+
+  /**
+   * Retrieves the value of a specific header.
+   * @param headerName - The name of the header to retrieve.
+   * @returns The value of the header, or undefined if the header is not found.
+   */
+  public abstract getHeader(headerName: string): string | undefined
+
+  /**
+   * Retrieves the cookies from the request.
+   * @returns An object containing the cookies.
+   */
+  public getCookies(): Partial<Record<string, string>> {
+    const cookieHeader = this.getHeader('cookie')
+    if (cookieHeader) {
+      return parseCookie(cookieHeader)
+    }
+    return {}
+  }
+
+  /**
+   * Retrieves the request parameters.
+   * @returns An object containing the request parameters.
+   */
+  public getParams(): Partial<Record<string, string | string[]>> {
+    return this.params
+  }
+
+  /**
+   * Sets the request parameters.
+   * @param params - An object containing the request parameters to set.
+   */
+  public setParams(
+    params: Record<string, string | string[] | undefined>
+  ): void {
+    this.params = params
+  }
+
+  /**
+   * Retrieves the query parameters from the request.
+   * @returns An object containing the query parameters.
+   */
+  public getQuery(): PikkuQuery {
+    return {}
+  }
+
+  /**
+   * Retrieves the IP address of the client making the request.
+   * @returns The IP address of the client.
+   * @throws {Error} This method is not implemented and should be overridden by subclasses.
+   */
+  public getIP(): string {
+    throw new Error('Method not implemented.')
+  }
+
+  /**
+   * Retrieves the combined data from the request, including parameters, query, and body.
+   * @returns A promise that resolves to an object containing the combined data.
+   */
+  public async getData(): Promise<In> {
+    return {
+      ...this.getParams(),
+      ...this.getQuery(),
+      // TODO: If body isn't an object, we should insert it as the word...
+      ...(await this.getBody()),
+    }
+  }
+}

package/src/http/pikku-http-abstract-response.ts

@@ -0,0 +1,79 @@
+import { SerializeOptions, serialize } from 'cookie'
+import { JSONValue } from '../types/core.types.js'
+import { PikkuResponse } from '../pikku-response.js'
+
+/**
+ * Abstract class representing a pikku response.
+ * @group RequestResponse
+ */
+export abstract class PikkuHTTPAbstractResponse extends PikkuResponse {
+  /**
+   * Sets the HTTP status code for the response.
+   * @param status - The HTTP status code to set.
+   */
+  public abstract setStatus(status: number): void
+
+  /**
+   * Sets the JSON body for the response.
+   * @param body - The JSON body to set.
+   */
+  public abstract setJson(body: JSONValue): void
+
+  /**
+   * Sets the response content.
+   * @param response - The response content, which can be a string or a Buffer.
+   */
+  public abstract setResponse(response: string | Buffer): void
+
+  /**
+   * Sets a header for the response.
+   * @param name - The name of the header.
+   * @param value - The value of the header, which can be a string, boolean, or an array of strings.
+   */
+  public setHeader(name: string, value: string | boolean | string[]) {
+    throw new Error('Method not implemented.')
+  }
+
+  /**
+   * Sets multiple headers for the response.
+   * @param headers - An object containing header names and values.
+   */
+  public setHeaders(headers: Record<string, string>) {
+    for (const [name, value] of Object.entries(headers)) {
+      this.setHeader(name, value)
+    }
+  }
+
+  /**
+   * Sets a cookie for the response.
+   * @param name - The name of the cookie.
+   * @param value - The value of the cookie.
+   * @param options - Options for cookie serialization.
+   */
+  public setCookie(name: string, value: string, options: SerializeOptions) {
+    this.setHeader('set-cookie', serialize(name, value, options))
+  }
+
+  /**
+   * Clears a cookie from the response.
+   * @param name - The name of the cookie to clear.
+   */
+  public clearCookie(name: string): void {
+    this.setHeader('set-cookie', serialize(name, '', { expires: new Date(0) }))
+  }
+
+  /**
+   * Sets a redirect for the response.
+   * @param path - The path to redirect to.
+   * @param status - The HTTP status code for the redirect.
+   */
+  public setRedirect(path: string, status: number) {
+    throw new Error('Method not implemented.')
+  }
+
+  /**
+   * Informs the response that it has ended, useful for when setting
+   * a status without a body or response.
+   */
+  public end() {}
+}

package/src/http/pikku-http-session-service.test.ts

@@ -0,0 +1,106 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { InvalidSessionError, MissingSessionError } from '../errors/errors.js'
+import { PikkuHTTPSessionService } from './pikku-http-session-service.js'
+
+test('PikkuHTTPSessionService: Handles JWT-based sessions', async () => {
+  const mockJWTService: any = {
+    decode: async (token) => {
+      if (token === 'validToken') return { id: 1, name: 'Test User' }
+      throw new InvalidSessionError()
+    },
+  }
+
+  const sessionService = new PikkuHTTPSessionService(mockJWTService, {})
+  const mockRequest: any = {
+    getHeader: (name) =>
+      name === 'authorization' ? 'Bearer validToken' : undefined,
+    getCookies: () => ({}),
+  }
+
+  const session = await sessionService.getUserSession(true, mockRequest)
+  assert.deepEqual(session, { id: 1, name: 'Test User' })
+})
+
+test('PikkuHTTPSessionService: Handles API key-based sessions', async () => {
+  const mockJWTService: any = { decode: async () => undefined }
+  const mockOptions = {
+    getSessionForAPIKey: async (apiKey) => {
+      return apiKey === 'validAPIKey' ? { id: 2, name: 'API User' } : undefined
+    },
+  }
+
+  const sessionService = new PikkuHTTPSessionService(
+    mockJWTService,
+    mockOptions
+  )
+  const mockRequest: any = {
+    getHeader: (name) => (name === 'x-api-key' ? 'validAPIKey' : undefined),
+    getCookies: () => ({}),
+  }
+
+  const session = await sessionService.getUserSession(true, mockRequest)
+  assert.deepEqual(session, { id: 2, name: 'API User' })
+})
+
+test('PikkuHTTPSessionService: Handles cookie-based sessions', async () => {
+  const mockJWTService: any = { decode: async () => undefined }
+  const mockOptions = {
+    cookieNames: ['session'],
+    getSessionForCookieValue: async (cookieValue, cookieName) => {
+      if (cookieValue === 'validCookie' && cookieName === 'session') {
+        return { id: 3, name: 'Cookie User' }
+      }
+      return undefined
+    },
+  }
+
+  const sessionService = new PikkuHTTPSessionService(
+    mockJWTService,
+    mockOptions
+  )
+  const mockRequest: any = {
+    getHeader: () => undefined,
+    getCookies: () => ({ session: 'validCookie' }),
+  }
+
+  const session = await sessionService.getUserSession(true, mockRequest)
+  assert.deepEqual(session, { id: 3, name: 'Cookie User' })
+})
+
+test('PikkuHTTPSessionService: Throws MissingSessionError when credentials are required but missing', async () => {
+  const mockJWTService: any = { decode: async () => undefined }
+  const sessionService = new PikkuHTTPSessionService(mockJWTService, {})
+
+  const mockRequest: any = {
+    getHeader: () => undefined,
+    getCookies: () => ({}),
+  }
+
+  await assert.rejects(
+    sessionService.getUserSession(true, mockRequest),
+    MissingSessionError
+  )
+})
+
+test('PikkuHTTPSessionService: Transforms session when transformSession is provided', async () => {
+  const mockJWTService: any = {
+    decode: async () => ({ id: 1, name: 'Original User' }),
+  }
+  const mockOptions = {
+    transformSession: async (session) => ({ ...session, transformed: true }),
+  }
+
+  const sessionService = new PikkuHTTPSessionService(
+    mockJWTService,
+    mockOptions
+  )
+  const mockRequest: any = {
+    getHeader: (name) =>
+      name === 'authorization' ? 'Bearer validToken' : undefined,
+    getCookies: () => ({}),
+  }
+
+  const session = await sessionService.getUserSession(true, mockRequest)
+  assert.deepEqual(session, { id: 1, name: 'Original User', transformed: true })
+})

package/src/http/pikku-http-session-service.ts

@@ -0,0 +1,135 @@
+import { HTTPSessionService } from './http-session-service.js'
+import { JWTService } from '../services/jwt-service.js'
+import { InvalidSessionError, MissingSessionError } from '../errors/errors.js'
+import { PikkuHTTPAbstractRequest } from './pikku-http-abstract-request.js'
+import { PikkuQuery } from './http-routes.types.js'
+
+/**
+ * The `PikkuHTTPSessionService` class provides session management capabilities, including handling JWT-based sessions,
+ * cookie-based sessions, and API key-based sessions. It allows for retrieving and transforming user sessions based on different
+ * authentication mechanisms.
+ *
+ * @template UserSession - The type representing a user session.
+ */
+export class PikkuHTTPSessionService<UserSession>
+  implements HTTPSessionService<UserSession>
+{
+  /**
+   * Constructs a new instance of the `PikkuHTTPSessionService` class.
+   *
+   * @param jwtService - The service for handling JWT operations.
+   * @param options - Options for configuring the session service.
+   */
+  constructor(
+    private jwtService: JWTService<UserSession>,
+    private options: {
+      cookieNames?: string[]
+      getSessionForCookieValue?: (
+        cookieValue: string,
+        cookieName: string
+      ) => Promise<UserSession>
+      getSessionForQueryValue?: (
+        queryValue: PikkuQuery
+      ) => Promise<UserSession> | undefined
+      getSessionForAPIKey?: (apiKey: string) => Promise<UserSession> | undefined
+      transformSession?: (session: any) => Promise<UserSession>
+    }
+  ) {}
+
+  /**
+   * Retrieves a session from cookies if available.
+   *
+   * @param request - The request object containing cookies.
+   * @returns A promise that resolves to the user session, or `undefined` if no session is found.
+   */
+  private async getCookieSession(
+    request: PikkuHTTPAbstractRequest
+  ): Promise<UserSession | undefined> {
+    const cookies = request.getCookies()
+    if (!cookies) {
+      return
+    }
+
+    let cookieName: string | undefined
+    if (this.options.cookieNames) {
+      for (const name of this.options.cookieNames) {
+        if (cookies[name]) {
+          cookieName = name
+        }
+      }
+    }
+
+    if (!cookieName) {
+      return
+    }
+
+    const cookieValue = cookies[cookieName]
+    if (!cookieValue) {
+      return
+    }
+
+    if (!this.options.getSessionForCookieValue) {
+      return
+    }
+
+    return await this.options.getSessionForCookieValue(cookieValue, cookieName)
+  }
+
+  /**
+   * Retrieves the user session based on available credentials (JWT, API key, or cookies).
+   *
+   * @param credentialsRequired - Whether credentials are required to proceed.
+   * @param request - The request object containing headers and cookies.
+   * @param debugJWTDecode - Whether to enable debugging for JWT decoding.
+   * @returns A promise that resolves to the user session, or `undefined` if no session is found and credentials are not required.
+   * @throws {MissingSessionError} - Throws an error if credentials are required but no session is found.
+   */
+  public async getUserSession(
+    credentialsRequired: boolean,
+    request: PikkuHTTPAbstractRequest,
+    debugJWTDecode?: boolean
+  ): Promise<UserSession | undefined> {
+    let userSession: UserSession | undefined
+
+    const authorization =
+      request.getHeader('authorization') || request.getHeader('Authorization')
+    if (authorization) {
+      const [part1, part2] = authorization.split(' ')
+      if (part1 !== 'Bearer' || !part2) {
+        throw new InvalidSessionError()
+      }
+      userSession = await this.jwtService.decode(
+        part2,
+        undefined,
+        debugJWTDecode
+      )
+    }
+
+    if (!userSession && this.options.getSessionForAPIKey) {
+      const apiKey = request.getHeader('x-api-key')
+      if (apiKey) {
+        userSession = await this.options.getSessionForAPIKey(apiKey)
+      }
+    }
+
+    if (!userSession && this.options.getSessionForCookieValue) {
+      userSession = await this.getCookieSession(request)
+    }
+
+    if (!userSession && this.options.getSessionForQueryValue) {
+      userSession = await this.options.getSessionForQueryValue(
+        request.getQuery()
+      )
+    }
+
+    if (!userSession && credentialsRequired) {
+      throw new MissingSessionError()
+    }
+
+    if (userSession && this.options.transformSession) {
+      return await this.options.transformSession(userSession)
+    }
+
+    return userSession
+  }
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @module @pikku/core
+ */
+export * from './types/core.types.js'
+export * from './types/functions.types.js'
+export * from './pikku-request.js'
+export * from './pikku-response.js'
+export * from './services/index.js'
+export * from './http/index.js'
+export * from './channel/index.js'
+export * from './scheduler/index.js'
+
+export { addRoute } from './http/http-route-runner.js'
+export { addChannel } from './channel/channel-runner.js'
+export { addScheduledTask } from './scheduler/scheduler-runner.js'