Use Keep-Alive by default in global agents and close idle connections in server by ShogunPanda · Pull Request #43522 · nodejs/node

ShogunPanda · 2022-06-21T12:59:22Z

This PR introduces the following changes:

Both http.globalAgent and https.globalAgent use keep-alive by default.
Agent now parses and applies Keep-Alive headers received by the server (if smaller than the current agent timeout)
http(s).Server.close now calls closeIdleConnections internally.

Fixes: #37184

nodejs-github-bot · 2022-06-21T12:59:28Z

Review requested:

@nodejs/crypto
@nodejs/http
@nodejs/net

mcollina

lgtm

mcollina · 2022-06-23T08:54:52Z

cc @nodejs/tsc

also @mscdex

nodejs-github-bot · 2022-06-27T07:48:04Z

CI: https://ci.nodejs.org/job/node-test-pull-request/44887/

mcollina

lgtm

cc @nodejs/tsc this needs another approval

Trott · 2022-06-27T13:51:52Z

cc @nodejs/tsc this needs another approval

It has two TSC approvals already (you and Antoine), so I think it's good as far as our landing-a-semver-major rules go. (However, I wouldn't discourage someone else from reviewing!)

nodejs-github-bot · 2022-06-27T13:53:04Z

CI: https://ci.nodejs.org/job/node-test-pull-request/44898/

Trott · 2022-06-27T13:54:16Z

CITGM: https://ci.nodejs.org/view/Node.js-citgm/job/citgm-smoker/2964/

nodejs-github-bot · 2022-06-27T17:01:46Z

CI: https://ci.nodejs.org/job/node-test-pull-request/44903/

nodejs-github-bot · 2022-06-28T10:40:28Z

CI: https://ci.nodejs.org/job/node-test-pull-request/44935/

nodejs-github-bot · 2022-06-28T13:36:14Z

CI: https://ci.nodejs.org/job/node-test-pull-request/44938/

ShogunPanda · 2022-06-29T10:49:04Z

Landed in 4267b92

PR-URL: #43522 Fixes: #37184 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

This gets the test to use its own `https.agent` instead of the default one. Signed-off-by: Daeyeon Jeong daeyeon.dev@gmail.com PR-URL: #44025 Refs: #43522 Refs: https://github.com/nodejs/node/actions/workflows/test-internet.yml Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com>

