Building an HTTP Server

A teammate needs a health check endpoint before Friday's demo. Their proposal:

func main() {
	http.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "ok")
	})
	log.Fatal(http.ListenAndServe(":8080", nil))
}

It answers curl localhost:8080/healthz, so it looks done. Two problems hide in those four lines.

No timeouts. With the default server, ReadHeaderTimeout, ReadTimeout, and WriteTimeout are all zero — unbounded. The server reads headers at whatever pace the client chooses. An attacker opens 50,000 connections and dribbles one byte a minute; each pins a goroutine and a buffer until memory runs out. That is the slowloris attack, and the default server loses it. Timeouts are not tuning — they are the admission policy for your listener.

Treating shutdown as a crash. log.Fatal fires on any error from ListenAndServe. Later you will add graceful shutdown, which makes the server return http.ErrServerClosed on purpose — and log.Fatal will turn your drain into a crash that kills in-flight requests. Check the error conditionally from day one.

package main

import (
	"errors"
	"log"
	"net/http"
	"time"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
	})

	srv := &http.Server{
		Addr:              ":8080",
		Handler:           mux,
		ReadHeaderTimeout: 5 * time.Second,
	}
	if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
		log.Fatal(err)
	}
}

Notice http.NewServeMux() instead of the default mux. http.DefaultServeMux is package-level shared state: any package you import can call http.Handle and silently add a route to your server. An explicit mux is a value you own, pass around, and inspect in tests.

The pattern GET /healthz carries a method prefix — Go 1.22+ routing built into the standard library. A POST /healthz never reaches your handler; the mux answers 405 Method Not Allowed with an Allow header for free.

Underneath sits one interface: http.Handler, a single ServeHTTP(ResponseWriter, *Request) method (Interfaces and Method Sets). The server holds a handler, the mux holds handlers, and handlers can hold other handlers. Every layer of a Go HTTP service repeats that abstraction, which is what makes Middleware possible. Your listener is now honest about failure and bounded in time. The next question is what to do with everything a request can carry.

The API spec says GET /users/{id}, POST /users, GET /users/{id}/orders, and a catch-all for the SPA at /. Before Go 1.22 you stripped prefixes and split on slashes yourself, and every hand-rolled dispatcher grew its own edge cases. The standard mux now parses patterns:

func routes() http.Handler {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /users/{id}", getUser)
	mux.HandleFunc("POST /users", createUser)
	mux.HandleFunc("GET /users/{id}/orders", listOrders)
	mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServerFS(staticFS)))
	mux.HandleFunc("GET /{$}", index) // matches exactly "/", nothing else
	return mux
}

func getUser(w http.ResponseWriter, r *http.Request) {
	id := r.PathValue("id")
	fmt.Fprintf(w, "user %s", id)
}

Four rules decide which handler runs:

1. Method mismatches are not misses. If a pattern matches the path but not the verb, the mux returns 405 with Allow: GET instead of 404. Only when no pattern matches the path at all do you get 404 — or the subtree fallback.
2. Longest match wins. /users/{id}/orders beats {id} beats /. A pattern ending in / matches the whole subtree; {$} matches only the root.
3. Conflicts panic at registration. Two patterns that overlap ambiguously blow up when routes() runs — at startup, not on the first unlucky request. Fail-fast routing is one reason to register everything in one function.
4. Query strings never participate. ?page=2 is invisible to matching; you read it with r.URL.Query() in the handler (Reading Requests in Handlers).

Trailing slashes deserve a note: registering /users/ and requesting /users gets an automatic 301 to /users/ (or the reverse), so clients with strict redirect handling need to know. Absolute paths in patterns are required — a pattern without a leading slash panics.

When does a third-party router earn its place? When you need per-subtree middleware mounting, route groups with shared headers, or path patterns the mux cannot express. Frameworks like chi wrap the same http.Handler contract, so choosing one later does not rewrite your handlers. The default answer for most services: start with the standard mux, keep routes() as the single place that knows the URL space, and revisit only when a concrete pattern is missing — not because a framework was mentioned in a blog post.

