@pikku/core 0.12.72 → 0.12.74

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

@@ -2,35 +2,6 @@ import type { CoreHTTPFunctionWiring, RunHTTPWiringOptions, PikkuHTTP, PikkuHTTP
 import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
 import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../types/core.types.js';
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
-/**
- * Registers HTTP middleware for a specific route pattern.
- *
- * This function registers middleware at runtime that will be applied to
- * HTTP routes matching the specified pattern.
- *
- * For tree-shaking benefits, wrap in a factory function:
- * `export const x = () => addHTTPMiddleware('pattern', [...])`
- *
- * @template PikkuMiddleware The middleware type.
- * @param {string} pattern - Route pattern (e.g., '*' for all routes, '/api/*' for specific routes).
- * @param {CorePikkuMiddlewareGroup} middleware - Array of middleware for this route pattern.
- *
- * @returns {CorePikkuMiddlewareGroup} The middleware array (for chaining/wrapping).
- *
- * @example
- * ```typescript
- * // Recommended: tree-shakeable
- * export const httpGlobal = () => addHTTPMiddleware('*', [
- *   corsMiddleware,
- *   loggingMiddleware
- * ])
- *
- * // Also works: no tree-shaking
- * export const apiMiddleware = addHTTPMiddleware('/api/*', [
- *   authMiddleware
- * ])
- * ```
- */
 export declare const addHTTPMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(pattern: string, middleware: CorePikkuMiddlewareGroup, packageName?: string | null) => CorePikkuMiddlewareGroup;
 /**
  * @deprecated HTTP-route-level permissions were removed in #972 — permissions
@@ -42,78 +13,8 @@ export declare const addHTTPMiddleware: <PikkuMiddleware extends CorePikkuMiddle
  * HTTP-route permissions.
  */
 export declare const addHTTPPermission: (_pattern: string, _permissions: Record<string, CorePikkuPermission | CorePikkuPermission[]> | CorePikkuPermission[]) => never;
-/**
- * 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 PikkuFunction Type for the route handler function.
- * @template PikkuFunctionSessionless Type for a sessionless handler.
- * @template PikkuPermissionGroup Type representing required permissions.
- * @template PikkuMiddleware Middleware type to be used with the route.
- * @param {CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>} httpWiring - The HTTP wiring configuration object.
- */
 export declare const wireHTTP: <In, Out, Route extends string, PikkuFunction extends CorePikkuFunction<In, Out> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out> = CorePikkuFunctionSessionless<In, Out>, PikkuPermissionGroup extends CorePikkuPermission<In> = CorePikkuPermission<In>, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware>(httpWiring: CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermissionGroup, PikkuMiddleware>) => void;
-/**
- * Combines the request and response objects into a single HTTP wire 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 wire object or undefined if none provided.
- */
 export declare const createHTTPWire: (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 {RunHTTPWiringOptions} 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?: RunHTTPWiringOptions) => 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 {RunHTTPWiringOptions} 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?: RunHTTPWiringOptions) => 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 wire 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 wire 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 {RunHTTPWiringOptions} 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, { skipUserSession, respondWith404, logWarningsForStatusCodes, coerceDataFromSchema, bubbleErrors, exposeErrors, generateRequestId, traceId: externalTraceId, maxBodySize, }?: RunHTTPWiringOptions) => Promise<Out | void>;

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

@@ -1,5 +1,5 @@
 import { NotFoundError } from '../../errors/errors.js';
