wrphttp

Documentation

Overview

Package wrphttp integrates go-kit's transport/http package with the patterns used by WebPA/XMiDT servers. Primarily, this package concerns itself with translating between HTTP requests and responses and WRP requests and responses.

Index

• Constants
• func AddMessageHeaders(h http.Header, m *wrp.Message)
• func DetermineFormat(defaultFormat wrp.Format, h http.Header, names ...string) (wrp.Format, error)
• func NewHTTPHandler(h Handler, options ...Option) http.Handler
• func NewMessageFromHeaders(h http.Header, p io.Reader) (message *wrp.Message, err error)
• func ReadPayload(h http.Header, p io.Reader, m *wrp.Message) (int, error)
• func SetMessageFromHeaders(h http.Header, m *wrp.Message) (err error)
• func WritePayload(h http.Header, p io.Writer, m *wrp.Message) (int, error)
• type Decoder
  • func DecodeEntity(defaultFormat wrp.Format) Decoder
  • func DefaultDecoder() Decoder
• type Entity
  • func DecodeRequestHeaders(ctx context.Context, original *http.Request) (*Entity, error)
• type Handler
• type HandlerFunc
  • func (hf HandlerFunc) ServeWRP(w ResponseWriter, r *Request)
• type MessageFunc
• type MockHandler
  • func (m *MockHandler) ServeWRP(response ResponseWriter, request *Request)
• type Option
  • func WithBefore(funcs ...MessageFunc) Option
  • func WithDecoder(d Decoder) Option
  • func WithErrorEncoder(ee gokithttp.ErrorEncoder) Option
  • func WithNewResponseWriter(rwf ResponseWriterFunc) Option
• type Request
  • func (r *Request) Context() context.Context
  • func (r *Request) WithContext(ctx context.Context) *Request
• type ResponseWriter
• type ResponseWriterFunc
  • func DefaultResponseWriterFunc() ResponseWriterFunc
  • func NewEntityResponseWriter(defaultFormat wrp.Format) ResponseWriterFunc

Constants

const (
	MessageTypeHeader             = "X-Xmidt-Message-Type"
	TransactionUuidHeader         = "X-Xmidt-Transaction-Uuid"
	StatusHeader                  = "X-Xmidt-Status"
	RequestDeliveryResponseHeader = "X-Xmidt-Request-Delivery-Response"
	IncludeSpansHeader            = "X-Xmidt-Include-Spans"
	SpanHeader                    = "X-Xmidt-Span"
	PathHeader                    = "X-Xmidt-Path"
	SourceHeader                  = "X-Xmidt-Source"
	DestinationHeader             = "X-Webpa-Device-Name"
	AcceptHeader                  = "X-Xmidt-Accept"
	MetadataHeader                = "X-Xmidt-Metadata"
	PartnerIdHeader               = "X-Xmidt-Partner-Id"
)

Functions

func AddMessageHeaders

func AddMessageHeaders(h http.Header, m *wrp.Message)

AddMessageHeaders adds the HTTP header representation of a given WRP message. This function does not handle the payload, to allow further headers to be written by calling code.

func DetermineFormat

func DetermineFormat(defaultFormat wrp.Format, h http.Header, names ...string) (wrp.Format, error)

DetermineFormat examines zero or more headers to determine which WRP format is to be used, either for decoding or encoding. The headers are tried in order, and the first non-empty value that maps to a WRP format is returned. Any non-empty header that is invalid results in an error. If none of the headers are present, this function returns the defaultFormat.

This function can be used with a single header, e.g. DetermineFormat(wrp.Msgpack, header, "Content-Type"). It can also be used for simple content negotiation, e.g. DetermineFormat(wrp.Msgpack, header, "Accept", "Content-Type").

func NewHTTPHandler

func NewHTTPHandler(h Handler, options ...Option) http.Handler

NewHTTPHandler creates an http.Handler that forwards WRP requests to the supplied WRP handler.

func NewMessageFromHeaders

func NewMessageFromHeaders(h http.Header, p io.Reader) (message *wrp.Message, err error)

NewMessageFromHeaders extracts a WRP message from a set of HTTP headers. If supplied, the given io.Reader is assumed to contain the payload of the WRP message.

func ReadPayload

func ReadPayload(h http.Header, p io.Reader, m *wrp.Message) (int, error)

ReadPayload extracts the payload from a reader, setting the appropriate fields on the given message.

func SetMessageFromHeaders

func SetMessageFromHeaders(h http.Header, m *wrp.Message) (err error)

SetMessageFromHeaders transfers header fields onto the given WRP message. The payload is not handled by this method.

func WritePayload