Notable Changes: doc: * graduate webcrypto to stable (Filip Skokan) #44897 esm: * remove specifier resolution flag (Geoffrey Booth) #44859 http: * (SEMVER-MAJOR) use Keep-Alive by default in global agents (Paolo Insogna) #43522 build: * (SEMVER-MAJOR) remove dtrace & etw support (Ben Noordhuis) #43652 * (SEMVER-MAJOR) remove systemtap support (Ben Noordhuis) #43651 deps: * (SEMVER-MAJOR) deps: update V8 to 10.7.193.13 (Michaël Zasso) #44741 Deprecation and Removals: * deprecate url.parse() (Rich Trott) #44919 * (SEMVER-MAJOR) runtime deprecate exports double slash maps (Guy Bedford) #44495 * (SEMVER-MAJOR) runtime deprecate coercion to integer in `process.exit()` (Daeyeon Jeong) #44711 Semver-Major Commits: * [53f73d1] - (SEMVER-MAJOR) build: enable V8's trap handler on Windows (Michaël Zasso) #44741 * [06aaf8a] - (SEMVER-MAJOR) build: reset embedder string to "-node.0" (Michaël Zasso) #44741 * [aa3a572] - (SEMVER-MAJOR) build: remove dtrace & etw support (Ben Noordhuis) #43652 * [38f1e27] - (SEMVER-MAJOR) build: remove systemtap support (Ben Noordhuis) #43651 * [2849283] - (SEMVER-MAJOR) crypto: remove non-standard `webcrypto.Crypto.prototype.CryptoKey` (Antoine du Hamel) #42083 * [a1653ac] - (SEMVER-MAJOR) crypto: do not allow to call setFips from the worker thread (Sergey Petushkov) #43624 * [fd36a8d] - (SEMVER-MAJOR) deps: update llhttp to 8.1.0 (Paolo Insogna) #44967 * [89ecddd] - (SEMVER-MAJOR) deps: bump minimum ICU version to 71 (Michaël Zasso) #44741 * [66fe446] - (SEMVER-MAJOR) deps: V8: cherry-pick 0cccb6f27d78 (Michaël Zasso) #44741 * [88ed027] - (SEMVER-MAJOR) deps: V8: cherry-pick 7ddb8399f9f1 (Michaël Zasso) #44741 * [26c651c] - (SEMVER-MAJOR) deps: V8: cherry-pick 1b3a4f0c34a1 (Michaël Zasso) #44741 * [c8ff2df] - (SEMVER-MAJOR) deps: V8: cherry-pick b161a0823165 (Michaël Zasso) #44741 * [7a8fa2d] - (SEMVER-MAJOR) deps: fix V8 build on Windows with MSVC (Michaël Zasso) #44741 * [83b0aaa] - (SEMVER-MAJOR) deps: fix V8 build on SmartOS (Michaël Zasso) #44741 * [7a952e8] - (SEMVER-MAJOR) deps: silence irrelevant V8 warning (Michaël Zasso) #44741 * [6bd756d] - (SEMVER-MAJOR) deps: update V8 to 10.7.193.13 (Michaël Zasso) #44741 * [03fb789] - (SEMVER-MAJOR) events: add null check for the signal of EventTarget (Masashi Hirano) #43153 * [a4fa526] - (SEMVER-MAJOR) fs: add directory autodetection to fsPromises.symlink() (Livia Medeiros) #42894 * [bb4891d] - (SEMVER-MAJOR) fs: add validateBuffer to improve error (Hirotaka Tagawa / wafuwafu13) #44769 * [950a441] - (SEMVER-MAJOR) fs: remove coercion to string in writing methods (Livia Medeiros) #42796 * [41a6d82] - (SEMVER-MAJOR) fs: harden fs.readSync(buffer, options) typecheck (LiviaMedeiros) #42772 * [2275faa] - (SEMVER-MAJOR) fs: harden fs.read(params, callback) typecheck (LiviaMedeiros) #42772 * [29953a0] - (SEMVER-MAJOR) fs: harden filehandle.read(params) typecheck (LiviaMedeiros) #42772 * [4267b92] - (SEMVER-MAJOR) http: use Keep-Alive by default in global agents (Paolo Insogna) #43522 * [0324529] - (SEMVER-MAJOR) inspector: introduce inspector/promises API (Erick Wendel) #44250 * [8027099] - (SEMVER-MAJOR) lib: enable global CustomEvent by default (Daeyeon Jeong) #44860 * [f529f73] - (SEMVER-MAJOR) lib: brand check event handler property receivers (Chengzhong Wu) #44483 * [6de2673] - (SEMVER-MAJOR) lib: enable global WebCrypto by default (Antoine du Hamel) #42083 * [73ba883] - (SEMVER-MAJOR) lib: use private field in AbortController (Joyee Cheung) #43820 * [7dd2f41] - (SEMVER-MAJOR) module: runtime deprecate exports double slash maps (Guy Bedford) #44495 * [22c39b1] - (SEMVER-MAJOR) path: the dot will be added(path.format) if it is not specified in `ext` (theanarkh) #44349 * [587367d] - (SEMVER-MAJOR) perf_hooks: expose webperf global scope interfaces (Chengzhong Wu) #44483 * [364c0e1] - (SEMVER-MAJOR) perf_hooks: fix webperf idlharness (Chengzhong Wu) #44483 * [ada2d05] - (SEMVER-MAJOR) process: runtime deprecate coercion to integer in `process.exit()` (Daeyeon Jeong) #44711 * [e0ab8dd] - (SEMVER-MAJOR) process: make process.config read only (Sergey Petushkov) #43627 * [481a959] - (SEMVER-MAJOR) readline: remove `question` method from `InterfaceConstructor` (Antoine du Hamel) #44606 * [c9602ce] - (SEMVER-MAJOR) src: use new v8::OOMErrorCallback API (Michaël Zasso) #44741 * [19a70c1] - (SEMVER-MAJOR) src: override CreateJob instead of PostJob (Clemens Backes) #44741 * [fd52c62] - (SEMVER-MAJOR) src: use V8_ENABLE_SANDBOX macro (Michaël Zasso) #44741 * [c10988d] - (SEMVER-MAJOR) src: use non-deprecated V8 inspector API (Michaël Zasso) #44741 * [3efe901] - (SEMVER-MAJOR) src: update NODE_MODULE_VERSION to 111 (Michaël Zasso) #44741 * [77e5856] - (SEMVER-MAJOR) src: turn embedder api overload into default argument (Alena Khineika) #43629 * [dabda03] - (SEMVER-MAJOR) src: per-environment time origin value (Chengzhong Wu) #43781 * [2e49b99] - (SEMVER-MAJOR) src,test: disable freezing V8 flags on initialization (Clemens Backes) #44741 * [2b32985] - (SEMVER-MAJOR) stream: use null for the error argument (Luigi Pinca) #44312 * [36805e8] - (SEMVER-MAJOR) test: adapt test-repl for V8 update (Michaël Zasso) #44741 * [96ef257] - (SEMVER-MAJOR) test: adapt test-repl-pretty-*stack to V8 changes (Michaël Zasso) #44741 * [71c193e] - (SEMVER-MAJOR) test: adapt to new JSON SyntaxError messages (Michaël Zasso) #44741 * [b5f1564] - (SEMVER-MAJOR) test: rename always-opt flag to always-turbofan (Michaël Zasso) #44741 * [1acf033] - (SEMVER-MAJOR) test: fix test-hash-seed for new V8 versions (Michaël Zasso) #44741 * [57ff476] - (SEMVER-MAJOR) test: remove duplicate test (Luigi Pinca) #44051 * [77def91] - (SEMVER-MAJOR) tls,http2: send fatal alert on ALPN mismatch (Tobias Nießen) #44031 * [4860ad9] - (SEMVER-MAJOR) tools: update V8 gypfiles for 10.7 (Michaël Zasso) #44741 PR-URL: #44626 Co-authored-by: Ruy Adorno <ruyadorno@google.com>

