@pikku/core 0.6.27 → 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/{types → function}/functions.types.ts

@@ -3,7 +3,7 @@ import type {
   CoreServices,
   CoreSingletonServices,
   CoreUserSession,
-} from './core.types.js'
+} from '../types/core.types.js'
 
 /**
  * Represents a core API function that performs an operation using core services and a user session.
@@ -16,16 +16,21 @@ import type {
 export type CoreAPIFunction<
   In,
   Out,
-  Services extends CoreSingletonServices = CoreServices & {
-    channel?: PikkuChannel<unknown, 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,
-  Channel extends boolean = false,
 > = (
   services: Services,
   data: In,
   session: Session
-) => Channel extends true ? Promise<Out> | Promise<void> : Promise<Out>
+) => ChannelData extends null ? Promise<Out> : Promise<Out> | Promise<void>
 
 /**
  * Represents a core API function that can be used without a session.
@@ -38,16 +43,21 @@ export type CoreAPIFunction<
 export type CoreAPIFunctionSessionless<
   In,
   Out,
-  Services extends CoreSingletonServices = CoreServices & {
-    channel?: PikkuChannel<unknown, 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,
-  Channel extends boolean = false,
 > = (
   services: Services,
   data: In,
   session?: Session
-) => Channel extends true ? Promise<Out> | Promise<void> : Promise<Out>
+) => ChannelData extends null ? Promise<Out> : Promise<Out> | Promise<void>
 
 /**
  * Represents a function that checks permissions for a given API operation.
@@ -61,3 +71,7 @@ export type CoreAPIPermission<
   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

@@ -1,7 +1,7 @@
 import { getErrorResponse } from './errors/error-handler.js'
 import { NotFoundError } from './errors/errors.js'
 import { Logger } from './services/logger.js'
-import { PikkuHTTP } from './http/http-routes.types.js'
+import { PikkuHTTP } from './http/http.types.js'
 
 /**
  * Handle errors that occur during route processing

package/src/http/{http-route-runner.test.ts → http-runner.test.ts}

@@ -2,18 +2,38 @@ 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, addRoute } from './http-route-runner.js'
-import { resetPikkuState } from '../pikku-state.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
@@ -57,7 +77,9 @@ describe('fetch', () => {
 
   test('should call the route function and return its result when a matching route is found', async () => {
     const routeFunc = async () => ({ success: true })
-    addRoute({
+    setHTTPFunctionMap(routeFunc)
+
+    addHTTPRoute({
       route: 'test',
       method: 'get',
       func: routeFunc,
@@ -75,8 +97,9 @@ describe('fetch', () => {
   test('should verify permissions if provided', async () => {
     const permissions = { test: async () => true }
     const routeFunc = async () => ({ success: true })
+    setHTTPFunctionMap(routeFunc)
 
-    addRoute({
+    addHTTPRoute({
       route: 'test',
       method: 'get',
       func: routeFunc,
@@ -97,13 +120,13 @@ describe('fetch', () => {
     const routeFunc = async () => {
       throw error
     }
-    addRoute({
+    setHTTPFunctionMap(routeFunc)
+    addHTTPRoute({
       route: 'test',
       method: 'get',
       func: routeFunc,
       middleware: [sessionMiddleware],
     })
-
     await assert.rejects(
       async () =>
         fetch(request, {

package/src/http/{http-route-runner.ts → http-runner.ts}

@@ -1,4 +1,3 @@
-import { verifyPermissions } from '../permissions.js'
 import {
   CoreHTTPFunctionRoute,
   RunRouteOptions,
@@ -6,20 +5,21 @@ import {
   PikkuHTTP,
   PikkuHTTPRequest,
   PikkuHTTPResponse,
-} from './http-routes.types.js'
+  HTTPRouteMeta,
+  HTTPMethod,
+} from './http.types.js'
 import {
   CoreUserSession,
   PikkuMiddleware,
   SessionServices,
 } from '../types/core.types.js'
 import { match } from 'path-to-regexp'
+import { MissingSessionError, NotFoundError } from '../errors/errors.js'
 import {
-  ForbiddenError,
-  MissingSessionError,
-  NotFoundError,
-} from '../errors/errors.js'
-import { closeSessionServices } from '../utils.js'
-import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js'
+  closeSessionServices,
+  createWeakUID,
+  isSerializable,
+} from '../utils.js'
 import {
   PikkuUserSessionService,
   UserSessionService,
@@ -29,6 +29,8 @@ import { handleError } from '../handle-error.js'
 import { pikkuState } from '../pikku-state.js'
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
+import { PikkuChannel } from '../channel/channel.types.js'
+import { addFunction, runPikkuFunc } from '../function/function-runner.js'
 
 /**
  * Registers middleware either globally or for a specific route.
@@ -69,30 +71,44 @@ export const addMiddleware = <APIMiddleware extends PikkuMiddleware>(
  * @template Route Route pattern as a string.
  * @template APIFunction Type for the route handler function.
  * @template APIFunctionSessionless Type for a sessionless handler.
- * @template APIPermission Type representing required permissions.
+ * @template APIPermissionGroup Type representing required permissions.
  * @template APIMiddleware Middleware type to be used with the route.
  * @param {CoreHTTPFunctionRoute<In, Out, Route, APIFunction, APIFunctionSessionless, APIPermission, APIMiddleware>} route - The route configuration object.
  */
