fix(runtime): node:http client transport errors → real coded Error (code/syscall/errno)

[proggeramlug]

What

A failed http.request / http.get handed request.on('error') listeners a bare string instead of Node's real system Error. Every library that branches on err.code === 'ECONNREFUSED' (most HTTP clients do) saw undefined.

# before (Perry)              # node v26
typeof: string                typeof: object (Error)
code:    undefined            code:    ECONNREFUSED
syscall: undefined            syscall: connect
errno:   undefined            errno:   -61
message: undefined            message: connect ECONNREFUSED 127.0.0.1:1

Root causes

1. reqwest::Error::to_string() carries only the top-level "error sending request for url (...)" text — the OS reason (Connection refused) lives in the source() chain, so client_events::error_event_arg's substring match never fired and fell through to the plain-string branch.
2. Even the recognized path only set .code; Node also sets .syscall, .errno, and a ${syscall} ${CODE} ${detail} message.

Fix

• js_node_system_error_value (runtime FFI, perry-runtime/src/error.rs): builds an Error with .message + .code (the message→code side table the .code getter reads) and .syscall / .errno own properties (the Error expando store), exposed as perry_ffi::system_error_value. Purely additive — no existing error path changed.
• perry-ext-http::transport_error: classifies a reqwest::Error (+ request URL) into (message, code, syscall, errno) by walking the source() chain for the underlying std::io::Error (raw_os_error() → exact errno, ErrorKind → code), plus a text trail for DNS failures (getaddrinfo ENOTFOUND). Recognized failures push a new PendingHttpEvent::TransportError that the drain turns into the coded Error; anything unrecognized keeps the legacy string path, so the existing socket hang up / ECONNRESET surface is untouched.

Handles ECONNREFUSED, ENOTFOUND (getaddrinfo), ETIMEDOUT, ECONNABORTED, EADDRNOTAVAIL, EHOSTUNREACH, ENETUNREACH.

Verification (node v26 vs Perry, byte-for-byte, this host)

New node-suite test http/client-request/transport-error.ts matches node exactly:

refused:  object|Error|connect ECONNREFUSED 127.0.0.1:1|ECONNREFUSED|connect|-61|true
notfound: object|Error|getaddrinfo ENOTFOUND does-not-exist.invalid|ENOTFOUND|getaddrinfo|-3008|true

node-suite http: 18/18 → 19/19 (0 regressions).

Note: the mandate's "node:http 38.9% (7/18), 11 crashes" baseline was stale — all 18 prior http node-suite tests already passed on main; this PR adds genuine client error-path correctness on top and pins it with a 19th test.

Regression check (re-ran modules not touched)

• https 5/5 — shares the client-dispatch path; the change only alters the request-send failure branch, so success paths are unaffected.
• net 12/13, dns 5/6 — the 2 failures (net/server/connection-state-limits connection-event ordering; dns/imports/default-export resolver-rejection stack formatting + env-dependent ESERVFAIL localhost) are pre-existing, in perry-ext-net / perry-runtime/dns.rs — neither file is touched by this PR.

Per contributor rules, no Cargo.toml version / CLAUDE.md / CHANGELOG.md edits (maintainer folds metadata at merge).

Summary by CodeRabbit

• Bug Fixes

  • Enhanced HTTP request error handling to provide structured error details (code, syscall, errno) for transport failures, enabling better diagnostics for connection and resolution issues.

• Tests

  • Added HTTP transport error test coverage for connection refusal and DNS resolution failure scenarios.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds structured transport error reporting for HTTP requests. Reqwest errors are now classified into Node-style error objects with code, syscall, and errno fields instead of generic strings. A new TransportError event carries this information through the HTTP event system to error handlers and the JavaScript layer.

Changes

HTTP Transport Error Classification