Your getUser handler needs the database and a logger. The tempting move is package-level variables:

var db *sql.DB // set in main
var logger = slog.Default()

Now every test must mutate global state, two tests running in parallel stomp each other, and the handler's real inputs are invisible in its signature. Go's answer is to make the handler a method on a struct that holds its dependencies:

type Queries interface {
	UserByID(ctx context.Context, id int64) (User, error)
}

type Server struct {
	q   Queries
	log *slog.Logger
}

func NewServer(q Queries, log *slog.Logger) *Server {
	return &Server{q: q, log: log}
}

func (s *Server) handleGetUser(w http.ResponseWriter, r *http.Request) {
	id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
	if err != nil {
		http.Error(w, "bad id", http.StatusBadRequest)
		return
	}
	u, err := s.q.UserByID(r.Context(), id)
	if err != nil {
		s.log.ErrorContext(r.Context(), "load user", "id", id, "err", err)
		http.Error(w, "not found", http.StatusNotFound)
		return
	}
	fmt.Fprintf(w, "%s <%s>", u.Name, u.Email)
}

func (s *Server) routes() http.Handler {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /users/{id}", s.handleGetUser)
	return mux
}

Read the signature as documentation: this handler depends on a Queries and a logger, nothing else. The interface is declared by the consumer — the server package — not by the database package (Interfaces at the Consumer Side), so tests pass a fake Queries and exercise the handler with no SQL, no network, and no global cleanup (Testing Handlers with httptest).

A method value like s.handleGetUser is already an http.HandlerFunc, so mux.HandleFunc accepts it directly. When you need the struct itself mounted — for example to wrap all its routes — the struct can implement ServeHTTP and satisfy http.Handler outright.

Keep two habits while this shape spreads. First, r.Context() flows into every dependency call, so a client that disconnects cancels the database query too (Context and Cancellation). Second, construct the graph once in main: srv := NewServer(db, logger) — wiring is explicit, and a missing dependency is a compile error rather than a nil dereference at request 9,000.

Your service runs behind a load balancer that removes the instance on SIGTERM and then sends remaining traffic elsewhere. If the process exits the moment the signal arrives, every request still being handled dies mid-flight: half-written JSON responses, orphaned transactions. Graceful shutdown gives in-flight work a bounded chance to finish.

func run() error {
	srv := &http.Server{
		Addr:              ":8080",
		Handler:           routes(),
		ReadHeaderTimeout: 5 * time.Second,
	}

	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()

	errCh := make(chan error, 1)
	go func() {
		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
			errCh <- err
		}
		close(errCh)
	}()

	select {
	case err := <-errCh:
		return err // listener failed on its own
	case <-ctx.Done(): // signal arrived
	}
	stop() // restore default signal behavior for a second Ctrl-C

	shutdownCtx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
	defer cancel()
	if err := srv.Shutdown(shutdownCtx); err != nil {
		return fmt.Errorf("graceful shutdown failed: %w", err)
	}
	return errors.Join(<-errCh...)
}

Three mechanics make this work. Shutdown closes listeners immediately, so the balancer's health check fails and new traffic stops; it then waits for active requests to return. If the deadline passes, it returns context.DeadlineExceeded and you may call srv.Close() to sever stragglers — a decision, not an accident. And signal.NotifyContext cancels a context on the first signal while leaving the second one at its default disposition, so an impatient operator can still force-kill.

Budget the timeout against your own work, not habit: 20 seconds is generous for JSON APIs but short if a job endpoint runs for minutes. Long-running handlers should watch their own timeouts and cancellation inside r.Context(), which Shutdown cancels once the deadline hits.

Deploy-time detail: the ordering matters. Platforms usually flip the balancer first, then signal, then hard-kill after a grace period. Your shutdown timeout must fit inside that grace period or the platform's SIGKILL undoes the politeness. Full treatment of signals and drain strategies lives in Graceful Shutdown; here the contract is narrow — stop accepting, finish what you accepted, exit non-zero only when something actually went wrong.