@pikku/core 0.6.27 → 0.7.0

package/dist/http/http-runner.js

@@ -0,0 +1,336 @@
+import { match } from 'path-to-regexp';
+import { MissingSessionError, NotFoundError } from '../errors/errors.js';
+import { closeSessionServices, createWeakUID, isSerializable, } from '../utils.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';
+import { addFunction, runPikkuFunc } from '../function/function-runner.js';
+/**
+ * Registers middleware either globally or for a specific route.
+ *
+ * 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 = (routeOrMiddleware, middleware) => {
+    if (typeof routeOrMiddleware === 'string' && middleware) {
+        pikkuState('http', 'middleware').push({
+            route: routeOrMiddleware,
+            middleware,
+        });
+    }
+    else {
+        pikkuState('http', 'middleware').push({
+            route: '*',
+            middleware: routeOrMiddleware,
+        });
+    }
+};
+/**
+ * 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.
+ *
+ * @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 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 addHTTPRoute = (httpRoute) => {
+    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);
+    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);
+};
+/**
+ * Finds a matching route based on the HTTP method and URL path.
+ *
+ * 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, requestPath) => {
+    const allRoutes = pikkuState('http', 'routes');
+    const middleware = pikkuState('http', 'middleware');
+    const routes = allRoutes.get(requestType.toLowerCase());
+    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,
+        });
+        // Attempt to match the request path
+        const matchedPath = matchFunc(requestPath.replace(/^\/\//, '/'));
+        if (matchedPath) {
+            // 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();
+            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 || [])],
+                meta: meta
+            };
+        }
+    }
+    return undefined;
+};
+/**
+ * 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 {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, response) => {
+    let http = undefined;
+    if (request || response) {
+        http = {};
+        if (request) {
+            http.request = request;
+        }
+        if (response) {
+            http.response = response;
+        }
+    }
+    return http;
+};
+/**
+ * Validates the input data and executes the route handler with associated middleware.
+ *
+ * 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, matchedRoute, http, options) => {
+    const { matchedPath, params, route, middleware, meta } = matchedRoute;
+    const { singletonServices, userSession, createSessionServices, skipUserSession, requestId, } = services;
+    const requiresSession = route.auth !== false;
+    let sessionServices;
+    let result;
+    // 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 logic wrapped for middleware handling
+    const runMain = async () => {
+        const session = userSession.get();
+        // Ensure session is available when required
+        if (skipUserSession && requiresSession) {
+            throw new Error("Can't skip trying to get user session if auth is required");
+        }
+        if (requiresSession && !session) {
+            singletonServices.logger.info({
+                action: 'Rejecting route (invalid session)',
+                path: matchedPath,
+            });
+            throw new MissingSessionError();
+        }
+        const data = http.request.data();
+        const getAllServices = async () => {
+            let channel;
+            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) => {
+                        response.arrayBuffer(isSerializable(data) ? JSON.stringify(data) : data);
+                    },
+                    close: () => {
+                        channel.state = 'closed';
+                        response.close?.();
+                    },
+                    state: 'open',
+                };
+            }
+            // Create session-specific services for handling the request
+            sessionServices = await createSessionServices({ ...singletonServices, userSession, channel }, { http }, session);
+            return {
+                ...singletonServices,
+                ...sessionServices,
+                http,
+                userSession,
+                channel,
+            };
+        };
+        const result = await runPikkuFunc(meta.pikkuFuncName, {
+            singletonServices,
+            getAllServices,
+            session,
+            data,
+            permissions: route.permissions,
+            coerceDataFromSchema: options.coerceDataFromSchema,
+        });
+        // Respond with either a binary or JSON response based on configuration
+        if (route.returnsJSON === false) {
+            http?.response?.arrayBuffer(result);
+        }
+        else {
+            http?.response?.json(result);
+        }
+        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, userSession }, { http }, middleware, runMain);
+    return sessionServices ? { result, sessionServices } : { result };
+};
+/**
+ * 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.
+ *
+ * @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 fetch = async (request, params) => {
+    const pikkuResponse = new PikkuFetchHTTPResponse();
+    await fetchData(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 (request, params) => {
+    const pikkuResponse = new PikkuFetchHTTPResponse();
+    await fetchData(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 (request, response, { singletonServices, createSessionServices, skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceDataFromSchema = true, bubbleErrors = false, generateRequestId, }) => {
+    const requestId = request.getHeader?.('x-request-id') ||
+        generateRequestId?.() ||
+        createWeakUID();
+    const userSession = new PikkuUserSessionService();
+    let sessionServices;
+    let result;
+    // 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();
+    // 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) {
+            singletonServices.logger.info({
+                message: 'Route not found',
+                apiRoute,
+                apiType,
+            });
+            throw new NotFoundError(`Route not found: ${apiRoute}`);
+        }
+        // Execute the matched route along with its middleware and session management
+        ;
+        ({ result, sessionServices } = await executeRouteWithMiddleware({
+            singletonServices,
+            userSession,
+            createSessionServices,
+            skipUserSession,
+            requestId,
+        }, matchedRoute, http, { coerceDataFromSchema }));
+        return result;
+    }
+    catch (e) {
+        // Handle errors and, depending on configuration, bubble them up or respond with an error
+        handleError(e, http, requestId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
+    }
+    finally {
+        // Clean up any session-specific services created during processing
+        if (sessionServices) {
+            await closeSessionServices(singletonServices.logger, sessionServices);
+        }
+    }
+};

package/dist/http/http.types.d.ts

@@ -0,0 +1,177 @@
+import type { SerializeOptions } from 'cookie';
+import type { PikkuError } from '../errors/error-handler.js';
+import type { APIDocs, CoreServices, CoreSingletonServices, CoreUserSession, CreateSessionServices, PikkuMiddleware } from '../types/core.types.js';
+import type { CoreAPIFunction, CoreAPIFunctionSessionless, CoreAPIPermission, CorePermissionGroup } from '../function/functions.types.js';
+type ExtractRouteParams<S extends string> = S extends `${string}:${infer Param}/${infer Rest}` ? Param | ExtractRouteParams<`/${Rest}`> : S extends `${string}:${infer Param}` ? Param : never;
+export type AssertRouteParams<In, Route extends string> = ExtractRouteParams<Route> extends keyof In ? unknown : ['Error: Route parameters', ExtractRouteParams<Route>, 'not in', keyof In];
+export type RunRouteOptions = Partial<{
+    skipUserSession: boolean;
+    respondWith404: boolean;
+    logWarningsForStatusCodes: number[];
+    coerceDataFromSchema: boolean;
+    bubbleErrors: boolean;
+    generateRequestId: () => string;
+}>;
+export type RunRouteParams = {
+    singletonServices: CoreSingletonServices;
+    createSessionServices: CreateSessionServices<CoreSingletonServices, CoreServices<CoreSingletonServices>, CoreUserSession>;
+};
+/**
+ * Represents the HTTP methods supported for API routes.
+ */
+export type HTTPMethod = 'post' | 'get' | 'delete' | 'patch' | 'head' | 'put' | 'options';
+/**
+ * Represents an API route without a function, including metadata such as content type, route, and timeout settings.
+ */
+export type CoreHTTPFunction = {
+    contentType?: 'xml' | 'json';
+    route: string;
+    eventChannel?: false;
+    returnsJSON?: false;
+    timeout?: number;
+    docs?: Partial<{
+        description: string;
+        response: string;
+        errors: Array<typeof PikkuError>;
+        tags: string[];
+    }>;
+};
+/**
+ * Represents a http interaction within Pikku, including a request and response.
+ */
+export interface PikkuHTTP {
+    request?: PikkuHTTPRequest;
+    response?: PikkuHTTPResponse;
+}
+/**
+ * Represents request headers as either a record or a function to get headers by name.
+ */
+export type RequestHeaders = Record<string, string | string[] | undefined> | ((headerName: string) => string | string[] | undefined);
+/**
+ * Represents a query object for Pikku, where each key can be a string, a value, or an array of values.
+ */
+export type PikkuQuery<T = Record<string, string | undefined>> = Record<string, string | T | null | Array<T | null>>;
+/**
+ * Represents a core API route, which can have different configurations depending on whether it requires authentication and permissions.
+ *
+ * @template In - The input type.
+ * @template Out - The output type.
+ * @template R - The route string type.
+ * @template APIFunction - The API function type, defaults to `CoreAPIFunction`.
+ * @template APIFunctionSessionless - The sessionless API function type, defaults to `CoreAPIFunctionSessionless`.
+ * @template APIPermission - The permission function type, defaults to `CoreAPIPermission`.
+ */
+export type CoreHTTPFunctionRoute<In, Out, R extends string, APIFunction = CoreAPIFunction<In, Out>, APIFunctionSessionless = CoreAPIFunctionSessionless<In, Out>, APIPermission = CoreAPIPermission<In>, APIMiddleware = PikkuMiddleware> = (CoreHTTPFunction & {
+    route: R;
+    method: HTTPMethod;
+    func: APIFunction;
+    permissions?: CorePermissionGroup<APIPermission>;
+    auth?: true;
+    tags?: string[];
+    middleware?: APIMiddleware[];
+    sse?: undefined;
+}) | (CoreHTTPFunction & {
+    route: R;
+    method: HTTPMethod;
+    func: APIFunctionSessionless;
+    permissions?: undefined;
+    auth?: false;
+    tags?: string[];
+    middleware?: APIMiddleware[];
+    sse?: undefined;
+}) | (CoreHTTPFunction & {
+    route: R;
+    method: 'get';
+    func: APIFunction;
+    permissions?: CorePermissionGroup<APIPermission>;
+    auth?: true;
+    sse?: boolean;
+    tags?: string[];
+    middleware?: APIMiddleware[];
+}) | (CoreHTTPFunction & {
+    route: R;
+    method: 'get';
+    func: APIFunctionSessionless;
+    permissions?: undefined;
+    auth?: false;
+    sse?: boolean;
+    tags?: string[];
+    middleware?: APIMiddleware[];
+}) | (CoreHTTPFunction & {
+    route: R;
+    method: 'post';
+    func: APIFunction;
+    permissions?: CorePermissionGroup<APIPermission>;
+    auth?: true;
+    query?: Array<keyof In>;
+    tags?: string[];
+    middleware?: APIMiddleware[];
+    sse?: undefined;
+}) | (CoreHTTPFunction & {
+    route: R;
+    method: 'post';
+    func: APIFunctionSessionless;
+    permissions?: undefined;
+    auth?: false;
+    query?: Array<keyof In>;
+    tags?: string[];
+    middleware?: APIMiddleware[];
+    sse?: undefined;
+});
+/**
+ * Represents the input types for route metadata, including parameters, query, and body types.
+ */
+export type HTTPFunctionMetaInputTypes = {
+    params?: string;
+    query?: string;
+    body?: string;
+};
+/**
+ * Represents metadata for a set of routes, including route details, methods, input/output types, and documentation.
+ */
+export type HTTPRouteMeta = {
+    pikkuFuncName: string;
+    route: string;
+    method: HTTPMethod;
+    params?: string[];
+    query?: string[];
+    input: string | null;
+    output: string | null;
+    inputTypes?: HTTPFunctionMetaInputTypes;
+    docs?: APIDocs;
+    tags?: string[];
+    sse?: true;
+};
+export type HTTPRoutesMeta = Array<HTTPRouteMeta>;
+export type HTTPFunctionsMeta = Array<{
+    name: string;
+    inputs: string[] | null;
+    outputs: string[] | null;
+}>;
+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: ArrayBuffer | ArrayBufferView | Blob | string | FormData | URLSearchParams | ReadableStream): this;
+    json(data: unknown): this;
+    redirect(location: string, status?: number): this;
+    close?: () => void;
+    setMode?: (mode: 'stream') => void;
+}
+export {};

