@pikku/core 0.12.72 → 0.12.77

package/src/wirings/http/http-runner.ts

@@ -16,17 +16,12 @@ import type {
   CoreUserSession,
   CorePikkuMiddleware,
   CorePikkuMiddlewareGroup,
-  WireServices,
   PikkuRawWire,
   PikkuWire,
   PikkuWiringTypes,
 } from '../../types/core.types.js'
 import { NotFoundError } from '../../errors/errors.js'
-import {
-  closeWireServices,
-  createWeakUID,
-  isSerializable,
-} from '../../utils.js'
+import { createWeakUID, isSerializable } from '../../utils.js'
 import {
   getSingletonServices,
   getCreateWireServices,
@@ -39,15 +34,13 @@ import { pikkuState } from '../../pikku-state.js'
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js'
 import type { PikkuChannel } from '../channel/channel.types.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: PikkuHTTPRequest,
   headerKeys: string[]
@@ -62,35 +55,6 @@ function extractHeadersFromRequest(
   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 = <PikkuMiddleware extends CorePikkuMiddleware>(
   pattern: string,
   middleware: CorePikkuMiddlewareGroup,
@@ -124,21 +88,6 @@ export const addHTTPPermission = (
   )
 }
 
-/**
- * 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 = <
   In,
   Out,
@@ -163,10 +112,6 @@ export const wireHTTP = <
   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.`
     )
@@ -184,17 +129,6 @@ export const wireHTTP = <
     ?.set(httpWiring.route, httpWiring as any)
 }
 
-/**
- * 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: string, requestPath: string) => {
   const matchedPath = httpRouter.match(
     requestType.toLowerCase() as HTTPMethod,
@@ -218,16 +152,6 @@ const getMatchingRoute = (requestType: string, requestPath: string) => {
   }
 }
 
-/**
- * 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: PikkuHTTPRequest | undefined,
   response: PikkuHTTPResponse | undefined
@@ -247,26 +171,6 @@ export const createHTTPWire = (
   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: {
     singletonServices: any
@@ -292,10 +196,8 @@ const executeRoute = async (
     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
@@ -310,14 +212,12 @@ const executeRoute = async (
   }
 
   const requiresSession = route.auth !== false
-  let wireServices: any
   let result: any
 
   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")
   }
@@ -365,11 +265,11 @@ const executeRoute = async (
       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 = {
@@ -432,12 +332,11 @@ const executeRoute = async (
         http?.response?.arrayBuffer(JSON.stringify({ type: 'done' }))
       } 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 {
     if (result instanceof Response) {
@@ -452,24 +351,9 @@ const executeRoute = async (
     }
   }
 
-  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 <In, Out>(
   request: Request,
   params: RunHTTPWiringOptions = {}
@@ -479,18 +363,6 @@ export const fetch = async <In, Out>(
   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 <In, Out>(
   request: Request | PikkuHTTPRequest,
   params: RunHTTPWiringOptions = {}
@@ -500,24 +372,6 @@ export const pikkuFetch = async <In, Out>(
   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 <In, Out>(
   request: Request | PikkuHTTPRequest,
   response: PikkuHTTPResponse,
@@ -527,7 +381,6 @@ export const fetchData = async <In, Out>(
     logWarningsForStatusCodes = [],
     coerceDataFromSchema = true,
     bubbleErrors = false,
-    // Surface the error message + stack on unexpected 500s unless in production.
     exposeErrors = !isProduction(),
     generateRequestId,
     traceId: externalTraceId,
@@ -536,16 +389,13 @@ export const fetchData = async <In, Out>(
 ): Promise<Out | void> => {
   const singletonServices = getSingletonServices()
   const createWireServices = getCreateWireServices()
-  let wireServices: WireServices<typeof singletonServices> | undefined
   let result: Out
 
-  // 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: string | null = externalTraceId ?? null
   if (!requestId) {
     try {
@@ -554,15 +404,12 @@ export const fetchData = async <In, Out>(
   }
   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) {
@@ -588,8 +435,7 @@ export const fetchData = async <In, Out>(
       throw new NotFoundError()
     }
 
-    // Execute the matched route along with its middleware and session management
-    ;({ result, wireServices } = await executeRoute(
+    ;({ result } = await executeRoute(
       {
         singletonServices,
         createWireServices,
@@ -613,10 +459,5 @@ export const fetchData = async <In, Out>(
       bubbleErrors,
       exposeErrors
     )
-  } finally {
-    // Clean up any session-specific services created during processing
-    if (wireServices) {
-      await closeWireServices(singletonServices.logger, wireServices)
-    }
   }
 }

package/src/wirings/http/http.types.ts

@@ -42,9 +42,6 @@ export type RunHTTPWiringOptions = Partial<{
   maxBodySize: number
 }>
 
-/**
- * Represents the HTTP methods supported for API HTTP wirings.
- */
 export type HTTPMethod =
   | 'post'
   | 'get'
@@ -54,17 +51,10 @@ export type HTTPMethod =
   | '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
@@ -72,47 +62,26 @@ export type HTTPRouteBaseConfig = {
   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,
@@ -208,21 +177,26 @@ export type CoreHTTPFunctionWiring<
       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[]
@@ -274,16 +248,15 @@ export interface PikkuHTTPResponse<Out = unknown> {
       | 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>
@@ -297,24 +270,14 @@ export type HTTPRouteConfig<
     any
   >,
 > = HTTPRouteBaseConfig & {
-  // Required
   method: HTTPMethod
   route: string
   func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>
-
-  // Auth
   auth?: boolean
-
-  // Middleware
   middleware?: PikkuMiddleware[]
-
-  // SSE support
   sse?: boolean
 }
 
-/**
- * Group-level configuration applied to all routes
- */
 export type HTTPRoutesGroupConfig<
   PikkuPermission extends CorePikkuPermission<any, any, any> =
     CorePikkuPermission<any, any, any>,
@@ -329,25 +292,15 @@ export type HTTPRoutesGroupConfig<
   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/src/wirings/http/log-http-routes.ts

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

package/src/wirings/http/pikku-fetch-http-request.test.ts

@@ -147,8 +147,6 @@ test('data() parses application/x-www-form-urlencoded correctly', async () => {
   })
 })
 
-// --- Compatible types
-
 test('data() treats "123" and 123 as equivalent', async () => {
   const req = createRequest(
     'POST',
@@ -160,7 +158,7 @@ test('data() treats "123" and 123 as equivalent', async () => {
   )
 
   const r = new PikkuFetchHTTPRequest(req)
-  r.setParams({ id: '123' }) // All match
+  r.setParams({ id: '123' })
   const result = await r.data()
   assert.deepEqual(result, { id: '123' })
 })
@@ -176,13 +174,11 @@ test('data() treats "true" and true as equivalent', async () => {
   )
 
   const r = new PikkuFetchHTTPRequest(req)
-  r.setParams({ flag: 'true' }) // All match
+  r.setParams({ flag: 'true' })
   const result = await r.data()
   assert.deepEqual(result, { flag: 'true' })
 })
 
-// --- Conflicts
-
 test('data() throws on conflicting values', async () => {
   const req = createRequest(
     'POST',
@@ -219,10 +215,6 @@ test('data() throws on boolean conflict', async () => {
   })
 })
 
-// --- Safe fallback: only one source
-
-// --- Body size limits
-
 const streamedRequest = (chunks) =>
   new Request('http://localhost', {
     method: 'POST',