wscengine

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: 16 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewWebsocketClientInstrumentationDecorator

func NewWebsocketClientInstrumentationDecorator(decorated wsclient.WebsocketClientInterface, tracerProvider trace.TracerProvider) (*websocketClientInstrumentationDecorator, error)

Description

Build and return a new decorator which instrument a provided WebsocketClientInterface implementation.

Inputs

  • decorated: The WebsocketClientInterface implementation to decorate. Must not be nil.
  • tracerProvider: Tracer provider used to get a tracer. If nil, global traver provider will be used.

Returns

A new insturmentation decorator for the provided WebsocketClientInterface implementation or an error if decorated is nil.

func Validate

Description

Helper function which validates WebsocketEngineConfigurationOptions. Options are valid if:

  • opts is not nil
  • opts.ReaderRoutinesCount is greater or equal to 1
  • opts.AutoReconnectRetryDelayBaseSeconds is greater or equal to 1
  • opts.AutoReconnectRetryDelayMaxExponent is greater or equal to 1
  • opts.OnOpenTimeoutMs is greater or equal to 0
  • opts.StopTimeoutMs is greater or equal to 0

Returns

InvalidValidationError for bad values passed in and nil or ValidationErrors as error otherwise. You will need to assert the error if it's not nil eg. err.(validator.ValidationErrors) to access the array of errors.

Types

type EngineStartError

type EngineStartError struct {
	// Embedded error
	Err error
}

Specific error type for errors which occurs when engine starts.

func (EngineStartError) Error

func (err EngineStartError) Error() string

func (EngineStartError) Unwrap

func (err EngineStartError) Unwrap() error

type WebsocketEngine

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

Engine which manages a websocket connection, read incoming messages, calls appropriate client callbacks and automatically reopen a connection with the server if connection is interrupted.

func NewWebsocketEngine

Description

Factory - Return a new, not started websocket engine.

Inputs

  • url: Target websocket server URL.
  • conn: Websocket connection adapter engine will use to connect to the target server.
  • wsclient: User provided callbacks which will be called by the websocket engine.
  • opts: Engine configuration options. If nil, default options are used.
  • traceProvider: OpenTelemetry tracer provider to use. If nil, global TracerProvider is used.

Return

Factory returns a new, non-started websocket engine in case of success. If provided options are invalid, factory will return nil and an error.

func (*WebsocketEngine) GetReadMutex

func (wsengine *WebsocketEngine) GetReadMutex() *sync.Mutex

Description

Get read Mutex used to pause the engine and prevent it from processing messages and events. User can can lock it to temporarely take full control over the underlying websocket connection.

An example of such case is when the user wants to handle a synchronous request-response pattern: User can lock the mutex (from inside a callback or outside of it), send a message to the server and then process incoming messages while waiting for a specific reply or error from the server.

Once user has finished done, user has to release the mutex to 'resume' the engine.

Warning

Be sure to unlock the mutex when using it! Engine goroutines will be blocked and engine will not process any message and will not stop until read mutex is unlocked.

Return

The mutex used to pause the websocket engine.

func (*WebsocketEngine) IsStarted

func (wsengine *WebsocketEngine) IsStarted() bool

Description

Returns the websocket engine started state. If the engine is starting or stopping, the method will block until engine has finished starting or stopping amd then will return the engine state.

func (*WebsocketEngine) Start

func (wsengine *WebsocketEngine) Start(ctx context.Context) error

Description

Start the websocket engine that will connect to the server, call OnOpen callback and then create goroutines which will continuously fetch messages and call appropriate user defined callbacks.

The Start method blocks until:

  • Engine startup phase completes.
  • The engine returns an error from its start phase.
  • A OnOpenTimeout occurs (if enabled).

Inputs

  • ctx: context used as parent of all engine contextes. Used for tracing/coordination purpose.

Return

The method will return nil on success.

The method returns an error if:

  • Provided context is canceled.
  • Engine has already started.
  • OnOpen returned an error: In this case, returned error embed error returned by OnOpen.
  • The engine fails to open a connection to the websocket server.
  • A timeout occured during startup phase.

What happen to the opened websocket connection if an error occurs during startup phase?

If an error occurs during the startup phase (timeout, context canceld, ...), the engine will try to close the websocket connection by sending a "Going away" 1001 close message.

What to do when an error occurs?

Some errors are not definitive failures:

  • The engine fails to open a connection to the websocket server.
  • OnOpen callback returned an error.
  • A timeout occured during startup phase

When an error occurs when engine is starting for the first time, the engine will not retry: it is up to the user code to try again calling Start().

func (*WebsocketEngine) Stop

func (wsengine *WebsocketEngine) Stop(ctx context.Context) error

Description

Definitely stop the websocket engine. The method will block until the engine has stopped. The engine will call OnClose callback, close the websocket connection and exit.

Return

The method returns nil on success or an error if:

  • the websocket engine is not started.
  • a timeout has occured while waiting for the engine to stop (if enabled).

Warning - Unlock read mutex before calling Stop()

If you have locked the read Mutex, the engine will not stop and signal it has stopped until read Mutex has been released. As Stop blocks until stop signal is emitted by the engine, the calling goroutine will be blocked on Stop until the read mutex is unlocked by another goroutine.

There is simple way to prevent this issue from occuring: Unlock read mutex before calling Stop!

type WebsocketEngineConfigurationOptions

