wrp

package
v1.3.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 8, 2019 License: Apache-2.0 Imports: 9 Imported by: 2

Documentation

Overview

Package wrp defines the various WRP messages supported by WebPA and implements serialization for those messages.

Some common uses of this package include:

(1) Encoding a specific message to send to a WebPA server:

var (
	// the infrastructure automatically fills in the correct Type field
	message = SimpleRequestResponse{
		Source: "myserver.com",
		Destination: "mac:112233445566",
		Payload: []byte("here is a lovely little payload that the device understands"),
	}

	buffer bytes.Buffer
	encoder = NewEncoder(&buffer, Msgpack)
)

if err := encoder.Encode(&message); err != nil {
	// deal with the error
}

(2) Decoding any generic WRP message, perhaps sent by a client:

// encoded may also be an io.Reader if desired
func myHandler(encoded []byte) (message *Message, err error) {
	decoder := NewDecoderBytes(encoded, Msgpack)
	message = new(Message)
	err = decoder.Decode(message)
	return
}

(3) Transcoding messages from one format to another:

// assume source contains a JSON message
func jsonToMsgpack(source io.Reader) ([]byte, error) {
	var (
		decoder = NewDecoder(source, JSON)
		buffer bytes.Buffer
		encoder = NewEncoder(&buffer, Msgpack)
	)

	// TranscodeMessage returns a *Message as its first value, which contains
	// the generic WRP message data
	if _, err := TranscodeMessage(encoder, decoder); err != nil {
		return nil, err
	}

	return buffer.Bytes(), nil
}

(4) Pooling encoders and/or decoders for efficiency:

// transcoding, using pools:
var (
	decoderPool = NewDecoderPool(100, JSON)
	encoderPool = NewEncoderPool(100, Msgpack)
)

func jsonToMsgpackUsingPools(source io.Reader) ([]byte, error) {
	var (
		decoder = decoderPool.Get()
		buffer bytes.Buffer
		encoder = encoderPool.Get()
	)

	defer decoderPool.Put(decoder)
	defer encoderPool.Put(encoder)

	// TranscodeMessage returns a *Message as its first value, which contains
	// the generic WRP message data
	if _, err := TranscodeMessage(encoder, decoder); err != nil {
		return nil, err
	}

	return buffer.Bytes(), nil
}

Index

Constants

View Source
const (
	MsgTypeHeader         = "X-Midt-Msg-Type"
	TransactionUuidHeader = "X-Midt-Transaction-Uuid"
	StatusHeader          = "X-Midt-Status"
	RDRHeader             = "X-Midt-Request-Delivery-Response"
	HeadersArrHeader      = "X-Midt-Headers"
	IncludeSpansHeader    = "X-Midt-Include-Spans"
	SpansHeader           = "X-Midt-Spans"
	PathHeader            = "X-Midt-Path"
	SourceHeader          = "X-Midt-Source"
)

Constant HTTP header strings representing WRP fields

Variables

View Source
var ErrInvalidMsgType = errors.New("Invalid Message Type")

Functions

func MustEncode

func MustEncode(message interface{}, f Format) []byte

MustEncode is a convenience function that attempts to encode a given message. A panic is raised on any error. This function is handy for package initialization.

Types

type CRUD

type CRUD struct {
	Type                    MessageType       `wrp:"msg_type"`
	Source                  string            `wrp:"source"`
	Destination             string            `wrp:"dest"`
	TransactionUUID         string            `wrp:"transaction_uuid,omitempty"`
	ContentType             string            `wrp:"content_type,omitempty"`
	Headers                 []string          `wrp:"headers,omitempty"`
	Metadata                map[string]string `wrp:"metadata,omitempty"`
	Spans                   [][]string        `wrp:"spans,omitempty"`
	IncludeSpans            *bool             `wrp:"include_spans,omitempty"`
	Status                  *int64            `wrp:"status,omitempty"`
	RequestDeliveryResponse *int64            `wrp:"rdr,omitempty"`
	Path                    string            `wrp:"path"`
	Payload                 []byte            `wrp:"payload,omitempty"`
	PartnerIDs              []string          `wrp:"partner_ids,omitempty"`
}

