Go’s http.Server can reject incomplete request headers after ReadHeaderTimeout expires. What happens if a client sends valid headers in time and then takes much longer to deliver the body? At the end of the headers, the server resets the header read deadline. The remaining time for a body read depends on ReadTimeout and any deadline the handler sets. A limit on body size answers a separate question: how many bytes will the handler accept? The five cases below use a controlled fixture to distinguish those boundaries.
Following Refonte’s Kubernetes ConfigMap application adoption playbook, each case pairs a synthetic server configuration with a client pattern and an expected result. All five cases and sample logs in this article are EXPECTED / NOT EXECUTED.
Case C1 (RH-only): With ReadHeaderTimeout set to 5s and ReadTimeout set to zero, the client delivers complete headers promptly and sends body bytes at two-second intervals. The body is expected to finish even though the total request takes longer than five seconds.
Case C2 (RH+RT): With ReadHeaderTimeout set to 5s and ReadTimeout set to 30s, the manifest specifies a body that is still incomplete at the full-request deadline. The pending server-side read is expected to time out.
Case C3 (RT-only): With ReadHeaderTimeout set to zero and ReadTimeout set to 5s, the header read inherits the five-second budget. If the headers remain incomplete when it expires, the handler should never receive the request.
Case C4 (no timeouts): Both timeouts are zero. The small, finite request should complete normally. This is the negative control.
Case C5 (MaxBytes): The handler wraps the body in http.MaxBytesReader with a 10-byte limit. Reading past 10 bytes should produce a MaxBytesError. The handler can translate that error into an HTTP 413 response.
Each case is identified (C1–C5) and includes the fixture setup, the slow-client steps, and the expected server response. The evidence for each case (logs, errors) will later be compared to this independent manifest to decide pass/fail.
1. Define the operational contract
We view the server as a state machine with two sequential phases: headers and body. The acceptance criteria are:
Header phase: If headers arrive slower than ReadHeaderTimeout, the server must terminate the connection. If headers arrive in time, the server then accepts the request.
Body phase: After headers are accepted, the service needs a time budget if it intends to bound how long a body read can occupy a connection. A byte limit can independently bound how much data the handler consumes. ReadHeaderTimeout alone supplies no body-read deadline.
We outline our test cases clearly:
Case C1 (RH-only): Server sets ReadHeaderTimeout=5s and no ReadTimeout. Client immediately sends a full header (so header-phase passes) then sends a 10-byte body, one byte every 2s. Expected outcome: the server does not time out on the body; the connection remains open for the full ~20s. Any timeout would violate the documented contract that ReadHeaderTimeout only applies to headers.
Case C2 (RH+RT): The server sets ReadHeaderTimeout=5s and ReadTimeout=30s. The manifest uses a body whose scheduled delivery extends beyond 30 seconds. Because ReadTimeout applies to the whole request, including the body, a read that still needs data when the deadline expires should return a timeout error. The shorter C1 body would finish within this budget.
Case C3 (RT-only): Server sets ReadTimeout=5s and no ReadHeaderTimeout. Client sends headers slowly, exceeding 5s. Expected: server times out during headers at ~5s (since ReadTimeout covers headers when ReadHeaderTimeout is zero).
Case C4 (No timeouts, small body): No timeouts at all, small body. Expected: connection completes normally without closure (negative control).
Case C5 (MaxBytes cap): The handler wraps r.Body in http.MaxBytesReader(w, r.Body, N). A large declared length alone does not trigger the error. The wrapper allows N bytes and reports a MaxBytesError when the handler attempts to read beyond that limit and excess data is present. If the handler maps that error to HTTP 413, capture the response separately.
We will capture evidence for each case (e.g. server log entries, client errors) labeled by case ID. The evidence ledger will later verify whether each case met its contract. If any case deviates (e.g. C1 times out unexpectedly), we flag it. This explicit contract mirrors the rigor in the ConfigMap adoption test: each input and expected output is defined before running tests.
2. Documented baseline and scope
Go’s net/http documentation describes what happens to the connection’s read deadline after the server parses the headers.
ReadHeaderTimeout sets the time allowed to read the headers. Once they are read, the server resets the deadline and the handler can apply its body-read policy. A zero value uses ReadTimeout. A negative value disables the header timeout, as does zero when ReadTimeout is also zero or negative.
ReadTimeout covers a longer interval.
A positive ReadTimeout bounds the time available to read the entire request, including its body. A value of zero or less disables this whole-request timeout.
With both settings at zero and no other deadline, a body read can wait indefinitely for the next byte. Safeguard’s guide to Go HTTP server timeouts points out a tradeoff for legitimate uploads: a whole-request deadline can cut off a slow upload. A service that needs different budgets for different requests can set ReadHeaderTimeout and let its handler choose a body-read deadline.
MaxHeaderBytes limits the size of the request line and headers. For the body, http.MaxBytesReader limits how many bytes a reader may consume. Reading past the limit returns a MaxBytesError. Neither byte limit sets a deadline.
The fixture isolates HTTP/1.1 request reads with a fixed Content-Length. It excludes chunked bodies, WriteTimeout, IdleTimeout, TLS handshakes and high-level middleware. Compare any unexpected deadline with the documented settings and the captured configuration before drawing a conclusion.
Version and environment fingerprint
The target fixture is Go 1.27 on Linux/AMD64. At test start, save the exact go version and go env output. For example, go version go1.27.4 linux/amd64 would identify a particular toolchain and platform in evidence/version.txt. A run on Go 1.26 or Windows is a different experiment. If the recorded environment differs from the declared fixture, qualify the result and rerun against the intended version.
3. Pin versions and build an isolated fixture
Create a disposable Go module and record the toolchain build information. The go directive declares the minimum Go version. The exact toolchain used for the run belongs in the environment record.
module github.com/example/timeouttest
go 1.27No external dependencies are needed beyond the standard library. We compile and run this fixture with go build or go run on a clean host. This fixture listens on localhost (choose an ephemeral port) to avoid interfering with any other services. It has debug logging enabled (e.g. print timestamps when reading headers/body). For example, our server.go might include:
srv := &http.Server{
Addr: "127.0.0.1:8080",
ReadHeaderTimeout: 5 * time.Second,
Handler: http.HandlerFunc(echoHandler),
// (initially no ReadTimeout in C1)
}Start the server in an isolated network namespace or container. The SQLite WAL checkpoint playbook, for example, fixed SQLite 3.54.1 and worked in a disposable database. Here the intended series is Go 1.27. Verify the exact toolchain with go version, keep the loopback path free of intermediary proxies, and record the source commit or binary hash as the fixture identity. Capture commands and outputs under evidence/.
Finally, before each run we ensure no other process listens on the test port (or pick a random free port in code). Each server instance is terminated cleanly after its case. This isolation ensures no residual state leaks between cases.
4. Write an independent expected-case manifest
Before running any tests, we author a manifest of expected outcomes for each case. This manifest is independent of actual results, to avoid bias. For example, in JSON form:
{
"cases": [
{"id": "C1", "setup": {"ReadHeaderTimeout": "5s", "ReadTimeout": "0s"},
"clientPattern": "fast headers, body 1B/2s (10 bytes total)",
"expected": {"bodyTimeout": false, "complete": true}},
{"id": "C2", "setup": {"ReadHeaderTimeout": "5s", "ReadTimeout": "30s"},
"clientPattern": "fast headers, body 1B/3s (15 bytes)",
"expected": {"timeoutOccurred": true, "complete": false}},
{"id": "C3", "setup": {"ReadHeaderTimeout": "0s", "ReadTimeout": "5s"},
"clientPattern": "header lines with 2s delay",
"expected": {"timeoutDuringHeaders": true}},
{"id": "C4", "setup": {"ReadHeaderTimeout": "0s", "ReadTimeout": "0s"},
"clientPattern": "immediate small request",
"expected": {"complete": true, "noTimeout": true}},
{"id": "C5", "setup": {"MaxBytes": 10, "ReadTimeout": "0s"},
"clientPattern": "fast headers, body 20B at 1B/s",
"expected": {"maxBytesError": true}}
]
}Each entry specifies the server setup, the client’s slow-send pattern, and exactly what we expect. We include negative controls (e.g. C4) to assert normal behavior.
Assert the expected negative case
For C4, record the expected success response as well as the absence of a timeout. A response log or a captured client response can establish that the request actually completed. An early closure or a timed-out read would fail this control. A missing log line on its own says little about what happened.
5. Reproduce the misleading success signal
Case C1 illustrates why a successful response can be a misleading signal. This example uses only the header timeout. The command and output show the intended setup (EXPECTED / NOT EXECUTED).
# Case C1: only header timeout
$ go run server.go -addr=127.0.0.1:8080 -rh=5s -rt=0s &
Server: started on 127.0.0.1:8080Consider the shorter C1 example: the headers arrive promptly, and the five-byte body arrives over about ten seconds. The client trace and server trace must refer to the same TCP connection.
POST /test HTTP/1.1
Host: localhost
Content-Length: 5The header excerpt identifies the request. Separate invocations of nc open separate connections, so a header write in one invocation and later body writes in others cannot establish that this request completed.
The server’s logs (redirected to evidence/server_C1.log) might look like:
Server: Begin reading request at 2026-11-19T10:01:00
Server: Headers accepted at 2026-11-19T10:01:00 (within 5s limit)
# (No deadline was set for the body, since ReadTimeout=0)
Server: Finished reading body (5 bytes) at 2026-11-19T10:01:10
Server: Wrote response at 2026-11-19T10:01:10The corresponding illustrative client trace would show completion:
Client: wrote last chunk at 2026-11-19T10:01:10
Client: Received response, no errorThis ten-second exchange is EXPECTED / NOT EXECUTED. If the actual logs show five body bytes consumed and a completed response, C1 would pass its behavioral check: the header timeout did not interrupt the body. The same evidence would leave the service’s requirement for a body-read deadline unmet. A successful read alone cannot establish that a deadline was enforced.
6. Run a controlled comparison case
The C2 manifest assigns 30 seconds to the entire request. For comparison, the original five-byte example can also be evaluated against a shorter, 15-second whole-request deadline. The following configuration and outcomes are illustrative (EXPECTED / NOT EXECUTED).
# Case C2: header + full timeouts
$ go run server.go -addr=127.0.0.1:8080 -rh=5s -rt=15s &
Server: started on 127.0.0.1:8080With prompt headers and a five-byte body delivered over roughly ten seconds, the shortened request should still finish within the 15-second budget. Its expected client result is:
Client: wrote final byte within the 15s budget
Client: received responseIf the server instead still has a pending read when the 15-second budget expires, its log might look like this:
Server: Begin reading at 2026-11-19T10:01:00
Server: Timeout after 15s while reading body at 2026-11-19T10:01:15The decisive fact is whether the server still needs body data when the deadline expires. The five-byte illustration and the longer C2 manifest case have different expected outcomes. This follows the same reasoning as Refonte’s requestAnimationFrame resume comparison: identify the condition that changes the expectation. Save the actual C2 server trace in evidence/server_C2.log and compare it with the manifest.
Distinguish absent evidence from failure
For C1, a missing timeout entry is meaningful only alongside evidence that the server finished reading the body. For the over-budget C2 case, look for a server-side read error while the body is incomplete. A missing timeout message on its own can also mean that the logger missed the event or the input finished early. RERUN if the trace cannot distinguish these possibilities.
7. Test negative controls and boundary conditions
We verify cases that should definitely pass or fail to sanity-check the fixture. For example:
C4 (no timeouts, small body): We run with ReadHeaderTimeout=0, ReadTimeout=0. The client sends 0-byte body (Content-Length:0). We assert the server responds immediately (2xx code) and no “timeout” appears. This normal case (negative control) should always succeed. If it fails, our test is broken.
Size boundaries with MaxBytesReader: With a 10-byte cap, a complete 10-byte body should succeed. An attempted read of an eleventh byte should return a MaxBytesError. Check separately whether the handler translates that error into HTTP 413.
Empty body vs non-empty: We test Content-Length 0 and 1 to ensure minimal bodies don’t accidentally time out.
At the deadline: An optional case finishes sending the body close to ReadTimeout. Capture when the server read completed and whether data was already buffered. A client timestamp alone cannot settle which event happened first.
These controls ensure our system works. No contradictory evidence should appear: e.g. C4 must not time out. If any control case fails, we must investigate infrastructure (socket hangs, buffer issues, etc.) rather than assume a Go bug.
8. Capture raw evidence before cleanup
Before tearing down servers or connections, we capture all raw output. We redirect server and client logs to files named by case: for instance, evidence/C1-server.log, evidence/C1-client.log, etc. This archival includes timestamps, error messages, and content of any “Timeout” or MaxBytesError. It is crucial that these logs are not altered or summarized: they are the source of truth. For example, after finishing Case C1, we check:
$ cat evidence/C1-server.log
(Server began reading headers...)Keep the logs when moving to the next case. Preserve unexpected output, including an error in a case expected to pass, so that it can be investigated. Also capture go version and go env in evidence/00-environment.txt. Keep the raw evidence until the release decision.
Preserve contradictory observations
We assert that no evidence is discarded. If C1 unexpectedly showed “timeout” (contradicting our manifest), we would not remove that from the log; we would instead mark the run as a failure of either the code or our understanding. In practice, we might prefix evidence lines with case IDs to avoid confusion (e.g. C1:). This way, if we see a log line like “ERROR: i/o timeout” under C1, we immediately know something is wrong. Preserving such contradictions is essential: it prevents “sweeping anomalies under the rug” and helps determine if a failure is due to environment flakiness or a real code issue.
9. Reconcile state, identity and completeness
After each test, we restore the environment to a known idle state. For example, we kill the server process and verify with lsof or netstat that the port is freed. We also confirm the server’s static configuration (headers read, timeouts set) matches what we intended: e.g. Expected: ReadHeaderTimeout=5s (evidence: server log entry or code snippet). We record identity details such as the exact Go commit or module version (go.mod) used. This is analogous to the partial-index UPSERT playbook, which kept a version.txt and schema evidence. In our case, the evidence files themselves (like version.txt, go.mod, and server logs) serve this purpose.
Record every planned case in a ledger and mark completed runs PASS or FAIL against their assertions. Keep EXPECTED / NOT EXECUTED for a case that never ran. If the server crashed or its log is missing, record the interruption and keep any partial evidence. Rerun the case under the same conditions before using it for a release decision.
10. Separate normative guarantees from observations
For C1, the documented configuration leaves the body without a server read deadline. A complete body read after the header budget has elapsed would agree with that expectation. A timeout at 20 seconds would need investigation: check the effective settings, any handler deadline and which endpoint reported the error before attributing it to Go. Record the documented expectation and the actual observation in separate columns.
The ledger below shows how to record the deadline and byte-limit cases while their outcomes are still unverified.
Case | Documented behavior | Evidence status | Decision |
C1 | No body deadline from ReadHeaderTimeout alone | EXPECTED / NOT EXECUTED | HOLD |
C2 | 30s budget for the entire request | EXPECTED / NOT EXECUTED | HOLD |
C5 | Error on reading past 10 bytes | EXPECTED / NOT EXECUTED | HOLD |
If any observed behavior falls outside these norms, it becomes the highest-priority item (possibly FAIL). We do not “massage” results. Documented behavior remains the benchmark.
Bound the repair and its risks
If a case appears to miss its deadline, check the configured budget against the actual request duration before changing the server. A 30-second ReadTimeout permits a 15-second body read, or even a 25-second upload, if enough time remains after the headers. An upload that needs more than the remaining budget can be interrupted. As with Kubernetes maxSkew and DoNotSchedule, a stricter setting can exclude legitimate work.
We capture our chosen fix (e.g. ReadTimeout=30s) and note: If a slow, legitimate client needs more than 30s, it will now fail. We treat this as a known risk. The resolution is documented alongside evidence. In practice we bound the repair by choosing a timeout large enough to cover intended use (e.g. 30s) but small enough to limit an attack. Our evidence will show exactly when the new timeout triggered, so we can adjust if needed.
11. Apply the smallest safe repair
For a service that requires a single time budget for request reads, the smallest configuration change in this fixture is a positive ReadTimeout. For example:
srv := &http.Server{
Addr: "127.0.0.1:8080",
ReadHeaderTimeout: 5 time.Second,
ReadTimeout: 30 time.Second, // added ReadTimeout
Handler: http.HandlerFunc(echoHandler),
}This change applies a whole-request read deadline, as described in Cloudflare’s guide to Go HTTP timeouts. Rebuild the fixture and rerun the five cases with their intended configurations preserved. Keep the repaired C1 alongside its original baseline: its roughly 20-second body fits within 30 seconds. The over-budget C2 case checks that a pending body read can actually expire.
For instance:
# After repair:
$ go run server.go -addr=127.0.0.1:8080 -rh=5s -rt=30s &
Server: started on 127.0.0.1:8080For a request still incomplete when the 30-second budget expires, the server-side log might show the following (EXPECTED / NOT EXECUTED):
Server: Headers accepted at ...
Server: Timeout after 30s during body at ...Record the server’s read error and the client’s response or connection error separately. The server deadline does not establish which byte the client last wrote. For the original C1 input, expect a normal completion within the new budget. Accept the repair only when the in-budget examples complete, the over-budget case records the expected error, and the independent controls still pass.
This repair changes only the server configuration. The handler and the declared case inputs can stay the same.
12. Test recovery, rollback and rerun safety
With the fix applied, we systematically rerun the tests to confirm no regressions. We verify:
Cases C1 and C2: The repaired C1 request should complete within the added 30-second budget. C2’s longer request should time out while the server is still reading the body.
Case C3: should still time out on headers.
Case C4: still succeeds (no timeouts, no change).
Case C5: MaxBytes behavior is unchanged by our ReadTimeout fix, so it should still error after 10 bytes.
For each rerun, capture new logs. If a control such as C4 acquires a timeout despite its unchanged configuration, record a failure and check how the fixture selected its settings. Roll back or adjust the change as needed and mark the affected cases for RERUN.
For rollback, restore ReadTimeout to zero and verify the setting in the new server process. The original C1 body should complete both before and after rollback because it fits within 30 seconds. To tell the configurations apart, compare the longer, over-budget case as well and preserve both sets of logs.
This approach is akin to the Kubernetes topology testing which rebuilds a synthetic cluster after making changes. Here our “cluster” is just the server process: we ensure that starting and stopping it around our fix is repeatable and leaves no stray state. Each run begins with a fresh process and each case is independent.
Assign ownership and rerun triggers
Finally, we embed this test suite into development practices. The ownership should lie with the backend/infra team responsible for the HTTP service. They must maintain the fixture code and expected-manifest as part of the project’s test suite. The rerun triggers include: any update to Go itself (e.g. a minor release), changes to net/http code, or alterations to server configuration. For example, if Go 1.28 is released or the code modifies server timeouts, the CI pipeline should rerun these tests to catch any shift in behavior.
In documentation, we state: “If net/http is upgraded or server timeout settings change, the acceptance tests in this playbook must be rerun”. We also note responsibility: e.g., the platform lead or SRE team is assigned to interpret results and take action. If tests ever FAIL, the ticket is assigned to the backend developer to RERUN/REPAIR (or HOLD if the test itself seems flaky).
13. Make the ACCEPT / REPAIR / RERUN / HOLD decision
The following decisions are conditional. The case inputs and illustrative traces define what evidence would support each decision.
C1 (RH-only): A completed read beyond the header deadline would match the Go contract. If the service requires a time limit for uploads, choose REPAIR. ACCEPT the revised configuration once the in-budget request and over-budget comparison both meet their assertions.
C2 (RH+RT): ACCEPT if the over-budget request produces a server-side body-read timeout around the configured 30-second deadline.
C3 (RT-only): ACCEPT if incomplete headers time out around five seconds and the handler is never entered.
C4 (no timeouts): ACCEPT if the small request completes normally.
C5 (MaxBytes limit): ACCEPT if the reader permits 10 bytes and reports a MaxBytesError on the attempted excess read. Verify HTTP 413 separately if it is part of the handler contract.
The planned release decision is ACCEPT with the ReadTimeout repair if the raw evidence supports all five cases. RERUN a case when its input, configuration or logs cannot establish what happened. Choose REPAIR when a reproducible result shows that the service misses its operational contract.
The current release decision is HOLD. All five cases are EXPECTED / NOT EXECUTED. Once the runs are complete, retain the evidence files with the decision and record the accepted upload deadline in the deployment guidelines.
14. Backend testing and deployment skills
Refonte Learning’s Backend Developer program is a three-month, part-time course requiring 10–12 hours per week. It covers server-side frameworks, databases and system design, including Node.js, Express, MongoDB, SQL and RESTful API design. Students earn a Training Certificate upon completion and an Internship Certificate for the practical projects.
The program’s testing, debugging and deployment modules provide a setting for the work illustrated here: defining a contract, writing independent tests and deciding whether the evidence supports a release. Hands-on labs and mentor guidance extend those skills to other backend services.
