http

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
• Variables
• 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 any) 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 SetContentType(w http.ResponseWriter, ct string)
• type ClientError
  • func (c ClientError) Error() string
  • func (c ClientError) Unwrap() error
• type ConnConfigureFunc
• type DebugDoer
  • func NewDebugDoer(d Doer) DebugDoer
• type Decoder
  • func RequestDecoder(r *http.Request) Decoder
  • func ResponseDecoder(resp *http.Response) Decoder
• type Dialer
• type Doer
• type Encoder
  • func RequestEncoder(r *http.Request) Encoder
  • func ResponseEncoder(ctx context.Context, w http.ResponseWriter) Encoder
• type EncodingFunc
  • func (f EncodingFunc) Decode(v any) error
  • func (f EncodingFunc) Encode(v any) error
• type ErrorResponse
  • func (resp *ErrorResponse) MarshalXML(e *xml.Encoder, _ xml.StartElement) error
  • func (resp *ErrorResponse) StatusCode() int
• type MiddlewareMuxer
• type Mounter
• type Muxer
• type ResolverMuxer
  • func NewMuxer() ResolverMuxer
• type Server
• type Servers
  • func (s Servers) Mount(mux Muxer)
  • func (s Servers) Use(m func(http.Handler) http.Handler)
• type Statuser
  • func NewErrorResponse(ctx context.Context, err error) 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

var (
	// ErrorResponseXMLName is the XML name used for ErrorResponse.
	ErrorResponseXMLName = xml.Name{Local: "error"}
)

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 any) 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(ctx context.Context, 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
	// The original error if any
	Err error
}

ClientError is an error returned by a HTTP service client.

func (ClientError) Error

func (c ClientError) Error() string

Error builds an error message.

func (ClientError) Unwrap

func (c ClientError) Unwrap() error

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 any) 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
• 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

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 any) 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 any) error

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

func (EncodingFunc) Decode

func (f EncodingFunc) Decode(v any) error

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

func (EncodingFunc) Encode

func (f EncodingFunc) Encode(v any) 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) MarshalXML

func (resp *ErrorResponse) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

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.

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 ResolverMuxer

type ResolverMuxer interface {
	MiddlewareMuxer
	ResolvePattern(*http.Request) string
}

ResolverMuxer is a MiddlewareMuxer that can resolve the route pattern used to register the handler for the given request.

func NewMuxer

func NewMuxer() ResolverMuxer

NewMuxer returns a Muxer implementation based on a Chi 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) Mount

func (s Servers) Mount(mux Muxer)

Mount will go through all the servers and mount them into the Muxer. It will panic unless all servers satisfy the Mounter interface.

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(ctx context.Context, 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.