feat: add connection timeout, TCP keepalive, and pool health features

[ajmeese7]

Problem

neo4rs has no mechanism to detect or recover from broken TCP connections. When a connection to Neo4j becomes half-open (peer closes, network interruption, container restart), recv() in connection.rs hangs indefinitely because TcpStream has no read timeout configured. This poisons the deadpool connection pool:

1. Graph::run() acquires a connection from deadpool
2. Sends the Bolt request via send() — succeeds (OS buffers the write)
3. Waits for response via recv() — hangs forever (peer is gone, no TCP RST received)
4. Deadpool's recycle() calls Connection::reset() → send_recv() → also hangs on recv()
5. The connection is never returned, permanently reducing available connections
6. With enough broken connections, the pool is exhausted and all operations deadlock

There is no workaround within neo4rs — users must wrap every graph.run()/graph.execute() call in tokio::time::timeout, which is error-prone and doesn't prevent pool poisoning.

Fix

Connection timeouts

• Wrap TcpStream::connect() and recv() in tokio::time::timeout (default 30s, configurable via ConfigBuilder::connection_timeout)
• New Error::ConnectionTimedOut variant for timeout errors

TCP keepalive

• Configure OS-level TCP keepalive on new connections via socket2 (default 60s interval, 10s probe interval, 3 retries)
• Configurable via ConfigBuilder::tcp_keepalive, set to None to disable

Pool health

• Wrap recycle() in a 5-second timeout — broken connections are evicted instead of blocking the pool forever
• Wire idle_timeout and max_lifetime through to deadpool's Pool::builder(), allowing automatic eviction of stale/old connections

New ConfigBuilder options

ConfigBuilder::new()
    .uri("bolt://localhost:7687")
    .user("neo4j")
    .password("password")
    .connection_timeout(Duration::from_secs(10))      // default: 30s
    .tcp_keepalive(Some(Duration::from_secs(30)))     // default: Some(60s)
    .idle_timeout(Some(Duration::from_secs(300)))     // default: None
    .max_lifetime(Some(Duration::from_secs(3600)))    // default: None
    .build()
    .unwrap();

Tests

7 new unit tests covering config defaults, custom timeout values, pool creation with timeout options, and error display. All 290 tests pass.

Dependencies

• Added socket2 = "0.5" (with all features) for TCP keepalive configuration

[madchicken]

It looks good on my side. @knutwalker please, take a look and merge it if you agree

[neo-walker]

Thanks for the PR, this looks good. I only got a small suggestions for API improvements.

For the builds, can you run cargo fmt and cargo xtask msrv min (might have to install jq for this) and commit the changes?

[neo-walker]

It looks good on my side. @knutwalker please, take a look and merge it if you agree

FYI, I am using a different account here, but I am still @knutwalker -- trying to get the old account back into this repo though :)

[ajmeese7]

Thanks for the PR, this looks good. I only got a small suggestions for API improvements.

For the builds, can you run cargo fmt and cargo xtask msrv min (might have to install jq for this) and commit the changes?

I can't get cargo xtask msrv min to work with my Rust v1.81 without updating pin_msrv_versions. I was able to get it to build with the following modifications:

fn pin_msrv_versions(dry_run: bool, sh: &Shell, cargo: &str, lockfile: &str) -> Result<()> {
    cmd!(sh, "rm {lockfile}").run_if(dry_run)?;

    let pin_versions: &[(&str, &str)] = &[
        ("backon", "1.5.2"),       // 1.6.0 bumped MSRV to 1.85
        ("idna_adapter", "1.2.0"), // 1.2.1 requires 1.82, transitive from url
        ("nalgebra", "0.32.6"),    // transitive requirement from nav_types,
+       ("serde_with", "3.16.1"),   // 3.17+ bumped MSRV to 1.82; 3.18+ requires time ~0.3.47 (edition2024)
+       ("time", "0.3.44"),        // 0.3.45+ pulls time-macros >=0.2.25 which needs edition2024
+       ("uuid", "1.20.0"),        // 1.21+ requires getrandom 0.4 which needs edition2024
+       ("deranged", "0.5.5"),     // 0.5.6+ bumped MSRV to 1.85
    ];

Not sure whether I should include this or leave it be. I did commit the resulting changes to the codebase from running that, but I haven't pushed the Cargo.lock.msrv, Cargo.lock.min, or main.rs changes.

[neo-walker]

Thanks, I'll take another look

Not sure whether I should include this or leave it be. I did commit the resulting changes to the codebase from running that, but I haven't pushed the Cargo.lock.msrv, Cargo.lock.min, or main.rs changes.

Can you please commit those as well? I try to keep the MSRV at or below what debian stable ships, which is 1.85 currently, but for now we're still on 1.81.

Those lockfiles and the version pins in the task are how we test MSRV compatibility. With the ecosystem moving along, we have to keep maintaining those.

[ajmeese7]

@neo-walker just pushed!

[neo-walker]

@ajmeese7 I noticed that you added socket2 in version 0.5 to the Cargo.toml, the latest is 0.6 (0.6.3), which also works with the MSRV. Is there a particular reason you chose 0.5 over 0.6?

[neo-walker]

Also looks like security-framework has to be pinned to 3.6.0 for MSRV

[neo-walker]

@ajmeese7 I just merged an update to the lockfiles and the version pins, can you rebase your PR? You can ignore the changes in the main.rs and the lockfiles from your side, and then re-run the xtask to update the lockfiles for the new dependency

[ajmeese7]

@neo-walker will do, have been without internet for a bit but it should be repaired soon!

[ajmeese7]

Should be handled @neo-walker, let me know if I need to do anything else