@pikku/core 0.12.72 → 0.12.74

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

@@ -6,11 +6,6 @@ import {
   UnprocessableContentError,
 } from '../../errors/errors.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 const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024
 
 export type PikkuFetchHTTPRequestOptions = Partial<{
@@ -19,8 +14,6 @@ export type PikkuFetchHTTPRequestOptions = Partial<{
 }>
 
 /**
- * Abstract class representing a pikku request.
- * @template In - The type of the request body.
  * @group RequestResponse
  */
 export class PikkuFetchHTTPRequest<
@@ -50,35 +43,15 @@ export class PikkuFetchHTTPRequest<
     return this.#url.pathname
   }
 
-  /**
-   * Retrieves the request body.
-   * @returns A promise that resolves to the request body.
-   */
   public async json(): Promise<In> {
     const text = await this.#readRawText()
     return JSON.parse(text) as In
   }
 
-  /**
-   * Retrieves the raw request body as a Buffer.
-   * @returns A promise that resolves to the raw request body.
-   */
   public async arrayBuffer(): Promise<ArrayBuffer> {
     return this.#readRawBuffer()
   }
 
-  /**
-   * Reads the underlying single-use request body exactly once and memoises both
-   * the in-flight promise and the result. `json()`, `arrayBuffer()`, `body()`
-   * and `toWebRequest()` all funnel through here, so a request whose body is
-   * consumed in more than one place can no longer race on the underlying stream
-   * and fail with "Body has already been used".
-   *
-   * If a second consumer asks for the body while the first read is still in
-   * flight, that is the concurrent double-read that used to crash — now safe,
-   * but warned about so the redundant consumer is found and removed at the
-   * source rather than silently leaning on this cache.
-   */
   async #readRawBuffer(): Promise<ArrayBuffer> {
     if (this.#rawBodyBuffer !== undefined) {
       return this.#rawBodyBuffer
@@ -105,12 +78,6 @@ export class PikkuFetchHTTPRequest<
     return this.#rawBufferPromise
   }
 
-  /**
-   * Reads the body while refusing to buffer more than `maxBodySize` bytes. The
-   * declared `content-length` is rejected up front so an oversized body is never
-   * transferred, and the stream is measured as it arrives because that header is
-   * both optional and attacker-controlled.
-   */
   async #readBoundedBuffer(): Promise<ArrayBuffer> {
     const contentLength = this.request.headers.get('content-length')
     if (contentLength !== null) {
@@ -177,19 +144,10 @@ export class PikkuFetchHTTPRequest<
     return Object.fromEntries(this.request.headers.entries())
   }
 
-  /**
-   * 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.
-   */
   public header(headerName: string): string | null {
     return this.request.headers.get(headerName.toLowerCase())
   }
 
-  /**
-   * Retrieves the cookies from the request.
-   * @returns An object containing the cookies.
-   */
   public cookie(cookieName: string): string | null {
     if (this.#cookies?.[cookieName]) {
       return this.#cookies[cookieName]
@@ -199,36 +157,20 @@ export class PikkuFetchHTTPRequest<
     return this.#cookies[cookieName] || null
   }
 
-  /**
-   * Retrieves the request parameters.
-   * @returns An object containing the request parameters.
-   */
   public params(): Partial<Record<string, string | string[]>> {
     return this.#params
   }
 
-  /**
-   * Sets the request parameters.
-   * @param params - An object containing the request parameters to set.
-   */
   public setParams(
     params: Record<string, string | string[] | undefined>
   ): void {
     this.#params = params
   }
 
-  /**
-   * Retrieves the query parameters from the request.
-   * @returns An object containing the query parameters.
-   */
   public query(): PikkuQuery {
     return parseQuery(this.#url.searchParams.toString()) as 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.
-   */
   public async data(): Promise<In> {
     const body = await this.body()
     const parts = [this.params(), this.query(), body]

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

@@ -1,6 +1,6 @@
 import { describe, test } from 'node:test'
 import assert from 'assert'
-import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js' // Adjust path if needed
+import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
 
 describe('PikkuFetchHTTPResponse', () => {
   test('sets status code', () => {

package/src/wirings/http/pikku-fetch-http-response.ts

@@ -118,8 +118,6 @@ export class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
     const cookieHeader = Array.from(this.#cookies.entries()).map(
       ([name, { value, flags }]) => serializeCookie(name, value, flags)
     )
-    // Multiple Set-Cookie headers must be appended separately, not joined with commas
-    // per HTTP specification (RFC 6265)
     cookieHeader.forEach((cookie) => this.#headers.append('Set-Cookie', cookie))
     return new Response(this.#body, {
       ...args,
@@ -143,7 +141,6 @@ export class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
         this.#send = send
         this.#close = close
 
-        // Force initial flush
         controller.enqueue(encoder.encode(':\n\n'))
       },
     })

package/src/wirings/http/routers/path-to-regex.test.ts

@@ -7,7 +7,6 @@ import type { HTTPMethod } from '../http.types.js'
 describe('PathToRegexRouter', () => {
   let router: PathToRegexRouter
 
-  // Helper to create mock route wiring
   const mockRoute = (route: string) => ({
     route,
     method: 'get' as HTTPMethod,
@@ -21,7 +20,6 @@ describe('PathToRegexRouter', () => {
 
   describe('Static Route Optimization', () => {
     test('should correctly identify static routes', () => {
-      // Setup test routes
       pikkuState(
         null,
         'http',
@@ -42,7 +40,6 @@ describe('PathToRegexRouter', () => {
 
       router.initialize()
 
-      // Test static routes - should return exact matches with empty params
       const staticResult = router.match('get', '/static')
       assert.ok(staticResult, 'Static route should match')
       assert.strictEqual(staticResult.route, '/static')
@@ -55,7 +52,6 @@ describe('PathToRegexRouter', () => {
     })
 
     test('should handle dynamic routes with parameters', () => {
-      // Setup test routes with parameters
       pikkuState(
         null,
         'http',
@@ -78,7 +74,6 @@ describe('PathToRegexRouter', () => {
 
       router.initialize()
 
-      // Test dynamic routes - should return matches with extracted parameters
       const userResult = router.match('get', '/api/users/123')
       assert.ok(userResult, 'Dynamic route should match')
       assert.strictEqual(userResult.route, '/api/users/:id')
@@ -98,7 +93,6 @@ describe('PathToRegexRouter', () => {
     })
 
     test('should handle multi-parameter routes', () => {
-      // Setup routes with multiple parameters
       pikkuState(
         null,
         'http',
@@ -124,7 +118,6 @@ describe('PathToRegexRouter', () => {
 
       router.initialize()
 
-      // Test multi-parameter routes
       const apiResult = router.match('get', '/api/v2/users/456')
       assert.ok(apiResult, 'Multi-parameter route should match')
       assert.strictEqual(apiResult.route, '/api/:version/users/:userId')
@@ -140,7 +133,6 @@ describe('PathToRegexRouter', () => {
     })
 
     test('should prioritize static routes over dynamic routes for performance', () => {
-      // Setup mixed routes where static could conflict with dynamic
       pikkuState(
         null,
         'http',
@@ -149,8 +141,8 @@ describe('PathToRegexRouter', () => {
           [
             'get',
             new Map([
-              ['/api/users', mockRoute('/api/users')], // static
-              ['/api/:resource', mockRoute('/api/:resource')], // dynamic that could match above
+              ['/api/users', mockRoute('/api/users')],
+              ['/api/:resource', mockRoute('/api/:resource')],
             ]),
           ],
         ])
@@ -160,10 +152,9 @@ describe('PathToRegexRouter', () => {
 
       router.initialize()
 
-      // Static route should be found first (O(1) lookup)
       const result = router.match('get', '/api/users')
       assert.ok(result, 'Route should match')
-      assert.strictEqual(result.route, '/api/users') // Should match static, not dynamic
+      assert.strictEqual(result.route, '/api/users')
       assert.deepStrictEqual(result.params, {})
     })
   })
@@ -178,7 +169,7 @@ describe('PathToRegexRouter', () => {
           [
             'get',
             new Map([
-              ['test', mockRoute('test')], // route without leading slash
+              ['test', mockRoute('test')],
               ['api/health', mockRoute('api/health')],
             ]),
           ],
@@ -189,7 +180,6 @@ describe('PathToRegexRouter', () => {
 
       router.initialize()
 
-      // Should match with or without leading slash in request
       const result1 = router.match('get', '/test')
       assert.ok(result1, 'Should match /test')
       assert.strictEqual(result1.route, 'test')
@@ -220,7 +210,6 @@ describe('PathToRegexRouter', () => {
 
       router.initialize()
 
-      // Channel routes should be accessible via GET method
       const wsResult = router.match('get', '/ws/test')
       assert.ok(wsResult, 'Static channel route should match')
       assert.strictEqual(wsResult.route, '/ws/test')
@@ -259,7 +248,6 @@ describe('PathToRegexRouter', () => {
 
       const result = router.match('get', '/api/test')
       assert.ok(result, 'Route should match')
-      // Router only returns route and params, middleware is handled separately
       assert.strictEqual(result.route, '/api/test')
       assert.deepStrictEqual(result.params, {})
     })
@@ -310,7 +298,6 @@ describe('PathToRegexRouter', () => {
       pikkuState(null, 'http', 'middleware', new Map())
       pikkuState(null, 'channel', 'channels', new Map())
 
-      // Don't call initialize manually
       const result = router.match('get', '/test')
       assert.ok(result, 'Should auto-initialize and match')
       assert.strictEqual(result.route, '/test')

package/src/wirings/http/routers/path-to-regex.ts

@@ -29,7 +29,6 @@ export class PathToRegexRouter implements Router {
     const routes = pikkuState(null, 'http', 'routes')
     const channelRoutes = pikkuState(null, 'channel', 'channels')
 
-    // Helper function to compile routes for a given method
     const compileRoutesForMethod = (
       method: HTTPMethod,
       routeEntries: Iterable<[string, any]>
@@ -40,28 +39,24 @@ export class PathToRegexRouter implements Router {
         this.staticRoutes.get(method) || new Map<string, StaticRoute>()
 
       for (const [routePath] of routeEntries) {
-        // Normalize route path - ensure it starts with /
         const normalizedRoutePath = routePath.startsWith('/')
           ? routePath
           : `/${routePath}`
 
-        // Check if route is static (no parameters or wildcards)
         const isStaticRoute = !/\*|:/.test(normalizedRoutePath)
 
         if (isStaticRoute) {
-          // Store static routes for O(1) lookup
           methodStaticRoutes.set(normalizedRoutePath, {
-            route: routePath, // Keep the original route path for lookup in pikkuState
+            route: routePath,
           })
         } else {
-          // Compile dynamic routes with path-to-regexp
           const matcher = match(normalizedRoutePath, {
             decode: decodeURIComponent,
           })
 
           methodCompiledRoutes.set(normalizedRoutePath, {
             matcher,
-            route: routePath, // Keep the original route path for lookup in pikkuState
+            route: routePath,
           })
         }
       }
@@ -70,12 +65,10 @@ export class PathToRegexRouter implements Router {
       this.staticRoutes.set(method, methodStaticRoutes)
     }
 
-    // Precompile all HTTP route matchers
     for (const [method, routeMap] of routes.entries()) {
       compileRoutesForMethod(method, routeMap.entries())
     }
 
-    // Precompile all channel route matchers (treating them as GET routes for WebSocket upgrades)
     const channelRoutesArray: Array<[string, any]> = Array.from(
       channelRoutes.entries()
     ).map(([, channel]) => [channel.route, channel])
@@ -89,10 +82,8 @@ export class PathToRegexRouter implements Router {
       this.initialize()
     }
 
-    // Normalize path - ensure it starts with /
     const normalizedPath = path.startsWith('/') ? path : `/${path}`
 
-    // First, try static routes for O(1) lookup
     const methodStaticRoutes = this.staticRoutes.get(method)
     if (methodStaticRoutes) {
       const staticRoute = methodStaticRoutes.get(normalizedPath)
@@ -104,13 +95,11 @@ export class PathToRegexRouter implements Router {
       }
     }
 
-    // If no static route matched, try dynamic routes
     const methodRoutes = this.compiledRoutes.get(method)
     if (!methodRoutes) {
       return null
     }
 
-    // Try each compiled route for this method
     for (const [, compiledRoute] of methodRoutes.entries()) {
       const result = compiledRoute.matcher(normalizedPath)
       if (result) {

package/src/wirings/http/web-request.test.ts

@@ -34,7 +34,7 @@ const createMockResponse = () => {
   const state = {
     statusCode: 0,
     headers: {} as Record<string, string | string[]>,
-    body: null as string | null,
+    body: null as string | Uint8Array | null,
     redirectUrl: null as string | null,
     redirectStatus: null as number | null,
   }
@@ -55,7 +55,9 @@ const createMockResponse = () => {
       return res
     },
     arrayBuffer(data: any) {
-      state.body = typeof data === 'string' ? data : null
+      // Recorded as given. Coercing a non-string to null here would have hidden
+      // a body that arrived as bytes, which is the case worth testing.
+      state.body = data ?? null
       return res
     },
     redirect(location: string, status?: number) {
@@ -348,4 +350,33 @@ describe('applyWebResponse', () => {
     assert.equal(state.headers['content-length'], undefined)
     assert.equal(state.headers['transfer-encoding'], undefined)
   })
+
+  test('passes a binary body through byte for byte', async () => {
+    // Reading a body as text is lossy for anything that is not valid UTF-8:
+    // 0x8e is not, and decoding it produces U+FFFD, which re-encodes to three
+    // bytes. A WASM module or a model file goes over the wire bigger than it
+    // started and no longer parses, with a 200 and nothing logged either side.
+    const { res, state } = createMockResponse()
+    const bytes = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x8e, 0xff])
+    const webRes = new Response(bytes, {
+      status: 200,
+      headers: { 'content-type': 'application/wasm' },
+    })
+
+    await applyWebResponse(res, webRes)
+
+    assert.deepEqual(new Uint8Array(state.body as Uint8Array), bytes)
+  })
+
+  test('still writes a JSON body as text', async () => {
+    const { res, state } = createMockResponse()
+    const webRes = new Response('{"ok":true}', {
+      status: 200,
+      headers: { 'content-type': 'application/json; charset=utf-8' },
+    })
+
+    await applyWebResponse(res, webRes)
+
+    assert.equal(state.body, '{"ok":true}')
+  })
 })

package/src/wirings/http/web-request.ts

@@ -1,10 +1,6 @@
 import type { PikkuHTTPRequest } from './http.types.js'
 import type { PikkuHTTPResponse } from './http.types.js'
 
-/**
- * Converts a PikkuHTTPRequest into a Web API Request.
- * Useful for bridging Pikku routes to libraries that expect standard Web Request objects.
- */
 export function toWebRequest(req: PikkuHTTPRequest, baseUrl?: string): Request {
   const proto = req.header('x-forwarded-proto') ?? 'http'
   const host =
@@ -30,11 +26,6 @@ export function toWebRequest(req: PikkuHTTPRequest, baseUrl?: string): Request {
   return new Request(url, {
     method,
     headers,
-    // `pull` (lazy) rather than `start` (eager): the body is only read from the
-    // underlying request when this stream is actually consumed. A consumer that
-    // builds a web Request just to read its headers (e.g. a session middleware
-    // calling getSession({ headers })) never touches the body, so it does zero
-    // body I/O and cannot race the route handler's read of the same request.
     body: new ReadableStream({
       async pull(controller) {
         try {
@@ -42,7 +33,6 @@ export function toWebRequest(req: PikkuHTTPRequest, baseUrl?: string): Request {
           if (buffer.byteLength > 0) {
             controller.enqueue(new Uint8Array(buffer))
           } else {
-            // arrayBuffer may be empty if body was pre-parsed (e.g., Express middleware)
             const contentType = (
               headers.get('content-type') || ''
             ).toLowerCase()
@@ -63,9 +53,7 @@ export function toWebRequest(req: PikkuHTTPRequest, baseUrl?: string): Request {
               controller.enqueue(new TextEncoder().encode(reconstructed))
             }
           }
-        } catch {
-          // Empty body
-        }
+        } catch {}
         controller.close()
       },
     }),
@@ -108,9 +96,34 @@ function collectSetCookieHeaders(webResponse: Response): string[] {
 }
 
 /**
- * Applies a Web API Response to a PikkuHTTPResponse.
- * Copies status, headers (including Set-Cookie), redirects, and body.
+ * Content types whose bodies are text. Everything else is bytes.
+ *
+ * The distinction matters because reading a body as text is lossy for anything
+ * that is not valid UTF-8: every byte that does not decode becomes U+FFFD, and
+ * re-encoding turns each of those into three bytes. A WASM module or an ONNX
+ * model served that way arrives larger than it left and no longer parses, with
+ * a 200 and no error anywhere to say why.
+ */
+const TEXTUAL_CONTENT_TYPE =
+  /^(text\/|application\/(json|javascript|ecmascript|xml|x-www-form-urlencoded)|[^;]*\+(json|xml)\b)/i
+
+/**
+ * Read a response body as text where that is meaningful, and as bytes
+ * otherwise. An absent content type is treated as text, which is what a body
+ * built from a string gets by default and so preserves existing behaviour.
  */
+async function readBody(
+  webResponse: Response
+): Promise<string | Uint8Array | null> {
+  const contentType = webResponse.headers.get('content-type')
+  if (contentType === null || TEXTUAL_CONTENT_TYPE.test(contentType)) {
+    const text = await webResponse.text()
+    return text === '' ? null : text
+  }
+  const bytes = new Uint8Array(await webResponse.arrayBuffer())
+  return bytes.byteLength === 0 ? null : bytes
+}
+
 export async function applyWebResponse(
   res: PikkuHTTPResponse,
   webResponse: Response
@@ -138,8 +151,8 @@ export async function applyWebResponse(
     res.header('Set-Cookie', setCookieValues)
   }
 
-  const body = await webResponse.text()
-  if (body) {
+  const body = await readBody(webResponse)
+  if (body !== null) {
     if (res.send) {
       res.send(body)
     } else {

package/src/wirings/mcp/mcp-endpoint-registry.test.ts

@@ -132,7 +132,6 @@ describe('MCPEndpointRegistry', () => {
     })
 
     test('should handle empty object gracefully', async () => {
-      // Test with empty object
       await registry.loadFromMCPJson({})
       assert.deepStrictEqual(registry.getTools(), [])
       assert.deepStrictEqual(registry.getResources(), [])

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

@@ -13,7 +13,6 @@ import type {
 } from '../../function/functions.types.js'
 import { getErrorResponse } from '../../errors/error-handler.js'
 import { isProduction } from '../../env.js'
-import { closeWireServices } from '../../utils.js'
 import {
   pikkuState,
   getSingletonServices,
@@ -36,10 +35,7 @@ export class MCPError extends Error {
 
 export type RunMCPEndpointParams<Tools extends string = any> = {
   mcp?: PikkuMCP<Tools>
-  /**
-   * Surface the error message + stack on unexpected internal errors.
-   * Defaults to enabled outside of production.
-   */
+  /** Defaults to enabled outside production. */
   exposeErrors?: boolean
 }
 
@@ -112,13 +108,11 @@ export async function runMCPResource(
     pikkuFuncId = metas[uri]?.pikkuFuncId
   } else {
     for (const [uriTemplate, value] of endpoints.entries()) {
-      // Extract parameter names from the template
       const paramNames = Array.from(
         uriTemplate.matchAll(/\{([^}]+)\}/g),
         (m) => m[1]
       )
 
-      // Create regex pattern to match and capture parameter values
       const regexPattern = uriTemplate.replace(/\{[^}]+\}/g, '([^/]+)')
       const regex = new RegExp(`^${regexPattern}$`)
       const match = uri.match(regex)
@@ -127,7 +121,6 @@ export async function runMCPResource(
         endpoint = value
         pikkuFuncId = metas[uriTemplate]?.pikkuFuncId
 
-        // Extract parameter values and create params object
         for (let i = 0; i < paramNames.length; i++) {
           extractedParams[paramNames[i]!] = match[i + 1]! // match[0] is the full match
         }
@@ -184,9 +177,6 @@ export async function runMCPPrompt(
   )
 }
 
-/**
- * JSON-RPC 2.0 compatible MCP endpoint runner
- */
 async function runMCPPikkuFunc(
   request: JsonRpcRequest,
   type: 'resource' | 'tool' | 'prompt',
@@ -197,7 +187,6 @@ async function runMCPPikkuFunc(
 ): Promise<JsonRpcResponse> {
   const singletonServices = getSingletonServices()
   const createWireServices = getCreateWireServices()
-  let wireServices: any
 
   try {
     if (request.jsonrpc !== '2.0') {
@@ -237,7 +226,6 @@ async function runMCPPikkuFunc(
       meta = pikkuState(null, 'mcp', 'promptsMeta')[name]
     }
 
-    // Resolve namespaced function IDs (e.g., 'swaggerPetstore:findPetsByStatus')
     let resolvedFuncName = pikkuFuncId
     let resolvedPackageName: string | null = meta?.packageName ?? null
     if (pikkuFuncId.includes(':')) {
@@ -295,16 +283,13 @@ async function runMCPPikkuFunc(
         id: request.id,
         code: -32603,
         message: 'Internal error',
+        // knowledge: decisions/security/mcp-internal-error-details-are-double-gated-on-production.md
         data:
           exposeErrors && !isProduction() && e instanceof Error
             ? { message: e.message, stack: e.stack }
             : undefined,
       })
     }
-  } finally {
-    if (wireServices) {
-      await closeWireServices(singletonServices.logger, wireServices)
-    }
   }
 }