Timeouts
Most important commands to remember
curl --connect-timeout— bound connection establishment.curl --max-time— bound the complete transfer.curl --write-out— inspect elapsed timing even when a transfer fails.
Commands and flags
| Command or syntax | Meaning |
|---|---|
--silent --show-error |
Hide progress but retain curl errors. |
--connect-timeout 1 |
Allow one second for the connection phase. |
--max-time 2 / 10 |
Allow two / ten seconds for the complete transfer. |
--output /dev/null |
Discard the response body. |
--write-out '…' |
Print timing fields after the attempt. |
time_connect / time_starttransfer / time_total |
Seconds from start to connection, first response byte, and completion or failure. |
printf … "$?" |
Print the immediately preceding command’s exit status. |
The quoted format uses curl fields and newline syntax. A transport-success exit status is not an HTTP application-success check; this example does not use HTTP fail-on-error behavior.
The concepts that matter
1. A timeout bounds how long one participant waits
A timeout limits waiting for an operation or phase. It prevents a caller from holding resources indefinitely when a dependency is slow or unreachable.
The limit belongs to that caller. It does not necessarily stop the remote service, cancel database work, or undo an action already performed. Treat a timeout as an incomplete observation of the outcome, not a universal statement that nothing happened.
2. Connection time and response time are different
Connection establishment can include name resolution and the required transport or security handshakes. After connecting, a server can still take a long time to produce a response or finish transferring it.
A connection timeout therefore does not bound the whole request. Use a total limit as well when the caller needs an overall bound. The timing phases help distinguish slow setup from waiting after a connection already exists.
3. Deadlines should cover the complete call chain
If a user request has a total budget, downstream calls must fit within the remaining time. Giving each nested call a fresh full timeout can make the overall request far exceed the intended budget.
A deadline represents the point after which the result is no longer useful. Propagating remaining budget and cancellation where supported helps stop unnecessary work. Queue waiting and retries also consume time; they do not happen outside the user’s experience.
4. Timeout choice balances patience and resource use
Too short a limit rejects useful work during normal variation. Too long a limit keeps callers, connections, and memory occupied during failure. Base the choice on observed latency and the operation’s purpose.
After a timeout on a state-changing operation, reconcile its status or use a suitable idempotency design before retrying. A second attempt can otherwise repeat an action whose response was lost. Read-only examples avoid that business-effect ambiguity while demonstrating waiting behavior.
One small example
Optional: use the existing five-second test endpoint. Run each curl and its following printf together. The endpoint must already exist; these commands do not create a delay server.
curl --silent --show-error --connect-timeout 1 --max-time 2 --output /dev/null --write-out 'connect=%{time_connect}s first_byte=%{time_starttransfer}s total=%{time_total}s\n' http://localhost:8080/slow
printf 'curl_exit=%s\n' "$?"
curl --silent --show-error --connect-timeout 1 --max-time 10 --output /dev/null --write-out 'connect=%{time_connect}s first_byte=%{time_starttransfer}s total=%{time_total}s\n' http://localhost:8080/slow
printf 'curl_exit=%s\n' "$?"With the stated delay, the first attempt should hit its two-second total limit despite connecting quickly; curl normally reports timeout status 28. The longer attempt can receive the response if the service completes within its budget.
Compare connection and total times. A first-byte value of zero on a failed attempt can mean no response byte arrived, not instantaneous server processing. Exact elapsed values vary. A connection-refused error means the fixture is unavailable and does not demonstrate a slow response. The client creates no persistent files.
Keep this idea: A timeout ends your wait; it does not prove the remote operation failed or never ran.