Skip to content
Tutorials Center
My learning

Topics

Lesson 106 of 147 ยท Web and Networking

Building an HTTP Server

Build a web server with Go's net/http - Handler and HandlerFunc, ServeMux method and wildcard patterns, requests and responses, status codes, headers, timeouts and graceful shutdown.

Go's standard library contains a production-grade HTTP server. Companies run services that handle millions of requests per day on nothing but net/http, with no framework at all. That is not an accident: the package was designed together with the language's concurrency model, so every incoming request runs in its own goroutine and your handler code can be written as plain, blocking, top-to-bottom Go.

This lesson builds a server from the ground up. You will meet the http.Handler interface, route requests with http.ServeMux (including the method and wildcard patterns added in Go 1.22), read the request and write the response, choose status codes and headers, configure timeouts, and shut the server down without dropping in-flight requests. The next lesson adds middleware, JSON handlers and handler testing.

Every runnable example on this page starts its own server with httptest.NewServer, or with a listener on 127.0.0.1 and a random port, and talks to it with http.Get from the same program. Only loopback networking works on this site, and that is all you need to see every behavior. In your own program you call http.ListenAndServe(":8080", mux) instead, and use curl or a browser as the client.

The programs that use method and wildcard patterns start with the line //go:debug httpmuxgo121=0. It switches on the Go 1.22 routing rules, and you need it only because the editors on this page compile a single file without a go.mod, which falls back to the old behavior. In a module whose go.mod says go 1.22 or newer, the patterns simply work and you leave that line out.

The smallest server

Everything in net/http revolves around one interface with a single method:

Go
type Handler interface {
	ServeHTTP(ResponseWriter, *Request)
}

A handler receives a *http.Request (what the client sent) and an http.ResponseWriter (where you write the answer). Because the interface has one method, Go also provides the adapter http.HandlerFunc: a function type that has a ServeHTTP method which simply calls the function. Any function with the right signature becomes a handler by conversion. This is the same trick as sort.Interface adapters and is explained in interfaces and function types.

httptest.NewServer starts a real HTTP server on a random loopback port and returns its URL. We use it to try the handler immediately:

Go A handler, a server and a client in one program

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Three things happened without any code from you. The status is 200 OK, because writing to the ResponseWriter without calling WriteHeader first sends 200. The Content-Type header was sniffed from the first bytes of the body (text/plain; charset=utf-8), and Content-Length was filled in, because the whole response was small enough to be buffered. In a real server you would write http.ListenAndServe(":8080", http.HandlerFunc(hello)), which blocks forever and returns only on error.

Types as handlers, and one goroutine per request

Because Handler is an interface, a handler can be a struct that carries its own state and dependencies (a database, a logger, a counter). Compare it with a plain function: when the handler needs configuration, a type with fields is the cleanest way to give it that.

There is one rule you must never forget: the server calls your handler from many goroutines at the same time. State shared between requests needs a mutex, an atomic or a channel (sync package, atomics). The example sends twenty requests at once to a handler that counts visits:

Go A struct handler shared by concurrent requests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

With a plain int and c.hits++ this program would have a data race and could print a smaller number (data races). The atomic makes the count exact. The order in which the 20 requests were handled is not defined, which is why the program prints only the final count.

Routing with ServeMux

A server usually has many URLs. The multiplexer http.ServeMux looks at each request and calls the handler registered for the best matching pattern. Create one with http.NewServeMux() and register handlers with Handle (for a Handler) or HandleFunc (for a function). Avoid the global http.DefaultServeMux that http.HandleFunc uses: any package you import can register routes on it, which is a security risk.

Since Go 1.22 a pattern can contain a method, wildcards and an optional host:

Pattern Matches
/about Exactly /about, any method
GET /about Only GET (and HEAD) requests for /about
/static/ Any path that starts with /static/ (a trailing slash means a subtree)
GET /{$} Exactly / and nothing else ({$} anchors the end)
GET /items/{id} /items/42, /items/abc; read the value with r.PathValue("id")
GET /files/{path...} /files/a, /files/a/b/c.txt; the rest of the path, with slashes, in PathValue("path")
example.com/blog/ Only for requests with the host example.com

When several patterns match, the most specific one wins: GET /items/new beats GET /items/{id}, which beats GET /items/{path...}. If two patterns match the same requests and neither is more specific, registering the second one panics at startup, so ambiguity is caught immediately instead of at 3 a.m. If the path matches a pattern but the method does not, the mux answers 405 Method Not Allowed with an Allow header. If nothing matches, it answers 404 Not Found.

Go Patterns, wildcards and automatic 404 and 405 answers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Study the results. /items/new goes to the specific handler even though could also match "new". DELETE /items/42 gets a 405 and the mux itself reports Allow: GET, HEAD, because that is the set of methods registered for the path. /items/ is a 404 because a wildcard must match a non-empty segment. GET patterns also answer HEAD requests. Wildcard values are always strings; convert them with strconv.Atoi and answer 400 Bad Request when the conversion fails.

Conflicts fail loudly

