tsweb

Documentation

Overview

Package tsweb contains code used in various Tailscale webservers.

Index

• Variables
• func AllowDebugAccess(r *http.Request) bool
• func DefaultCertDir(leafDir string) string
• func IsProd443(addr string) bool
• func NewMux(debugHandler http.Handler) *http.ServeMux
• func Protected(h http.Handler) http.Handler
• func StdHandler(h ReturnHandler, logf logger.Logf) http.Handler
• func StdHandlerNo200s(h ReturnHandler, logf logger.Logf) http.Handler
• func StdHandlerOpts(h ReturnHandler, opts HandlerOptions) http.Handler
• func Uptime() time.Duration
• func VarzHandler(w http.ResponseWriter, r *http.Request)
• type AccessLogRecord
  • func (m AccessLogRecord) String() string
• type HTTPError
  • func Error(code int, msg string, err error) HTTPError
  • func (e HTTPError) Error() string
• type HandlerOptions
• type JSONHandlerFunc
  • func (fn JSONHandlerFunc) ServeHTTPReturn(w http.ResponseWriter, r *http.Request) error
• type Port80Handler
  • func (h Port80Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ReturnHandler
• type ReturnHandlerFunc
  • func (f ReturnHandlerFunc) ServeHTTPReturn(w http.ResponseWriter, r *http.Request) error

Variables

var DevMode bool

DevMode controls whether extra output in shown, for when the binary is being run in dev mode.

Functions

func AllowDebugAccess

func AllowDebugAccess(r *http.Request) bool

AllowDebugAccess reports whether r should be permitted to access various debug endpoints.

func DefaultCertDir

func DefaultCertDir(leafDir string) string

func IsProd443

func IsProd443(addr string) bool

IsProd443 reports whether addr is a Go listen address for port 443.

func NewMux

func NewMux(debugHandler http.Handler) *http.ServeMux

NewMux returns a new ServeMux with debugHandler registered (and protected) at /debug/.

func Protected

func Protected(h http.Handler) http.Handler

Protected wraps a provided debug handler, h, returning a Handler that enforces AllowDebugAccess and returns forbiden replies for unauthorized requests.

func StdHandler

func StdHandler(h ReturnHandler, logf logger.Logf) http.Handler

StdHandler converts a ReturnHandler into a standard http.Handler. Handled requests are logged using logf, as are any errors. Errors are handled as specified by the Handler interface.

func StdHandlerNo200s

func StdHandlerNo200s(h ReturnHandler, logf logger.Logf) http.Handler

StdHandlerNo200s is like StdHandler, but successfully handled HTTP requests don't write an access log entry to logf.

TODO(josharian): eliminate this and StdHandler in favor of StdHandlerOpts, rename StdHandlerOpts to StdHandler. Will be a breaking API change.

func StdHandlerOpts

func StdHandlerOpts(h ReturnHandler, opts HandlerOptions) http.Handler

StdHandlerOpts converts a ReturnHandler into a standard http.Handler. Handled requests are logged using opts.Logf, as are any errors. Errors are handled as specified by the Handler interface.

func Uptime

func Uptime() time.Duration

func VarzHandler

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

VarzHandler is an HTTP handler to write expvar values into the prometheus export format:

https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md

It makes the following assumptions:

• *expvar.Int are counters (unless marked as a gauge_; see below)
• a *tailscale/metrics.Set is descended into, joining keys with underscores. So use underscores as your metric names.
• an expvar named starting with "gauge_" or "counter_" is of that Prometheus type, and has that prefix stripped.
• anything else is untyped and thus not exported.
• expvar.Func can return an int or int64 (for now) and anything else is not exported.

This will evolve over time, or perhaps be replaced.

Types

type AccessLogRecord

type AccessLogRecord struct {
	// Timestamp at which request processing started.
	When time.Time `json:"when"`
	// 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.
	Seconds float64 `json:"duration"`

	// The client's ip:port.
	RemoteAddr string `json:"remote_addr"`
	// The HTTP protocol version, usually "HTTP/1.1 or HTTP/2".
	Proto string `json:"proto"`
	// Whether the request was received over TLS.
	TLS bool `json:"tls"`
	// The target hostname in the request.
	Host string `json:"host"`
	// The HTTP method invoked.
	Method string `json:"method"`
	// The unescaped request URI, including query parameters.
	RequestURI string `json:"request_uri"`

	// The client's user-agent
	UserAgent string `json:"user_agent"`
	// Where the client was before making this request.
	Referer string `json:"referer"`

	// The HTTP response code sent to the client.
	Code int `json:"code"`
	// Number of bytes sent in response body to client. If the request
	// was hijacked, only includes bytes sent up to the point of
	// hijacking.
	Bytes int `json:"bytes"`
	// Error encountered during request processing.
	Err string `json:"err"`
}

AccessLogRecord is a record of one HTTP request served.

func (AccessLogRecord) String

func (m AccessLogRecord) String() string

String returns m as a JSON string.

type HTTPError

type HTTPError struct {
	Code int    // HTTP response code to send to client; 0 means means 500
	Msg  string // Response body to send to client
	Err  error  // Detailed error to log on the server
}

HTTPError is an error with embedded HTTP response information.

It is the error type to be (optionally) used by Handler.ServeHTTPReturn.

func Error

func Error(code int, msg string, err error) HTTPError

Error returns an HTTPError containing the given information.

func (HTTPError) Error

func (e HTTPError) Error() string

Error implements the error interface.

type HandlerOptions

type HandlerOptions struct {
	Quiet200s bool // if set, do not log successfully handled HTTP requests
	Logf      logger.Logf
	Now       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
}

type JSONHandlerFunc

type JSONHandlerFunc func(r *http.Request) (status int, data interface{}, err error)

JSONHandlerFunc is an HTTP ReturnHandler that writes JSON responses to the client.

Return a HTTPError to show an error message, otherwise JSONHandlerFunc will only report "internal server error" to the user with status code 500.

func (JSONHandlerFunc) ServeHTTPReturn

func (fn JSONHandlerFunc) ServeHTTPReturn(w http.ResponseWriter, r *http.Request) error

ServeHTTPReturn implements the ReturnHandler interface.

Use the following code to unmarshal the request body

body := new(DataType)
if err := json.NewDecoder(r.Body).Decode(body); err != nil {
  return http.StatusBadRequest, nil, err
}

See jsonhandler_test.go for examples.

type Port80Handler

type Port80Handler struct{ Main http.Handler }

Port80Handler is the handler to be given to autocert.Manager.HTTPHandler. The inner handler is the mux returned by NewMux containing registered /debug handlers.

func (Port80Handler) ServeHTTP

func (h Port80Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type ReturnHandler

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
}

ReturnHandler is like net/http.Handler, but the handler can return an error instead of writing to its ResponseWriter.

type ReturnHandlerFunc

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

ReturnHandlerFunc is an adapter to allow the use of ordinary functions as ReturnHandlers. If f is a function with the appropriate signature, ReturnHandlerFunc(f) is a ReturnHandler that calls f.

func (ReturnHandlerFunc) ServeHTTPReturn

func (f ReturnHandlerFunc) ServeHTTPReturn(w http.ResponseWriter, r *http.Request) error

ServeHTTPReturn calls f(w, r).