@pikku/core 0.6.13 → 0.6.15

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

@@ -1,4 +1,3 @@
-import { getErrorResponse } from '../errors/error-handler.js'
 import { verifyPermissions } from '../permissions.js'
 import {
   CoreHTTPFunctionRoute,
@@ -6,31 +5,42 @@ import {
   RunRouteOptions,
   RunRouteParams,
   PikkuHTTP,
+  HTTPRouteMiddleware,
 } from './http-routes.types.js'
-import { CoreUserSession, SessionServices } from '../types/core.types.js'
+import { SessionServices } from '../types/core.types.js'
 import { match } from 'path-to-regexp'
 import { PikkuHTTPAbstractRequest } from './pikku-http-abstract-request.js'
 import { PikkuHTTPAbstractResponse } from './pikku-http-abstract-response.js'
-import { Logger, SchemaService } from '../services/index.js'
 import {
   ForbiddenError,
+  MissingSessionError,
   NotFoundError,
-  NotImplementedError,
 } from '../errors/errors.js'
 import crypto from 'crypto'
 import { closeSessionServices } from '../utils.js'
-import { CoreAPIChannel } from '../channel/channel.types.js'
 import { PikkuRequest } from '../pikku-request.js'
 import { PikkuResponse } from '../pikku-response.js'
-import { HTTPSessionService } from './http-session-service.js'
-import { getSchema, validateAndCoerce } from '../schema.js'
+import { coerceQueryStringToArray, validateSchema } from '../schema.js'
+import { LocalUserSessionService } from '../services/user-session-service.js'
+import { runMiddleware } from '../middleware-runner.js'
+import { handleError } from '../handle-error.js'
 
+/**
+ * Initialize global state for HTTP routes and middleware if not already available
+ */
 if (!globalThis.pikku?.httpRoutes) {
   globalThis.pikku = globalThis.pikku || {}
+  globalThis.pikku.httpMiddleware = []
   globalThis.pikku.httpRoutes = []
   globalThis.pikku.httpRoutesMeta = []
 }
 
+/**
+ * Get or set the global HTTP routes
+ *
+ * @param {CoreHTTPFunctionRoute<any, any, any>[]} [data] - Optional routes data to set
+ * @returns {CoreHTTPFunctionRoute<any, any, any>[]} Current routes
+ */
 const httpRoutes = (
   data?: CoreHTTPFunctionRoute<any, any, any>[]
 ): CoreHTTPFunctionRoute<any, any, any>[] => {
@@ -40,6 +50,12 @@ const httpRoutes = (
   return globalThis.pikku.httpRoutes
 }
 
+/**
+ * Get or set the global HTTP route metadata
+ *
+ * @param {HTTPRoutesMeta} [data] - Optional route metadata to set
+ * @returns {HTTPRoutesMeta} Current route metadata
+ */
 const httpRoutesMeta = (data?: HTTPRoutesMeta): HTTPRoutesMeta => {
   if (data) {
     globalThis.pikku.httpRoutesMeta = data
@@ -47,6 +63,49 @@ const httpRoutesMeta = (data?: HTTPRoutesMeta): HTTPRoutesMeta => {
   return globalThis.pikku.httpRoutesMeta
 }
 
+/**
+ * Get or set the global HTTP middleware
+ *
+ * @param {HTTPRouteMiddleware[]} [data] - Optional middleware to set
+ * @returns {HTTPRouteMiddleware[]} Current middleware
+ */
+const httpMiddleware = (
+  data?: HTTPRouteMiddleware[]
+): HTTPRouteMiddleware[] => {
+  if (data) {
+    globalThis.pikku.httpMiddleware = data
+  }
+  return globalThis.pikku.httpMiddleware
+}
+
+/**
+ * Add middleware to a specific route or globally
+ *
+ * @param {APIMiddleware[] | string} routeOrMiddleware - Route pattern to match or middleware array
+ * @param {APIMiddleware} [middleware] - Middleware to add (required if first param is a string)
+ */
+export const addMiddleware = <APIMiddleware>(
+  routeOrMiddleware: APIMiddleware[] | string,
+  middleware?: APIMiddleware
+) => {
+  if (typeof routeOrMiddleware === 'string') {
+    globalThis.pikku.httpMiddleware.push({
+      route: routeOrMiddleware,
+      middleware: middleware!,
+    })
+  } else {
+    globalThis.pikku.httpMiddleware.push({
+      route: '*',
+      middleware: routeOrMiddleware,
+    })
+  }
+}
+
+/**
+ * Add a route to the global routes registry
+ *
+ * @param {CoreHTTPFunctionRoute} route - Route configuration to add
+ */
 export const addRoute = <
   In,
   Out,
@@ -54,6 +113,7 @@ export const addRoute = <
   APIFunction,
   APIFunctionSessionless,
   APIPermission,
+  APIMiddleware,
 >(
   route: CoreHTTPFunctionRoute<
     In,
@@ -61,25 +121,34 @@ export const addRoute = <
     Route,
     APIFunction,
     APIFunctionSessionless,
-    APIPermission
+    APIPermission,
+    APIMiddleware
   >
 ) => {
   httpRoutes().push(route as any)
 }
 
+/**
+ * Remove all routes from the global registry
+ */
 export const clearRoutes = () => {
   httpRoutes([])
 }
 
 /**
+ * Set the HTTP routes metadata
+ *
+ * @param {HTTPRoutesMeta} routeMeta - Metadata for routes
  * @ignore
  */
-export const setHTTPRoutesMeta = (_routeMeta: HTTPRoutesMeta) => {
-  httpRoutesMeta(_routeMeta)
+export const setHTTPRoutesMeta = (routeMeta: HTTPRoutesMeta) => {
+  httpRoutesMeta(routeMeta)
 }
 
 /**
- * Returns all the registered routes and associated metadata.
+ * Returns all the registered routes and associated metadata
+ *
+ * @returns {Object} Object containing routes and routesMeta
  * @internal
  */
 export const getRoutes = () => {
@@ -89,105 +158,66 @@ export const getRoutes = () => {
   }
 }
 
-const getMatchingRoute = (
-  schemaService: SchemaService | undefined,
-  requestType: string,
-  requestPath: string
-) => {
+/**
+ * Find a route that matches the given request type and path
+ *
+ * @param {string} requestType - HTTP method (GET, POST, etc.)
+ * @param {string} requestPath - URL path to match
+ * @returns {Object | undefined} Matching route information or undefined if no match
+ */
+const getMatchingRoute = (requestType: string, requestPath: string) => {
   for (const route of httpRoutes()) {
-    // TODO: This is a performance improvement, but we could
-    // run against all routes if we want to return a 405 method.
-    // Probably want a cache to support.
+    // Skip routes that don't match the request method
     if (route.method !== requestType.toLowerCase()) {
       continue
     }
+
+    // Create path matcher function
     const matchFunc = match(`/${route.route}`.replace(/^\/\//, '/'), {
       decode: decodeURIComponent,
     })
+
+    // Try to match the path
     const matchedPath = matchFunc(requestPath.replace(/^\/\//, '/'))
 
     if (matchedPath) {
-      // TODO: Cache this loop as a performance improvement
+      // Get all middleware for this route
+      const globalMiddleware = httpMiddleware()
+        .filter((m) => m.route === '*' || new RegExp(m.route).test(route.route))
+        .map((m) => m.middleware)
+        .flat()
+
+      // Find schema for this route
       const schemaName = httpRoutesMeta().find(
         (routeMeta) =>
           routeMeta.method === route.method && routeMeta.route === route.route
       )?.input
-      if (schemaName && schemaService) {
-        const schema = getSchema(schemaName)
-        schemaService.compileSchema(schemaName, schema)
-      }
-      return { matchedPath, params: matchedPath.params, route, schemaName }
-    }
-  }
-  return undefined
-}
-
-export const getUserSession = async <UserSession extends CoreUserSession>(
-  httpSessionService: HTTPSessionService<UserSession> | undefined,
-  auth: boolean,
-  request: PikkuHTTPAbstractRequest
-): Promise<CoreUserSession | undefined> => {
-  if (httpSessionService) {
-    return (await httpSessionService.getUserSession(
-      auth,
-      request
-    )) as UserSession
-  } else if (auth) {
-    throw new NotImplementedError('Session service not implemented')
-  }
-  return undefined
-}
-
-export const loadUserSession = async (
-  skipUserSession: boolean,
-  requiresSession: boolean,
-  http: PikkuHTTP | undefined,
-  matchedPath: any,
-  route:
-    | CoreHTTPFunctionRoute<unknown, unknown, any>
-    | CoreAPIChannel<unknown, any>,
-  logger: Logger,
-  httpSessionService: HTTPSessionService | undefined
-) => {
-  if (skipUserSession && requiresSession) {
-    throw new Error("Can't skip trying to get user session if auth is required")
-  }
 
-  if (skipUserSession === false) {
-    try {
-      if (http?.request) {
-        return await getUserSession(
-          httpSessionService,
-          requiresSession,
-          http.request
-        )
-      } else if (requiresSession) {
-        logger.error({
-          action: 'Can only get user session with HTTP request',
-          path: matchedPath,
-          route,
-        })
-        throw new Error('Can only get user session with HTTP request')
-      }
-    } catch (e: any) {
-      if (requiresSession) {
-        logger.info({
-          action: 'Rejecting route (invalid session)',
-          path: matchedPath,
-        })
-        throw e
+      return {
+        matchedPath,
+        params: matchedPath.params,
+        route,
+        middleware: [...globalMiddleware, ...(route.middleware || [])],
+        schemaName,
       }
     }
   }
-
   return undefined
 }
 
+/**
+ * Create an HTTP interaction object from request and response
+ *
+ * @param {PikkuRequest | undefined} request - The HTTP request object
+ * @param {PikkuResponse | undefined} response - The HTTP response object
+ * @returns {PikkuHTTP | undefined} HTTP interaction object or undefined
+ */
 export const createHTTPInteraction = (
   request: PikkuRequest | undefined,
   response: PikkuResponse | undefined
-) => {
+): PikkuHTTP | undefined => {
   let http: PikkuHTTP | undefined = undefined
+
   if (
     request instanceof PikkuHTTPAbstractRequest ||
     response instanceof PikkuHTTPAbstractResponse
@@ -200,52 +230,141 @@ export const createHTTPInteraction = (
       http.response = response
     }
   }
+
   return http
 }
 
-export const handleError = (
-  e: any,
+/**
+ * Validate input data and execute route handler with appropriate middleware
+ *
+ * @param {Object} services - Available services
+ * @param {Object} matchedRoute - Information about the matched route
+ * @param {PikkuHTTP | undefined} http - HTTP interaction object
+ * @param {Object} options - Additional options
+ * @returns {Promise<any>} Result of the route handler
+ */
+const executeRouteWithMiddleware = async (
+  services: {
+    singletonServices: any
+    userSessionService: any
+    createSessionServices: Function
+    skipUserSession: boolean
+  },
+  matchedRoute: {
+    matchedPath: any
+    params: any
+    route: CoreHTTPFunctionRoute<any, any, any>
+    middleware: any[]
+    schemaName?: string | null
+  },
   http: PikkuHTTP | undefined,
-  trackerId: string,
-  logger: Logger,
-  logWarningsForStatusCodes: number[],
-  respondWith404: boolean,
-  bubbleError: boolean
-) => {
-  if (e instanceof NotFoundError && !respondWith404) {
-    return
+  options: {
+    coerceToArray: boolean
   }
+) => {
+  const { matchedPath, params, route, middleware, schemaName } = matchedRoute
+  const {
+    singletonServices,
+    userSessionService,
+    createSessionServices,
+    skipUserSession,
+  } = services
+  const { coerceToArray } = options
+
+  const requiresSession = route.auth !== false
+  let sessionServices: any
+  let result: any
+
+  http?.request?.setParams(params)
+
+  singletonServices.logger.info(
+    `Matched route: ${route.route} | method: ${route.method.toUpperCase()} | auth: ${requiresSession.toString()}`
+  )
 
-  const errorResponse = getErrorResponse(e)
-  if (errorResponse != null) {
-    http?.response?.setStatus(errorResponse.status)
-    http?.response?.setJson({
-      message: errorResponse.message,
-      payload: (e as any).payload,
-      traceId: trackerId,
-    })
+  // Main route execution function
+  const runMain = async () => {
+    const session = userSessionService.get()
 
-    if (logWarningsForStatusCodes.includes(errorResponse.status)) {
-      logger.warn(`Warning id: ${trackerId}`)
-      logger.warn(e)
+    // Validate session was set if needed
+    if (skipUserSession && requiresSession) {
+      throw new Error(
+        "Can't skip trying to get user session if auth is required"
+      )
     }
-  } else {
-    logger.warn(`Error id: ${trackerId}`)
-    logger.error(e)
-    http?.response?.setStatus(500)
-    http?.response?.setJson({ errorId: trackerId })
-  }
 
-  if (e instanceof NotFoundError) {
+    if (requiresSession && !session) {
+      singletonServices.logger.info({
+        action: 'Rejecting route (invalid session)',
+        path: matchedPath,
+      })
+      throw new MissingSessionError()
+    }
+
+    // Create session services
+    sessionServices = await createSessionServices(
+      singletonServices,
+      { http },
+      session
+    )
+
+    const allServices = { ...singletonServices, ...sessionServices, http }
+    const data = await http?.request?.getData()
+
+    // Validate schema
+    validateSchema(
+      singletonServices.logger,
+      singletonServices.schemaService,
+      schemaName,
+      data
+    )
+
+    if (coerceToArray && schemaName) {
+      coerceQueryStringToArray(schemaName, data)
+    }
+
+    // Run permission checks
+    const permissioned = await verifyPermissions(
+      route.permissions,
+      allServices,
+      data,
+      session
+    )
+
+    if (permissioned === false) {
+      throw new ForbiddenError('Permission denied')
+    }
+
+    // Execute the route handler
+    result = await route.func(allServices, data, session!)
+
+    // Set the response
+    if (route.returnsJSON === false) {
+      http?.response?.setResponse(result)
+    } else {
+      http?.response?.setJson(result)
+    }
+
+    http?.response?.setStatus(200)
     http?.response?.end()
-  }
 
-  if (bubbleError) {
-    throw e
+    return result
   }
+
+  await runMiddleware(
+    { ...singletonServices, userSessionService },
+    { http },
+    middleware,
+    runMain
+  )
+
+  return sessionServices ? { result, sessionServices } : { result }
 }
 
 /**
+ * Run an HTTP route with the given parameters
+ *
+ * @param {Object} options - Options for running the route
+ * @returns {Promise<Out | void>} Result of the route handler
  * @ignore
  */
 export const runHTTPRoute = async <In, Out>({
@@ -263,18 +382,20 @@ export const runHTTPRoute = async <In, Out>({
 }: Pick<CoreHTTPFunctionRoute<unknown, unknown, any>, 'route' | 'method'> &
   RunRouteOptions &
   RunRouteParams<In>): Promise<Out | void> => {
-  let sessionServices: SessionServices<typeof singletonServices> | undefined
   const trackerId: string = crypto.randomUUID().toString()
 
+  const userSessionService = new LocalUserSessionService()
+  let sessionServices: SessionServices<typeof singletonServices> | undefined
+  let result: Out
+
+  // Create HTTP interaction object
   const http = createHTTPInteraction(request, response)
 
-  const matchedRoute = getMatchingRoute(
-    singletonServices.schemaService,
-    apiType,
-    apiRoute
-  )
+  // Find matching route
+  const matchedRoute = getMatchingRoute(apiType, apiRoute)
 
   try {
+    // Handle route not found
     if (!matchedRoute) {
       singletonServices.logger.info({
         message: 'Route not found',
@@ -284,70 +405,22 @@ export const runHTTPRoute = async <In, Out>({
       throw new NotFoundError(`Route not found: ${apiRoute}`)
     }
 
-    const { matchedPath, params, route, schemaName } = matchedRoute
-    const requiresSession = route.auth !== false
-    http?.request?.setParams(params)
-
-    singletonServices.logger.info(
-      `Matched route: ${route.route} | method: ${route.method.toUpperCase()} | auth: ${requiresSession.toString()}`
-    )
-
-    const session = await loadUserSession(
-      skipUserSession,
-      requiresSession,
+    // Execute route with middleware
+    ;({ result, sessionServices } = await executeRouteWithMiddleware(
+      {
+        singletonServices,
+        userSessionService,
+        createSessionServices,
+        skipUserSession,
+      },
+      matchedRoute,
       http,
-      matchedPath,
-      route,
-      singletonServices.logger,
-      singletonServices.httpSessionService
-    )
-    const data = await request.getData()
-
-    validateAndCoerce(
-      singletonServices.logger,
-      singletonServices.schemaService,
-      schemaName,
-      data,
-      coerceToArray
-    )
-
-    sessionServices = await createSessionServices(
-      singletonServices,
-      { http },
-      session
-    )
-    const allServices = { ...singletonServices, ...sessionServices, http }
-
-    if (singletonServices.enforceHTTPAccess) {
-      await singletonServices.enforceHTTPAccess(route, session)
-    }
-
-    const permissioned = await verifyPermissions(
-      route.permissions,
-      allServices,
-      data,
-      session
-    )
-    if (permissioned === false) {
-      throw new ForbiddenError('Permission denied')
-    }
-
-    const result: any = (await route.func(
-      allServices,
-      data,
-      session!
-    )) as unknown as Out
-
-    if (route.returnsJSON === false) {
-      http?.response?.setResponse(result)
-    } else {
-      http?.response?.setJson(result)
-    }
-    http?.response?.setStatus(200)
-    http?.response?.end()
+      { coerceToArray }
+    ))
 
     return result
   } catch (e: any) {
+    // Handle and possibly bubble the error
     handleError(
       e,
       http,
@@ -358,6 +431,7 @@ export const runHTTPRoute = async <In, Out>({
       bubbleErrors
     )
   } finally {
+    // Clean up session services
     if (sessionServices) {
       await closeSessionServices(singletonServices.logger, sessionServices)
     }

package/src/http/http-routes.types.ts

@@ -5,6 +5,7 @@ import {
   CoreSingletonServices,
   CoreUserSession,
   CreateSessionServices,
+  PikkuMiddleware,
 } from '../types/core.types.js'
 import {
   CoreAPIFunction,
@@ -115,6 +116,7 @@ export type CoreHTTPFunctionRoute<
   APIFunction = CoreAPIFunction<In, Out>,
   APIFunctionSessionless = CoreAPIFunctionSessionless<In, Out>,
   APIPermission = CoreAPIPermission<In>,
+  APIMiddleware = PikkuMiddleware,
 > =
   | (CoreHTTPFunction & {
       route: R
@@ -122,6 +124,8 @@ export type CoreHTTPFunctionRoute<
       func: APIFunction
       permissions?: Record<string, APIPermission[] | APIPermission>
       auth?: true
+      tags?: string[]
+      middleware?: APIMiddleware[]
     })
   | (CoreHTTPFunction & {
       route: R
@@ -129,6 +133,8 @@ export type CoreHTTPFunctionRoute<
       func: APIFunctionSessionless
       permissions?: undefined
       auth?: false
+      tags?: string[]
+      middleware?: APIMiddleware[]
     })
   | (CoreHTTPFunction & {
       route: R
@@ -137,6 +143,8 @@ export type CoreHTTPFunctionRoute<
       permissions?: Record<string, APIPermission[] | APIPermission>
       auth?: true
       query?: Array<keyof In>
+      tags?: string[]
+      middleware?: APIMiddleware[]
     })
   | (CoreHTTPFunction & {
       route: R
@@ -145,6 +153,8 @@ export type CoreHTTPFunctionRoute<
       permissions?: undefined
       auth?: false
       query?: Array<keyof In>
+      tags?: string[]
+      middleware?: APIMiddleware[]
     })
 
 /**
@@ -175,15 +185,10 @@ export type HTTPRoutesMeta = Array<{
   output: string | null
   inputTypes?: HTTPFunctionMetaInputTypes
   docs?: APIDocs
+  tags?: string[]
 }>
 
-/**
- * Verifies access to a route.
- * @param route - The route to verify access for.
- * @param session - The user session.
- * @returns A promise that resolves if access is granted.
- */
-export type enforceHTTPAccess = (
-  route: CoreHTTPFunctionRoute<unknown, unknown, any>,
-  session?: CoreUserSession
-) => Promise<void> | void
+export type HTTPRouteMiddleware = {
+  route: string
+  middleware: PikkuMiddleware[]
+}

package/src/http/index.ts

@@ -1,5 +1,3 @@
-export * from './pikku-http-session-service.js'
-
 export * from './pikku-http-abstract-request.js'
 
 export * from './pikku-http-abstract-response.js'

package/src/http/pikku-http-abstract-request.ts

@@ -1,6 +1,6 @@
 import { parse as parseCookie } from 'cookie'
 import { PikkuRequest } from '../pikku-request.js'
-import { PikkuQuery } from './http-routes.types.js'
+import { HTTPMethod, PikkuQuery } from './http-routes.types.js'
 
 /**
  * Abstract class representing a pikku request.
@@ -12,6 +12,13 @@ export abstract class PikkuHTTPAbstractRequest<
 > extends PikkuRequest<In> {
   private params: Partial<Record<string, string | string[]>> = {}
 
+  constructor(
+    public path: string,
+    public method: HTTPMethod
+  ) {
+    super()
+  }
+
   /**
    * Retrieves the request body.
    * @returns A promise that resolves to the request body.

package/src/index.ts

@@ -10,7 +10,9 @@ export * from './http/index.js'
 export * from './channel/index.js'
 export * from './scheduler/index.js'
 export * from './errors/index.js'
+export * from './middleware/index.js'
 
+export { runMiddleware } from './middleware-runner.js'
 export { addRoute } from './http/http-route-runner.js'
 export { addChannel } from './channel/channel-runner.js'
 export { addScheduledTask } from './scheduler/scheduler-runner.js'