goa: goa.design/goa/http Index | Files | Directories

package http

import "goa.design/goa/http"

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

Package Files

client.go doc.go encoding.go error.go mux.go websocket.go

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
)

func ErrDecodingError Uses

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

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

func ErrEncodingError Uses

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

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

func ErrInvalidResponse Uses

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 Uses

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 Uses

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 Uses

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

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

func ErrValidationError Uses

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 Uses

func ErrorEncoder(encoder func(context.Context, http.ResponseWriter) Encoder) func(context.Context, http.ResponseWriter, error) error

ErrorEncoder returns an encoder that encodes errors returned by service methods. The 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.

func SetContentType Uses

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

type ClientError Uses

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 Uses

func (c *ClientError) Error() string

Error builds an error message.

type ConnConfigureFunc Uses

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 Uses

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 Uses

func NewDebugDoer(d Doer) DebugDoer

NewDebugDoer wraps the given doer and captures the request and response so they can be printed.

type Decoder Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Doer is the HTTP client interface.

type Encoder Uses

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 Uses

func RequestEncoder(r *http.Request) Encoder

RequestEncoder returns a HTTP request encoder. The encoder uses package encoding/json.

func ResponseEncoder Uses

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 Uses

type EncodingFunc func(v interface{}) error

EncodingFunc allows a function with appropriate signature to act as a Decoder/Encoder.

func (EncodingFunc) Decode Uses

func (f EncodingFunc) Decode(v interface{}) error

Decode implements the Decoder interface. It simply calls f(v).

func (EncodingFunc) Encode Uses

func (f EncodingFunc) Encode(v interface{}) error

Encode implements the Encoder interface. It simply calls f(v).

type ErrorResponse Uses

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 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 NewErrorResponse Uses

func NewErrorResponse(err error) *ErrorResponse

NewErrorResponse creates a HTTP response from the given error.

func (*ErrorResponse) StatusCode Uses

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 Uses

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 Uses

func NewMuxer() Muxer

NewMuxer returns a Muxer implementation based on the httptreemux router.

type Upgrader Uses

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

PathSynopsis
codegenPackage 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.
codegen/openapiPackage openapi produces OpenAPI Specification 2.0 (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) for the HTTP endpoints.
middlewarePackage middleware contains HTTP middlewares that wrap a HTTP handler to provide additional functionality.
middleware/xrayPackage 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 http imports 18 packages (graph) and is imported by 13 packages. Updated 2019-09-12. Refresh now. Tools for package owners.