SyntaxPilot
Courses/Go Programming/Lesson 63
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Go Programming · Lesson 63 of 89

HTTP clients done right

http.Clienthttp.Get pitfallsclient timeoutshttp.Transportconnection pooling and keep-aliveMaxIdleConnsPerHostalways closing resp.Bodyhttp.NewRequestWithContextretries with exponential backoff and jitteridempotency and retriescircuit breaker (concept)cookie jars

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"); DefaultClient is the client used by Get, Head and Post; a Client.Timeout of 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 != nil means the request could not be completed at all (no connection, timeout, broken reply). A 404 Not Found or 500 Internal Server Error is still a valid HTTP answer, so err is nil. Always check resp.StatusCode.
  • Trap 2: no timeout. http.Get uses http.DefaultClient, whose Timeout is 0s: 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.N from math/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

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

  1. Write fetch(ctx, client, url) ([]byte, error) that returns an error for any non-2xx status and always closes the body.
  2. Which of these may a client retry automatically? GET /menu, POST /orders, PUT /menu/2, DELETE /orders/42, POST /pay with an Idempotency-Key.
  3. A client has Timeout: 10 * time.Second, and the request's context has a 2-second deadline. When does the request give up?
  4. Why does setting MaxIdleConnsPerHost on a Transport do nothing if you create a new http.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

  1. Why shouldn't you use http.Get in production? It uses DefaultClient, which has no timeout; a stuck server blocks the caller forever.
  2. Does client.Do return an error for a 500? No. Errors are for transport failures (DNS, connection, timeout, malformed reply). Check resp.StatusCode.
  3. 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.
  4. What's the difference between http.Client and http.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.
  5. What is MaxIdleConnsPerHost and its default? The number of idle keep-alive connections kept per host; default DefaultMaxIdleConnsPerHost = 2, too low for a service that calls one host heavily.
  6. Client.Timeout vs 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.
  7. 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.
  8. 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.
  9. How does a Go client keep a login session? With a cookie jar (cookiejar.New) set as Client.Jar; it stores Set-Cookie values 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.Get uses http.DefaultClient: no timeout, and a 404 is not an error.
  • Make one shared http.Client with a Timeout; use http.NewRequestWithContext for per-request deadlines and cancellation.
  • Read and close every resp.Body so the http.Transport can reuse connections (pooling, keep-alive); raise MaxIdleConnsPerHost (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.