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) IsReady() bool
  • func (cs *ClientServerImpl) MakeRequest(input interface{}) error
  • func (cs *ClientServerImpl) SetAnyRequestHandler(f RequestHandler)
  • func (cs *ClientServerImpl) SetConnection(conn WebsocketConn)
  • func (cs *ClientServerImpl) SetReadDeadline(t time.Time) error
  • func (cs *ClientServerImpl) WriteMessage(send []byte) error
• type NotMarshallableWSRequest
  • func (u *NotMarshallableWSRequest) Error() string
  • func (u *NotMarshallableWSRequest) Retry() bool
• type ReceivedMessage
• type RequestHandler
• type RequestMessage
• type ServiceError
• type TypeDecoder
  • func BuildTypeDecoder(recognizedTypes []interface{}) TypeDecoder
• type TypeDecoderImpl
  • func (d *TypeDecoderImpl) GetRecognizedTypes() map[string]reflect.Type
  • func (d *TypeDecoderImpl) NewOfType(typeString string) (interface{}, bool)
• 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
	WriteMessage(input []byte) error
	Connect() error
	IsConnected() bool
	SetConnection(conn WebsocketConn)
	Disconnect(...interface{}) error
	Serve() error
	SetReadDeadline(t time.Time) error
	io.Closer
}

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

type ClientServerImpl

type ClientServerImpl struct {
	// AgentConfig is the user-specified runtime configuration
	AgentConfig *config.Config

	// CredentialProvider is used to retrieve AWS credentials
	CredentialProvider *credentials.Credentials
	// 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
	// RWTimeout is the duration used for setting read and write deadlines
	// for the websocket connection
	RWTimeout time.Duration

	ClientServer
	ServiceError
	TypeDecoder
	// contains filtered or unexported fields
}

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

func (cs *ClientServerImpl) IsReady() bool

IsReady gives a boolean response that informs the caller if the websocket connection is fully established.

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)

SetAnyRequestHandler passes a RequestHandler object into the client.

func (*ClientServerImpl) SetConnection

func (cs *ClientServerImpl) SetConnection(conn WebsocketConn)

SetConnection passes a websocket connection object into the client. This is used only in testing and should be avoided in non-test code.

func (*ClientServerImpl) SetReadDeadline

func (cs *ClientServerImpl) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline for the websocket connection A read timeout results in an io error if there are any outstanding reads that exceed the deadline

func (*ClientServerImpl) WriteMessage

func (cs *ClientServerImpl) WriteMessage(send []byte) error

WriteMessage wraps the low level websocket write method with a lock

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.

func BuildTypeDecoder

func BuildTypeDecoder(recognizedTypes []interface{}) TypeDecoder

BuildTypeDecoder takes a list of interfaces and stores them internally as a list of typeMappings in the format below. "MyMessage": TypeOf(ecstcs.MyMessage)

type TypeDecoderImpl

type TypeDecoderImpl struct {
	// contains filtered or unexported fields
}

TypeDecoderImpl is an implementation for general use between ACS and TCS clients

func (*TypeDecoderImpl) GetRecognizedTypes

func (d *TypeDecoderImpl) GetRecognizedTypes() map[string]reflect.Type

func (*TypeDecoderImpl) NewOfType

func (d *TypeDecoderImpl) NewOfType(typeString string) (interface{}, bool)

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
	SetWriteDeadline(t time.Time) error
	SetReadDeadline(t time.Time) error
}

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