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

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

    func ErrDecodingError(svc, m string, err error) error

      ErrDecodingError is the error returned when the decoder fails to decode the response body.

      func ErrEncodingError

      func ErrEncodingError(svc, m string, err error) error

        ErrEncodingError is the error returned when the encoder fails to encode the request body.

        func ErrInvalidResponse

        func ErrInvalidResponse(svc, m string, code int, body string) error

          ErrInvalidResponse is the error returned when the service responded with an unexpected response status code.

          func ErrInvalidType

          func ErrInvalidType(svc, m, expected string, actual interface{}) error

            ErrInvalidType is the error returned when the wrong type is given to a method function.

            func ErrInvalidURL

            func ErrInvalidURL(svc, m, u string, err error) error

              ErrInvalidURL is the error returned when the URL computed for an method is invalid.

              func ErrRequestError

              func ErrRequestError(svc, m string, err error) error

                ErrRequestError is the error returned when the request fails to be sent.

                func ErrValidationError

                func ErrValidationError(svc, m string, err error) error

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

                        func (*ClientError) Error

                        func (c *ClientError) Error() string

                          Error builds an error message.

                          type ConnConfigureFunc

                          type ConnConfigureFunc func(conn *websocket.Conn, cancel context.CancelFunc) *websocket.Conn

                            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

                              func NewDebugDoer(d Doer) DebugDoer

                                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

                                  func RequestDecoder(r *http.Request) Decoder

                                    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
                                    

                                    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

                                    func ResponseDecoder(resp *http.Response) Decoder

                                      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 Doer

                                        type Doer interface {
                                        	Do(*http.Request) (*http.Response, error)
                                        }

                                          Doer is the HTTP client interface.

                                          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

                                            func RequestEncoder(r *http.Request) Encoder

                                              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 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_]+".

                                                            func NewMuxer

                                                            func NewMuxer() Muxer

                                                              NewMuxer returns a Muxer implementation based on the httptreemux router.

                                                              type Server

                                                              type Server interface {
                                                              	Use(func(http.Handler) http.Handler)
                                                              }

                                                                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.

                                                                  func (Servers) Use

                                                                  func (s Servers) Use(m func(http.Handler) http.Handler)

                                                                    Use wraps the servers with the given middleware.

                                                                    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

                                                                      func NewErrorResponse(err error) Statuser

                                                                        NewErrorResponse creates a HTTP response from the given error.

                                                                        type Upgrader

                                                                        type Upgrader interface {
                                                                        	// Upgrade upgrades the HTTP connection to the websocket protocol.
                                                                        	Upgrade(w http.ResponseWriter, r *http.Request, responseHeader http.Header) (*websocket.Conn, error)
                                                                        }

                                                                          Upgrader is an HTTP connection that is able to upgrade to websocket.

                                                                          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.