func WritePayload(h http.Header, p io.Writer, m *wrp.Message) (int, error)

WritePayload writes the WRP payload to the given io.Writer. If the message has no payload, this function does nothing.

The http.Header is optional. If supplied, the header's Content-Type and Content-Length will be set appropriately.

Types

type Decoder

type Decoder func(context.Context, *http.Request) (*Entity, error)

Decoder turns an HTTP request into a WRP entity.

func DecodeEntity

func DecodeEntity(defaultFormat wrp.Format) Decoder

func DefaultDecoder

func DefaultDecoder() Decoder

type Entity

type Entity struct {
	// Message holds the WRP message that was decoded
	Message wrp.Message

	// Format is the original format used to decode the message.
	// This will generally be used as the default format for output.
	Format wrp.Format
}

Entity represents a decoded WRP message.

func DecodeRequestHeaders

func DecodeRequestHeaders(ctx context.Context, original *http.Request) (*Entity, error)

DecodeRequestHeaders is a Decoder that uses the HTTP headers as fields of a WRP message. The HTTP entity, if specified, is used as the payload of the WRP message.

type Handler

type Handler interface {
	ServeWRP(ResponseWriter, *Request)
}

Handler is a WRP handler for messages over HTTP. This is the analog of http.Handler.

type HandlerFunc

type HandlerFunc func(ResponseWriter, *Request)

func (HandlerFunc) ServeWRP

func (hf HandlerFunc) ServeWRP(w ResponseWriter, r *Request)

type MessageFunc

type MessageFunc func(context.Context, *wrp.Message) context.Context

MessageFunc is a strategy for post-processing a WRP message, adding things to the context or performing other processing on the message itself.

type MockHandler

type MockHandler struct {
	mock.Mock
}

func (*MockHandler) ServeWRP

func (m *MockHandler) ServeWRP(response ResponseWriter, request *Request)

type Option

type Option func(*wrpHandler)

Option is a configurable option for an HTTP handler that works with WRP

func WithBefore

func WithBefore(funcs ...MessageFunc) Option

func WithDecoder

func WithDecoder(d Decoder) Option

WithDecoder sets a go-kit DecodeRequestFunc strategy that turns an http.Request into a WRP request. By default, DefaultDecoder() is used. If the supplied strategy is nil, it reverts to the default.

func WithErrorEncoder

func WithErrorEncoder(ee gokithttp.ErrorEncoder) Option

WithErrorEncoder establishes a go-kit ErrorEncoder for the given handler. By default, DefaultErrorEncoder is used. If the supplied ErrorEncoder is nil, it reverts to the default.

func WithNewResponseWriter

func WithNewResponseWriter(rwf ResponseWriterFunc) Option

WithNewResponseWriter establishes a factory function for ResponseWriter objects. By default, DefaultResponseWriterFunc() is used. If the supplied strategy function is nil, it reverts to the default.

type Request

type Request struct {
	// Original is the HTTP request which corresponds to this WRP request.  The request body will have
	// already been read to produce the entity.
	Original *http.Request

	// Entity is the decoded WRP message
	Entity *Entity
	// contains filtered or unexported fields
}

Request wraps an original http.Request and contains WRP message information. Context handling mimics http.Request.

func (*Request) Context

func (r *Request) Context() context.Context

Context returns the context associated with this WRP Request, which is not necessarily the same as the context returned by r.Original.Context(). Use this method instead of the original request.

func (*Request) WithContext

func (r *Request) WithContext(ctx context.Context) *Request

WithContext returns a shallow copy of this WRP Request using the supplied context. The semantics of this method are the same as http.Request.WithContext. Note that the original request's context is not updated via this method.

type ResponseWriter

type ResponseWriter interface {
	http.ResponseWriter

	// WriteWRP writes a WRP message to the underlying response.  The format used is determined
	// by the configuration of the underlying implementation.  This method is idempotent, and returns
	// an error if called multiple times for the same instance.
	WriteWRP(interface{}) (int, error)
}

ResponseWriter extends http.ResponseWriter with some WRP behavior.

type ResponseWriterFunc

type ResponseWriterFunc func(http.ResponseWriter, *Request) (ResponseWriter, error)

func DefaultResponseWriterFunc

func DefaultResponseWriterFunc() ResponseWriterFunc

func NewEntityResponseWriter

func NewEntityResponseWriter(defaultFormat wrp.Format) ResponseWriterFunc

NewEntityResponseWriter creates a ResponseWriterFunc that returns an entity-based ResponseWriter. The returned ResponseWriter writes WRP messages to the response body, using content negotation with a fallback to the supplied default format.