@scriptc/compiler 0.4.5 → 0.4.6

package/ambient/node-fallback/http.d.ts

@@ -0,0 +1,326 @@
+/// <reference path="./http2.d.ts" />
+/// <reference path="./net.d.ts" />
+
+/* node:http — the SERVER and CLIENT slices (scr_http.c layers a
+ * hand-written HTTP/1.1 parser + serializer on scr_net.c; both link only
+ * into using binaries). createServer(handler) returns a net.Server —
+ * listen/close/address().port/'error' are the same lowered surface. The
+ * request carries url/method (always present on server requests),
+ * statusCode (a number on client responses, undefined on server
+ * requests), the underlying socket, and lowercased headers read as
+ * `string | undefined`; the body streams through on("data"/"end"). The
+ * response is setHeader/writeHead/write/end/destroy with Node's framing
+ * (Content-Length for a single end(body), chunked after writeHead/write)
+ * and the auto Date/Connection headers; writeHead's headers argument is
+ * an object literal or a Record<string, string>. request/get dial one
+ * connection per call (no agent pooling) with Node's exact wire head. */
+declare module "http" {
+  import { Server as NetServer, Socket } from "net";
+  export const METHODS: string[];
+  export const STATUS_CODES: { [status: number]: string | undefined };
+  export const maxHeaderSize: number;
+  export interface Server extends NetServer {
+    timeout: number;
+    setTimeout(msecs: number, callback?: (socket: Socket) => void): this;
+    closeAllConnections(): void;
+    closeIdleConnections(): void;
+    keepAliveTimeout: number;
+    keepAliveTimeoutBuffer: number;
+    headersTimeout: number;
+    requestTimeout: number;
+  }
+  export type RequestListener = (req: IncomingMessage, res: ServerResponse) => void;
+  /* The Server VALUE — Node's constructor works with and without `new`
+   * (test/parallel's http.Server(fn) spelling); both route to the
+   * createServer lowering. */
+  export const Server: {
+    new (requestListener?: (req: IncomingMessage, res: ServerResponse) => void): Server;
+    new (
+      options: ServerOptions,
+      requestListener?: (req: IncomingMessage, res: ServerResponse) => void,
+    ): Server;
+    (requestListener?: (req: IncomingMessage, res: ServerResponse) => void): Server;
+    (
+      options: ServerOptions,
+      requestListener?: (req: IncomingMessage, res: ServerResponse) => void,
+    ): Server;
+  };
+  /* The options-record stance (the RequestOptions precedent): every
+   * documented key typechecks; the lowering's option walk decides per
+   * key — requireHostHeader: false, joinDuplicateHeaders, and
+   * keepAliveTimeoutBuffer lower,
+   * documented-but-unlowered keys fence by name, unknown keys drop. */
+  export interface ServerOptions {
+    requireHostHeader?: boolean;
+    joinDuplicateHeaders?: boolean;
+    keepAliveTimeoutBuffer?: number;
+    maxHeaderSize?: number;
+    [option: string]: unknown;
+  }
+  /* The outgoing-header shape, @types/node's matrix: numbers format via
+   * String(n), arrays write one line per element (set-cookie's shape).
+   * Incoming headers stay `string | undefined` — what the parser answers
+   * (under @types/node the two SLOTS unify so `{ ...req.headers }`
+   * merges into outgoing literals as a copy; the fallback keeps reads
+   * simple and spreads target the same string | undefined slot). */
+  export type OutgoingHttpHeaders = { [name: string]: number | string | string[] | undefined };
+  export interface IncomingMessage {
+    readonly url: string;
+    readonly method: string;
+    readonly httpVersion: string;
+    readonly complete: boolean;
+    readonly aborted: boolean;
+    readonly statusCode: number | undefined;
+    readonly statusMessage: string | undefined;
+    readonly socket: Socket;
+    readonly connection: Socket;
+    readonly headers: { [name: string]: string | undefined };
+    readonly headersDistinct: { [name: string]: string[] | undefined };
+    readonly rawHeaders: string[];
+    readonly trailers: { [name: string]: string | undefined };
+    readonly trailersDistinct: { [name: string]: string[] | undefined };
+    readonly rawTrailers: string[];
+    resume(): void;
+    pause(): void;
+    destroy(): void;
+    setTimeout(msecs: number, callback?: () => void): this;
+    /* setEncoding('utf8'): 'data' delivers strings (other real encodings
+     * throw a "not supported yet" Error at runtime; unknown names throw
+     * ERR_UNKNOWN_ENCODING). */
+    setEncoding(encoding: string): void;
+    /* The proxy legs: the body streams into a ServerResponse, a
+     * ClientRequest, or a raw Socket; natural end ends the destination. */
+    pipe(
+      destination: ServerResponse | import("http2").Http2ServerResponse | ClientRequest | Socket,
+    ): void;
+    on(event: "data", listener: (chunk: any) => void): void;
+    on(event: "end" | "close" | "aborted", listener: () => void): void;
+    on(event: "error", listener: (err: Error) => void): void;
+    /* addListener IS on (Node aliases them) — the suite spells both. */
+    addListener(event: "data", listener: (chunk: any) => void): void;
+    addListener(event: "end" | "close" | "aborted", listener: () => void): void;
+    addListener(event: "error", listener: (err: Error) => void): void;
+    once(event: "data", listener: (chunk: any) => void): void;
+    once(event: "end" | "close" | "aborted", listener: () => void): void;
+    once(event: "error", listener: (err: Error) => void): void;
+  }
+  export interface ServerResponse {
+    readonly headersSent: boolean;
+    readonly writableEnded: boolean;
+    readonly finished: boolean;
+    readonly writableFinished: boolean;
+    readonly writableCorked: number;
+    readonly req: IncomingMessage;
+    readonly socket: Socket | null;
+    readonly connection: Socket | null;
+    sendDate: boolean;
+    strictContentLength: boolean;
+    /* Node's writable head properties: the implicit head reads them. */
+    statusCode: number;
+    statusMessage: string | undefined;
+    /* The value keeps its type: getHeader answers the number, string or
+     * array that was set. */
+    setHeader(name: string, value: number | string | readonly string[]): void;
+    appendHeader(name: string, value: string | readonly string[]): void;
+    getHeader(name: string): number | string | string[] | undefined;
+    getHeaderNames(): string[];
+    getRawHeaderNames(): string[];
+    getHeaders(): OutgoingHttpHeaders;
+    hasHeader(name: string): boolean;
+    removeHeader(name: string): void;
+    /* Both overloads answer the response (`return this` chaining); the
+     * headers argument also takes Node's flat [name, value, ...] array. */
+    writeHead(statusCode: number, headers?: OutgoingHttpHeaders | string[]): ServerResponse;
+    writeHead(
+      statusCode: number,
+      statusMessage: string,
+      headers?: OutgoingHttpHeaders | string[],
+    ): ServerResponse;
+    writeContinue(callback?: () => void): void;
+    writeProcessing(callback?: () => void): void;
+    writeEarlyHints(hints: Record<string, string | string[]>, callback?: () => void): void;
+    write(data: string | Uint8Array): void;
+    flushHeaders(): void;
+    cork(): void;
+    uncork(): void;
+    addTrailers(headers: OutgoingHttpHeaders | ReadonlyArray<[string, string]>): void;
+    setTimeout(msecs: number, callback?: () => void): this;
+    /* end's callback forms fire once the body went out (the 'finish'
+     * emit, deferred past the handler's synchronous tail). */
+    end(data?: string | Uint8Array, callback?: () => void): void;
+    end(callback: () => void): void;
+    destroy(): void;
+    on(event: "close" | "finish", listener: () => void): void;
+    /* addListener IS on (Node aliases them) — the suite spells both. */
+    addListener(event: "close" | "finish", listener: () => void): void;
+    once(event: "close" | "finish", listener: () => void): void;
+  }
+  /* The CLIENT slice (http.request/http.get): the options-object form
+   * with hostname/host, port, path, method, timeout, and headers; the
+   * callback receives the response as an IncomingMessage (statusCode,
+   * headers, body via on("data"/"end")). */
+  export interface RequestOptions {
+    hostname?: string | null;
+    host?: string | null;
+    /* A string port (a URL's .port) is accepted, as by Node. */
+    port?: number | string | null;
+    path?: string | null;
+    method?: string;
+    timeout?: number;
+    headers?: OutgoingHttpHeaders;
+    /* The caller's own dialer (the proxy's loopback dial): invoked once,
+     * synchronously; its socket carries the exchange. */
+    createConnection?: () => Socket;
+    /* agent: false is a one-shot dial with Connection: close — exactly
+     * the compiled client's model; null/undefined are the default; an
+     * Agent VALUE threads through (getName-keyed maxSockets accounting
+     * over one-dial-per-request connections). */
+    agent?: Agent | boolean | null;
+    /* Aborting destroys the request with an AbortError. */
+    signal?: AbortSignal;
+    /* HTTP over the Unix socket at this path instead of host:port. */
+    socketPath?: string;
+    /* The options-record stance: Node ignores an options record's
+     * unknown keys, so every key typechecks here — the option WALK in
+     * the lowering decides per key (lower, fence by name, or drop
+     * undocumented keys exactly like Node). */
+    [option: string]: unknown;
+  }
+  /* The Agent lowers to a checked-dynamic HANDLE: option parsing at the
+   * literal construction site, getName, destroy, the sockets/requests/
+   * freeSockets snapshots, and REAL maxSockets accounting (over-limit
+   * requests defer their dial and queue). keepAlive: true keeps finished
+   * connections in freeSockets for the next request to the same name,
+   * taken in `scheduling` order. */
+  export interface AgentOptions {
+    keepAlive?: boolean;
+    keepAliveMsecs?: number;
+    maxSockets?: number;
+    maxFreeSockets?: number;
+    maxTotalSockets?: number;
+    scheduling?: "fifo" | "lifo";
+    timeout?: number;
+    port?: number;
+    [option: string]: unknown;
+  }
+  export class Agent {
+    constructor(options?: AgentOptions);
+    destroy(): void;
+    /* Node's exact key shape: host:port:localAddress[:family][:socketPath]. */
+    getName(options?: {
+      host?: string;
+      port?: number;
+      localAddress?: string;
+      family?: number;
+      socketPath?: string;
+      [option: string]: unknown;
+    }): string;
+    maxSockets: number;
+    maxFreeSockets: number;
+    keepAliveMsecs: number;
+    readonly keepAlive: boolean;
+    readonly protocol: string;
+    /* Settable — a portless request through this agent dials it (Node's
+     * option merge). */
+    defaultPort: number;
+    readonly totalSocketCount: number;
+    readonly sockets: { [key: string]: unknown[] };
+    readonly freeSockets: { [key: string]: unknown[] };
+    readonly requests: { [key: string]: unknown[] };
+  }
+  /* Node's keepAlive global agent for requests without an agent option. */
+  export const globalAgent: Agent;
+  export interface ClientRequest {
+    readonly destroyed: boolean;
+    readonly aborted: boolean;
+    readonly socket: Socket;
+    readonly connection: Socket;
+    readonly writableCorked: number;
+    readonly method: string;
+    readonly path: string;
+    readonly host: string;
+    readonly protocol: string;
+    readonly headersSent: boolean;
+    readonly writableEnded: boolean;
+    readonly writableFinished: boolean;
+    readonly finished: boolean;
+    readonly reusedSocket: boolean;
+    setHeader(name: string, value: string): void;
+    getHeader(name: string): string | undefined;
+    hasHeader(name: string): boolean;
+    removeHeader(name: string): void;
+    getHeaderNames(): string[];
+    getRawHeaderNames(): string[];
+    getHeaders(): OutgoingHttpHeaders;
+    flushHeaders(): void;
+    addTrailers(headers: OutgoingHttpHeaders | ReadonlyArray<[string, string]>): void;
+    cork(): void;
+    uncork(): void;
+    setNoDelay(noDelay?: boolean): void;
+    setSocketKeepAlive(enable?: boolean, initialDelay?: number): void;
+    setTimeout(timeout: number, callback?: () => void): this;
+    write(data: string | Uint8Array): void;
+    end(data?: string | Uint8Array): void;
+    destroy(error?: Error): void;
+    abort(): void;
+    on(event: "response", listener: (res: IncomingMessage) => void): void;
+    on(event: "socket", listener: (socket: Socket) => void): void;
+    on(
+      event: "upgrade",
+      listener: (res: IncomingMessage, socket: Socket, head: Buffer) => void,
+    ): void;
+    on(event: "timeout" | "close" | "finish" | "abort" | "continue", listener: () => void): void;
+    on(event: "error", listener: (err: Error) => void): void;
+    /* addListener IS on (Node aliases them) — the suite spells both. */
+    addListener(event: "response", listener: (res: IncomingMessage) => void): void;
+    addListener(event: "socket", listener: (socket: Socket) => void): void;
+    addListener(
+      event: "upgrade",
+      listener: (res: IncomingMessage, socket: Socket, head: Buffer) => void,
+    ): void;
+    addListener(event: "timeout" | "close" | "finish" | "abort", listener: () => void): void;
+    addListener(event: "error", listener: (err: Error) => void): void;
+    once(event: "response", listener: (res: IncomingMessage) => void): void;
+    once(event: "socket", listener: (socket: Socket) => void): void;
+    once(
+      event: "upgrade",
+      listener: (res: IncomingMessage, socket: Socket, head: Buffer) => void,
+    ): void;
+    once(event: "timeout" | "close" | "finish" | "abort" | "continue", listener: () => void): void;
+    once(event: "error", listener: (err: Error) => void): void;
+  }
+  export function createServer(
+    requestListener?: (req: IncomingMessage, res: ServerResponse) => void,
+  ): Server;
+  export function createServer(
+    options: ServerOptions,
+    requestListener?: (req: IncomingMessage, res: ServerResponse) => void,
+  ): Server;
+  /* One signature with a UNION first parameter rather than Node's two
+   * overloads: `const requestFn = tls ? https.request : http.request`
+   * (the portless isProxyRunning shape) unions two function types, and
+   * resolving a call on that union collapses each constituent to a
+   * single signature — with an overload SET on both sides the options
+   * literal ends up checked against URL, in either declaration order.
+   * A union parameter has nothing to collapse. The lowering dispatches
+   * on the argument's own type, so it reads the same either way.
+   *
+   * `target` is a URL string or URL object (the spelling a from-scratch
+   * client reaches for first — dialed directly, with a non-http scheme
+   * an ERR_INVALID_PROTOCOL at runtime rather than a type error), or
+   * the options record. */
+  export function request(
+    target: RequestOptions | string | URL,
+    callback?: (res: IncomingMessage) => void,
+  ): ClientRequest;
+  export function get(
+    target: RequestOptions | string | URL,
+    callback?: (res: IncomingMessage) => void,
+  ): ClientRequest;
+  export function validateHeaderName(name: string, label?: string): void;
+  export function validateHeaderValue(name: string, value: unknown): void;
+}
+
+declare module "node:http" {
+  export * from "http";
+}