CRUD represents a WRP message of one of the CRUD message types. This type does not implement BeforeEncode, and so does not automatically set the Type field. Client code must set the Type code appropriately.

https://github.com/xmidt-org/wrp-c/wiki/Web-Routing-Protocol#crud-message-definition

func (*CRUD) CodecDecodeSelf

func (x *CRUD) CodecDecodeSelf(d *codec1978.Decoder)

func (*CRUD) CodecEncodeSelf

func (x *CRUD) CodecEncodeSelf(e *codec1978.Encoder)

func (*CRUD) From

func (msg *CRUD) From() string

func (*CRUD) IsTransactionPart

func (msg *CRUD) IsTransactionPart() bool

func (*CRUD) MessageType

func (msg *CRUD) MessageType() MessageType

func (*CRUD) Response

func (msg *CRUD) Response(newSource string, requestDeliveryResponse int64) Routable

func (*CRUD) SetIncludeSpans

func (msg *CRUD) SetIncludeSpans(value bool) *CRUD

SetIncludeSpans simplifies setting the optional IncludeSpans field, which is a pointer type tagged with omitempty.

func (*CRUD) SetRequestDeliveryResponse

func (msg *CRUD) SetRequestDeliveryResponse(value int64) *CRUD

SetRequestDeliveryResponse simplifies setting the optional RequestDeliveryResponse field, which is a pointer type tagged with omitempty.

func (*CRUD) SetStatus

func (msg *CRUD) SetStatus(value int64) *CRUD

SetStatus simplifies setting the optional Status field, which is a pointer type tagged with omitempty.

func (*CRUD) To

func (msg *CRUD) To() string

func (*CRUD) TransactionKey

func (msg *CRUD) TransactionKey() string

type Decoder

type Decoder interface {
	Decode(interface{}) error
	Reset(io.Reader)
	ResetBytes([]byte)
}

Decoder represents the underlying ugorji behavior that WRP supports

func NewDecoder

func NewDecoder(input io.Reader, f Format) Decoder

NewDecoder produces a ugorji Decoder using the appropriate WRP configuration for the given format

func NewDecoderBytes

func NewDecoderBytes(input []byte, f Format) Decoder

NewDecoderBytes produces a ugorji Decoder using the appropriate WRP configuration for the given format

type EncodeListener

type EncodeListener interface {
	BeforeEncode() error
}

EncodeListener can be implemented on any type passed to an Encoder in order to get notified when an encoding happens. This interface is useful to set mandatory fields, such as message type.

type Encoder

type Encoder interface {
	Encode(interface{}) error
	Reset(io.Writer)
	ResetBytes(*[]byte)
}

Encoder represents the underlying ugorji behavior that WRP supports

func NewEncoder

func NewEncoder(output io.Writer, f Format) Encoder

NewEncoder produces a ugorji Encoder using the appropriate WRP configuration for the given format

func NewEncoderBytes

func NewEncoderBytes(output *[]byte, f Format) Encoder

NewEncoderBytes produces a ugorji Encoder using the appropriate WRP configuration for the given format

type Format

type Format int

Format indicates which format is desired. The zero value indicates Msgpack, which means by default other infrastructure can assume msgpack-formatted data.

const (
	Msgpack Format = iota
	JSON
)

func AllFormats

func AllFormats() []Format

AllFormats returns a distinct slice of all supported formats.

func FormatFromContentType

func FormatFromContentType(contentType string, fallback ...Format) (Format, error)

FormatFromContentType examines the Content-Type value and returns the appropriate Format. This function returns an error if the given Content-Type did not map to a WRP format.

The optional fallback is used if contentType is the empty string. Only the first fallback value is used. The rest are ignored. This approach allows simple usages such as:

FormatFromContentType(header.Get("Content-Type"), wrp.Msgpack)

func (Format) ContentType

func (f Format) ContentType() string

ContentType returns the MIME type associated with this format

func (Format) String

func (i Format) String() string

type Message

