Documentation ¶
Overview ¶
Package http contains HTTP specific constructs that complement the code generated by Goa. The constructs include a composable HTTP client, default encodings, a mux and a websocket implementation that relies on the Gorilla websocket package.
Index ¶
- Constants
- func ErrDecodingError(svc, m string, err error) error
- func ErrEncodingError(svc, m string, err error) error
- func ErrInvalidResponse(svc, m string, code int, body string) error
- func ErrInvalidType(svc, m, expected string, actual interface{}) error
- func ErrInvalidURL(svc, m, u string, err error) error
- func ErrRequestError(svc, m string, err error) error
- func ErrValidationError(svc, m string, err error) error
- func ErrorEncoder(encoder func(context.Context, http.ResponseWriter) Encoder, ...) func(context.Context, http.ResponseWriter, error) error
- func Replace(old, nw string, h http.Handler) http.Handler
- func SetContentType(w http.ResponseWriter, ct string)
- type ClientError
- type ConnConfigureFunc
- type DebugDoer
- type Decoder
- type Dialer
- type Doer
- type Encoder
- type EncodingFunc
- type ErrorResponse
- type MiddlewareMuxer
- type Mounter
- type Muxer
- type Server
- type Servers
- type Statuser
- type Upgrader
Constants ¶
const ( // AcceptTypeKey is the context key used to store the value of the HTTP // request Accept-Type header. The value may be used by encoders and // decoders to implement a content type negotiation algorithm. AcceptTypeKey contextKey = iota + 1 // ContentTypeKey is the context key used to store the value of the HTTP // response Content-Type header when explicitly set in the DSL. The value // may be used by encoders to set the header appropriately. ContentTypeKey )
Variables ¶
This section is empty.
Functions ¶
func ErrDecodingError ¶
ErrDecodingError is the error returned when the decoder fails to decode the response body.
func ErrEncodingError ¶
ErrEncodingError is the error returned when the encoder fails to encode the request body.
func ErrInvalidResponse ¶
ErrInvalidResponse is the error returned when the service responded with an unexpected response status code.
func ErrInvalidType ¶
ErrInvalidType is the error returned when the wrong type is given to a method function.
func ErrInvalidURL ¶
ErrInvalidURL is the error returned when the URL computed for an method is invalid.
func ErrRequestError ¶
ErrRequestError is the error returned when the request fails to be sent.
func ErrValidationError ¶
ErrValidationError is the error returned when the response body is properly received and decoded but fails validation.
func ErrorEncoder ¶
func ErrorEncoder(encoder func(context.Context, http.ResponseWriter) Encoder, formatter func(err error) Statuser) func(context.Context, http.ResponseWriter, error) error
ErrorEncoder returns an encoder that encodes errors returned by service methods. The default encoder checks whether the error is a goa ServiceError struct and if so uses the error temporary and timeout fields to infer a proper HTTP status code and marshals the error struct to the body using the provided encoder. If the error is not a goa ServiceError struct then it is encoded as a permanent internal server error. This behavior as well as the shape of the response can be overridden by providing a non-nil formatter.
func Replace ¶
Replace returns a handler that serves HTTP requests by replacing the request URL's Path (and RawPath if set) and invoking the handler h. The logic is the same as the standard http package StripPrefix function.
func SetContentType ¶
func SetContentType(w http.ResponseWriter, ct string)
SetContentType initializes the response Content-Type header given a MIME type. If the Content-Type header is already set and the MIME type is "application/json" or "application/xml" then SetContentType appends a suffix to the header ("+json" or "+xml" respectively).
Types ¶
type ClientError ¶
type ClientError struct { // Name is a name for this class of errors. Name string // Message contains the specific error details. Message string // Service is the name of the service. Service string // Method is the name of the service method. Method string // Is the error temporary? Temporary bool // Is the error a timeout? Timeout bool // Is the error a server-side fault? Fault bool }
ClientError is an error returned by a HTTP service client.
type ConnConfigureFunc ¶
ConnConfigureFunc is used to configure a websocket connection with custom handlers. The cancel function cancels the request context when invoked in the configure function.
type DebugDoer ¶
type DebugDoer interface { Doer // Fprint prints the HTTP request and response details. Fprint(io.Writer) }
DebugDoer is a Doer that can print the low level HTTP details.
func NewDebugDoer ¶
NewDebugDoer wraps the given doer and captures the request and response so they can be printed.
type Decoder ¶
type Decoder interface { // Decode decodes into v. Decode(v interface{}) error }
Decoder provides the actual decoding algorithm used to load HTTP request and response bodies.
func RequestDecoder ¶
RequestDecoder returns a HTTP request body decoder suitable for the given request. The decoder handles the following mime types:
- application/json using package encoding/json
- application/xml using package encoding/xml
- application/gob using package encoding/gob
- text/html and text/plain for strings
RequestDecoder defaults to the JSON decoder if the request "Content-Type" header does not match any of the supported mime type or is missing altogether.
func ResponseDecoder ¶
ResponseDecoder returns a HTTP response decoder. The decoder handles the following content types:
- application/json using package encoding/json (default)
- application/xml using package encoding/xml
- application/gob using package encoding/gob
- text/html and text/plain for strings
type Dialer ¶
type Dialer interface { // DialContext creates a client connection to the websocket server. DialContext(ctx context.Context, url string, h http.Header) (*websocket.Conn, *http.Response, error) }
Dialer creates a websocket connection to a given URL.
type Encoder ¶
type Encoder interface { // Encode encodes v. Encode(v interface{}) error }
Encoder provides the actual encoding algorithm used to write HTTP request and response bodies.
func RequestEncoder ¶
RequestEncoder returns a HTTP request encoder. The encoder uses package encoding/json.
func ResponseEncoder ¶
func ResponseEncoder(ctx context.Context, w http.ResponseWriter) Encoder
ResponseEncoder returns a HTTP response encoder leveraging the mime type set in the context under the AcceptTypeKey or the ContentTypeKey if any. The encoder supports the following mime types:
- application/json using package encoding/json
- application/xml using package encoding/xml
- application/gob using package encoding/gob
- text/html and text/plain for strings
ResponseEncoder defaults to the JSON encoder if the context AcceptTypeKey or ContentTypeKey value does not match any of the supported mime types or is missing altogether.
type EncodingFunc ¶
type EncodingFunc func(v interface{}) error
EncodingFunc allows a function with appropriate signature to act as a Decoder/Encoder.
func (EncodingFunc) Decode ¶
func (f EncodingFunc) Decode(v interface{}) error
Decode implements the Decoder interface. It simply calls f(v).
func (EncodingFunc) Encode ¶
func (f EncodingFunc) Encode(v interface{}) error
Encode implements the Encoder interface. It simply calls f(v).
type ErrorResponse ¶
type ErrorResponse struct { // Name is a name for that class of errors. Name string `json:"name" xml:"name" form:"name"` // ID is the unique error instance identifier. ID string `json:"id" xml:"id" form:"id"` // Message describes the specific error occurrence. Message string `json:"message" xml:"message" form:"message"` // Temporary indicates whether the error is temporary. Temporary bool `json:"temporary" xml:"temporary" form:"temporary"` // Timeout indicates whether the error is a timeout. Timeout bool `json:"timeout" xml:"timeout" form:"timeout"` // Fault indicates whether the error is a server-side fault. Fault bool `json:"fault" xml:"fault" form:"fault"` }
ErrorResponse is the default data structure encoded in HTTP responses that correspond to errors created by the generated code. This struct is mainly intended for clients to decode error responses.
func (*ErrorResponse) StatusCode ¶
func (resp *ErrorResponse) StatusCode() int
StatusCode implements a heuristic that computes a HTTP response status code appropriate for the timeout, temporary and fault characteristics of the error. This method is used by the generated server code when the error is not described explicitly in the design.
type MiddlewareMuxer ¶
type MiddlewareMuxer interface { Muxer // Use appends a middleware to the list of middlewares to be applied // to the Muxer. Use(func(http.Handler) http.Handler) }
MiddlewareMuxer makes it possible to mount middlewares downstream of the Muxer.
func NewMuxer ¶
func NewMuxer() MiddlewareMuxer
NewMuxer returns a Muxer implementation based on the httptreemux router.
type Mounter ¶
type Mounter interface {
Mount(Muxer)
}
Mounter is the interface for servers that allow mounting their endpoints into a muxer.
type Muxer ¶
type Muxer interface { // Handle registers the handler function for the given method // and pattern. Handle(method, pattern string, handler http.HandlerFunc) // ServeHTTP dispatches the request to the handler whose method // matches the request method and whose pattern most closely // matches the request URL. ServeHTTP(http.ResponseWriter, *http.Request) // Vars returns the path variables captured for the given // request. Vars(*http.Request) map[string]string }
Muxer is the HTTP request multiplexer interface used by the generated code. ServerHTTP must match the HTTP method and URL of each incoming request against the list of registered patterns and call the handler for the corresponding method and the pattern that most closely matches the URL.
The patterns may include wildcards that identify URL segments that must be captured.
There are two forms of wildcards the implementation must support:
"{name}" wildcards capture a single path segment, for example the pattern "/images/{name}" captures "/images/favicon.ico" and adds the key "name" with the value "favicon.ico" to the map returned by Vars.
"{*name}" wildcards must appear at the end of the pattern and captures the entire path starting where the wildcard matches. For example the pattern "/images/{*filename}" captures "/images/public/thumbnail.jpg" and associates the key key "filename" with "public/thumbnail.jpg" in the map returned by Vars.
The names of wildcards must match the regular expression "[a-zA-Z0-9_]+".
type Server ¶
Server is the HTTP server interface used to wrap the server handlers with the given middleware.
type Servers ¶
type Servers []Server
Servers is a list of servers.
type Statuser ¶
type Statuser interface { // StatusCode return the HTTP status code used to encode the response // when not defined in the design. StatusCode() int }
Statuser is implemented by error response object to provide the response HTTP status code.
func NewErrorResponse ¶
NewErrorResponse creates a HTTP response from the given error.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package codegen contains code generation logic to generate HTTP server and client that wrap the generated goa endpoint and the OpenAPI 2.0 specifications for the HTTP endpoints.
|
Package codegen contains code generation logic to generate HTTP server and client that wrap the generated goa endpoint and the OpenAPI 2.0 specifications for the HTTP endpoints. |
openapi
Package openapi provides common algorithms and data structures used to generate both OpenAPI v2 and v3 specifications from Goa designs.
|
Package openapi provides common algorithms and data structures used to generate both OpenAPI v2 and v3 specifications from Goa designs. |
openapi/v2
Package openapiv2 contains the algorithms and data structures used to generate OpenAPI v2 specifications from Goa designs.
|
Package openapiv2 contains the algorithms and data structures used to generate OpenAPI v2 specifications from Goa designs. |
openapi/v3
Package openapiv3 contains the algorithms and data structures used to generate OpenAPI v3 specifications from Goa designs.
|
Package openapiv3 contains the algorithms and data structures used to generate OpenAPI v3 specifications from Goa designs. |
Package middleware contains HTTP middlewares that wrap a HTTP handler to provide additional functionality.
|
Package middleware contains HTTP middlewares that wrap a HTTP handler to provide additional functionality. |
xray
Package xray contains middleware that creates AWS X-Ray segments from the HTTP requests and responses and send the segments to an AWS X-ray daemon.
|
Package xray contains middleware that creates AWS X-Ray segments from the HTTP requests and responses and send the segments to an AWS X-ray daemon. |