@pikku/core 0.12.4 → 0.12.5

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

@@ -0,0 +1,369 @@
+import type { SerializeOptions } from 'cookie'
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type {
+  CorePikkuMiddleware,
+  CommonWireMeta,
+} from '../../types/core.types.js'
+import type {
+  CorePikkuFunction,
+  CorePikkuFunctionSessionless,
+  CorePikkuPermission,
+  CorePermissionGroup,
+  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
+}>
+
+/**
+ * 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>,
+> =
+  | (CoreHTTPFunction & {
+      route: R
+      method: HTTPMethod
+      func: CorePikkuFunctionConfig<
+        PikkuFunction,
+        PikkuPermission,
+        PikkuMiddleware
+      >
+      permissions?: CorePermissionGroup<PikkuPermission>
+      auth?: true
+      middleware?: PikkuMiddleware[]
+      sse?: undefined
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: HTTPMethod
+      func: CorePikkuFunctionConfig<
+        PikkuFunctionSessionless,
+        PikkuPermission,
+        PikkuMiddleware
+      >
+      permissions?: undefined
+      auth?: false
+      middleware?: PikkuMiddleware[]
+      sse?: undefined
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: 'get'
+      func: CorePikkuFunctionConfig<
+        PikkuFunction,
+        PikkuPermission,
+        PikkuMiddleware
+      >
+      permissions?: CorePermissionGroup<PikkuPermission>
+      auth?: true
+      middleware?: PikkuMiddleware[]
+      sse?: boolean
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: 'get'
+      func: CorePikkuFunctionConfig<
+        PikkuFunctionSessionless,
+        PikkuPermission,
+        PikkuMiddleware
+      >
+      permissions?: undefined
+      auth?: false
+      middleware?: PikkuMiddleware[]
+      sse?: boolean
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: 'post'
+      func: CorePikkuFunctionConfig<
+        PikkuFunction,
+        PikkuPermission,
+        PikkuMiddleware
+      >
+      permissions?: CorePermissionGroup<PikkuPermission>
+      auth?: true
+      middleware?: PikkuMiddleware[]
+      query?: Array<keyof In>
+      sse?: undefined
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: 'post'
+      func: CorePikkuFunctionConfig<
+        PikkuFunctionSessionless,
+        PikkuPermission,
+        PikkuMiddleware
+      >
+      permissions?: undefined
+      auth?: false
+      middleware?: PikkuMiddleware[]
+      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
+  params?: string[]
+  query?: string[]
+  inputTypes?: HTTPFunctionMetaInputTypes
+  headersSchemaName?: string
+  sse?: true
+  groupBasePath?: string
+}
+export type HTTPWiringsMeta = Record<HTTPMethod, Record<string, HTTPWiringMeta>>
+
+export type HTTPFunctionsMeta = Array<{
+  name: string
+  inputs: string[] | null
+  outputs: string[] | null
+}>
+
+export type HTTPWiringMiddleware = {
+  route: string
+  middleware: CorePikkuMiddleware[]
+}
+
+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> {
+  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
+  send?(data: string | ArrayBuffer | Buffer): this
+  redirect(location: string, status?: number): this
+  close?: () => void
+  setMode?: (mode: 'stream') => 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>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+> = HTTPRouteBaseConfig & {
+  // Required
+  method: HTTPMethod
+  route: string
+  func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>
+
+  // Auth & permissions
+  auth?: boolean
+  permissions?: CorePermissionGroup<PikkuPermission>
+
+  // 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>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+> = {
+  basePath?: string
+  tags?: string[]
+  auth?: boolean
+  middleware?: PikkuMiddleware[]
+  permissions?: CorePermissionGroup<PikkuPermission>
+}
+
+/**
+ * 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/index.ts

@@ -0,0 +1,28 @@
+export { PikkuFetchHTTPRequest } 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,
+  addHTTPPermission,
+} from './http-runner.js'
+
+export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js'
+export { toWebRequest, applyWebResponse } from './web-request.js'
+
+export type {
+  AssertHTTPWiringParams,
+  CoreHTTPFunctionWiring,
+  HTTPMethod,
+  HTTPRouteBaseConfig,
+  HTTPRouteContract,
+  HTTPRouteMap,
+  HTTPWiringsMeta,
+  PikkuHTTPRequest,
+  PikkuHTTPResponse,
+  PikkuQuery,
+  RunHTTPWiringOptions,
+} from './http.types.js'

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

@@ -0,0 +1,22 @@
+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) {
+    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

@@ -0,0 +1,237 @@
+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',
+  })
+})
+
+// --- Compatible types
+
+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' }) // All match
+  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' }) // All match
+  const result = await r.data()
+  assert.deepEqual(result, { flag: 'true' })
+})
+
+// --- Conflicts
+
+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"',
+  })
+})
+
+// --- Safe fallback: only one source
+
+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' })
+})