@pikku/core 0.7.0 → 0.7.1

package/src/http/pikku-fetch-http-response.test.ts

@@ -0,0 +1,82 @@
+import { describe, test } from 'node:test'
+import assert from 'assert'
+import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js' // Adjust path if needed
+
+describe('PikkuFetchHTTPResponse', () => {
+  test('sets status code', () => {
+    const res = new PikkuFetchHTTPResponse().status(404).toResponse()
+    assert.strictEqual(res.status, 404)
+  })
+
+  test('sets headers', async () => {
+    const res = new PikkuFetchHTTPResponse()
+      .header('X-Test', 'value')
+      .header('X-Multi', ['a', 'b'])
+      .toResponse()
+
+    assert.strictEqual(res.headers.get('X-Test'), 'value')
+    const multi = res.headers.get('X-Multi')?.split(', ')
+    assert.deepEqual(multi, ['a', 'b'])
+  })
+
+  test('sets cookies', () => {
+    const res = new PikkuFetchHTTPResponse()
+      .cookie('token', 'abc123', { httpOnly: true, path: '/' })
+      .cookie('other', 'val', { maxAge: 3600 })
+      .toResponse()
+
+    const setCookieHeader = res.headers.get('Set-Cookie')
+    assert.ok(setCookieHeader)
+
+    const cookies = setCookieHeader!.split(', ')
+    assert.ok(cookies.some((c) => c.startsWith('token=abc123')))
+    assert.ok(cookies.some((c) => c.startsWith('other=val')))
+  })
+
+  test('json sets correct content type and body', async () => {
+    const res = new PikkuFetchHTTPResponse()
+      .json({ hello: 'world' })
+      .toResponse()
+
+    assert.strictEqual(res.headers.get('Content-Type'), 'application/json')
+    const body = await res.json()
+    assert.deepEqual(body, { hello: 'world' })
+  })
+
+  test('text sets correct content type and body', async () => {
+    const res = new PikkuFetchHTTPResponse().text('hello').toResponse()
+
+    assert.strictEqual(res.headers.get('Content-Type'), 'text/plain')
+    const text = await res.text()
+    assert.strictEqual(text, 'hello')
+  })
+
+  test('html sets correct content type and body', async () => {
+    const res = new PikkuFetchHTTPResponse().html('<p>hi</p>').toResponse()
+
+    assert.strictEqual(res.headers.get('Content-Type'), 'text/html')
+    const text = await res.text()
+    assert.strictEqual(text, '<p>hi</p>')
+  })
+
+  test('arrayBuffer sets correct content type', async () => {
+    const buffer = new Uint8Array([1, 2, 3]).buffer
+    const res = new PikkuFetchHTTPResponse().arrayBuffer(buffer).toResponse()
+
+    assert.strictEqual(
+      res.headers.get('Content-Type'),
+      'application/octet-stream'
+    )
+    const body = await res.arrayBuffer()
+    assert.deepEqual(new Uint8Array(body), new Uint8Array([1, 2, 3]))
+  })
+
+  test('redirect sets Location header and status', () => {
+    const res = new PikkuFetchHTTPResponse()
+      .redirect('/login', 301)
+      .toResponse()
+
+    assert.strictEqual(res.status, 301)
+    assert.strictEqual(res.headers.get('Location'), '/login')
+  })
+})

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

