These are the notes for Go episode 63. In episodes 61 and 62 we built HTTP servers. Now Raju's shop app has to call other people's servers: a payment gateway and a delivery partner's API. A program that sends requests is a client. We find the two traps inside http.Get, fix them with an http.Client that has a timeout, see why you must close resp.Body, look under the hood at the http.Transport and its connection pool, then learn to retry safely (exponential backoff, jitter, idempotency keys), when to stop calling a broken service (circuit breaker), and how a client stays logged in (cookie jars).
All outputs are from real runs (Go 1.24.7, linux/amd64). Ports, random waits and some connection counts change between runs.
Facts and sources
- The complete guide to Go net/http timeouts (Cloudflare blog, Filippo Valsorda, 29 June 2016): package-level functions such as
http.Get"use a Client without timeouts", which makes them "dangerous to use on the open Internet". go doc net/http(Go 1.24.7):const DefaultMaxIdleConnsPerHost = 2("the default value of Transport's MaxIdleConnsPerHost");DefaultClientis the client used byGet,HeadandPost; aClient.Timeoutof zero means no timeout.- Everything else is from the real runs below.
The two traps in http.Get
Real-life example: Raju's app asks the payment gateway to charge ₹500. The gateway accepts the connection and then says nothing. Every customer at the counter waits, because of someone else's server. In real life you'd hang up after 30 seconds of ringing.
package main
import (
"fmt"
"net/http"
"net/http/httptest"
"os"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("GET /stuck", func(w http.ResponseWriter, r *http.Request) {
<-r.Context().Done() // a broken server that never answers
})
srv := httptest.NewServer(mux)
defer srv.Close()
resp, err := http.Get(srv.URL + "/missing") // pitfall 1
fmt.Println("GET /missing: err =", err, "| status =", resp.StatusCode)
go func() { // a watchdog, only so this demo can end
time.Sleep(3 * time.Second)
fmt.Println("3s later: still waiting... DefaultClient.Timeout =", http.DefaultClient.Timeout)
os.Exit(0)
}()
resp, err = http.Get(srv.URL + "/stuck") // pitfall 2
fmt.Println("GET /stuck:", err)
}
Real output:
GET /missing: err = <nil> | status = 404
3s later: still waiting... DefaultClient.Timeout = 0s
- Trap 1: a 404 is not an error. In Go's client,
err != nilmeans the request could not be completed at all (no connection, timeout, broken reply). A404 Not Foundor500 Internal Server Erroris still a valid HTTP answer, soerrisnil. Always checkresp.StatusCode. - Trap 2: no timeout.
http.Getuseshttp.DefaultClient, whoseTimeoutis0s: wait forever. The watchdog goroutine is there only so the demo can end.
http.Client and timeouts
Real-life example: your rules for a phone call.
| Phone call | Go | Meaning |
|---|---|---|
| your calling rules | http.Client |
timeout, cookie jar, redirect policy |
| a kitchen timer for the whole call | Client.Timeout |
covers connecting, sending, waiting for headers and reading the body |
| "cancel, the customer left!" | http.NewRequestWithContext |
a deadline or cancel for one request (contexts: episode 51) |
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("GET /stuck", func(w http.ResponseWriter, r *http.Request) {
<-r.Context().Done() // a broken server that never answers
})
srv := httptest.NewServer(mux)
defer srv.Close()
resp, err := http.Get(srv.URL + "/missing")
if err == nil && resp.StatusCode != http.StatusOK { // check the status yourself
fmt.Println("GET /missing failed:", resp.Status)
}
client := &http.Client{Timeout: time.Second} // the whole request: at most 1 s
_, err = client.Get(srv.URL + "/stuck")
fmt.Println("client.Timeout:", err)
ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
defer cancel()
req, _ := http.NewRequestWithContext(ctx, "GET", srv.URL+"/stuck", nil) // this request only
_, err = client.Do(req)
fmt.Println("with context:", err)
}
Real output:
GET /missing failed: 404 Not Found
client.Timeout: Get "http://127.0.0.1:42979/stuck": context deadline exceeded (Client.Timeout exceeded while awaiting headers)
with context: Get "http://127.0.0.1:42979/stuck": context deadline exceeded
- "awaiting headers" means the server never even started its answer.
- When both a client timeout and a context deadline exist, whichever comes first wins.
- A client is safe for use by many goroutines at once: create one and share it.
Close the body: http.Transport, connection pooling and keep-alive
Real-life example: the bikes at Raju's delivery stand.
| Delivery stand | Go | Meaning |
|---|---|---|
| bikes that carry orders | http.Transport |
the part of the client that opens TCP connections and sends the bytes |
| a returning bike goes out again | connection pooling | finished connections wait in a pool and are reused |
| the rider stays on the route | keep-alive | one connection carries many requests one after another (HTTP/1.1 default) |
| unload the bike before reuse | resp.Body.Close() |
read the body to the end and close it, or the connection can't go back to the pool |
Opening a connection is slow: a TCP handshake, plus a TLS handshake for HTTPS. Reusing one skips both.
package main
import (
"fmt"
"io"
"net"
"net/http"
"net/http/httptest"
"sync/atomic"
)
func main() {
var conns atomic.Int64 // how many TCP connections the server saw
srv := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "masala chai ₹20")
}))
srv.Config.ConnState = func(c net.Conn, s http.ConnState) {
if s == http.StateNew {
conns.Add(1)
}
}
srv.Start()
defer srv.Close()
for _, closeBody := range []bool{false, true} {
conns.Store(0)
for i := 0; i < 10; i++ {
resp, err := http.Get(srv.URL)
if err != nil {
fmt.Println(err)
return
}
if closeBody {
io.Copy(io.Discard, resp.Body) // read it to the end...
resp.Body.Close() // ...and close it
}
}
fmt.Printf("closeBody=%-5v 10 requests -> %d new connection(s)\n", closeBody, conns.Load())
}
}
Real output:
closeBody=false 10 requests -> 10 new connection(s)
closeBody=true 10 requests -> 1 new connection(s)
ConnState is a hook the server calls whenever a connection changes state; http.StateNew means a brand-new connection. io.Copy(io.Discard, resp.Body) reads the rest of the body and throws it away.
MaxIdleConnsPerHost
A host is one server address (api.example.com:443). MaxIdleConnsPerHost is how many idle connections the pool keeps per host. Zero means the default, 2.
package main
import (
"fmt"
"io"
"net"
"net/http"
"net/http/httptest"
"sync"
"sync/atomic"
"time"
)
func main() {
var conns atomic.Int64
srv := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
time.Sleep(10 * time.Millisecond)
fmt.Fprintln(w, "ok")
}))
srv.Config.ConnState = func(c net.Conn, s http.ConnState) {
if s == http.StateNew {
conns.Add(1)
}
}
srv.Start()
defer srv.Close()
for _, idle := range []int{0, 20} { // 0 means the default: 2 per host
conns.Store(0)
client := &http.Client{Transport: &http.Transport{MaxIdleConnsPerHost: idle}}
for round := 0; round < 5; round++ { // 5 rounds of 20 requests at once
var wg sync.WaitGroup
for i := 0; i < 20; i++ {
wg.Add(1)
go func() {
defer wg.Done()
resp, _ := client.Get(srv.URL)
io.Copy(io.Discard, resp.Body)
resp.Body.Close()
}()
}
wg.Wait()
}
fmt.Printf("MaxIdleConnsPerHost=%-2d 100 requests -> %d new connections\n", idle, conns.Load())
}
}
Real output (the first count varies a little between runs):
MaxIdleConnsPerHost=0 100 requests -> 92 new connections
MaxIdleConnsPerHost=20 100 requests -> 20 new connections
With the default, after each burst of 20 requests the pool kept only 2 idle connections and closed the rest, so almost every request in the next burst dialed again. With MaxIdleConnsPerHost: 20, 100 requests used 20 connections. Raise it for hosts you call a lot, and share one client (the pool lives in its Transport).
Other useful http.Transport fields: MaxIdleConns (idle connections across all hosts), MaxConnsPerHost (a hard cap including busy ones), IdleConnTimeout (how long an idle connection may wait), TLSHandshakeTimeout, ResponseHeaderTimeout.
Retries with exponential backoff and jitter
Real-life example: a busy phone line.
| Phone | Go | Meaning |
|---|---|---|
| "the number is busy" | retry | send the same request again after a temporary failure (503, timeout) |
| everyone redials every second | retry storm | instant retries keep an overloaded server overloaded |
| wait 1, then 2, then 4 minutes | exponential backoff | the wait doubles after each failure |
| each caller adds a random bit | jitter | randomness so clients don't retry at the same moment |
package main
import (
"fmt"
"math/rand/v2"
"net/http"
"net/http/httptest"
"time"
)
// getWithRetry tries up to 5 times, waiting longer after each failure.
func getWithRetry(client *http.Client, url string) (*http.Response, error) {
base := 100 * time.Millisecond
for attempt := 1; ; attempt++ {
resp, err := client.Get(url)
if err == nil && resp.StatusCode < 500 {
return resp, nil // success, or a 4xx that retrying won't fix
}
if err == nil {
resp.Body.Close()
err = fmt.Errorf("status %d", resp.StatusCode)
}
if attempt == 5 {
return nil, fmt.Errorf("gave up after %d attempts: %w", attempt, err)
}
backoff := base << (attempt - 1) // 100, 200, 400, 800 ms
wait := backoff/2 + rand.N(backoff/2) // + jitter: a random part
fmt.Printf(" attempt %d: %v -> wait %v\n", attempt, err, wait.Round(time.Millisecond))
time.Sleep(wait)
}
}
func main() {
calls := 0
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
calls++
if calls <= 3 { // the payment gateway is overloaded for a moment
http.Error(w, "busy", http.StatusServiceUnavailable)
return
}
fmt.Fprintln(w, "ok")
}))
defer srv.Close()
resp, err := getWithRetry(&http.Client{Timeout: 2 * time.Second}, srv.URL)
if err != nil {
fmt.Println(err)
return
}
resp.Body.Close()
fmt.Println("finally:", resp.Status, "after", calls, "calls")
}
Real output (waits are random):
attempt 1: status 503 -> wait 85ms
attempt 2: status 503 -> wait 175ms
attempt 3: status 503 -> wait 347ms
finally: 200 OK after 4 calls
base << (attempt - 1)doubles: 100, 200, 400, 800 ms.backoff/2 + rand.N(backoff/2)is "half the backoff plus a random part up to the other half" (rand.Nfrommath/rand/v2, episode 37).- A 4xx is returned immediately: the request itself is wrong and will fail again.
- Always keep a maximum number of attempts and a client timeout, and close failed responses before retrying.
Idempotency: never charge twice
Real-life example: Asha pays ₹500, the reply is late, the client times out and the app retries. The first payment had gone through: she paid twice. A timeout tells you that you didn't hear back, not that nothing happened.
package main
import (
"fmt"
"net/http"
"net/http/httptest"
"sync"
"time"
)
func main() {
var mu sync.Mutex
charged := 0
seen := map[string]bool{} // Idempotency-Keys already handled
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
key := r.Header.Get("Idempotency-Key")
mu.Lock()
if key == "" || !seen[key] { // a new payment: charge it
seen[key] = key != ""
charged += 500
}
mu.Unlock()
time.Sleep(300 * time.Millisecond) // the bank is slow to reply
fmt.Fprintln(w, "paid")
}))
defer srv.Close()
client := &http.Client{Timeout: 200 * time.Millisecond}
for _, key := range []string{"", "order-42-pay"} {
charged = 0
for attempt := 1; attempt <= 2; attempt++ { // timed out? retry once
req, _ := http.NewRequest("POST", srv.URL+"/pay", nil)
if key != "" {
req.Header.Set("Idempotency-Key", key)
}
_, err := client.Do(req)
fmt.Printf("key=%-13q attempt %d: timed out = %v\n", key, attempt, err != nil)
}
time.Sleep(400 * time.Millisecond)
mu.Lock()
fmt.Printf(" customer charged: ₹%d\n", charged)
mu.Unlock()
}
}
Real output:
key="" attempt 1: timed out = true
key="" attempt 2: timed out = true
customer charged: ₹1000
key="order-42-pay" attempt 1: timed out = true
key="order-42-pay" attempt 2: timed out = true
customer charged: ₹500
An operation is idempotent if doing it twice has the same effect as doing it once (pressing the lift button again: the lift still comes once). GET, HEAD, PUT and DELETE are defined as idempotent; POST is not. An Idempotency-Key header is a unique ID per operation that the client repeats on every retry; the server stores the keys it has handled and doesn't repeat the effect. Many payment APIs support such a key. Retry only what is safe to repeat.
Circuit breaker (concept)
Real-life example: the MCB (miniature circuit breaker), the trip switch in your home's electric box.
| MCB | Circuit breaker | Meaning |
|---|---|---|
| normal: current flows | closed | calls go through; failures are counted |
| a short circuit: it trips | open | after N failures in a row, every call fails immediately for a cool-down period |
| push it up again | half-open | after the cool-down, one test call goes through; success closes it, failure opens it again |
Why: when a service is down for minutes, every call would wait for its timeout and retry, making your app slow and hammering the struggling service. Failing fast keeps your app responsive and gives the other service room to recover. The standard library has no circuit breaker; teams write a small one or use a library. A minimal one:
package main
import (
"errors"
"fmt"
"sync"
"time"
)
var ErrOpen = errors.New("circuit open: failing fast")
// Breaker opens after `limit` failures in a row and lets one test call through after `cool`.
type Breaker struct {
mu sync.Mutex
fails int
limit int
openedAt time.Time
cool time.Duration
}
func (b *Breaker) Call(f func() error) error {
b.mu.Lock()
if b.fails >= b.limit && time.Since(b.openedAt) < b.cool {
b.mu.Unlock()
return ErrOpen // open: don't even try
}
b.mu.Unlock() // closed, or half-open after the cool-down
err := f()
b.mu.Lock()
defer b.mu.Unlock()
if err != nil {
b.fails++
if b.fails >= b.limit {
b.openedAt = time.Now() // (re)open
}
return err
}
b.fails = 0 // success closes it
return nil
}
func main() {
b := &Breaker{limit: 3, cool: 200 * time.Millisecond}
down := true
call := func() error {
if down {
return errors.New("delivery API: 503")
}
return nil
}
for i := 1; i <= 5; i++ {
fmt.Printf("call %d: %v\n", i, b.Call(call))
}
time.Sleep(250 * time.Millisecond) // cool-down passes; the API is back
down = false
fmt.Println("after cool-down:", b.Call(call))
fmt.Println("next call:", b.Call(call))
}
Real output:
call 1: delivery API: 503
call 2: delivery API: 503
call 3: delivery API: 503
call 4: circuit open: failing fast
call 5: circuit open: failing fast
after cool-down: <nil>
next call: <nil>
Retry or not?
| Retry | Don't retry |
|---|---|
| timeouts, connection errors | 400 Bad Request |
502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout |
401 Unauthorized, 403 Forbidden |
429 Too Many Requests (slow down; honour Retry-After if sent) |
404 Not Found |
POST only with an Idempotency-Key |
POST without one |
Cookie jars
Real-life example: the cloakroom token at a wedding hall.
| Cloakroom | HTTP | Meaning |
|---|---|---|
| you get a numbered token | Set-Cookie header |
the server sends a small name=value (a cookie) |
| show it to get your bag | Cookie header |
the client sends it back on later requests |
| keep tokens in your wallet | cookie jar | stores cookies per website and sends the right ones back |
HTTP forgets everything between requests; cookies let a server recognise you. Browsers keep cookies automatically; a Go client only does with a Jar (net/http/cookiejar).
package main
import (
"fmt"
"io"
"net/http"
"net/http/cookiejar"
"net/http/httptest"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("GET /login", func(w http.ResponseWriter, r *http.Request) {
http.SetCookie(w, &http.Cookie{Name: "session", Value: "asha-7f3a", HttpOnly: true})
fmt.Fprintln(w, "welcome, Asha")
})
mux.HandleFunc("GET /cart", func(w http.ResponseWriter, r *http.Request) {
c, err := r.Cookie("session")
if err != nil {
http.Error(w, "who are you? ("+err.Error()+")", http.StatusUnauthorized)
return
}
fmt.Fprintln(w, "cart for session", c.Value, ": 2 samosa")
})
srv := httptest.NewServer(mux)
defer srv.Close()
jar, _ := cookiejar.New(nil) // remembers cookies, per website
for _, client := range []*http.Client{{}, {Jar: jar}} {
fmt.Println("client with jar:", client.Jar != nil)
for _, path := range []string{"/login", "/cart"} {
resp, _ := client.Get(srv.URL + path)
b, _ := io.ReadAll(resp.Body)
resp.Body.Close()
fmt.Printf(" %-6s %d %s", path, resp.StatusCode, b)
}
}
}
Real output:
client with jar: false
/login 200 welcome, Asha
/cart 401 who are you? (http: named cookie not present)
client with jar: true
/login 200 welcome, Asha
/cart 200 cart for session asha-7f3a : 2 samosa
HttpOnly means browser JavaScript can't read the cookie. r.Cookie(name) returns http.ErrNoCookie ("http: named cookie not present") when it's missing.
Mini project: a delivery API client
One shared client with a timeout and a tuned Transport; every call uses a context, checks the status, reads and closes the body; temporary errors (502/503/504/429) are retried with backoff and jitter (max 4 attempts); booking a rider sends an Idempotency-Key; everything is tested against an httptest server that fails on purpose.
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"math/rand/v2"
"net/http"
"net/http/httptest"
"sync"
"time"
)
// Delivery is a small client for a delivery partner's API.
type Delivery struct {
base string
client *http.Client // one shared client: timeout + tuned pool
}
func NewDelivery(base string) *Delivery {
return &Delivery{base: base, client: &http.Client{
Timeout: 5 * time.Second,
Transport: &http.Transport{MaxIdleConnsPerHost: 20, IdleConnTimeout: 90 * time.Second},
}}
}
// retryable reports whether a status is worth another try.
func retryable(code int) bool {
return code == http.StatusBadGateway || code == http.StatusServiceUnavailable ||
code == http.StatusGatewayTimeout || code == http.StatusTooManyRequests
}
// do sends the request built by mk up to 4 times with backoff + jitter and decodes JSON into out.
func (d *Delivery) do(ctx context.Context, mk func() (*http.Request, error), out any) error {
base := 50 * time.Millisecond
for attempt := 1; ; attempt++ {
req, err := mk()
if err != nil {
return err
}
resp, err := d.client.Do(req.WithContext(ctx))
if err == nil {
body, rerr := io.ReadAll(resp.Body) // read to the end...
resp.Body.Close() // ...and close: the connection goes back to the pool
switch {
case rerr != nil:
err = rerr
case resp.StatusCode >= 200 && resp.StatusCode < 300:
return json.Unmarshal(body, out)
case !retryable(resp.StatusCode):
return fmt.Errorf("%s: %s", resp.Status, bytes.TrimSpace(body)) // 4xx: don't retry
default:
err = fmt.Errorf("status %d", resp.StatusCode)
}
}
if attempt == 4 || ctx.Err() != nil {
return fmt.Errorf("gave up after %d attempts: %w", attempt, err)
}
backoff := base << (attempt - 1)
wait := backoff/2 + rand.N(backoff/2)
fmt.Printf(" attempt %d: %v, retrying in %v\n", attempt, err, wait.Round(time.Millisecond))
select {
case <-time.After(wait):
case <-ctx.Done():
return ctx.Err()
}
}
}
type Rider struct {
ID string `json:"id"`
Name string `json:"name"`
}
func (d *Delivery) GetRider(ctx context.Context, id string) (Rider, error) {
var r Rider
err := d.do(ctx, func() (*http.Request, error) {
return http.NewRequestWithContext(ctx, "GET", d.base+"/riders/"+id, nil)
}, &r)
return r, err
}
func (d *Delivery) BookRider(ctx context.Context, orderID string) (Rider, error) {
var r Rider
err := d.do(ctx, func() (*http.Request, error) {
req, err := http.NewRequestWithContext(ctx, "POST", d.base+"/bookings",
bytes.NewReader([]byte(`{"order":"`+orderID+`"}`)))
if err == nil {
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "book-"+orderID) // the same key on every attempt
}
return req, err
}, &r)
return r, err
}
func main() {
var mu sync.Mutex
calls, bookings := 0, map[string]Rider{}
mux := http.NewServeMux()
mux.HandleFunc("GET /riders/{id}", func(w http.ResponseWriter, r *http.Request) {
if r.PathValue("id") != "7" {
http.Error(w, "no such rider", http.StatusNotFound)
return
}
json.NewEncoder(w).Encode(Rider{"7", "Ravi"})
})
mux.HandleFunc("POST /bookings", func(w http.ResponseWriter, r *http.Request) {
mu.Lock()
defer mu.Unlock()
calls++
if calls <= 2 { // the partner is overloaded at first
http.Error(w, "busy", http.StatusServiceUnavailable)
return
}
key := r.Header.Get("Idempotency-Key")
if _, ok := bookings[key]; !ok {
bookings[key] = Rider{"7", "Ravi"}
}
json.NewEncoder(w).Encode(bookings[key])
})
srv := httptest.NewServer(mux)
defer srv.Close()
d := NewDelivery(srv.URL)
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
r, err := d.GetRider(ctx, "7")
fmt.Println("GetRider(7):", r, err)
_, err = d.GetRider(ctx, "9")
fmt.Println("GetRider(9):", err)
r, err = d.BookRider(ctx, "42")
fmt.Println("BookRider(42):", r, err)
r, err = d.BookRider(ctx, "42") // the app retries the whole booking
mu.Lock()
fmt.Println("BookRider(42) again:", r, err, "| bookings stored:", len(bookings))
mu.Unlock()
}
Real output:
GetRider(7): {7 Ravi} <nil>
GetRider(9): 404 Not Found: no such rider
attempt 1: status 503, retrying in 35ms
attempt 2: status 503, retrying in 98ms
BookRider(42): {7 Ravi} <nil>
BookRider(42) again: {7 Ravi} <nil> | bookings stored: 1
Booking twice stored one booking: the key made the retry safe. (Run it with go run -race main.go too: no data races.)
Common mistakes (and the real messages)
| Mistake | What you see | Why | Fix |
|---|---|---|---|
http.Get in production |
waits forever; DefaultClient.Timeout = 0s |
the default client has no timeout | &http.Client{Timeout: ...} |
only checking err |
a 404 treated as success (err is nil, status 404) |
a 4xx/5xx is a valid response | check resp.StatusCode |
defer resp.Body.Close() before checking err |
panic: runtime error: invalid memory address or nil pointer dereference |
resp is nil when err != nil |
check err first, then defer Close |
| never closing the body | 10 requests -> 10 new connection(s) |
the connection can't return to the pool | read to EOF + Close |
| a new client per request | no connection reuse | each client has its own pool | create one client, share it |
| default pool for a busy host | almost every request dials again | DefaultMaxIdleConnsPerHost = 2 |
raise MaxIdleConnsPerHost |
retrying POST /pay |
customer charged: ₹1000 |
the first one went through | Idempotency-Key |
| instant, endless retries | a retry storm | everyone retries together | backoff + jitter + max attempts |
| no jar for a login API | 401 who are you? (http: named cookie not present) |
the client drops cookies | http.Client{Jar: jar} |
A failed connection looks like this (nothing listening on the port):
error: Get "http://127.0.0.1:1/menu": dial tcp 127.0.0.1:1: connect: connection refused
Practice
- Write
fetch(ctx, client, url) ([]byte, error)that returns an error for any non-2xx status and always closes the body. - Which of these may a client retry automatically?
GET /menu,POST /orders,PUT /menu/2,DELETE /orders/42,POST /paywith anIdempotency-Key. - A client has
Timeout: 10 * time.Second, and the request's context has a 2-second deadline. When does the request give up? - Why does setting
MaxIdleConnsPerHoston aTransportdo nothing if you create a newhttp.Client{Transport: &http.Transport{...}}for every request?
Solutions
1.
package main
import (
"context"
"fmt"
"io"
"net/http"
"net/http/httptest"
"time"
)
func fetch(ctx context.Context, c *http.Client, url string) ([]byte, error) {
req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
if err != nil {
return nil, err
}
resp, err := c.Do(req)
if err != nil {
return nil, err // resp is nil here
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return nil, err
}
if resp.StatusCode < 200 || resp.StatusCode > 299 {
return nil, fmt.Errorf("GET %s: %s", url, resp.Status)
}
return body, nil
}
func main() {
mux := http.NewServeMux()
mux.HandleFunc("GET /menu", func(w http.ResponseWriter, r *http.Request) { fmt.Fprintln(w, "chai ₹20") })
srv := httptest.NewServer(mux)
defer srv.Close()
c := &http.Client{Timeout: 2 * time.Second}
b, err := fetch(context.Background(), c, srv.URL+"/menu")
fmt.Printf("%q %v\n", b, err)
_, err = fetch(context.Background(), c, srv.URL+"/bill")
fmt.Println(err)
}
Real output:
"chai ₹20\n" <nil>
GET http://127.0.0.1:42905/bill: 404 Not Found
2. GET /menu, PUT /menu/2, DELETE /orders/42 (idempotent methods) and POST /pay with an Idempotency-Key (the server makes it idempotent). Not POST /orders without a key: a retry could create a second order.
3. After 2 seconds: whichever limit comes first wins, and the error is context deadline exceeded.
4. The pool lives inside the Transport. A new Transport per request starts with an empty pool, so nothing is reused (and old idle connections pile up until they time out). Create the client and Transport once.
Quick quiz
1. The server answers 404 for /missing. What does this print? (From the video.)
resp, err := http.Get(srv.URL + "/missing") // server answers 404
if err != nil {
fmt.Println("error:", err)
return
}
defer resp.Body.Close()
fmt.Println("ok:", resp.StatusCode)
A. error: 404 Not Found · B. ok: 404 · C. ok: 200 · D. nothing, it panics
Answer
B. A 404 is a complete HTTP response, so err is nil.
2. What is http.DefaultClient.Timeout?
Answer
0s: no timeout at all.
3. What is jitter for?
Answer
It adds a random part to each retry wait so that many clients that failed together don't all retry at the same moment.
Interview questions
- Why shouldn't you use
http.Getin production? It usesDefaultClient, which has no timeout; a stuck server blocks the caller forever. - Does
client.Doreturn an error for a 500? No. Errors are for transport failures (DNS, connection, timeout, malformed reply). Checkresp.StatusCode. - Why must you close
resp.Body, and why read it fully? Closing releases the connection; reading to EOF lets the Transport put it back in the pool for keep-alive reuse. Otherwise connections leak and every request dials anew. - What's the difference between
http.Clientandhttp.Transport? The Client holds high-level policy (timeout, cookies, redirects); the Transport opens, pools and reuses connections and does TLS. Clients and Transports are safe for concurrent use and should be reused. - What is
MaxIdleConnsPerHostand its default? The number of idle keep-alive connections kept per host; defaultDefaultMaxIdleConnsPerHost = 2, too low for a service that calls one host heavily. Client.Timeoutvs a context deadline? The timeout applies to every request made by that client (including reading the body); a context (NewRequestWithContext) sets a deadline or cancellation for one request and also propagates cancellation from callers.- How do you retry safely? Only temporary failures, only idempotent operations (or with an idempotency key), exponential backoff with jitter, a maximum number of attempts, and an overall deadline.
- What is a circuit breaker? A wrapper that counts failures and, after a threshold, fails calls immediately (open) for a cool-down, then lets a test call through (half-open) before closing again.
- How does a Go client keep a login session? With a cookie jar (
cookiejar.New) set asClient.Jar; it storesSet-Cookievalues per site and sends them back.
Glossary
| Term | Meaning | Example |
|---|---|---|
| Client (HTTP) | a program that sends HTTP requests | Raju's app calling the payment gateway |
http.Client |
Go value holding request rules: timeout, cookie jar, redirects | &http.Client{Timeout: 5 * time.Second} |
http.DefaultClient |
the client used by http.Get, http.Head, http.Post; no timeout |
DefaultClient.Timeout = 0s |
http.Get pitfalls |
no timeout; a 4xx/5xx is not an error | err is nil for a 404 |
resp.StatusCode / resp.Status |
the number / text of the answer's status | 404, "404 Not Found" |
| Timeout | the longest you are willing to wait | Client.Timeout: time.Second |
Client.Timeout |
limit for the whole request, including reading the body | Client.Timeout exceeded while awaiting headers |
| Context | carries a deadline or cancellation (episode 51) | context.WithTimeout(ctx, 300*time.Millisecond) |
http.NewRequestWithContext |
builds a request tied to a context | http.NewRequestWithContext(ctx, "GET", url, nil) |
client.Do |
sends a prepared request | resp, err := client.Do(req) |
context deadline exceeded |
the error when a deadline passes | from a timed-out request |
resp.Body |
the stream of the response's body | io.ReadAll(resp.Body) |
resp.Body.Close() |
releases the response and its connection | defer resp.Body.Close() |
io.Discard |
a writer that throws bytes away | io.Copy(io.Discard, resp.Body) |
| Nil pointer dereference | using a nil pointer's fields; panics | resp.Body when resp is nil |
| TCP connection | an open two-way byte channel between two programs (episode 60) | client ↔ server |
| Handshake | the setup messages before a connection can be used (TCP, TLS) | slow, so reuse connections |
http.Transport |
opens, pools and reuses connections; does TLS | &http.Transport{MaxIdleConnsPerHost: 20} |
| Connection pooling | keeping finished connections to reuse them | 10 requests → 1 connection |
| Keep-alive | one connection carrying many requests in turn | HTTP/1.1 default |
| Idle connection | an open connection not carrying a request right now | waits in the pool |
| Host | one server address | 127.0.0.1:42979, api.example.com |
MaxIdleConnsPerHost |
idle connections kept per host | default 2 |
DefaultMaxIdleConnsPerHost |
the constant for that default | = 2 |
ConnState |
server hook called when a connection changes state | http.StateNew |
http.StateNew |
the state of a brand-new connection | counted in the demo |
| Retry | sending the same request again after a temporary failure | 503 → try again |
503 Service Unavailable |
the server is overloaded or down for now | "busy" |
502 / 504 |
a gateway in front got a bad answer / no answer in time | retry these |
429 Too Many Requests |
you are sending too fast | slow down, then retry |
| Retry storm | many clients retrying fast, overloading a server | everyone redials every second |
| Exponential backoff | waiting twice as long after each failure | 100, 200, 400, 800 ms |
| Jitter | a random part added to a wait | backoff/2 + rand.N(backoff/2) |
rand.N |
random number in [0, n) from math/rand/v2 |
rand.N(50 * time.Millisecond) |
| Idempotent | doing it twice = doing it once | pressing the lift button again |
| Idempotency key | a unique ID repeated on retries so the server does the effect once | Idempotency-Key: order-42-pay |
| Circuit breaker | stops calling a failing service for a while (fail fast) | MCB trip switch |
| Closed / open / half-open | breaker states: calls go through / fail fast / one test call | after 3 failures → open |
| Fail fast | return an error immediately instead of waiting | circuit open: failing fast |
| Cookie | small name=value a server asks the client to send back | session=asha-7f3a |
Set-Cookie / Cookie header |
server → client / client → server | via http.SetCookie, r.Cookie |
HttpOnly |
browser scripts can't read the cookie | HttpOnly: true |
| Cookie jar | stores cookies per website and sends them back | cookiejar.New(nil) |
Client.Jar |
the jar a client uses | &http.Client{Jar: jar} |
http.ErrNoCookie |
error for a missing cookie | http: named cookie not present |
401 Unauthorized |
you are not logged in | the cart without a cookie |
httptest.NewServer |
a real test server on a free port | srv.URL |
Summary
http.Getuseshttp.DefaultClient: no timeout, and a 404 is not an error.- Make one shared
http.Clientwith aTimeout; usehttp.NewRequestWithContextfor per-request deadlines and cancellation. - Read and close every
resp.Bodyso thehttp.Transportcan reuse connections (pooling, keep-alive); raiseMaxIdleConnsPerHost(default 2) for busy hosts. - Retry only temporary failures, with exponential backoff + jitter and a maximum; retry only idempotent requests or use an
Idempotency-Key. - A circuit breaker fails fast when a service keeps failing.
- A cookie jar (
net/http/cookiejar) keeps a client logged in.
Next episode: Middleware: func(http.Handler) http.Handler, chaining, logging, panic recovery, request IDs, authentication, CORS, http.TimeoutHandler and http.ResponseController.