package/dist/http/http.types.js

@@ -0,0 +1 @@
+export {};

package/dist/http/index.d.ts

@@ -2,5 +2,5 @@ export * from './pikku-fetch-http-request.js';
 export * from './pikku-fetch-http-response.js';
 export * from './incomingmessage-to-request-convertor.js';
 export * from './log-http-routes.js';
-export { fetch, fetchData, addRoute } from './http-route-runner.js';
-export type * from './http-routes.types.js';
+export { fetch, fetchData, addHTTPRoute } from './http-runner.js';
+export type * from './http.types.js';

package/dist/http/index.js

@@ -2,4 +2,4 @@ export * from './pikku-fetch-http-request.js';
 export * from './pikku-fetch-http-response.js';
 export * from './incomingmessage-to-request-convertor.js';
 export * from './log-http-routes.js';
-export { fetch, fetchData, addRoute } from './http-route-runner.js';
+export { fetch, fetchData, addHTTPRoute } from './http-runner.js';

package/dist/http/log-http-routes.js

@@ -4,14 +4,16 @@ import { pikkuState } from '../pikku-state.js';
  * @param logger - A logger for logging information.
  */
 export const logRoutes = (logger) => {
-    const routes = pikkuState('http', 'routes');
-    if (routes.length === 0) {
+    const routesByType = pikkuState('http', 'routes');
+    if (routesByType.size === 0) {
         logger.info('No routes added');
         return;
     }
     let routesMessage = 'Routes loaded:';
-    for (const { method, route } of routes) {
-        routesMessage += `\n\t- ${method.toUpperCase()} -> ${route}`;
-    }
+    routesByType.forEach((routes) => {
+        routes.forEach((route) => {
+            routesMessage += `\n\t- ${route.method.toUpperCase()} -> ${route}`;
+        });
+    });
     logger.info(routesMessage);
 };

package/dist/http/pikku-fetch-http-request.d.ts

@@ -1,4 +1,4 @@
-import { HTTPMethod, PikkuHTTPRequest, PikkuQuery } from './http-routes.types.js';
+import { HTTPMethod, PikkuHTTPRequest, PikkuQuery } from './http.types.js';
 /**
  * Abstract class representing a pikku request.
  * @template In - The type of the request body.

package/dist/http/pikku-fetch-http-response.d.ts

@@ -1,7 +1,8 @@
-import { PikkuHTTPResponse } from './http-routes.types.js';
+import { PikkuHTTPResponse } from './http.types.js';
 import { SerializeOptions as CookieSerializeOptions } from 'cookie';
 export declare class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
     #private;
+    setMode(mode: 'stream'): void;
     status(code: number): this;
     cookie(name: string, value: string, flags: CookieSerializeOptions): this;
     header(name: string, value: string | string[]): this;
@@ -9,7 +10,8 @@ export declare class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
     json(data: unknown): this;
     text(content: string): this;
     html(content: string): this;
-    body(body: BodyInit): this;
     redirect(location: string, status?: number): this;
+    close(): this;
     toResponse(args?: Record<string, any>): Response;
+    private createStream;
 }