wsadapters

package
v0.0.0-...-f682b98 Latest Latest
Warning

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

 Go to latest Published: Jan 5, 2024 License: Apache-2.0 Imports: 9 Imported by: 1

Documentation

Overview

The package defines an interface to adapt 3rd parties websocket libraries to websocket engine.

The package defines an interface to adapt 3rd parties websocket libraries to websocket engine.

The package defines an interface to adapt 3rd parties websocket libraries to websocket engine.

The package defines an interface to adapt 3rd parties websocket libraries to websocket engine.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type MessageType 

type MessageType int

Websocket message types which can be received.

Codes mimics RFC6455 frame opcodes. Control frames like continuation, close, ping, pong and others are excluded as the library focuses on message level and not frame level. Furthermore, the underlying websocket library used by the engine is expected to seamlessly handle message fragmentation and control frames like close, ping & pong.

https://datatracker.ietf.org/doc/html/rfc6455#section-5.6 

const (
	// Denotes a text message
	Text MessageType = iota + 1
	// Denotes a binary message
	Binary
)

type StatusCode 

type StatusCode int

Constants for RFC6455 defined close status codes

RFC: https://www.rfc-editor.org/rfc/rfc6455.html#section-7.4.1

Code names are inspired by: https://www.iana.org/assignments/websocket/websocket.xhtml 

const (
	// 1000 indicates a normal closure, meaning that the purpose for
	// which the connection was established has been fulfilled.
	NormalClosure StatusCode = iota + 1000
	// 1001 indicates that an endpoint is "going away", such as a server
	// going down or a browser having navigated away from a page.
	GoingAway
	// 1002 indicates that an endpoint is terminating the connection due
	// to a protocol error.
	ProtocolError
	// 1003 indicates that an endpoint is terminating the connection
	// because it has received a type of data it cannot accept (e.g., an
	// endpoint that understands only text data MAY send this if it
	// receives a binary message).
	UnsupportedData
	// 1005 is a reserved value and MUST NOT be set as a status code in a
	// Close control frame by an endpoint.  It is designated for use in
	// applications expecting a status code to indicate that no status
	// code was actually present.
	NoStatusReceived StatusCode = iota + 1000 + 1 // Skip 1003
	// 1006 is a reserved value and MUST NOT be set as a status code in a
	// Close control frame by an endpoint.  It is designated for use in
	// applications expecting a status code to indicate that the
	// connection was closed abnormally, e.g., without sending or
	// receiving a Close control frame.
	AbnormalClosure
	// 1007 indicates that an endpoint is terminating the connection
	// because it has received data within a message that was not
	// consistent with the type of the message (e.g., non-UTF-8 [RFC3629]
	// data within a text message).
	InvalidFramePayloadData
	// 1008 indicates that an endpoint is terminating the connection
	// because it has received a message that violates its policy.  This
	// is a generic status code that can be returned when there is no
	// other more suitable status code (e.g., 1003 or 1009) or if there
	// is a need to hide specific details about the policy.
	PolicyViolation
	// 1009 indicates that an endpoint is terminating the connection
	// because it has received a message that is too big for it to
	// process.
	MessageTooBig
	// 1010 indicates that an endpoint (client) is terminating the
	// connection because it has expected the server to negotiate one or
	// more extension, but the server didn't return them in the response
	// message of the WebSocket handshake.  The list of extensions that
	// are needed SHOULD appear in the /reason/ part of the Close frame.
	// Note that this status code is not used by the server, because it
	// can fail the WebSocket handshake instead.
	MandatoryExtension
	// 1011 indicates that a server is terminating the connection because
	// it encountered an unexpected condition that prevented it from
	// fulfilling the request.
	InternalError
	// 1015 is a reserved value and MUST NOT be set as a status code in a
	// Close control frame by an endpoint.  It is designated for use in
	// applications expecting a status code to indicate that the
	// connection was closed due to a failure to perform a TLS handshake
	// (e.g., the server certificate can't be verified).
	TLSHandshake StatusCode = iota + 1000 + 3 // Skip 1012 to 1014
)

type WebsocketCloseError 

type WebsocketCloseError struct {
	// Status code used or received when connection has been closed. If websocket connection has
	// been closed and no close message has been received, 1006 should be used.
	//
	// https://www.rfc-editor.org/rfc/rfc6455.html#section-7.1.5
	Code StatusCode
	// Optional close reason used/received when connection has been closed.
	//
	// https://www.rfc-editor.org/rfc/rfc6455.html#section-7.1.6
	Reason string
	// Embedded error if any. Can be the error returned by the underlying websocket library by Read
	// method when websocket is closed.
	Err error
}

