Skip to content

Bound the whole connection attempt by connect_timeout - #48

Merged
quinnj-bot[bot] merged 3 commits into
mainfrom
claude/connect-timeout-whole-attempt
Nov 10, 2026
Merged

quinnj-bot[bot] merged 3 commits into
mainfrom
claude/connect-timeout-whole-attempt

Conversation

@quinnj-bot

@quinnj-bot quinnj-bot Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Why

connect_timeout bounded only the TCP connect, plus a fresh timer for the TLS handshake. A server that accepted the connection and then stalled blocked Postgres.Connection, a reconnect=true reconnect, or cancel_query! with no limit. The server might stall before answering SSLRequest, during startup or authentication, or before ReadyForQuery. A pool checkout against an overloaded or unreachable server hung the same way. libpq's connect_timeout bounds the whole attempt, and this change does the same.

What changed

  • Each connection attempt computes one deadline when it starts. The TCP dial gets it (deadline_ns), and it stays on the socket as the read and write deadline through GSS or TLS negotiation, startup, authentication and session setup. A server that stalls at any stage fails the attempt after about connect_timeout in total. The TLS handshake no longer gets its own fresh timer.
  • The deadline is cleared before the connection is returned, on every success path (_startup!), the reconnect in checkconn included. Otherwise it would cut off a later statement.
  • A timeout at any stage, the dial included, throws Postgres.Error("timeout expired while connecting to host:port") instead of a Reseau OpError, TLSHandshakeTimeoutError or TLSError. cancel_request uses the same deadline: a dial timeout throws that error, and a stall later returns false, as other cancel failures already do.
  • The comment above check_mode now says libpq compares sslmode/gssencmode exactly (follow-up from the Validate sslmode and gssencmode at parse time and in the constructor #47 review).

Scope

  • One window per attempt. Postgres.jl connects to one host. When the host name resolves to several addresses, Reseau's dialer tries them within that one window. Unlike libpq, which gives each address its own window and moves to the next address when a later stage fails, Postgres.jl has never fallen back to another address after the TCP connect, and this PR does not add that.
  • Under gssencmode=prefer, the second dial after a failed GSS attempt shares the deadline. libpq does the same for one address.
  • connect_timeout of 0 or less means no limit, as in libpq. A negative value used to fail in the TLS configuration.
  • Kerberos traffic to the KDC inside the GSSAPI library is still not bounded (docs/src/support.md already says so).
  • Built on main at 3d8ba83, which includes Validate sslmode and gssencmode at parse time and in the constructor #47. Both PRs change API.connect.

Blast Radius

The change affects every connect, reconnect and cancel that sets connect_timeout; without connect_timeout nothing changes.

  • Code that caught Reseau's dial-timeout OpError or TLSHandshakeTimeoutError now gets Postgres.Error.
  • Authentication now counts toward the window, as in libpq, so a slow SCRAM or GSS exchange with a very small connect_timeout can now time out.
  • API.connectsocket (internal) now takes the attempt's deadline instead of seconds. Its keyword form, which had no callers, is removed.
  • docs/src/support.md said that connect_timeout does not bound authentication; it now describes the new behavior.

Most of the API.connect diff is reindentation from the new outer try. Review it with whitespace ignored.

Verification

  • Scripted servers with connect_timeout=1. On main (3d8ba83), silent after accept, an unanswered SSLRequest, and cancel_request were all still waiting after 8 s. A stalled TLS handshake threw Reseau's TLSHandshakeTimeoutError after 1.11 s. Two stages of 0.6 s each connected after 1.37 s. A dial to 10.255.255.1 threw a Reseau OpError after 1.16 s. With this PR, every case throws Postgres.Error "timeout expired" after 1.04 to 1.10 s, cancel_request returns false after 1.05 s, and a statement run 1.5 s after connecting succeeds.
  • A fresh process with connect_timeout=1 against postgres:16 with SCRAM: the first connection succeeds, so first-call compilation does not eat the window.
  • New fake-server tests (test/connect_timeout_fake_server.jl, plus a stalled GSS handshake in test/gssapi.jl). Full Pkg.test() on Julia 1.12.6 (macOS arm64) with the Docker integration (postgres:16) and the trim compile test: 9949/9949, which is main's 9919 plus the 30 new checks.

🤖 Generated with Claude Code

quinnj and others added 3 commits November 10, 2026 13:16
Scripted servers stall after accepting, before answering SSLRequest, during
the TLS and GSS handshakes, and across two stages that each answer within
the timeout. Each attempt must fail with "timeout expired" within about
connect_timeout. A statement run after connect_timeout has passed must
still succeed, on a fresh connection and after a reconnect, and
cancel_request must give up on a stalled server.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
connect_timeout bounded only the TCP connect and, with a fresh timer, the TLS
handshake. A server that accepted the connection and then stalled before
answering SSLRequest, startup or authentication blocked the connect, a
reconnect, or cancel_query! indefinitely.

Each attempt now gets one deadline, as libpq's connect_timeout does. The
dial uses it, and it stays on the socket as the read and write deadline
through GSS or TLS negotiation, startup, authentication and session setup.
The deadline is cleared before the connection is returned, so it cannot cut
off a later statement. A timeout at any stage throws Postgres.Error
"timeout expired" instead of a Reseau error. cancel_request uses the same
deadline.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
libpq compares sslmode and gssencmode exactly (strcmp in connectOptions2).
Postgres.jl compares them case-insensitively.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@quinnj-bot
quinnj-bot Bot merged commit 1e09ff7 into main Nov 10, 2026
16 checks passed
@quinnj-bot quinnj-bot Bot mentioned this pull request Nov 10, 2026
quinnj referenced this pull request Nov 10, 2026
Co-authored-by: Jacob Quinn <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant