wsclient

Documentation

Overview

Package wsclient wraps the generated aws-sdk-go client to provide marshalling and unmarshalling of data over a websocket connection in the format expected by backend. It allows for bidirectional communication and acts as both a client-and-server in terms of requests, but only as a client in terms of connecting.

Package wsclient wraps the generated aws-sdk-go client to provide marshalling and unmarshalling of data over a websocket connection in the format expected by backend. It allows for bidirectional communication and acts as both a client-and-server in terms of requests, but only as a client in terms of connecting.

Index

• Constants
• func DecodeConnectionError(data []byte, dec TypeDecoder) (interface{}, string, error)
• func DecodeData(data []byte, dec TypeDecoder) (interface{}, string, error)
• type ClientServer
• type ClientServerImpl
  • func (cs *ClientServerImpl) AddRequestHandler(f RequestHandler)
  • func (cs *ClientServerImpl) Connect() error
  • func (cs *ClientServerImpl) ConsumeMessages() error
  • func (cs *ClientServerImpl) CreateRequestMessage(input interface{}) ([]byte, error)
  • func (cs *ClientServerImpl) Disconnect(...interface{}) error
  • func (cs *ClientServerImpl) MakeRequest(input interface{}) error
  • func (cs *ClientServerImpl) SetAnyRequestHandler(f RequestHandler)
• type NotMarshallableWSRequest
  • func (u *NotMarshallableWSRequest) Error() string
  • func (u *NotMarshallableWSRequest) Retry() bool
• type ReceivedMessage
• type RequestHandler
• type RequestMessage
• type ServiceError
• type TypeDecoder
• type UndecodableMessage
  • func (u *UndecodableMessage) Error() string
• type UnrecognizedWSRequestType
  • func (u *UnrecognizedWSRequestType) Error() string
  • func (u *UnrecognizedWSRequestType) Retry() bool
• type WSError
  • func (err *WSError) Error() string
  • func (err *WSError) Retry() bool
• type WSUnretriableErrors
• type WebsocketConn

Constants

const (
	// ServiceName defines the service name for the agent. This is used to sign messages
	// that are sent to the backend.
	ServiceName = "ecs"
)

Functions

func DecodeConnectionError

func DecodeConnectionError(data []byte, dec TypeDecoder) (interface{}, string, error)

DecodeConnectionError decodes some of the connection errors returned by the backend. Some differ from the usual ones in that they do not have a 'type' and 'message' field, but rather are of the form {"ErrorType":"ErrorMessage"}

func DecodeData

func DecodeData(data []byte, dec TypeDecoder) (interface{}, string, error)

DecodeData decodes a raw message into its type. E.g. An ACS message of the form {"type":"FooMessage","message":{"foo":1}} will be decoded into the corresponding *ecsacs.FooMessage type. The type string, "FooMessage", will also be returned as a convenience.

Types

type ClientServer

type ClientServer interface {
	AddRequestHandler(RequestHandler)
	// SetAnyRequestHandler takes a function with the signature 'func(i
	// interface{})' and calls it with every message the server passes down.
	// Only a single 'AnyRequestHandler' will be active at a given time for a
	// ClientServer
	SetAnyRequestHandler(RequestHandler)
	MakeRequest(input interface{}) error
	Connect() error
	Disconnect(...interface{}) error
	Serve() error
	io.Closer
}

ClientServer is a combined client and server for the backend websocket connection

type ClientServerImpl

type ClientServerImpl struct {
	AcceptInvalidCert  bool
	Conn               WebsocketConn
	CredentialProvider *credentials.Credentials
	Region             string
	// RequestHandlers is a map from message types to handler functions of the
	// form:
	//     "FooMessage": func(message *ecsacs.FooMessage)
	RequestHandlers map[string]RequestHandler
	// AnyRequestHandler is a request handler that, if set, is called on every
	// message with said message. It will be called before a RequestHandler is
	// called. It must take a single interface{} argument.
	AnyRequestHandler RequestHandler
	// URL is the full url to the backend, including path, querystring, and so on.
	URL string
	ClientServer
	ServiceError
	TypeDecoder
}

ClientServerImpl wraps commonly used methods defined in ClientServer interface.

func (*ClientServerImpl) AddRequestHandler

func (cs *ClientServerImpl) AddRequestHandler(f RequestHandler)

AddRequestHandler adds a request handler to this client. A request handler *must* be a function taking a single argument, and that argument *must* be a pointer to a recognized 'ecsacs' struct. E.g. if you desired to handle messages from acs of type 'FooMessage', you would pass the following handler in:

func(message *ecsacs.FooMessage)

This function will panic if the passed in function does not have one pointer argument or the argument is not a recognized type. Additionally, the request handler will block processing of further messages on this connection so it's important that it return quickly.

func (*ClientServerImpl) Connect

func (cs *ClientServerImpl) Connect() error

Connect opens a connection to the backend and upgrades it to a websocket. Calls to 'MakeRequest' can be made after calling this, but responss will not be receivable until 'Serve' is also called.

func (*ClientServerImpl) ConsumeMessages

func (cs *ClientServerImpl) ConsumeMessages() error

ConsumeMessages reads messages from the websocket connection and handles read messages from an active connection.

func (*ClientServerImpl) CreateRequestMessage

func (cs *ClientServerImpl) CreateRequestMessage(input interface{}) ([]byte, error)

CreateRequestMessage creates the request json message using the given input. Note, the input *MUST* be a pointer to a valid backend type that this client recognises.

func (*ClientServerImpl) Disconnect

func (cs *ClientServerImpl) Disconnect(...interface{}) error

Disconnect disconnects the connection

func (*ClientServerImpl) MakeRequest

func (cs *ClientServerImpl) MakeRequest(input interface{}) error

MakeRequest makes a request using the given input. Note, the input *MUST* be a pointer to a valid backend type that this client recognises

func (*ClientServerImpl) SetAnyRequestHandler

func (cs *ClientServerImpl) SetAnyRequestHandler(f RequestHandler)

type NotMarshallableWSRequest

type NotMarshallableWSRequest struct {
	Type string

	Err error
}

NotMarshallableWSRequest represents that the given request input could not be marshalled

func (*NotMarshallableWSRequest) Error

func (u *NotMarshallableWSRequest) Error() string

Error implements error

func (*NotMarshallableWSRequest) Retry

func (u *NotMarshallableWSRequest) Retry() bool

Retry implementes Retriable

type ReceivedMessage

type ReceivedMessage struct {
	Type    string          `json:"type"`
	Message json.RawMessage `json:"message"`
}

ReceivedMessage is the intermediate message used to unmarshal a message from backend

type RequestHandler

type RequestHandler interface{}

RequestHandler would be func(*ecsacs.T for T in ecsacs.*) to be more proper, but it needs to be interface{} to properly capture that

type RequestMessage

type RequestMessage struct {
	Type    string          `json:"type"`
	Message json.RawMessage `json:"message"`
}

RequestMessage is the intermediate message marshalled to send to backend.

type ServiceError

type ServiceError interface {
	NewError(err interface{}) *WSError
}

ServiceError defines methods to return new backend specific error objects.

type TypeDecoder

type TypeDecoder interface {
	// NewOfType returns an object of a recognized type for a given type name.
	// It additionally returns a boolean value which is set to false for an
	// unrecognized type.
	NewOfType(string) (interface{}, bool)

	// GetRecognizedTypes returns a map of type-strings (as passed in acs/tcs messages as
	// the 'type' field) to a pointer to the corresponding struct type this type should
	// be marshalled/unmarshalled to/from.
	GetRecognizedTypes() map[string]reflect.Type
}

TypeDecoder interface defines methods to decode ecs types.

type UndecodableMessage

type UndecodableMessage struct {
	Msg string
}

UndecodableMessage indicates that a message from the backend could not be decoded

func (*UndecodableMessage) Error

func (u *UndecodableMessage) Error() string

type UnrecognizedWSRequestType

type UnrecognizedWSRequestType struct {
	Type string
}

UnrecognizedWSRequestType specifies that a given type is not recognized. This error is not retriable.

func (*UnrecognizedWSRequestType) Error

func (u *UnrecognizedWSRequestType) Error() string

Error implements error

func (*UnrecognizedWSRequestType) Retry

func (u *UnrecognizedWSRequestType) Retry() bool

Retry implements Retriable

type WSError

type WSError struct {
	ErrObj interface{}
	Type   string
	WSUnretriableErrors
}

WSError wraps all the typed errors that the backend may return This will not be needed once the aws-sdk-go generation handles error types more cleanly

func (*WSError) Error

func (err *WSError) Error() string

Error returns an error string

func (*WSError) Retry

func (err *WSError) Retry() bool

Retry returns true if this error should be considered retriable

type WSUnretriableErrors

type WSUnretriableErrors interface {
	Get() []interface{}
}

WSUnretriableErrors defines methods to retrieve the list of unretriable errors.

type WebsocketConn

type WebsocketConn interface {
	WriteMessage(messageType int, data []byte) error
	ReadMessage() (messageType int, data []byte, err error)
	Close() error
}

WebsocketConn specifies the subset of gorilla/websocket's connection's methods that this client uses.