@pikku/core 0.6.26 → 0.7.0

package/dist/http/http-route-runner.js

@@ -1,14 +1,13 @@
-import { verifyPermissions } from '../permissions.js';
 import { match } from 'path-to-regexp';
-import { ForbiddenError, MissingSessionError, NotFoundError, } from '../errors/errors.js';
-import { closeSessionServices } from '../utils.js';
-import { coerceTopLevelDataFromSchema, validateSchema } from '../schema.js';
+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 { getFunctionName, runPikkuFunc } from '../function/function-runner.js';
 /**
  * Registers middleware either globally or for a specific route.
  *
@@ -45,7 +44,7 @@ export const addMiddleware = (routeOrMiddleware, middleware) => {
  * @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.
  */
@@ -66,7 +65,6 @@ export const addRoute = (route) => {
 const getMatchingRoute = (requestType, requestPath) => {
     const routes = 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()) {
@@ -84,14 +82,12 @@ const getMatchingRoute = (requestType, requestPath) => {
                 .filter((m) => m.route === '*' || new RegExp(m.route).test(route.route))
                 .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;
             return {
                 matchedPath,
                 params: matchedPath.params,
                 route,
+                permissions: route.permissions,
                 middleware: [...globalMiddleware, ...(route.middleware || [])],
-                schemaName,
             };
         }
     }
@@ -141,8 +137,8 @@ export const createHTTPInteraction = (request, response) => {
  * @throws Throws errors like MissingSessionError or ForbiddenError on validation failures.
  */
 const executeRouteWithMiddleware = async (services, matchedRoute, http, options) => {
-    const { matchedPath, params, route, middleware, schemaName } = matchedRoute;
-    const { singletonServices, userSession, createSessionServices, skipUserSession, } = services;
+    const { matchedPath, params, route, middleware } = matchedRoute;
+    const { singletonServices, userSession, createSessionServices, skipUserSession, requestId, } = services;
     const requiresSession = route.auth !== false;
     let sessionServices;
     let result;
@@ -163,28 +159,54 @@ const executeRouteWithMiddleware = async (services, matchedRoute, http, options)
             });
             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 = 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 data = await http?.request?.data();
-        // 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 (options.coerceDataFromSchema && schemaName) {
-            coerceTopLevelDataFromSchema(schemaName, data);
-        }
-        // Execute permission checks
-        const permissioned = await verifyPermissions(route.permissions, allServices, data, session);
-        if (permissioned === false) {
-            throw new ForbiddenError('Permission denied');
-        }
-        // Invoke the actual route handler function
-        result = await route.func(allServices, data, session);
+        const funName = getFunctionName(route.func);
+        const result = await runPikkuFunc(funName, {
+            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);
@@ -256,7 +278,10 @@ export const pikkuFetch = async (request, params) => {
  * @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, }) => {
+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;
@@ -283,13 +308,13 @@ export const fetchData = async (request, response, { singletonServices, createSe
             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, '111', // TODO: context.get('trackingId'),
-        singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
+        handleError(e, http, requestId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
     }
     finally {
         // Clean up any session-specific services created during processing

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

@@ -1,7 +1,7 @@
-import { SerializeOptions } from 'cookie';
-import { PikkuError } from '../errors/error-handler.js';
-import { APIDocs, CoreServices, CoreSingletonServices, CoreUserSession, CreateSessionServices, PikkuMiddleware } from '../types/core.types.js';
-import { CoreAPIFunction, CoreAPIFunctionSessionless, CoreAPIPermission } from '../types/functions.types.js';
+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<{
@@ -10,6 +10,7 @@ export type RunRouteOptions = Partial<{
     logWarningsForStatusCodes: number[];
     coerceDataFromSchema: boolean;
     bubbleErrors: boolean;
+    generateRequestId: () => string;
 }>;
 export type RunRouteParams = {
     singletonServices: CoreSingletonServices;
@@ -64,10 +65,11 @@ export type CoreHTTPFunctionRoute<In, Out, R extends string, APIFunction = CoreA
     route: R;
     method: HTTPMethod;
     func: APIFunction;
-    permissions?: Record<string, APIPermission[] | APIPermission>;
+    permissions?: CorePermissionGroup<APIPermission>;
     auth?: true;
     tags?: string[];
     middleware?: APIMiddleware[];
+    sse?: undefined;
 }) | (CoreHTTPFunction & {
     route: R;
     method: HTTPMethod;
@@ -76,15 +78,35 @@ export type CoreHTTPFunctionRoute<In, Out, R extends string, APIFunction = CoreA
     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?: Record<string, APIPermission[] | APIPermission>;
+    permissions?: CorePermissionGroup<APIPermission>;
     auth?: true;
     query?: Array<keyof In>;
     tags?: string[];
     middleware?: APIMiddleware[];
+    sse?: undefined;
 }) | (CoreHTTPFunction & {
     route: R;
     method: 'post';
@@ -94,6 +116,7 @@ export type CoreHTTPFunctionRoute<In, Out, R extends string, APIFunction = CoreA
     query?: Array<keyof In>;
     tags?: string[];
     middleware?: APIMiddleware[];
+    sse?: undefined;
 });
 /**
  * Represents an array of core API routes.
@@ -120,6 +143,12 @@ export type HTTPRoutesMeta = Array<{
     inputTypes?: HTTPFunctionMetaInputTypes;
     docs?: APIDocs;
     tags?: string[];
+    sse?: true;
+}>;
+export type HTTPFunctionsMeta = Array<{
+    name: string;
+    inputs: string[] | null;
+    outputs: string[] | null;
 }>;
 export type HTTPRouteMiddleware = {
     route: string;
@@ -141,8 +170,10 @@ 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;
+    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-runner.d.ts

@@ -0,0 +1,90 @@
+import { CoreHTTPFunctionRoute, RunRouteOptions, RunRouteParams, PikkuHTTP, PikkuHTTPRequest, PikkuHTTPResponse } from './http.types.js';
+import { PikkuMiddleware } from '../types/core.types.js';
+import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.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 declare const addMiddleware: <APIMiddleware extends PikkuMiddleware>(routeOrMiddleware: APIMiddleware[] | string, middleware?: APIMiddleware[]) => void;
+/**
+ * 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 declare const addHTTPRoute: <In, Out, Route extends string, APIFunction, APIFunctionSessionless, APIPermissionGroup, APIMiddleware>(httpRoute: CoreHTTPFunctionRoute<In, Out, Route, APIFunction, APIFunctionSessionless, APIPermissionGroup, APIMiddleware>) => void;
+/**
+ * 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 declare const createHTTPInteraction: (request: PikkuHTTPRequest | undefined, response: PikkuHTTPResponse | undefined) => PikkuHTTP | undefined;
+/**
+ * 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 declare const fetch: <In, Out>(request: Request, params: RunRouteOptions & RunRouteParams) => Promise<Response>;
+/**
+ * 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 declare const pikkuFetch: <In, Out>(request: Request | PikkuHTTPRequest, params: RunRouteOptions & RunRouteParams) => Promise<PikkuFetchHTTPResponse>;
+/**
+ * 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 declare const fetchData: <In, Out>(request: Request | PikkuHTTPRequest, response: PikkuHTTPResponse, { singletonServices, createSessionServices, skipUserSession, respondWith404, logWarningsForStatusCodes, coerceDataFromSchema, bubbleErrors, generateRequestId, }: RunRouteOptions & RunRouteParams) => Promise<Out | void>;