@@ -0,0 +1,138 @@
+import { PikkuHTTPResponse } from './http.types.js'
+import {
+  SerializeOptions as CookieSerializeOptions,
+  serialize as serializeCookie,
+} from 'cookie'
+
+export class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
+  #statusCode: number = 200
+  #headers = new Headers()
+  #cookies = new Map<string, { value: string; flags: CookieSerializeOptions }>()
+
+  #body: BodyInit | null = null
+  #responseMode: 'stream' | null = null
+  #send: ((data: string) => void) | null = null
+  #close: (() => void) | null = null
+
+  public setMode(mode: 'stream') {
+    this.#responseMode = 'stream'
+    if (mode === 'stream') {
+      this.#body = this.createStream()
+    }
+  }
+
+  public status(code: number): this {
+    this.#statusCode = code
+    return this
+  }
+
+  public cookie(
+    name: string,
+    value: string,
+    flags: CookieSerializeOptions
+  ): this {
+    this.#cookies.set(name, { value, flags })
+    return this
+  }
+
+  public header(name: string, value: string | string[]): this {
+    this.#headers.delete(name)
+    if (Array.isArray(value)) {
+      value.forEach((v) => this.#headers.append(name, v))
+    } else {
+      this.#headers.set(name, value)
+    }
+    return this
+  }
+
+  public arrayBuffer(data: XMLHttpRequestBodyInit): this {
+    if (this.#responseMode === 'stream') {
+      this.#send!(data as string)
+    } else {
+      this.#body = data
+      this.header('Content-Type', 'application/octet-stream')
+    }
+    return this
+  }
+
+  public json(data: unknown): this {
+    if (this.#responseMode === 'stream') {
+      this.#send!(JSON.stringify(data))
+    } else {
+      this.#body = JSON.stringify(data)
+      this.header('Content-Type', 'application/json')
+    }
+    return this
+  }
+
+  public text(content: string): this {
+    if (this.#responseMode === 'stream') {
+      this.#send!(content)
+    } else {
+      this.#body = content
+      this.header('Content-Type', 'text/plain')
+    }
+    return this
+  }
+
+  public html(content: string): this {
+    if (this.#responseMode === 'stream') {
+      this.#send!(content)
+    } else {
+      this.#body = content
+      this.header('Content-Type', 'text/html')
+    }
+    return this
+  }
+
+  // public body(body: BodyInit): this {
+  //   this.#body = body
+  //   return this
+  // }
+
+  public redirect(location: string, status: number = 302): this {
+    this.#statusCode = status
+    this.header('Location', location)
+    return this
+  }
+
+  public close(): this {
+    if (this.#close) {
+      this.#close()
+    }
+    return this
+  }
+
+  public toResponse(args?: Record<string, any>): Response {
+    const cookieHeader = Array.from(this.#cookies.entries()).map(
+      ([name, { value, flags }]) => serializeCookie(name, value, flags)
+    )
+    this.#headers.set('Set-Cookie', cookieHeader.join(', '))
+    return new Response(this.#body, {
+      ...args,
+      status: this.#statusCode,
+      headers: this.#headers,
+    })
+  }
+
+  private createStream(): ReadableStream<Uint8Array> {
+    const encoder = new TextEncoder()
+    return new ReadableStream({
+      start: (controller) => {
+        const send = (data: string) => {
+          controller.enqueue(encoder.encode(`data: ${data}\n\n`))
+        }
+
+        const close = () => {
+          controller.close()
+        }
+
+        this.#send = send
+        this.#close = close
+
+        // Force initial flush
+        controller.enqueue(encoder.encode(':\n\n'))
+      },
+    })
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @module @pikku/core
+ */
+export * from './types/core.types.js'
+export * from './function/index.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 * from './errors/index.js'
+export * from './middleware/index.js'
+export * from './time-utils.js'
+export * from './utils.js'
+export { pikkuState } from './pikku-state.js'
+export { runMiddleware } from './middleware-runner.js'
+export { addHTTPRoute, addMiddleware } from './http/http-runner.js'
+export { addChannel } from './channel/channel-runner.js'
+export { addScheduledTask } from './scheduler/scheduler-runner.js'

package/src/middleware/auth-apikey.ts

@@ -0,0 +1,66 @@
+import {
+  CoreConfig,
+  CoreSingletonServices,
+  CoreUserSession,
+  PikkuMiddleware,
+} from '../types/core.types.js'
+
+/**
+ * API key middleware that retrieves a session from the 'x-api-key' header using a provided callback.
+ *
+ * @param options.getSessionForAPIKey - A function that returns a session when provided an API key.
+ */
+export const authAPIKey = <
+  SingletonServices extends CoreSingletonServices<CoreConfig>,
+  UserSession extends CoreUserSession,
+>({
+  source,
+  getSessionForAPIKey,
+  jwt,
+}: {
+  source: 'header' | 'query' | 'all'
+} & (
+  | {
+      getSessionForAPIKey?: undefined
+      jwt?: true
+    }
+  | {
+      getSessionForAPIKey: (
+        services: SingletonServices,
+        apiKey: string
+      ) => Promise<any>
+      jwt?: false
+    }
+)) => {
+  const middleware: PikkuMiddleware = async (services, { http }, next) => {
+    const { userSession: userSessionService, jwt: jwtService } = services
+    if (!http?.request || userSessionService.get()) {
+      return next()
+    }
+
+    let apiKey: string | null = null
+    if (source === 'header' || source === 'all') {
+      apiKey = http.request.header('x-api-key') as string | null
+    }
+    if (!apiKey && (source === 'query' || source === 'all')) {
+      apiKey = http.request.query().apiKey as string | null
+    }
+    if (apiKey) {
+      let userSession: UserSession | null = null
+      if (jwt) {
+        if (!jwtService) {
+          throw new Error('JWT service is required for JWT decoding.')
+        }
+        userSession = await jwtService.decode(apiKey)
+      } else {
+        userSession = await getSessionForAPIKey!(services as any, apiKey)
+      }
+      if (userSession) {
+        userSessionService.setInitial(userSession)
+      }
+    }
+    return next()
+  }
+
+  return middleware
+}

package/src/middleware/auth-bearer.ts

@@ -0,0 +1,66 @@
+import { InvalidSessionError } from '../errors/errors.js'
+import {
+  CoreConfig,
+  CoreSingletonServices,
+  CoreUserSession,
+  PikkuMiddleware,
+} from '../types/core.types.js'
+
+/**
+ * Extracts the Bearer token from the Authorization header
+ */
+export const authBearer = <
+  SingletonServices extends CoreSingletonServices<CoreConfig>,
+  UserSession extends CoreUserSession,
+>({
+  token,
+  jwt,
+  getSession,
+}: {
+  token?: {
+    value: string
+    userSession: UserSession
+  }
+  jwt?: boolean
+  getSession?: (
+    services: SingletonServices,
+    token: string
+  ) => Promise<UserSession> | UserSession
+} = {}): PikkuMiddleware => {
+  const middleware: PikkuMiddleware = async (services, { http }, next) => {
+    const { userSession: userSessionService, jwt: jwtService } = services
+    // Skip if session already exists.
+    if (!http?.request || userSessionService.get()) {
+      return next()
+    }
+
+    const authHeader =
+      http.request.header('authorization') ||
+      http.request.header('Authorization')
+    if (authHeader) {
+      const [scheme, bearerToken] = authHeader.split(' ')
+      if (scheme !== 'Bearer' || !token || !bearerToken) {
+        throw new InvalidSessionError()
+      }
+      let userSession: UserSession | null = null
+      if (jwt) {
+        if (!jwtService) {
+          throw new Error('JWT service is required for JWT decoding.')
+        }
+        userSession = await jwtService.decode(bearerToken)
+      } else if (token) {
+        if (bearerToken === token.value) {
+          userSession = token.userSession
+        }
+      } else if (getSession) {
+        userSession = await getSession(services as any, token)
+      }
+
+      if (userSession) {
+        userSessionService.setInitial(userSession)
+      }
+    }
+    return next()
+  }
+  return middleware
+}

package/src/middleware/auth-cookie.ts

@@ -0,0 +1,103 @@
+import { SerializeOptions } from 'cookie'
+import {
+  CoreConfig,
+  CoreSingletonServices,
+  CoreUserSession,
+  PikkuMiddleware,
+} from '../types/core.types.js'
+import {
+  getRelativeTimeOffsetFromNow,
+  RelativeTimeInput,
+} from '../time-utils.js'
+
+/**
+ * Cookie middleware that extracts a session from cookies.
+ *
+ * @param options.name - List of cookie names to check.
+ * @param options.getSessionForCookieValue - Function to retrieve a session using a cookie value.
+ */
+export const authCookie = <
+  SingletonServices extends CoreSingletonServices<CoreConfig>,
+  UserSession extends CoreUserSession,
+>({
+  name,
+  getSessionForCookieValue,
+  jwt,
+  options,
+  expiresIn,
+}: {
+  name: string
+  options: SerializeOptions
+  expiresIn: RelativeTimeInput
+} & (
+  | {
+      getSessionForCookieValue: (
+        services: SingletonServices,
+        cookieValue: string,
+        cookieName: string
+      ) => Promise<UserSession>
+      jwt?: false
+    }
+  | {
+      getSessionForCookieValue?: undefined
+      jwt: true
+    }
+)): PikkuMiddleware => {
+  const middleware: PikkuMiddleware = async (services, { http }, next) => {
+    const {
+      userSession: userSessionService,
+      jwt: jwtService,
+      logger,
+    } = services
+    if (!http?.request || userSessionService.get()) {
+      return next()
+    }
+
+    let userSession: UserSession | null = null
+    const cookieValue = http.request.cookie(name)
+    if (cookieValue) {
+      if (jwt) {
+        if (!jwtService) {
+          throw new Error('JWT service is required for JWT decoding.')
+        }
+        userSession = await jwtService.decode(cookieValue)
+      } else if (getSessionForCookieValue) {
+        userSession = await getSessionForCookieValue(
+          services as any,
+          cookieValue,
+          name
+        )
+      }
+    }
+
+    if (userSession) {
+      userSessionService.setInitial(userSession)
+    }
+    await next()
+
+    // Set the cookie in the response if the session has changed
+    if (!http?.response) {
+      return
+    }
+
+    if (userSessionService.sessionChanged) {
+      const session = userSessionService.get()
+      if (jwt) {
+        if (!jwtService) {
+          throw new Error('JWT service is required for JWT encoding.')
+        }
+        http.response.cookie(
+          name,
+          await jwtService.encode(expiresIn, session),
+          {
+            ...options,
+            expires: getRelativeTimeOffsetFromNow(expiresIn),
+          }
+        )
+      } else {
+        logger.warn('No JWT service available, unable to set cookie')
+      }
+    }
+  }
+  return middleware
+}

package/src/middleware/index.ts

@@ -0,0 +1,3 @@
+export * from './auth-apikey.js'
+export * from './auth-cookie.js'
+export * from './auth-bearer.js'

package/src/middleware/timeout.ts

@@ -0,0 +1,13 @@
+import { RequestTimeoutError } from '../errors/errors.js'
+import { PikkuMiddleware } from '../types/core.types.js'
+
+export const timeout = (timeout: number) => {
+  const middleware: PikkuMiddleware = async (_services, _interaction, next) => {
+    setTimeout(() => {
+      throw new RequestTimeoutError()
+    }, timeout)
+
+    await next()
+  }
+  return middleware
+}

package/src/middleware-runner.ts

@@ -0,0 +1,43 @@
+import { UserSessionService } from './services/user-session-service.js'
+import {
+  CoreSingletonServices,
+  PikkuInteraction,
+  PikkuMiddleware,
+} from './types/core.types.js'
+
+/**
+ * Runs a chain of middleware functions in sequence before executing the main function.
+ *
+ * @param services - An object containing services (e.g., singletonServices, userSession, etc.)
+ * @param interaction - The interaction context, e.g., { http }.
+ * @param middlewares - An array of middleware functions to run.
+ * @param main - The main function to execute after all middleware have run.
+ * @returns A promise resolving to the result of the main function.
+ *
+ * @example
+ * runMiddleware(
+ *   { ...services, userSession },
+ *   { http },
+ *   [middleware1, middleware2, middleware3],
+ *   async () => { return await runMain(); }
+ * );
+ */
+export const runMiddleware = async (
+  services: CoreSingletonServices & {
+    userSession: UserSessionService<any>
+  },
+  interaction: PikkuInteraction,
+  middlewares: PikkuMiddleware[],
+  main?: () => Promise<void>
+): Promise<void> => {
+  const dispatch = async (index: number): Promise<any> => {
+    if (middlewares && index < middlewares.length) {
+      await middlewares[index]!(services, interaction, () =>
+        dispatch(index + 1)
+      )
+    } else if (main) {
+      return await main()
+    }
+  }
+  await dispatch(0)
+}

package/src/permissions.test.ts

@@ -0,0 +1,58 @@
+import { test, describe } from 'node:test'
+import assert from 'assert'
+import { getErrorResponse, addError } from './errors/error-handler.js'
+import {
+  ForbiddenError,
+  BadRequestError,
+  NotFoundError,
+} from './errors/errors.js'
+
+describe('getErrorResponse', () => {
+  test('should return the correct error response for BadRequestError', () => {
+    const error = new BadRequestError()
+    const response = getErrorResponse(error)
+    assert.deepStrictEqual(response, {
+      status: 400,
+      message:
+        'The server cannot or will not process the request due to client error (e.g., malformed request syntax).',
+    })
+  })
+
+  test('should return the correct error response for NotFoundError', () => {
+    const error = new NotFoundError()
+    const response = getErrorResponse(error)
+    assert.deepStrictEqual(response, {
+      status: 404,
+      message: 'The server cannot find the requested resource.',
+    })
+  })
+
+  test('should return the correct error response for ForbiddenError', () => {
+    const error = new ForbiddenError()
+    const response = getErrorResponse(error)
+    assert.deepStrictEqual(response, {
+      status: 403,
+      message:
+        'The client does not have permission to access the requested resource.',
+    })
+  })
+
+  test('should return undefined for an unknown error', () => {
+    class UnknownError extends Error {}
+    const error = new UnknownError()
+    const response = getErrorResponse(error)
+    assert.strictEqual(response, undefined)
+  })
+
+  test('should return the correct error response for a custom error added to apiErrors', () => {
+    class CustomError extends Error {}
+    const customError = new CustomError()
+    const customErrorDetails = { status: 400, message: 'Custom Error' }
+
+    // Add the custom error to the apiErrors map
+    addError(CustomError, customErrorDetails)
+
+    const response = getErrorResponse(customError)
+    assert.deepStrictEqual(response, customErrorDetails)
+  })
+})

package/src/permissions.ts

@@ -0,0 +1,43 @@
+import { CoreServices, CoreUserSession } from './types/core.types.js'
+import { CorePermissionGroup } from './function/functions.types.js'
+
+/**
+ * This function validates permissions by iterating over permission groups and executing the corresponding permission functions. If all functions in at least one group return true, the permission is considered valid.
+ * @param services - The core services required for permission validation.
+ * @param data - The data to be used in the permission validation functions.
+ * @param session - An optional user session for permission validation.
+ * @returns A promise that resolves to void.
+ */
+export const verifyPermissions = async (
+  permissions: CorePermissionGroup,
+  services: CoreServices,
+  data: any,
+  session?: CoreUserSession
+): Promise<boolean> => {
+  if (!permissions) {
+    return true
+  }
+
+  let valid = false
+  const permissionGroups = Object.values(permissions)
+  if (permissionGroups.length === 0) {
+    return true
+  }
+
+  for (const funcs of permissionGroups) {
+    if (funcs instanceof Array) {
+      const permissioned = await Promise.all(
+        funcs.map((func) => func(services, data, session))
+      )
+      if (permissioned.every((result) => result)) {
+        valid = true
+      }
+    } else {
+      valid = await funcs(services, data, session)
+    }
+    if (valid) {
+      return true
+    }
+  }
+  return false
+}

package/src/pikku-function.ts

@@ -0,0 +1 @@
+export const callFunction = () => {}

package/src/pikku-request.ts

@@ -0,0 +1,23 @@
+/**
+ * Simplest class to represent a pikku request.
+ * @template In - The type of the request body.
+ * @group RequestResponse
+ */
+export abstract class PikkuRequest<In = any> {
+  #data: In | undefined
+
+  constructor(data: In) {
+    this.#data = data
+  }
+
+  /**
+   * Retrieves the data
+   * @returns A promise that resolves to an object containing the combined data.
+   */
+  public async data(): Promise<In> {
+    if (!this.#data) {
+      throw new Error('Data not found')
+    }
+    return this.#data
+  }
+}

package/src/pikku-response.ts

@@ -0,0 +1,5 @@
+/**
+ * Abstract class representing a pikku response.
+ * @group RequestResponse
+ */
+export abstract class PikkuResponse {}