This gets the test to use its own `https.agent` instead of the default one. Signed-off-by: Daeyeon Jeong daeyeon.dev@gmail.com PR-URL: nodejs/node#44025 Refs: nodejs/node#43522 Refs: https://github.com/nodejs/node/actions/workflows/test-internet.yml Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com>

Prior to Node.js 19.0.0, calling close while an idle client was connected to a server would not actually close the server before the client disconnected. This behavior was modified in Node.js 19.0.0: nodejs/node#43522 This resulted in our mock server being closed before we expected and as a result, some of the tests in `cluster.test.js` would fail. This is because the 1 second timeout is lower than the exponential backoff logic in the `_autoRetry` function inside the `native_realm.js` file. To get around this issue, the timeout have simply been incresed to 5 seconds instead of 1. This is not pretty, but it gets the job done.

## 发现了什么宿主起 HTTP 服务这件事，本仓此前只给缝（`createHttpHandler` 返回 `(req,res)=>void`），剩下全靠抄示例。`examples/deploy/src/main.ts` 108 行里约 35 行与业务无关：端口解析校验、 `createServer` + `listen` 回调、信号 + drain + `server.close` + `process.exit`。麻烦不在长度，在于**写错没人报**——四个错都有这个性质： 1. **连接没收干净**：`server.close()` 要等所有连接结束，而**已连接但一个字节都没发的裸 TCP 不在 http 的 idle 列表里**，`closeIdleConnections()` 实测打不掉它（destroyed=false），只有 `closeAllConnections()` 能收 ⇒ 没有预算就永远挂着。 2. **顺序反了**：先 `server.close()` 再 `drain()`，在飞请求被切断，而 `drain()` 仍报告「已排空」。 3. **第二次信号被吞**：`if (stopping) return;` 的注释写着「便于强杀」，**恰恰相反**——注册了 listener 就拦截了信号，Node 默认行为（终止）不会发生，而 handler 什么都不做 ⇒ 运维第二次 SIGTERM 毫无反应，只能等 SIGKILL。四份参考示例当时都这么写。 4. **停完不退出**：`drain()` 返回 `false` 的契约是「此后本进程不再推进任何任务 ⇒ 必须退出」，但退出码与「关池 / 冲 sink 之后再退」的编排没有落点，宿主容易漏掉 `process.exit`，于是已落库的记录永远停在 `running`。 ## 实证（不是设计推演） - **PITFALL 60**：设计稿原本照旧知识写「不显式 `closeIdleConnections()`，keep-alive 会让 `close()` 等满超时」—— **在 Node 22 上是假的**。查官方确认：v19.0.0 起 `close()` 自己收空闲连接（nodejs/node#43522，官方原话「19 之后没必要再配合调它，但调也无害，且对要支持 <19 的库有用」）。本机实测：真 keep-alive 空闲连接 + 不调它 ⇒ `close()` 照常 402ms 回调 ⇒ 「删掉它就超时」这条变异**不成立**，行为断言抓不到。 ⇒ 但 `engines` 是 `>=18`，对 18.x 那行仍承重 ⇒ **保留调用，改用调用断言钉**（期望次数按运行时算：≥19 是 2 次 = Node 自己 1 次 + 我们 1 次；<19 是 1 次）⇒ 两个版本上删掉都红。判据：**行为断言抓不到时，先问是不是运行时版本已内建了这个行为，别急着删代码。** - **PITFALL 61**（探针 `/tmp/probe-idle*.mjs`）：裸 TCP 与真 keep-alive 是两种连接，前者任何 Node 版本都收不掉 ⇒ 这同时证明**预算是必需品不是装饰**。 - **变异 8/8** 亲跑，各咬住预期用例后还原：删 `closeIdleConnections` / 删 `closeAllConnections` / 删 `server.off('error')` / 破坏幂等（`??=` → `=`）/ 二次信号 `return` 吞掉 / drain 抛错就不关服务器 / `closeServer` 提前到 drain 之前 / 删 `onShutdown` 调用。 ## 为什么这么改（边界论证）先确认了 NestJS 的真实机制：它的 `SIGTERM` 订阅**默认关闭**，必须显式 `app.enableShutdownHooks()`（官方理由：listener 占资源、一进程多实例会泄漏）⇒ Nest 也是 opt-in。所以本原语的 `signals` **不传 = 一个信号都不订阅**，与 `enableShutdownHooks()` 同构。给按钮不违反「不做进程级决策」——违反的是**在 `createApp` 里偷偷 listen** 或**替宿主订阅信号**。同理 `onShutdown(clean)` 只把结论交回宿主，本原语**不调 `process.exit`**。 API 定型： - `serve(handler, { port, host?, backlog? }) → { server, port, close(opts?) }`， `port` 是**实际**端口（传 0 时由 OS 分配），端口冲突直接 reject（boot 阶段静默起不来比崩更难查）。 - `gracefulShutdown({ server, drain, signals?, timeoutMs?=15000, onSecondSignal?, onShutdown? }) → 幂等 stop()`；并发 `stop()` 共用同一个 in-flight promise；`timeoutMs <= 0` 读作「不限」。 `onShutdown` 是写示例时才发现的缺口，后加的缝。 ## 取舍如实记 - 没选「一个大 `serve(app,{...})` 包到底」（B 档）：那样与「只想拿 handler 挂进已有 Express」的用法打架，且核心变厚一层 serving。两个正交原语对已有用法零影响。 - `closeIdleConnections()` 在 ≥19 上是冗余调用，**保留**（18.x 承重 + 官方明确「调也无害」）。 - `patrol` 的 `npm run drill`（§5 断言退出码 0）**没跑**（要真模型）。现在退出码随 `clean` 变化 ⇒ drill 若报 1 是**真信号不是假警**。 ## 影响面 - 新增：`src/transport/serve.ts`（~220 行）、`tests/transport/serve.test.ts`（15 例）、 `docs/plans/2026-10-22-serve-graceful-shutdown.md`（设计稿）、`docs/database.md`。 - 公共面：`src/index.ts` 导出 5 个名字（serve / Served / ServeOptions / gracefulShutdown / GracefulShutdownOptions）⇒ 官网 api.html 反向全覆盖守卫当场红，中英两页补表 + chip 228 → 233。 - 四份示例全改（deploy / complete / agent-endpoint / patrol），样板 35 行 → ~8 行。 - 文档：`usage-guide` 优雅停机小节（新代码块已进 `code-fences` 真编译射程，变异 `onSecondSignalX` ⇒ `usage-guide.md:761 TS2561` 亲验）、`deployment.md` §5、 `database.md` §7、`guards.md` §1.3 登记行、`spec.md` §10 决策条、`CHANGELOG` Unreleased。 - 顺带清掉 CHANGELOG 里一个空的重复 `## [Unreleased]`（发版时靠手工搬运、无机器查，两个空壳会搬错地方）。 - ⚠️ 圈号守卫真红过一次：注释里写「决策 2026-10-22 ② ref-…」也红（带 slug 也不行）⇒ 四处改成不带圈号的形式。 ## 验证 - typecheck + typecheck:tests + biome ci **全绿**。 - `npm run build` + `e2e-deploy`（`shutdownExitCode: 0`、`metricsHasRuns: true`）+ `e2e-examples` （26 项）全绿；deploy / complete / patrol 各自 `tsc -p` 绿；agent-endpoint 无 node_modules，临时 tsconfig（paths → `../../src/index.ts`）typecheck 绿后删除。 - 官网构建 + agent 可读性检查绿。 - 本机 `npm test`（16m41s）剩 2 条，均为已知本机假红（MCP stdio 两例整链红、单跑 30/30 绿）；最终判据看 CI。

ShogunPanda requested review from mcollina and ronag June 21, 2022 12:59

nodejs-github-bot added http Issues and PRs related to the http subsystem. https Issues and PRs related to the https subsystem. needs-ci PRs that need a full CI run. labels Jun 21, 2022

mcollina added the semver-major PRs that contain breaking changes and should be released in the next major version. label Jun 21, 2022

mcollina approved these changes Jun 21, 2022

View reviewed changes

aduh95 approved these changes Jun 23, 2022

View reviewed changes

Comment thread lib/_http_agent.js Outdated

ShogunPanda force-pushed the default-agent branch from ae668c1 to aca06a6 Compare June 24, 2022 10:21

http: use Keep-Alive by default in global agents

a8262b8

ShogunPanda force-pushed the default-agent branch from aca06a6 to a8262b8 Compare June 27, 2022 07:46

mcollina approved these changes Jun 27, 2022

View reviewed changes

github-actions Bot mentioned this pull request Jun 28, 2022

CI Reliability 2022-06-28 nodejs/reliability#314

Open

32 tasks

github-actions Bot mentioned this pull request Jun 29, 2022

CI Reliability 2022-06-29 nodejs/reliability#315

Open

23 tasks

ShogunPanda closed this Jun 29, 2022

ShogunPanda added a commit that referenced this pull request Jun 29, 2022