-import { closeWireServices, createWeakUID, isSerializable, } from '../../utils.js';
+import { createWeakUID, isSerializable } from '../../utils.js';
 import { getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
 import { PikkuSessionService } from '../../services/user-session-service.js';
 import { getErrorResponse } from '../../errors/error-handler.js';
@@ -8,14 +8,12 @@ import { isProduction } from '../../env.js';
 import { pikkuState } from '../../pikku-state.js';
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js';
+import { unsupportedChannelRemote } from '../channel/channel-rpc.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { applyWebResponse } from './web-request.js';
 import { httpRouter } from './routers/http-router.js';
 import { validateSchema } from '../../schema.js';
 import { runMiddleware } from '../../middleware-runner.js';
-/**
- * Extract headers from a PikkuHTTPRequest based on the schema keys
- */
 function extractHeadersFromRequest(request, headerKeys) {
     const headers = {};
     for (const headerName of headerKeys) {
@@ -26,35 +24,6 @@ function extractHeadersFromRequest(request, headerKeys) {
     }
     return headers;
 }
-/**
- * Registers HTTP middleware for a specific route pattern.
- *
- * This function registers middleware at runtime that will be applied to
- * HTTP routes matching the specified pattern.
- *
- * For tree-shaking benefits, wrap in a factory function:
- * `export const x = () => addHTTPMiddleware('pattern', [...])`
- *
- * @template PikkuMiddleware The middleware type.
- * @param {string} pattern - Route pattern (e.g., '*' for all routes, '/api/*' for specific routes).
- * @param {CorePikkuMiddlewareGroup} middleware - Array of middleware for this route pattern.
- *
- * @returns {CorePikkuMiddlewareGroup} The middleware array (for chaining/wrapping).
- *
- * @example
- * ```typescript
- * // Recommended: tree-shakeable
- * export const httpGlobal = () => addHTTPMiddleware('*', [
- *   corsMiddleware,
- *   loggingMiddleware
- * ])
- *
- * // Also works: no tree-shaking
- * export const apiMiddleware = addHTTPMiddleware('/api/*', [
- *   authMiddleware
- * ])
- * ```
- */
 export const addHTTPMiddleware = (pattern, middleware, packageName = null) => {
     const httpGroups = pikkuState(packageName, 'middleware', 'httpGroup');
     const existing = httpGroups[pattern];
@@ -75,29 +44,10 @@ export const addHTTPMiddleware = (pattern, middleware, packageName = null) => {
 export const addHTTPPermission = (_pattern, _permissions) => {
     throw new Error('addHTTPPermission was removed in #972 — HTTP-route-level permissions no longer exist. Declare permissions on the function definition instead: pikkuFunc({ permissions }).');
 };
-/**
- * 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 PikkuFunction Type for the route handler function.
- * @template PikkuFunctionSessionless Type for a sessionless handler.
- * @template PikkuPermissionGroup Type representing required permissions.
- * @template PikkuMiddleware Middleware type to be used with the route.
- * @param {CoreHTTPFunctionWiring<In, Out, Route, PikkuFunction, PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>} httpWiring - The HTTP wiring configuration object.
- */
 export const wireHTTP = (httpWiring) => {
     const httpMeta = pikkuState(null, 'http', 'meta');
     const routeMeta = httpMeta[httpWiring.method][httpWiring.route];
     if (!routeMeta) {
-        // In deploy units with filtered metadata, wiring files may include
-        // routes for functions not in this unit. This happens when multiple
-        // wirings share a file — split them into separate files for better
-        // tree-shaking.
         console.warn(`[pikku] Skipping HTTP route '${httpWiring.method.toUpperCase()} ${httpWiring.route}' — metadata not found. Consider moving this wiring to its own file.`);
         return;
     }
@@ -112,17 +62,6 @@ export const wireHTTP = (httpWiring) => {
         .get(httpWiring.method)
         ?.set(httpWiring.route, httpWiring);
 };
-/**
- * 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 matchedPath = httpRouter.match(requestType.toLowerCase(), requestPath);
     if (matchedPath) {
@@ -138,16 +77,6 @@ const getMatchingRoute = (requestType, requestPath) => {
         };
     }
 };
-/**
- * Combines the request and response objects into a single HTTP wire 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 wire object or undefined if none provided.
- */
 export const createHTTPWire = (request, response) => {
     let http = undefined;
     if (request || response) {
@@ -161,43 +90,19 @@ export const createHTTPWire = (request, response) => {
     }
     return http;
 };
-/**
- * Validates the input data and executes the route handler
- *
- * This function 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, and optional schema.
- * @param {PikkuHTTP | undefined} http - The HTTP wire 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 wire services (if any).
- * @throws Throws errors like MissingSessionError or ForbiddenError on validation failures.
- */
 const executeRoute = async (services, matchedRoute, http, options) => {
     const { params, route, meta } = matchedRoute;
     const { singletonServices, createWireServices, skipUserSession, requestId } = services;
     const userSession = new PikkuSessionService(singletonServices.sessionStore);
-    // Attach URL parameters to the request object
     http?.request?.setParams(params);
-    // Validate request headers if schema is defined
     if (meta.headersSchemaName && http.request && singletonServices.schema) {
         const headerKeys = singletonServices.schema.getSchemaKeys(meta.headersSchemaName);
         const rawHeaders = extractHeadersFromRequest(http.request, headerKeys);
         await validateSchema(singletonServices.logger, singletonServices.schema, meta.headersSchemaName, rawHeaders);
     }
     const requiresSession = route.auth !== false;
-    let wireServices;
     let result;
     singletonServices.logger.info(`Matched route: ${route.route} | method: ${route.method.toUpperCase()} | auth: ${requiresSession.toString()}`);
-    // Ensure session is available when required
     if (skipUserSession && requiresSession) {
         throw new Error("Can't skip trying to get user session if auth is required");
     }
@@ -243,10 +148,10 @@ const executeRoute = async (services, matchedRoute, http, options) => {
             clearState: () => {
                 sseState = undefined;
             },
+            // SSE only flows server to client — the client has no way to answer on
+            // this channel, so a remote call could never be replied to.
+            remote: unsupportedChannelRemote,
         };
-        // Register the SSE channel with the eventHub (if present) so that
-        // eventHub.publish() can deliver messages to SSE subscribers.
-        // The channel handler wraps the SSE channel to match PikkuChannelHandler.
         if (singletonServices.eventHub?.onChannelOpened) {
             const channelRef = channel;
             const channelHandler = {
@@ -304,12 +209,11 @@ const executeRoute = async (services, matchedRoute, http, options) => {
             }
             catch { }
             channel?.close();
-            return wireServices ? { result, wireServices } : { result };
+            return { result };
         }
         throw e;
     }
     if (matchedRoute.route.sse) {
-        // Flush headers after middleware has run so CORS/auth headers are included
         http?.response?.flushHeaders?.();
     }
     else {
@@ -327,75 +231,25 @@ const executeRoute = async (services, matchedRoute, http, options) => {
             http?.response?.json(result);
         }
     }
-    return wireServices ? { result, wireServices } : { result };
+    return { 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 {RunHTTPWiringOptions} 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 {RunHTTPWiringOptions} 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 wire 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 wire 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 {RunHTTPWiringOptions} 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, { skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceDataFromSchema = true, bubbleErrors = false, 
-// Surface the error message + stack on unexpected 500s unless in production.
-exposeErrors = !isProduction(), generateRequestId, traceId: externalTraceId, maxBodySize, } = {}) => {
+export const fetchData = async (request, response, { skipUserSession = false, respondWith404 = true, logWarningsForStatusCodes = [], coerceDataFromSchema = true, bubbleErrors = false, exposeErrors = !isProduction(), generateRequestId, traceId: externalTraceId, maxBodySize, } = {}) => {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
-    let wireServices;
     let result;
-    // Combine the request and response into one wire object
     const pikkuRequest = request instanceof Request
         ? new PikkuFetchHTTPRequest(request, { maxBodySize })
         : request;
-    // Resolve traceId: external (e.g. CF-Ray) > x-request-id header > generated
     let requestId = externalTraceId ?? null;
     if (!requestId) {
         try {
@@ -404,13 +258,10 @@ exposeErrors = !isProduction(), generateRequestId, traceId: externalTraceId, max
         catch { }
     }
     requestId = requestId || generateRequestId?.() || createWeakUID();
-    // Scoped logger for HTTP runner internal logging (error handling, route matching)
-    // Functions/middleware receive singletonServices.logger directly for compatibility
     const scopedLogger = singletonServices.logger.scope?.(requestId) ?? singletonServices.logger;
     const http = createHTTPWire(pikkuRequest, 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 (!matchedRoute) {
@@ -431,9 +282,8 @@ exposeErrors = !isProduction(), generateRequestId, traceId: externalTraceId, max
             });
             throw new NotFoundError();
         }
-        // Execute the matched route along with its middleware and session management
         ;
-        ({ result, wireServices } = await executeRoute({
+        ({ result } = await executeRoute({
             singletonServices,
             createWireServices,
             skipUserSession,
@@ -444,10 +294,4 @@ exposeErrors = !isProduction(), generateRequestId, traceId: externalTraceId, max
     catch (e) {
         handleHTTPError(e, http, requestId, scopedLogger, logWarningsForStatusCodes, respondWith404, bubbleErrors, exposeErrors);
     }
-    finally {
-        // Clean up any session-specific services created during processing
-        if (wireServices) {
-            await closeWireServices(singletonServices.logger, wireServices);
-        }
-    }
 };

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

@@ -22,57 +22,25 @@ export type RunHTTPWiringOptions = Partial<{
     /** Maximum request body size in bytes, applied when pikku wraps a fetch `Request`. */
     maxBodySize: number;
 }>;
-/**
- * Represents the HTTP methods supported for API HTTP wirings.
- */
 export type HTTPMethod = 'post' | 'get' | 'delete' | 'patch' | 'head' | 'put' | 'options';
-/**
- * Header schema type for request header validation.
- * Uses Standard Schema interface - works with Zod, Valibot, ArkType, Effect Schema, etc.
- */
 export type HTTPHeadersSchema = StandardSchemaV1<Record<string, string | string[] | undefined>>;
-/**
- * Common HTTP route configuration shared between wireHTTP and wireHTTPRoutes
- */
 export type HTTPRouteBaseConfig = {
     contentType?: 'xml' | 'json';
     timeout?: number;
     tags?: string[];
     headers?: HTTPHeadersSchema;
 };
-/**
- * Represents an API HTTP wiring without a function, including metadata such as content type, route, and timeout settings.
- */
 export type CoreHTTPFunction = HTTPRouteBaseConfig & {
     route: string;
     eventChannel?: false;
     returnsJSON?: false;
 };
-/**
- * Represents a http wire within Pikku, including a request and response.
- */
 export interface PikkuHTTP<In = unknown> {
     request?: PikkuHTTPRequest<In>;
     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 HTTP wiring, 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 PikkuFunction - The API function type, defaults to `CorePikkuFunction`.
- * @template PikkuFunctionSessionless - The sessionless API function type, defaults to `CorePikkuFunctionSessionless`.
- * @template PikkuPermission - The permission function type, defaults to `CorePikkuPermission`.
- */
 export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any> = CorePikkuFunctionSessionless<In, Out>, PikkuPermission extends CorePikkuPermission<In, any, any> = CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = (CoreHTTPFunction & {
     route: R;
     method: HTTPMethod;
@@ -118,20 +86,25 @@ export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction exte
     query?: Array<keyof In>;
     sse?: undefined;
 });
-/**
- * Represents the input types for HTTP wiring metadata, including parameters, query, and body types.
- */
 export type HTTPFunctionMetaInputTypes = {
     params?: string;
     query?: string;
     body?: string;
 };
-/**
- * Represents metadata for a set of HTTP wirings, including HTTP wiring details, methods, input/output types, and documentation.
- */
 export type HTTPWiringMeta = CommonWireMeta & {
     route: string;
     method: HTTPMethod;
+    /** The route's own `auth`, or the group's if the route did not set one. */
+    auth?: boolean;
+    /**
+     * Whether reaching this route requires a session, resolved at codegen time
+     * across every layer that can demand one: the function's `sessionless`, its
+     * own `auth`, this route's `auth`, and the auth flag of the addon the
+     * function belongs to. Answering "which routes are open?" used to mean
+     * joining four separate places and knowing which of them wins; getting that
+     * join wrong reads an open route as a closed one.
+     */
+    requiresSession?: boolean;
     refTarget?: string;
     params?: string[];
     query?: string[];
@@ -170,15 +143,14 @@ export interface PikkuHTTPResponse<Out = unknown> {
     header(name: string, value: string | string[]): this;
     arrayBuffer(data: ArrayBuffer | ArrayBufferView | Blob | string | FormData | URLSearchParams | ReadableStream): this;
     json(data: Out): this;
-    send?(data: string | ArrayBuffer | Buffer): this;
+    /** `ArrayBufferView` covers `Buffer` and `Uint8Array`, which is how a body
+     *  that is not text reaches here without being decoded on the way. */
+    send?(data: string | ArrayBuffer | ArrayBufferView): this;
     redirect(location: string, status?: number): this;
     close?: () => void;
     setMode?: (mode: 'stream') => void;
     flushHeaders?: () => void;
 }
-/**
- * Single route configuration - supports all wireHTTP options
- */
 export type HTTPRouteConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any> = CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = HTTPRouteBaseConfig & {
     method: HTTPMethod;
     route: string;
@@ -187,31 +159,18 @@ export type HTTPRouteConfig<PikkuFunction extends CorePikkuFunction<any, any, an
     middleware?: PikkuMiddleware[];
     sse?: boolean;
 };
-/**
- * Group-level configuration applied to all routes
- */
 export type HTTPRoutesGroupConfig<PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = {
     basePath?: string;
     tags?: string[];
     auth?: boolean;
     middleware?: PikkuMiddleware[];
 };
-/**
- * Nested route map - allows hierarchical organization
- * Can contain individual routes, nested maps, or contracts with config
- */
 export type HTTPRouteMap = {
     [key: string]: HTTPRouteConfig | HTTPRouteMap | HTTPRouteContract;
 };
-/**
- * A route contract with optional group config (returned by defineRoutes)
- */
 export type HTTPRouteContract<T extends HTTPRouteMap = HTTPRouteMap> = HTTPRoutesGroupConfig & {
     routes: T;
 };
-/**
- * Full configuration for wireHTTPRoutes
- */
 export type WireHTTPRoutesConfig = HTTPRoutesGroupConfig & {
     routes: HTTPRouteMap | HTTPRouteConfig[];
 };

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

@@ -1,6 +1,2 @@
 import type { 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/wirings/http/log-http-routes.js

@@ -1,8 +1,4 @@
 import { pikkuState } from '../../pikku-state.js';
-/**
- * Logs all the loaded routes.
- * @param logger - A logger for logging information.
- */
 export const logRoutes = (logger) => {
     const routesByType = pikkuState(null, 'http', 'routes');
     if (routesByType.size === 0) {

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

@@ -1,17 +1,10 @@
 import type { HTTPMethod, PikkuHTTPRequest, PikkuQuery } from './http.types.js';
-/**
- * The largest request body read into memory when no limit is configured. Ample
- * for JSON APIs and typical uploads while keeping a single request's memory
- * footprint bounded.
- */
 export declare const DEFAULT_MAX_BODY_SIZE: number;
 export type PikkuFetchHTTPRequestOptions = Partial<{
     /** Maximum request body size in bytes. Defaults to {@link DEFAULT_MAX_BODY_SIZE}. */
     maxBodySize: number;
 }>;
 /**
- * Abstract class representing a pikku request.
- * @template In - The type of the request body.
  * @group RequestResponse
  */
 export declare class PikkuFetchHTTPRequest<In = unknown> implements PikkuHTTPRequest<In> {
@@ -20,47 +13,14 @@ export declare class PikkuFetchHTTPRequest<In = unknown> implements PikkuHTTPReq
     constructor(request: Request, { maxBodySize }?: PikkuFetchHTTPRequestOptions);
     method(): HTTPMethod;
     path(): string;
-    /**
-     * Retrieves the request body.
-     * @returns A promise that resolves to the request body.
-     */
     json(): Promise<In>;
-    /**
-     * Retrieves the raw request body as a Buffer.
-     * @returns A promise that resolves to the raw request body.
-     */
     arrayBuffer(): Promise<ArrayBuffer>;
     headers(): Record<string, string>;
-    /**
-     * 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.
-     */
     header(headerName: string): string | null;
-    /**
-     * Retrieves the cookies from the request.
-     * @returns An object containing the cookies.
-     */
     cookie(cookieName: string): string | null;
-    /**
-     * Retrieves the request parameters.
-     * @returns An object containing the request parameters.
-     */
     params(): 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.
-     */
     query(): PikkuQuery;
-    /**
-     * Retrieves the combined data from the request, including parameters, query, and body.
-     * @returns A promise that resolves to an object containing the combined data.
-     */
     data(): Promise<In>;
     private body;
 }