type Message struct {
	// Type The message type for the message
	//
	// required: true
	// example: 4
	Type MessageType `wrp:"msg_type"`

	// Source The device_id name of the device originating the request or response.
	//
	// required: false
	// example: dns:talaria.xmidt.example.com
	Source string `wrp:"source,omitempty"`

	// Destination The device_id name of the target device of the request or response.
	//
	// required: false
	// example: event:device-status/mac:ffffffffdae4/online
	Destination string `wrp:"dest,omitempty"`

	// TransactionUUID The transaction key for the message
	//
	// required: false
	// example: 546514d4-9cb6-41c9-88ca-ccd4c130c525
	TransactionUUID string `wrp:"transaction_uuid,omitempty"`

	// ContentType The media type of the payload.
	//
	// required: false
	// example: json
	ContentType string `wrp:"content_type,omitempty"`

	// Accept  The media type accepted in the response.
	//
	// required: false
	Accept string `wrp:"accept,omitempty"`

	// Status The response status from the originating service.
	//
	// required: false
	Status *int64 `wrp:"status,omitempty"`

	// RequestDeliveryResponse The request delivery response is the delivery result of the previous (implied request)
	// message with a matching transaction_uuid
	//
	// required: false
	RequestDeliveryResponse *int64 `wrp:"rdr,omitempty"`

	// Headers The headers associated with the payload.
	//
	// required: false
	Headers []string `wrp:"headers,omitempty"`

	// Metadata The map of name/value pairs used by consumers of WRP messages for filtering & other purposes.
	//
	// required: false
	// example: {"/boot-time":1542834188,"/last-reconnect-reason":"spanish inquisition"}
	Metadata map[string]string `wrp:"metadata,omitempty"`

	// Spans An array of arrays of timing values as a list in the format: "parent" (string), "name" (string),
	// "start time" (int), "duration" (int), "status" (int)
	//
	// required: false
	Spans [][]string `wrp:"spans,omitempty"`

	// IncludeSpans (Deprecated) If the timing values should be included in the response.
	//
	// required: false
	IncludeSpans *bool `wrp:"include_spans,omitempty"`

	// Path The path to which to apply the payload.
	//
	// required: false
	Path string `wrp:"path,omitempty"`

	// Payload The string encoded of the ContentType
	//
	// required: false
	// example: eyJpZCI6IjUiLCJ0cyI6IjIwMTktMDItMTJUMTE6MTA6MDIuNjE0MTkxNzM1WiIsImJ5dGVzLXNlbnQiOjAsIm1lc3NhZ2VzLXNlbnQiOjEsImJ5dGVzLXJlY2VpdmVkIjowLCJtZXNzYWdlcy1yZWNlaXZlZCI6MH0=
	Payload []byte `wrp:"payload,omitempty"`

	// ServiceName The originating point of the request or response
	//
	// required: false
	ServiceName string `wrp:"service_name,omitempty"`

	// URL The url to use when connecting to the nanomsg pipeline
	//
	// required: false
	URL string `wrp:"url,omitempty"`

	// PartnerIDs The list of partner ids the message is meant to target.
	//
	// required: false
	// example: ["hello","world"]
	PartnerIDs []string `wrp:"partner_ids,omitempty"`
}

Message is the union of all WRP fields, made optional (except for Type). This type is useful for transcoding streams, since deserializing from non-msgpack formats like JSON has some undesirable side effects.

IMPORTANT: Anytime a new WRP field is added to any message, or a new message with new fields, those new fields must be added to this struct for transcoding to work properly. And of course: update the tests!

For server code that sends specific messages, use one of the other WRP structs in this package.

For server code that needs to read one format and emit another, use this struct as it allows client code to transcode without knowledge of the exact type of message.

swagger:response Message

func TranscodeMessage

func TranscodeMessage(target Encoder, source Decoder) (msg *Message, err error)

TranscodeMessage converts a WRP message of any type from one format into another, e.g. from JSON into Msgpack. The intermediate, generic Message used to hold decoded values is returned in addition to any error. If a decode error occurs, this function will not perform the encoding step.

func (*Message) CodecDecodeSelf

func (x *Message) CodecDecodeSelf(d *codec1978.Decoder)

func (*Message) CodecEncodeSelf

func (x *Message) CodecEncodeSelf(e *codec1978.Encoder)

func (*Message) FindEventStringSubMatch added in v1.1.0

func (msg *Message) FindEventStringSubMatch() string

func (*Message) From

func (msg *Message) From() string

func (*Message) IsTransactionPart

func (msg *Message) IsTransactionPart() bool

func (*Message) MessageType

