@pikku/core 0.6.20 → 0.6.22

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

@@ -1,39 +1,20 @@
 import { test, describe, beforeEach, afterEach } from 'node:test'
 import * as assert from 'assert'
 import { NotFoundError } from '../errors/errors.js'
-import { PikkuHTTPAbstractRequest } from './pikku-http-abstract-request.js'
-import { PikkuHTTPAbstractResponse } from './pikku-http-abstract-response.js'
 import { JSONValue, PikkuMiddleware } from '../types/core.types.js'
-import { runHTTPRoute, addRoute } from './http-route-runner.js'
+import { fetch, addRoute } from './http-route-runner.js'
 import { resetPikkuState } from '../pikku-state.js'
-
-class PikkuTestRequest extends PikkuHTTPAbstractRequest {
-  public getBody(): Promise<unknown> {
-    throw new Error('Method not implemented.')
-  }
-  public getHeader(_headerName: string): string | undefined {
-    throw new Error('Method not implemented.')
-  }
-}
-
-class PikkuTestResponse extends PikkuHTTPAbstractResponse {
-  public setStatus(_status: number): void {
-    throw new Error('Method not implemented.')
-  }
-  public setJson(_body: JSONValue): void {
-    throw new Error('Method not implemented.')
-  }
-  public setResponse(_response: string | Buffer): void {
-    throw new Error('Method not implemented.')
-  }
-}
+import {
+  PikkuMockRequest,
+  PikkuMockResponse,
+} from '../channel/local/local-channel-runner.test.js'
 
 const sessionMiddleware: PikkuMiddleware = async (services, _, next) => {
   services.userSessionService.set({ userId: 'test' } as any)
   await next()
 }
 
