/// <reference lib="es2022" />
/// <reference path="hatsy.core.d.ts" />
declare module "@hatsy/hatsy" {
    import type { DueLog, Loggable } from "@proc7ts/logger";
    /**
     * A error corresponding to the given HTTP status code.
     *
     * HTTP request processing handlers may raise this error. The {@link renderHttpError error handler} would render
     * corresponding error page then.
     *
     * @see HttpConfig.errorHandler
     */
    export class HttpError extends Error implements Loggable {
        #private;
        /**
         * Constructs HTTP status error.
         *
         * @param statusCode - HTTP status code.
         * @param options - HTTP error options.
         */
        constructor(statusCode: number, options?: HttpError.Options);
        /**
         * HTTP status code.
         */
        get statusCode(): number;
        /**
         * HTTP status message.
         */
        get statusMessage(): string | undefined;
        /**
         * Error details.
         *
         * This will be displayed on error page in addition to error code.
         */
        get details(): string | undefined;
        /**
         * Performs additional message processing before it is logged.
         *
         * At output or default logging stage replaces this error with error message, details, and reason. Does nothing at
         * other logging stages.
         *
         * @returns Either new loggable value representation, or nothing outside the output logging stage.
         */
        toLog({ on }: DueLog): unknown[] | void;
    }
    export namespace HttpError {
        /**
         * Options for {@link HttpError HTTP error} construction.
         */
        interface Options extends ErrorOptions {
            /**
             * HTTP status message.
             */
            readonly statusMessage?: string | undefined;
            /**
             * Error message.
             *
             * @default Constructed by status code and status message.
             */
            readonly message?: string | undefined;
            /**
             * Error details.
             *
             * This will be displayed on error page in addition to error code.
             */
            readonly details?: string | undefined;
        }
    }
}

declare module "@hatsy/hatsy" {
    import type { IncomingMessage, ServerResponse } from "node:http";
    /**
     * HTTP request processing means.
     *
     * When passed to HTTP handler the latter responds by utilizing the passed in {@link response}, or delegates to the
     * {@link RequestContext.Agent.next next handler}.
     *
     * @typeParam TRequest - HTTP request type.
     * @typeParam TResponse - HTTP response type.
     */
    export interface HttpMeans<TRequest extends IncomingMessage = IncomingMessage, TResponse extends ServerResponse = ServerResponse> {
        /**
         * HTTP request.
         */
        readonly request: TRequest;
        /**
         * HTTP request addressing info.
         */
        readonly requestAddresses: HttpMeans.Addresses;
        /**
         * HTTP response.
         */
        readonly response: TResponse;
    }
    export namespace HttpMeans {
        /**
         * HTTP request addressing info.
         */
        interface Addresses {
            /**
             * Request URL.
             */
            readonly url: URL;
            /**
             * Remote address.
             */
            readonly ip: string;
        }
    }
}

declare module "@hatsy/hatsy" {
    import type { ServerResponse } from "node:http";
    /**
     * Appends HTTP header value to server response.
     *
     * Avoids value duplication.
     *
     * @param response - HTTP response to add header to.
     * @param name - Target HTTP header name.
     * @param value - HTTP header value to add.
     */
    export function addResponseHeader(response: ServerResponse, name: string, value: string): void;
}

declare module "@hatsy/hatsy" {
    import { RequestHandler, RequestHandlerMethod } from "@hatsy/hatsy/core.js";
    /**
     * Request processing handlers for accepted MIME types.
     *
     * @typeParam TMeans - Supported HTTP request processing means.
     */
    export interface DispatchMimeTypes<TMeans extends HttpMeans = HttpMeans> {
        /**
         * Produces HTML.
         */
        readonly 'text/html'?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Produces JSON.
         */
        readonly 'application/json'?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Produces any content.
         *
         * This is a fallback handler typically.
         */
        readonly '*/*'?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Request processing method with MIME type as its key.
         *
         * MIME can be a wildcard like `image/*` or `* / *`.
         */
        readonly [mimeType: string]: RequestHandlerMethod<this, TMeans> | undefined;
    }
    /**
     * Dispatches request processing by requested MIME type.
     *
     * Performs [content negotiation] based on [Accept] header. Then calls handler based on negotiation results.
     *
     * Appends `Vary: Accept` header to the response.
     *
     * [content negotiation]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation
     * [Accept]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept
     *
     * @param mimeTypes - Request processing handlers for accepted MIME types.
     * @param fallback - Fallback request handler to call when negotiation failed. Issues 406 (Not Acceptable) by default.
     *
     * @returns New HTTP request processing handler.
     */
    export function dispatchByAccepted<TMeans extends HttpMeans>(mimeTypes: DispatchMimeTypes<TMeans>, fallback?: RequestHandler<TMeans>): RequestHandler<TMeans>;
}

