@pikku/core 0.7.0 → 0.7.1

package/src/function/function-runner.ts

@@ -0,0 +1,91 @@
+import { ForbiddenError } from '../errors/errors.js'
+import { verifyPermissions } from '../permissions.js'
+import { pikkuState } from '../pikku-state.js'
+import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
+import {
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+} from '../types/core.types.js'
+import {
+  CoreAPIFunction,
+  CoreAPIFunctionSessionless,
+  CorePermissionGroup,
+} from './functions.types.js'
+
+export const addFunction = (
+  funcName: string,
+  func: CoreAPIFunction<any, any> | CoreAPIFunctionSessionless<any, any>
+) => {
+  pikkuState('functions', 'nameToFunction').set(funcName, func)
+}
+
+export const runPikkuFuncDirectly = async <In, Out>(
+  funcName: string,
+  allServices: CoreServices,
+  data: In,
+  session?: CoreUserSession
+) => {
+  const func = pikkuState('functions', 'nameToFunction').get(funcName)
+  if (!func) {
+    throw new Error(`Function not found: ${funcName}`)
+  }
+  return (await func(allServices, data, session!)) as Out
+}
+
+export const runPikkuFunc = async <In = any, Out = any>(
+  funcName: string,
+  {
+    singletonServices,
+    getAllServices,
+    data,
+    session,
+    permissions,
+    coerceDataFromSchema,
+  }: {
+    singletonServices: CoreSingletonServices
+    getAllServices: () => Promise<CoreServices> | CoreServices
+    data: In
+    session?: CoreUserSession
+    permissions?: CorePermissionGroup
+    coerceDataFromSchema?: boolean
+  }
+): Promise<Out> => {
+  const func = pikkuState('functions', 'nameToFunction').get(funcName)
+  if (!func) {
+    throw new Error(`Function not found: ${funcName}`)
+  }
+  const funcMeta = pikkuState('functions', 'meta')[funcName]
+  if (!funcMeta) {
+    throw new Error(`Function meta not found: ${funcName}`)
+  }
+  const schemaName = funcMeta.schemaName
+  // Validate request data against the defined schema, if any
+  await validateSchema(
+    singletonServices.logger,
+    singletonServices.schema,
+    schemaName,
+    data
+  )
+
+  // Coerce (top level) query string parameters or date objects if specified by the schema
+  if (coerceDataFromSchema && schemaName) {
+    coerceTopLevelDataFromSchema(schemaName, data)
+  }
+
+  const allServices = await getAllServices()
+
+  // Execute permission checks
+  const permissioned = await verifyPermissions(
+    permissions,
+    allServices,
+    data,
+    session
+  )
+
+  if (permissioned === false) {
+    throw new ForbiddenError('Permission denied')
+  }
+
+  return (await func(allServices, data, session!)) as Out
+}

package/src/function/functions.types.ts

@@ -0,0 +1,77 @@
+import { PikkuChannel } from '../channel/channel.types.js'
+import type {
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+} from '../types/core.types.js'
+
+/**
+ * Represents a core API function that performs an operation using core services and a user session.
+ *
+ * @template In - The input type.
+ * @template Out - The output type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CoreAPIFunction<
+  In,
+  Out,
+  ChannelData extends unknown | null = null,
+  Services extends CoreSingletonServices = CoreServices &
+    (ChannelData extends null
+      ? {
+          channel?: PikkuChannel<unknown, Out> | undefined
+        }
+      : {
+          channel: PikkuChannel<ChannelData, Out>
+        }),
+  Session extends CoreUserSession = CoreUserSession,
+> = (
+  services: Services,
+  data: In,
+  session: Session
+) => ChannelData extends null ? Promise<Out> : Promise<Out> | Promise<void>
+
+/**
+ * Represents a core API function that can be used without a session.
+ *
+ * @template In - The input type.
+ * @template Out - The output type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CoreAPIFunctionSessionless<
+  In,
+  Out,
+  ChannelData extends unknown | null = null,
+  Services extends CoreSingletonServices = CoreServices &
+    (ChannelData extends null
+      ? {
+          channel?: PikkuChannel<unknown, Out> | undefined
+        }
+      : {
+          channel: PikkuChannel<ChannelData, Out>
+        }),
+  Session extends CoreUserSession = CoreUserSession,
+> = (
+  services: Services,
+  data: In,
+  session?: Session
+) => ChannelData extends null ? Promise<Out> : Promise<Out> | Promise<void>
+
+/**
+ * Represents a function that checks permissions for a given API operation.
+ *
+ * @template In - The input type.
+ * @template Services - The services type, defaults to `CoreServices`.
+ * @template Session - The session type, defaults to `CoreUserSession`.
+ */
+export type CoreAPIPermission<
+  In = any,
+  Services extends CoreSingletonServices = CoreServices,
+  Session extends CoreUserSession = CoreUserSession,
+> = (services: Services, data: In, session?: Session) => Promise<boolean>
+
+export type CorePermissionGroup<APIPermission = CoreAPIPermission<any>> =
+  | Record<string, APIPermission | APIPermission[]>
+  | undefined

package/src/function/index.ts

@@ -0,0 +1,2 @@
+export * from './function-runner.js'
+export * from './functions.types.js'

package/src/handle-error.ts

