Go HTTP Cheat Sheet for Servers and Clients in One Page

package main

import (
	"context"
	"encoding/json"
	"errors"
	"net"
	"net/http"
	"time"
)

// NewServer is the baseline http.Server: every field here is a decision, not decoration.
func NewServer(h http.Handler) *http.Server {
	return &http.Server{
		Handler:           h,
		ReadHeaderTimeout: 5 * time.Second,  // slow clients cannot hold a goroutine with a trickle of headers
		ReadTimeout:       15 * time.Second, // whole request including body; raise for upload routes
		WriteTimeout:      30 * time.Second, // whole response; use ResponseController for streaming routes
		IdleTimeout:       60 * time.Second, // keep-alive connections that go quiet
		MaxHeaderBytes:    16 << 10,         // the default is 1 MB
	}
}

// Run serves on ln until ctx ends, then drains in-flight requests for up to grace.
func Run(ctx context.Context, srv *http.Server, ln net.Listener, grace time.Duration) error {
	errc := make(chan error, 1)
	go func() { errc <- srv.Serve(ln) }()
	select {
	case err := <-errc:
		return err
	case <-ctx.Done():
	}
	shutCtx, cancel := context.WithTimeout(context.Background(), grace)
	defer cancel()
	if err := srv.Shutdown(shutCtx); err != nil {
		srv.Close() // the grace period ran out: cut the remaining connections
		return err
	}
	if err := <-errc; !errors.Is(err, http.ErrServerClosed) {
		return err // ErrServerClosed after Shutdown is success
	}
	return nil
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status) // status first, then the body
	json.NewEncoder(w).Encode(v)
}

func fail(w http.ResponseWriter, status int, msg string) {
	writeJSON(w, status, map[string]string{"error": msg})
}

// decode reads a JSON body with a size cap and without tolerating unknown fields.
func decode(w http.ResponseWriter, r *http.Request, dst any) bool {
	dec := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<20))
	dec.DisallowUnknownFields()
	if err := dec.Decode(dst); err != nil {
		var tooBig *http.MaxBytesError
		if errors.As(err, &tooBig) {
			fail(w, http.StatusRequestEntityTooLarge, "body too large")
		} else {
			fail(w, http.StatusBadRequest, "invalid JSON body")
		}
		return false
	}
	return true
}

package main

import (
	"fmt"
	"net/http"
	"strconv"
	"time"
)

type Middleware func(http.Handler) http.Handler

func Chain(h http.Handler, m ...Middleware) http.Handler {
	for i := len(m) - 1; i >= 0; i-- { // the first in the list is the outermost
		h = m[i](h)
	}
	return h
}

func Recover(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			if v := recover(); v != nil {
				fail(w, http.StatusInternalServerError, "internal error")
			}
		}()
		next.ServeHTTP(w, r)
	})
}

func RequestID(next http.Handler) http.Handler {
	var n int
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		id := r.Header.Get("X-Request-Id")
		if id == "" {
			n++
			id = fmt.Sprintf("req-%d", n)
		}
		w.Header().Set("X-Request-Id", id)
		next.ServeHTTP(w, r)
	})
}

func Timeout(d time.Duration) Middleware {
	return func(next http.Handler) http.Handler { return http.TimeoutHandler(next, d, `{"error":"timeout"}`) }
}

func Routes() http.Handler {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /{$}", func(w http.ResponseWriter, r *http.Request) { writeJSON(w, 200, map[string]string{"service": "sheet"}) })
	mux.HandleFunc("GET /items/{id}", func(w http.ResponseWriter, r *http.Request) {
		id, err := strconv.Atoi(r.PathValue("id"))
		if err != nil {
			fail(w, http.StatusBadRequest, "id must be a number")
			return
		}
		writeJSON(w, 200, map[string]any{"id": id, "page": r.URL.Query().Get("page")})
	})
	mux.HandleFunc("POST /items", func(w http.ResponseWriter, r *http.Request) {
		var in struct {
			Name string `json:"name"`
		}
		if !decode(w, r, &in) {
			return
		}
		w.Header().Set("Location", "/items/1")
		writeJSON(w, http.StatusCreated, map[string]any{"id": 1, "name": in.Name})
	})
	mux.HandleFunc("GET /files/{path...}", func(w http.ResponseWriter, r *http.Request) {
		writeJSON(w, 200, map[string]string{"path": r.PathValue("path")})
	})
	mux.HandleFunc("GET /boom", func(w http.ResponseWriter, r *http.Request) { panic("handler bug") })
	return Chain(mux, RequestID, Recover)
}

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"strings"
	"time"
)

