tsweb

package
v0.0.0-...-ded95ce Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 14, 2022 License: BSD-3-Clause Imports: 29 Imported by: 0

Documentation

Overview

Package tsweb contains code used in various Tailscale webservers.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var DevMode bool

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

Functions

func AcceptsEncoding 

func AcceptsEncoding(r *http.Request, enc string) bool

AcceptsEncoding reports whether r accepts the named encoding ("gzip", "br", etc).

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 Protected 

func Protected(h http.Handler) http.Handler

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

func StdHandler 

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

StdHandler 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.

func WritePrometheusExpvar 

func WritePrometheusExpvar(w io.Writer, kv expvar.KeyValue)

WritePrometheusExpvar writes kv to w in Prometheus metrics format.

See VarzHandler for conventions. This is exported primarily for people to test their varz.

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,omitempty"`

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

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

	// The HTTP response code sent to the client.
	Code int `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.
	Bytes int `json:"bytes,omitempty"`
	// Error encountered during request processing.
	Err string `json:"err,omitempty"`
}

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 DebugHandler 

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

DebugHandler is an http.Handler that serves a debugging "homepage", and provides helpers to register more debug endpoints and reports.

The rendered page consists of three sections: informational key/value pairs, links to other pages, and additional program-specific HTML. Callers can add to these sections using the KV, URL and Section helpers respectively.

Additionally, the Handle method offers a shorthand for correctly registering debug handlers and cross-linking them from /debug/.

func Debugger 

func Debugger(mux *http.ServeMux) *DebugHandler

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

func (*DebugHandler) Handle 

func (d *DebugHandler) Handle(slug, desc string, handler http.Handler)

Handle registers handler at /debug/<slug> and creates a descriptive entry in /debug/ for it.

Example 
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))

Output:

func (*DebugHandler) KV 

func (d *DebugHandler) KV(k string, v any)

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

Example 
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)

Output:

func (*DebugHandler) KVFunc 

func (d *DebugHandler) KVFunc(k string, v func() any)

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

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

Output:

func (*DebugHandler) Section 

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

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

Example 
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)
})

Output:

func (*DebugHandler) ServeHTTP 

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

ServeHTTP implements http.Handler.

func (*DebugHandler) URL 

func (d *DebugHandler) URL(url, desc string)

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

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

Output:

type ErrorHandlerFunc 

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

ErrorHandlerFunc is called to present a error response.

type HTTPError 

type HTTPError struct {
	Code   int         // HTTP response code to send to client; 0 means 500
	Msg    string      // Response body to send to client
	Err    error       // Detailed error to log on the server
	Header http.Header // Optional set of HTTP headers to set in the response
}

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.

func (HTTPError) Unwrap 

func (e HTTPError) Unwrap() error

type HandlerOptions 

type HandlerOptions struct {
	QuietLoggingIfSuccessful bool // if set, do not log successfully handled HTTP requests (200 and 304 status codes)
	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
	// 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

	// 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.
	OnError ErrorHandlerFunc
}

type Port80Handler 

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

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 PrometheusMetricsReflectRooter 

type PrometheusMetricsReflectRooter interface {
	expvar.Var

	// PrometheusMetricsReflectRoot returns the struct or struct pointer to walk.
	PrometheusMetricsReflectRoot() any
}

PrometheusMetricsReflectRooter is an optional interface that expvar.Var implementations can implement to indicate that they should be walked recursively with reflect to find sets of fields to export.

type PrometheusVar 

type PrometheusVar interface {
	// WritePrometheus writes the value of the var to w, in Prometheus
	// metric syntax. All variables names written out must start with
	// prefix (or write out a single variable named exactly prefix)
	WritePrometheus(w io.Writer, prefix string)
}

PrometheusVar is a value that knows how to format itself into Prometheus metric syntax.

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).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.