func AcceptsEncoding(r *http.Request, encstring)bool

func AddBrowserHeaders(whttp.ResponseWriter)

func AllowDebugAccess(r *http.Request)bool

func BrowserHeaderHandler(hhttp.Handler)http.Handler

func BrowserHeaderHandlerFunc(hhttp.HandlerFunc)http.HandlerFunc

func CleanRedirectURL(urlStrstring, allowedHosts []string) (*url.URL,error)

func DefaultCertDir(leafDirstring)string

func ErrorHandler(hReturnHandler, optsErrorOptions)http.Handler

func IsProd443(addrstring)bool

func LogHandler(hhttp.Handler, optsLogOptions)http.Handler

func NormalizedPath(pstring)string

func Protected(hhttp.Handler)http.Handler

func SetRequestID(hhttp.Handler)http.Handler

func StdHandler(hReturnHandler, optsHandlerOptions)http.Handler

func VarzHandler(whttp.ResponseWriter, r *http.Request)

func WriteHTTPError(whttp.ResponseWriter, r *http.Request, eHTTPError)

type AccessLogRecord struct {// Timestamp at which request processing started.Timetime.Time `json:"time"`// Time it took to finish processing the request. It does not// include the entire lifetime of the underlying connection in// cases like connection hijacking, only the lifetime of the HTTP// request handler.Secondsfloat64 `json:"duration,omitempty"`// The client's ip:port.RemoteAddrstring `json:"remote_addr,omitempty"`// The HTTP protocol version, usually "HTTP/1.1 or HTTP/2".Protostring `json:"proto,omitempty"`// Whether the request was received over TLS.TLSbool `json:"tls,omitempty"`// The target hostname in the request.Hoststring `json:"host,omitempty"`// The HTTP method invoked.Methodstring `json:"method,omitempty"`// The unescaped request URI, including query parameters.RequestURIstring `json:"request_uri,omitempty"`// The client's user-agentUserAgentstring `json:"user_agent,omitempty"`// Where the client was before making this request.Refererstring `json:"referer,omitempty"`// The HTTP response code sent to the client.Codeint `json:"code,omitempty"`// Number of bytes sent in response body to client. If the request// was hijacked, only includes bytes sent up to the point of// hijacking.Bytesint `json:"bytes,omitempty"`// Error encountered during request processing.Errstring `json:"err,omitempty"`// RequestID is a unique ID for this request. If the *http.Request context// carries this value via SetRequestID, then it will be displayed to the// client immediately after the error text, as well as logged here. This// makes it easier to correlate support requests with server logs. If a// RequestID generator is not configured, RequestID will be empty.RequestIDRequestID `json:"request_id,omitempty"`}

func (AccessLogRecord)String¶added inv0.98.0

func (mAccessLogRecord) String()string

String returns m as a JSON string.

type BucketedStatsOptions struct {// Bucket returns which bucket the given request is in.// If nil, [NormalizedPath] is used to compute the bucket.Bucket func(req *http.Request)string// If non-nil, Started maintains a counter of all requests which// have begun processing.Started *metrics.LabelMap// If non-nil, Finished maintains a counter of all requests which// have finished processing with success (that is, the HTTP handler has// returned).Finished *metrics.LabelMap}

type DebugHandler struct {// contains filtered or unexported fields}

funcDebugger¶added inv1.10.0

func Debugger(mux *http.ServeMux) *DebugHandler

Debugger returns the DebugHandler registered on mux at /debug/,creating it if necessary.

func (*DebugHandler)Handle¶added inv1.10.0

func (d *DebugHandler) Handle(slug, descstring, handlerhttp.Handler)

Handle registers handler at /debug/<slug> and adds a link to iton /debug/ with the provided description.

mux := http.NewServeMux()dbg := Debugger(mux)// Registers /debug/flushcache with the given handler, and adds a// link to /debug/ with the description "Flush caches".dbg.Handle("flushcache", "Flush caches", http.HandlerFunc(http.NotFound))

func (*DebugHandler)HandleFunc¶added inv1.82.0

func (d *DebugHandler) HandleFunc(slug, descstring, handlerhttp.HandlerFunc)

Handle registers handler at /debug/<slug> and adds a link to iton /debug/ with the provided description.

func (*DebugHandler)HandleSilent¶added inv1.50.0

func (d *DebugHandler) HandleSilent(slugstring, handlerhttp.Handler)

HandleSilent registers handler at /debug/<slug>. It does not adda descriptive entry in /debug/ for it. This should be usedsparingly, for things that need to be registered but would pollutethe list of debug links.

func (*DebugHandler)HandleSilentFunc¶added inv1.82.0

func (d *DebugHandler) HandleSilentFunc(slugstring, handlerhttp.HandlerFunc)

HandleSilent registers handler at /debug/<slug>. It does not adda descriptive entry in /debug/ for it. This should be usedsparingly, for things that need to be registered but would pollutethe list of debug links.

func (*DebugHandler)KV¶added inv1.10.0

func (d *DebugHandler) KV(kstring, vany)

KV adds a key/value list item to /debug/.

mux := http.NewServeMux()dbg := Debugger(mux)// Adds two list items to /debug/, showing that the condition is// red and there are 42 donuts.dbg.KV("Condition", "red")dbg.KV("Donuts", 42)

func (*DebugHandler)KVFunc¶added inv1.10.0

func (d *DebugHandler) KVFunc(kstring, v func()any)

KVFunc adds a key/value list item to /debug/. v is called on everyrender of /debug/.

mux := http.NewServeMux()dbg := Debugger(mux)// Adds an count of page renders to /debug/. Note this example// isn't concurrency-safe.views := 0dbg.KVFunc("Debug pageviews", func() any {views = views + 1return views})dbg.KV("Donuts", 42)

func (*DebugHandler)Section¶added inv1.10.0

func (d *DebugHandler) Section(f func(wio.Writer, r *http.Request))

Section invokes f on every render of /debug/ to add supplementalHTML to the page body.

mux := http.NewServeMux()dbg := Debugger(mux)// Adds a section to /debug/ that dumps the HTTP request of the// visitor.dbg.Section(func(w io.Writer, r *http.Request) {io.WriteString(w, "<h3>Dump of your HTTP request</h3>")fmt.Fprintf(w, "<code>%#v</code>", r)})

func (*DebugHandler)ServeHTTP¶added inv1.10.0

func (d *DebugHandler) ServeHTTP(whttp.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

func (*DebugHandler)Title¶added inv1.82.0

func (d *DebugHandler) Title(titlestring)

Title sets the title at the top of the debug page.

func (*DebugHandler)URL¶added inv1.10.0

func (d *DebugHandler) URL(url, descstring)

URL adds a URL and description list item to /debug/.

mux := http.NewServeMux()dbg := Debugger(mux)// Links to the Tailscale website from /debug/.dbg.URL("https://www.tailscale.com", "Homepage")

type ErrorHandlerFunc func(http.ResponseWriter, *http.Request,HTTPError)

type ErrorOptions struct {// Logf is used to record unexpected behaviours when returning HTTPError but// different error codes have already been written to the client.Logflogger.Logf// OnError is called if the handler returned a HTTPError. This// is intended to be used to present pretty error pages if// the user agent is determined to be a browser.OnErrorErrorHandlerFunc}

type HTTPError struct {Codeint// HTTP response code to send to client; 0 means 500Msgstring// Response body to send to clientErrerror// Detailed error to log on the serverHeaderhttp.Header// Optional set of HTTP headers to set in the response}

funcError¶added inv0.98.0

func Error(codeint, msgstring, errerror)HTTPError

Error returns an HTTPError containing the given information.

func (HTTPError)Error¶added inv0.98.0

func (eHTTPError) Error()string

Error implements the error interface.

func (HTTPError)Unwrap¶added inv1.32.0

func (eHTTPError) Unwrap()error

type HandlerOptions struct {QuietLoggingIfSuccessfulbool// if set, do not log successfully handled HTTP requests (200 and 304 status codes)Logflogger.LogfNow                      func()time.Time// if nil, defaults to time.Now// If non-nil, StatusCodeCounters maintains counters// of status codes for handled responses.// The keys are "1xx", "2xx", "3xx", "4xx", and "5xx".StatusCodeCounters *expvar.Map// If non-nil, StatusCodeCountersFull maintains counters of status// codes for handled responses.// The keys are HTTP numeric response codes e.g. 200, 404, ...StatusCodeCountersFull *expvar.Map// If non-nil, BucketedStats computes and exposes statistics// for each bucket based on the contained parameters.BucketedStats *BucketedStatsOptions// OnStart is called inline before ServeHTTP is called. Optional.OnStartOnStartFunc// OnError is called if the handler returned a HTTPError. This// is intended to be used to present pretty error pages if// the user agent is determined to be a browser.OnErrorErrorHandlerFunc// OnCompletion is called inline when ServeHTTP is finished and gets// useful data that the implementor can use for metrics. Optional.OnCompletionOnCompletionFunc}

type LogOptions struct {// Logf is used to log HTTP requests and responses.Logflogger.Logf// Now is a function giving the current time. Defaults to [time.Now].Now func()time.Time// QuietLogging suppresses all logging of handled HTTP requests, even if// there are errors or status codes considered unsuccessful. Use this option// to add your own logging in OnCompletion.QuietLoggingbool// QuietLoggingIfSuccessful suppresses logging of handled HTTP requests// where the request's response status code is 200 or 304.QuietLoggingIfSuccessfulbool// StatusCodeCounters maintains counters of status code classes.// The keys are "1xx", "2xx", "3xx", "4xx", and "5xx".// If nil, no counting is done.StatusCodeCounters *expvar.Map// StatusCodeCountersFull maintains counters of status codes.// The keys are HTTP numeric response codes e.g. 200, 404, ...// If nil, no counting is done.StatusCodeCountersFull *expvar.Map// BucketedStats computes and exposes statistics for each bucket based on// the contained parameters. If nil, no counting is done.BucketedStats *BucketedStatsOptions// OnStart is called inline before ServeHTTP is called. Optional.OnStartOnStartFunc// OnCompletion is called inline when ServeHTTP is finished and gets// useful data that the implementor can use for metrics. Optional.OnCompletionOnCompletionFunc}

type Middleware func(hhttp.Handler)http.Handler

funcMiddlewareStack¶added inv1.72.0

func MiddlewareStack(mw ...Middleware)Middleware

MiddlewareStack combines multiple middleware into a single middleware fordecorating ahttp.Handler. The first middleware argument will be the firstto process an incoming request, before passing the request onto subsequentmiddleware and eventually the wrapped handler.

For example:

MiddlewareStack(A, B)(h).ServeHTTP(w, r)

calls in sequence:

   a.ServeHTTP(w, r)-> b.ServeHTTP(w, r)-> h.ServeHTTP(w, r)

(where the lowercase handlers were generated by the uppercase middleware).

// setHeader returns a middleware that sets header k = vs.setHeader := func(k string, vs ...string) Middleware {k = textproto.CanonicalMIMEHeaderKey(k)return func(h http.Handler) http.Handler {return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {w.Header()[k] = vsh.ServeHTTP(w, r)})}}// h is a http.Handler which prints the A, B & C response headers, wrapped// in a few middleware which set those headers.var h http.Handler = MiddlewareStack(setHeader("A", "mw1"),MiddlewareStack(setHeader("A", "mw2.1"),setHeader("B", "mw2.2"),setHeader("C", "mw2.3"),setHeader("C", "mw2.4"),),setHeader("B", "mw3"),)(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {fmt.Println("A", w.Header().Get("A"))fmt.Println("B", w.Header().Get("B"))fmt.Println("C", w.Header().Get("C"))}))// Invoke the handler.h.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest("", "/", nil))

Output:A mw2.1B mw3C mw2.4

type OnCompletionFunc func(*http.Request,AccessLogRecord)

type OnStartFunc func(*http.Request,AccessLogRecord)

type Port80Handler struct {Mainhttp.Handler// FQDN is used to redirect incoming requests to https://<FQDN>.// If it is not set, the hostname is calculated from the incoming// request.FQDNstring}

func (Port80Handler)ServeHTTP¶

func (hPort80Handler) ServeHTTP(whttp.ResponseWriter, r *http.Request)

type RequestIDstring

funcGenerateRequestID¶added inv1.62.0

func GenerateRequestID()RequestID

GenerateRequestID generates a new request ID with the current format.

func (RequestID)String¶added inv1.62.0

func (rRequestID) String()string

String returns the string format of the request ID, for use in e.g. settingahttp.Header.

type ReturnHandler interface {// ServeHTTPReturn is like http.Handler.ServeHTTP, except that// it can choose to return an error instead of writing to its// http.ResponseWriter.//// If ServeHTTPReturn returns an error, it caller should handle// an error by serving an HTTP 500 response to the user. The// error details should not be sent to the client, as they may// contain sensitive information. If the error is an// HTTPError, though, callers should use the HTTP response// code and message as the response to the client.ServeHTTPReturn(http.ResponseWriter, *http.Request)error}

type ReturnHandlerFunc func(http.ResponseWriter, *http.Request)error

func (ReturnHandlerFunc)ServeHTTPReturn¶added inv0.98.1

func (fReturnHandlerFunc) ServeHTTPReturn(whttp.ResponseWriter, r *http.Request)error

ServeHTTPReturn calls f(w, r).