type WebsocketEngineConfigurationOptions struct {
	// Number of goroutine the engine will create to concurrently read messages, call user
	// callbacks and manage the shared websocket connection.
	//
	// Defaults to 4. Must be at least 1.
	ReaderRoutinesCount int `validate:"gte=1"`
	// If true, the engine will continuously try to reopen websocket connection when it
	// is interrupted by the server.
	//
	// Defaults to true.
	AutoReconnect bool
	// Base used to compute exponential reconnect retry delay (seconds).
	//
	// Defaults to 5s. Must be at least 1.
	AutoReconnectRetryDelayBaseSeconds int `validate:"gte=1"`
	// Maximum exponent used to compute exponential reconnect retry delay (inclusive).
	//
	// Defaults to 1. Must be at least 1.
	AutoReconnectRetryDelayMaxExponent int `validate:"gte=1"`
	// Delay to open websocket connection, call and complete OnOpen callback (milliseconds).
	//
	// Default to 300000 (5 minutes) - 0 disables the timeout.
	OnOpenTimeoutMs int64 `validate:"gte=0"`
	// Delay (milliseconds )to complete Stop() method. This includes triggering engine shutdown and
	// wait for the engine to stop: call & complete OnClose callback and close the connection.
	//
	// Default to 300000 (5 minutes) - 0 disables the timeout.
	StopTimeoutMs int64 `validate:"gte=0"`
}

Defines configuration options for websocket connection.

Use the factory function to get a new instance of the struct with nice defaults and then modify settings using With*** methods.

func NewWebsocketEngineConfigurationOptions

func NewWebsocketEngineConfigurationOptions() *WebsocketEngineConfigurationOptions

Description

Factory which creates a new WebsocketEngineConfigurationOptions object with nice defaults. Settings can then be modified by the user by using With*** methods.

Default settings

  • ReaderRoutinesCount = 4 , websocket engine will span 4 goroutines to concurrently manage the shared websocket connection and process messages.
  • AutoReconnect = true , websocket engine will continuously retry failed connection.
  • AutoReconnectRetryDelayBaseSeconds = 5 , Exponential retry delay will use 5 seconds as base.
  • AutoReconnectRetryDelayMaxExponent = 1 , Exponential retry delay will use 0 and then 1 as exponent to compute the delay (5s^0 = 1s as delay on first retry, 5s^1 = 5s as next delays).
  • OnOpenTimeoutMs = 300000 (5 minutes).
  • StopTimeoutMs = 300000 (5 minutes).

func (*WebsocketEngineConfigurationOptions) WithAutoReconnect

Description

Set opts.AutoReconnect and return the modified object. The method does not validate inputs.

AutoReconnect

This option defines whether the engine will automatically try to open a new connection to the websocket server in case the connection has been interrupted.

Defaults to true (= enabled).

Return

The modified options.

func (*WebsocketEngineConfigurationOptions) WithAutoReconnectRetryDelayBaseSeconds

func (opts *WebsocketEngineConfigurationOptions) WithAutoReconnectRetryDelayBaseSeconds(
	value int) *WebsocketEngineConfigurationOptions

Description

Set opts.AutoReconnectRetryDelayBaseSeconds and return the modified object. The method does not validate inputs.

AutoReconnectRetryDelayBaseSeconds

This option defines the number of seconds used as base in the exponential retry delay.

Defaults to 5 seconds. Must be greater or equal to 1s.

Return

The modified options.

func (*WebsocketEngineConfigurationOptions) WithAutoReconnectRetryDelayMaxExponent

func (opts *WebsocketEngineConfigurationOptions) WithAutoReconnectRetryDelayMaxExponent(
	value int) *WebsocketEngineConfigurationOptions

Description

Set opts.AutoReconnectRetryDelayMaxExponent and return the modified object. The method does not validate inputs.

AutoReconnectRetryDelayMaxExponent

This option defines the number used as exponent in the exponential retry delay. If AutoReconnectRetryDelayBaseSeconds is 5s and AutoReconnectRetryDelayMaxExponent is 2, retry delay will be 5s^0 = 1s for first retry, 5s^1 = 5s for second retry and 5s^2 all other retries.

Default to 1. Must be greater or equal to 1.

Return

The modified options.

func (*WebsocketEngineConfigurationOptions) WithOnOpenTimeoutMs

Description

Set opts.OnOpenTimeoutMs and return the modified object. The method does not validate inputs.

OnOpenTimeoutMs

This option defines the maximum delay (milliseconds) to open websocket connection, call and complete OnOpen callback. A value of 0 disables the timeout.

Must be greater or equal to 0. Defaults to 5 minutes (= 300000).

Return

The modified options.

func (*WebsocketEngineConfigurationOptions) WithReaderRoutinesCount

func (opts *WebsocketEngineConfigurationOptions) WithReaderRoutinesCount(
	value int) *WebsocketEngineConfigurationOptions

Description

Set opts.ReaderRoutinesCount and return the modified object. Method does not validate inputs.

ReaderRoutinesCount

This option defines the number of goroutines websocket engine will span to concurrently manage the shared websocket connection and process messages.

Defaults to 4. Must be greater or equal to 1.

Return

The modified options.

func (*WebsocketEngineConfigurationOptions) WithStopTimeoutMs

Description

Set opts.StopTimeoutMs and return the modified object. The method does not validate inputs.

StopTimeoutMs

This option defines the maximum delay (milliseconds) to stop websocket engine. A value of 0 disables the timeout.

Must be greater or equal to 0. Defaults to 5 minutes (= 300000).

Return

The modified options.

Directories

Path Synopsis
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.
gorilla
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).
nhooyr
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