@pikku/core 0.7.0 → 0.7.1

package/src/http/http.types.ts

@@ -0,0 +1,250 @@
+import type { SerializeOptions } from 'cookie'
+import type { PikkuError } from '../errors/error-handler.js'
+import type {
+  APIDocs,
+  CoreServices,
+  CoreSingletonServices,
+  CoreUserSession,
+  CreateSessionServices,
+  PikkuMiddleware,
+} from '../types/core.types.js'
+import type {
+  CoreAPIFunction,
+  CoreAPIFunctionSessionless,
+  CoreAPIPermission,
+  CorePermissionGroup,
+} from '../function/functions.types.js'
+
+type ExtractRouteParams<S extends string> =
+  S extends `${string}:${infer Param}/${infer Rest}`
+    ? Param | ExtractRouteParams<`/${Rest}`>
+    : S extends `${string}:${infer Param}`
+      ? Param
+      : never
+
+export type AssertRouteParams<In, Route extends string> =
+  ExtractRouteParams<Route> extends keyof In
+    ? unknown
+    : ['Error: Route parameters', ExtractRouteParams<Route>, 'not in', keyof In]
+
+export type RunRouteOptions = Partial<{
+  skipUserSession: boolean
+  respondWith404: boolean
+  logWarningsForStatusCodes: number[]
+  coerceDataFromSchema: boolean
+  bubbleErrors: boolean
+  generateRequestId: () => string
+}>
+
+export type RunRouteParams = {
+  singletonServices: CoreSingletonServices
+  createSessionServices: CreateSessionServices<
+    CoreSingletonServices,
+    CoreServices<CoreSingletonServices>,
+    CoreUserSession
+  >
+}
+
+/**
+ * Represents the HTTP methods supported for API routes.
+ */
+export type HTTPMethod =
+  | 'post'
+  | 'get'
+  | 'delete'
+  | 'patch'
+  | 'head'
+  | 'put'
+  | 'options'
+
+/**
+ * Represents an API route without a function, including metadata such as content type, route, and timeout settings.
+ */
+export type CoreHTTPFunction = {
+  contentType?: 'xml' | 'json'
+  route: string
+  eventChannel?: false
+  returnsJSON?: false
+  timeout?: number
+  docs?: Partial<{
+    description: string
+    response: string
+    errors: Array<typeof PikkuError>
+    tags: string[]
+  }>
+}
+/**
+ * Represents a http interaction within Pikku, including a request and response.
+ */
+export interface PikkuHTTP {
+  request?: PikkuHTTPRequest
+  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 route, 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 APIFunction - The API function type, defaults to `CoreAPIFunction`.
+ * @template APIFunctionSessionless - The sessionless API function type, defaults to `CoreAPIFunctionSessionless`.
+ * @template APIPermission - The permission function type, defaults to `CoreAPIPermission`.
+ */
+export type CoreHTTPFunctionRoute<
+  In,
+  Out,
+  R extends string,
+  APIFunction = CoreAPIFunction<In, Out>,
+  APIFunctionSessionless = CoreAPIFunctionSessionless<In, Out>,
+  APIPermission = CoreAPIPermission<In>,
+  APIMiddleware = PikkuMiddleware,
+> =
+  | (CoreHTTPFunction & {
+      route: R
+      method: HTTPMethod
+      func: APIFunction
+      permissions?: CorePermissionGroup<APIPermission>
+      auth?: true
+      tags?: string[]
+      middleware?: APIMiddleware[]
+      sse?: undefined
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: HTTPMethod
+      func: APIFunctionSessionless
+      permissions?: undefined
+      auth?: false
+      tags?: string[]
+      middleware?: APIMiddleware[]
+      sse?: undefined
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: 'get'
+      func: APIFunction
+      permissions?: CorePermissionGroup<APIPermission>
+      auth?: true
+      sse?: boolean
+      tags?: string[]
+      middleware?: APIMiddleware[]
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: 'get'
+      func: APIFunctionSessionless
+      permissions?: undefined
+      auth?: false
+      sse?: boolean
+      tags?: string[]
+      middleware?: APIMiddleware[]
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: 'post'
+      func: APIFunction
+      permissions?: CorePermissionGroup<APIPermission>
+      auth?: true
+      query?: Array<keyof In>
+      tags?: string[]
+      middleware?: APIMiddleware[]
+      sse?: undefined
+    })
+  | (CoreHTTPFunction & {
+      route: R
+      method: 'post'
+      func: APIFunctionSessionless
+      permissions?: undefined
+      auth?: false
+      query?: Array<keyof In>
+      tags?: string[]
+      middleware?: APIMiddleware[]
+      sse?: undefined
+    })
+
+/**
+ * Represents the input types for route metadata, including parameters, query, and body types.
+ */
+export type HTTPFunctionMetaInputTypes = {
+  params?: string
+  query?: string
+  body?: string
+}
+
+/**
+ * Represents metadata for a set of routes, including route details, methods, input/output types, and documentation.
+ */
+export type HTTPRouteMeta = {
+  pikkuFuncName: string
+  route: string
+  method: HTTPMethod
+  params?: string[]
+  query?: string[]
+  input: string | null
+  output: string | null
+  inputTypes?: HTTPFunctionMetaInputTypes
+  docs?: APIDocs
+  tags?: string[]
+  sse?: true
+}
+export type HTTPRoutesMeta = Array<HTTPRouteMeta>
+
+export type HTTPFunctionsMeta = Array<{
+  name: string
+  inputs: string[] | null
+  outputs: string[] | null
+}>
+
+export type HTTPRouteMiddleware = {
+  route: string
+  middleware: PikkuMiddleware[]
+}
+
+export interface PikkuHTTPRequest<In = unknown> {
+  method(): HTTPMethod
+  path(): string
+  data(): Promise<In>
+  json(): Promise<unknown>
+  arrayBuffer(): Promise<ArrayBuffer>
+  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 {
+  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: unknown): this
+  redirect(location: string, status?: number): this
+  close?: () => void
+  setMode?: (mode: 'stream') => void
+}

package/src/http/index.ts

@@ -0,0 +1,8 @@
+export * from './pikku-fetch-http-request.js'
+export * from './pikku-fetch-http-response.js'
+export * from './incomingmessage-to-request-convertor.js'
+export * from './log-http-routes.js'
+
+export { fetch, fetchData, addHTTPRoute } from './http-runner.js'
+
+export type * from './http.types.js'

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

@@ -0,0 +1,22 @@
+import { pikkuState } from '../pikku-state.js'
+import { 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('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/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' })
+})

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