Error used by websocket connection to signal connection has been closed

func (WebsocketCloseError) Error 

func (err WebsocketCloseError) Error() string

func (WebsocketCloseError) Unwrap 

func (err WebsocketCloseError) Unwrap() error

type WebsocketConnectionAdapterInstrumentationDecorator 

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

A decorator which can be used to automatically instrument implementations of WebsocketConnectionAdapterInterface.

func NewWebsocketConnectionAdapterInstrumentationDecorator 

func NewWebsocketConnectionAdapterInstrumentationDecorator(
	decorated WebsocketConnectionAdapterInterface,
	tracerProvider trace.TracerProvider,
) (*WebsocketConnectionAdapterInstrumentationDecorator, error)

Description

Create a new decorator which will atomatically instrument the provided implementation of WebsocketConnectionAdapterInterface.

func (*WebsocketConnectionAdapterInstrumentationDecorator) Close 

func (decorator *WebsocketConnectionAdapterInstrumentationDecorator) Close(ctx context.Context, code StatusCode, reason string) error

Decorate and instrument the Close method of a WebsocketConnectionAdapterInterface implementation.

func (*WebsocketConnectionAdapterInstrumentationDecorator) Dial 

func (decorator *WebsocketConnectionAdapterInstrumentationDecorator) Dial(ctx context.Context, target url.URL) (*http.Response, error)

Decorate and instrument the Dial method of a WebsocketConnectionAdapterInterface implementation.

func (*WebsocketConnectionAdapterInstrumentationDecorator) GetUnderlyingWebsocketConnection 

func (decorator *WebsocketConnectionAdapterInstrumentationDecorator) GetUnderlyingWebsocketConnection() any

Simple proxy for non-instrumented getter

func (*WebsocketConnectionAdapterInstrumentationDecorator) Ping 

func (decorator *WebsocketConnectionAdapterInstrumentationDecorator) Ping(ctx context.Context) error

Decorate and instrument the Close method of a WebsocketConnectionAdapterInterface implementation.

func (*WebsocketConnectionAdapterInstrumentationDecorator) Read 

func (decorator *WebsocketConnectionAdapterInstrumentationDecorator) Read(ctx context.Context) (MessageType, []byte, error)

Decorate and instrument the Read method of a WebsocketConnectionAdapterInterface implementation.

func (*WebsocketConnectionAdapterInstrumentationDecorator) Write 

func (decorator *WebsocketConnectionAdapterInstrumentationDecorator) Write(ctx context.Context, msgType MessageType, msg []byte) error

Decorate and instrument the Read method of a WebsocketConnectionAdapterInterface implementation.

type WebsocketConnectionAdapterInterface 

