@pikku/core 0.12.4 → 0.12.5

package/src/dev/hot-reload.ts

@@ -0,0 +1,212 @@
+import { watch, type FSWatcher } from 'node:fs'
+import { stat, readFile } from 'node:fs/promises'
+import { join, resolve, relative } from 'node:path'
+
+import { pikkuState } from '../pikku-state.js'
+import { addFunction } from '../function/function-runner.js'
+import { clearMiddlewareCache } from '../middleware-runner.js'
+import { clearPermissionsCache } from '../permissions.js'
+import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js'
+import { httpRouter } from '../wirings/http/routers/http-router.js'
+import { addSchema, compileAllSchemas } from '../schema.js'
+import type { Logger } from '../services/logger.js'
+import type { CorePikkuFunctionConfig } from '../function/functions.types.js'
+
+interface PikkuDevReloaderOptions {
+  srcDirectories: string[]
+  logger: Logger
+  pikkuDir?: string
+}
+
+const isFunctionConfig = (
+  value: unknown
+): value is CorePikkuFunctionConfig<any, any> => {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'func' in value &&
+    typeof (value as any).func === 'function'
+  )
+}
+
+const findCompiledFile = async (
+  tsFile: string,
+  srcDir: string,
+  pikkuDir: string
+): Promise<string | null> => {
+  const rel = relative(srcDir, tsFile).replace(/\.ts$/, '.js')
+  const candidates = [
+    join(pikkuDir, 'dist', rel),
+    join(srcDir, rel),
+    tsFile.replace(/\.ts$/, '.js'),
+  ]
+  for (const candidate of candidates) {
+    try {
+      await stat(candidate)
+      return candidate
+    } catch {
+      // not found, try next
+    }
+  }
+  return null
+}
+
+// Use data: URLs to import modules. This bypasses TypeScript loaders
+// (e.g. tsx) that intercept file:// imports and break dynamic ESM loading.
+// Each import gets unique content so there's no module cache to worry about.
+const reimportModule = async (
+  filePath: string
+): Promise<Record<string, unknown> | null> => {
+  try {
+    const content = await readFile(resolve(filePath), 'utf-8')
+    const dataUrl =
+      'data:text/javascript;base64,' + Buffer.from(content).toString('base64')
+    return await import(dataUrl)
+  } catch {
+    return null
+  }
+}
+
+const isWatchedTsFile = (filename: string): boolean => {
+  return (
+    filename.endsWith('.ts') &&
+    !filename.endsWith('.test.ts') &&
+    !filename.endsWith('.d.ts') &&
+    !filename.endsWith('.gen.ts')
+  )
+}
+
+export async function pikkuDevReloader(
+  options: PikkuDevReloaderOptions
+): Promise<{ close: () => void }> {
+  const { srcDirectories, logger, pikkuDir = '.pikku' } = options
+  const absSrcDirs = srcDirectories.map((d) => resolve(d))
+  const absPikkuDir = resolve(pikkuDir)
+  const watchers: FSWatcher[] = []
+
+  const functionsMap = pikkuState(null, 'function', 'functions')
+
+  const handleFileChange = async (changedTsFile: string) => {
+    const start = Date.now()
+    const reloadedNames: string[] = []
+
+    const srcDir = absSrcDirs.find((d) => changedTsFile.startsWith(d))
+    if (!srcDir) return
+
+    const compiledFile = await findCompiledFile(
+      changedTsFile,
+      srcDir,
+      absPikkuDir
+    )
+    if (!compiledFile) {
+      logger.warn(
+        `Could not find compiled JS for: ${relative(process.cwd(), changedTsFile)}`
+      )
+      return
+    }
+
+    const mod = await reimportModule(compiledFile)
+    if (!mod) {
+      logger.error(
+        `Failed to import: ${relative(process.cwd(), compiledFile)} (keeping old code)`
+      )
+      return
+    }
+
+    let schemasChanged = false
+
+    for (const [exportName, exportValue] of Object.entries(mod)) {
+      if (isFunctionConfig(exportValue) && functionsMap.has(exportName)) {
+        addFunction(exportName, exportValue)
+        reloadedNames.push(exportName)
+
+        if (exportValue.input) {
+          addSchema(exportName, exportValue.input)
+          schemasChanged = true
+        }
+        if (exportValue.output) {
+          addSchema(`${exportName}Output`, exportValue.output)
+          schemasChanged = true
+        }
+      }
+    }
+
+    if (reloadedNames.length > 0) {
+      clearMiddlewareCache()
+      clearPermissionsCache()
+      clearChannelMiddlewareCache()
+      httpRouter.reset()
+
+      if (schemasChanged) {
+        try {
+          compileAllSchemas(logger)
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err)
+          if (
+            msg.includes('SchemaService') ||
+            (msg.includes('schema') && msg.includes('not'))
+          ) {
+            logger.warn('Schema recompilation skipped (no SchemaService)')
+          } else {
+            logger.error(`Schema recompilation failed: ${msg}`)
+            return
+          }
+        }
+      }
+
+      const elapsed = Date.now() - start
+      logger.info(`Hot-reloaded: ${reloadedNames.join(', ')} (${elapsed}ms)`)
+    }
+  }
+
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined
+  const pendingChanges = new Set<string>()
+
+  const scheduleReload = (filePath: string) => {
+    pendingChanges.add(filePath)
+    if (debounceTimer) clearTimeout(debounceTimer)
+    debounceTimer = setTimeout(async () => {
+      const files = [...pendingChanges]
+      pendingChanges.clear()
+      for (const file of files) {
+        try {
+          await handleFileChange(file)
+        } catch (err) {
+          logger.error(
+            `Hot-reload error for ${relative(process.cwd(), file)}: ${err instanceof Error ? err.message : String(err)}`
+          )
+        }
+      }
+    }, 50)
+  }
+
+  for (const srcDir of absSrcDirs) {
+    try {
+      const watcher = watch(
+        srcDir,
+        { recursive: true },
+        (eventType, filename) => {
+          if (filename && isWatchedTsFile(filename)) {
+            scheduleReload(join(srcDir, filename))
+          }
+        }
+      )
+      watchers.push(watcher)
+    } catch (err: any) {
+      logger.error(
+        `Failed to watch directory ${srcDir}: ${err?.message || err}`
+      )
+    }
+  }
+
+  logger.info(`Hot-reload active for: ${srcDirectories.join(', ')}`)
+
+  return {
+    close: () => {
+      if (debounceTimer) clearTimeout(debounceTimer)
+      for (const watcher of watchers) {
+        watcher.close()
+      }
+    },
+  }
+}

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)
+    })
+  }
+})