@pikku/core 0.12.4 → 0.12.6

package/src/errors/error-handler.ts

@@ -0,0 +1,62 @@
+import { pikkuState } from '../pikku-state.js'
+
+/**
+ * Base class for custom errors.
+ * @extends {Error}
+ */
+export class PikkuError extends Error {
+  /**
+   * Creates an instance of PikkuError.
+   * @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
+  mcpCode?: number
+}
+
+/**
+ * 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) => {
+  pikkuState(null, 'misc', 'errors').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; mcpCode?: number } | undefined => {
+  const errors = Array.from(pikkuState(null, 'misc', 'errors').entries())
+  const foundError = errors.find(([e]) => e.name === error.constructor.name)
+  if (foundError) {
+    return foundError[1]
+  }
+  return pikkuState(null, 'misc', 'errors').get(error)
+}

package/src/errors/error.test.ts

@@ -0,0 +1,195 @@
+import { test, describe } from 'node:test'
+import assert from 'assert'
+import {
+  getErrorResponse,
+  addError,
+  addErrors,
+  PikkuError,
+} from './error-handler.js'
+import {
+  BadRequestError,
+  UnauthorizedError,
+  MissingSessionError,
+  InvalidSessionError,
+  PaymentRequiredError,
+  ForbiddenError,
+  InvalidOriginError,
+  NotFoundError,
+  MethodNotAllowedError,
+  NotAcceptableError,
+  ProxyAuthenticationRequiredError,
+  RequestTimeoutError,
+  ConflictError,
+  GoneError,
+  LengthRequiredError,
+  PreconditionFailedError,
+  PayloadTooLargeError,
+  URITooLongError,
+  UnsupportedMediaTypeError,
+  RangeNotSatisfiableError,
+  ExpectationFailedError,
+  UnprocessableContentError,
+  LockedError,
+  TooManyRequestsError,
+  InternalServerError,
+  NotImplementedError,
+  BadGatewayError,
+  ServiceUnavailableError,
+  GatewayTimeoutError,
+  HTTPVersionNotSupportedError,
+  MaxComputeTimeReachedError,
+  MissingSchemaError,
+  InvalidMiddlewareWireError,
+  PikkuMissingMetaError,
+} from './errors.js'
+
+describe('PikkuError', () => {
+  test('should create error with default message', () => {
+    const error = new PikkuError()
+    assert.strictEqual(error.message, 'An error occurred')
+  })
+
+  test('should create error with custom message', () => {
+    const error = new PikkuError('custom message')
+    assert.strictEqual(error.message, 'custom message')
+  })
+
+  test('should be instance of Error', () => {
+    const error = new PikkuError()
+    assert.ok(error instanceof Error)
+  })
+
+  test('should be instance of PikkuError', () => {
+    const error = new PikkuError()
+    assert.ok(error instanceof PikkuError)
+  })
+
+  test('subclasses should be instanceof PikkuError', () => {
+    assert.ok(new BadRequestError() instanceof PikkuError)
+    assert.ok(new NotFoundError() instanceof PikkuError)
+    assert.ok(new ForbiddenError() instanceof PikkuError)
+  })
+})
+
+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)
+  })
+})
+
+describe('addErrors', () => {
+  test('should register multiple errors at once', () => {
+    class ErrA extends Error {}
+    class ErrB extends Error {}
+    addErrors([
+      [ErrA, { status: 450, message: 'Error A' }],
+      [ErrB, { status: 451, message: 'Error B' }],
+    ])
+    assert.deepStrictEqual(getErrorResponse(new ErrA()), {
+      status: 450,
+      message: 'Error A',
+    })
+    assert.deepStrictEqual(getErrorResponse(new ErrB()), {
+      status: 451,
+      message: 'Error B',
+    })
+  })
+})
+
+describe('all built-in error classes', () => {
+  const errorCases: [string, any, number][] = [
+    ['InvalidMiddlewareWireError', InvalidMiddlewareWireError, 500],
+    ['PikkuMissingMetaError', PikkuMissingMetaError, 500],
+    ['BadRequestError', BadRequestError, 400],
+    ['UnauthorizedError', UnauthorizedError, 401],
+    ['MissingSessionError', MissingSessionError, 401],
+    ['InvalidSessionError', InvalidSessionError, 401],
+    ['PaymentRequiredError', PaymentRequiredError, 402],
+    ['ForbiddenError', ForbiddenError, 403],
+    ['InvalidOriginError', InvalidOriginError, 403],
+    ['NotFoundError', NotFoundError, 404],
+    ['MethodNotAllowedError', MethodNotAllowedError, 405],
+    ['NotAcceptableError', NotAcceptableError, 406],
+    ['ProxyAuthenticationRequiredError', ProxyAuthenticationRequiredError, 407],
+    ['RequestTimeoutError', RequestTimeoutError, 408],
+    ['ConflictError', ConflictError, 409],
+    ['GoneError', GoneError, 410],
+    ['LengthRequiredError', LengthRequiredError, 411],
+    ['PreconditionFailedError', PreconditionFailedError, 412],
+    ['PayloadTooLargeError', PayloadTooLargeError, 413],
+    ['URITooLongError', URITooLongError, 414],
+    ['UnsupportedMediaTypeError', UnsupportedMediaTypeError, 415],
+    ['RangeNotSatisfiableError', RangeNotSatisfiableError, 416],
+    ['ExpectationFailedError', ExpectationFailedError, 417],
+    ['UnprocessableContentError', UnprocessableContentError, 422],
+    ['LockedError', LockedError, 423],
+    ['TooManyRequestsError', TooManyRequestsError, 429],
+    ['InternalServerError', InternalServerError, 500],
+    ['NotImplementedError', NotImplementedError, 501],
+    ['BadGatewayError', BadGatewayError, 502],
+    ['ServiceUnavailableError', ServiceUnavailableError, 503],
+    ['GatewayTimeoutError', GatewayTimeoutError, 504],
+    ['HTTPVersionNotSupportedError', HTTPVersionNotSupportedError, 505],
+    ['MaxComputeTimeReachedError', MaxComputeTimeReachedError, 524],
+    ['MissingSchemaError', MissingSchemaError, 500],
+  ]
+
+  for (const [name, ErrorClass, expectedStatus] of errorCases) {
+    test(`${name} should map to status ${expectedStatus}`, () => {
+      const error = new ErrorClass()
+      const response = getErrorResponse(error)
+      assert.ok(response, `Expected error response for ${name}`)
+      assert.strictEqual(response!.status, expectedStatus)
+      assert.ok(response!.message.length > 0)
+    })
+
+    test(`${name} should be instance of PikkuError`, () => {
+      const error = new ErrorClass()
+      assert.ok(error instanceof PikkuError)
+    })
+  }
+})

package/src/errors/errors.ts

@@ -0,0 +1,374 @@
+/**
+ * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
+ */
+import { addError, PikkuError } from './error-handler.js'
+
+export class InvalidMiddlewareWireError extends PikkuError {}
+addError(InvalidMiddlewareWireError, {
+  status: 500,
+  message: 'The middleware wire is invalid for the current wiring type.',
+})
+
+export class PikkuMissingMetaError extends PikkuError {}
+addError(PikkuMissingMetaError, {
+  status: 500,
+  message: 'Required metadata is missing',
+})
+
+/**
+ * The server cannot or will not process the request due to client error (e.g., malformed request syntax).
+ * @group Error
+ */
+export class BadRequestError extends PikkuError {}
+addError(BadRequestError, {
+  status: 400,
+  mcpCode: -32600,
+  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 PikkuError {}
+/**
+ * More specific error to why it's unauthorized.
+ * @group Error
+ */
+export class MissingSessionError extends PikkuError {}
+/**
+ * More specific error to why it's unauthorized.
+ * @group Error
+ */
+export class InvalidSessionError extends PikkuError {}
+
+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 PikkuError {}
+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 PikkuError {}
+addError(ForbiddenError, {
+  status: 403,
+  message:
+    'The client does not have permission to access the requested resource.',
+})
+
+/**
+ * The session is readonly and cannot access a non-readonly function.
+ * @group Error
+ */
+export class ReadonlySessionError extends PikkuError {}
+addError(ReadonlySessionError, {
+  status: 403,
+  message: 'The session is readonly and cannot access this function.',
+})
+
+/**
+ * The request was made from an origin that is not permitted to access this resource.
+ * @group Error
+ */
+export class InvalidOriginError extends PikkuError {}
+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 PikkuError {}
+/**
+ * The server cannot find the requested route.
+ * @group Error
+ */
+addError(NotFoundError, {
+  status: 404,
+  mcpCode: -32601,
+  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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+addError(ProxyAuthenticationRequiredError, {
+  status: 407,
+  message: 'The client must authenticate itself to get the requested response.',
+})
+
+/**
+ * The server request expired
+ * @group Error
+ */
+export class RequestTimeoutError extends PikkuError {}
+addError(RequestTimeoutError, {
+  status: 408,
+  message: 'The request timeout has expired.',
+})
+
+/**
+ * The request could not be completed due to a conflict with the current state of the target resource.
+ * @group Error
+ */
+export class ConflictError extends PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+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 PikkuError {}
+addError(MaxComputeTimeReachedError, {
+  status: 524,
+  message:
+    'The server took too long to complete the request, reaching the maximum compute time allowed.',
+})
+
+/**
+ * A required schema was not found during validation.
+ * @group Error
+ */
+export class MissingSchemaError extends PikkuError {}
+addError(MissingSchemaError, {
+  status: 500,
+  message:
+    'A required schema was not found. Ensure schema generation has been run.',
+})

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export * from './errors.js'
+export { PikkuError, addError, addErrors } from './error-handler.js'