Test network error branches with shimforge

Disclosure: I maintain shimforge (MIT), the crate this issue suggests.

Problem

Several places decide whether to retry, or which error to report, from reqwest::Error flags such as is_connect(), is_timeout() and is_body(). reqwest::Error has no public constructor, so a test can only get one of these errors from a real failure: a server that stalls, or a port that refuses the connection. Most of these branches are untested today:

A real server is a poor way to reach these branches. Timeouts cost real time, and connect errors are platform-dependent: on Windows a refused localhost connection takes about 2 s, so a connect test with a short timeout fails with a timeout instead.

Proposal

Add shimforge as a dev-dependency. It redirects calls to a function at run time, for the current test thread only. A test can then start from a real reqwest::Error built without any network access (a URL that does not parse) and mock only the flag it checks. Production code does not change.

Example: connect failures are retried

Cargo.toml:

[workspace.dependencies]
shimforge = "0.1.3"

exec-server/Cargo.toml:

[dev-dependencies]
reqwest = { workspace = true }
shimforge = { workspace = true }

exec-server/src/client_recovery_tests.rs:

use shimforge::Session;
use shimforge::mock;

/// A real `reqwest::Error` from a URL that does not parse. No request is sent.
fn registry_request_error() -> ExecServerError {
    let error = reqwest::Client::new()
        .get("not a url")
        .build()
        .expect_err("the URL does not parse");
    ExecServerError::EnvironmentRegistryRequest(
        codex_http_client::RouteAwareRequestError::Request(error),
    )
}

#[test]
fn recovery_retries_registry_connect_failures() {
    let mut session = Session::new();
    let is_connect = mock!(
        session,
        reqwest::Error::is_connect,
        fn(&reqwest::Error) -> bool
    );
    is_connect.expect().once().returns(true);

    assert!(is_retryable_registry_error(&registry_request_error()));
}

#[test]
fn recovery_does_not_retry_other_request_errors() {
    assert!(!is_retryable_registry_error(&registry_request_error()));
}

Tests for is_body and is_decode have the same shape, and so do the other rows in the table. No server, no waiting, and the same result on every OS.

Costs and limits

• Dev-dependency only; nothing ships in release builds. Runs on Linux, macOS and Windows, on x86-64 and ARM64.
• It patches machine code at run time, so the mocked function must not be inlined into its caller. Codex's dev and ci-test profiles build at opt-level = 0 so it's not a problem.

Evidence

I made the same kind of change in another Rust project: mezmo/aura#711. It replaced a wiremock server and a closed-port connect in error-classification tests with this pattern. The tests pass on Linux, macOS and Windows (x86-64 and ARM64) and in that project's Jenkins coverage run. The closed-port test it replaced was already failing on Windows for the 2 s reason above.

I can post the full test code for any row in the table here.

Start with the workspace Cargo.toml and the listed test and implementation files: exec-server/src/client_recovery_tests.rs, agent-identity/src/lib.rs, codex-api/src/files.rs, cli/src/doctor/network.rs, and feedback/src/upload.rs. Review each error branch and existing tests, then run the relevant test suites; done means the listed reqwest error paths are covered deterministically without network waits or platform-specific behavior.