declare module "@hatsy/hatsy" {
    import { RequestHandler, RequestHandlerMethod } from "@hatsy/hatsy/core.js";
    /**
     * Request processing handlers for accepted languages.
     *
     * @typeParam TMeans - Supported HTTP request processing means.
     */
    export interface DispatchLanguages<TMeans extends HttpMeans = HttpMeans> {
        /**
         * English response.
         */
        en?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Response in any language.
         *
         * This is a fallback handler typically.
         */
        '*'?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Request processing method with language code as its key.
         *
         * Language code can be a `*` wildcard.
         */
        readonly [code: string]: RequestHandlerMethod<this, TMeans> | undefined;
    }
    /**
     * Dispatches request processing by requested language.
     *
     * Performs [content negotiation] based on [Accept-Language] header. Then calls handler based on negotiation results.
     *
     * Appends `Vary: Accept-Language` header to the response.
     *
     * Issues 406 (Not Acceptable) error if no matching handler found.
     *
     * [content negotiation]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation
     * [Accept-Language]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language
     */
    export function dispatchByLanguage<TMeans extends HttpMeans>(languages: DispatchLanguages<TMeans>): RequestHandler<TMeans>;
}

declare module "@hatsy/hatsy" {
    import { RequestHandler, RequestHandlerMethod } from "@hatsy/hatsy/core.js";
    /**
     * Request processing handlers for HTTP request methods.
     *
     * @typeParam TMeans - Supported HTTP request processing means.
     */
    export interface DispatchMethods<TMeans extends HttpMeans = HttpMeans> {
        /**
         * Request processing handler for HTTP DELETE.
         */
        readonly delete?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Request processing handler for HTTP GET.
         *
         * It is also called for HTTP HEAD requests unless a [head] handler is also defined.
         */
        readonly get?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Request processing handler for HTTP HEAD.
         */
        readonly head?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Request processing handler for HTTP OPTIONS.
         */
        readonly options?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Request processing handler for HTTP PATCH.
         */
        readonly patch?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Request processing handler for HTTP POST.
         */
        readonly post?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Request processing handler for HTTP PUT.
         */
        readonly put?: RequestHandlerMethod<this, TMeans> | undefined;
        /**
         * Request handler method with lower-case HTTP method name as its key.
         */
        readonly [method: string]: RequestHandlerMethod<this, TMeans> | undefined;
    }
    /**
     * Dispatches request processing by HTTP request method.
     *
     * @typeParam TMeans - Supported HTTP route processing means.
     * @param methods - A map of request processing handlers corresponding to HTTP request methods.
     *
     * @returns New HTTP request processing handler.
     */
    export function dispatchByMethod<TMeans extends HttpMeans>(methods: DispatchMethods<TMeans>): RequestHandler<TMeans>;
}

