@pikku/core 0.6.13 → 0.6.14

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## 0.6
 
+## 0.6.14
+
+### Patch Changes
+
+- c1d8381: feat: adding filtering by tags to minimize produced payload
+- ee5c874: feat: moving towards using middleware for http and channels
+
 ## 0.6.13
 
 ### Patch Changes

package/dist/channel/channel-handler.d.ts

@@ -1,3 +1,3 @@
-import { CoreServices, CoreUserSession } from '../types/core.types.js';
+import { CoreServices } from '../types/core.types.js';
 import { CoreAPIChannel, PikkuChannelHandler } from './channel.types.js';
-export declare const processMessageHandlers: (services: CoreServices, channelConfig: CoreAPIChannel<any, any>, channelHandler: PikkuChannelHandler<CoreUserSession, unknown>) => (rawData: any) => Promise<unknown>;
+export declare const processMessageHandlers: (services: CoreServices, channelConfig: CoreAPIChannel<any, any>, channelHandler: PikkuChannelHandler) => (rawData: any) => Promise<unknown>;

package/dist/channel/channel-handler.js

@@ -17,20 +17,20 @@ const validateSchema = (logger, data, channelName, routingProperty, routerValue)
         }
     }
 };
-const validateAuth = (requiresSession, channelHandler, onMessage) => {
+const validateAuth = (requiresSession, userSession, onMessage) => {
     const auth = typeof onMessage === 'function'
         ? requiresSession
         : onMessage.auth === undefined
             ? requiresSession
             : onMessage.auth;
-    if (auth && !channelHandler.getChannel().userSession) {
+    if (auth && !userSession) {
         return false;
     }
     return true;
 };
-const validatePermissions = async (services, channelHandler, onMessage, data) => {
+const validatePermissions = async (services, userSession, onMessage, data) => {
     const permissions = typeof onMessage === 'function' ? {} : onMessage.permissions;
-    return await verifyPermissions(permissions, services, data, channelHandler.getChannel().userSession);
+    return await verifyPermissions(permissions, services, data, userSession);
 };
 const runFunction = async (services, channelHandler, onMessage, data) => {
     const func = typeof onMessage === 'function' ? onMessage : onMessage.func;

package/dist/channel/channel-runner.d.ts

@@ -1,4 +1,4 @@
-import { CoreUserSession } from '../types/core.types.js';
+import { UserSessionService } from '../services/user-session-service.js';
 import { CoreAPIChannel, ChannelsMeta, CoreAPIChannels, RunChannelOptions, RunChannelParams } from './channel.types.js';
 /**
  * Returns all the registered routes and associated metadata.
@@ -16,11 +16,12 @@ export declare const setChannelsMeta: (_channelsMeta: ChannelsMeta) => void;
 export declare const getMatchingChannelConfig: (request: string) => {
     matchedPath: import("path-to-regexp").MatchResult<Partial<Record<string, string | string[]>>>;
     params: Partial<Record<string, string | string[]>>;
-    channelConfig: CoreAPIChannel<any, string, import("./channel.types.js").CoreChannelConnection<any, unknown, import("../types/core.types.js").CoreServices, CoreUserSession>, import("./channel.types.js").CoreChannelDisconnection<any, import("../types/core.types.js").CoreServices, CoreUserSession>, import("./channel.types.js").CoreChannelMessage<unknown, unknown, unknown, import("../types/core.types.js").CoreServices, CoreUserSession>, import("./channel.types.js").CoreChannelMessage<unknown, unknown, unknown, import("../types/core.types.js").CoreServices, CoreUserSession>, import("../index.js").CoreAPIPermission<any>>;
+    channelConfig: CoreAPIChannel<any, string, import("./channel.types.js").CoreChannelConnection<any, unknown, import("../index.js").CoreServices>, import("./channel.types.js").CoreChannelDisconnection<any, import("../index.js").CoreServices>, import("./channel.types.js").CoreChannelMessage<unknown, unknown, unknown, import("../index.js").CoreServices>, import("./channel.types.js").CoreChannelMessage<unknown, unknown, unknown, import("../index.js").CoreServices>, import("../index.js").CoreAPIPermission<any>>;
     schemaName: string | null | undefined;
 } | null;
-export declare const openChannel: ({ route, singletonServices, skipUserSession, coerceToArray, http, }: Pick<CoreAPIChannel<unknown, string>, "route"> & Omit<RunChannelParams<unknown>, "response" | "request"> & RunChannelOptions) => Promise<{
-    userSession?: CoreUserSession;
+export declare const openChannel: ({ route, singletonServices, coerceToArray, http, userSessionService, }: Pick<CoreAPIChannel<unknown, string>, "route"> & Omit<RunChannelParams<unknown>, "response" | "request"> & {
+    userSessionService?: UserSessionService<any>;
+} & RunChannelOptions) => Promise<{
     openingData: unknown;
     channelConfig: CoreAPIChannel<unknown, any>;
 }>;

package/dist/channel/channel-runner.js

@@ -1,6 +1,5 @@
 import { NotFoundError } from '../errors/errors.js';
-import { loadUserSession } from '../http/http-route-runner.js';
-import { validateAndCoerce } from '../schema.js';
+import { coerceQueryStringToArray, validateSchema } from '../schema.js';
 import { match } from 'path-to-regexp';
 if (!globalThis.pikku?.channels) {
     globalThis.pikku = globalThis.pikku || {};
@@ -59,28 +58,23 @@ export const getMatchingChannelConfig = (request) => {
     }
     return null;
 };
-export const openChannel = async ({ route, singletonServices, skipUserSession = false, coerceToArray = false, http, }) => {
+export const openChannel = async ({ route, singletonServices, coerceToArray = false, http, userSessionService, }) => {
     const matchingChannel = getMatchingChannelConfig(route);
     if (!matchingChannel) {
         singletonServices.logger.info(`Channel not found: ${route}`);
         throw new NotFoundError(`Channel not found: ${route}`);
     }
-    const { matchedPath, params, channelConfig, schemaName } = matchingChannel;
+    const { params, channelConfig, schemaName } = matchingChannel;
     const requiresSession = channelConfig.auth !== false;
     http?.request?.setParams(params);
     singletonServices.logger.info(`Matched channel: ${channelConfig.name} | route: ${channelConfig.route} | auth: ${requiresSession.toString()}`);
-    const userSession = await loadUserSession(skipUserSession, 
-    // We may require a session, but we don't actually need it
-    // on connect since channels can authenticate later given
-    // how websocket sessions work (cookie or queryParam based)
-    false, http, matchedPath, channelConfig, singletonServices.logger, singletonServices.httpSessionService);
-    if (singletonServices.enforceChannelAccess) {
-        await singletonServices.enforceChannelAccess(matchingChannel.channelConfig, userSession);
-    }
     let openingData;
     if (http?.request) {
         openingData = await http.request.getData();
-        validateAndCoerce(singletonServices.logger, singletonServices.schemaService, schemaName, openingData, coerceToArray);
+        if (coerceToArray && schemaName) {
+            coerceQueryStringToArray(schemaName, openingData);
+        }
+        validateSchema(singletonServices.logger, singletonServices.schemaService, schemaName, openingData);
     }
-    return { userSession, openingData, channelConfig };
+    return { openingData, channelConfig };
 };

package/dist/channel/channel.types.d.ts

@@ -2,7 +2,7 @@ import { PikkuError } from '../errors/error-handler.js';
 import { HTTPFunctionMetaInputTypes, PikkuHTTP } from '../http/http-routes.types.js';
 import { PikkuHTTPAbstractRequest } from '../http/pikku-http-abstract-request.js';
 import { PikkuHTTPAbstractResponse } from '../http/pikku-http-abstract-response.js';
-import { APIDocs, CoreServices, CoreSingletonServices, CoreUserSession, CreateSessionServices } from '../types/core.types.js';
+import { APIDocs, CoreServices, CoreSingletonServices, CreateSessionServices, PikkuMiddleware } from '../types/core.types.js';
 import { CoreAPIPermission } from '../types/functions.types.js';
 import { PikkuRequest } from '../pikku-request.js';
 import { PikkuResponse } from '../pikku-response.js';
@@ -41,10 +41,11 @@ export interface ChannelMeta {
         outputs: string[] | null;
     }>>;
     docs?: APIDocs;
+    tags?: string[];
 }
 export type ChannelsMeta = ChannelMeta[];
-export type CoreChannelConnection<ChannelData, Out = unknown, Services extends CoreServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = (services: Services, channel: PikkuChannel<Session, ChannelData, Out>) => Promise<void>;
-export type CoreChannelDisconnection<ChannelData, Services extends CoreServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = (services: Services, channel: PikkuChannel<Session, ChannelData, never>) => Promise<void>;
+export type CoreChannelConnection<ChannelData, Out = unknown, Services extends CoreServices = CoreServices> = (services: Services, channel: PikkuChannel<ChannelData, Out>) => Promise<void>;
+export type CoreChannelDisconnection<ChannelData, Services extends CoreServices = CoreServices> = (services: Services, channel: PikkuChannel<ChannelData, never>) => Promise<void>;
 /**
  * Represents a core channel function that performs an operation using core services and a user session.
  *
@@ -52,7 +53,7 @@ export type CoreChannelDisconnection<ChannelData, Services extends CoreServices
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
-export type CoreChannelMessage<In, Out, ChannelData, Services extends CoreServices = CoreServices, Session extends CoreUserSession = CoreUserSession> = (services: Services, channel: PikkuChannel<Session, ChannelData, Out>, data: In) => Promise<void | Out>;
+export type CoreChannelMessage<In, Out, ChannelData, Services extends CoreServices = CoreServices> = (services: Services, channel: PikkuChannel<ChannelData, Out>, data: In) => Promise<void | Out>;
 export type CoreAPIChannelMessage<ChannelFunctionMessage = CoreChannelMessage<unknown, unknown, unknown>> = {
     func: ChannelFunctionMessage;
     route: string;
@@ -72,6 +73,7 @@ export type CoreAPIChannel<ChannelData, Channel extends string, ChannelFunctionC
         permissions?: Record<string, APIPermission[] | APIPermission>;
         auth?: boolean;
     }>>;
+    middleware?: PikkuMiddleware[];
     permissions?: Record<string, APIPermission[] | APIPermission>;
     auth?: boolean;
     docs?: Partial<{
@@ -80,27 +82,18 @@ export type CoreAPIChannel<ChannelData, Channel extends string, ChannelFunctionC
         errors: Array<typeof PikkuError>;
         tags: string[];
     }>;
+    tags?: string[];
 };
 export type CoreAPIChannels = CoreAPIChannel<any, string>[];
-export interface PikkuChannel<UserSession, OpeningData, Out> {
+export interface PikkuChannel<OpeningData, Out> {
     channelId: string;
-    userSession?: UserSession;
-    setUserSession: (userSession: UserSession) => Promise<void> | void;
     openingData: OpeningData;
     send: (data: Out, isBinary?: boolean) => Promise<void> | void;
     close: () => Promise<void> | void;
     state: 'initial' | 'open' | 'closed';
 }
-export interface PikkuChannelHandler<UserSession extends CoreUserSession = CoreUserSession, OpeningData = unknown, Out = unknown> {
-    setUserSession(session: UserSession): Promise<void> | void;
+export interface PikkuChannelHandler<OpeningData = unknown, Out = unknown> {
     send(message: Out, isBinary?: boolean): Promise<void> | void;
-    getChannel(): PikkuChannel<UserSession, OpeningData, Out>;
+    getChannel(): PikkuChannel<OpeningData, Out>;
 }
-export type PikkuChannelHandlerFactory<OpeningData = unknown, UserSession extends CoreUserSession = CoreUserSession, Out = unknown> = (channelId: string, channelName: string, openingData: OpeningData, userSession: UserSession | undefined) => PikkuChannelHandler<UserSession, OpeningData, Out>;
-/**
- * Enfore access to a channel.
- * @param route - The channel to verify access for.
- * @param session - The user session.
- * @returns A promise that resolves if access is granted.
- */
-export type enforceChannelAccess = (channel: CoreAPIChannel<unknown, any>, session?: CoreUserSession) => Promise<void> | void;
+export type PikkuChannelHandlerFactory<OpeningData = unknown, Out = unknown> = (channelId: string, channelName: string, openingData: OpeningData) => PikkuChannelHandler<OpeningData, Out>;

package/dist/channel/local/local-channel-handler.d.ts

@@ -1,6 +1,5 @@
-import { CoreUserSession } from '../../types/core.types.js';
 import { PikkuAbstractChannelHandler } from '../pikku-abstract-channel-handler.js';
-export declare class PikkuLocalChannelHandler<UserSession extends CoreUserSession = CoreUserSession, OpeningData = unknown, Out = unknown> extends PikkuAbstractChannelHandler<UserSession, OpeningData, Out> {
+export declare class PikkuLocalChannelHandler<OpeningData = unknown, Out = unknown> extends PikkuAbstractChannelHandler<OpeningData, Out> {
     private onMessageCallback?;
     private openCallBack?;
     private closeCallback?;
@@ -13,5 +12,4 @@ export declare class PikkuLocalChannelHandler<UserSession extends CoreUserSessio
     close(): void;
     registerOnSend(send: (message: Out) => void): void;
     send(message: Out, isBinary?: boolean): void;
-    setUserSession(userSession: UserSession): void;
 }

package/dist/channel/local/local-channel-handler.js

@@ -35,7 +35,4 @@ export class PikkuLocalChannelHandler extends PikkuAbstractChannelHandler {
         }
         return this.sendCallback?.(message, isBinary);
     }
-    setUserSession(userSession) {
-        this.getChannel().userSession = userSession;
-    }
 }

package/dist/channel/local/local-channel-runner.js

@@ -1,46 +1,62 @@
 import { openChannel } from '../channel-runner.js';
-import { createHTTPInteraction, handleError, } from '../../http/http-route-runner.js';
+import { createHTTPInteraction } from '../../http/http-route-runner.js';
 import { closeSessionServices } from '../../utils.js';
 import { processMessageHandlers } from '../channel-handler.js';
 import { PikkuLocalChannelHandler } from './local-channel-handler.js';
+import { handleError } from '../../handle-error.js';
+import { runMiddleware } from '../../middleware-runner.js';
+import { LocalUserSessionService } from '../../services/user-session-service.js';
 export const runLocalChannel = async ({ singletonServices, channelId, request, response, route, createSessionServices, skipUserSession = false, respondWith404 = true, coerceToArray = false, logWarningsForStatusCodes = [], bubbleErrors = false, }) => {
     let sessionServices;
+    let channelHandler;
+    const userSessionService = new LocalUserSessionService();
     const http = createHTTPInteraction(request, response);
-    try {
-        const { userSession, openingData, channelConfig } = await openChannel({
-            channelId,
-            createSessionServices,
-            respondWith404,
-            http,
-            route,
-            singletonServices,
-            skipUserSession,
-            coerceToArray,
-        });
-        const channelHandler = new PikkuLocalChannelHandler(channelId, channelConfig.name, userSession, openingData);
-        const channel = channelHandler.getChannel();
-        if (createSessionServices) {
-            sessionServices = await createSessionServices(singletonServices, { http }, userSession);
+    const main = async () => {
+        try {
+            const { openingData, channelConfig } = await openChannel({
+                channelId,
+                createSessionServices,
+                respondWith404,
+                http,
+                route,
+                singletonServices,
+                skipUserSession,
+                coerceToArray,
+            });
+            channelHandler = new PikkuLocalChannelHandler(channelId, channelConfig.name, openingData);
+            const channel = channelHandler.getChannel();
+            const userSession = await userSessionService.get();
+            if (createSessionServices) {
+                sessionServices = await createSessionServices(singletonServices, { http }, userSession);
+            }
+            const allServices = {
+                ...singletonServices,
+                ...sessionServices,
+                userSessionService,
+            };
+            channelHandler.registerOnOpen(() => {
+                channelConfig.onConnect?.(allServices, channel);
+            });
+            channelHandler.registerOnClose(async () => {
+                channelConfig.onDisconnect?.(allServices, channel);
+                if (sessionServices) {
+                    await closeSessionServices(singletonServices.logger, sessionServices);
+                }
+            });
+            channelHandler.registerOnMessage(processMessageHandlers(allServices, channelConfig, channelHandler));
+        }
+        catch (e) {
+            handleError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
         }
-        const allServices = { ...singletonServices, ...sessionServices };
-        channelHandler.registerOnOpen(() => {
-            channelConfig.onConnect?.(allServices, channel);
-        });
-        channelHandler.registerOnClose(async () => {
-            channelConfig.onDisconnect?.(allServices, channel);
+        finally {
             if (sessionServices) {
                 await closeSessionServices(singletonServices.logger, sessionServices);
             }
-        });
-        channelHandler.registerOnMessage(processMessageHandlers(allServices, channelConfig, channelHandler));
-        return channelHandler;
-    }
-    catch (e) {
-        handleError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
-    }
-    finally {
-        if (sessionServices) {
-            await closeSessionServices(singletonServices.logger, sessionServices);
         }
-    }
+    };
+    await runMiddleware({
+        ...singletonServices,
+        userSessionService,
+    }, { http }, route.middleware || [], main);
+    return channelHandler;
 };

package/dist/channel/pikku-abstract-channel-handler.d.ts

@@ -1,15 +1,12 @@
-import { CoreUserSession } from '../types/core.types.js';
 import { PikkuChannel, PikkuChannelHandler } from './channel.types.js';
-export declare abstract class PikkuAbstractChannelHandler<UserSession extends CoreUserSession = CoreUserSession, OpeningData = unknown, Out = unknown> implements PikkuChannelHandler<UserSession, OpeningData, Out> {
+export declare abstract class PikkuAbstractChannelHandler<OpeningData = unknown, Out = unknown> implements PikkuChannelHandler<OpeningData, Out> {
     channelId: string;
     channelName: string;
-    protected userSession: UserSession | undefined;
     protected openingData: OpeningData;
-    protected channel?: PikkuChannel<UserSession, OpeningData, Out>;
-    constructor(channelId: string, channelName: string, userSession: UserSession | undefined, openingData: OpeningData);
-    abstract setUserSession(userSession: UserSession): Promise<void> | void;
+    protected channel?: PikkuChannel<OpeningData, Out>;
+    constructor(channelId: string, channelName: string, openingData: OpeningData);
     abstract send(message: Out, isBinary?: boolean): Promise<void> | void;
-    getChannel(): PikkuChannel<UserSession, OpeningData, Out>;
+    getChannel(): PikkuChannel<OpeningData, Out>;
     open(): void;
     close(): Promise<void> | void;
 }

package/dist/channel/pikku-abstract-channel-handler.js

@@ -1,22 +1,18 @@
 export class PikkuAbstractChannelHandler {
     channelId;
     channelName;
-    userSession;
     openingData;
     channel;
-    constructor(channelId, channelName, userSession, openingData) {
+    constructor(channelId, channelName, openingData) {
         this.channelId = channelId;
         this.channelName = channelName;
-        this.userSession = userSession;
         this.openingData = openingData;
     }
     getChannel() {
         if (!this.channel) {
             this.channel = {
                 channelId: this.channelId,
-                userSession: this.userSession,
                 openingData: this.openingData,
-                setUserSession: this.setUserSession.bind(this),
                 send: this.send.bind(this),
                 close: this.close.bind(this),
                 state: 'initial',

package/dist/channel/serverless/serverless-channel-runner.js

@@ -1,14 +1,17 @@
 import { closeSessionServices } from '../../utils.js';
 import { processMessageHandlers } from '../channel-handler.js';
 import { getChannels, openChannel } from '../channel-runner.js';
-import { createHTTPInteraction, handleError, } from '../../http/http-route-runner.js';
-const getVariablesForChannel = ({ channelId, userSession, channelName, channelHandlerFactory, openingData, }) => {
+import { createHTTPInteraction } from '../../http/http-route-runner.js';
+import { handleError } from '../../handle-error.js';
+import { RemoteUserSessionService } from '../../services/user-session-service.js';
+import { runMiddleware } from '../../middleware-runner.js';
+const getVariablesForChannel = ({ channelId, channelName, channelHandlerFactory, openingData, }) => {
     const { channels } = getChannels();
     const channelConfig = channels.find((channelConfig) => channelConfig.name === channelName);
     if (!channelConfig) {
         throw new Error(`Channel not found: ${channelName}`);
     }
-    const channelHandler = channelHandlerFactory(channelId, channelConfig.name, openingData, userSession);
+    const channelHandler = channelHandlerFactory(channelId, channelConfig.name, openingData);
     return {
         channelConfig,
         channelHandler,
@@ -18,48 +21,53 @@ const getVariablesForChannel = ({ channelId, userSession, channelName, channelHa
 export const runChannelConnect = async ({ singletonServices, channelId, channelObject, request, response, route, createSessionServices, channelStore, channelHandlerFactory, coerceToArray = false, logWarningsForStatusCodes = [], respondWith404 = true, bubbleErrors = false, }) => {
     let sessionServices;
     const http = createHTTPInteraction(request, response);
-    try {
-        const { userSession, channelConfig, openingData } = await openChannel({
-            channelId,
-            createSessionServices,
-            http,
-            route,
-            singletonServices,
-            coerceToArray,
-        });
-        await channelStore.addChannel({
-            channelId,
-            channelName: channelConfig.name,
-            openingData,
-            channelObject,
-        });
-        const { channel } = getVariablesForChannel({
-            channelId,
-            userSession,
-            channelHandlerFactory,
-            channelName: channelConfig.name,
-        });
-        if (createSessionServices) {
-            sessionServices = await createSessionServices(singletonServices, { http }, userSession);
+    const userSessionService = new RemoteUserSessionService(channelStore, channelId);
+    const { channelConfig, openingData } = await openChannel({
+        channelId,
+        createSessionServices,
+        http,
+        route,
+        singletonServices,
+        coerceToArray,
+    });
+    const main = async () => {
+        try {
+            await channelStore.addChannel({
+                channelId,
+                channelName: channelConfig.name,
+                openingData,
+                channelObject,
+            });
+            const { channel } = getVariablesForChannel({
+                channelId,
+                channelHandlerFactory,
+                channelName: channelConfig.name,
+            });
+            if (createSessionServices) {
+                sessionServices = await createSessionServices(singletonServices, { http }, await userSessionService.get());
+            }
+            await channelConfig.onConnect?.({ ...singletonServices, ...sessionServices }, channel);
+            http?.response?.setStatus(101);
         }
-        await channelConfig.onConnect?.({ ...singletonServices, ...sessionServices }, channel);
-        http?.response?.setStatus(101);
-    }
-    catch (e) {
-        handleError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
-    }
-    finally {
-        if (sessionServices) {
-            await closeSessionServices(singletonServices.logger, sessionServices);
+        catch (e) {
+            handleError(e, http, channelId, singletonServices.logger, logWarningsForStatusCodes, respondWith404, bubbleErrors);
         }
-    }
+        finally {
+            if (sessionServices) {
+                await closeSessionServices(singletonServices.logger, sessionServices);
+            }
+        }
+    };
+    await runMiddleware({
+        ...singletonServices,
+        userSessionService,
+    }, { http }, channelConfig.middleware || [], main);
 };
 export const runChannelDisconnect = async ({ singletonServices, ...params }) => {
     let sessionServices;
     const { userSession, openingData, channelName } = await params.channelStore.getChannel(params.channelId);
     const { channel, channelConfig } = getVariablesForChannel({
         ...params,
-        userSession,
         openingData,
         channelName,
     });
@@ -77,7 +85,6 @@ export const runChannelMessage = async ({ singletonServices, ...params }, data)
     const { userSession, openingData, channelName } = await params.channelStore.getChannel(params.channelId);
     const { channelHandler, channelConfig } = getVariablesForChannel({
         ...params,
-        userSession,
         openingData,
         channelName,
     });

package/dist/handle-error.d.ts

@@ -0,0 +1,14 @@
+import { Logger } from './services/logger.js';
+import { PikkuHTTP } from './http/http-routes.types.js';
+/**
+ * Handle errors that occur during route processing
+ *
+ * @param {any} e - The error that occurred
+ * @param {PikkuHTTP | undefined} http - HTTP interaction object
+ * @param {string} trackerId - Unique ID for tracking this error
+ * @param {Logger} logger - Logger service
+ * @param {number[]} logWarningsForStatusCodes - HTTP status codes to log as warnings
+ * @param {boolean} respondWith404 - Whether to respond with 404 for NotFoundError
+ * @param {boolean} bubbleError - Whether to throw the error after handling
+ */
+export declare const handleError: (e: any, http: PikkuHTTP | undefined, trackerId: string, logger: Logger, logWarningsForStatusCodes: number[], respondWith404: boolean, bubbleError: boolean) => void;

package/dist/handle-error.js

@@ -0,0 +1,53 @@
+import { getErrorResponse } from './errors/error-handler.js';
+import { NotFoundError } from './errors/errors.js';
+/**
+ * Handle errors that occur during route processing
+ *
+ * @param {any} e - The error that occurred
+ * @param {PikkuHTTP | undefined} http - HTTP interaction object
+ * @param {string} trackerId - Unique ID for tracking this error
+ * @param {Logger} logger - Logger service
+ * @param {number[]} logWarningsForStatusCodes - HTTP status codes to log as warnings
+ * @param {boolean} respondWith404 - Whether to respond with 404 for NotFoundError
+ * @param {boolean} bubbleError - Whether to throw the error after handling
+ */
+export const handleError = (e, http, trackerId, logger, logWarningsForStatusCodes, respondWith404, bubbleError) => {
+    // Skip 404 handling if configured to do so
+    if (e instanceof NotFoundError && !respondWith404) {
+        return;
+    }
+    // Get appropriate error response
+    const errorResponse = getErrorResponse(e);
+    if (errorResponse != null) {
+        // Set status and response body
+        http?.response?.setStatus(errorResponse.status);
+        http?.response?.setJson({
+            message: errorResponse.message,
+            payload: e.payload,
+            traceId: trackerId,
+        });
+        // Log certain status codes as warnings
+        if (logWarningsForStatusCodes.includes(errorResponse.status)) {
+            logger.warn(`Warning id: ${trackerId}`);
+            logger.warn(e);
+        }
+    }
+    else {
+        // Handle unexpected errors
+        logger.warn(`Error id: ${trackerId}`);
+        logger.error(e);
+        http?.response?.setStatus(500);
+        http?.response?.setJson({ errorId: trackerId });
+    }
+    // Handle 404 errors specifically
+    if (e instanceof NotFoundError) {
+        http?.response?.end();
+    }
+    // Either bubble up or end the response
+    if (bubbleError) {
+        throw e;
+    }
+    else {
+        http?.response?.end();
+    }
+};

package/dist/http/http-route-runner.d.ts

@@ -1,30 +1,53 @@
 import { CoreHTTPFunctionRoute, HTTPRoutesMeta, RunRouteOptions, RunRouteParams, PikkuHTTP } from './http-routes.types.js';
-import { CoreUserSession } from '../types/core.types.js';
-import { PikkuHTTPAbstractRequest } from './pikku-http-abstract-request.js';
-import { Logger } from '../services/index.js';
-import { CoreAPIChannel } from '../channel/channel.types.js';
 import { PikkuRequest } from '../pikku-request.js';
 import { PikkuResponse } from '../pikku-response.js';
-import { HTTPSessionService } from './http-session-service.js';
-export declare const addRoute: <In, Out, Route extends string, APIFunction, APIFunctionSessionless, APIPermission>(route: CoreHTTPFunctionRoute<In, Out, Route, APIFunction, APIFunctionSessionless, APIPermission>) => void;
+/**
+ * Add middleware to a specific route or globally
+ *
+ * @param {APIMiddleware[] | string} routeOrMiddleware - Route pattern to match or middleware array
+ * @param {APIMiddleware} [middleware] - Middleware to add (required if first param is a string)
+ */
+export declare const addMiddleware: <APIMiddleware>(routeOrMiddleware: APIMiddleware[] | string, middleware?: APIMiddleware) => void;
+/**
+ * Add a route to the global routes registry
+ *
+ * @param {CoreHTTPFunctionRoute} route - Route configuration to add
+ */
+export declare const addRoute: <In, Out, Route extends string, APIFunction, APIFunctionSessionless, APIPermission, APIMiddleware>(route: CoreHTTPFunctionRoute<In, Out, Route, APIFunction, APIFunctionSessionless, APIPermission, APIMiddleware>) => void;
+/**
+ * Remove all routes from the global registry
+ */
 export declare const clearRoutes: () => void;
 /**
+ * Set the HTTP routes metadata
+ *
+ * @param {HTTPRoutesMeta} routeMeta - Metadata for routes
  * @ignore
  */
-export declare const setHTTPRoutesMeta: (_routeMeta: HTTPRoutesMeta) => void;
+export declare const setHTTPRoutesMeta: (routeMeta: HTTPRoutesMeta) => void;
 /**
- * Returns all the registered routes and associated metadata.
+ * Returns all the registered routes and associated metadata
+ *
+ * @returns {Object} Object containing routes and routesMeta
  * @internal
  */
 export declare const getRoutes: () => {
     routes: CoreHTTPFunctionRoute<any, any, any>[];
     routesMeta: HTTPRoutesMeta;
 };
-export declare const getUserSession: <UserSession extends CoreUserSession>(httpSessionService: HTTPSessionService<UserSession> | undefined, auth: boolean, request: PikkuHTTPAbstractRequest) => Promise<CoreUserSession | undefined>;
-export declare const loadUserSession: (skipUserSession: boolean, requiresSession: boolean, http: PikkuHTTP | undefined, matchedPath: any, route: CoreHTTPFunctionRoute<unknown, unknown, any> | CoreAPIChannel<unknown, any>, logger: Logger, httpSessionService: HTTPSessionService | undefined) => Promise<CoreUserSession | undefined>;
+/**
+ * Create an HTTP interaction object from request and response
+ *
+ * @param {PikkuRequest | undefined} request - The HTTP request object
+ * @param {PikkuResponse | undefined} response - The HTTP response object
+ * @returns {PikkuHTTP | undefined} HTTP interaction object or undefined
+ */
 export declare const createHTTPInteraction: (request: PikkuRequest | undefined, response: PikkuResponse | undefined) => PikkuHTTP | undefined;
-export declare const handleError: (e: any, http: PikkuHTTP | undefined, trackerId: string, logger: Logger, logWarningsForStatusCodes: number[], respondWith404: boolean, bubbleError: boolean) => void;
 /**
+ * Run an HTTP route with the given parameters
+ *
+ * @param {Object} options - Options for running the route
+ * @returns {Promise<Out | void>} Result of the route handler
  * @ignore
  */
 export declare const runHTTPRoute: <In, Out>({ singletonServices, request, response, createSessionServices, route: apiRoute, method: apiType, skipUserSession, respondWith404, logWarningsForStatusCodes, coerceToArray, bubbleErrors, }: Pick<CoreHTTPFunctionRoute<unknown, unknown, any>, "route" | "method"> & RunRouteOptions & RunRouteParams<In>) => Promise<Out | void>;