Layer / File(s)	Summary
Transport error classifier crates/perry-ext-http/src/transport_error.rs	New classify_reqwest function parses reqwest error chains and URL details to produce Node-shaped (message, code, syscall, errno) tuples for known patterns (connect, DNS, connection refused) or None for unrecognized failures; includes unit tests for parsing, message formatting, and error-kind mapping.
PendingHttpEvent model extension crates/perry-ext-http/src/lib.rs	New transport_error module imported; PendingHttpEvent enum gains TransportError { request_handle, message, code, syscall, errno } variant to carry structured error information.
Request dispatch classification crates/perry-ext-http/src/client_dispatch.rs	In dispatch_request, non-timeout reqwest errors are classified via classify_reqwest; classified errors emit PendingHttpEvent::TransportError with structured fields, others fall back to generic PendingHttpEvent::Error.
Transport error event handler crates/perry-ext-http/src/client_events.rs	New handle_transport_error_event function marks request complete, converts transport fields into a Node-coded Error via perry_ffi::system_error_value, fires 'error' listeners, and emits 'close'.
Event loop drain dispatch crates/perry-ext-http/src/lib.rs	Main pending-event drain matches PendingHttpEvent::TransportError and routes to handle_transport_error_event with request handle and error fields.
FFI Node error construction crates/perry-ffi/src/error.rs, crates/perry-runtime/src/error.rs	FFI declaration and Rust helper system_error_value enable building Node-style Error objects with .code, .syscall, and .errno properties; runtime implementation creates base Error then sets properties via js_object_set_field_by_name; keepalive anchor prevents LTO dead-stripping.
FFI re-export formatting crates/perry-ffi/src/lib.rs	Re-export block reformatted to multi-line; system_error_value added to exported error helpers.
Transport error integration test test-parity/node-suite/http/client-request/transport-error.ts	Test verifies HTTP error listeners receive real Error objects with code, syscall, and errno properties; tests connection refusal and DNS lookup failure scenarios.

🎯 3 (Moderate) | ⏱️ ~25 minutes

🐰 Hops along the error path with glee,
Where transport woes now Error be,
With code and syscall, errno too—
Node-style errors shine right through!
A classified cascade of truth so clear, ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change: converting http client transport errors from bare strings to real Node-coded Error objects with code, syscall, and errno properties.
Description check	✅ Passed	The description comprehensively covers the problem, root causes, solution, verification steps, and regression checks, following the template structure with clear sections.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch node-http-fix-parity

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test-parity/node-suite/http/client-request/transport-error.ts`:
- Line 40: Replace the fixed setTimeout keepalive (setTimeout(() => {}, 2000))
with deterministic completion gating: create a Promise (or promises) that
resolve when the test's DNS/error callbacks are invoked (e.g., resolve inside
the request/error callback handlers used in this test) and await Promise.all (or
Promise.race with a reasonable per-request timeout to avoid hanging) so the test
only finishes after those callbacks run (or the timeout elapses); remove the
hardcoded 2s sleep and use the promise-based completion guard instead.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: db6efd75-e1fe-4ec2-bdd5-e1b9658d94bd

📥 Commits

Reviewing files that changed from the base of the PR and between ab5b7e8 and ebf2b3e.

📒 Files selected for processing (8)

• crates/perry-ext-http/src/client_dispatch.rs
• crates/perry-ext-http/src/client_events.rs
• crates/perry-ext-http/src/lib.rs
• crates/perry-ext-http/src/transport_error.rs
• crates/perry-ffi/src/error.rs
• crates/perry-ffi/src/lib.rs
• crates/perry-runtime/src/error.rs
• test-parity/node-suite/http/client-request/transport-error.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Replace fixed sleep with deterministic completion gating.

Line 40 uses a hardcoded 2s keepalive, so the test can exit before the DNS error callback fires on slower resolvers/networks, causing flaky/missing parity output. Track completion from callbacks (and optionally add per-request timeout) instead of relying on wall-clock sleep.

Suggested fix

-function describe(label: string, e: any) {
+function describe(label: string, e: any) {
   console.log(
     label,
     [
       typeof e,
@@
-// Port 1 is reserved/unused — a connect there is refused immediately.
+let doneCount = 0;
+const done = () => {
+  doneCount += 1;
+  if (doneCount === 2) {
+    // allow event loop to drain naturally once both errors are observed
+  }
+};
+
+// Port 1 is reserved/unused — a connect there is refused immediately.
 const refused = http.get({ host: "127.0.0.1", port: 1, path: "/" }, () => {});
 refused.on("error", (e: any) => {
   describe("refused:", e);
+  done();
@@
   notfound.on("error", (e2: any) => {
     describe("notfound:", e2);
+    done();
   });
 });
-
-setTimeout(() => {}, 2000);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test-parity/node-suite/http/client-request/transport-error.ts` at line 40,
Replace the fixed setTimeout keepalive (setTimeout(() => {}, 2000)) with
deterministic completion gating: create a Promise (or promises) that resolve
when the test's DNS/error callbacks are invoked (e.g., resolve inside the
request/error callback handlers used in this test) and await Promise.all (or
Promise.race with a reasonable per-request timeout to avoid hanging) so the test
only finishes after those callbacks run (or the timeout elapses); remove the
hardcoded 2s sleep and use the promise-based completion guard instead.