@@ -0,0 +1,163 @@
+import { parse as parseQuery } from 'picoquery'
+import { parse as parseCookie } from 'cookie'
+import { HTTPMethod, PikkuHTTPRequest, PikkuQuery } from './http.types.js'
+import { UnprocessableContentError } from '../errors/errors.js'
+
+/**
+ * Abstract class representing a pikku request.
+ * @template In - The type of the request body.
+ * @group RequestResponse
+ */
+export class PikkuFetchHTTPRequest<In = unknown>
+  implements PikkuHTTPRequest<In>
+{
+  #cookies: Partial<Record<string, string>> | undefined
+  #params: Partial<Record<string, string | string[]>> = {}
+  #url: URL
+
+  constructor(private request: Request) {
+    this.#url = new URL(request.url)
+  }
+
+  public method(): HTTPMethod {
+    return this.request.method.toLowerCase() as HTTPMethod
+  }
+
+  public path(): string {
+    return this.#url.pathname
+  }
+
+  /**
+   * Retrieves the request body.
+   * @returns A promise that resolves to the request body.
+   */
+  public json(): Promise<In> {
+    return this.request.json()
+  }
+
+  /**
+   * Retrieves the raw request body as a Buffer.
+   * @returns A promise that resolves to the raw request body.
+   */
+  public arrayBuffer(): Promise<ArrayBuffer> {
+    return this.request.arrayBuffer()
+  }
+
+  /**
+   * 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 {
+    const cookieHeader = this.header('cookie')
+    this.#cookies = cookieHeader ? parseCookie(cookieHeader) : {}
+    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]
+    const merged: Record<string, unknown> = {}
+    for (const part of parts) {
+      for (const [key, value] of Object.entries(part)) {
+        if (key in merged && !valuesAreEquivalent(merged[key], value)) {
+          throw new UnprocessableContentError(
+            `Conflicting values for key "${key}": "${merged[key]}" vs "${value}"`
+          )
+        }
+        merged[key] ??= value
+      }
+    }
+    return merged as In
+  }
+
+  private async body(): Promise<any> {
+    const noBodyMethods: HTTPMethod[] = ['get', 'head', 'options']
+    if (noBodyMethods.includes(this.method())) {
+      return {}
+    }
+
+    let body: any = {}
+    const contentType = this.header('content-type') || ''
+    try {
+      if (contentType.includes('application/json')) {
+        const parsed = await this.json()
+        body =
+          typeof parsed === 'object' &&
+          parsed !== null &&
+          !Array.isArray(parsed)
+            ? parsed
+            : { data: parsed }
+      } else if (contentType.includes('text/')) {
+        const text = await this.request.text()
+        body = { data: text }
+      } else if (contentType.includes('application/octet-stream')) {
+        const buffer = await this.request.arrayBuffer()
+        body = { data: buffer }
+      } else if (contentType === 'application/x-www-form-urlencoded') {
+        const text = await this.request.text()
+        body = Object.fromEntries(new URLSearchParams(text))
+      } else {
+        throw new UnprocessableContentError(
+          `Unsupported content type ${contentType}`
+        )
+      }
+    } catch (e) {
+      throw new UnprocessableContentError(`Error parsing body: ${e}`)
+    }
+    return body
+  }
+}
+
+function valuesAreEquivalent(a: unknown, b: unknown): boolean {
+  return coerce(a) === coerce(b)
+}
+
+function coerce(value: unknown): string | number | boolean {
+  if (typeof value === 'boolean' || typeof value === 'number') return value
+  if (typeof value === 'string') {
+    if (value === 'true') return true
+    if (value === 'false') return false
+    const num = Number(value)
+    return isNaN(num) ? value : num
+  }
+  return value as any
+}