@pikku/core 0.12.71 → 0.12.74

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

@@ -1,11 +1,19 @@
 import { parse as parseQuery } from 'picoquery'
 import { parse as parseCookie } from 'cookie'
 import type { HTTPMethod, PikkuHTTPRequest, PikkuQuery } from './http.types.js'
-import { UnprocessableContentError } from '../../errors/errors.js'
+import {
+  PayloadTooLargeError,
+  UnprocessableContentError,
+} from '../../errors/errors.js'
+
+export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024
+
+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 class PikkuFetchHTTPRequest<
@@ -17,9 +25,14 @@ export class PikkuFetchHTTPRequest<
   #rawBodyText: string | undefined
   #rawBodyBuffer: ArrayBuffer | undefined
   #rawBufferPromise: Promise<ArrayBuffer> | undefined
+  #maxBodySize: number
 
-  constructor(private request: Request) {
+  constructor(
+    private request: Request,
+    { maxBodySize = DEFAULT_MAX_BODY_SIZE }: PikkuFetchHTTPRequestOptions = {}
+  ) {
     this.#url = new URL(request.url)
+    this.#maxBodySize = maxBodySize
   }
 
   public method(): HTTPMethod {
@@ -30,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
@@ -78,13 +71,66 @@ export class PikkuFetchHTTPRequest<
       )
       return this.#rawBufferPromise
     }
-    this.#rawBufferPromise = this.request.arrayBuffer().then((buf) => {
+    this.#rawBufferPromise = this.#readBoundedBuffer().then((buf) => {
       this.#rawBodyBuffer = buf
       return buf
     })
     return this.#rawBufferPromise
   }
 
+  async #readBoundedBuffer(): Promise<ArrayBuffer> {
+    const contentLength = this.request.headers.get('content-length')
+    if (contentLength !== null) {
+      const declaredSize = Number(contentLength)
+      if (Number.isFinite(declaredSize) && declaredSize > this.#maxBodySize) {
+        throw this.#payloadTooLarge()
+      }
+    }
+
+    const stream = this.request.body
+    if (stream === null) {
+      const buffer = await this.request.arrayBuffer()
+      if (buffer.byteLength > this.#maxBodySize) {
+        throw this.#payloadTooLarge()
+      }
+      return buffer
+    }
+
+    const reader = stream.getReader()
+    const chunks: Uint8Array[] = []
+    let size = 0
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) {
+          break
+        }
+        size += value.byteLength
+        if (size > this.#maxBodySize) {
+          await reader.cancel()
+          throw this.#payloadTooLarge()
+        }
+        chunks.push(value)
+      }
+    } finally {
+      reader.releaseLock()
+    }
+
+    const body = new Uint8Array(size)
+    let offset = 0
+    for (const chunk of chunks) {
+      body.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+    return body.buffer as ArrayBuffer
+  }
+
+  #payloadTooLarge(): PayloadTooLargeError {
+    return new PayloadTooLargeError(
+      `Request body exceeds the maximum size of ${this.#maxBodySize} bytes`
+    )
+  }
+
   async #readRawText(): Promise<string> {
     if (this.#rawBodyText !== undefined) {
       return this.#rawBodyText
@@ -98,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]
@@ -120,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]
@@ -214,6 +235,9 @@ export class PikkuFetchHTTPRequest<
         )
       }
     } catch (e) {
+      if (e instanceof PayloadTooLargeError) {
+        throw e
+      }
       throw new UnprocessableContentError(`Error parsing body: ${e}`)
     }
     return 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.test.ts

@@ -329,6 +329,46 @@ describe('runMCPTool', () => {
       }
     )
   })
+
+  test('withholds the error message and stack from internal MCP errors in production', async () => {
+    pikkuState(null, 'mcp', 'toolsMeta').prodBoom = {
+      name: 'prodBoom',
+      title: 'Prod Boom',
+      description: 'Prod Boom',
+      pikkuFuncId: 'prodBoomFunc',
+      inputSchema: null,
+      outputSchema: null,
+    } as never
+    registerFunction('prodBoomFunc', async () => {
+      throw new Error('secret internal detail')
+    })
+
+    const originalNodeEnv = process.env.NODE_ENV
+    process.env.NODE_ENV = 'production'
+    try {
+      await assert.rejects(
+        () =>
+          runMCPTool(
+            { jsonrpc: '2.0', id: 'prod-boom-1', params: {} },
+            { mcp: mcpWire as never },
+            'prodBoom'
+          ),
+        (error: unknown) => {
+          assert.ok(error instanceof MCPError)
+          assert.equal(error.error.code, -32603)
+          assert.equal(error.error.message, 'Internal error')
+          assert.equal(error.error.data, undefined)
+          return true
+        }
+      )
+    } finally {
+      if (originalNodeEnv === undefined) {
+        delete process.env.NODE_ENV
+      } else {
+        process.env.NODE_ENV = originalNodeEnv
+      }
+    }
+  })
 })
 
 describe('runMCPPrompt', () => {