declare module "@hatsy/hatsy" {
    import { ErrorMeans } from "@hatsy/hatsy/core.js";
    import { RequestHandler } from "@hatsy/hatsy/core.js";
    /**
     * HTTP processing configuration.
     *
     * @typeParam TMeans - A type of supported HTTP request processing means.
     */
    export interface HttpConfig<TMeans extends HttpMeans = HttpMeans> {
        /**
         * Default HTTP request handler.
         *
         * This handler will be called after all other handlers when response is not generated.
         *
         * When set to `false` the default response won't be generated.
         *
         * @default `true`, which means a `404 Not Found` error will be raised if there is no response.
         */
        readonly defaultHandler?: RequestHandler<TMeans> | boolean | undefined;
        /**
         * Error processing handler.
         *
         * This handler will be called once request processing error occurred. Such handler would receive
         * a {@link ErrorMeans error processing means} along with {@link HttpMeans HTTP processing ones}.
         *
         * When set to `false` the request processing errors will be logged, but otherwise ignored.
         *
         * @default `true`, which means the request processing error page will be rendered by {@link renderHttpError}
         * handler.
         */
        readonly errorHandler?: RequestHandler<TMeans & ErrorMeans> | boolean | undefined;
        /**
         * Whether to log HTTP processing error.
         *
         * Unhandled errors will be logged with `console.error` in any case.
         *
         * @default `true`, which means an error will be logged with {@link LoggerMeans logger means}, created if necessary.
         */
        readonly logError?: boolean | undefined;
    }
    export namespace HttpConfig {
        /**
         * HTTP processing configuration for extended requests.
         *
         * @typeParam TExt - Request processing means extension type.
         * @typeParam TMeans - A type of supported HTTP request processing means.
         */
        interface Extended<TExt, TMeans extends HttpMeans = HttpMeans> extends HttpConfig<TMeans & TExt> {
            /**
             * Creates actual HTTP request handler.
             *
             * This can be used e.g. to set up additional request processing capabilities, such as {@link Logging}.
             *
             * @param handler - HTTP request handler.
             *
             * @returns HTTP request handler to use instead.
             */
            handleBy(handler: RequestHandler<TMeans & TExt>): RequestHandler<TMeans>;
        }
    }
}

declare module "@hatsy/hatsy" {
    /**
     * HTTP response body render means.
     *
     * It is implied that response body is generated by these means only. I.e. nothing is written to `ServerResponse`
     * directly.
     *
     * All `renderXXX` methods write `Content-Length` header. They skip writing content body when request method is `HEAD`.
     */
    export interface RenderMeans {
        /**
         * Renders response body.
         *
         * @param body - Response body text or Buffer.
         * @param encoding - Response body buffer encoding. Ignored for buffer.
         */
        renderBody(this: void, body: string | Buffer, encoding?: BufferEncoding): void;
        /**
         * Renders HTML response body.
         *
         * Generates content in `UTF-8` encoding and sets `Content-Type: text/html; charset=utf-8` header.
         *
         * @param html - HTML response text or Buffer.
         */
        renderHtml(this: void, html: string | Buffer): void;
        /**
         * Renders JSON response body.
         *
         * Generates content in `UTF-8` encoding and sets `Content-Type: application/json; charset=utf-8` header.
         *
         * @param body - JSON object to stringify.
         */
        renderJson(this: void, body: unknown): void;
    }
}

declare module "@hatsy/hatsy" {
    import { RequestCapability } from "@hatsy/hatsy/core.js";
    /**
     * HTTP response rendering capability.
     *
     * Provides {@link RenderMeans HTTP response body render means} for handlers.
     */
    export const Rendering: RequestCapability<HttpMeans, RenderMeans>;
}

declare module "@hatsy/hatsy" {
    import { ErrorMeans } from "@hatsy/hatsy/core.js";
    import { RequestHandler } from "@hatsy/hatsy/core.js";
    /**
     * HTTP request processing error handler that renders HTML page with error info.
     *
     * Threats {@link HttpError HTTP status error} as HTTP status code to set for error page.
     *
     * Renders either JSON or HTML error page.
     */
    export const renderHttpError: RequestHandler<HttpMeans & ErrorMeans>;
}