http: use Keep-Alive by default in global agents

4267b92

PR-URL: #43522 Fixes: #37184 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

ShogunPanda deleted the default-agent branch June 29, 2022 10:49

MoLow mentioned this pull request Jun 30, 2022

Investigate flaky test-stream-finished #43623

Closed

tniessen mentioned this pull request Jul 1, 2022

http: fix failing test #43641

Merged

F3n67u mentioned this pull request Jul 1, 2022

Revert "http: use Keep-Alive by default in global agents" #43636

Closed

RafaelGSS mentioned this pull request Oct 17, 2022

Support Node.js v19 fastify/fastify#4350

Closed

mcollina mentioned this pull request Oct 21, 2022

Node.js V19 support fastify/fastify#4366

Merged

3 of 4 tasks

richardbann mentioned this pull request Nov 15, 2022

FetchError: request to http://0.0.0.0:8000/graphql failed, reason: socket hang up remix-run/remix#4414

Closed

Linkgoron mentioned this pull request Jun 7, 2023

https: fix connection checking interval not clearing on server close #48383

Merged

trevor-scheer mentioned this pull request Jul 21, 2023

Test against Node 20, update tests for compatibility apollographql/apollo-server#7636

Merged

himself65 mentioned this pull request Oct 15, 2023

fetch will always hang up about 4s nodejs/undici#2348

Closed

BrandonGillis mentioned this pull request Dec 6, 2023

feat: add custom CA Certificate preference usebruno/bruno#1155

Merged

5 tasks done

ShogunPanda mentioned this pull request Dec 14, 2023

doc && http: fix agent default value for keepAlive #51115

Closed

lpinca mentioned this pull request Jan 12, 2024

Detecting broken connections fails with RSV1 must be clear on node v20.11.0 websockets/ws#2193

Closed

1 task done

fahrradflucht mentioned this pull request Apr 6, 2024

doc: call out http(s).globalAgent defaults #52392

Merged

nikwen mentioned this pull request Aug 11, 2024

Keep-Alive behavior is different on Node.js ≤ 18 and > 18 axios/axios#6536

Closed

jishi mentioned this pull request Nov 21, 2024

Node.js 20 problems jishi/node-sonos-http-api#907

Closed

ArtskydJ mentioned this pull request Dec 12, 2024

"Socket hang up" in node 19+ trex-arms/sqs#11

Closed

waltmayf mentioned this pull request Sep 3, 2026

Instrument AppSync live-push per-hop latency + resolve direct-action feasibility (#263, #262) aws-samples/sample-edge-to-cloud-digital-ops-workshop#264

Merged

migoric mentioned this pull request Oct 22, 2026

feat(transport): 新增 serve() 与 gracefulShutdown()，收口起服务与优雅停机的四个静默错 migoric/agentia#277

Merged

Navigation Menu

Repository navigation

Use Keep-Alive by default in global agents and close idle connections in server - #43522

Use Keep-Alive by default in global agents and close idle connections in server#43522
ShogunPanda wants to merge 1 commit into
nodejs:mainfrom
ShogunPanda:default-agent

ShogunPanda commented Jun 21, 2022

Uh oh!

nodejs-github-bot commented Jun 21, 2022

Uh oh!

mcollina left a comment

Uh oh!

mcollina commented Jun 23, 2022

Uh oh!

Uh oh!

nodejs-github-bot commented Jun 27, 2022

Uh oh!

mcollina left a comment

Uh oh!

Trott commented Jun 27, 2022

Uh oh!

nodejs-github-bot commented Jun 27, 2022

Uh oh!

Trott commented Jun 27, 2022

Uh oh!

nodejs-github-bot commented Jun 27, 2022

Uh oh!

nodejs-github-bot commented Jun 28, 2022

Uh oh!

nodejs-github-bot commented Jun 28, 2022

Uh oh!

ShogunPanda commented Jun 29, 2022

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

ShogunPanda commented Jun 21, 2022

Uh oh!

nodejs-github-bot commented Jun 21, 2022

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

mcollina commented Jun 23, 2022

Uh oh!

Uh oh!

nodejs-github-bot commented Jun 27, 2022

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

Trott commented Jun 27, 2022

Uh oh!

nodejs-github-bot commented Jun 27, 2022

Uh oh!

Trott commented Jun 27, 2022

Uh oh!

nodejs-github-bot commented Jun 27, 2022

Uh oh!

nodejs-github-bot commented Jun 28, 2022

Uh oh!

nodejs-github-bot commented Jun 28, 2022

Uh oh!

ShogunPanda commented Jun 29, 2022

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants