tsweb

type AccessLogRecord struct {
	// Timestamp at which request processing started.
	Time time.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.
	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"`
	// 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.
	RequestID RequestID `json:"request_id,omitempty"`
}

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
}

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

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
}

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

	// 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.
	OnStart OnStartFunc

	// 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

	// OnCompletion is called inline when ServeHTTP is finished and gets
	// useful data that the implementor can use for metrics. Optional.
	OnCompletion OnCompletionFunc
}

type LogOptions struct {
	// Logf is used to log HTTP requests and responses.
	Logf logger.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.
	QuietLogging bool
	// QuietLoggingIfSuccessful suppresses logging of handled HTTP requests
	// where the request's response status code is 200 or 304.
	QuietLoggingIfSuccessful bool

	// 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.
	OnStart OnStartFunc
	// OnCompletion is called inline when ServeHTTP is finished and gets
	// useful data that the implementor can use for metrics. Optional.
	OnCompletion OnCompletionFunc
}

type Middleware func(h http.Handler) http.Handler

type OnCompletionFunc func(*http.Request, AccessLogRecord)

type OnStartFunc func(*http.Request, AccessLogRecord)

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
}

type RequestID string

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