declare module "@hatsy/hatsy" {
    import type { IncomingMessage, ServerResponse } from "node:http";
    import { RequestHandler } from "@hatsy/hatsy/core.js";
    /**
     * Creates Node.js HTTP request listener that processes requests by extended HTTP request processing handler.
     *
     * @typeParam TRequest - A type of supported HTTP request.
     * @typeParam TResponse - A type of supported HTTP response.
     * @typeParam TExt - Request processing means extension type.
     * @param config - HTTP processing configuration.
     * @param handler - HTTP request processing handler to delegate to.
     *
     * @returns HTTP request listener to pass to Node.js HTTP server.
     *
     * @see requestHandler
     */
    export function httpListener<TExt, TRequest extends IncomingMessage = IncomingMessage, TResponse extends ServerResponse = ServerResponse>(config: HttpConfig.Extended<TExt, HttpMeans<TRequest, TResponse>>, handler: RequestHandler<HttpMeans<TRequest, TResponse> & TExt>): (this: void, req: TRequest, res: TResponse) => void;
    /**
     * Creates Node.js HTTP request listener that processes requests by HTTP request processing handler.
     *
     * @typeParam TRequest - A type of supported HTTP request.
     * @typeParam TResponse - A type of supported HTTP response.
     * @param config - HTTP processing configuration.
     * @param handler - HTTP request processing handler to delegate to.
     *
     * @returns HTTP request listener to pass to Node.js HTTP server.
     *
     * @see requestHandler
     */
    export function httpListener<TRequest extends IncomingMessage, TResponse extends ServerResponse>(config: HttpConfig<HttpMeans<TRequest, TResponse>>, handler: RequestHandler<HttpMeans<TRequest, TResponse>>): (this: void, req: TRequest, res: TResponse) => void;
    /**
     * Creates Node.js HTTP request listener that processes requests by HTTP request processing handler according to
     * default configuration.
     *
     * @typeParam TRequest - A type of supported HTTP request.
     * @typeParam TResponse - A type of supported HTTP response.
     * @param handler - HTTP request processing handler to delegate to.
     *
     * @returns HTTP request listener to pass to Node.js HTTP server.
     *
     * @see requestHandler
     */
    export function httpListener<TRequest extends IncomingMessage, TResponse extends ServerResponse>(handler: RequestHandler<HttpMeans<TRequest, TResponse>>): (this: void, req: TRequest, res: TResponse) => void;
}

declare module "@hatsy/hatsy" {
    import type { IncomingMessage, ServerResponse } from "node:http";
    import { RequestCapability } from "@hatsy/hatsy/core.js";
    /**
     * HTTP middleware signature.
     *
     * This is a [Connect]-style middleware.
     *
     * [Connect]: https://github.com/senchalabs/connect
     *
     * @typeParam TRequest - Supported HTTP request type.
     * @typeParam TResponse - Supported HTTP response type.
     *
     * @param request - HTTP request.
     * @param response HTTP response.
     * @param next - Next function to delegate request processing to or report error with.
     */
    export type Middleware<TRequest extends IncomingMessage = IncomingMessage, TResponse extends ServerResponse = ServerResponse> = (this: void, request: TRequest, response: TResponse, next: Middleware.Next) => void;
    export namespace Middleware {
        /**
         * A signature of the function the {@link Middleware middleware} may call to delegate request processing
         * or report error with.
         *
         * @param error - Either an error to report, or nothing to delegate request processing to next handler.
         */
        type Next = (this: void, error?: unknown) => void;
    }
    /**
     * Involves the given `middleware` into HTTP request processing.
     *
     * @typeParam TInput - A type of input HTTP request processing means.
     * @param middleware - Middleware to apply.
     *
     * @returns New request processing capability that processes HTTP requests by the given `middleware`.
     */
    export function middleware<TInput extends HttpMeans>(middleware: Middleware<TInput['request'], TInput['response']>): RequestCapability<TInput>;
}

