An HTTP client

The client half of net/http is http.Get for one call and http.Client for a program. A client owns a connection pool, a timeout and a policy of redirects, and the zero value is usable but has no timeout at all, which is the default worth changing first. The server in these programs is httptest.NewServer, which gives a real socket on a free port and closes it at the end.

http.Get

http.Get is DefaultClient.Get, and it returns a response whose body is a stream that the caller must read and close. The body is closed with a defer and read before the close, because a response that is closed unread cannot reuse the connection. The status and the text are the two things a caller checks.

package main import ( "fmt" "io" "net/http" "net/http/httptest" ) func main() { srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { fmt.Fprintln(w, "hello client") })) defer srv.Close() resp, err := http.Get(srv.URL) if err != nil { panic(err) } body, err := io.ReadAll(resp.Body) resp.Body.Close() if err != nil { panic(err) } fmt.Println("status:", resp.Status) fmt.Print("body: ", string(body)) }

go build -o app main.go && ./app

status: 200 OK
body: hello client

The server sent a plain text body and the client read it whole. A client that calls Get in a loop for different hosts creates a connection pool per host; a client value shared by the program reuses the connections, which is the difference between a few milliseconds and a few microseconds per call.

A client timeout

http.Client{Timeout: ...} bounds the whole call, from the dial to the last byte of the body. The server below sleeps twenty milliseconds and the client gives up after five, so the error is not nil and it wraps context.DeadlineExceeded. A client without a timeout waits forever on a server that accepts the connection and never answers.

package main import ( "context" "errors" "fmt" "net/http" "net/http/httptest" "time" ) func main() { srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { time.Sleep(20 * time.Millisecond) fmt.Fprintln(w, "slow") })) defer srv.Close() client := &http.Client{Timeout: 5 * time.Millisecond} _, err := client.Get(srv.URL) fmt.Println("failed:", err != nil) fmt.Println("timeout:", errors.Is(err, context.DeadlineExceeded)) }

go build -o app main.go && ./app

failed: true
timeout: true

The error is a *url.Error that wraps the deadline, so errors.Is is the test and the message is for a log. The timeout is not a retry policy: a call that timed out may have reached the server and changed its state, which is why the API lessons make a POST safe to repeat with an idempotency key rather than with a retry loop.

A request with a context

http.NewRequestWithContext builds a request that carries a deadline and a cancellation, and DefaultClient.Do sends it. The context of the caller is the one to pass, so a request cancelled by a user stops the outbound call too. The client below sets a header and the server echoes it back.

package main import ( "context" "fmt" "io" "net/http" "net/http/httptest" "time" ) func main() { srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { fmt.Fprintf(w, "token=%s\n", r.Header.Get("X-Token")) })) defer srv.Close() ctx, cancel := context.WithTimeout(context.Background(), time.Second) defer cancel() req, err := http.NewRequestWithContext(ctx, "GET", srv.URL, nil) if err != nil { panic(err) } req.Header.Set("X-Token", "secret") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } body, err := io.ReadAll(resp.Body) resp.Body.Close() if err != nil { panic(err) } fmt.Print("body: ", string(body)) }

go build -o app main.go && ./app

body: token=secret

The header arrived and the context bounded the call. A POST sends a body with bytes.NewReader or strings.NewReader and sets its content type, and a client that sends JSON twice a second keeps one *http.Client and one encoder rather than building a request per call from scratch.

A connection refused

A connection error arrives before any HTTP status exists, and it is also a *url.Error that wraps the system error. A program that wants to distinguish "the host is down" from "the host answered 500" tests with errors.Is against syscall.ECONNREFUSED or checks the type of the wrapped error, and prints the message for the log.

package main import ( "errors" "fmt" "net/http" "syscall" "time" ) func main() { client := &http.Client{Timeout: time.Second} _, err := client.Get("http://127.0.0.1:1/") fmt.Println("error:", err) fmt.Println("refused:", errors.Is(err, syscall.ECONNREFUSED)) }

go build -o app main.go && ./app

error: Get "http://127.0.0.1:1/": dial tcp 127.0.0.1:1: connect: connection refused
refused: true

Port 1 has nothing listening, so the dial failed at once. The message names the request, the address and the system error, and the errors.Is line is the machine-readable form. A service maps a refused connection to a 503 and a timeout to a 504, and keeps the text for the log.

The client a service needs

Four settings make a client safe in a service. A timeout on the client value. A shared client, not a new one per call, so connections are reused. A context on every request, taken from the incoming request. And a check of the status before the body, because a 500 with an HTML error page parses as a successful call if nobody looks. The transport behind the client can also set a connection limit per host, which is the backpressure of the outbound side.

The next lesson builds the JSON API both sides of a call, and the capstone service uses this client in its tests and its handlers. A test that needs a server uses httptest.NewServer, exactly as these programs do.

Exercises

  1. Remove the io.ReadAll and close the body at once. What does the client do with the connection, and how would a second request show it?
  2. Set the client timeout to one second and the handler sleep to twenty milliseconds. What does the error become, and what does errors.Is report?
  3. Send a POST with a JSON body and a content type. What does the server read first, and what does it do with a body that is not valid JSON?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is http.Get?

    Answer

    DefaultClient.Get with the request and the body

    A client value is the configurable form.

  2. What must happen to a response body?

    Answer

    It must be read and closed

    An unread body blocks connection reuse.

  3. What does Client.Timeout cover?

    Answer

    The whole call, from the dial to the last byte

    A context bounds a single request the same way.

  4. What does a timeout error wrap?

    Answer

    context.DeadlineExceeded

    errors.Is is the test.

  5. What does NewRequestWithContext add?

    Answer

    A deadline and cancellation from the caller

    The caller's context reaches the outbound call.

  6. What does a connection refused error wrap?

    Answer

    syscall.ECONNREFUSED

    The dial failed before any HTTP status.

  7. Why share one http.Client?

    Answer

    It reuses connections between calls

    A pool per host lives in the client.

  8. When should a client check the status?

    Answer

    Before reading the body

    An error page is not the data the caller expects.

  9. Which error does a refused connection map to in a service?

    Answer

    503

    A timeout maps to 504.

  10. What does httptest.NewServer give?

    Answer

    A real server on a free port with a URL

    Close stops it at the end of the test.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev