node/doc
Joyee Cheung 036b1fd66d
http,https: add built-in proxy support in http/https.request and Agent
This patch implements proxy support for HTTP and HTTPS clients and
agents in the `http` and `https` built-ins`. When NODE_USE_ENV_PROXY
is set to 1, the default global agent would parse the
HTTP_PROXY/http_proxy, HTTPS_PROXY/https_proxy, NO_PROXY/no_proxy
settings from the environment variables, and proxy the requests
sent through the built-in http/https client accordingly.

To support this, `http.Agent` and `https.Agent` now accept a few new
options:

- `proxyEnv`: when it's an object, the agent would read and parse
  the HTTP_PROXY/http_proxy, HTTPS_PROXY/https_proxy, NO_PROXY/no_proxy
  properties from it, and apply them based on the protocol it uses
  to send requests. This option allows custom agents to
  reuse built-in proxy support by composing options. Global agents
  set this to `process.env` when NODE_USE_ENV_PROXY is 1.
- `defaultPort` and `protocol`: these allow setting of the default port
  and protocol of the agents. We also need these when configuring
  proxy settings and deciding whether a request should be proxied.

Implementation-wise, this adds a `ProxyConfig` internal class to handle
parsing and application of proxy configurations. The configuration
is parsed during agent construction. When requests are made,
the `createConnection()` methods on the agents would check whether
the request should be proxied. If yes, they either connect to the
proxy server (in the case of HTTP reqeusts) or establish a tunnel
(in the case of HTTPS requests) through either a TCP socket (if the
proxy uses HTTP) or a TLS socket (if the proxy uses HTTPS).

When proxying HTTPS requests through a tunnel, the connection listener
is invoked after the tunnel is established. Tunnel establishment uses
the timeout of the request options, if there is one. Otherwise it uses
the timeout of the agent.

If an error is encountered during tunnel establishment, an
ERR_PROXY_TUNNEL would be emitted on the returned socket. If the proxy
server sends a errored status code, the error would contain an
`statusCode` property. If the error is caused by timeout, the error
would contain a `proxyTunnelTimeout` property.

This implementation honors the built-in socket pool and socket limits.
Pooled sockets are still keyed by request endpoints, they are just
connected to the proxy server instead, and the persistence of the
connection can be maintained as long as the proxy server respects
connection/proxy-connection or persist by default (HTTP/1.1)

PR-URL: https://github.com/nodejs/node/pull/58980
Refs: https://github.com/nodejs/node/issues/57872
Refs: https://github.com/nodejs/node/issues/8381
Refs: https://github.com/nodejs/node/issues/15620
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
2025-07-18 09:06:32 +02:00
..
api http,https: add built-in proxy support in http/https.request and Agent 2025-07-18 09:06:32 +02:00
api_assets doc: add scroll margin to links 2025-07-10 16:22:51 +02:00
changelogs 2025-07-15, Version 20.19.4 'Iron' (LTS) 2025-07-15 19:05:10 -03:00
contributing doc: add RafaelGSS as steward July 25 2025-07-16 09:16:52 +00:00
abi_version_registry.json doc: reserve NMV 139 for Electron 38 2025-06-23 18:49:42 +00:00
eslint.config_partial.mjs tools: import rather than require ESLint plugins 2025-03-07 14:52:52 +00:00
full-white-stripe.jpg
node-config-schema.json watch: add --watch-kill-signal flag 2025-06-28 22:51:59 +00:00
node.1 doc: add missing environment variables to manpage 2025-07-11 07:38:24 +00:00
osx_installer_logo.png
README.md doc: update style guide 2024-09-26 22:56:35 +00:00
template.html doc: add "Skip to content" button 2025-01-26 18:41:45 +00:00
thin-white-stripe.jpg

Node.js documentation style guide

This guide provides clear and concise instructions to help you create well-organized and readable documentation for the Node.js community. It covers organization, spelling, formatting, and more to ensure consistency and professionalism across all documents.

Table of contents

  1. General Guidelines
  2. Writing Style
  3. Punctuation
  4. Document Structure
  5. API Documentation
  6. Code Blocks
  7. Formatting
  8. Product and Project Naming

General guidelines

File naming

  • Markdown Files: Use lowercase-with-dashes.md.
    • Use underscores only if they are part of the topic name (e.g., child_process).
    • Some files, like top-level Markdown files, may be exceptions.

Text wrapping

  • Wrap documents at 120 characters per line to enhance readability and version control.

Editor configuration

  • Follow the formatting rules specified in .editorconfig.
    • A plugin is available for some editors to enforce these rules.

Testing documentation

  • Validate documentation changes using make test-doc -j or vcbuild test-doc.

Writing style

Spelling and grammar

  • Spelling: Use US spelling.
  • Grammar: Use clear, concise language. Avoid unnecessary jargon.

Commas

  • Serial Commas: Use serial commas for clarity.
    • Example: apples, oranges, and bananas

Pronouns

  • Avoid first-person pronouns (I, we).
    • Exception: Use we recommend foo instead of foo is recommended.

Gender-neutral language

  • Use gender-neutral pronouns and plural nouns.
    • OK: they, their, them, folks, people, developers
    • NOT OK: his, hers, him, her, guys, dudes

Terminology

  • Use precise technical terms and avoid colloquialisms.
  • Define any specialized terms or acronyms at first use.

Punctuation

Terminal punctuation

  • Place inside parentheses or quotes if the content is a complete clause.
  • Place outside if the content is a fragment of a clause.

Quotation marks

  • Use double quotation marks for direct quotes.
  • Use single quotation marks for quotes within quotes.

Colons and semicolons

  • Use colons to introduce lists or explanations.
  • Use semicolons to link closely related independent clauses.

Document structure

Headings

  • Start documents with a level-one heading (#).
  • Use subsequent headings (##, ###, etc.) to organize content hierarchically.
  • Prefer reference-style links ([a link][]) over inline links ([a link](http://example.com)).

Lists

  • Use bullet points for unordered lists and numbers for ordered lists.
  • Keep list items parallel in structure.

Tables

  • Use tables to present structured information clearly. Ensure they are readable in plain text.

API documentation

YAML comments

  • Update the YAML comments associated with the API, especially when introducing or deprecating an API.

Usage examples

  • Provide a usage example or a link to an example for every function.

Parameter descriptions

  • Clearly describe parameters and return values, including types and defaults.
    • Example:
      * `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
      

Code blocks

Language-aware fences

  • Use language-aware fences (e.g., ```js) for code blocks.

    • Info String: Use the appropriate info string from the following list:

      Language Info String
      Bash bash
      C c
      CommonJS cjs
      CoffeeScript coffee
      Terminal Session console
      C++ cpp
      Diff diff
      HTTP http
      JavaScript js
      JSON json
      Markdown markdown
      EcmaScript mjs
      Powershell powershell
      R r
      Plaintext text
      TypeScript typescript
    • Use text for languages not listed until their grammar is added to remark-preset-lint-node.

Code comments

  • Use comments to explain complex logic within code examples.
  • Follow the standard commenting style of the respective language.

Formatting

Escaping characters

  • Use backslash-escaping for underscores, asterisks, and backticks: \_, \*, \`.

Naming conventions

  • Constructors: Use PascalCase.
  • Instances: Use camelCase.
  • Methods: Indicate methods with parentheses: socket.end() instead of socket.end.

Function arguments and returns

  • Arguments:
    * `name` {type|type2} Optional description. **Default:** `value`.
    
    Example:
    * `byteOffset` {integer} Index of first byte to expose. **Default:** `0`.
    
  • Returns:
    * Returns: {type|type2} Optional description.
    
    Example:
    * Returns: {AsyncHook} A reference to `asyncHook`.
    

Product and project naming

Official styling

  • Use official capitalization for products and projects.
    • OK: JavaScript, Google's V8
    • NOT OK: Javascript, Google's v8

Node.js references

  • Use Node.js instead of Node, NodeJS, or similar variants.
    • For the executable, node is acceptable.

Version references

  • Use Node.js and the version number in prose. Do not prefix the version number with v.
    • OK: Node.js 14.x, Node.js 14.3.1
    • NOT OK: Node.js v14

For topics not addressed here, please consult the Microsoft Writing Style Guide.