declare module "@hatsy/hatsy" {
    import { URLSearchParams } from "node:url";
    import { RequestBodyMeans } from "@hatsy/hatsy/core.js";
    import { RequestCapability } from "@hatsy/hatsy/core.js";
    import { RequestValueTransformer } from "@hatsy/hatsy/core.js";
    /**
     * URL-encoded form decoding capability.
     *
     * Represents form data submitted as `application/x-www-form-urlencoded` as a {@link RequestBodyMeans.requestBody
     * request body} of type `URLSearchParams`, or optionally transforms it to another type.
     *
     * Responds with 415 (Unsupported Media Type) status code if request has content type specified, and it is not
     * `application/x-www-form-urlencoded` or `text/plain`.
     *
     * @typeParam TInput - Input HTTP request processing means.
     * @typeParam TBody - Request body type.
     */
    export interface FormDecoding<TInput extends HttpMeans = HttpMeans, TBody = URLSearchParams> extends RequestCapability<TInput, RequestBodyMeans<TBody>> {
        /**
         * Configures form decoding capability to transform submitted form.
         *
         * @typeParam TMeans - HTTP request processing means.
         * @typeParam TTransformed - Transformed request body type.
         * @param transformer - Transformer function.
         *
         * @returns New form decoding capability.
         */
        withBody<TMeans extends TInput, TTransformed>(transformer: RequestValueTransformer<TMeans, URLSearchParams, TTransformed>): FormDecoding<TMeans, TTransformed>;
    }
    /**
     * URL-encoded form decoding capability.
     *
     * Represents form data submitted as `application/x-www-form-urlencoded` as a {@link RequestBodyMeans.requestBody
     * request body} of type `URLSearchParams`.
     */
    export const FormDecoding: FormDecoding;
}

declare module "@hatsy/hatsy" {
    import type { HttpForwardTrust } from "http-header-value/headers.js";
    import { RequestCapability } from "@hatsy/hatsy/core.js";
    /**
     * HTTP proxy forwarding capability.
     *
     * Extracts trusted forwarding information from HTTP request and updates {@link HttpMeans.requestAddresses HTTP request
     * addressing info} accordingly.
     *
     * The proxy forwarding information is not trusted by default.
     */
    export interface HttpForwarding extends RequestCapability<HttpMeans> {
        /**
         * Configures trust policy to proxy forwarding records.
         *
         * @param trust - New trust policy to HTTP proxy forwarding records.
         *
         * @returns New HTTP proxy forwarding capability.
         */
        with(trust: HttpForwardTrust): HttpForwarding;
    }
    /**
     * HTTP proxy forwarding capability.
     *
     * Can be used directly, or {@link HttpForwarding.with configured} first.
     */
    export const HttpForwarding: HttpForwarding;
}

declare module "@hatsy/hatsy" {
    import { RequestBodyMeans } from "@hatsy/hatsy/core.js";
    import { RequestCapability } from "@hatsy/hatsy/core.js";
    import { RequestValueTransformer } from "@hatsy/hatsy/core.js";
    /**
     * JSON request body parsing capability.
     *
     * Attempts to parse requested data as JSON, and optionally transforms it to another type.
     *
     * Responds with 415 (Unsupported Media Type) status code if request has content type specified, and it is not
     * `application/json`, `text/json`, or `text/plain`.
     *
     * Responds with 400 (Bad Request) status code if failed to parse JSON.
     *
     * @typeParam TInput - Input HTTP request processing means.
     * @typeParam TBody - Request body type.
     */
    export interface JsonParsing<TInput extends HttpMeans = HttpMeans, TBody = any> extends RequestCapability<TInput, RequestBodyMeans<TBody>> {
        /**
         * Configures JSON parsing capability to transform submitted data.
         *
         * @typeParam TMeans - HTTP request processing means.
         * @typeParam TTransformed - Transformed request body type.
         * @param transformer - Transformer function.
         *
         * @returns New JSON parsing capability.
         */
        withBody<TMeans extends TInput, TTransformed>(transformer: RequestValueTransformer<TMeans, any, TTransformed>): FormDecoding<TMeans, TTransformed>;
    }
    /**
     * JSON request body parsing capability.
     *
     * Parses request body as JSON.
     */
    export const JsonParsing: JsonParsing;
}

declare module "@hatsy/hatsy" {
    /**
     * @module @hatsy/hatsy
     */
    export * from "@hatsy/hatsy/core.js";
}
//# sourceMappingURL=hatsy.d.ts.map