The mux checks every new pattern against the existing ones. Two patterns conflict when some request matches both and neither is strictly more specific. The registration panics with a message that names both patterns:

Go Conflicting patterns panic at registration (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

The second pattern conflicts with the first. The panic message even gives an example path that matches both ("/a/start/end") and ends with "But neither is more specific than the other." The fourth is a plain duplicate. The third one is fine, because it only matches two-segment paths. Since this happens when the program starts, a conflict can never reach production unnoticed.

Before Go 1.22, programs needed a router package to match methods or extract /users/{id}. For many services the standard ServeMux is now enough. Reach for a third-party router only when you need features it lacks, such as regular-expression routes.

Reading the request

The *http.Request carries everything the client sent:

Field or method What it gives you
r.Method "GET", "POST", ... (use the constants http.MethodGet, ...)
r.URL.Path, r.URL.Query() The path and the parsed query string (url.Values, see URLs)
r.PathValue("id") A wildcard from the matched pattern
r.Header Request headers; read with r.Header.Get("Name"), which ignores case
r.Body A stream (io.ReadCloser) with the request body
r.ParseForm(), r.FormValue("k"), r.PostForm URL-encoded form data
r.Context() A context that is cancelled when the client disconnects or the handler returns
r.Host, r.RemoteAddr, r.Proto Target host, client address and "HTTP/1.1"
Go Everything a handler can read from a request

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

r.URL.Query()["b"] returns every value of a repeated key, while .Get("a") returns the first (or the empty string). ParseForm reads the body for POST, PUT and PATCH requests with the application/x-www-form-urlencoded content type, so call it once.

Some important habits when reading a request body:

  • Limit its size. A client can send gigabytes. Wrap the body first: r.Body = http.MaxBytesReader(w, r.Body, 1<<20). Reads then fail with an error once the limit is passed, and the server closes the connection.
  • Don't trust anything. Headers, paths and form values are user input. Validate them, and never build file paths or SQL out of them directly.
  • You don't need to close r.Body. The server does that. (The client must close response bodies, see the HTTP client lesson.)

Writing the response

The ResponseWriter has three jobs: Header() returns the map of response headers, WriteHeader(code) sends the status line and headers, and Write([]byte) sends body bytes. The order is strict:

  1. Set headers with w.Header().Set(...).
  2. Send the status with w.WriteHeader(code). If you skip this, the first call to Write sends 200.
  3. Write the body.

Headers set after the first Write or WriteHeader are silently ignored, and a second WriteHeader is ignored too (the server logs http: superfluous response.WriteHeader call). This is the most common bug in new handlers: calling w.Write(...) and then trying to change the status.

The package offers shortcuts for common answers: http.Error(w, msg, code) (sets a plain-text type and writes the message), http.NotFound, http.Redirect(w, r, url, code), http.SetCookie(w, cookie) and http.ServeFile for files. Use the named constants for status codes, such as http.StatusCreated, and http.StatusText(code) for the reason phrase.

The status codes you will use most:

Code Name When
200 OK The default success
201 Created A resource was created; send a Location header
204 No Content Success with nothing to send back (delete, update)
301 / 308 Moved Permanently / Permanent Redirect The URL has changed for good
302 / 303 / 307 Found / See Other / Temporary Redirect Temporary redirect (303 after a POST)
400 Bad Request The request is malformed or invalid
401 / 403 Unauthorized / Forbidden Not signed in / not allowed
404 Not Found No such resource
405 Method Not Allowed Wrong method for this URL
409 Conflict The change clashes with the current state
422 Unprocessable Content Well-formed but semantically invalid
429 Too Many Requests Rate limit hit
500 Internal Server Error A bug on the server
503 Service Unavailable Overloaded or shutting down
Go Status codes, headers, redirects and cookies

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Notice what each shortcut did: http.Redirect set Location and also wrote a small HTML body for old clients, http.Error set a plain-text content type and added the newline, and /too-late has no X-Late header because the headers had already gone out with the first Write. For JSON, always set the Content-Type header yourself before encoding; the next lesson wraps this into helpers.

Configuring the server

http.ListenAndServe is fine for experiments, but production code creates an http.Server value so that it can set timeouts and shut down cleanly. The defaults have no timeouts at all, which means a client that connects and then sends nothing can hold a connection (and a goroutine) forever. That is called a slow-client or slowloris attack, and it needs only a few lines to set up.

Go
srv := &http.Server{
	Addr:              ":8080",
	Handler:           mux,
	ReadHeaderTimeout: 5 * time.Second,  // time to receive the request headers
	ReadTimeout:       15 * time.Second, // time to read the entire request, body included
	WriteTimeout:      30 * time.Second, // time to write the response
	IdleTimeout:       60 * time.Second, // how long keep-alive connections may sit unused
	MaxHeaderBytes:    1 << 20,
}
log.Fatal(srv.ListenAndServe())

Always set at least ReadHeaderTimeout and IdleTimeout. WriteTimeout is a hard limit on the whole handler run for a plain response, so it is wrong for endpoints that stream for a long time (see streaming and SSE); for those, extend the deadline per request with http.NewResponseController(w).SetWriteDeadline(...). A timeout on the handler itself can be added with http.TimeoutHandler(h, 2*time.Second, "timeout"), and the request's context (context) tells your own code when to give up.

For HTTPS, call srv.ListenAndServeTLS(certFile, keyFile). With TLS enabled the server speaks HTTP/2 automatically to clients that support it; your handlers don't change. Many deployments terminate TLS in a reverse proxy (nginx, Caddy, a cloud load balancer) and run plain HTTP behind it.

Graceful shutdown

When you deploy a new version, the old process receives a termination signal. Killing it at once would cut off requests that are half-done. srv.Shutdown(ctx) does it politely: it closes the listeners so no new connections arrive, then waits for active requests to finish, then returns. If the context expires first, Shutdown returns the context's error and you can call srv.Close() to cut the remaining connections.

The program below proves it. A slow request is in flight when Shutdown starts. The new connections are refused immediately, Shutdown keeps waiting, and the slow request still receives its full answer:

Go Shutdown waits for the request that is in flight

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Serve (and ListenAndServe) returns http.ErrServerClosed as soon as Shutdown is called. That is the normal way for a server to end, so you must not treat it as a failure: if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) { log.Fatal(err) }.

A complete main for a real service ties this to operating-system signals with signal.NotifyContext (read-only, since this site cannot send signals):

Go
func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprint(w, "ok")
	})

	srv := &http.Server{
		Addr:              ":8080",
		Handler:           mux,
		ReadHeaderTimeout: 5 * time.Second,
		IdleTimeout:       60 * time.Second,
	}

	// ctx is cancelled when the process receives Ctrl+C or SIGTERM.
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	go func() {
		log.Println("listening on", srv.Addr)
		if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
			log.Fatal(err)
		}
	}()

	<-ctx.Done() // wait for the signal
	stop()       // a second Ctrl+C now kills the process immediately

	shutdownCtx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
	defer cancel()
	if err := srv.Shutdown(shutdownCtx); err != nil {
		log.Println("forced shutdown:", err)
	}
	log.Println("bye")
}

Container platforms such as Kubernetes send SIGTERM, wait for a grace period (30 seconds by default) and then send SIGKILL, so pick a shutdown timeout shorter than that. A /healthz endpoint like the one above lets a load balancer check whether the process is alive.

What the server does for you

Some behaviors of net/http surprise newcomers, and knowing them saves debugging time:

  • One goroutine per connection, not per server. Keep-alive connections handle requests one after another, and HTTP/2 multiplexes many requests on one connection, each in its own goroutine.
  • Panics in handlers don't crash the server. The server recovers, logs the stack trace and closes that connection. That is a safety net; adding your own recovery middleware that answers 500 is nicer (next lesson). Panicking with http.ErrAbortHandler aborts silently on purpose.
  • A handler that returns finishes the response. There is no "end" call; you can't write after returning, and you must not use w or r from a goroutine that outlives the handler.
  • The client may leave. If the browser closes the tab, r.Context() is cancelled. Long database calls and downstream requests should take that context so they stop too.
  • HEAD is free for GET patterns: the mux calls your handler and discards the body.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What makes http.HandlerFunc(f) a valid http.Handler?

    HandlerFunc is declared as type HandlerFunc func(ResponseWriter, *Request) and has a ServeHTTP method that calls the function itself, so the conversion adapts any function to the Handler interface.
  2. 2. Which pattern matches only requests for exactly / and nothing else?

    A pattern ending in a slash matches the whole subtree, so / matches everything. {$} anchors the end of the path: /{$} (or GET /{$}) matches only the root.
  3. 3. A handler calls w.Write([]byte("hi")) and then w.WriteHeader(404). What does the client receive?

    The first Write sends the status line with 200 and the headers. WriteHeader afterwards is superfluous: the server ignores it and logs a warning.
  4. 4. You call srv.Shutdown(ctx) while one request is still running. What happens?

    Shutdown stops accepting new connections and waits for active requests. If the context expires first, it returns the context's error.
  5. 5. What does ListenAndServe return after a successful Shutdown?

    ListenAndServe and Serve always return a non-nil error; after Shutdown or Close it is http.ErrServerClosed, which is the normal way to end and should not be logged as a failure.

Summary

  • A handler is anything with ServeHTTP(w http.ResponseWriter, r *http.Request); http.HandlerFunc adapts plain functions, and structs can carry state and dependencies.
  • The server calls handlers concurrently, so shared state needs a mutex or an atomic.
  • Use your own http.NewServeMux(). Go 1.22 patterns can include a method (GET /items/{id}), wildcards (, {path...}, {$}) and a host; the most specific pattern wins and conflicting patterns panic at startup. Wrong methods get 405 with Allow, unknown paths get 404.
  • Read input through r.URL.Query(), r.PathValue, r.Header, r.ParseForm and r.Body (limited with http.MaxBytesReader); set headers first, then call WriteHeader, then write the body.
  • Create an http.Server with at least ReadHeaderTimeout and IdleTimeout, and shut it down with Shutdown after a signal; treat http.ErrServerClosed as success.

Next: Handlers, Routing and Middleware