Documentation
¶
Overview ¶
Package wsutil provides abstractions around the Websocket, including rate limits.
Index ¶
- Variables
- func IsUnknownEvent(err error) bool
- func NewDialLimiter() *rate.Limiter
- func NewGlobalIdentityLimiter() *rate.Limiter
- func NewIdentityLimiter() *rate.Limiter
- func NewSendLimiter() *rate.Limiter
- type BackgroundErrorEvent
- type Broadcaster
- type CloseEvent
- type Codec
- type Conn
- type Connection
- type ConnectionError
- type DecodeBuffer
- type Event
- type EventType
- type Gateway
- func (g *Gateway) AssertIsNotRunning()
- func (g *Gateway) Connect(ctx context.Context, h Handler) <-chan Op
- func (g *Gateway) HasStarted() bool
- func (g *Gateway) LastError() error
- func (g *Gateway) QueueReconnect()
- func (g *Gateway) ResetHeartbeat(d time.Duration)
- func (g *Gateway) Send(ctx context.Context, data Event) error
- func (g *Gateway) SendError(err error)
- func (g *Gateway) SendErrorWrap(err error, message string)
- type GatewayOpts
- type Handler
- type Op
- type OpCode
- type OpFunc
- type OpUnmarshalers
- type UnknownEventError
- type Websocket
Constants ¶
This section is empty.
Variables ¶
var ( // 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 DefaultGatewayOpts = GatewayOpts{ ReconnectDelay: func(try int) time.Duration { return time.Duration(4+(2*try)) * time.Second }, DialTimeout: 0, ReconnectAttempt: 0, AlwaysCloseGracefully: true, }
DefaultGatewayOpts is the default event loop options.
var ErrWebsocketClosed = errors.New("websocket is closed")
ErrWebsocketClosed is returned if the websocket is already closed.
Functions ¶
func IsUnknownEvent ¶
IsBrokenConnection returns true if the error is a broken connection error.
func NewDialLimiter ¶
func NewIdentityLimiter ¶
func NewSendLimiter ¶
Types ¶
type BackgroundErrorEvent ¶
type BackgroundErrorEvent struct {
Err error
}
BackgroundErrorEvent describes an error that the gateway event loop might stumble upon while it's running. See Gateway's documentation for possible usages.
func (*BackgroundErrorEvent) Error ¶
func (err *BackgroundErrorEvent) Error() string
Error formats the BackgroundErrorEvent.
func (*BackgroundErrorEvent) EventType ¶
func (err *BackgroundErrorEvent) EventType() EventType
EventType implements Op. It returns an opaque unique string.
func (*BackgroundErrorEvent) Op ¶
func (err *BackgroundErrorEvent) Op() OpCode
Op implements Op. It returns -1.
func (*BackgroundErrorEvent) Unwrap ¶
func (err *BackgroundErrorEvent) Unwrap() error
Unwrap returns err.Err.
type Broadcaster ¶
type Broadcaster struct {
// contains filtered or unexported fields
}
Broadcaster is primarily used for debugging.
func NewBroadcaster ¶
func NewBroadcaster(src <-chan Op) *Broadcaster
NewBroadcaster creates a new broadcaster.
func (*Broadcaster) NewSubscribed ¶
func (b *Broadcaster) NewSubscribed() <-chan Op
NewSubscribed creates a newly subscribed Op channel.
func (*Broadcaster) Subscribe ¶
func (b *Broadcaster) Subscribe(ch chan<- Op)
Subscribe subscribes the given channel
type CloseEvent ¶
type CloseEvent struct {
// Err is the underlying error.
Err error
// Code is the websocket close code, if any.
Code int
}
CloseEvent is an event that is given from wsutil when the websocket is closed.
func (*CloseEvent) Error ¶
func (e *CloseEvent) Error() string
Error formats the CloseEvent. A CloseEvent is also an error.
func (*CloseEvent) EventType ¶
func (e *CloseEvent) EventType() EventType
EventType implements Event. It returns an emty string.
type Codec ¶
type Codec struct {
Unmarshalers OpUnmarshalers
Headers http.Header
}
Codec holds the codec states for Websocket implementations to share with the manager. It is used internally in the Websocket and the Connection implementation.
func NewCodec ¶
func NewCodec(unmarshalers OpUnmarshalers) Codec
NewCodec creates a new default Codec instance.
func (Codec) DecodeFrom ¶
func (c Codec) DecodeFrom(r io.Reader, buf *DecodeBuffer) Op
DecodeFrom reads the given reader and decodes it into an Op.
buf is optional.
type Conn ¶
type Conn struct {
// CloseTimeout is the timeout for graceful closing. It's defaulted to 5s.
CloseTimeout time.Duration
// contains filtered or unexported fields
}
Conn is the default Websocket connection. It tries to compresses all payloads using zlib.
func NewConnWithDialer ¶
NewConnWithDialer creates a new default websocket connection with a custom dialer.
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) (<-chan Op, error)
// Send allows the caller to send bytes.
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. If
// gracefully is true, then the implementation must send a close frame
// prior.
Close(gracefully bool) 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 ConnectionError ¶
type ConnectionError struct {
Err error
}
ConnectionError is given to the user if the gateway fails to connect to the gateway for any reason, including during an initial connection or a reconnection. To check for this error, use the errors.As function.
func (ConnectionError) Unwrap ¶
func (err ConnectionError) Unwrap() error
Unwrap unwraps the ConnectionError.
type DecodeBuffer ¶
type DecodeBuffer struct {
// contains filtered or unexported fields
}
DecodeBuffer boxes a byte slice to provide a shared and thread-unsafe buffer. It is used internally and should only be handled around as an opaque thing.
func NewDecodeBuffer ¶
func NewDecodeBuffer(cap int) DecodeBuffer
NewDecodeBuffer creates a new preallocated DecodeBuffer.
type EventType ¶
type EventType string
EventType is a type for event types, which is the "t" field in the payload.
type Gateway ¶
type Gateway struct {
// contains filtered or unexported fields
}
Gateway describes an instance that handles the Discord gateway. It is basically an abstracted concurrent event loop that the user could signal to start connecting to the Discord gateway server.
func NewGateway ¶
func NewGateway(ws *Websocket, opts *GatewayOpts) *Gateway
NewGateway creates a new Gateway with a custom gateway URL and a pre-existing Identifier. If opts is nil, then DefaultOpts is used.
func (*Gateway) AssertIsNotRunning ¶
func (g *Gateway) AssertIsNotRunning()
AssertIsNotRunning asserts that the gateway is currently not running. If the gateway is running, the method will panic. Since a gateway cannot be started back up, this method can be used to detect whether or not the caller in a single goroutine can read the state safely.
func (*Gateway) Connect ¶
Connect starts the background goroutine that tries its best to maintain a stable connection to the Websocket gateway. To the user, the gateway should appear to be working seamlessly.
For more documentation, refer to (*gateway.Gateway).Connect.
func (*Gateway) HasStarted ¶
HasStarted returns true if the gateway event loop is currently spinning.
func (*Gateway) QueueReconnect ¶
func (g *Gateway) QueueReconnect()
QueueReconnect queues a reconnection in the gateway loop. This method should only be called in the event loop ONCE; calling more than once will deadlock the loop.
func (*Gateway) ResetHeartbeat ¶
ResetHeartbeat resets the heartbeat to be the given duration.
func (*Gateway) SendError ¶
SendError sends the given error wrapped in a BackgroundErrorEvent into the event channel.
func (*Gateway) SendErrorWrap ¶
SendErrorWrap is a convenient function over SendError.
type GatewayOpts ¶
type GatewayOpts struct {
// ReconnectDelay determines the duration to idle after each failed retry.
// This can be used to implement exponential backoff. The default is already
// sane, so this field rarely needs to be changed.
ReconnectDelay func(try int) time.Duration
// FatalCloseCodes is a list of close codes that will cause the gateway to
// exit out if it stumbles on one of these. It is a copy of FatalCloseCodes
// (the global variable) by default.
FatalCloseCodes []int
// DialTimeout is the timeout to wait for each websocket dial before failing
// it and retrying. Default is 0.
DialTimeout time.Duration
// ReconnectAttempt is the maximum number of attempts made to Reconnect
// before aborting the whole gateway. If this set to 0, unlimited attempts
// will be made. Default is 0.
ReconnectAttempt int
// AlwaysCloseGracefully, if true, will always make the Gateway close
// gracefully once the context given to Open is cancelled. It governs the
// Close behavior. The default is true.
AlwaysCloseGracefully bool
}
GatewayOpts describes the gateway event loop options.
type Handler ¶
type Handler interface {
// OnOp is called by the gateway event loop on every new Op. If the returned
// boolean is false, then the loop fatally exits.
OnOp(context.Context, Op) (canContinue bool)
// SendHeartbeat is called by the gateway event loop everytime a heartbeat
// needs to be sent over.
SendHeartbeat(context.Context)
// Close closes the handler.
Close() error
}
Handler describes a gateway handler. It describes the core that governs the behavior of the gateway event loop.
type Op ¶
type Op struct {
Code OpCode `json:"op"`
Data Event `json:"d,omitempty"`
// Type is only for gateway dispatch events.
Type EventType `json:"t,omitempty"`
// Sequence is only for gateway dispatch events (Op 0).
Sequence int64 `json:"s,omitempty"`
}
Op is a gateway Operation.
type OpCode ¶
type OpCode int
OpCode is the type for websocket Op codes. Op codes less than 0 are internal Op codes and should usually be ignored.
type OpUnmarshalers ¶
type OpUnmarshalers struct {
// contains filtered or unexported fields
}
OpUnmarshalers contains a map of event constructor function.
func NewOpUnmarshalers ¶
func NewOpUnmarshalers(funcs ...OpFunc) OpUnmarshalers
NewOpUnmarshalers creates a nwe OpUnmarshalers instance from the given constructor functions.
func (OpUnmarshalers) Add ¶
func (m OpUnmarshalers) Add(funcs ...OpFunc)
Add adds the given functions into the unmarshaler registry.
type UnknownEventError ¶
UnknownEventError is required by HandleOp if an event is encountered that is not known. Internally, unknown events are logged and ignored. It is not a fatal error.
func (UnknownEventError) Error ¶
func (err UnknownEventError) Error() string
Error formats the unknown event error to with the event name and payload
type Websocket ¶
type Websocket struct {
// contains filtered or unexported fields
}
Websocket is a wrapper around a websocket Conn with thread safety and rate limiting for sending and throttling.
func NewCustomWebsocket ¶
func NewCustomWebsocket(conn Connection, addr string) *Websocket
NewCustomWebsocket creates a new undialed Websocket.
func NewWebsocket ¶
NewWebsocket creates a default Websocket with the given address.
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 ¶
CloseGracefully is similar to Close, but a proper close frame is sent to Discord, invalidating the internal session ID and voiding resumes.
Source Files
Directories