Create dedicated type for HTTP CONNECT errors and pass status code

[danpoletaev]

Currently, all request failures (connection refused, proxy rejections, HTTP errors, etc.) surface as a generic error(GenericFailure). There's no way for callers to tell why the request failed.

What we want:
Introduce a dedicated type(e.g. ImpitConnectError) that is thrown when the connection phase fails - i.e. before any response from the target server was received. This covers:

• TCP connection refused
• Connect timeout
• HTTP proxy rejecting the CONNECT tunnel (e.g. proxy returns 403 or 407)

When a proxy rejects the tunnel, the proxy's HTTP status code should be available on the error (e.g. statusCode: 403).

[danpoletaev]

Example in NodeJS

import wrapper from './index.wrapper.js';
const { Impit } = wrapper;

const main = async () => {

    const impit = new Impit({
        browser: 'chrome',
        proxyUrl: '<enter proxy url>',
        ignoreTlsErrors: true,
    });

    try {
        const response = await impit.fetch("https://playstation.com", undefined)
    } catch (err) {
        // error is generic here, no status code
        // {
        //     "code": "GenericFailure",
        //     "stack": "Error: impit error: Failed to connect to the server.\n" +
        //             "Reason: hyper_util::client::legacy::Error(\n" +
        //             "    Connect,\n" +
        //             "    TunnelUnsuccessful,\n" +
        //             ")",
        //     "message": "impit error: Failed to connect to the server.\n" +
        //             "Reason: hyper_util::client::legacy::Error(\n" +
        //             "    Connect,\n" +
        //             "    TunnelUnsuccessful,\n" +
        //             ")"
        // }
    }


};

main()
    .then((res) => console.log('result'))
    .catch((err) => console.error(err));

[bliuchak]

I've made a small investigation on this, and it looks like a non-trivial task.

Investigation Summary

The root cause is that hyper-util's tunnel implementation discards the proxy's HTTP status code. In tunnel.rs, the CONNECT response is parsed, but the status code is thrown away:

• HTTP/1.1 200 - success
• HTTP/1.1 407 - TunnelError::ProxyAuthRequired (no status code stored)
• Anything else - TunnelError::TunnelUnsuccessful (unit variant, zero data)

Additionally, TunnelError is a private type (not re-exported), so downstream crates can't even downcast to inspect it. The error eventually surfaces in Node.js as a generic Error with a debug-formatted message string.

Proposed Solution

Three layers of changes:

1. Fork hyper-util - carry the status code

   Patch TunnelError::TunnelUnsuccessful to TunnelUnsuccessful(u16) so it preserves the proxy's response status code. This is a ~10-line change in tunnel.rs. We already maintain forks of h2, rustls, and tower-http.

2. Thread the status code through Rust - napi boundary

   • In impit/src/errors.rs: detect the proxy status code from the error chain and store it in ImpitError::ConnectError (or a new ProxyConnectError(u16, String) variant)
   • In impit-node/src/lib.rs: encode the error variant as a machine-readable code in the napi::Error message (e.g. "CONNECT_ERROR:407:impit error: Proxy authentication required")

   This is needed because napi-rs cannot create custom JS error classes from async Rust code (Env is not Send, so it's unavailable inside async blocks).

3. JS error class hierarchy + wrapper mapping

   Define error classes in JavaScript (matching the existing Python hierarchy) and intercept native errors in index.wrapper.js's fetch() method to re-throw as the appropriate typed error:

   class ImpitError extends Error { }
   class RequestError extends ImpitError { }
   class TransportError extends RequestError { }
   class TimeoutError extends TransportError { }
   class ConnectTimeoutError extends TimeoutError { }
   class NetworkError extends TransportError { }
   class ConnectError extends NetworkError { }
   class ProxyError extends TransportError {
   statusCode; // the proxy's HTTP response status (e.g. 407)
   }
   // ... etc
   

   This gives users proper instanceof checks and machine-readable .statusCode on proxy errors:

   try {
       await impit.fetch("https://example.com");
   } catch (err) {
       if (err instanceof ProxyError) {
           console.log(err.statusCode); // 407
       } else if (err instanceof TimeoutError) {
           // ...
       }
   }