func (msg *Message) MessageType() MessageType

func (*Message) Response

func (msg *Message) Response(newSource string, requestDeliveryResponse int64) Routable

func (*Message) SetIncludeSpans

func (msg *Message) SetIncludeSpans(value bool) *Message

SetIncludeSpans simplifies setting the optional IncludeSpans field, which is a pointer type tagged with omitempty.

func (*Message) SetRequestDeliveryResponse

func (msg *Message) SetRequestDeliveryResponse(value int64) *Message

SetRequestDeliveryResponse simplifies setting the optional RequestDeliveryResponse field, which is a pointer type tagged with omitempty.

func (*Message) SetStatus

func (msg *Message) SetStatus(value int64) *Message

SetStatus simplifies setting the optional Status field, which is a pointer type tagged with omitempty.

func (*Message) To

func (msg *Message) To() string

func (*Message) TransactionKey

func (msg *Message) TransactionKey() string

type MessageType

type MessageType int64

MessageType indicates the kind of WRP message

const (
	SimpleRequestResponseMessageType MessageType = iota + 3
	SimpleEventMessageType
	CreateMessageType
	RetrieveMessageType
	UpdateMessageType
	DeleteMessageType
	ServiceRegistrationMessageType
	ServiceAliveMessageType
	UnknownMessageType
)

func StringToMessageType

func StringToMessageType(value string) (MessageType, error)

StringToMessageType converts a string into an enumerated MessageType constant. If the value equals the friendly name of a type, e.g. "Auth" for AuthMessageType, that type is returned. Otherwise, the value is converted to an integer and looked up, with an error being returned in the event the integer value is not valid.

func (MessageType) FriendlyName

func (mt MessageType) FriendlyName() string

FriendlyName is just the String version of this type minus the "MessageType" suffix. This is used in most textual representations, such as HTTP headers.

func (MessageType) String

func (i MessageType) String() string

func (MessageType) SupportsTransaction

func (mt MessageType) SupportsTransaction() bool

SupportsTransaction tests if messages of this type are allowed to participate in transactions. If this method returns false, the TransactionUUID field should be ignored (but passed through where applicable).

type Routable

type Routable interface {
	Typed

	// To is the destination of this Routable instance.  It corresponds to the Destination field
	// in WRP messages defined in this package.
	To() string

	// From is the originator of this Routable instance.  It corresponds to the Source field
	// in WRP messages defined in this package.
	From() string

	// IsTransactionPart tests if this message represents part of a transaction.  For this to be true,
	// both (1) the msg_type field must be of a type that participates in transactions and (2) a transaction_uuid
	// must exist in the message (see TransactionKey).
	//
	// If this method returns true, TransactionKey will always return a non-empty string.
	IsTransactionPart() bool

	// TransactionKey corresponds to the transaction_uuid field.  If present, this field is used
	// to match up responses from devices.
	//
	// Not all Routables support transactions, e.g. SimpleEvent.  For those Routable messages that do
	// not possess a transaction_uuid field, this method returns an empty string.
	TransactionKey() string

	// Response produces a new Routable instance which is a response to this one.  The new Routable's
	// destination (From) is set to the original source (To), with the supplied newSource used as the response's source.
	// The requestDeliveryResponse parameter indicates the success or failure of this response.  The underlying
	// type of the returned Routable will be the same as this type, i.e. if this instance is a Message,
	// the returned Routable will also be a Message.
	//
	// If applicable, the response's payload is set to nil.  All other fields are copied as is into the response.
	Response(newSource string, requestDeliveryResponse int64) Routable
}

Routable describes an object which can be routed. Implementations will most often also be WRP Message instances. All Routable objects may be passed to Encoders and Decoders.

Not all WRP messages are Routable. Only messages that can be sent through routing software (e.g. talaria) implement this interface.

type ServiceAlive

type ServiceAlive struct {
	// Type is exposed principally for encoding.  This field *must* be set to ServiceAliveMessageType,
	// and is automatically set by the BeforeEncode method.
	Type MessageType `wrp:"msg_type"`
}

ServiceAlive represents a WRP message of type ServiceAliveMessageType.

https://github.com/xmidt-org/wrp-c/wiki/Web-Routing-Protocol#on-device-service-alive-message-definition

