@pikku/core 0.6.9

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

@@ -0,0 +1,190 @@
+import { CoreUserSession, SessionServices } from '../../types/core.types.js'
+import { closeSessionServices } from '../../utils.js'
+import { processMessageHandlers } from '../channel-handler.js'
+import { getChannels, openChannel } from '../channel-runner.js'
+import type {
+  CoreAPIChannel,
+  RunChannelOptions,
+  RunChannelParams,
+  PikkuChannelHandlerFactory,
+} from '../channel.types.js'
+import {
+  createHTTPInteraction,
+  handleError,
+} from '../../http/http-route-runner.js'
+import { ChannelStore } from '../channel-store.js'
+
+export interface RunServerlessChannelParams<ChannelData>
+  extends RunChannelParams<ChannelData> {
+  channelStore: ChannelStore
+  channelHandlerFactory: PikkuChannelHandlerFactory
+  channelObject?: unknown
+}
+
+const getVariablesForChannel = ({
+  channelId,
+  userSession,
+  channelName,
+  channelHandlerFactory,
+  openingData,
+}: {
+  channelId: string
+  channelName: string
+  userSession?: CoreUserSession
+  channelHandlerFactory: PikkuChannelHandlerFactory
+  openingData?: unknown
+}) => {
+  const { channels } = getChannels()
+  const channelConfig = channels.find(
+    (channelConfig) => channelConfig.name === channelName
+  )
+  if (!channelConfig) {
+    throw new Error(`Channel not found: ${channelName}`)
+  }
+  const channelHandler = channelHandlerFactory(
+    channelId,
+    channelConfig.name,
+    openingData,
+    userSession
+  )
+  return {
+    channelConfig,
+    channelHandler,
+    channel: channelHandler.getChannel(),
+  }
+}
+
+export const runChannelConnect = async ({
+  singletonServices,
+  channelId,
+  channelObject,
+  request,
+  response,
+  route,
+  createSessionServices,
+  channelStore,
+  channelHandlerFactory,
+  coerceToArray = false,
+  logWarningsForStatusCodes = [],
+  respondWith404 = true,
+  bubbleErrors = false,
+}: Pick<CoreAPIChannel<unknown, any>, 'route'> &
+  RunChannelOptions &
+  RunServerlessChannelParams<unknown>) => {
+  let sessionServices: SessionServices | undefined
+  const http = createHTTPInteraction(request, response)
+  try {
+    const { userSession, channelConfig, openingData } = await openChannel({
+      channelId,
+      createSessionServices,
+      http,
+      route,
+      singletonServices,
+      coerceToArray,
+    })
+    await channelStore.addChannel({
+      channelId,
+      channelName: channelConfig.name,
+      openingData,
+      channelObject,
+    })
+    const { channel } = getVariablesForChannel({
+      channelId,
+      userSession,
+      channelHandlerFactory,
+      channelName: channelConfig.name,
+    })
+    if (createSessionServices) {
+      sessionServices = await createSessionServices(
+        singletonServices,
+        { http },
+        userSession
+      )
+    }
+    await channelConfig.onConnect?.(
+      { ...singletonServices, ...sessionServices },
+      channel
+    )
+    http?.response?.setStatus(101)
+  } catch (e: any) {
+    handleError(
+      e,
+      http,
+      channelId,
+      singletonServices.logger,
+      logWarningsForStatusCodes,
+      respondWith404,
+      bubbleErrors
+    )
+  } finally {
+    if (sessionServices) {
+      await closeSessionServices(singletonServices.logger, sessionServices)
+    }
+  }
+}
+
+export const runChannelDisconnect = async ({
+  singletonServices,
+  ...params
+}: RunServerlessChannelParams<unknown>): Promise<void> => {
+  let sessionServices: SessionServices | undefined
+  const { userSession, openingData, channelName } =
+    await params.channelStore.getChannel(params.channelId)
+  const { channel, channelConfig } = getVariablesForChannel({
+    ...params,
+    userSession,
+    openingData,
+    channelName,
+  })
+  if (!sessionServices && params.createSessionServices) {
+    sessionServices = await params.createSessionServices(
+      singletonServices,
+      {},
+      userSession
+    )
+  }
+  await channelConfig.onDisconnect?.(
+    { ...singletonServices, ...sessionServices },
+    channel
+  )
+  await params.channelStore.removeChannels([channel.channelId])
+  if (sessionServices) {
+    await closeSessionServices(singletonServices.logger, sessionServices)
+  }
+}
+
+export const runChannelMessage = async (
+  { singletonServices, ...params }: RunServerlessChannelParams<unknown>,
+  data: unknown
+): Promise<unknown> => {
+  let sessionServices: SessionServices | undefined
+  const { userSession, openingData, channelName } =
+    await params.channelStore.getChannel(params.channelId)
+  const { channelHandler, channelConfig } = getVariablesForChannel({
+    ...params,
+    userSession,
+    openingData,
+    channelName,
+  })
+  if (params.createSessionServices) {
+    sessionServices = await params.createSessionServices(
+      singletonServices,
+      {},
+      userSession
+    )
+  }
+  let response: unknown
+  try {
+    const onMessage = processMessageHandlers(
+      { ...singletonServices, ...sessionServices },
+      channelConfig,
+      channelHandler
+    )
+    response = await onMessage(data)
+  } finally {
+    if (sessionServices) {
+      await closeSessionServices(singletonServices.logger, sessionServices)
+    }
+  }
+  return response
+}

package/src/errors/error-handler.ts

@@ -0,0 +1,74 @@
+/**
+ * Base class for custom errors.
+ * @extends {Error}
+ */
+export class EError extends Error {
+  /**
+   * Creates an instance of EError.
+   * @param message - The error message.
+   */
+  constructor(message: string = 'An error occurred') {
+    super(message)
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+/**
+ * Interface for error details.
+ */
+export interface ErrorDetails {
+  status: number
+  message: string
+}
+
+/**
+ * Map of API errors to their details.
+ */
+if (!globalThis.pikku?.apiErrors) {
+  globalThis.pikku = globalThis.pikku || {}
+  globalThis.pikku.apiErrors = new Map<any, ErrorDetails>([])
+}
+
+const apiErrors = (): Map<any, ErrorDetails> => {
+  return globalThis.pikku.apiErrors
+}
+
+export const getErrors = () => apiErrors()
+
+/**
+ * Adds an error to the API errors map.
+ * @param error - The error to add.
+ * @param details - The details of the error.
+ */
+export const addError = (error: any, { status, message }: ErrorDetails) => {
+  apiErrors().set(error, { status, message })
+}
+
+/**
+ * Adds multiple errors to the API errors map.
+ * @param errors - An array of errors and their details.
+ */
+export const addErrors = (
+  errors: Array<[error: any, details: ErrorDetails]>
+) => {
+  errors.forEach((error) => {
+    addError(error[0], error[1])
+  })
+}
+
+/**
+ * Retrieves the error response for a given error.
+ * @param error - The error to get the response for.
+ * @returns An object containing the status and message, or undefined if the error is not found.
+ */
+export const getErrorResponse = (
+  error: Error
+): { status: number; message: string } | undefined => {
+  const foundError = Array.from(apiErrors().entries()).find(
+    ([e]) => e.name === error.constructor.name
+  )
+  if (foundError) {
+    return foundError[1]
+  }
+  return apiErrors().get(error)
+}

package/src/errors/error.test.ts

@@ -0,0 +1,54 @@
+import { test, describe } from 'node:test'
+import assert from 'assert'
+import { getErrorResponse, addError } from './error-handler.js'
+import { ForbiddenError, BadRequestError, NotFoundError } from './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/errors/errors.ts

@@ -0,0 +1,340 @@
+/**
+ * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
+ */
+import { addError, EError } from './error-handler.js'
+
+/**
+ * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
+ * @group Error
+ */
+export class BadRequestError extends EError {}
+addError(BadRequestError, {
+  status: 400,
+  message:
+    'The server cannot or will not process the request due to client error (e.g., malformed request syntax).',
+})
+
+/**
+ * Authentication is required and has failed or has not yet been provided.
+ * @group Error
+ */
+export class UnauthorizedError extends EError {}
+/**
+ * More specific error to why it's unauthorized.
+ * @group Error
+ */
+export class MissingSessionError extends EError {}
+/**
+ * More specific error to why it's unauthorized.
+ * @group Error
+ */
+export class InvalidSessionError extends EError {}
+
+addError(UnauthorizedError, {
+  status: 401,
+  message:
+    'Authentication is required and has failed or has not yet been provided.',
+})
+addError(MissingSessionError, { status: 401, message: 'Session missing.' })
+addError(InvalidSessionError, {
+  status: 401,
+  message: 'The session provided is not valid.',
+})
+
+/**
+ * Reserved for future use, often related to digital payment or subscription services.
+ * @group Error
+ */
+export class PaymentRequiredError extends EError {}
+addError(PaymentRequiredError, {
+  status: 402,
+  message:
+    'Reserved for future use, often related to digital payment or subscription services.',
+})
+
+/**
+ * The client does not have permission to access the requested resource.
+ * @group Error
+ */
+export class ForbiddenError extends EError {}
+addError(ForbiddenError, {
+  status: 403,
+  message:
+    'The client does not have permission to access the requested resource.',
+})
+
+/**
+ * The request was made from an origin that is not permitted to access this resource.
+ * @group Error
+ */
+export class InvalidOriginError extends EError {}
+addError(InvalidOriginError, {
+  status: 403,
+  message:
+    'The request was made from an origin that is not permitted to access this resource.',
+})
+
+/**
+ * The server cannot find the requested resource.
+ * @group Error
+ */
+export class NotFoundError extends EError {}
+/**
+ * The server cannot find the requested route.
+ * @group Error
+ */
+addError(NotFoundError, {
+  status: 404,
+  message: 'The server cannot find the requested resource.',
+})
+
+/**
+ * The request method is known by the server but is not supported by the resource.
+ * @group Error
+ */
+export class MethodNotAllowedError extends EError {}
+addError(MethodNotAllowedError, {
+  status: 405,
+  message:
+    'The request method is known by the server but is not supported by the resource.',
+})
+
+/**
+ * The requested resource cannot produce a response matching the list of acceptable values in the request's headers.
+ * @group Error
+ */
+export class NotAcceptableError extends EError {}
+addError(NotAcceptableError, {
+  status: 406,
+  message:
+    "The requested resource cannot produce a response matching the list of acceptable values in the request's headers.",
+})
+
+/**
+ * The client must authenticate itself to get the requested response.
+ * @group Error
+ */
+export class ProxyAuthenticationRequiredError extends EError {}
+addError(ProxyAuthenticationRequiredError, {
+  status: 407,
+  message: 'The client must authenticate itself to get the requested response.',
+})
+
+/**
+ * The server did not receive a timely response from an upstream server.
+ * @group Error
+ */
+export class RequestTimeoutError extends EError {}
+addError(RequestTimeoutError, {
+  status: 408,
+  message:
+    'The server did not receive a timely response from an upstream server.',
+})
+
+/**
+ * The request could not be completed due to a conflict with the current state of the target resource.
+ * @group Error
+ */
+export class ConflictError extends EError {}
+addError(ConflictError, {
+  status: 409,
+  message:
+    'The request could not be completed due to a conflict with the current state of the target resource.',
+})
+
+/**
+ * The resource that is being accessed is no longer available and will not be available again.
+ * @group Error
+ */
+export class GoneError extends EError {}
+addError(GoneError, {
+  status: 410,
+  message:
+    'The resource that is being accessed is no longer available and will not be available again.',
+})
+
+/**
+ * The request did not specify the length of its content, which is required by the requested resource.
+ * @group Error
+ */
+export class LengthRequiredError extends EError {}
+addError(LengthRequiredError, {
+  status: 411,
+  message:
+    'The request did not specify the length of its content, which is required by the requested resource.',
+})
+
+/**
+ * The server does not meet one of the preconditions that the requester put on the request.
+ * @group Error
+ */
+export class PreconditionFailedError extends EError {}
+addError(PreconditionFailedError, {
+  status: 412,
+  message:
+    'The server does not meet one of the preconditions that the requester put on the request.',
+})
+
+/**
+ * The request is larger than the server is willing or able to process.
+ * @group Error
+ */
+export class PayloadTooLargeError extends EError {}
+addError(PayloadTooLargeError, {
+  status: 413,
+  message:
+    'The request is larger than the server is willing or able to process.',
+})
+
+/**
+ * The URI requested by the client is longer than the server is willing to interpret.
+ * @group Error
+ */
+export class URITooLongError extends EError {}
+addError(URITooLongError, {
+  status: 414,
+  message:
+    'The URI requested by the client is longer than the server is willing to interpret.',
+})
+
+/**
+ * The server does not support the media format of the requested data.
+ * @group Error
+ */
+export class UnsupportedMediaTypeError extends EError {}
+addError(UnsupportedMediaTypeError, {
+  status: 415,
+  message:
+    'The server does not support the media format of the requested data.',
+})
+
+/**
+ * The client has asked for a portion of the file, but the server cannot supply that portion.
+ * @group Error
+ */
+export class RangeNotSatisfiableError extends EError {}
+addError(RangeNotSatisfiableError, {
+  status: 416,
+  message:
+    'The client has asked for a portion of the file, but the server cannot supply that portion.',
+})
+
+/**
+ * The server cannot meet the requirements of the Expect request-header field.
+ * @group Error
+ */
+export class ExpectationFailedError extends EError {}
+addError(ExpectationFailedError, {
+  status: 417,
+  message:
+    'The server cannot meet the requirements of the Expect request-header field.',
+})
+
+/**
+ * Indicates that the server understood the content type of the request content, and the syntax of the request content was correct, but it was unable to process the contained instructions.
+ * @group Error
+ */
+export class UnprocessableContentError extends EError {}
+addError(UnprocessableContentError, {
+  status: 422,
+  message:
+    'The server understood the content type of the request content, and the syntax of the request content was correct, but it was unable to process the contained instructions..',
+})
+
+/**
+ * Indicates that the server understood the content type of the request content, and the syntax of the request content was correct, but it was unable to process the contained instructions.
+ * @group Error
+ */
+export class LockedError extends EError {}
+addError(LockedError, {
+  status: 423,
+  message:
+    "The resource is locked, meaning it can't be accessed. Its response body should contain information in WebDAV's XML format.",
+})
+
+/**
+ * The user has sent too many requests in a given amount of time ("rate limiting").
+ * @group Error
+ */
+export class TooManyRequestsError extends EError {}
+addError(TooManyRequestsError, {
+  status: 429,
+  message:
+    'The user has sent too many requests in a given amount of time ("rate limiting").',
+})
+
+/**
+ * A generic error message, given when no more specific message is suitable.
+ * @group Error
+ */
+export class InternalServerError extends EError {}
+addError(InternalServerError, {
+  status: 500,
+  message:
+    'A generic error message, given when no more specific message is suitable.',
+})
+
+/**
+ * The server does not recognize the request method and cannot support it.
+ * @group Error
+ */
+export class NotImplementedError extends EError {}
+addError(NotImplementedError, {
+  status: 501,
+  message:
+    'The server does not recognize the request method and cannot support it.',
+})
+
+/**
+ * The server was acting as a gateway or proxy and received an invalid response from the upstream server.
+ * @group Error
+ */
+export class BadGatewayError extends EError {}
+addError(BadGatewayError, {
+  status: 502,
+  message:
+    'The server was acting as a gateway or proxy and received an invalid response from the upstream server.',
+})
+
+/**
+ * The server is currently unavailable (overloaded or down).
+ * @group Error
+ */
+export class ServiceUnavailableError extends EError {}
+addError(ServiceUnavailableError, {
+  status: 503,
+  message: 'The server is currently unavailable (overloaded or down).',
+})
+
+/**
+ * The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
+ * @group Error
+ */
+export class GatewayTimeoutError extends EError {}
+addError(GatewayTimeoutError, {
+  status: 504,
+  message:
+    'The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.',
+})
+
+/**
+ * The server does not support the HTTP protocol version used in the request.
+ * @group Error
+ */
+export class HTTPVersionNotSupportedError extends EError {}
+addError(HTTPVersionNotSupportedError, {
+  status: 505,
+  message:
+    'The server does not support the HTTP protocol version used in the request.',
+})
+
+/**
+ * The server took too long to complete the request, reaching the maximum compute time allowed.
+ * @group Error
+ */
+export class MaxComputeTimeReachedError extends EError {}
+addError(MaxComputeTimeReachedError, {
+  status: 524,
+  message:
+    'The server took too long to complete the request, reaching the maximum compute time allowed.',
+})

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export * from './error-handler.js'
+export * from './errors.js'