type WebsocketConnectionAdapterInterface interface {
	// # Description
	//
	// Dial opens a connection to the websocket server and performs a WebSocket handshake.
	//
	// # Expected behaviour
	//
	//	- Dial MUST block until websocket handshake is complete. Websocket handshake and TLS must
	//	  be handled seamlessly either by the adapter implementation or by the underlying websocket
	//    library.
	//
	//	- Dial MUST NOT return the underlying websocket connection. The undelrying websocket
	//    connection must be kept internally by the adapter implementation in order to be used
	//    later by other adapter methods.
	//
	//	- Dial MUST return an error in case a connection has already been established and Close
	//	  method has not been called yet.
	//
	// # Inputs
	//
	//	- ctx: Context used for tracing/timeout purpose
	//	- target: Target server URL
	//
	// # Returns
	//
	// The server response to websocket handshake or an error if any.
	Dial(ctx context.Context, target url.URL) (*http.Response, error)
	// # Description
	//
	// Send a close message with the provided status code and an optional close reason and drop
	// the websocket connection.
	//
	// # Expected behaviour
	//
	//	- Close MUST be blocking until close message has been sent to the server.
	//	- Close MUST drop pending write/read messages.
	//	- Close MUST return a (wrapped) net.ErrClosed error in case connection is already closed.
	//
	// # Inputs
	//
	//	- ctx: Context used for tracing purpose
	//	- code: Status code to use in close message
	//	- reason: Optional reason joined in clsoe message. Can be empty.
	//
	// # Returns
	//
	//	- nil in case of success
	//	- error: server unreachable, connection already closed, ...
	Close(ctx context.Context, code StatusCode, reason string) error
	// # Description
	//
	// Send a Ping message to the websocket server and blocks until a Pong response is received, a
	// timmeout occurs, or connection is closed.
	//
	// # Expected behaviour
	//
	//	- Ping MUST be blocking either until an error or a context timeout or cancellation occurs
	//    or until Ping message is sent and a Pong response is somehow detected either by the
	//    adapter implementation or by the underlying websocket connection library.
	//
	//	- It CANNOT be assumed that there will be at least one concurrent goroutine which continuously
	//    call Read method. In case the underlying websocket library requires to have a concurrent
	//    goroutine continuously reading in order for Ping to complete, it is up to either the
	//    adapter or to the final user to ensure there is a concurrent goroutine reading.
	//
	//	- Ping MUST return an error if connection is closed, if server is unreachable or if context
	//    has expired (timeout or cancel). In this later case, Ping MUST return the context error.
	//
	// # Inputs
	//
	//	- ctx: context used for tracing/timeout purpose.
	//
	// # Returns
	//
	// - nil in case of success: if a Ping message is sent to the server and if a Pong is received.
	// - error: connection is closed, context timeout/cancellation, ...
	Ping(ctx context.Context) error
	// # Description
	//
	// Read a single message from the websocket server. Read blocks until a message is received
	// from the server or until connection closes.
	//
	// # Expected behaviour
	//
	//	- Read MUST handle seamlessly message defragmentation, decompression and TLS decryption.
	//    It is up to the adapter implementation or to the underlying websocket library to handle
	//    these features.
	//
	//	- Read MUST NOT return close, ping, pong and continuation frames as control frames MUST be
	//    handled seamlessly either by the adapter implementation or by the underlying websocket
	//    connection library.
	//
	//	- Read MUST return a WebsocketCloseError either if a close message is read or if connection
	//    is closed without a close message. In the later case, the 1006 status code MUST be used.
	//    Read MUST drop the existing connection so a new one can be established.
	//
	//	- Read MUST block until a message is read from the server or until connection is closed.
	//
	// # Inputs
	//
	//	- ctx: Context used for tracing purpose
	//
	// # Returns
	//
	//	- MessageType: received message type (Binary | Text)
	//	- []bytes: Message content
	//	- error: in case of connection closure or failure.
	Read(ctx context.Context) (MessageType, []byte, error)
	// # Description
	//
	// Write a single message to the websocket server. Write blocks until message is sent to the
	// server or until an error occurs: context timeout, cancellation, connection closed, ....
	//
	// # Expected behaviour
	//
	//	- Write MUST handle seamlessly message fragmentation, compression and TLS encryption. It is
	//    up to the adapter implementation or to the underlying websocket library to handle these.
	//
	//	- Write MUST NOT handle sending control frames like Close, Ping, etc...
	//
	//	- Write MUST be blocking until a message is sent to the server or until an error occurs.
	//
	// # Inputs
	//
	//	- ctx: Context used for tracing/timeout purpose
	//	- MessageType: received message type (Binary | Text)
	//	- []bytes: Message content
	//
	// # Returns
	//
	//	- error: in case of connection closure, context timeout/cancellation or failure.
	Write(ctx context.Context, msgType MessageType, msg []byte) error
	// # Description
	//
	// Return the underlying websocket connection if any. Returned value has to be type asserted.
	//
	// # Returns
	//
	// The underlying websocket connection if any. Returned value has to be type asserted.
	GetUnderlyingWebsocketConnection() any
}

Interface which describes the adapter methods and behaviour that the websocket engine expects from the underlying websocket connection library.

Adapters are assumed to be thread-safe. Thread safety must be ensured either by the adapter implementation or by the underlying websocket connection library.

type WebsocketConnectionAdapterInterfaceMock 

type WebsocketConnectionAdapterInterfaceMock struct {
	mock.Mock
}

Mock for WebsocketConnectionAdapterInterface

func NewWebsocketConnectionAdapterInterfaceMock 

func NewWebsocketConnectionAdapterInterfaceMock() *WebsocketConnectionAdapterInterfaceMock

Factory

func (*WebsocketConnectionAdapterInterfaceMock) Close 

func (mock *WebsocketConnectionAdapterInterfaceMock) Close(ctx context.Context, code StatusCode, reason string) error

Description

Send a close message with the provided status code and an optional close reason and close the websocket connection.

Expected behaviour

  • Close MUST be blocking until close message has been sent to the server and until websocket connection closure.

  • There are no guidelines about dropping pending write/read messages when Close is called. Refer to the adapter or the underlying websocket library documentation for guidance.

Inputs

  • ctx: Context used for tracing purpose
  • code: Status code to use in close message
  • reason: Optional reason joined in clsoe message. Can be empty.

Returns

  • nil in case of success
  • error: server unreachable, connection already closed, ...

func (*WebsocketConnectionAdapterInterfaceMock) Dial 

