README
¶
recws
Reconnecting WebSocket is a websocket client based on gorilla/websocket that will automatically reconnect if the connection is dropped - thread safe!
Features
- Automatic reconnection with configurable backoff
- Thread-safe operations
- Structured logging with configurable levels
- Robust keepalive mechanism
- Proper connection establishment with channel-based synchronization
- TLS support
- Proxy support
- Compression support (RFC 7692)
- Graceful shutdown support
Installation
go get github.com/inference-sh/recws
Quick Start
import "github.com/inference-sh/recws"
// Create a new reconnecting websocket
ws := &recws.RecConn{
KeepAliveTimeout: 30 * time.Second,
}
// Connect (blocks until connection is established or timeout reached)
ws.Dial("ws://example.com/ws", nil)
// Send/receive messages
ws.WriteMessage(websocket.TextMessage, []byte("hello"))
Examples
See the examples directory for complete working examples.
Important Note
This library is designed to be used as a WebSocket client (the connecting end) that initiates connections to a WebSocket server. It is not meant to be used for implementing WebSocket server endpoints. If you're looking to implement a WebSocket server, please use the gorilla/websocket package directly instead.
Examples
See the examples directory for complete working examples.
Important Note
This library is designed to be used as a WebSocket client (the connecting end) that initiates connections to a WebSocket server. It is not meant to be used for implementing WebSocket server endpoints. If you're looking to implement a WebSocket server, please use the gorilla/websocket package directly instead.
Logo Credits
- Logo by Anastasia Marx
- Gopher by Gophers
License
recws is open-source software licensed under the MIT license.
Documentation
¶
Overview ¶
Package recws provides websocket client based on gorilla/websocket that will automatically reconnect if the connection is dropped.
Index ¶
- Variables
- type Logger
- type RecConn
- func (rc *RecConn) Close()
- func (rc *RecConn) CloseAndReconnect()
- func (rc *RecConn) Dial(urlStr string, reqHeader http.Header)
- func (rc *RecConn) GetDialError() error
- func (rc *RecConn) GetHTTPResponse() *http.Response
- func (rc *RecConn) GetURL() string
- func (rc *RecConn) IsConnected() bool
- func (rc *RecConn) ReadJSON(v interface{}) error
- func (rc *RecConn) ReadMessage() (messageType int, message []byte, err error)
- func (rc *RecConn) SetTLSClientConfig(tlsClientConfig *tls.Config)
- func (rc *RecConn) Shutdown(writeWait time.Duration)
- func (rc *RecConn) WriteJSON(v interface{}) error
- func (rc *RecConn) WriteMessage(messageType int, data []byte) error
Constants ¶
This section is empty.
Variables ¶
var ErrNotConnected = errors.New("websocket: not connected")
ErrNotConnected is returned when the application read/writes a message and the connection is closed
Functions ¶
This section is empty.
Types ¶
type Logger ¶ added in v1.6.0
type Logger interface {
Debug(msg string, args ...any)
Info(msg string, args ...any)
Warn(msg string, args ...any)
Error(msg string, args ...any)
}
Logger is the interface for logging operations
func DefaultLogger ¶ added in v1.6.0
func DefaultLogger() Logger
DefaultLogger returns a slog-based default logger
type RecConn ¶
type RecConn struct {
// RecIntvlMin specifies the initial reconnecting interval,
// default to 2 seconds
RecIntvlMin time.Duration
// RecIntvlMax specifies the maximum reconnecting interval,
// default to 30 seconds
RecIntvlMax time.Duration
// RecIntvlFactor specifies the rate of increase of the reconnection
// interval, default to 1.5
RecIntvlFactor float64
// HandshakeTimeout specifies the duration for the handshake to complete,
// default to 2 seconds
HandshakeTimeout time.Duration
// Proxy specifies the proxy function for the dialer
// defaults to ProxyFromEnvironment
Proxy func(*http.Request) (*url.URL, error)
// Client TLS config to use on reconnect
TLSClientConfig *tls.Config
// SubscribeHandler fires after the connection successfully establish.
SubscribeHandler func() error
// KeepAliveTimeout is an interval for sending ping/pong messages
// disabled if 0
KeepAliveTimeout time.Duration
// Compression enables per-message compression as defined in https://datatracker.ietf.org/doc/html/rfc7692
Compression bool
// Logger is the logger instance to use. If nil, DefaultLogger() will be used.
Logger Logger
*websocket.Conn
// contains filtered or unexported fields
}
The RecConn type represents a Reconnecting WebSocket connection.
func (*RecConn) Close ¶
func (rc *RecConn) Close()
Close closes the underlying network connection without sending or waiting for a close frame.
func (*RecConn) CloseAndReconnect ¶
func (rc *RecConn) CloseAndReconnect()
CloseAndReconnect will try to reconnect. Safe to call concurrently — only the first caller triggers a reconnect, subsequent calls are no-ops until the reconnect completes.
func (*RecConn) GetDialError ¶
GetDialError returns the last dialer error. nil on successful connection.
func (*RecConn) GetHTTPResponse ¶
GetHTTPResponse returns the http response from the handshake. Useful when WebSocket handshake fails, so that callers can handle redirects, authentication, etc.
func (*RecConn) IsConnected ¶
IsConnected returns the WebSocket connection state
func (*RecConn) ReadMessage ¶
ReadMessage is a helper method for getting a reader using NextReader and reading from that reader to a buffer.
If the connection is closed ErrNotConnected is returned
func (*RecConn) SetTLSClientConfig ¶
func (*RecConn) Shutdown ¶
Shutdown gracefully closes the connection by sending the websocket.CloseMessage. The writeWait param defines the duration before the deadline of the write operation is hit.
Source Files
Directories