Documentation
¶
Overview ¶
Package wsutil provides abstractions around the Websocket, including rate limits.
Index ¶
- Variables
- func ErrBrokenConnection(err error) error
- func HandleEvent(h EventHandler, ev Event) error
- func IsBrokenConnection(err error) bool
- func NewDialLimiter() *rate.Limiter
- func NewGlobalIdentityLimiter() *rate.Limiter
- func NewIdentityLimiter() *rate.Limiter
- func NewSendLimiter() *rate.Limiter
- func WaitForEvent(ctx context.Context, h EventHandler, ch <-chan Event, fn func(*OP) bool) error
- type Conn
- type Connection
- type Event
- type EventHandler
- type EventLoopHandler
- type ExtraHandler
- type ExtraHandlers
- type OP
- type OPCode
- type PacemakerLoop
- type Websocket
Constants ¶
This section is empty.
Variables ¶
var ( // WSTimeout is the timeout for connecting and writing to the Websocket, // before Gateway cancels and fails. WSTimeout = 30 * time.Second // WSBuffer is the size of the Event channel. This has to be at least 1 to // make space for the first Event: Ready or Resumed. WSBuffer = 10 // WSError is the default error handler WSError = func(err error) { log.Println("Gateway error:", err) } // WSDebug is used for extra debug logging. This is expected to behave // similarly to log.Println(). WSDebug = func(v ...interface{}) {} )
var CloseDeadline = time.Second
CloseDeadline controls the deadline to wait for sending the Close frame.
var CopyBufferSize = 4096
CopyBufferSize is used for the initial size of the internal WS' buffer. Its size is 4KB.
var ErrEmptyPayload = errors.New("empty payload")
var ErrWebsocketClosed = errors.New("websocket is closed")
ErrWebsocketClosed is returned if the websocket is already closed.
var MaxCapUntilReset = CopyBufferSize * 4
MaxCapUntilReset determines the maximum capacity before the bytes buffer is re-allocated. It is roughly 16KB, quadruple CopyBufferSize.
Functions ¶
func ErrBrokenConnection ¶
ErrBrokenConnection marks the given error as a broken connection error. This error will cause the pacemaker loop to break and return the error. The error, when stringified, will say "explicit connection break."
func HandleEvent ¶
func HandleEvent(h EventHandler, ev Event) error
func IsBrokenConnection ¶
IsBrokenConnection returns true if the error is a broken connection error.
func NewDialLimiter ¶
func NewIdentityLimiter ¶
func NewSendLimiter ¶
func WaitForEvent ¶
WaitForEvent blocks until fn() returns true. All incoming events are handled regardless.
Types ¶
type Conn ¶
type Conn struct {
Dialer websocket.Dialer
Header http.Header
Conn *websocket.Conn
// contains filtered or unexported fields
}
Conn is the default Websocket connection. It tries to compresses all payloads using zlib.
func NewConn ¶
func NewConn() *Conn
NewConn creates a new default websocket connection with a default dialer.
func NewConnWithDialer ¶
NewConnWithDialer creates a new default websocket connection with a custom dialer.
func (*Conn) CloseGracefully ¶
type Connection ¶
type Connection interface {
// Dial dials the address (string). Context needs to be passed in for
// timeout. This method should also be re-usable after Close is called.
Dial(context.Context, string) error
// Listen returns an event channel that sends over events constantly. It can
// return nil if there isn't an ongoing connection.
Listen() <-chan Event
// Send allows the caller to send bytes. It does not need to clean itself
// up on errors, as the Websocket wrapper will do that.
//
// If the data is nil, it should send a close frame
Send(context.Context, []byte) error
// Close should close the websocket connection. The underlying connection
// may be reused, but this Connection instance will be reused with Dial. The
// Connection must still be reusable even if Close returns an error.
Close() error
// CloseGracefully sends a close frame and then closes the websocket
// connection.
CloseGracefully() error
}
Connection is an interface that abstracts around a generic Websocket driver. This connection expects the driver to handle compression by itself, including modifying the connection URL. The implementation doesn't have to be safe for concurrent use.
type EventHandler ¶
type EventLoopHandler ¶
type EventLoopHandler interface {
EventHandler
HeartbeatCtx(context.Context) error
}
TODO API
type ExtraHandler ¶
type ExtraHandlers ¶
type ExtraHandlers struct {
// contains filtered or unexported fields
}
func (*ExtraHandlers) Check ¶
func (ex *ExtraHandlers) Check(op *OP)
Check runs and sends OP data. It is not thread-safe.
type OP ¶
type OP struct {
Code OPCode `json:"op"`
Data json.Raw `json:"d,omitempty"`
// Only for Gateway Dispatch (op 0)
Sequence int64 `json:"s,omitempty"`
EventName string `json:"t,omitempty"`
}
func (*OP) UnmarshalData ¶
type PacemakerLoop ¶
type PacemakerLoop struct {
heart.Pacemaker
Extras ExtraHandlers
ErrorLog func(error)
// contains filtered or unexported fields
}
PacemakerLoop provides an event loop with a pacemaker. A zero-value instance is a valid instance only when RunAsync is called first.
func (*PacemakerLoop) Pace ¶
func (p *PacemakerLoop) Pace(ctx context.Context) error
Pace calls the pacemaker's Pace function.
func (*PacemakerLoop) SetEventChannel ¶
func (p *PacemakerLoop) SetEventChannel(evCh <-chan Event)
SetEventChannel sets the event channel inside the event loop. There is no guarantee that the channel is set when the function returns. This function is concurrently safe.
func (*PacemakerLoop) SetPace ¶
func (p *PacemakerLoop) SetPace(pace time.Duration)
SetPace (re)sets the pace duration. As with SetEventChannel, there is no guarantee that the pacer is reset when the function returns. This function is concurrently safe.
func (*PacemakerLoop) StartBeating ¶
func (p *PacemakerLoop) StartBeating(pace time.Duration, evl EventLoopHandler, exit func(error))
StartBeating asynchronously starts the pacemaker loop.
func (*PacemakerLoop) Stop ¶
func (p *PacemakerLoop) Stop()
Stop signals the pacemaker to stop. It does not wait for the pacer to stop. The pacer will call the given callback with a nil error.
type Websocket ¶
type Websocket struct {
// Timeout for connecting and writing to the Websocket, uses default
// WSTimeout (global).
Timeout time.Duration
// contains filtered or unexported fields
}
Websocket is a wrapper around a websocket Conn with thread safety and rate limiting for sending and throttling.
func NewCustom ¶
func NewCustom(conn Connection, addr string) *Websocket
NewCustom creates a new undialed Websocket.
func (*Websocket) Close ¶
Close closes the websocket connection. It assumes that the Websocket is closed even when it returns an error. If the Websocket was already closed before, ErrWebsocketClosed will be returned.
func (*Websocket) CloseGracefully ¶
func (*Websocket) Listen ¶
Listen returns the inner event channel or nil if the Websocket connection is not alive.
Source Files