Documentation
¶
Overview ¶
Package server provides a small, gracefully-stoppable HTTP server.
A Server binds its listener at construction time (so the bound address is immediately available via Server.Addr), but does not begin serving until Server.ServeHTTP or Server.ServeHTTPHandler is called. Those methods block until the provided context is cancelled, at which point the server is shut down with a short grace period.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HealthzHandler ¶ added in v0.2.0
HealthzHandler returns a liveness handler that always responds 200 {"status":"ok"}. Liveness means "the process is up"; for dependency checks use ReadyzHandler.
func ReadyzHandler ¶ added in v0.2.0
ReadyzHandler returns a readiness handler that runs the named checks with the request context. If every check returns nil it responds 200 {"status":"ok"}; otherwise it responds 503 listing only the failing check names:
{"status":"unavailable","failed":["database"]}
Check error details are logged server-side, never returned in the body, so a publicly-reachable probe cannot leak internal hostnames, addresses, or paths. A check that panics is treated as failed rather than crashing the probe. Checks should be fast and side-effect free (e.g. a ping); wrap slow checks in your own caching if probes are frequent.
Example ¶
package main
import (
"context"
"errors"
"fmt"
"net/http"
"net/http/httptest"
"github.com/mikehelmick/go-bananas/server"
)
func main() {
// Register named readiness checks; details of failures are logged
// server-side while the public body lists only the failing names.
h := server.ReadyzHandler(map[string]func(context.Context) error{
"database": func(_ context.Context) error {
return errors.New("dial tcp: connection refused") // logged, not returned
},
"cache": func(_ context.Context) error { return nil },
})
w := httptest.NewRecorder()
h.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/readyz", nil))
fmt.Println(w.Code)
fmt.Print(w.Body.String())
}
Output: 503 {"failed":["database"],"status":"unavailable"}
Types ¶
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a gracefully-stoppable HTTP server. It is safe for concurrent use.
func New ¶
New creates a server listening on the provided port. The listener is bound immediately, so the server is ready to accept connections before serving begins. An empty port lets the operating system choose a free one.
func NewFromListener ¶
NewFromListener creates a server on the given listener, useful for customizing the listener type or bind options. The listener must be TCP.
func (*Server) ServeHTTP ¶
ServeHTTP starts the server with the provided http.Server and blocks until ctx is cancelled, after which it gracefully shuts down with a 5-second timeout. A server is not safe to reuse after it has stopped.
func (*Server) ServeHTTPHandler ¶
ServeHTTPHandler is a convenience wrapper around Server.ServeHTTP that builds an http.Server from handler with sensible timeouts. Observability or tracing wrappers, if desired, are the caller's responsibility (wrap handler before passing it in).
Source Files