func (*ServiceAlive) BeforeEncode

func (msg *ServiceAlive) BeforeEncode() error

func (*ServiceAlive) CodecDecodeSelf

func (x *ServiceAlive) CodecDecodeSelf(d *codec1978.Decoder)

func (*ServiceAlive) CodecEncodeSelf

func (x *ServiceAlive) CodecEncodeSelf(e *codec1978.Encoder)

type ServiceRegistration

type ServiceRegistration struct {
	// Type is exposed principally for encoding.  This field *must* be set to ServiceRegistrationMessageType,
	// and is automatically set by the BeforeEncode method.
	Type        MessageType `wrp:"msg_type"`
	ServiceName string      `wrp:"service_name"`
	URL         string      `wrp:"url"`
}

ServiceRegistration represents a WRP message of type ServiceRegistrationMessageType.

https://github.com/xmidt-org/wrp-c/wiki/Web-Routing-Protocol#on-device-service-registration-message-definition

func (*ServiceRegistration) BeforeEncode

func (msg *ServiceRegistration) BeforeEncode() error

func (*ServiceRegistration) CodecDecodeSelf

func (x *ServiceRegistration) CodecDecodeSelf(d *codec1978.Decoder)

func (*ServiceRegistration) CodecEncodeSelf

func (x *ServiceRegistration) CodecEncodeSelf(e *codec1978.Encoder)

type SimpleEvent

type SimpleEvent struct {
	// Type is exposed principally for encoding.  This field *must* be set to SimpleEventMessageType,
	// and is automatically set by the BeforeEncode method.
	Type        MessageType       `wrp:"msg_type"`
	Source      string            `wrp:"source"`
	Destination string            `wrp:"dest"`
	ContentType string            `wrp:"content_type,omitempty"`
	Headers     []string          `wrp:"headers,omitempty"`
	Metadata    map[string]string `wrp:"metadata,omitempty"`
	Payload     []byte            `wrp:"payload,omitempty"`
	PartnerIDs  []string          `wrp:"partner_ids,omitempty"`
}

SimpleEvent represents a WRP message of type SimpleEventMessageType.

This type implements Routable, and as such has a Response method. However, in actual practice failure responses are not sent for messages of this type. Response is merely supplied in order to satisfy the Routable interface.

https://github.com/xmidt-org/wrp-c/wiki/Web-Routing-Protocol#simple-event-definition

func (*SimpleEvent) BeforeEncode

func (msg *SimpleEvent) BeforeEncode() error

func (*SimpleEvent) CodecDecodeSelf

func (x *SimpleEvent) CodecDecodeSelf(d *codec1978.Decoder)

func (*SimpleEvent) CodecEncodeSelf

func (x *SimpleEvent) CodecEncodeSelf(e *codec1978.Encoder)

func (*SimpleEvent) From

func (msg *SimpleEvent) From() string

func (*SimpleEvent) IsTransactionPart

func (msg *SimpleEvent) IsTransactionPart() bool

IsTransactionPart for SimpleEvent types always returns false

func (*SimpleEvent) MessageType

func (msg *SimpleEvent) MessageType() MessageType

func (*SimpleEvent) Response

func (msg *SimpleEvent) Response(newSource string, requestDeliveryResponse int64) Routable

func (*SimpleEvent) To

func (msg *SimpleEvent) To() string

func (*SimpleEvent) TransactionKey

func (msg *SimpleEvent) TransactionKey() string

type SimpleRequestResponse

type SimpleRequestResponse struct {
	// Type is exposed principally for encoding.  This field *must* be set to SimpleRequestResponseMessageType,
	// and is automatically set by the BeforeEncode method.
	Type                    MessageType       `wrp:"msg_type"`
	Source                  string            `wrp:"source"`
	Destination             string            `wrp:"dest"`
	ContentType             string            `wrp:"content_type,omitempty"`
	Accept                  string            `wrp:"accept,omitempty"`
	TransactionUUID         string            `wrp:"transaction_uuid,omitempty"`
	Status                  *int64            `wrp:"status,omitempty"`
	RequestDeliveryResponse *int64            `wrp:"rdr,omitempty"`
	Headers                 []string          `wrp:"headers,omitempty"`
	Metadata                map[string]string `wrp:"metadata,omitempty"`
	Spans                   [][]string        `wrp:"spans,omitempty"`
	IncludeSpans            *bool             `wrp:"include_spans,omitempty"`
	Payload                 []byte            `wrp:"payload,omitempty"`
	PartnerIDs              []string          `wrp:"partner_ids,omitempty"`
}

