Documentation
¶
Overview ¶
Package http is an extra layer on to of the standard go net/http package.
This package does most of the heavy lifting for common http APIs, such as:
- Routing
- Request parsing
- Response rendering
- Graceful shutdown
- Basic security
- Logging
- Stats
- Tracing
Index ¶
- Constants
- Variables
- func Get(ctx context.Context, url string) (*http.Response, error)
- func Head(ctx context.Context, url string) (resp *http.Response, err error)
- func Post(ctx context.Context, url string, contentType string, body io.Reader) (resp *http.Response, err error)
- func PostForm(ctx context.Context, url string, data url.Values) (resp *http.Response, err error)
- type Client
- func (c *Client) Do(ctx context.Context, req *http.Request) (*http.Response, error)
- func (c *Client) Get(ctx context.Context, url string) (*http.Response, error)
- func (c *Client) Head(ctx context.Context, url string) (*http.Response, error)
- func (c *Client) Post(ctx context.Context, url string, bodyType string, body io.Reader) (*http.Response, error)
- func (c *Client) PostForm(ctx context.Context, url string, data url.Values) (*http.Response, error)
- type Endpoint
- type Middleware
- type Option
- type ParseGob
- type ParseJSON
- type ParseNull
- type Parser
- type RenderConditional
- type RenderContent
- type RenderData
- type RenderGob
- type RenderHead
- type RenderJSON
- type RenderRedirect
- type Renderer
- type Request
- type ResponseWriter
- type ServeFunc
- type Server
- func (s *Server) ActivateTLS(certFile, keyFile string)
- func (s *Server) Append(m Middleware)
- func (s *Server) Drain()
- func (s *Server) HandleEndpoint(e Endpoint)
- func (s *Server) HandleFunc(path, method string, f func(ctx context.Context, w ResponseWriter, r *Request))
- func (s *Server) HandleStatic(path, root string, ...)
- func (s *Server) Serve(ctx context.Context, addr string) error
- func (s *Server) SetOptions(opts ...Option)
Constants ¶
const ( StatusContinue = 100 // RFC 7231, 6.2.1 StatusSwitchingProtocols = 101 // RFC 7231, 6.2.2 StatusProcessing = 102 // RFC 2518, 10.1 StatusOK = 200 // RFC 7231, 6.3.1 StatusCreated = 201 // RFC 7231, 6.3.2 StatusAccepted = 202 // RFC 7231, 6.3.3 StatusNonAuthoritativeInfo = 203 // RFC 7231, 6.3.4 StatusNoContent = 204 // RFC 7231, 6.3.5 StatusResetContent = 205 // RFC 7231, 6.3.6 StatusPartialContent = 206 // RFC 7233, 4.1 StatusMultiStatus = 207 // RFC 4918, 11.1 StatusAlreadyReported = 208 // RFC 5842, 7.1 StatusIMUsed = 226 // RFC 3229, 10.4.1 StatusMultipleChoices = 300 // RFC 7231, 6.4.1 StatusMovedPermanently = 301 // RFC 7231, 6.4.2 StatusFound = 302 // RFC 7231, 6.4.3 StatusSeeOther = 303 // RFC 7231, 6.4.4 StatusNotModified = 304 // RFC 7232, 4.1 StatusUseProxy = 305 // RFC 7231, 6.4.5 StatusTemporaryRedirect = 307 // RFC 7231, 6.4.7 StatusPermanentRedirect = 308 // RFC 7538, 3 StatusBadRequest = 400 // RFC 7231, 6.5.1 StatusPaymentRequired = 402 // RFC 7231, 6.5.2 StatusForbidden = 403 // RFC 7231, 6.5.3 StatusNotFound = 404 // RFC 7231, 6.5.4 StatusMethodNotAllowed = 405 // RFC 7231, 6.5.5 StatusNotAcceptable = 406 // RFC 7231, 6.5.6 StatusProxyAuthRequired = 407 // RFC 7235, 3.2 StatusRequestTimeout = 408 // RFC 7231, 6.5.7 StatusConflict = 409 // RFC 7231, 6.5.8 StatusGone = 410 // RFC 7231, 6.5.9 StatusLengthRequired = 411 // RFC 7231, 6.5.10 StatusPreconditionFailed = 412 // RFC 7232, 4.2 StatusRequestEntityTooLarge = 413 // RFC 7231, 6.5.11 StatusRequestURITooLong = 414 // RFC 7231, 6.5.12 StatusUnsupportedMediaType = 415 // RFC 7231, 6.5.13 StatusRequestedRangeNotSatisfiable = 416 // RFC 7233, 4.4 StatusExpectationFailed = 417 // RFC 7231, 6.5.14 StatusTeapot = 418 // RFC 7168, 2.3.3 StatusUnprocessableEntity = 422 // RFC 4918, 11.2 StatusLocked = 423 // RFC 4918, 11.3 StatusFailedDependency = 424 // RFC 4918, 11.4 StatusUpgradeRequired = 426 // RFC 7231, 6.5.15 StatusPreconditionRequired = 428 // RFC 6585, 3 StatusTooManyRequests = 429 // RFC 6585, 4 StatusRequestHeaderFieldsTooLarge = 431 // RFC 6585, 5 StatusInternalServerError = 500 // RFC 7231, 6.6.1 StatusNotImplemented = 501 // RFC 7231, 6.6.2 StatusBadGateway = 502 // RFC 7231, 6.6.3 StatusGatewayTimeout = 504 // RFC 7231, 6.6.5 StatusHTTPVersionNotSupported = 505 // RFC 7231, 6.6.6 StatusVariantAlsoNegotiates = 506 // RFC 2295, 8.1 StatusInsufficientStorage = 507 // RFC 4918, 11.5 StatusLoopDetected = 508 // RFC 5842, 7.2 StatusNotExtended = 510 // RFC 2774, 7 StatusNetworkAuthenticationRequired = 511 // RFC 6585, 6 )
HTTP status codes as registered with IANA. See: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
const ( // OPTIONS method represents a request for information about the communication options available // on the request/response chain identified by the Request-URI. OPTIONS = "OPTIONS" // GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI. GET = "GET" // HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. // The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical // to the information sent in response to a GET request. HEAD = "HEAD" // POST method is used to request that the origin server accept the entity enclosed in the request as // a new subordinate of the resource identified by the Request-URI in the Request-Line. POST = "POST" // PUT method requests that the enclosed entity be stored under the supplied Request-URI. // If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered // as a modified version of the one residing on the origin server. // If the Request-URI does not point to an existing resource, and that URI is capable of being defined // as a new resource by the requesting user agent, the origin server can create the resource with that URI. PUT = "PUT" // DELETE method requests that the origin server delete the resource identified by the Request-URI. DELETE = "DELETE" // TRACE method is used to invoke a remote, application-layer loop-back of the request message. TRACE = "TRACE" // PATCH is similar to PUT, but unlike PUT which proceeds to a complete replacement of a document, // PATCH to modifies partially an existing document. PATCH = "PATCH" // LINK is used to establish one or more relationships between the resource identified by the effective // request URI and one or more other resources. LINK = "LINK" // UNLINK is used to remove one or more relationships between the resource identified by the effective // request URI and other resources. UNLINK = "UNLINK" )
const TimeFormat = "Mon, 02 Jan 2006 15:04:05 GMT"
TimeFormat is the time format to use when generating times in HTTP headers. It is like time.RFC1123 but hard-codes GMT as the time zone. The time being formatted must be in UTC for Format to generate the correct format.
For parsing this time format, see ParseTime.
Variables ¶
var DefaultClient = &Client{}
DefaultClient is the default Client and is used by Get, Head, and Post.
Functions ¶
func Head ¶
Head issues a HEAD to the specified URL. If the response is one of the following redirect codes, Head follows the redirect, up to a maximum of 10 redirects:
301 (Moved Permanently) 302 (Found) 303 (See Other) 307 (Temporary Redirect) 308 (Permanent Redirect)
Head is a wrapper around DefaultClient.Head
Types ¶
type Client ¶
type Client struct {
// HTTP is the standard net/http client
HTTP http.Client
// PropagateContext tells whether the context should be propagated upstream
//
// This should be activated when the upstream endpoint is a SPINE service
// or another SPINE-compatible service. The context can potentially leak
// sensitive information, so do not activate it for services that you don't trust.
PropagateContext bool
}
Client is a wrapper for the standard net/http client.
func (*Client) Do ¶
Do sends an HTTP request with the provided http.Client and returns an HTTP response.
If the client is nil, http.DefaultClient is used.
The provided ctx must be non-nil. If it is canceled or times out, ctx.Err() will be returned.
type Endpoint ¶
type Endpoint interface {
Path() string
Method() string
Attach(*mux.Router, func(http.ResponseWriter, *http.Request))
Serve(ctx context.Context, w ResponseWriter, r *Request)
}
An Endpoint is a an entity that serves a request from a given route
type Middleware ¶
Middleware is a function called on the HTTP stack before an action
type Option ¶
type Option func(*Server)
Option allows to configure unexported handler fields
func OptIdleTimeout ¶
OptIdleTimeout configures the maximum amount of time to wait for the next request when keep-alives are enabled.
func OptReadHeaderTimeout ¶
OptReadHeaderTimeout configures the amount of time allowed to read request headers
func OptReadTimeout ¶
OptReadTimeout configures the maximum duration for reading the entire request, including the body.
func OptWriteTimeout ¶
OptWriteTimeout configures the maximum duration before timing out writes of the response
type ParseGob ¶
type ParseGob struct {
// contains filtered or unexported fields
}
ParseGob Parses Gob
type ParseJSON ¶
type ParseJSON struct {
// contains filtered or unexported fields
}
ParseJSON Parses JSON
type ParseNull ¶
type ParseNull struct {
// contains filtered or unexported fields
}
ParseNull is a null-object that is used when no other Parsers have been found
type RenderConditional ¶
type RenderConditional struct {
Req *http.Request
ETag string
LastModified time.Time
Next Renderer
}
func (*RenderConditional) Render ¶
func (r *RenderConditional) Render(res ResponseWriter) error
type RenderContent ¶
func (*RenderContent) Render ¶
func (r *RenderContent) Render(res ResponseWriter) error
type RenderData ¶
type RenderData struct {
Code int
ContentType string
Reader io.ReadCloser
}
func (*RenderData) Render ¶
func (r *RenderData) Render(res ResponseWriter) error
type RenderGob ¶
type RenderGob struct {
Code int
V interface{}
}
RenderGob is a renderer that marshals responses in Gob
func (*RenderGob) Render ¶
func (r *RenderGob) Render(res ResponseWriter) error
type RenderHead ¶
type RenderHead struct {
Code int
}
RenderHead is a renderer that returns a body-less response
func (*RenderHead) Render ¶
func (r *RenderHead) Render(res ResponseWriter) error
type RenderJSON ¶
type RenderJSON struct {
Code int
V interface{}
}
RenderJSON is a renderer that marshals responses in JSON
func (*RenderJSON) Render ¶
func (r *RenderJSON) Render(res ResponseWriter) error
type RenderRedirect ¶
RenderRedirect is a renderer that returns a redirection
func (*RenderRedirect) Render ¶
func (r *RenderRedirect) Render(res ResponseWriter) error
type Renderer ¶
type Renderer interface {
// Render writes a response to the response writer
Render(ResponseWriter) error
}
Renderer is a response returned by an action
type Request ¶
type Request struct {
HTTP *http.Request
Params map[string]string
// contains filtered or unexported fields
}
Request wraps the standard net/http Request struct
type ResponseWriter ¶
type ResponseWriter interface {
// Header returns the header map that will be sent by
// WriteHeader. The Header map also is the mechanism with which
// Handlers can set HTTP trailers.
//
// Changing the header map after a call to WriteHeader (or
// Write) has no effect unless the modified headers are
// trailers.
//
// There are two ways to set Trailers. The preferred way is to
// predeclare in the headers which trailers you will later
// send by setting the "Trailer" header to the names of the
// trailer keys which will come later. In this case, those
// keys of the Header map are treated as if they were
// trailers. See the example. The second way, for trailer
// keys not known to the Handler until after the first Write,
// is to prefix the Header map keys with the TrailerPrefix
// constant value. See TrailerPrefix.
//
// To suppress implicit response headers (such as "Date"), set
// their value to nil.
Header() http.Header
// Write writes the data to the connection as part of an HTTP reply.
//
// If WriteHeader has not yet been called, Write calls
// WriteHeader(http.StatusOK) before writing the data. If the Header
// does not contain a Content-Type line, Write adds a Content-Type set
// to the result of passing the initial 512 bytes of written data to
// DetectContentType.
//
// Depending on the HTTP protocol version and the client, calling
// Write or WriteHeader may prevent future reads on the
// Request.Body. For HTTP/1.x requests, handlers should read any
// needed request body data before writing the response. Once the
// headers have been flushed (due to either an explicit Flusher.Flush
// call or writing enough data to trigger a flush), the request body
// may be unavailable. For HTTP/2 requests, the Go HTTP server permits
// handlers to continue to read the request body while concurrently
// writing the response. However, such behavior may not be supported
// by all HTTP/2 clients. Handlers should read before writing if
// possible to maximize compatibility.
Write([]byte) (int, error)
// WriteHeader sends an HTTP response header with status code.
// If WriteHeader is not called explicitly, the first call to Write
// will trigger an implicit WriteHeader(http.StatusOK).
// Thus explicit calls to WriteHeader are mainly used to
// send error codes.
WriteHeader(int)
// Code returns the written status code.
// If it has not been set yet, it will return 0
Code() int
// HasCode returns whether the status code has been set
HasCode() bool
// Head replies to the request using the provided data. It encodes the
// response in JSON
JSON(code int, data interface{}) error
// Head replies to the request using the provided data. It encodes the
// response in gob.
// Since gob does not have an official mime type, Content-Type will be set
// to `application/octet-stream`
Gob(code int, data interface{}) error
// Head replies to the request only with a header
Head(code int) error
// Redirect replies to the request with an http.StatusTemporaryRedirect to
// url, which may be a path relative to the request path.
Redirect(req *http.Request, url string) error
// Content replies to the request using the content in the provided
// ReadSeeker.
// The main benefit of Content over Data is that it handles Range requests
// properly, sets the MIME type, and handles If-Match, If-Unmodified-Since,
// If-None-Match, If-Modified-Since, and If-Range requests.
//
// If modtime is not the zero time or Unix epoch, Content includes it in a
// Last-Modified header in the response.
// If the request includes an If-Modified-Since header, Content uses modtime
// to decide whether the content needs to be sent at all.
//
// Using Conditional with Content is redundant.
Content(req *http.Request, content io.ReadSeeker, modtime ...time.Time) error
// Data encodes an arbitrary type of data
Data(code int, contentType string, data io.ReadCloser) error
// Conditional checks whether the request conditions are fresh.
// If the request is fresh, it returns a 304, otherwise it calls the next
// renderer
Conditional(
req *http.Request, etag string, lastModified time.Time, next func() error,
) error
}
ResponseWriter wraps the standard net/http Response struct The main reason of wrapping it is to interact with the status code and avoid double the “http: multiple response.WriteHeader calls” warnings
type ServeFunc ¶
type ServeFunc func(ctx context.Context, w ResponseWriter, r *Request)
ServeFunc is the function signature for standard endpoints
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
A Server defines parameters for running a spine compatible HTTP server The zero value for Server is a valid configuration.
func NewServer ¶
func NewServer() *Server
NewServer creates a new server and attaches the default middlewares
func (*Server) ActivateTLS ¶
ActivateTLS activates TLS on this handler. That means only incoming HTTPS connections are allowed.
If the certificate is signed by a certificate authority, the certFile should be the concatenation of the server's certificate, any intermediates, and the CA's certificate.
func (*Server) Append ¶
func (s *Server) Append(m Middleware)
Append appends the given middleware to the call chain
func (*Server) Drain ¶
func (s *Server) Drain()
Drain puts the handler into drain mode. All new requests will be blocked with a 503 and it will block this call until all in-flight requests have been completed
func (*Server) HandleEndpoint ¶
HandleEndpoint registers an endpoint. This is particularily useful for custom endpoint types
func (*Server) HandleFunc ¶
func (s *Server) HandleFunc( path, method string, f func(ctx context.Context, w ResponseWriter, r *Request), )
HandleFunc registers a new function as an action on the given path and method
func (*Server) HandleStatic ¶
func (s *Server) HandleStatic( path, root string, hook ...func(ctx context.Context, w ResponseWriter, r *Request, serveFile func()), )
HandleStatic registers a new route on the given path with path prefix to serve static files from the provided root directory
func (*Server) SetOptions ¶
SetOptions changes the handler options