@@ -0,0 +1,73 @@
+import { getErrorResponse } from './errors/error-handler.js'
+import { NotFoundError } from './errors/errors.js'
+import { Logger } from './services/logger.js'
+import { PikkuHTTP } from './http/http.types.js'
+
+/**
+ * Handle errors that occur during route processing
+ *
+ * @param {any} e - The error that occurred
+ * @param {PikkuHTTP | undefined} http - HTTP interaction object
+ * @param {string} trackerId - Unique ID for tracking this error
+ * @param {Logger} logger - Logger service
+ * @param {number[]} logWarningsForStatusCodes - HTTP status codes to log as warnings
+ * @param {boolean} respondWith404 - Whether to respond with 404 for NotFoundError
+ * @param {boolean} bubbleError - Whether to throw the error after handling
+ */
+export const handleError = (
+  e: any,
+  http: PikkuHTTP | undefined,
+  trackerId: string | undefined,
+  logger: Logger,
+  logWarningsForStatusCodes: number[],
+  respondWith404: boolean,
+  bubbleError: boolean
+) => {
+  // Skip 404 handling if configured to do so
+  if (e instanceof NotFoundError && !respondWith404) {
+    return
+  }
+
+  // Get appropriate error response
+  const errorResponse = getErrorResponse(e)
+  if (errorResponse != null) {
+    // Set status and response body
+    http?.response?.status(errorResponse.status)
+    http?.response?.json({
+      message: errorResponse.message,
+      payload: (e as any).payload,
+      traceId: trackerId,
+    })
+
+    // Log certain status codes as warnings
+    if (logWarningsForStatusCodes.includes(errorResponse.status)) {
+      if (trackerId) {
+        logger.warn(`Warning id: ${trackerId}`)
+      }
+      logger.warn(e)
+    }
+  } else {
+    // Handle unexpected errors
+    logger.error(e)
+    http?.response?.status(500)
+
+    if (trackerId) {
+      logger.warn(`Error id: ${trackerId}`)
+      http?.response?.json({ errorId: trackerId })
+    }
+  }
+
+  // Handle 404 errors specifically
+  if (e instanceof NotFoundError) {
+    // TODO
+    // http?.response?.end()
+  }
+
+  // Either bubble up or end the response
+  if (bubbleError) {
+    throw e
+  } else {
+    // TODO
+    // http?.response?.end()
+  }
+}

package/src/http/http-runner.test.ts

@@ -0,0 +1,140 @@
+import { test, describe, beforeEach, afterEach } from 'node:test'
+import * as assert from 'assert'
+import { NotFoundError } from '../errors/errors.js'
+import { JSONValue, PikkuMiddleware } from '../types/core.types.js'
+import { fetch, addHTTPRoute } from './http-runner.js'
+import { pikkuState, resetPikkuState } from '../pikku-state.js'
+import {
+  PikkuMockRequest,
+  PikkuMockResponse,
+} from '../channel/local/local-channel-runner.test.js'
+import { addFunction } from '../function/function-runner.js'
+
+const sessionMiddleware: PikkuMiddleware = async (services, _, next) => {
+  services.userSession.set({ userId: 'test' } as any)
+  await next()
+}
+
+const setHTTPFunctionMap = (fun: any) => {
+  pikkuState('functions', 'meta', {
+    pikku_func_name: {
+      pikkuFuncName: 'pikku_func_name',
+      services: ['userSession'],
+    },
+  } as any)
+  pikkuState('http', 'meta', [
+    {
+      pikkuFuncName: 'pikku_func_name',
+      route: 'test',
+      method: 'get',
+      input: null,
+      output: null,
+    },
+  ])
+  addFunction('pikku_func_name', fun)
+}
+
+describe('fetch', () => {
+  let singletonServices: any
+  let createSessionServices: any
+  let request: any
+  let response: any
+
+  beforeEach(() => {
+    resetPikkuState()
+
+    singletonServices = {
+      logger: {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+      },
+    }
+
+    createSessionServices = async () => ({})
+    request = new PikkuMockRequest('/test', 'get')
+    response = new PikkuMockResponse()
+
+    request.getData = async () => ({})
+    request.getHeader = () => 'application/json'
+    response.setStatus = (status: number) => {}
+    response.setJson = (json: JSONValue) => {}
+  })
+
+  afterEach(() => {})
+
+  test('should throw RouteNotFoundError when no matching route is found', async () => {
+    await assert.rejects(
+      async () =>
+        fetch(request, {
+          singletonServices,
+          createSessionServices,
+          bubbleErrors: true,
+        }),
+      NotFoundError
+    )
+  })
+
+  test('should call the route function and return its result when a matching route is found', async () => {
+    const routeFunc = async () => ({ success: true })
+    setHTTPFunctionMap(routeFunc)
+
+    addHTTPRoute({
+      route: 'test',
+      method: 'get',
+      func: routeFunc,
+      middleware: [sessionMiddleware],
+    })
+
+    const result = await fetch(request, {
+      singletonServices,
+      createSessionServices,
+    })
+
+    assert.deepStrictEqual(await result.json(), { success: true })
+  })
+
+  test('should verify permissions if provided', async () => {
+    const permissions = { test: async () => true }
+    const routeFunc = async () => ({ success: true })
+    setHTTPFunctionMap(routeFunc)
+
+    addHTTPRoute({
+      route: 'test',
+      method: 'get',
+      func: routeFunc,
+      permissions,
+      middleware: [sessionMiddleware],
+    })
+
+    await fetch(request, {
+      singletonServices,
+      createSessionServices,
+    })
+
+    assert.strictEqual(await permissions.test(), true)
+  })
+
+  test('should handle errors and set appropriate response', async () => {
+    const error = new Error('Test error')
+    const routeFunc = async () => {
+      throw error
+    }
+    setHTTPFunctionMap(routeFunc)
+    addHTTPRoute({
+      route: 'test',
+      method: 'get',
+      func: routeFunc,
+      middleware: [sessionMiddleware],
+    })
+    await assert.rejects(
+      async () =>
+        fetch(request, {
+          singletonServices,
+          createSessionServices,
+          bubbleErrors: true,
+        }),
+      error
+    )
+  })
+})