| | |
| | | /** |
| | | * To use the HTTP server and client one must import the `node:http` module. |
| | | * |
| | | * The HTTP interfaces in Node.js are designed to support many features |
| | | * of the protocol which have been traditionally difficult to use. |
| | | * In particular, large, possibly chunk-encoded, messages. The interface is |
| | | * careful to never buffer entire requests or responses, so the |
| | | * user is able to stream data. |
| | | * |
| | | * HTTP message headers are represented by an object like this: |
| | | * |
| | | * ```json |
| | | * { "content-length": "123", |
| | | * "content-type": "text/plain", |
| | | * "connection": "keep-alive", |
| | | * "host": "example.com", |
| | | * "accept": "*" } |
| | | * ``` |
| | | * |
| | | * Keys are lowercased. Values are not modified. |
| | | * |
| | | * In order to support the full spectrum of possible HTTP applications, the Node.js |
| | | * HTTP API is very low-level. It deals with stream handling and message |
| | | * parsing only. It parses a message into headers and body but it does not |
| | | * parse the actual headers or the body. |
| | | * |
| | | * See `message.headers` for details on how duplicate headers are handled. |
| | | * |
| | | * The raw headers as they were received are retained in the `rawHeaders` property, which is an array of `[key, value, key2, value2, ...]`. For |
| | | * example, the previous message header object might have a `rawHeaders` list like the following: |
| | | * |
| | | * ```js |
| | | * [ 'ConTent-Length', '123456', |
| | | * 'content-LENGTH', '123', |
| | | * 'content-type', 'text/plain', |
| | | * 'CONNECTION', 'keep-alive', |
| | | * 'Host', 'example.com', |
| | | * 'accepT', '*' ] |
| | | * ``` |
| | | * @see [source](https://github.com/nodejs/node/blob/v25.x/lib/http.js) |
| | | */ |
| | | declare module "node:http" { |
| | | import { NonSharedBuffer } from "node:buffer"; |
| | | import { LookupOptions } from "node:dns"; |
| | |
| | | * @since v18.17.0, v20.2.0 |
| | | */ |
| | | rejectNonStandardBodyWrites?: boolean | undefined; |
| | | /** |
| | | * If set to `true`, requests without `Content-Length` |
| | | * or `Transfer-Encoding` headers (indicating no body) will be initialized with an |
| | | * already-ended body stream, so they will never emit any stream events |
| | | * (like `'data'` or `'end'`). You can use `req.readableEnded` to detect this case. |
| | | * @since v25.1.0 |
| | | * @default false |
| | | */ |
| | | optimizeEmptyRequests?: boolean | undefined; |
| | | } |
| | | type RequestListener< |
| | | Request extends typeof IncomingMessage = typeof IncomingMessage, |
| | |
| | | * been transmitted are equal or not. |
| | | * |
| | | * Attempting to set a header field name or value that contains invalid characters |
| | | * will result in a \[`Error`\]\[\] being thrown. |
| | | * will result in a `Error` being thrown. |
| | | * @since v0.1.30 |
| | | */ |
| | | writeHead( |
| | |
| | | * |
| | | * ```js |
| | | * import http from 'node:http'; |
| | | * const agent = new http.Agent({ keepAlive: true }); |
| | | * |
| | | * // Server has a 5 seconds keep-alive timeout by default |
| | | * http |
| | |
| | | * sockets. Do not modify. |
| | | * @since v0.5.9 |
| | | */ |
| | | readonly requests: NodeJS.ReadOnlyDict<IncomingMessage[]>; |
| | | readonly requests: NodeJS.ReadOnlyDict<ClientRequest[]>; |
| | | constructor(opts?: AgentOptions); |
| | | /** |
| | | * Destroy any sockets that are currently in use by the agent. |
| | |
| | | /** |
| | | * Produces a socket/stream to be used for HTTP requests. |
| | | * |
| | | * By default, this function is the same as `net.createConnection()`. However, |
| | | * custom agents may override this method in case greater flexibility is desired. |
| | | * By default, this function behaves identically to `net.createConnection()`, |
| | | * synchronously returning the created socket. The optional `callback` parameter in the |
| | | * signature is **not** used by this default implementation. |
| | | * |
| | | * A socket/stream can be supplied in one of two ways: by returning the |
| | | * socket/stream from this function, or by passing the socket/stream to `callback`. |
| | | * However, custom agents may override this method to provide greater flexibility, |
| | | * for example, to create sockets asynchronously. When overriding `createConnection`: |
| | | * |
| | | * This method is guaranteed to return an instance of the `net.Socket` class, |
| | | * a subclass of `stream.Duplex`, unless the user specifies a socket |
| | | * type other than `net.Socket`. |
| | | * 1. **Synchronous socket creation**: The overriding method can return the |
| | | * socket/stream directly. |
| | | * 2. **Asynchronous socket creation**: The overriding method can accept the `callback` |
| | | * and pass the created socket/stream to it (e.g., `callback(null, newSocket)`). |
| | | * If an error occurs during socket creation, it should be passed as the first |
| | | * argument to the `callback` (e.g., `callback(err)`). |
| | | * |
| | | * `callback` has a signature of `(err, stream)`. |
| | | * The agent will call the provided `createConnection` function with `options` and |
| | | * this internal `callback`. The `callback` provided by the agent has a signature |
| | | * of `(err, stream)`. |
| | | * @since v0.11.4 |
| | | * @param options Options containing connection details. Check `createConnection` for the format of the options |
| | | * @param callback Callback function that receives the created socket |
| | | * @param options Options containing connection details. Check |
| | | * `net.createConnection` for the format of the options. For custom agents, |
| | | * this object is passed to the custom `createConnection` function. |
| | | * @param callback (Optional, primarily for custom agents) A function to be |
| | | * called by a custom `createConnection` implementation when the socket is |
| | | * created, especially for asynchronous operations. |
| | | * @returns The created socket. This is returned by the default |
| | | * implementation or by a custom synchronous `createConnection` implementation. |
| | | * If a custom `createConnection` uses the `callback` for asynchronous |
| | | * operation, this return value might not be the primary way to obtain the socket. |
| | | */ |
| | | createConnection( |
| | | options: ClientRequestArgs, |
| | |
| | | */ |
| | | function setMaxIdleHTTPParsers(max: number): void; |
| | | /** |
| | | * Dynamically resets the global configurations to enable built-in proxy support for |
| | | * `fetch()` and `http.request()`/`https.request()` at runtime, as an alternative |
| | | * to using the `--use-env-proxy` flag or `NODE_USE_ENV_PROXY` environment variable. |
| | | * It can also be used to override settings configured from the environment variables. |
| | | * |
| | | * As this function resets the global configurations, any previously configured |
| | | * `http.globalAgent`, `https.globalAgent` or undici global dispatcher would be |
| | | * overridden after this function is invoked. It's recommended to invoke it before any |
| | | * requests are made and avoid invoking it in the middle of any requests. |
| | | * |
| | | * See [Built-in Proxy Support](https://nodejs.org/docs/latest-v25.x/api/http.html#built-in-proxy-support) for details on proxy URL formats and `NO_PROXY` |
| | | * syntax. |
| | | * @since v25.4.0 |
| | | * @param proxyEnv An object containing proxy configuration. This accepts the |
| | | * same options as the `proxyEnv` option accepted by {@link Agent}. **Default:** |
| | | * `process.env`. |
| | | * @returns A function that restores the original agent and dispatcher |
| | | * settings to the state before this `http.setGlobalProxyFromEnv()` is invoked. |
| | | */ |
| | | function setGlobalProxyFromEnv(proxyEnv?: ProxyEnv): () => void; |
| | | /** |
| | | * Global instance of `Agent` which is used as the default for all HTTP client |
| | | * requests. Diverges from a default `Agent` configuration by having `keepAlive` |
| | | * enabled and a `timeout` of 5 seconds. |