// One client for the program: the Transport inside it is the connection pool.
var client = &http.Client{Timeout: 10 * time.Second}

// do sends a request and decodes a JSON answer. It checks the status, bounds the read and drains the body.
func do(ctx context.Context, method, url, body string, out any) (int, error) {
	req, err := http.NewRequestWithContext(ctx, method, url, strings.NewReader(body))
	if err != nil {
		return 0, err
	}
	if body != "" {
		req.Header.Set("Content-Type", "application/json")
	}
	res, err := client.Do(req)
	if err != nil {
		return 0, err
	}
	defer res.Body.Close()
	data, err := io.ReadAll(io.LimitReader(res.Body, 1<<20))
	if err != nil {
		return res.StatusCode, err
	}
	if res.StatusCode >= 300 {
		return res.StatusCode, fmt.Errorf("%s %s: %s %s", method, url, res.Status, strings.TrimSpace(string(data)))
	}
	if out != nil {
		return res.StatusCode, json.Unmarshal(data, out)
	}
	return res.StatusCode, nil
}

package main

import (
	"context"
	"fmt"
	"net"
	"strings"
	"time"
)

func main() {
	ln, _ := net.Listen("tcp", "127.0.0.1:0")
	base := "http://" + ln.Addr().String()
	ctx, stop := context.WithCancel(context.Background())
	done := make(chan error, 1)
	go func() { done <- Run(ctx, NewServer(Routes()), ln, 5*time.Second) }()

	show := func(label, method, path, body string) {
		var out map[string]any
		status, err := do(context.Background(), method, base+path, body, &out)
		text := fmt.Sprint(out)
		if err != nil {
			text = strings.ReplaceAll(err.Error(), base, "")
		}
		fmt.Printf("%-26s %3d  %s\n", label, status, text)
	}
	show("root", "GET", "/", "")
	show("path value and query", "GET", "/items/7?page=2", "")
	show("bad path value", "GET", "/items/abc", "")
	show("create", "POST", "/items", `{"name":"widget"}`)
	show("unknown JSON field", "POST", "/items", `{"name":"x","admin":true}`)
	show("malformed JSON", "POST", "/items", `{"name":`)
	show("wildcard with slashes", "GET", "/files/a/b/c.txt", "")
	show("wrong method", "DELETE", "/items/7", "")
	show("unknown path", "GET", "/nope", "")
	show("panic recovered", "GET", "/boom", "")

	res, _ := client.Get(base + "/")
	res.Body.Close()
	fmt.Println("request ID header set:", res.Header.Get("X-Request-Id") != "")

	stop() // the signal.NotifyContext in a real main
	fmt.Println("Run returned:", <-done)
}

root                       200  map[service:sheet]
path value and query       200  map[id:7 page:2]
bad path value             400  GET /items/abc: 400 Bad Request {"error":"id must be a number"}
create                     201  map[id:1 name:widget]
unknown JSON field         400  POST /items: 400 Bad Request {"error":"invalid JSON body"}
malformed JSON             400  POST /items: 400 Bad Request {"error":"invalid JSON body"}
wildcard with slashes      200  map[path:a/b/c.txt]
wrong method               405  DELETE /items/7: 405 Method Not Allowed Method Not Allowed
unknown path               404  GET /nope: 404 Not Found 404 page not found
panic recovered            500  GET /boom: 500 Internal Server Error {"error":"internal error"}
request ID header set: true
Run returned: <nil>