SimpleRequestResponse represents a WRP message of type SimpleRequestResponseMessageType.

https://github.com/xmidt-org/wrp-c/wiki/Web-Routing-Protocol#simple-request-response-definition

func (*SimpleRequestResponse) BeforeEncode

func (msg *SimpleRequestResponse) BeforeEncode() error

func (*SimpleRequestResponse) CodecDecodeSelf

func (x *SimpleRequestResponse) CodecDecodeSelf(d *codec1978.Decoder)

func (*SimpleRequestResponse) CodecEncodeSelf

func (x *SimpleRequestResponse) CodecEncodeSelf(e *codec1978.Encoder)

func (*SimpleRequestResponse) FindEventStringSubMatch added in v1.1.0

func (msg *SimpleRequestResponse) FindEventStringSubMatch() string

func (*SimpleRequestResponse) From

func (msg *SimpleRequestResponse) From() string

func (*SimpleRequestResponse) IsTransactionPart

func (msg *SimpleRequestResponse) IsTransactionPart() bool

func (*SimpleRequestResponse) MessageType

func (msg *SimpleRequestResponse) MessageType() MessageType

func (*SimpleRequestResponse) Response

func (msg *SimpleRequestResponse) Response(newSource string, requestDeliveryResponse int64) Routable

func (*SimpleRequestResponse) SetIncludeSpans

func (msg *SimpleRequestResponse) SetIncludeSpans(value bool) *SimpleRequestResponse

SetIncludeSpans simplifies setting the optional IncludeSpans field, which is a pointer type tagged with omitempty.

func (*SimpleRequestResponse) SetRequestDeliveryResponse

func (msg *SimpleRequestResponse) SetRequestDeliveryResponse(value int64) *SimpleRequestResponse

SetRequestDeliveryResponse simplifies setting the optional RequestDeliveryResponse field, which is a pointer type tagged with omitempty.

func (*SimpleRequestResponse) SetStatus

func (msg *SimpleRequestResponse) SetStatus(value int64) *SimpleRequestResponse

SetStatus simplifies setting the optional Status field, which is a pointer type tagged with omitempty.

func (*SimpleRequestResponse) To

func (msg *SimpleRequestResponse) To() string

func (*SimpleRequestResponse) TransactionKey

func (msg *SimpleRequestResponse) TransactionKey() string

type Typed

type Typed interface {
	// MessageType is the type of message represented by this Typed.
	MessageType() MessageType
}

Typed is implemented by any WRP type which is associated with a MessageType. All message types implement this interface.

type Unknown added in v1.1.0

type Unknown struct {
	// Type is exposed principally for encoding.  This field *must* be set to UnknownMessageType,
	// and is automatically set by the BeforeEncode method.
	Type MessageType `wrp:"msg_type"`
}

Unknown represents a WRP message of type UnknownMessageType.

https://github.com/xmidt-org/wrp-c/wiki/Web-Routing-Protocol#unknown-message-definition

func (*Unknown) BeforeEncode added in v1.1.0

func (msg *Unknown) BeforeEncode() error

func (*Unknown) CodecDecodeSelf added in v1.1.0

func (x *Unknown) CodecDecodeSelf(d *codec1978.Decoder)

func (*Unknown) CodecEncodeSelf added in v1.1.0

func (x *Unknown) CodecEncodeSelf(e *codec1978.Encoder)

Directories

Path Synopsis
Package wrpendpoint integrates go-kit endpoints with the notion of services that consume and emit WRP.
Package wrpendpoint integrates go-kit endpoints with the notion of services that consume and emit WRP.
Package wrphttp integrates go-kit's transport/http package with the patterns used by WebPA/XMiDT servers.
Package wrphttp integrates go-kit's transport/http package with the patterns used by WebPA/XMiDT servers.
Package wrpmeta provides a simple API for building WRP message metadata
Package wrpmeta provides a simple API for building WRP message metadata

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL