Add connection timeout (#179)

Thread lori's `ConnectionTimeout` through `ServerConnectInfo` to
`Session` so users can bound the TCP connection phase. Without this,
connections to unreachable hosts hang until the OS-level TCP timeout.

`ServerConnectInfo` gains an optional `connection_timeout` parameter
(default `None`). When set, lori fires `ConnectionFailedTimeout` if TCP
doesn't connect in time — the existing failure mapping (from PR #177)
delivers it to `pg_session_connection_failed`.

`_CancelSender` does not use the connection timeout — cancel connections
are fire-and-forget with no user callback, so a timeout would have no
observable effect.

Design: #72

Author: SeanTAllen

.release-notes/add-connection-timeout.md

@@ -0,0 +1,16 @@
+## Add connection timeout
+
+You can now set a timeout on the TCP connection phase by passing a `connection_timeout` to `ServerConnectInfo`. If the server is unreachable within the given duration, `pg_session_connection_failed` fires with `ConnectionFailedTimeout` instead of hanging indefinitely. Construct the timeout with `lori.MakeConnectionTimeout(milliseconds)`.
+
+```pony
+match lori.MakeConnectionTimeout(5000)
+| let ct: lori.ConnectionTimeout =>
+  let session = Session(
+    ServerConnectInfo(auth, host, port
+      where connection_timeout' = ct),
+    DatabaseConnectInfo(username, password, database),
+    notify)
+end
+```
+
+Without a connection timeout (the default), connection attempts have no time bound and rely on the operating system's TCP timeout behavior.

CLAUDE.md

@@ -136,7 +136,7 @@ Only one operation is in-flight at a time. The queue serializes execution. `quer
 - `CodecRegistry` class (val) — maps OIDs to text and binary `Codec` instances. Immutable — `with_codec(oid, codec)?` returns a new registry with the codec registered (partial — errors if OID is already registered, built-in or custom, or collides with a built-in or custom array OID). `with_array_type(array_oid, element_oid)?` registers a custom array type mapping (partial — errors if element_oid is an array OID, array_oid collides with a registered OID, array_oid is already a custom array OID, array_oid is already a custom element OID, or array_oid == element_oid). `array_oid_for(element_oid)` returns the array OID (built-in + custom, 0 if unknown). Supports chaining: `CodecRegistry.with_codec(600, A)?.with_array_type(1017, 600)?`. Default constructor populates all built-in codecs. `decode(oid, format, data)` is partial — returns `FieldData` for known OIDs, fallbacks for unknown OIDs (unknown text→`String`, unknown binary→`RawBytes`), and errors when a registered codec's `decode()` fails. Intercepts array OIDs before normal codec dispatch. `has_binary_codec(oid)` for format selection (includes array OIDs)
 - `ClientQueryError` — union type `(SessionNeverOpened | SessionClosed | SessionNotAuthenticated | DataError)`
 - `DatabaseConnectInfo` — val class grouping database authentication parameters (user, password, database). Passed to `Session.create()` alongside `ServerConnectInfo`.
-- `ServerConnectInfo` — val class grouping connection parameters (auth, host, service, ssl_mode). Passed to `Session.create()` as the first parameter. Also used by `_CancelSender`.
+- `ServerConnectInfo` — val class grouping connection parameters (auth, host, service, ssl_mode, connection_timeout). Passed to `Session.create()` as the first parameter. Also used by `_CancelSender`. Optional `connection_timeout: (lori.ConnectionTimeout | None)` bounds the TCP connection phase; if the timeout fires before a connection is established, `pg_session_connection_failed` is called with `ConnectionFailedTimeout`.
 - `SSLMode` — union type `(SSLDisabled | SSLPreferred | SSLRequired)`. `SSLDisabled` is the default (plaintext). `SSLPreferred` wraps an `SSLContext val` and attempts SSL with plaintext fallback on server refusal (`sslmode=prefer`). `SSLRequired` wraps an `SSLContext val` and aborts on server refusal.
 - `ErrorResponseMessage` — full PostgreSQL error with all standard fields
 - `AuthenticationFailureReason` = `(InvalidAuthenticationSpecification | InvalidPassword | ServerVerificationFailed | UnsupportedAuthenticationMethod)`
@@ -189,7 +189,7 @@ Codec-based decoding via `CodecRegistry.decode(oid, format_code, data)`. Extende
 
 Tests live in the main `postgres/` package (private test classes), organized across multiple files by concern (`_test_*.pony`). The `Main` test actor in `_test.pony` is the single test registry that lists all tests. Read the individual test files for per-test details.
 
-**Conventions**: `_test.pony` contains shared helpers (`_ConnectionTestConfiguration` for env vars, `_ConnectTestNotify`/`_AuthenticateTestNotify` reused by other files). `_test_response_parser.pony` contains `_Incoming*TestMessage` builder classes that construct raw protocol bytes for mock servers across all test files. `_test_mock_message_reader.pony` contains `_MockMessageReader` for extracting complete PostgreSQL frontend messages from TCP data in mock servers. `_test_codecs.pony` contains unit tests for binary/text codecs, `CodecRegistry`, `_ParamEncoder`, and binary-format bind wire format. `_test_array.pony` contains unit tests for `_ArrayOidMap`, binary/text array decode, `PgArray` equality/string, `_ArrayEncoder` roundtrips, `_ParamEncoder` with `PgArray`, `_FrontendMessage.bind()` with `PgArray`, `_FieldDataEq` extraction, `_NumericBinaryCodec` encode roundtrip, `CodecRegistry` array methods, and integration tests for array SELECT/roundtrip. `_test_statement_timeout.pony` contains unit tests for statement timeout timer lifecycle (fires on slow query, cancelled on normal completion) and integration test for pg_sleep with timeout.
+**Conventions**: `_test.pony` contains shared helpers (`_ConnectionTestConfiguration` for env vars, `_ConnectTestNotify`/`_AuthenticateTestNotify` reused by other files). `_test_response_parser.pony` contains `_Incoming*TestMessage` builder classes that construct raw protocol bytes for mock servers across all test files. `_test_mock_message_reader.pony` contains `_MockMessageReader` for extracting complete PostgreSQL frontend messages from TCP data in mock servers. `_test_codecs.pony` contains unit tests for binary/text codecs, `CodecRegistry`, `_ParamEncoder`, and binary-format bind wire format. `_test_array.pony` contains unit tests for `_ArrayOidMap`, binary/text array decode, `PgArray` equality/string, `_ArrayEncoder` roundtrips, `_ParamEncoder` with `PgArray`, `_FrontendMessage.bind()` with `PgArray`, `_FieldDataEq` extraction, `_NumericBinaryCodec` encode roundtrip, `CodecRegistry` array methods, and integration tests for array SELECT/roundtrip. `_test_statement_timeout.pony` contains unit tests for statement timeout timer lifecycle (fires on slow query, cancelled on normal completion) and integration test for pg_sleep with timeout. `_test_connection_timeout.pony` contains unit test for connection timeout (connects to non-routable address, verifies `ConnectionFailedTimeout` is reported).
 
 **Ports**: Mock server tests use ports in the 7669–7721 range and 9667–9668. **Port 7680 is reserved by Windows** (Update Delivery Optimization) and will fail to bind on WSL2 — do not use it.
 

examples/README.md

@@ -38,6 +38,10 @@ SSL-encrypted query using `SSLRequired`. Same workflow as `query` but with TLS n
 
 Query cancellation using `Session.cancel()`. Executes a long-running query (`SELECT pg_sleep(10)`), cancels it, and handles the resulting `ErrorResponseMessage` with SQLSTATE `57014` (query_canceled) in the `ResultReceiver`. Shows that cancellation is best-effort and arrives as a query failure, not a separate callback.
 
+## connection-timeout
+
+Connection timeout using the `connection_timeout` parameter on `ServerConnectInfo`. Connects to a configurable host and port with a 3-second timeout via `lori.MakeConnectionTimeout(3000)`, and handles `ConnectionFailedTimeout` in `pg_session_connection_failed`. Shows how the driver reports unreachable servers without hanging indefinitely.
+
 ## crud
 
 Multi-query workflow mixing `SimpleQuery` and `PreparedQuery`. Creates a table, inserts rows with parameterized INSERTs, selects them back, deletes, and drops the table. Demonstrates all three `Result` types (`ResultSet`, `RowModifying`, `SimpleResult`) and `ErrorResponseMessage` error handling.

examples/connection-timeout/connection-timeout-example.pony

@@ -0,0 +1,88 @@
+"""
+Connection timeout using the `connection_timeout` parameter on
+`ServerConnectInfo`. Connects to a configurable host and port with a 3-second
+timeout. If the server is unreachable within the timeout, the session reports
+`ConnectionFailedTimeout` via `pg_session_connection_failed`.
+"""
+use "cli"
+use "collections"
+use "constrained_types"
+use lori = "lori"
+// in your code this `use` statement would be:
+// use "postgres"
+use "../../postgres"
+
+actor Main
+  new create(env: Env) =>
+    let server_info = ServerInfo(env.vars)
+    let auth = lori.TCPConnectAuth(env.root)
+
+    let client = Client(auth, server_info, env.out)
+
+actor Client is SessionStatusNotify
+  let _session: Session
+  let _out: OutStream
+
+  new create(auth: lori.TCPConnectAuth, info: ServerInfo, out: OutStream) =>
+    _out = out
+    match lori.MakeConnectionTimeout(3000)
+    | let ct: lori.ConnectionTimeout =>
+      _out.print("Connecting with 3-second timeout...")
+      _session = Session(
+        ServerConnectInfo(auth, info.host, info.port
+          where connection_timeout' = ct),
+        DatabaseConnectInfo(info.username, info.password, info.database),
+        this)
+    | let _: ValidationFailure =>
+      _out.print("Failed to create connection timeout.")
+      _session = Session(
+        ServerConnectInfo(auth, info.host, info.port),
+        DatabaseConnectInfo(info.username, info.password, info.database),
+        this)
+    end
+
+  be pg_session_connected(session: Session) =>
+    _out.print("Connected.")
+
+  be pg_session_connection_failed(s: Session,
+    reason: ConnectionFailureReason)
+  =>
+    match reason
+    | ConnectionFailedTimeout =>
+      _out.print("Connection timed out.")
+    | ConnectionFailedDNS =>
+      _out.print("DNS resolution failed.")
+    | ConnectionFailedTCP =>
+      _out.print("TCP connection failed.")
+    | SSLServerRefused =>
+      _out.print("SSL refused by server.")
+    | TLSAuthFailed =>
+      _out.print("TLS authentication failed.")
+    | TLSHandshakeFailed =>
+      _out.print("TLS handshake failed.")
+    end
+
+  be pg_session_authenticated(session: Session) =>
+    _out.print("Authenticated.")
+    session.close()
+
+  be pg_session_authentication_failed(
+    s: Session,
+    reason: AuthenticationFailureReason)
+  =>
+    _out.print("Failed to authenticate.")
+
+class val ServerInfo
+  let host: String
+  let port: String
+  let username: String
+  let password: String
+  let database: String
+
+  new val create(vars: (Array[String] val | None)) =>
+    let e = EnvVars(vars)
+    host = try e("POSTGRES_HOST")? else "127.0.0.1" end
+    port = try e("POSTGRES_PORT")? else "5432" end
+    username = try e("POSTGRES_USERNAME")? else "postgres" end
+    password = try e("POSTGRES_PASSWORD")? else "postgres" end
+    database = try e("POSTGRES_DATABASE")? else "postgres" end

postgres/_test.pony

@@ -123,6 +123,7 @@ actor \nodoc\ Main is TestList
     test(_TestSSLCancelQueryInFlight)
     test(_TestCancelPgSleep)
     test(_TestCancelSSLPgSleep)
+    test(_TestConnectionTimeoutFires)
     test(_TestStatementTimeoutFires)
     test(_TestStatementTimeoutCancelledOnCompletion)
     test(_TestStatementTimeoutPgSleep)

postgres/_test_connection_timeout.pony

@@ -0,0 +1,49 @@
+use "constrained_types"
+use lori = "lori"
+use "pony_test"
+
+class \nodoc\ iso _TestConnectionTimeoutFires is UnitTest
+  """
+  Verifies that when a connection timeout is set and the server is unreachable,
+  pg_session_connection_failed fires with ConnectionFailedTimeout.
+  Connects to 192.0.2.1 (RFC 5737 TEST-NET-1, guaranteed non-routable).
+  """
+  fun name(): String =>
+    "ConnectionTimeout/Fires"
+
+  fun apply(h: TestHelper) =>
+    match lori.MakeConnectionTimeout(100)
+    | let ct: lori.ConnectionTimeout =>
+      let session = Session(
+        ServerConnectInfo(lori.TCPConnectAuth(h.env.root),
+          "192.0.2.1", "9999"
+          where connection_timeout' = ct),
+        DatabaseConnectInfo("postgres", "postgres", "postgres"),
+        _ConnectionTimeoutTestClient(h))
+      h.dispose_when_done(session)
+    | let _: ValidationFailure =>
+      h.fail("Failed to create ConnectionTimeout.")
+      h.complete(false)
+    end
+    h.long_test(5_000_000_000)
+
+actor \nodoc\ _ConnectionTimeoutTestClient is SessionStatusNotify
+  let _h: TestHelper
+
+  new create(h: TestHelper) =>
+    _h = h
+
+  be pg_session_connection_failed(s: Session,
+    reason: ConnectionFailureReason)
+  =>
+    match reason
+    | ConnectionFailedTimeout =>
+      _h.complete(true)
+    else
+      _h.fail("Expected ConnectionFailedTimeout but got different reason.")
+      _h.complete(false)
+    end
+
+  be pg_session_authenticated(session: Session) =>
+    _h.fail("Should not have connected.")
+    _h.complete(false)

postgres/server_connect_info.pony

@@ -4,16 +4,24 @@ class val ServerConnectInfo
   """
   Connection parameters needed to reach the PostgreSQL server. Grouped because
   they are always used together — individually they have no meaning.
+
+  An optional `connection_timeout` bounds the TCP connection phase. If the
+  timeout fires before a TCP connection is established, `pg_session_connection_failed`
+  is called with `ConnectionFailedTimeout`. Construct the timeout with
+  `lori.MakeConnectionTimeout(milliseconds)`.
   """
   let auth: lori.TCPConnectAuth
   let host: String
   let service: String
   let ssl_mode: SSLMode
+  let connection_timeout: (lori.ConnectionTimeout | None)
 
   new val create(auth': lori.TCPConnectAuth, host': String, service': String,
-    ssl_mode': SSLMode = SSLDisabled)
+    ssl_mode': SSLMode = SSLDisabled,
+    connection_timeout': (lori.ConnectionTimeout | None) = None)
   =>
     auth = auth'
     host = host'
     service = service'
     ssl_mode = ssl_mode'
+    connection_timeout = connection_timeout'

postgres/session.pony

@@ -20,6 +20,10 @@ actor Session is (lori.TCPConnectionActor & lori.ClientLifecycleEventReceiver)
   multiple queries are sent to the server in a single write and processed
   sequentially, reducing round-trip latency.
 
+  An optional connection timeout can be set via `ServerConnectInfo`. If the
+  TCP connection is not established within the given duration,
+  `pg_session_connection_failed` is called with `ConnectionFailedTimeout`.
+
   Most operations accept an optional `statement_timeout` parameter. When
   provided, the driver automatically sends a CancelRequest if the operation
   does not complete within the given duration. Construct the timeout with
@@ -45,7 +49,8 @@ actor Session is (lori.TCPConnectionActor & lori.ClientLifecycleEventReceiver)
       server_connect_info'.service,
       "",
       this,
-      this)
+      this
+      where connection_timeout = server_connect_info'.connection_timeout)
 
   be execute(query: Query, receiver: ResultReceiver,
     statement_timeout: (lori.TimerDuration | None) = None)