net: reject keep-alive delays that cannot be applied

[zeexzeex]

socket.setKeepAlive() takes its delays in milliseconds, but the underlying
socket options are configured in whole seconds. A positive value below 1000
rounds down to 0, which leaves the system default in place instead of
applying the requested timing:

socket.setKeepAlive(true, 400); // TCP_KEEPIDLE is left unchanged

Nothing indicated that the value had no effect. There was no exception, no
warning, and the return value was the socket either way, so the caller had no
way to tell that keep-alive was not configured as asked.

Sub-second timings cannot be supported: uv_tcp_keepalive() takes seconds and
rejects a delay outside [1, 32767]. This change rejects a delay that cannot
be applied as requested, instead of silently altering it.

Changes

• Throw ERR_OUT_OF_RANGE when a positive initialDelay or interval would
  truncate to zero or exceed the 32767 second socket-option limit.
  Non-positive values keep their documented meaning of leaving the current
  setting unchanged. Infinity (used by Agent to mean "no timeout") is left
  alone for the same reason.
• Document the new error behaviour in net.md.
• Adjust existing tests that passed values below 1000 ms which never actually
  configured keep-alive.

http.Agent reaches this path via keepAliveMsecs, so a value below 1000
now throws instead of being ignored.

Refs: #57712

[nodejs-github-bot]

Review requested:

• @nodejs/net

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.30%. Comparing base (4b5e86c) to head (6222f2f).
⚠️ Report is 269 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65528      +/-   ##
==========================================
+ Coverage   90.14%   90.30%   +0.16%     
==========================================
  Files         751      771      +20     
  Lines      253679   267033   +13354     
  Branches    47789    51445    +3656     
==========================================
+ Hits       228671   241157   +12486     
- Misses      16264    16902     +638     
- Partials     8744     8974     +230     

Files with missing lines	Coverage Δ
lib/net.js	94.60% <100.00%> (+0.04%)	⬆️

... and 210 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mcollina]

I don't think we should be landing a warning for this. I think we should be throwing an error.

[zeexzeex]

@mcollina Agreed, switched to throwing. uv_tcp_keepalive() already rejects a delay outside [1, 32767] seconds, so ERR_OUT_OF_RANGE now covers both ends. Non-positive values keep their documented "leave unchanged" meaning.

This surfaced test-async-hooks-http-parser-destroy, which sets keepAliveMsecs: 100 and so had never configured keep-alive at all. Raised to 1000.

Five tests also pass Infinity through Agent. That reads as "no timeout" but truncates to 0 today, so it has the same defect. I left it accepted rather than throwing, because the fix is a design choice rather than an obvious one: reject it, clamp it to the maximum, or keep the current behaviour and document it. It also looks like an established idiom, so it seemed better to let you pick instead of settling it here.

Two questions: does this need semver-major? And Agent reaches this path, so keepAliveMsecs below 1000 now throws instead of being ignored. Full parallel suite is green.

[mcollina]

ptal @nodejs/tsc

[mcollina]

ptal @nodejs/tsc

[mcollina]

@zeexzeex please update the PR title and description