@pikku/core 0.12.107 → 0.12.112

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

@@ -1,307 +0,0 @@
-import type { SerializeOptions } from 'cookie'
-import type { StandardSchemaV1 } from '@standard-schema/spec'
-import type { CommonWireMeta } from '../../types/core.types.js'
-import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js'
-import type {
-  CorePikkuFunction,
-  CorePikkuFunctionSessionless,
-  CorePikkuPermission,
-  CorePikkuFunctionConfig,
-} from '../../function/functions.types.js'
-
-type ExtractHTTPWiringParams<S extends string> =
-  S extends `${string}:${infer Param}/${infer Rest}`
-    ? Param | ExtractHTTPWiringParams<`/${Rest}`>
-    : S extends `${string}:${infer Param}`
-      ? Param
-      : never
-
-export type AssertHTTPWiringParams<In, HTTPWiring extends string> =
-  ExtractHTTPWiringParams<HTTPWiring> extends keyof In
-    ? unknown
-    : [
-        'Error: HTTPWiring parameters',
-        ExtractHTTPWiringParams<HTTPWiring>,
-        'not in',
-        keyof In,
-      ]
-
-export type RunHTTPWiringOptions = Partial<{
-  skipUserSession: boolean
-  respondWith404: boolean
-  logWarningsForStatusCodes: number[]
-  coerceDataFromSchema: boolean
-  bubbleErrors: boolean
-  exposeErrors: boolean
-  generateRequestId: () => string
-  /** Pre-resolved trace ID (e.g. CF-Ray). Falls back to x-request-id header or generated ID. */
-  traceId: string
-  /** Maximum request body size in bytes, applied when pikku wraps a fetch `Request`. */
-  maxBodySize: number
-}>
-
-export type HTTPMethod =
-  'post' | 'get' | 'delete' | 'patch' | 'head' | 'put' | 'options'
-
-export type HTTPHeadersSchema = StandardSchemaV1<
-  Record<string, string | string[] | undefined>
->
-
-export type HTTPRouteBaseConfig = {
-  /** How the body is serialised. Defaults to JSON; `xml` is for routes a caller you do not control insists on. */
-  contentType?: 'xml' | 'json'
-  /** Seconds before the request is abandoned. Work that can outlast a request should be dispatched instead, not given a longer timeout. */
-  timeout?: number
-  /** Filters this route in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
-  tags?: string[]
-  /** A schema the request headers are validated against, so a missing or malformed header fails before the function body runs. */
-  headers?: HTTPHeadersSchema
-}
-
-export type CoreHTTPFunction = HTTPRouteBaseConfig & {
-  route: string
-  /** Sends the returned value as-is rather than JSON-encoding it, for a route whose body is binary or already serialised. */
-  returnsJSON?: false
-}
-
-export interface PikkuHTTP<In = unknown> {
-  request?: PikkuHTTPRequest<In>
-  response?: PikkuHTTPResponse
-}
-
-export type PikkuQuery<T = Record<string, string | undefined>> = Record<
-  string,
-  string | T | null | Array<T | null>
->
-
-/**
- * The keys every HTTP wiring takes, whatever it is wired to. The three that
- * are not here — `method`, `auth` and `func` — are correlated rather than
- * independent, and live in the unions below.
- */
-type HTTPWiringShared<
-  R extends string,
-  PikkuMiddleware extends CorePikkuMiddleware<any, any>,
-> = CoreHTTPFunction & {
-  /**
-   * The path this wiring answers on. `:name` marks a parameter, and every
-   * parameter in the path must be a key of the function's input schema —
-   * a mismatch is a compile error rather than a 404 at runtime.
-   */
-  route: R
-  /** Wraps every request to this route: auth, tracing, rate limiting. Runs before the permissions on `func`. */
-  middleware?: PikkuMiddleware[]
-}
-
-/**
- * `auth` decides which kind of function this route can point at, so the two
- * travel together: a route that requires a session gets a function that is
- * handed one, and an open route gets a sessionless function that has none to
- * read. Splitting them would let a function ask for a session the route never
- * establishes.
- */
-type HTTPWiringAuth<
-  In,
-  Out,
-  PikkuFunction extends CorePikkuFunction<In, Out, any, any, any>,
-  PikkuFunctionSessionless extends CorePikkuFunctionSessionless<
-    In,
-    Out,
-    any,
-    any,
-    any
-  >,
-  PikkuPermission extends CorePikkuPermission<In, any, any>,
-  PikkuMiddleware extends CorePikkuMiddleware<any, any>,
-> =
-  | {
-      /** Whether reaching this route requires a session. Defaults to true — a route is closed unless it says otherwise. */
-      auth?: true
-      /** The function to run. It is handed the session this route required. */
-      func: CorePikkuFunctionConfig<
-        PikkuFunction,
-        PikkuPermission,
-        PikkuMiddleware
-      >
-    }
-  | {
-      /** Whether reaching this route requires a session. Defaults to true — a route is closed unless it says otherwise. */
-      auth?: false
-      /** On an open route there is no session, so this must be a sessionless function. */
-      func: CorePikkuFunctionConfig<
-        PikkuFunctionSessionless,
-        PikkuPermission,
-        PikkuMiddleware
-      >
-    }
-
-/**
- * `sse` and `query` are each valid on one method only, so the method carries
- * them: streaming is a GET, and naming which input keys arrive in the query
- * string is only a question on a POST, where the rest of the input is a body.
- */
-type HTTPWiringMethod<In> =
-  | {
-      /** The HTTP method. A route and method together address one wiring. */
-      method: HTTPMethod
-      sse?: undefined
-    }
-  | {
-      /** The HTTP method. A route and method together address one wiring. */
-      method: 'get'
-      /** Streams the response as server-sent events instead of returning it once. GET only. */
-      sse?: boolean
-    }
-  | {
-      /** The HTTP method. A route and method together address one wiring. */
-      method: 'post'
-      /** Input keys that arrive in the query string rather than the body. POST only, where the body is the default home for input. */
-      query?: Array<keyof In>
-      sse?: undefined
-    }
-
-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
-  >,
-> = HTTPWiringShared<R, PikkuMiddleware> &
-  HTTPWiringAuth<
-    In,
-    Out,
-    PikkuFunction,
-    PikkuFunctionSessionless,
-    PikkuPermission,
-    PikkuMiddleware
-  > &
-  HTTPWiringMethod<In>
-
-export type HTTPFunctionMetaInputTypes = {
-  params?: string
-  query?: string
-  body?: string
-}
-
-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
-  params?: string[]
-  query?: string[]
-  inputTypes?: HTTPFunctionMetaInputTypes
-  headersSchemaName?: string
-  sse?: true
-  groupBasePath?: string
-}
-export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>
-
-export interface PikkuHTTPRequest<In = unknown> {
-  method(): HTTPMethod
-  path(): string
-  data(): Promise<In>
-  json(): Promise<unknown>
-  arrayBuffer(): Promise<ArrayBuffer>
-  headers(): Record<string, string>
-  header(headerName: string): string | null
-  cookie(name?: string): string | null
-  params(): Partial<Record<string, string | string[]>>
-  setParams(params: Record<string, string | string[] | undefined>): void
-  query(): PikkuQuery
-}
-
-export interface PikkuHTTPResponse<Out = unknown> {
-  readonly statusCode: number
-  status(code: number): this
-  cookie(name: string, value: string | null, options: SerializeOptions): this
-  header(name: string, value: string | string[]): this
-  arrayBuffer(
-    data:
-      | ArrayBuffer
-      | ArrayBufferView
-      | Blob
-      | string
-      | FormData
-      | URLSearchParams
-      | ReadableStream
-  ): this
-  json(data: Out): 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
-}
-
-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
-  func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>
-  auth?: boolean
-  middleware?: PikkuMiddleware[]
-  sse?: boolean
-}
-
-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[]
-}
-
-export type HTTPRouteMap = {
-  [key: string]: HTTPRouteConfig | HTTPRouteMap | HTTPRouteContract
-}
-
-export type HTTPRouteContract<T extends HTTPRouteMap = HTTPRouteMap> =
-  HTTPRoutesGroupConfig & {
-    routes: T
-  }
-
-export type WireHTTPRoutesConfig = HTTPRoutesGroupConfig & {
-  routes: HTTPRouteMap | HTTPRouteConfig[]
-}

package/src/wirings/http/index.ts

@@ -1,27 +0,0 @@
-export {
-  PikkuFetchHTTPRequest,
-  DEFAULT_MAX_BODY_SIZE,
-} from './pikku-fetch-http-request.js'
-export { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js'
-export { logRoutes } from './log-http-routes.js'
-
-export { fetch, fetchData, wireHTTP, addHTTPMiddleware } from './http-runner.js'
-
-export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js'
-export { toWebRequest, applyWebResponse } from './web-request.js'
-export { httpRouter } from './routers/http-router.js'
-
-export type {
-  AssertHTTPWiringParams,
-  CoreHTTPFunctionWiring,
-  HTTPMethod,
-  HTTPRouteBaseConfig,
-  HTTPRouteContract,
-  HTTPRouteMap,
-  HTTPWiringsMeta,
-  PikkuHTTP,
-  PikkuHTTPRequest,
-  PikkuHTTPResponse,
-  PikkuQuery,
-  RunHTTPWiringOptions,
-} from './http.types.js'

package/src/wirings/http/log-http-routes.ts

@@ -1,18 +0,0 @@
-import { pikkuState } from '../../pikku-state.js'
-import type { Logger } from '../../services/index.js'
-
-export const logRoutes = (logger: Logger) => {
-  const routesByType = pikkuState(null, 'http', 'routes')
-  if (routesByType.size === 0) {
-    logger.info('No routes added')
-    return
-  }
-
-  let routesMessage = 'Routes loaded:'
-  routesByType.forEach((routes) => {
-    routes.forEach((route) => {
-      routesMessage += `\n\t- ${route.method.toUpperCase()} -> ${route.route}`
-    })
-  })
-  logger.info(routesMessage)
-}

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

@@ -1,318 +0,0 @@
-import { test } from 'node:test'
-import assert from 'node:assert/strict'
-import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request'
-
-const createRequest = (method, url, body, headers = {}) => {
-  return new Request(url, {
-    method,
-    headers,
-    body:
-      method === 'POST'
-        ? typeof body === 'string'
-          ? body
-          : JSON.stringify(body)
-        : undefined,
-  })
-}
-
-test('method() returns lowercase HTTP method', () => {
-  const req = createRequest('POST', 'http://localhost/test', null)
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  assert.equal(pikkuReq.method(), 'post')
-})
-
-test('path() returns pathname only', () => {
-  const req = createRequest('GET', 'http://localhost/foo/bar?x=1', null)
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  assert.equal(pikkuReq.path(), '/foo/bar')
-})
-
-test('header() retrieves headers case-insensitively', () => {
-  const req = createRequest('GET', 'http://localhost', null, {
-    'Content-Type': 'application/json',
-  })
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  assert.equal(pikkuReq.header('content-type'), 'application/json')
-})
-
-test('cookie() parses cookies correctly', () => {
-  const req = createRequest('GET', 'http://localhost', null, {
-    Cookie: 'session=abc; user=test',
-  })
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  assert.equal(pikkuReq.cookie('session'), 'abc')
-  assert.equal(pikkuReq.cookie('user'), 'test')
-  assert.equal(pikkuReq.cookie('missing'), null)
-})
-
-test('params() and setParams()', () => {
-  const req = createRequest('GET', 'http://localhost', null)
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  assert.deepEqual(pikkuReq.params(), {})
-  pikkuReq.setParams({ id: '123' })
-  assert.deepEqual(pikkuReq.params(), { id: '123' })
-})
-
-test('query() parses URL search params', () => {
-  const req = createRequest('GET', 'http://localhost?x=1&y=2', null)
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  assert.equal(pikkuReq.query().x, '1')
-  assert.equal(pikkuReq.query().y, '2')
-})
-
-test('data() merges json body, query, and params', async () => {
-  const req = createRequest(
-    'POST',
-    'http://localhost/test?a=5',
-    { foo: 'bar' },
-    { 'Content-Type': 'application/json' }
-  )
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  pikkuReq.setParams({ id: '22' })
-  const result = await pikkuReq.data()
-  assert.deepEqual(result, { id: '22', a: '5', foo: 'bar' })
-})
-
-test('data() wraps string JSON body under data key', async () => {
-  const req = createRequest('POST', 'http://localhost', '"hello"', {
-    'Content-Type': 'application/json',
-  })
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  const result = await pikkuReq.data()
-  assert.deepEqual(result, { data: 'hello' })
-})
-
-test('data() handles text/plain correctly', async () => {
-  const req = new Request('http://localhost', {
-    method: 'POST',
-    headers: { 'Content-Type': 'text/plain' },
-    body: 'hello world',
-  })
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  const result = await pikkuReq.data()
-  assert.deepEqual(result, { data: 'hello world' })
-})
-
-test('data() returns arrayBuffer for unknown content-type', async () => {
-  const buffer = Buffer.from('raw')
-  const req = new Request('http://localhost', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/octet-stream' },
-    body: buffer,
-  })
-  const pikkuReq = new PikkuFetchHTTPRequest<any>(req)
-  const result = await pikkuReq.data()
-  assert(result.data instanceof ArrayBuffer)
-  const str = Buffer.from(result.data).toString()
-  assert.equal(str, 'raw')
-})
-
-test('data() handles invalid JSON safely', async () => {
-  const req = new Request('http://localhost', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: 'not-json',
-  })
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  try {
-    await pikkuReq.data()
-    assert(false, 'Should have thrown')
-  } catch (e) {
-    assert(e.message.includes('Error parsing body'))
-  }
-})
-
-test('data() parses application/x-www-form-urlencoded correctly', async () => {
-  const formBody = 'name=Yasser&age=35&active=true'
-
-  const req = new Request('http://localhost/form?ref=abc', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/x-www-form-urlencoded',
-    },
-    body: formBody,
-  })
-
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  pikkuReq.setParams({ userId: '999' })
-
-  const result = await pikkuReq.data()
-
-  assert.deepEqual(result, {
-    userId: '999',
-    ref: 'abc',
-    name: 'Yasser',
-    age: '35',
-    active: 'true',
-  })
-})
-
-test('data() treats "123" and 123 as equivalent', async () => {
-  const req = createRequest(
-    'POST',
-    'http://localhost?id=123',
-    { id: 123 },
-    {
-      'Content-Type': 'application/json',
-    }
-  )
-
-  const r = new PikkuFetchHTTPRequest(req)
-  r.setParams({ id: '123' })
-  const result = await r.data()
-  assert.deepEqual(result, { id: '123' })
-})
-
-test('data() treats "true" and true as equivalent', async () => {
-  const req = createRequest(
-    'POST',
-    'http://localhost?flag=true',
-    { flag: true },
-    {
-      'Content-Type': 'application/json',
-    }
-  )
-
-  const r = new PikkuFetchHTTPRequest(req)
-  r.setParams({ flag: 'true' })
-  const result = await r.data()
-  assert.deepEqual(result, { flag: 'true' })
-})
-
-test('data() throws on conflicting values', async () => {
-  const req = createRequest(
-    'POST',
-    'http://localhost?foo=123',
-    { foo: 456 },
-    {
-      'Content-Type': 'application/json',
-    }
-  )
-
-  const r = new PikkuFetchHTTPRequest(req)
-  r.setParams({ foo: '123' })
-
-  await assert.rejects(async () => await r.data(), {
-    message: 'Conflicting values for key "foo": "123" vs "456"',
-  })
-})
-
-test('data() throws on boolean conflict', async () => {
-  const req = createRequest(
-    'POST',
-    'http://localhost?debug=false',
-    { debug: true },
-    {
-      'Content-Type': 'application/json',
-    }
-  )
-
-  const r = new PikkuFetchHTTPRequest(req)
-  r.setParams({})
-
-  await assert.rejects(async () => await r.data(), {
-    message: 'Conflicting values for key "debug": "false" vs "true"',
-  })
-})
-
-const streamedRequest = (chunks) =>
-  new Request('http://localhost', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: new ReadableStream({
-      start(controller) {
-        for (const chunk of chunks) {
-          controller.enqueue(new TextEncoder().encode(chunk))
-        }
-        controller.close()
-      },
-    }),
-    duplex: 'half',
-  })
-
-test('arrayBuffer() rejects a body larger than the configured limit', async () => {
-  const req = new Request('http://localhost', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/octet-stream' },
-    body: 'x'.repeat(64),
-  })
-  const pikkuReq = new PikkuFetchHTTPRequest(req, { maxBodySize: 16 })
-  await assert.rejects(async () => await pikkuReq.arrayBuffer(), {
-    name: 'PayloadTooLargeError',
-  })
-})
-
-test('arrayBuffer() rejects an oversized body with no content-length header', async () => {
-  const req = streamedRequest(['x'.repeat(32), 'y'.repeat(32)])
-  assert.equal(req.headers.get('content-length'), null)
-  const pikkuReq = new PikkuFetchHTTPRequest(req, { maxBodySize: 16 })
-  await assert.rejects(async () => await pikkuReq.arrayBuffer(), {
-    name: 'PayloadTooLargeError',
-  })
-})
-
-test('arrayBuffer() rejects a body whose content-length under-reports its size', async () => {
-  const req = new Request('http://localhost', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Content-Length': '4',
-    },
-    body: new ReadableStream({
-      start(controller) {
-        controller.enqueue(new TextEncoder().encode('z'.repeat(128)))
-        controller.close()
-      },
-    }),
-    duplex: 'half',
-  })
-  const pikkuReq = new PikkuFetchHTTPRequest(req, { maxBodySize: 16 })
-  await assert.rejects(async () => await pikkuReq.arrayBuffer(), {
-    name: 'PayloadTooLargeError',
-  })
-})
-
-test('data() surfaces PayloadTooLargeError rather than wrapping it', async () => {
-  const req = createRequest(
-    'POST',
-    'http://localhost',
-    { padding: 'x'.repeat(256) },
-    { 'Content-Type': 'application/json' }
-  )
-  const pikkuReq = new PikkuFetchHTTPRequest(req, { maxBodySize: 16 })
-  await assert.rejects(async () => await pikkuReq.data(), {
-    name: 'PayloadTooLargeError',
-  })
-})
-
-test('data() accepts a body within the configured limit', async () => {
-  const req = createRequest(
-    'POST',
-    'http://localhost',
-    { ok: true },
-    { 'Content-Type': 'application/json' }
-  )
-  const pikkuReq = new PikkuFetchHTTPRequest(req, { maxBodySize: 1024 })
-  assert.deepEqual(await pikkuReq.data(), { ok: true })
-})
-
-test('data() accepts a streamed body within the default limit', async () => {
-  const req = streamedRequest(['{"ok"', ':true}'])
-  const pikkuReq = new PikkuFetchHTTPRequest(req)
-  assert.deepEqual(await pikkuReq.data(), { ok: true })
-})
-
-test('data() works when only body has values', async () => {
-  const req = createRequest(
-    'POST',
-    'http://localhost',
-    { test: 'ok' },
-    {
-      'Content-Type': 'application/json',
-    }
-  )
-
-  const r = new PikkuFetchHTTPRequest(req)
-  const result = await r.data()
-  assert.deepEqual(result, { test: 'ok' })
-})