@mpen/routekit 0.1.0 → 0.1.1

package/src/router/request.ts

@@ -1,611 +0,0 @@
-import { CommonHeaders, HttpStatus, StatusText } from '@mpen/http'
-import type { ContentType, MaybePromise } from './types'
-import { mediaRangeAccepts, mediaRangeQuality, parseContentType } from './lib/media-type'
-
-/**
- * Request body stream exposed by Routekit request bodies.
- *
- * @example
- * ```ts
- * const stream = request.body.stream()
- * ```
- */
-export type RequestBodyStream = ReadableStream<Uint8Array<ArrayBufferLike>> | null
-
-/**
- * FormData type returned by the active Fetch runtime.
- *
- * @example
- * ```ts
- * const form: RequestBodyFormData = await request.body.formData()
- * ```
- */
-export type RequestBodyFormData = Awaited<ReturnType<Response['formData']>>
-
-/**
- * Error thrown when Routekit cannot read or parse a request body.
- *
- * @example
- * ```ts
- * throw new RequestBodyError('Unsupported body', HttpStatus.UNSUPPORTED_MEDIA_TYPE)
- * ```
- */
-export class RequestBodyError extends Error {
-    /**
-     * HTTP status code that should be returned for this request body failure.
-     */
-    readonly status: HttpStatus
-
-    /**
-     * Create a request body error.
-     *
-     * @param message - Error message.
-     * @param status - HTTP status code for the failure.
-     */
-    constructor(message: string, status: HttpStatus) {
-        super(message)
-        this.name = 'RequestBodyError'
-        this.status = status
-    }
-}
-
-/**
- * Error thrown when no registered parser accepts the request `Content-Type`.
- *
- * @example
- * ```ts
- * throw new UnsupportedRequestBodyMediaTypeError('image/png')
- * ```
- */
-export class UnsupportedRequestBodyMediaTypeError extends RequestBodyError {
-    /**
-     * Incoming `Content-Type` value that was rejected.
-     */
-    readonly contentType: string | null
-
-    /**
-     * Create an unsupported media type error.
-     *
-     * @param contentType - Incoming content type, when present.
-     */
-    constructor(contentType: string | null) {
-        super(
-            contentType
-                ? `Unsupported request body media type: ${contentType}`
-                : 'Request body is missing Content-Type.',
-            HttpStatus.UNSUPPORTED_MEDIA_TYPE,
-        )
-        this.name = 'UnsupportedRequestBodyMediaTypeError'
-        this.contentType = contentType
-    }
-}
-
-/**
- * Error thrown when a request body exceeds a configured byte limit.
- *
- * @example
- * ```ts
- * throw new RequestBodyTooLargeError(1024, 2048)
- * ```
- */
-export class RequestBodyTooLargeError extends RequestBodyError {
-    /**
-     * Maximum allowed body size in bytes.
-     */
-    readonly maxSize: number
-    /**
-     * Number of bytes received before the limit failed.
-     */
-    readonly received: number
-
-    /**
-     * Create a body-too-large error.
-     *
-     * @param maxSize - Maximum allowed body size in bytes.
-     * @param received - Number of bytes received.
-     */
-    constructor(maxSize: number, received: number) {
-        super(`Payload exceeded ${maxSize} bytes`, HttpStatus.PAYLOAD_TOO_LARGE)
-        this.name = 'RequestBodyTooLargeError'
-        this.maxSize = maxSize
-        this.received = received
-    }
-}
-
-/**
- * Error thrown when `Content-Length` does not match the streamed body size.
- *
- * @example
- * ```ts
- * throw new RequestBodyLengthMismatchError(4, 3)
- * ```
- */
-export class RequestBodyLengthMismatchError extends RequestBodyError {
-    /**
-     * Expected byte count from `Content-Length`.
-     */
-    readonly expected: number
-    /**
-     * Actual byte count read from the stream.
-     */
-    readonly received: number
-
-    /**
-     * Create a content-length mismatch error.
-     *
-     * @param expected - Expected byte count.
-     * @param received - Actual byte count.
-     */
-    constructor(expected: number, received: number) {
-        super(
-            `Content-Length ${expected} bytes did not match ${received} bytes`,
-            HttpStatus.BAD_REQUEST,
-        )
-        this.name = 'RequestBodyLengthMismatchError'
-        this.expected = expected
-        this.received = received
-    }
-}
-
-/**
- * Body reader context passed to request body parsers.
- *
- * @example
- * ```ts
- * const parser = {
- *     mediaTypes: ['text/plain'],
- *     parse: (ctx: RequestBodyParseContext) => ctx.text(),
- * }
- * ```
- */
-export interface RequestBodyParseContext {
-    /**
-     * Parsed request `Content-Type`, when present and valid.
-     */
-    readonly contentType: ContentType | null
-    /**
-     * Request headers.
-     */
-    readonly headers: Headers
-    /**
-     * Return the current body stream.
-     *
-     * @returns Body stream, or `null` when the request has no body.
-     */
-    stream(): RequestBodyStream
-    /**
-     * Read the body as UTF-8 text.
-     *
-     * @returns Body text.
-     */
-    text(): Promise<string>
-    /**
-     * Read the body as raw bytes.
-     *
-     * @returns Body bytes.
-     */
-    arrayBuffer(): Promise<ArrayBuffer>
-    /**
-     * Read the body as form data.
-     *
-     * @returns Parsed form data.
-     */
-    formData(): Promise<RequestBodyFormData>
-}
-
-/**
- * Parser used by [`RoutekitRequestBody.parse`]{@link RoutekitRequestBody#parse}.
- *
- * @example
- * ```ts
- * const jsonParser: RequestBodyParser = {
- *     mediaTypes: ['application/json'],
- *     parse: async ctx => JSON.parse(await ctx.text()),
- * }
- * ```
- */
-export interface RequestBodyParser<T = unknown> {
-    /**
-     * Media ranges this parser can consume. Entries may include an Accept-style
-     * `q` parameter to prefer more specific parsers over broader media ranges.
-     */
-    readonly mediaTypes: readonly string[]
-    /**
-     * Return `true` when this parser should handle the content type.
-     *
-     * @param contentType - Parsed request content type.
-     * @returns Whether this parser can parse the request body.
-     */
-    canParse?(contentType: ContentType | null): boolean
-    /**
-     * Parse the request body.
-     *
-     * @param ctx - Lazy body reader context.
-     * @returns Parsed request body.
-     */
-    parse(ctx: RequestBodyParseContext): MaybePromise<T>
-}
-
-/**
- * Lazy request body reader exposed to handlers and middleware.
- *
- * @example
- * ```ts
- * const body = await request.body.parse()
- * ```
- */
-export interface RoutekitRequestBody {
-    /**
-     * Parsed request `Content-Type`, when present and valid.
-     */
-    readonly contentType: ContentType | null
-    /**
-     * Return the current body stream.
-     *
-     * @returns Body stream, or `null` when the request has no body.
-     */
-    stream(): RequestBodyStream
-    /**
-     * Return a body wrapper that reads from another stream.
-     *
-     * @param stream - Replacement body stream.
-     * @returns Request body wrapper using the replacement stream.
-     */
-    withStream(stream: RequestBodyStream): RoutekitRequestBody
-    /**
-     * Parse the body with the first matching registered body parser.
-     *
-     * @returns Parsed request body.
-     * @typeParam T - Expected parsed body type.
-     */
-    parse<T = unknown>(): Promise<T>
-    /**
-     * Read the body as JSON.
-     *
-     * @returns Parsed JSON body.
-     * @typeParam T - Expected JSON body type.
-     */
-    json<T = unknown>(): Promise<T>
-    /**
-     * Read the body as UTF-8 text.
-     *
-     * @returns Body text.
-     */
-    text(): Promise<string>
-    /**
-     * Read the body as raw bytes.
-     *
-     * @returns Body bytes.
-     */
-    arrayBuffer(): Promise<ArrayBuffer>
-    /**
-     * Read the body as form data.
-     *
-     * @returns Parsed form data.
-     */
-    formData(): Promise<RequestBodyFormData>
-}
-
-/**
- * Routekit request wrapper exposed to handlers and middleware.
- *
- * @example
- * ```ts
- * const method = request.method
- * const body = await request.body.parse()
- * ```
- */
-export interface RoutekitRequest {
-    /**
-     * Native Fetch request for low-level escape hatches.
-     */
-    readonly raw: Request
-    /**
-     * Parsed request URL.
-     */
-    readonly url: URL
-    /**
-     * Request method.
-     */
-    readonly method: string
-    /**
-     * Request headers.
-     */
-    readonly headers: Headers
-    /**
-     * Request abort signal.
-     */
-    readonly signal: AbortSignal
-    /**
-     * Lazy request body reader.
-     */
-    readonly body: RoutekitRequestBody
-    /**
-     * Return a request wrapper with another body reader.
-     *
-     * @param body - Replacement body reader.
-     * @returns Request wrapper using the replacement body reader.
-     */
-    withBody(body: RoutekitRequestBody): RoutekitRequest
-}
-
-type RequestBodyOptions = {
-    raw: Request
-    headers: Headers
-    stream: RequestBodyStream
-    parsers: readonly RequestBodyParser[]
-}
-
-class DefaultRoutekitRequestBody implements RoutekitRequestBody {
-    readonly contentType: ContentType | null
-
-    readonly #raw: Request
-    readonly #headers: Headers
-    readonly #stream: RequestBodyStream
-    readonly #parsers: readonly RequestBodyParser[]
-    #arrayBufferPromise: Promise<ArrayBuffer> | undefined
-    #textPromise: Promise<string> | undefined
-    #formDataPromise: Promise<RequestBodyFormData> | undefined
-    #parsePromise: Promise<unknown> | undefined
-
-    constructor(options: RequestBodyOptions) {
-        this.#raw = options.raw
-        this.#headers = options.headers
-        this.#stream = options.stream
-        this.#parsers = options.parsers
-        this.contentType = parseContentType(options.headers.get(CommonHeaders.CONTENT_TYPE))
-    }
-
-    get headers(): Headers {
-        return this.#headers
-    }
-
-    stream(): RequestBodyStream {
-        return this.#stream
-    }
-
-    withStream(stream: RequestBodyStream): RoutekitRequestBody {
-        return new DefaultRoutekitRequestBody({
-            raw: this.#raw,
-            headers: this.#headers,
-            stream,
-            parsers: this.#parsers,
-        })
-    }
-
-    async parse<T = unknown>(): Promise<T> {
-        if (!this.#stream) return undefined as T
-        this.#parsePromise ??= this.#parse()
-        return (await this.#parsePromise) as T
-    }
-
-    async json<T = unknown>(): Promise<T> {
-        return JSON.parse(await this.text()) as T
-    }
-
-    text(): Promise<string> {
-        this.#textPromise ??= this.arrayBuffer().then((buffer) => new TextDecoder().decode(buffer))
-        return this.#textPromise
-    }
-
-    arrayBuffer(): Promise<ArrayBuffer> {
-        this.#arrayBufferPromise ??= new Response(this.#stream).arrayBuffer()
-        return this.#arrayBufferPromise
-    }
-
-    formData(): Promise<RequestBodyFormData> {
-        return (this.#formDataPromise ??= new Response(this.#stream, {
-            headers: this.#headers,
-        }).formData())
-    }
-
-    async #parse(): Promise<unknown> {
-        const parser = this.#selectParser()
-        if (!parser) {
-            throw new UnsupportedRequestBodyMediaTypeError(
-                this.#headers.get(CommonHeaders.CONTENT_TYPE),
-            )
-        }
-        try {
-            return await parser.parse(this)
-        } catch (error) {
-            if (error instanceof RequestBodyError) throw error
-            const message = error instanceof Error ? error.message : String(error)
-            throw new RequestBodyError(message, HttpStatus.BAD_REQUEST)
-        }
-    }
-
-    #parserQuality(parser: RequestBodyParser): number | null {
-        let bestQuality = parser.canParse?.(this.contentType) ? 1 : 0
-        if (this.contentType) {
-            for (const mediaType of parser.mediaTypes) {
-                if (mediaRangeAccepts(mediaType, this.contentType)) {
-                    bestQuality = Math.max(bestQuality, mediaRangeQuality(mediaType))
-                }
-            }
-        }
-        return bestQuality > 0 ? bestQuality : null
-    }
-
-    #selectParser(): RequestBodyParser | null {
-        let best: { parser: RequestBodyParser; quality: number } | null = null
-        for (const parser of this.#parsers) {
-            const quality = this.#parserQuality(parser)
-            if (quality == null) continue
-            if (!best || quality > best.quality) {
-                best = { parser, quality }
-            }
-        }
-        return best?.parser ?? null
-    }
-}
-
-class DefaultRoutekitRequest implements RoutekitRequest {
-    readonly raw: Request
-    readonly url: URL
-    readonly method: string
-    readonly headers: Headers
-    readonly signal: AbortSignal
-    readonly body: RoutekitRequestBody
-
-    constructor(raw: Request, url: URL, body: RoutekitRequestBody) {
-        this.raw = raw
-        this.url = url
-        this.method = raw.method
-        this.headers = raw.headers
-        this.signal = raw.signal
-        this.body = body
-    }
-
-    withBody(body: RoutekitRequestBody): RoutekitRequest {
-        return new DefaultRoutekitRequest(this.raw, this.url, body)
-    }
-}
-
-function readParams(searchParams: URLSearchParams): Record<string, string | string[]> {
-    const query: Record<string, string | string[]> = {}
-    for (const [key, value] of searchParams.entries()) {
-        const existing = query[key]
-        if (existing === undefined) {
-            query[key] = value
-            continue
-        }
-        if (Array.isArray(existing)) {
-            existing.push(value)
-        } else {
-            query[key] = [existing, value]
-        }
-    }
-    return query
-}
-
-/**
- * Create the default JSON request body parser.
- *
- * @example
- * ```ts
- * const router = new Router().setRequestBodyParsers([jsonRequestBodyParser()])
- * ```
- *
- * @returns Parser for `application/json` and `application/*+json` request bodies.
- */
-export function jsonRequestBodyParser(): RequestBodyParser<unknown> {
-    return {
-        mediaTypes: ['application/json', 'application/*+json;q=0.5'],
-        parse: async (ctx) => JSON.parse(await ctx.text()),
-    }
-}
-
-/**
- * Create the default text request body parser.
- *
- * @example
- * ```ts
- * const router = new Router().setRequestBodyParsers([textRequestBodyParser()])
- * ```
- *
- * @returns Parser for `text/*` request bodies.
- */
-export function textRequestBodyParser(): RequestBodyParser<string> {
-    return {
-        mediaTypes: ['text/*'],
-        parse: (ctx) => ctx.text(),
-    }
-}
-
-/**
- * Create the default URL-encoded form request body parser.
- *
- * @example
- * ```ts
- * const router = new Router().setRequestBodyParsers([urlEncodedRequestBodyParser()])
- * ```
- *
- * @returns Parser for `application/x-www-form-urlencoded` request bodies.
- */
-export function urlEncodedRequestBodyParser(): RequestBodyParser<
-    Record<string, string | string[]>
-> {
-    return {
-        mediaTypes: ['application/x-www-form-urlencoded'],
-        parse: async (ctx) => readParams(new URLSearchParams(await ctx.text())),
-    }
-}
-
-/**
- * Create the default multipart form request body parser.
- *
- * @example
- * ```ts
- * const router = new Router().setRequestBodyParsers([formDataRequestBodyParser()])
- * ```
- *
- * @returns Parser for `multipart/form-data` request bodies.
- */
-export function formDataRequestBodyParser(): RequestBodyParser<RequestBodyFormData> {
-    return {
-        mediaTypes: ['multipart/form-data'],
-        parse: (ctx) => ctx.formData(),
-    }
-}
-
-/**
- * Create the default Routekit request body parser list.
- *
- * @example
- * ```ts
- * const parsers = defaultRequestBodyParsers()
- * ```
- *
- * @returns Default parser list.
- */
-export function defaultRequestBodyParsers(): RequestBodyParser[] {
-    return [
-        jsonRequestBodyParser(),
-        textRequestBodyParser(),
-        urlEncodedRequestBodyParser(),
-        formDataRequestBodyParser(),
-    ]
-}
-
-/**
- * Create a Routekit request wrapper for a native Fetch request.
- *
- * @example
- * ```ts
- * const request = createRoutekitRequest(new Request('https://example.com'), new URL('https://example.com'), defaultRequestBodyParsers())
- * ```
- *
- * @param raw - Native Fetch request.
- * @param url - Parsed request URL.
- * @param parsers - Request body parsers.
- * @returns Routekit request wrapper.
- */
-export function createRoutekitRequest(
-    raw: Request,
-    url: URL,
-    parsers: readonly RequestBodyParser[],
-): RoutekitRequest {
-    const body = new DefaultRoutekitRequestBody({
-        raw,
-        headers: raw.headers,
-        stream: raw.body,
-        parsers,
-    })
-    return new DefaultRoutekitRequest(raw, url, body)
-}
-
-/**
- * Create a plain response for a request body error.
- *
- * @example
- * ```ts
- * const response = responseFromRequestBodyError(error)
- * ```
- *
- * @param error - Request body error to convert.
- * @returns HTTP response for the body error.
- */
-export function responseFromRequestBodyError(error: RequestBodyError): Response {
-    return new Response(StatusText[error.status] ?? error.message, { status: error.status })
-}