-export const addRoute = <
+export const addHTTPRoute = <
   In,
   Out,
   Route extends string,
   APIFunction,
   APIFunctionSessionless,
-  APIPermission,
+  APIPermissionGroup,
   APIMiddleware,
 >(
-  route: CoreHTTPFunctionRoute<
+  httpRoute: CoreHTTPFunctionRoute<
     In,
     Out,
     Route,
     APIFunction,
     APIFunctionSessionless,
-    APIPermission,
+    APIPermissionGroup,
     APIMiddleware
   >
 ) => {
-  pikkuState('http', 'routes').push(route as any)
+  const httpMeta = pikkuState('http', 'meta')
+  const routeMeta = httpMeta.find(
+    (meta) => meta.route === httpRoute.route && meta.method === httpRoute.method
+  )
+  if (!routeMeta) {
+    throw new Error('Route metadata not found')
+  }
+  addFunction(routeMeta.pikkuFuncName, httpRoute.func as any)
+  const routes = pikkuState('http', 'routes')
+  if (!routes.has(httpRoute.method)) {
+    routes.set(httpRoute.method, new Map())
+  }
+  pikkuState('http', 'routes')
+    .get(httpRoute.method)
+    ?.set(httpRoute.route, httpRoute as any)
 }
 
 /**
@@ -107,16 +123,13 @@ export const addRoute = <
  * @returns {Object | undefined} An object with matched route details or undefined if no match.
  */
 const getMatchingRoute = (requestType: string, requestPath: string) => {
-  const routes = pikkuState('http', 'routes')
+  const allRoutes = pikkuState('http', 'routes')
   const middleware = pikkuState('http', 'middleware')
-  const routesMeta = pikkuState('http', 'meta')
-
-  for (const route of routes) {
-    // Skip routes that don't match the HTTP method
-    if (route.method !== requestType.toLowerCase()) {
-      continue
-    }
-
+  const routes = allRoutes.get(requestType.toLowerCase() as HTTPMethod)
+  if (!routes) {
+    return undefined
+  }
+  for (const route of routes.values()) {
     // Generate a matching function from the route pattern
     const matchFunc = match(`/${route.route}`.replace(/^\/\//, '/'), {
       decode: decodeURIComponent,
@@ -132,18 +145,17 @@ const getMatchingRoute = (requestType: string, requestPath: string) => {
         .map((m) => m.middleware)
         .flat()
 
-      // Extract associated schema information if available
-      const schemaName = routesMeta.find(
-        (routeMeta) =>
-          routeMeta.method === route.method && routeMeta.route === route.route
-      )?.input
+      const meta = pikkuState('http', 'meta').find(
+        (meta) => meta.route === route.route && meta.method === route.method
+      )
 
       return {
         matchedPath,
         params: matchedPath.params,
         route,
+        permissions: route.permissions,
         middleware: [...globalMiddleware, ...(route.middleware || [])],
-        schemaName,
+        meta: meta!,
       }
     }
   }
@@ -205,25 +217,27 @@ const executeRouteWithMiddleware = async (
     userSession: UserSessionService<CoreUserSession>
     createSessionServices: Function
     skipUserSession: boolean
+    requestId: string
   },
   matchedRoute: {
     matchedPath: any
     params: any
     route: CoreHTTPFunctionRoute<any, any, any>
     middleware: any[]
-    schemaName?: string | null
+    meta: HTTPRouteMeta
   },
-  http: PikkuHTTP | undefined,
+  http: PikkuHTTP,
   options: {
     coerceDataFromSchema: boolean
   }
 ) => {
-  const { matchedPath, params, route, middleware, schemaName } = matchedRoute
+  const { matchedPath, params, route, middleware, meta } = matchedRoute
   const {
     singletonServices,
     userSession,
     createSessionServices,
     skipUserSession,
+    requestId,
   } = services
 
   const requiresSession = route.auth !== false
@@ -256,48 +270,62 @@ const executeRouteWithMiddleware = async (
       throw new MissingSessionError()
     }
 
-    // Create session-specific services for handling the request
-    sessionServices = await createSessionServices(
-      { ...singletonServices, userSession },
-      { http },
-      session
-    )
-
-    const allServices = {
-      ...singletonServices,
-      ...sessionServices,
-      userSession,
-      http,
-    }
-    const data = await http?.request?.data()
-
-    // Validate request data against the defined schema, if any
-    await validateSchema(
-      singletonServices.logger,
-      singletonServices.schema,
-      schemaName,
-      data
-    )
+    const data = http.request!.data()
+
+    const getAllServices = async () => {
+      let channel: PikkuChannel<unknown, unknown> | undefined
+      if (matchedRoute.route.sse) {
+        const response = http?.response
+        if (!response) {
+          throw new Error('SSE requires a valid HTTP response object')
+        }
+        if (!response.setMode) {
+          throw new Error('Response object does not support SSE mode')
+        }
+        response.setMode('stream')
+        response.header('Content-Type', 'text/event-stream')
+        response.header('Cache-Control', 'no-cache')
+        response.header('Connection', 'keep-alive')
+        response.header('Transfer-Encoding', 'chunked')
+        channel = {
+          channelId: requestId,
+          openingData: data,
+          send: (data: any) => {
+            response.arrayBuffer(
+              isSerializable(data) ? JSON.stringify(data) : data
+            )
+          },
+          close: () => {
+            channel!.state = 'closed'
+            response.close?.()
+          },
+          state: 'open',
+        }
+      }
 
-    // Coerce (top level) query string parameters or date objects if specified by the schema
-    if (options.coerceDataFromSchema && schemaName) {
-      coerceTopLevelDataFromSchema(schemaName, data)
+      // Create session-specific services for handling the request
+      sessionServices = await createSessionServices(
+        { ...singletonServices, userSession, channel },
+        { http },
+        session
+      )
+      return {
+        ...singletonServices,
+        ...sessionServices,
+        http,
+        userSession,
+        channel,
+      }
     }
 
-    // Execute permission checks
-    const permissioned = await verifyPermissions(
-      route.permissions,
-      allServices,
+    const result = await runPikkuFunc(meta.pikkuFuncName, {
+      singletonServices,
+      getAllServices,
+      session,
       data,
-      session
-    )
-
-    if (permissioned === false) {
-      throw new ForbiddenError('Permission denied')
-    }
-
-    // Invoke the actual route handler function
-    result = await route.func(allServices, data, session!)
+      permissions: route.permissions,
+      coerceDataFromSchema: options.coerceDataFromSchema,
+    })
 
     // Respond with either a binary or JSON response based on configuration
     if (route.returnsJSON === false) {
@@ -398,8 +426,13 @@ export const fetchData = async <In, Out>(
     logWarningsForStatusCodes = [],
     coerceDataFromSchema = true,
     bubbleErrors = false,
+    generateRequestId,
   }: RunRouteOptions & RunRouteParams
 ): Promise<Out | void> => {
+  const requestId =
+    (request as any).getHeader?.('x-request-id') ||
+    generateRequestId?.() ||
+    createWeakUID()
   const userSession = new PikkuUserSessionService()
   let sessionServices: SessionServices<typeof singletonServices> | undefined
   let result: Out
@@ -414,7 +447,6 @@ export const fetchData = async <In, Out>(
 
   // Locate the matching route based on the HTTP method and path
   const matchedRoute = getMatchingRoute(apiType, apiRoute)
-
   try {
     // If no route matches, log the occurrence and throw a NotFoundError
     if (!matchedRoute) {
@@ -433,9 +465,10 @@ export const fetchData = async <In, Out>(
         userSession,
         createSessionServices,
         skipUserSession,
+        requestId,
       },
       matchedRoute,
-      http,
+      http!,
       { coerceDataFromSchema }
     ))
 
@@ -445,7 +478,7 @@ export const fetchData = async <In, Out>(
     handleError(
       e,
       http,
-      '111', // TODO: context.get('trackingId'),
+      requestId,
       singletonServices.logger,
       logWarningsForStatusCodes,
       respondWith404,