@pikku/core 0.6.9

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

@@ -0,0 +1,208 @@
+import { getErrorResponse } from '../errors/error-handler.js';
+import { verifyPermissions } from '../permissions.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, NotFoundError, NotImplementedError, } from '../errors/errors.js';
+import crypto from 'crypto';
+import { closeSessionServices } from '../utils.js';
+import { getSchema, validateAndCoerce } from '../schema.js';
+if (!globalThis.pikku?.httpRoutes) {
+    globalThis.pikku = globalThis.pikku || {};
+    globalThis.pikku.httpRoutes = [];
+    globalThis.pikku.httpRoutesMeta = [];
+}
+const httpRoutes = (data) => {
+    if (data) {
+        globalThis.pikku.httpRoutes = data;
+    }
+    return globalThis.pikku.httpRoutes;
+};
+const httpRoutesMeta = (data) => {
+    if (data) {
+        globalThis.pikku.httpRoutesMeta = data;
+    }
+    return globalThis.pikku.httpRoutesMeta;
+};
+export const addRoute = (route) => {
+    httpRoutes().push(route);
+};
+export const clearRoutes = () => {
+    httpRoutes([]);
+};
+/**
+ * @ignore
+ */
+export const setHTTPRoutesMeta = (_routeMeta) => {
+    httpRoutesMeta(_routeMeta);
+};
+/**
+ * Returns all the registered routes and associated metadata.
+ * @internal
+ */
+export const getRoutes = () => {
+    return {
+        routes: httpRoutes(),
+        routesMeta: httpRoutesMeta(),
+    };
+};
+const getMatchingRoute = (schemaService, requestType, requestPath) => {
+    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.
+        if (route.method !== requestType.toLowerCase()) {
+            continue;
+        }
+        const matchFunc = match(`/${route.route}`.replace(/^\/\//, '/'), {
+            decode: decodeURIComponent,
+        });
+        const matchedPath = matchFunc(requestPath.replace(/^\/\//, '/'));
+        if (matchedPath) {
+            // TODO: Cache this loop as a performance improvement
+            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 (httpSessionService, auth, request) => {
+    if (httpSessionService) {
+        return (await httpSessionService.getUserSession(auth, request));
+    }
+    else if (auth) {
+        throw new NotImplementedError('Session service not implemented');
+    }
+    return undefined;
+};
+export const loadUserSession = async (skipUserSession, requiresSession, http, matchedPath, route, logger, httpSessionService) => {
+    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) {
+            if (requiresSession) {
+                logger.info({
+                    action: 'Rejecting route (invalid session)',
+                    path: matchedPath,
+                });
+                throw e;
+            }
+        }
+    }
+    return undefined;
+};
+export const createHTTPInteraction = (request, response) => {
+    let http = undefined;
+    if (request instanceof PikkuHTTPAbstractRequest ||
+        response instanceof PikkuHTTPAbstractResponse) {
+        http = {};
+        if (request instanceof PikkuHTTPAbstractRequest) {
+            http.request = request;
+        }
+        if (response instanceof PikkuHTTPAbstractResponse) {
+            http.response = response;
+        }
+    }
+    return http;
+};
+export const handleError = (e, http, trackerId, logger, logWarningsForStatusCodes, respondWith404, bubbleError) => {
+    if (e instanceof NotFoundError && !respondWith404) {
+        return;
+    }
+    const errorResponse = getErrorResponse(e);
+    if (errorResponse != null) {
+        http?.response?.setStatus(errorResponse.status);
+        http?.response?.setJson({
+            message: errorResponse.message,
+            payload: e.payload,
+            traceId: trackerId,
+        });
+        if (logWarningsForStatusCodes.includes(errorResponse.status)) {
+            logger.warn(`Warning id: ${trackerId}`);
+            logger.warn(e);
+        }
+    }
+    else {
+        logger.warn(`Error id: ${trackerId}`);
+        logger.error(e);
+        http?.response?.setStatus(500);
+        http?.response?.setJson({ errorId: trackerId });
+    }
+    if (e instanceof NotFoundError) {
+        http?.response?.end();
+    }
+    if (bubbleError) {
+        throw e;
+    }
+};
+/**
+ * @ignore
+ */
+export const runHTTPRoute = async ({ singletonServices, request, response, createSessionServices, route: apiRoute, method: apiType, skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceToArray = false, bubbleErrors = false, }) => {
+    let sessionServices;
+    const trackerId = crypto.randomUUID().toString();
+    const http = createHTTPInteraction(request, response);
+    const matchedRoute = getMatchingRoute(singletonServices.schemaService, apiType, apiRoute);
+    try {
+        if (!matchedRoute) {
+            singletonServices.logger.info({
+                message: 'Route not found',
+                apiRoute,
+                apiType,
+            });
+            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, 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 = (await route.func(allServices, data, session));
+        if (route.returnsJSON === false) {
+            http?.response?.setResponse(result);
+        }
+        else {
+            http?.response?.setJson(result);
+        }
+        http?.response?.setStatus(200);
+        http?.response?.end();
+        return result;
+    }
+    catch (e) {
+        handleError(e, http, trackerId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
+    }
+    finally {
+        if (sessionServices) {
+            await closeSessionServices(singletonServices.logger, sessionServices);
+        }
+    }
+};

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

@@ -0,0 +1,127 @@
+import { EError } from '../errors/error-handler.js';
+import { APIDocs, CoreServices, CoreSingletonServices, CoreUserSession, CreateSessionServices } from '../types/core.types.js';
+import { CoreAPIFunction, 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}` ? 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[];
+    coerceToArray: boolean;
+    bubbleErrors: boolean;
+}>;
+export type RunRouteParams<In> = {
+    singletonServices: CoreSingletonServices;
+    request: PikkuRequest<In> | PikkuHTTPAbstractRequest<In>;
+    response?: PikkuResponse | PikkuHTTPAbstractResponse | undefined;
+    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 EError>;
+        tags: string[];
+    }>;
+};
+/**
+ * Represents a http interaction within Pikku, including a request and response.
+ */
+export interface PikkuHTTP {
+    request?: PikkuHTTPAbstractRequest;
+    response?: PikkuHTTPAbstractResponse;
+}
+/**
+ * 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>> = (CoreHTTPFunction & {
+    route: R;
+    method: HTTPMethod;
+    func: APIFunction;
+    permissions?: Record<string, APIPermission[] | APIPermission>;
+    auth?: true;
+}) | (CoreHTTPFunction & {
+    route: R;
+    method: HTTPMethod;
+    func: APIFunctionSessionless;
+    permissions?: undefined;
+    auth?: false;
+}) | (CoreHTTPFunction & {
+    route: R;
+    method: 'post';
+    func: APIFunction;
+    permissions?: Record<string, APIPermission[] | APIPermission>;
+    auth?: true;
+    query?: Array<keyof In>;
+}) | (CoreHTTPFunction & {
+    route: R;
+    method: 'post';
+    func: APIFunctionSessionless;
+    permissions?: undefined;
+    auth?: false;
+    query?: Array<keyof In>;
+});
+/**
+ * Represents an array of core API routes.
+ */
+export type CoreHTTPFunctionRoutes = Array<CoreHTTPFunctionRoute<any, any, string>>;
+/**
+ * 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 HTTPRoutesMeta = Array<{
+    route: string;
+    method: HTTPMethod;
+    params?: string[];
+    query?: string[];
+    input: string | null;
+    output: string | null;
+    inputTypes?: HTTPFunctionMetaInputTypes;
+    docs?: APIDocs;
+}>;
+/**
+ * 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 {};

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

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

package/dist/http/http-session-service.d.ts

@@ -0,0 +1,15 @@
+import { CoreUserSession } from '../types/core.types.js';
+import { PikkuHTTPAbstractRequest } from './pikku-http-abstract-request.js';
+/**
+ * Interface for handling user sessions.
+ * @template UserSession - The type of the user session.
+ */
+export interface HTTPSessionService<UserSession = CoreUserSession> {
+    /**
+     * Retrieves the user session.
+     * @param credentialsRequired - A flag indicating whether credentials are required.
+     * @param pikkuRequest - The request object.
+     * @returns A promise that resolves to the user session or undefined.
+     */
+    getUserSession: (credentialsRequired: boolean, pikkuRequest: PikkuHTTPAbstractRequest) => Promise<UserSession | undefined>;
+}

package/dist/http/http-session-service.js

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

package/dist/http/index.d.ts

@@ -0,0 +1,6 @@
+export * from './pikku-http-session-service.js';
+export * from './pikku-http-abstract-request.js';
+export * from './pikku-http-abstract-response.js';
+export * from './log-http-routes.js';
+export { runHTTPRoute, getRoutes, setHTTPRoutesMeta, addRoute, } from './http-route-runner.js';
+export type * from './http-routes.types.js';

package/dist/http/index.js

@@ -0,0 +1,5 @@
+export * from './pikku-http-session-service.js';
+export * from './pikku-http-abstract-request.js';
+export * from './pikku-http-abstract-response.js';
+export * from './log-http-routes.js';
+export { runHTTPRoute, getRoutes, setHTTPRoutesMeta, addRoute, } from './http-route-runner.js';

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

@@ -0,0 +1,6 @@
+import { Logger } from '../services/index.js';
+/**
+ * Logs all the loaded routes.
+ * @param logger - A logger for logging information.
+ */
+export declare const logRoutes: (logger: Logger) => void;

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

@@ -0,0 +1,17 @@
+import { getRoutes } from './http-route-runner.js';
+/**
+ * Logs all the loaded routes.
+ * @param logger - A logger for logging information.
+ */
+export const logRoutes = (logger) => {
+    const { routes } = getRoutes();
+    if (routes.length === 0) {
+        logger.info('No routes added');
+        return;
+    }
+    let routesMessage = 'Routes loaded:';
+    for (const { method, route } of routes) {
+        routesMessage += `\n\t- ${method.toUpperCase()} -> ${route}`;
+    }
+    logger.info(routesMessage);
+};

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

@@ -0,0 +1,57 @@
+import { PikkuRequest } from '../pikku-request.js';
+import { PikkuQuery } from './http-routes.types.js';
+/**
+ * Abstract class representing a pikku request.
+ * @template In - The type of the request body.
+ * @group RequestResponse
+ */
+export declare abstract class PikkuHTTPAbstractRequest<In = unknown> extends PikkuRequest<In> {
+    private params;
+    /**
+     * Retrieves the request body.
+     * @returns A promise that resolves to the request body.
+     */
+    abstract getBody(): Promise<In>;
+    /**
+     * Retrieves the raw request body as a Buffer.
+     * @returns A promise that resolves to the raw request body.
+     */
+    getRawBody(): Promise<Buffer>;
+    /**
+     * Retrieves the value of a specific header.
+     * @param headerName - The name of the header to retrieve.
+     * @returns The value of the header, or undefined if the header is not found.
+     */
+    abstract getHeader(headerName: string): string | undefined;
+    /**
+     * Retrieves the cookies from the request.
+     * @returns An object containing the cookies.
+     */
+    getCookies(): Partial<Record<string, string>>;
+    /**
+     * Retrieves the request parameters.
+     * @returns An object containing the request parameters.
+     */
+    getParams(): Partial<Record<string, string | string[]>>;
+    /**
+     * Sets the request parameters.
+     * @param params - An object containing the request parameters to set.
+     */
+    setParams(params: Record<string, string | string[] | undefined>): void;
+    /**
+     * Retrieves the query parameters from the request.
+     * @returns An object containing the query parameters.
+     */
+    getQuery(): PikkuQuery;
+    /**
+     * Retrieves the IP address of the client making the request.
+     * @returns The IP address of the client.
+     * @throws {Error} This method is not implemented and should be overridden by subclasses.
+     */
+    getIP(): string;
+    /**
+     * Retrieves the combined data from the request, including parameters, query, and body.
+     * @returns A promise that resolves to an object containing the combined data.
+     */
+    getData(): Promise<In>;
+}

package/dist/http/pikku-http-abstract-request.js

@@ -0,0 +1,69 @@
+import { parse as parseCookie } from 'cookie';
+import { PikkuRequest } from '../pikku-request.js';
+/**
+ * Abstract class representing a pikku request.
+ * @template In - The type of the request body.
+ * @group RequestResponse
+ */
+export class PikkuHTTPAbstractRequest extends PikkuRequest {
+    params = {};
+    /**
+     * Retrieves the raw request body as a Buffer.
+     * @returns A promise that resolves to the raw request body.
+     */
+    getRawBody() {
+        throw new Error('Method not implemented.');
+    }
+    /**
+     * Retrieves the cookies from the request.
+     * @returns An object containing the cookies.
+     */
+    getCookies() {
+        const cookieHeader = this.getHeader('cookie');
+        if (cookieHeader) {
+            return parseCookie(cookieHeader);
+        }
+        return {};
+    }
+    /**
+     * Retrieves the request parameters.
+     * @returns An object containing the request parameters.
+     */
+    getParams() {
+        return this.params;
+    }
+    /**
+     * Sets the request parameters.
+     * @param params - An object containing the request parameters to set.
+     */
+    setParams(params) {
+        this.params = params;
+    }
+    /**
+     * Retrieves the query parameters from the request.
+     * @returns An object containing the query parameters.
+     */
+    getQuery() {
+        return {};
+    }
+    /**
+     * Retrieves the IP address of the client making the request.
+     * @returns The IP address of the client.
+     * @throws {Error} This method is not implemented and should be overridden by subclasses.
+     */
+    getIP() {
+        throw new Error('Method not implemented.');
+    }
+    /**
+     * Retrieves the combined data from the request, including parameters, query, and body.
+     * @returns A promise that resolves to an object containing the combined data.
+     */
+    async getData() {
+        return {
+            ...this.getParams(),
+            ...this.getQuery(),
+            // TODO: If body isn't an object, we should insert it as the word...
+            ...(await this.getBody()),
+        };
+    }
+}

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

@@ -0,0 +1,58 @@
+import { SerializeOptions } from 'cookie';
+import { JSONValue } from '../types/core.types.js';
+import { PikkuResponse } from '../pikku-response.js';
+/**
+ * Abstract class representing a pikku response.
+ * @group RequestResponse
+ */
+export declare abstract class PikkuHTTPAbstractResponse extends PikkuResponse {
+    /**
+     * Sets the HTTP status code for the response.
+     * @param status - The HTTP status code to set.
+     */
+    abstract setStatus(status: number): void;
+    /**
+     * Sets the JSON body for the response.
+     * @param body - The JSON body to set.
+     */
+    abstract setJson(body: JSONValue): void;
+    /**
+     * Sets the response content.
+     * @param response - The response content, which can be a string or a Buffer.
+     */
+    abstract setResponse(response: string | Buffer): void;
+    /**
+     * Sets a header for the response.
+     * @param name - The name of the header.
+     * @param value - The value of the header, which can be a string, boolean, or an array of strings.
+     */
+    setHeader(name: string, value: string | boolean | string[]): void;
+    /**
+     * Sets multiple headers for the response.
+     * @param headers - An object containing header names and values.
+     */
+    setHeaders(headers: Record<string, string>): void;
+    /**
+     * Sets a cookie for the response.
+     * @param name - The name of the cookie.
+     * @param value - The value of the cookie.
+     * @param options - Options for cookie serialization.
+     */
+    setCookie(name: string, value: string, options: SerializeOptions): void;
+    /**
+     * Clears a cookie from the response.
+     * @param name - The name of the cookie to clear.
+     */
+    clearCookie(name: string): void;
+    /**
+     * Sets a redirect for the response.
+     * @param path - The path to redirect to.
+     * @param status - The HTTP status code for the redirect.
+     */
+    setRedirect(path: string, status: number): void;
+    /**
+     * Informs the response that it has ended, useful for when setting
+     * a status without a body or response.
+     */
+    end(): void;
+}

package/dist/http/pikku-http-abstract-response.js

@@ -0,0 +1,54 @@
+import { serialize } from 'cookie';
+import { PikkuResponse } from '../pikku-response.js';
+/**
+ * Abstract class representing a pikku response.
+ * @group RequestResponse
+ */
+export class PikkuHTTPAbstractResponse extends PikkuResponse {
+    /**
+     * Sets a header for the response.
+     * @param name - The name of the header.
+     * @param value - The value of the header, which can be a string, boolean, or an array of strings.
+     */
+    setHeader(name, value) {
+        throw new Error('Method not implemented.');
+    }
+    /**
+     * Sets multiple headers for the response.
+     * @param headers - An object containing header names and values.
+     */
+    setHeaders(headers) {
+        for (const [name, value] of Object.entries(headers)) {
+            this.setHeader(name, value);
+        }
+    }
+    /**
+     * Sets a cookie for the response.
+     * @param name - The name of the cookie.
+     * @param value - The value of the cookie.
+     * @param options - Options for cookie serialization.
+     */
+    setCookie(name, value, options) {
+        this.setHeader('set-cookie', serialize(name, value, options));
+    }
+    /**
+     * Clears a cookie from the response.
+     * @param name - The name of the cookie to clear.
+     */
+    clearCookie(name) {
+        this.setHeader('set-cookie', serialize(name, '', { expires: new Date(0) }));
+    }
+    /**
+     * Sets a redirect for the response.
+     * @param path - The path to redirect to.
+     * @param status - The HTTP status code for the redirect.
+     */
+    setRedirect(path, status) {
+        throw new Error('Method not implemented.');
+    }
+    /**
+     * Informs the response that it has ended, useful for when setting
+     * a status without a body or response.
+     */
+    end() { }
+}