Documentation
¶
Index ¶
- func Validate(opts *WebsocketEngineConfigurationOptions) error
- type EngineStartError
- type WebsocketEngine
- type WebsocketEngineConfigurationOptions
- func (opts *WebsocketEngineConfigurationOptions) WithAutoReconnect(value bool) *WebsocketEngineConfigurationOptions
- func (opts *WebsocketEngineConfigurationOptions) WithAutoReconnectRetryDelayBaseSeconds(value int) *WebsocketEngineConfigurationOptions
- func (opts *WebsocketEngineConfigurationOptions) WithAutoReconnectRetryDelayMaxExponent(value int) *WebsocketEngineConfigurationOptions
- func (opts *WebsocketEngineConfigurationOptions) WithOnOpenTimeoutMs(value int64) *WebsocketEngineConfigurationOptions
- func (opts *WebsocketEngineConfigurationOptions) WithReaderRoutinesCount(value int) *WebsocketEngineConfigurationOptions
- func (opts *WebsocketEngineConfigurationOptions) WithStopTimeoutMs(value int64) *WebsocketEngineConfigurationOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Validate ¶
func Validate(opts *WebsocketEngineConfigurationOptions) error
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 ¶
func NewWebsocketEngine( url *url.URL, conn adapters.WebsocketConnectionAdapterInterface, wsclient wsclient.WebsocketClientInterface, opts *WebsocketEngineConfigurationOptions, tracerProvider trace.TracerProvider) (*WebsocketEngine, error)
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 spawn 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 ¶
func (opts *WebsocketEngineConfigurationOptions) WithAutoReconnect( value bool) *WebsocketEngineConfigurationOptions
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 ¶
func (opts *WebsocketEngineConfigurationOptions) WithOnOpenTimeoutMs( value int64) *WebsocketEngineConfigurationOptions
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 ¶
func (opts *WebsocketEngineConfigurationOptions) WithStopTimeoutMs( value int64) *WebsocketEngineConfigurationOptions
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.
Source Files
¶
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. |
|
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). |