@webda/core 4.0.0-beta.1 → 4.0.0-beta.3

package/lib/services/httpserver.service.d.ts

@@ -0,0 +1,248 @@
+import { Service } from "./service.js";
+import { WebContext } from "../contexts/webcontext.js";
+import { Context, ContextProvider, ContextProviderInfo } from "../contexts/icontext.js";
+import { ServiceParameters } from "../services/serviceparameters.js";
+import { IncomingMessage, Server, ServerResponse } from "node:http";
+import { Http2SecureServer } from "node:http2";
+import type { Http2Server } from "node:http2";
+import { AddressInfo } from "node:net";
+import { CancelablePromise } from "@webda/utils";
+import type { JSONed } from "@webda/models";
+/** Parameters for the HTTP server including request limits, timeouts, TLS, and proxy settings */
+export declare class HttpServerParameters extends ServiceParameters {
+    /**
+     * Will not try to parse request bigger than this
+     *
+     * This parameter can be overriden by a direct call to
+     * getHttpContext().getRawBody(xxx)
+     *
+     * @default 10Mb
+     */
+    requestLimit?: number;
+    /**
+     * Will not take more than this to read a request (unit: milliseconds)
+     *
+     * This parameter can be overriden by a direct call to
+     * getHttpContext().getRawBody(undefined, xxx)
+     *
+     * @default 60000
+     */
+    requestTimeout?: number;
+    /**
+     * Trust this reverse proxies
+     */
+    trustedProxies: string[];
+    /**
+     * Allowed origin for referer that match
+     * any of this regexp
+     *
+     * {@link OriginFilter}
+     */
+    csrfOrigins?: string[];
+    /**
+     * Default headers to send to the client
+     *
+     * Having a Cache-Control: private will prevent caching for API
+     * If you overwrite this parameter, you will need to add it back
+     */
+    defaultHeaders?: {
+        [key: string]: string;
+    };
+    /**
+     * Port to listen on
+     *
+     * @default 18080
+     */
+    port?: number;
+    /**
+     * Run this instance as an HTTP/2 cleartext (h2c) server rather than
+     * HTTP/1.1. The resulting port accepts only prior-knowledge HTTP/2
+     * clients (e.g. `grpcurl -plaintext`). To serve both REST (HTTP/1.1)
+     * and gRPC without TLS, configure a second HttpServer service with
+     * `h2c: true` on a separate port.
+     * @default false
+     */
+    h2c?: boolean;
+    /**
+     * TLS key file path — enables HTTPS or HTTP/2
+     */
+    key?: string;
+    /**
+     * TLS certificate file path
+     */
+    cert?: string;
+    /**
+     * Enable HTTP/2 (default: true when key+cert provided)
+     * Set to false for HTTPS without HTTP/2
+     */
+    http2?: boolean;
+    /**
+     * Auto-generate a self-signed certificate on startup when `key`/`cert`
+     * aren't configured. Dev convenience: gives the main port HTTP/2 via
+     * ALPN (plus HTTP/1.1 fallback) with zero setup. Keys are written under
+     * `.webda/dev-tls/`.
+     *
+     * @default false
+     */
+    autoTls?: boolean;
+    /**
+     * Load parameters with defaults for request limits, timeouts, and proxy configuration
+     * @param params - the service parameters
+     * @returns this for chaining
+     */
+    load(params: Omit<JSONed<HttpServerParameters>, "trustedProxies"> & {
+        trustedProxies?: string | string[];
+    }): this;
+}
+export type HttpServerEvents = {
+    /** Emitted when new result is sent */
+    "Webda.Result": {
+        context: WebContext;
+    };
+    /** Emitted when new request comes in */
+    "Webda.Request": {
+        context: WebContext;
+    };
+    /** Emitted when a request does not match any route */
+    "Webda.404": {
+        context: WebContext;
+    };
+    /** Sent when route is added to context */
+    "Webda.UpdateContextRoute": {
+        context: WebContext;
+    };
+};
+/**
+ * HTTP server service supporting HTTP/1.1, HTTPS, and HTTP/2
+ *
+ * @WebdaModda
+ */
+export declare class HttpServer<P extends HttpServerParameters = HttpServerParameters, E extends HttpServerEvents = HttpServerEvents> extends Service<P, E> {
+    /** Registered context providers */
+    private contextProviders;
+    server: Server | Http2SecureServer | Http2Server;
+    /**
+     * Resolvers of the pending serve() promises, settled when the service stops
+     */
+    protected serving: Set<() => void>;
+    /** In TLS mode, the server answering plain HTTP with a redirect */
+    protected redirectServer?: Server;
+    protected subnetChecker: (address: string) => boolean;
+    /** Whether this server uses HTTP/2 */
+    protected isHttp2: boolean;
+    /**
+     * Extra request handlers — matched first, before the default web request
+     * pipeline. Used to plug in alternate wire protocols (gRPC) that share the
+     * same port. Each interceptor returns true when it handles the request.
+     */
+    private interceptors;
+    /**
+     * Register an additional low-level request handler. Interceptors are
+     * checked in registration order; the first one that returns true short-
+     * circuits the default pipeline. Typical use: gRPC dispatcher that matches
+     * `content-type: application/grpc`.
+     * @param handler - returns true when it has taken ownership of the request
+     */
+    registerRequestInterceptor(handler: (req: IncomingMessage, res: ServerResponse) => boolean): void;
+    /**
+     * Flush response headers from WebContext to the underlying response stream.
+     * Handles both HTTP/1.1 (writeHead) and HTTP/2 (setHeader + statusCode) patterns.
+     *
+     * @param ctx - the web context with stored headers
+     */
+    flushHeaders(ctx: WebContext): void;
+    /**
+     * Flush the response body and close the response.
+     *
+     * @param ctx - the web context with buffered output
+     */
+    flush(ctx: WebContext): void;
+    /**
+     * Handle an incoming HTTP request: create context, route, flush response.
+     *
+     * @param req - the incoming message
+     * @param res - the server response
+     */
+    handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * Serve HTTP until the service stops
+     *
+     * The returned promise stays pending while the server runs: it resolves when the
+     * service stops, and cancelling it closes the server.
+     * Use {@link start} to only wait for the server to listen.
+     *
+     * @param bind - the bind address
+     * @param port - the port number
+     * @returns a promise settled once the server is stopped
+     */
+    serve(bind?: string, port?: number): CancelablePromise<void>;
+    /**
+     * Start the HTTP server
+     * @param bind - the bind address
+     * @param port - the port number
+     * @returns a promise resolved once the server listens
+     */
+    start(bind?: string, port?: number): Promise<void>;
+    /**
+     * Close the HTTP server, dropping its open connections
+     * @returns a promise resolved once the server is closed
+     */
+    protected closeServer(): Promise<void>;
+    /**
+     * Address the server is listening on, or null before it listens
+     * @returns the bound address
+     */
+    address(): string | AddressInfo;
+    /**
+     * Accept plain HTTP on a TLS port. TLS handshakes go to the TLS server as
+     * before; anything else gets a 308 redirect to the same URL over https,
+     * where a browser typing `localhost:<port>` would otherwise get an empty
+     * response.
+     *
+     * Node's TLS server wraps each accepted socket in its single `connection`
+     * listener; that listener is wrapped so the server keeps owning the port
+     * (`listening`, `address()` and the `Webda.Init.Http` hooks are unchanged).
+     * @param tlsServer - the TLS server handling the application
+     */
+    protected redirectPlainHttp(tlsServer: Server | Http2SecureServer): void;
+    /** @override */
+    stop(): Promise<void>;
+    /**
+     * Ensure a self-signed TLS key+cert exists under `.webda/dev-tls/` and
+     * return their paths. Used by {@link HttpServerParameters.autoTls} to bring
+     * up HTTPS/HTTP2 on the dev server with zero setup. Dev-only — real
+     * deploys should supply a proper cert via `key`/`cert` params.
+     *
+     * @returns absolute paths to the generated key and cert files
+     */
+    protected ensureDevTlsCert(): {
+        key: string;
+        cert: string;
+    };
+    /**
+     * Create a WebContext from an HTTP request
+     * @param req - the incoming message
+     * @param res - the server response
+     * @returns the context, or undefined if request should be rejected
+     */
+    getContextFromRequest(req: IncomingMessage, res?: ServerResponse): Promise<Context>;
+    /**
+     * Check if a proxy is a trusted proxy
+     * @param ip - the IP address
+     * @returns true if the proxy is trusted
+     */
+    isProxyTrusted(ip: string): boolean;
+    /**
+     * Create a context from provider info
+     * @param info - the context provider info
+     * @param noInit - skip initialization
+     * @returns the created context
+     */
+    newContext<T extends Context>(info: ContextProviderInfo, noInit?: boolean): Promise<Context>;
+    /**
+     * Register a new context provider (prepended, higher priority)
+     * @param provider - the context provider
+     */
+    registerContextProvider(provider: ContextProvider): void;
+}
+//# sourceMappingURL=httpserver.service.d.ts.map

package/lib/services/httpserver.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpserver.service.d.ts","sourceRoot":"","sources":["../../src/services/httpserver.service.ts"],"names":[],"mappings":"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"}