-describe('runHTTPRoute', () => {
+describe('fetch', () => {
   let singletonServices: any
   let createSessionServices: any
   let request: any
@@ -51,8 +32,8 @@ describe('runHTTPRoute', () => {
     }
 
     createSessionServices = async () => ({})
-    request = new PikkuTestRequest('path', 'get')
-    response = new PikkuTestResponse()
+    request = new PikkuMockRequest('/test', 'get')
+    response = new PikkuMockResponse()
 
     request.getData = async () => ({})
     request.getHeader = () => 'application/json'
@@ -63,18 +44,11 @@ describe('runHTTPRoute', () => {
   afterEach(() => {})
 
   test('should throw RouteNotFoundError when no matching route is found', async () => {
-    const apiRoute = '/test'
-    const apiType = 'get'
-
     await assert.rejects(
       async () =>
-        runHTTPRoute({
-          request,
-          response,
+        fetch(request, {
           singletonServices,
           createSessionServices,
-          route: apiRoute,
-          method: apiType,
           bubbleErrors: true,
         }),
       NotFoundError
@@ -82,8 +56,6 @@ describe('runHTTPRoute', () => {
   })
 
   test('should call the route function and return its result when a matching route is found', async () => {
-    const apiRoute = '/test'
-    const apiType = 'get'
     const routeFunc = async () => ({ success: true })
     addRoute({
       route: 'test',
@@ -92,21 +64,15 @@ describe('runHTTPRoute', () => {
       middleware: [sessionMiddleware],
     })
 
-    const result = await runHTTPRoute({
-      request,
-      response,
+    const result = await fetch(request, {
       singletonServices,
       createSessionServices,
-      route: apiRoute,
-      method: apiType,
     })
 
-    assert.deepStrictEqual(result, { success: true })
+    assert.deepStrictEqual(await result.json(), { success: true })
   })
 
   test('should verify permissions if provided', async () => {
-    const apiRoute = '/test'
-    const apiType = 'get'
     const permissions = { test: async () => true }
     const routeFunc = async () => ({ success: true })
 
@@ -118,21 +84,15 @@ describe('runHTTPRoute', () => {
       middleware: [sessionMiddleware],
     })
 
-    await runHTTPRoute({
-      request,
-      response,
+    await fetch(request, {
       singletonServices,
       createSessionServices,
-      route: apiRoute,
-      method: apiType,
     })
 
     assert.strictEqual(await permissions.test(), true)
   })
 
   test('should handle errors and set appropriate response', async () => {
-    const apiRoute = '/test'
-    const apiType = 'get'
     const error = new Error('Test error')
     const routeFunc = async () => {
       throw error
@@ -146,13 +106,9 @@ describe('runHTTPRoute', () => {
 
     await assert.rejects(
       async () =>
-        runHTTPRoute({
-          request,
-          response,
+        fetch(request, {
           singletonServices,
           createSessionServices,
-          route: apiRoute,
-          method: apiType,
           bubbleErrors: true,
         }),
       error

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

@@ -4,30 +4,35 @@ import {
   RunRouteOptions,
   RunRouteParams,
   PikkuHTTP,
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
 } from './http-routes.types.js'
 import { PikkuMiddleware, 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 {
   ForbiddenError,
   MissingSessionError,
   NotFoundError,
 } from '../errors/errors.js'
 import { closeSessionServices } from '../utils.js'
-import { PikkuRequest } from '../pikku-request.js'
-import { PikkuResponse } from '../pikku-response.js'
 import { coerceQueryStringToArray, validateSchema } from '../schema.js'
-import { LocalUserSessionService } from '../services/user-session-service.js'
+import { PikkuUserSessionService } from '../services/user-session-service.js'
 import { runMiddleware } from '../middleware-runner.js'
 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'
 
 /**
- * Add middleware to a specific route or globally
+ * Registers middleware either globally or for a specific route.
  *
- * @param {APIMiddleware[] | string} routeOrMiddleware - Route pattern to match or middleware array
- * @param {APIMiddleware} [middleware] - Middleware to add (required if first param is a string)
+ * When a string route pattern is provided along with middleware, the middleware
+ * is applied only to that route. Otherwise, if an array is provided, it is treated
+ * as global middleware (applied to all routes).
+ *
+ * @template APIMiddleware The middleware type.
+ * @param {APIMiddleware[] | string} routeOrMiddleware - Either a global middleware array or a route pattern string.
+ * @param {APIMiddleware[]} [middleware] - The middleware array to apply when a route pattern is specified.
  */
 export const addMiddleware = <APIMiddleware extends PikkuMiddleware>(
   routeOrMiddleware: APIMiddleware[] | string,
@@ -47,9 +52,19 @@ export const addMiddleware = <APIMiddleware extends PikkuMiddleware>(
 }
 
 /**
- * Add a route to the global routes registry
+ * Adds a new route to the global HTTP route registry.
+ *
+ * The route configuration includes the HTTP method, route path, permissions,
+ * middleware, and the handler function that implements the route's logic.
  *
- * @param {CoreHTTPFunctionRoute} route - Route configuration to add
+ * @template In Expected input type.
+ * @template Out Expected output type.
+ * @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 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 = <
   In,
@@ -74,11 +89,15 @@ export const addRoute = <
 }
 
 /**
- * Find a route that matches the given request type and path
+ * Finds a matching route based on the HTTP method and URL 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
+ * Iterates over all registered routes, skipping those with a mismatched method.
+ * When a route pattern matches the incoming request path, this function aggregates
+ * any global middleware along with route-specific middleware and identifies any input schema.
+ *
+ * @param {string} requestType - The HTTP method (e.g., GET, POST).
+ * @param {string} requestPath - The URL path of the incoming request.
+ * @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')
@@ -86,27 +105,27 @@ const getMatchingRoute = (requestType: string, requestPath: string) => {
   const routesMeta = pikkuState('http', 'meta')
 
   for (const route of routes) {
-    // Skip routes that don't match the request method
+    // Skip routes that don't match the HTTP method
     if (route.method !== requestType.toLowerCase()) {
       continue
     }
 
-    // Create path matcher function
+    // Generate a matching function from the route pattern
     const matchFunc = match(`/${route.route}`.replace(/^\/\//, '/'), {
       decode: decodeURIComponent,
     })
 
-    // Try to match the path
+    // Attempt to match the request path
     const matchedPath = matchFunc(requestPath.replace(/^\/\//, '/'))
 
     if (matchedPath) {
-      // Get all middleware for this route
+      // Aggregate global and route-specific middleware
       const globalMiddleware = middleware
         .filter((m) => m.route === '*' || new RegExp(m.route).test(route.route))
         .map((m) => m.middleware)
         .flat()
 
-      // Find schema for this route
+      // Extract associated schema information if available
       const schemaName = routesMeta.find(
         (routeMeta) =>
           routeMeta.method === route.method && routeMeta.route === route.route
@@ -125,27 +144,27 @@ const getMatchingRoute = (requestType: string, requestPath: string) => {
 }
 
 /**
- * Create an HTTP interaction object from request and response
+ * Combines the request and response objects into a single HTTP interaction object.
+ *
+ * This utility function creates an object that holds both the HTTP request and response,
+ * which simplifies passing these around through middleware and route execution.
  *
- * @param {PikkuRequest | undefined} request - The HTTP request object
- * @param {PikkuResponse | undefined} response - The HTTP response object
- * @returns {PikkuHTTP | undefined} HTTP interaction object or undefined
+ * @param {PikkuHTTPRequest | undefined} request - The HTTP request object.
+ * @param {PikkuHTTPResponse | undefined} response - The HTTP response object.
+ * @returns {PikkuHTTP | undefined} The combined HTTP interaction object or undefined if none provided.
  */
 export const createHTTPInteraction = (
-  request: PikkuRequest | undefined,
-  response: PikkuResponse | undefined
+  request: PikkuHTTPRequest | undefined,
+  response: PikkuHTTPResponse | undefined
 ): PikkuHTTP | undefined => {
   let http: PikkuHTTP | undefined = undefined
 
-  if (
-    request instanceof PikkuHTTPAbstractRequest ||
-    response instanceof PikkuHTTPAbstractResponse
-  ) {
+  if (request || response) {
     http = {}
-    if (request instanceof PikkuHTTPAbstractRequest) {
+    if (request) {
       http.request = request
     }
-    if (response instanceof PikkuHTTPAbstractResponse) {
+    if (response) {
       http.response = response
     }
   }
@@ -154,19 +173,29 @@ export const createHTTPInteraction = (
 }
 
 /**
- * Validate input data and execute route handler with appropriate middleware
+ * Validates the input data and executes the route handler with associated 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
+ * This function is the central execution point for a route. It performs these steps:
+ *  1. Sets URL parameters on the request.
+ *  2. Validates the user session if required.
+ *  3. Creates session-specific services.
+ *  4. Validates the incoming data against a schema.
+ *  5. Optionally coerces query string values to arrays.
+ *  6. Checks route-specific permissions.
+ *  7. Executes the route handler.
+ *  8. Sends the appropriate response.
+ *
+ * @param {Object} services - A collection of shared services and utilities.
+ * @param {Object} matchedRoute - Contains route details, URL parameters, middleware, and optional schema.
+ * @param {PikkuHTTP | undefined} http - The HTTP interaction object.
+ * @param {Object} options - Options for route execution (e.g., whether to coerce query strings to arrays).
+ * @returns {Promise<any>} An object containing the route handler result and session services (if any).
+ * @throws Throws errors like MissingSessionError or ForbiddenError on validation failures.
  */
 const executeRouteWithMiddleware = async (
   services: {
     singletonServices: any
     userSessionService: any
-    context: Map<string, unknown>
     createSessionServices: Function
     skipUserSession: boolean
   },
@@ -186,7 +215,6 @@ const executeRouteWithMiddleware = async (
   const {
     singletonServices,
     userSessionService,
-    context,
     createSessionServices,
     skipUserSession,
   } = services
@@ -195,17 +223,18 @@ const executeRouteWithMiddleware = async (
   let sessionServices: any
   let result: any
 
+  // Attach URL parameters to the request object
   http?.request?.setParams(params)
 
   singletonServices.logger.info(
     `Matched route: ${route.route} | method: ${route.method.toUpperCase()} | auth: ${requiresSession.toString()}`
   )
 
-  // Main route execution function
+  // Main route execution logic wrapped for middleware handling
   const runMain = async () => {
     const session = userSessionService.get()
 
-    // Validate session was set if needed
+    // Ensure session is available when required
     if (skipUserSession && requiresSession) {
       throw new Error(
         "Can't skip trying to get user session if auth is required"
@@ -220,29 +249,39 @@ const executeRouteWithMiddleware = async (
       throw new MissingSessionError()
     }
 
-    // Create session services
+    // Create session-specific services for handling the request
     sessionServices = await createSessionServices(
-      { ...singletonServices, context },
+      { ...singletonServices, userSessionService },
       { http },
       session
     )
 
-    const allServices = { ...singletonServices, ...sessionServices, context }
-    const data = await http?.request?.getData()
-
-    // Validate schema
-    validateSchema(
-      singletonServices.logger,
-      singletonServices.schemaService,
-      schemaName,
-      data
-    )
+    const allServices = {
+      ...singletonServices,
+      ...sessionServices,
+      http,
+    }
+    const data = await http?.request?.data()
+
+    // Validate request data against the defined schema, if any
+    try {
+      console.log(schemaName, data)
+      validateSchema(
+        singletonServices.logger,
+        singletonServices.schemaService,
+        schemaName,
+        data
+      )
+    } catch (e) {
+      // TODO: Implement proper handling for schema validation failures
+    }
 
+    // Coerce query string parameters to arrays if specified by the schema
     if (options.coerceToArray && schemaName) {
       coerceQueryStringToArray(schemaName, data)
     }
 
-    // Run permission checks
+    // Execute permission checks
     const permissioned = await verifyPermissions(
       route.permissions,
       allServices,
@@ -254,24 +293,26 @@ const executeRouteWithMiddleware = async (
       throw new ForbiddenError('Permission denied')
     }
 
-    // Execute the route handler
+    // Invoke the actual route handler function
     result = await route.func(allServices, data, session!)
 
-    // Set the response
+    // Respond with either a binary or JSON response based on configuration
     if (route.returnsJSON === false) {
-      http?.response?.setResponse(result)
+      http?.response?.arrayBuffer(result)
     } else {
-      http?.response?.setJson(result)
+      http?.response?.json(result)
     }
 
-    http?.response?.setStatus(200)
-    http?.response?.end()
+    http?.response?.status(200)
+    // TODO: Evaluate if the response stream should be explicitly ended.
+    // http?.response?.end()
 
     return result
   }
 
+  // Execute middleware, then run the main logic
   await runMiddleware(
-    { ...singletonServices, context, userSessionService },
+    { ...singletonServices, userSessionService },
     { http },
     middleware,
     runMain
@@ -281,41 +322,98 @@ const executeRouteWithMiddleware = async (
 }
 
 /**
- * Run an HTTP route with the given parameters
+ * Executes an HTTP route for a given Fetch API request.
+ *
+ * This function wraps the entire lifecycle of handling an HTTP request:
+ *  - Matching the request to a registered route.
+ *  - Validating input and session state.
+ *  - Running middleware and the route handler.
+ *  - Handling errors and forming the response.
  *
- * @param {Object} options - Options for running the route
- * @returns {Promise<Out | void>} Result of the route handler
- * @ignore
+ * @template In Expected input data type.
+ * @template Out Expected output data type.
+ * @param {Request} request - The native Fetch API Request object.
+ * @param {RunRouteOptions & RunRouteParams} params - Additional options including services and session management.
+ * @returns {Promise<Response>} A promise that resolves to a Fetch API Response object.
  */
-export const runHTTPRoute = async <In, Out>({
-  singletonServices,
-  request,
-  response,
-  createSessionServices,
-  route: apiRoute,
-  method: apiType,
-  skipUserSession = false,
-  respondWith404 = true,
-  logWarningsForStatusCodes = [],
-  coerceToArray = false,
-  bubbleErrors = false,
-}: Pick<CoreHTTPFunctionRoute<unknown, unknown, any>, 'route' | 'method'> &
-  RunRouteOptions &
-  RunRouteParams<In>): Promise<Out | void> => {
-  const context = new Map()
-
-  const userSessionService = new LocalUserSessionService()
+export const fetch = async <In, Out>(
+  request: Request,
+  params: RunRouteOptions & RunRouteParams
+): Promise<Response> => {
+  const pikkuResponse = new PikkuFetchHTTPResponse()
+  await fetchData<In, Out>(request, pikkuResponse, params)
+  return pikkuResponse.toResponse()
+}
+
+/**
+ * Executes an HTTP route using a Pikku-specific request wrapper.
+ *
+ * This variant accepts either a native Request or a PikkuHTTPRequest object and returns
+ * a PikkuFetchHTTPResponse for further manipulation if needed.
+ *
+ * @template In Expected input data type.
+ * @template Out Expected output data type.
+ * @param {Request | PikkuHTTPRequest} request - The request object.
+ * @param {RunRouteOptions & RunRouteParams} params - Execution options including services and session configuration.
+ * @returns {Promise<PikkuFetchHTTPResponse>} A promise that resolves to a PikkuFetchHTTPResponse object.
+ */
+export const pikkuFetch = async <In, Out>(
+  request: Request | PikkuHTTPRequest,
+  params: RunRouteOptions & RunRouteParams
+): Promise<PikkuFetchHTTPResponse> => {
+  const pikkuResponse = new PikkuFetchHTTPResponse()
+  await fetchData<In, Out>(request, pikkuResponse, params)
+  return pikkuResponse
+}
+
+/**
+ * Core function to process an HTTP request through route matching, validation,
+ * middleware execution, error handling, and session service cleanup.
+ *
+ * This function does the following:
+ *  - Wraps the incoming request and response into an HTTP interaction object.
+ *  - Determines the correct route based on HTTP method and path.
+ *  - Executes middleware and the route handler.
+ *  - Catches and handles errors, optionally bubbling them if configured.
+ *  - Cleans up any session services created during processing.
+ *
+ * @template In Expected input data type.
+ * @template Out Expected output data type.
+ * @param {Request | PikkuHTTPRequest} request - The incoming HTTP request.
+ * @param {PikkuHTTPResponse} response - The response object to be populated.
+ * @param {RunRouteOptions & RunRouteParams} options - Options such as singleton services, session handling, and error configuration.
+ * @returns {Promise<Out | void>} The output from the route handler or void if an error occurred.
+ */
+export const fetchData = async <In, Out>(
+  request: Request | PikkuHTTPRequest,
+  response: PikkuHTTPResponse,
+  {
+    singletonServices,
+    createSessionServices,
+    skipUserSession = false,
+    respondWith404 = true,
+    logWarningsForStatusCodes = [],
+    coerceToArray = false,
+    bubbleErrors = false,
+  }: RunRouteOptions & RunRouteParams
+): Promise<Out | void> => {
+  const userSessionService = new PikkuUserSessionService()
   let sessionServices: SessionServices<typeof singletonServices> | undefined
   let result: Out
 
-  // Create HTTP interaction object
-  const http = createHTTPInteraction(request, response)
+  // Combine the request and response into one interaction object
+  const http = createHTTPInteraction(
+    request instanceof Request ? new PikkuFetchHTTPRequest(request) : request,
+    response
+  )
+  const apiType = http!.request!.method()
+  const apiRoute = http!.request!.path()
 
-  // Find matching route
+  // Locate the matching route based on the HTTP method and path
   const matchedRoute = getMatchingRoute(apiType, apiRoute)
 
   try {
-    // Handle route not found
+    // If no route matches, log the occurrence and throw a NotFoundError
     if (!matchedRoute) {
       singletonServices.logger.info({
         message: 'Route not found',
@@ -325,12 +423,11 @@ export const runHTTPRoute = async <In, Out>({
       throw new NotFoundError(`Route not found: ${apiRoute}`)
     }
 
-    // Execute route with middleware
+    // Execute the matched route along with its middleware and session management
     ;({ result, sessionServices } = await executeRouteWithMiddleware(
       {
         singletonServices,
         userSessionService,
-        context,
         createSessionServices,
         skipUserSession,
       },
@@ -341,18 +438,18 @@ export const runHTTPRoute = async <In, Out>({
 
     return result
   } catch (e: any) {
-    // Handle and possibly bubble the error
+    // Handle errors and, depending on configuration, bubble them up or respond with an error
     handleError(
       e,
       http,
-      context.get('trackingId'),
+      '111', // TODO: context.get('trackingId'),
       singletonServices.logger,
       logWarningsForStatusCodes,
       respondWith404,
       bubbleErrors
     )
   } finally {
-    // Clean up session services
+    // Clean up any session-specific services created during processing
     if (sessionServices) {
       await closeSessionServices(singletonServices.logger, sessionServices)
     }

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

@@ -1,3 +1,4 @@
+import { SerializeOptions } from 'cookie'
 import { PikkuError } from '../errors/error-handler.js'
 import {
   APIDocs,
@@ -12,10 +13,6 @@ import {
   CoreAPIFunctionSessionless,
   CoreAPIPermission,
 } from '../types/functions.types.js'
-import { PikkuRequest } from '../pikku-request.js'
-import { PikkuResponse } from '../pikku-response.js'
-import { PikkuHTTPAbstractRequest } from './pikku-http-abstract-request.js'
-import { PikkuHTTPAbstractResponse } from './pikku-http-abstract-response.js'
 
 type ExtractRouteParams<S extends string> =
   S extends `${string}:${infer Param}/${infer Rest}`
@@ -37,10 +34,8 @@ export type RunRouteOptions = Partial<{
   bubbleErrors: boolean
 }>
 
-export type RunRouteParams<In> = {
+export type RunRouteParams = {
   singletonServices: CoreSingletonServices
-  request: PikkuRequest<In> | PikkuHTTPAbstractRequest<In>
-  response?: PikkuResponse | PikkuHTTPAbstractResponse | undefined
   createSessionServices: CreateSessionServices<
     CoreSingletonServices,
     CoreServices<CoreSingletonServices>,
@@ -80,8 +75,8 @@ export type CoreHTTPFunction = {
  * Represents a http interaction within Pikku, including a request and response.
  */
 export interface PikkuHTTP {
-  request?: PikkuHTTPAbstractRequest
-  response?: PikkuHTTPAbstractResponse
+  request?: PikkuHTTPRequest
+  response?: PikkuHTTPResponse
 }
 
 /**
@@ -192,3 +187,25 @@ export type HTTPRouteMiddleware = {
   route: string
   middleware: PikkuMiddleware[]
 }
+
+export interface PikkuHTTPRequest<In = unknown> {
+  method(): HTTPMethod
+  path(): string
+  data(): Promise<In>
+  json(): Promise<unknown>
+  arrayBuffer(): Promise<ArrayBuffer>
+  header(headerName: string): string | null
+  cookie(name?: string): string | null
+  params(): Partial<Record<string, string | string[]>>
+  setParams(params: Record<string, string | string[] | undefined>): void
+  query(): PikkuQuery
+}
+
+export interface PikkuHTTPResponse {
+  status(code: number): this
+  cookie(name: string, value: string | null, options: SerializeOptions): this
+  header(name: string, value: string | string[]): this
+  arrayBuffer(data: XMLHttpRequestBodyInit): this
+  json(data: unknown): this
+  redirect(location: string, status?: number): this
+}