func (mock *WebsocketConnectionAdapterInterfaceMock) Dial(ctx context.Context, target url.URL) (*http.Response, error)

Description

Dial open a connection to the websocket server, performs a WebSocket handshake on url and keep internally the underlying websocket connection for further use.

Expected behaviour

  • Dial MUST block until websocket handshake completes. Websocket handshake and TLS must be handled seamlessly either by the adapter implementation or by the underlying websocket library.

  • Dial MUST NOT return the undelrying websocket connection. The undelrying websocket connection must be kept internally by the adapter implementation in order to be used later by Read, Write, ...

  • Dial SHOULD close any previous opened connection if called again and MUST drop any previous connection. Connection closure must be seamless.

Inputs

  • ctx: Context used for tracing/timeout purpose
  • target: Target server URL

Returns

  • Server response to websocket handshake
  • error if any

func (*WebsocketConnectionAdapterInterfaceMock) GetUnderlyingWebsocketConnection 

func (mock *WebsocketConnectionAdapterInterfaceMock) GetUnderlyingWebsocketConnection() any

Description

Return the underlying websocket connection if any. Returned value has to be type asserted.

Returns

The underlying websocket connection if any. Returned value has to be type asserted.

func (*WebsocketConnectionAdapterInterfaceMock) Ping 

func (mock *WebsocketConnectionAdapterInterfaceMock) Ping(ctx context.Context) error

Description

Send a Ping message to the websocket server and blocks until a Pong response is received.

Expected behaviour

  • Ping MUST be blocking either until an error or a context timeout or cancellation occurs or until Ping message is sent and a Pong response is somehow detected either by the adapter implementation or by the underlying websocket connection library.

  • It can be assumed that there will be at least one concurrent goroutine which continuously call Read method.

  • Ping MUST return an error if connection is closed, if server is unreachable or if context has expired (timeout or cancel). In this later case, Ping MUST return the context error.

Inputs

  • ctx: context used for tracing/timeout purpose.

Returns

- nil in case of success: if a Ping message is sent to the server and if a Pong is received. - error: connection is closed, context timeout/cancellation, ...

func (*WebsocketConnectionAdapterInterfaceMock) Read 

func (mock *WebsocketConnectionAdapterInterfaceMock) Read(ctx context.Context) (MessageType, []byte, error)

Description

Read a single message from the websocket server. Read blocks until a message is received from the server, until connection closes or until a timeout or a cancel occurs.

Expected behaviour

  • Read MUST handle seamlessly message defragmentation, decompression and TLS decryption. It is up to the adapter implementation or to the underlying websocket library to handle these features.

  • Read MUST NOT return close, ping, pong and continuation frames as control frames MUST be handled seamlessly either by the adapter implementation or by the underlying websocket connection library.

  • Read MUST return a WebsocketCloseError either if a close message is read or if connection is closed without a close message. In the later case, the 1006 status code MUST be used.

  • Read MUST block until a message is read from the server or until an error occurs.

Inputs

  • ctx: Context used for tracing/timeout purpose

Returns

  • MessageType: received message type (Binary | Text)
  • []bytes: Message content
  • error: in case of connection closure, context timeout/cancellation or failure.

func (*WebsocketConnectionAdapterInterfaceMock) Write 

func (mock *WebsocketConnectionAdapterInterfaceMock) Write(ctx context.Context, msgType MessageType, msg []byte) error

Description

Write a single message to the websocket server. Write blocks until message is sent to the server or until an error occurs: context timeout, cancellation, connection closed, ....

Expected behaviour

  • Write MUST handle seamlessly message fragmentation, compression and TLS encryption. It is up to the adapter implementation or to the underlying websocket library to handle these.

  • Write MUST NOT handle sending control frames like Close, Ping, etc...

  • Write MUST be blocking until a message is sent to the server or until an error occurs.

Inputs

  • ctx: Context used for tracing/timeout purpose
  • MessageType: received message type (Binary | Text)
  • []bytes: Message content

Returns

  • error: in case of connection closure, context timeout/cancellation or failure.

Source Files

View all Source files

Directories

Path Synopsis
Package which contains a WebsocketConnectionAdapterInterface implementation for gorilla/websocket library (https://github.com/gorilla/websocket).
 Package which contains a WebsocketConnectionAdapterInterface implementation for gorilla/websocket library (https://github.com/gorilla/websocket).
Package which contains a WebsocketConnectionAdapterInterface implementation for nhooyr/websocket library (https://github.com/nhooyr/websocket).
 Package which contains a WebsocketConnectionAdapterInterface implementation for nhooyr/websocket library (https://github.com/nhooyr/websocket).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.