http

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Sep 15, 2022 License: MIT Imports: 37 Imported by: 1

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

View Source 
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
	StatusUnauthorized                 = 401 // RFC 7235, 3.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
	StatusUnavailableForLegalReasons   = 451 // RFC 7725, 3

	StatusInternalServerError           = 500 // RFC 7231, 6.6.1
	StatusNotImplemented                = 501 // RFC 7231, 6.6.2
	StatusBadGateway                    = 502 // RFC 7231, 6.6.3
	StatusServiceUnavailable            = 503 // RFC 7231, 6.6.4
	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

View Source 
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"
)
View Source 
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

View Source 
var DefaultClient = &Client{}

DefaultClient is the default Client and is used by Get, Head, and Post.

Functions

func Get 

func Get(ctx context.Context, url string) (*http.Response, error)

Get issues a GET request via the Do function. 

func Head(ctx context.Context, url string) (resp *http.Response, err error)

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

func Post 

func Post(
	ctx context.Context, url string, contentType string, body io.Reader,
) (resp *http.Response, err error)

Post issues a POST to the specified URL.

func PostForm 

func PostForm(
	ctx context.Context, url string, data url.Values,
) (resp *http.Response, err error)

PostForm issues a POST to the specified URL, with data's keys and values URL-encoded as the request body.

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 

func (c *Client) Do(ctx context.Context, req *http.Request) (*http.Response, error)

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.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, url string) (*http.Response, error)

Get issues a GET request via the Do function.

func (*Client) Head 

func (c *Client) Head(ctx context.Context, url string) (*http.Response, error)

Head issues a HEAD request via the Do function.

func (*Client) Post 

func (c *Client) Post(
	ctx context.Context, url string, bodyType string, body io.Reader,
) (*http.Response, error)

Post issues a POST request via the Do function.

func (*Client) PostForm 

func (c *Client) PostForm(
	ctx context.Context, url string, data url.Values,
) (*http.Response, error)

PostForm issues a POST request via the Do function.

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 

type Middleware func(ServeFunc) ServeFunc

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 

func OptIdleTimeout(d time.Duration) Option

OptIdleTimeout configures the maximum amount of time to wait for the next request when keep-alives are enabled.

func OptReadHeaderTimeout 

func OptReadHeaderTimeout(d time.Duration) Option

OptReadHeaderTimeout configures the amount of time allowed to read request headers

func OptReadTimeout 

func OptReadTimeout(d time.Duration) Option

OptReadTimeout configures the maximum duration for reading the entire request, including the body.

func OptTLS 

func OptTLS(config *tls.Config) Option

OptTLS changes the handler TLS configuration.

func OptWriteTimeout 

func OptWriteTimeout(d time.Duration) Option

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

func (*ParseGob) Parse 

func (d *ParseGob) Parse(v interface{}) error

Parse unmarshal the request payload into the given structure

func (*ParseGob) Type 

func (d *ParseGob) Type() string

Type returns the mime type

type ParseJSON 

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

ParseJSON Parses JSON

func (*ParseJSON) Parse 

func (d *ParseJSON) Parse(v interface{}) error

Parse unmarshal the request payload into the given structure

func (*ParseJSON) Type 

func (d *ParseJSON) Type() string

Type returns the mime type

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

func (*ParseNull) Parse 

func (d *ParseNull) Parse(v interface{}) error

Parse returns an error because this Parser has nothing to Parse

func (*ParseNull) Type 

func (d *ParseNull) Type() string

Type returns the mime type

type Parser 

type Parser interface {
	Type() string
	Parse(v interface{}) error
}

Parser is a request data Parser

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 

type RenderContent struct {
	Req     *http.Request
	Modtime time.Time
	Content io.ReadSeeker
}

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 

type RenderRedirect struct {
	Req *http.Request
	URL string
}

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

func (*Request) Parse 

func (r *Request) Parse(ctx context.Context, v interface{}) error

Parse parses the request body and decodes it on the given 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 

func (s *Server) ActivateTLS(certFile, keyFile string)

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 

func (s *Server) HandleEndpoint(e Endpoint)

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

func (s *Server) Serve(ctx context.Context, addr string) error

Serve starts serving HTTP requests (blocking call)

func (*Server) SetOptions 

func (s *Server) SetOptions(opts ...Option)

SetOptions changes the handler options

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.