session

Documentation

Overview

Package session abstracts around the REST API and the Gateway, managing both at once. It offers a handler interface similar to that in discordgo for Gateway events.

Index

• Variables
• type Session
  • func Login(ctx context.Context, email, password, mfa string) (*Session, error)
  • func New(token string) *Session
  • func NewCustom(id gateway.Identifier, cl *api.Client, h *handler.Handler) *Session
  • func NewWithGateway(g *gateway.Gateway, h *handler.Handler) *Session
  • func NewWithIdentifier(id gateway.Identifier) *Session
  • func NewWithIntents(token string, intents ...gateway.Intents) *Session
  • func (s *Session) AddIntents(intents gateway.Intents)
  • func (s *Session) AddInteractionHandler(h webhook.InteractionHandler)
  • func (s *Session) AddInteractionHandlerFunc(f webhook.InteractionHandlerFunc)
  • func (s *Session) Close() error
  • func (s *Session) Connect(ctx context.Context) error
  • func (s *Session) Gateway() *gateway.Gateway
  • func (s *Session) GatewayError() error
  • func (s *Session) GatewayIsAlive() bool
  • func (s *Session) GatewayOpts() *ws.GatewayOpts
  • func (s *Session) HasIntents(intents gateway.Intents) bool
  • func (s *Session) Open(ctx context.Context) error
  • func (s *Session) SendGateway(ctx context.Context, m ws.Event) error
  • func (s *Session) Wait(ctx context.Context) error
  • func (s *Session) WithContext(ctx context.Context) *Session

Variables

var ErrClosed = errors.New("Session is closed")

ErrClosed is returned if the Session is closed, either because it's already closed (and Close is being called again) or it was never started.

var ErrMFA = errors.New("account has 2FA enabled")

ErrMFA is returned if the account requires a 2FA code to log in.

Types

type Session

type Session struct {
	*api.Client
	*handler.Handler

	// OnInteractionError is called when an interaction added using
	// AddInteractionHandler cannot be sent. By default, it logs into the
	// console.
	OnInteractionError func(*gateway.InteractionCreateEvent, error)

	// DontWaitForReady makes Open not wait for the Ready event. This is useful
	// for non-bots, since Discord may send over a READY_SUPPLEMENT instead. If
	// this is true, then any event sent by Discord will unblock Open (usually
	// HELLO).
	DontWaitForReady bool // false
	// contains filtered or unexported fields
}

Session manages both the API and Gateway. As such, Session inherits all of API's methods, as well has the Handler used for Gateway.

func Login

func Login(ctx context.Context, email, password, mfa string) (*Session, error)

Login tries to log in as a normal user account; MFA is optional.

func New

func New(token string) *Session

New creates a new session from a given token. Most bots should be using NewWithIntents instead.

func NewCustom

func NewCustom(id gateway.Identifier, cl *api.Client, h *handler.Handler) *Session

NewCustom constructs a bare Session from the given parameters.

func NewWithGateway

func NewWithGateway(g *gateway.Gateway, h *handler.Handler) *Session

NewWithGateway constructs a bare Session from the given UNOPENED gateway.

func NewWithIdentifier

func NewWithIdentifier(id gateway.Identifier) *Session

NewWithIdentifier creates a bare Session with the given identifier.

func NewWithIntents

func NewWithIntents(token string, intents ...gateway.Intents) *Session

NewWithIntents is similar to New but adds the given intents in during construction.

func (*Session) AddIntents

func (s *Session) AddIntents(intents gateway.Intents)

AddIntents adds the given intents into the gateway. Calling it after Open has already been called will result in a panic.

func (*Session) AddInteractionHandler

func (s *Session) AddInteractionHandler(h webhook.InteractionHandler)

AddInteractionHandler adds an interaction handler function to be handled with the gateway and the API client. Use this as a compatibility layer for bots that support both methods of hosting.

AddInteractionHandler will automatically send the return value of the interaction handler to the API. If the return value cannot be sent successfully, then s.OnInteractionError will be called.

func (*Session) AddInteractionHandlerFunc

func (s *Session) AddInteractionHandlerFunc(f webhook.InteractionHandlerFunc)

AddInteractionHandlerFunc is a function variant of AddInteractionHandler.

func (*Session) Close

func (s *Session) Close() error

Close closes the underlying Websocket connection, invalidating the session ID. It will send a closing frame before ending the connection, closing it gracefully. This will cause the bot to appear as offline instantly. To prevent this behavior, change Gateway.AlwaysCloseGracefully.

func (*Session) Connect

func (s *Session) Connect(ctx context.Context) error

Connect opens the Discord gateway and waits until an unrecoverable error occurs. Always prefer this method over Open. Note that Connect will return when ctx is done or when s.Close is called.

As an odd case, when ctx is done and if the gateway is already finished connecting, then a nil error will be returned (unless the gateway has an error). This is contrary to the common behavior of a ctx function returning ctx.Err().

func (*Session) Gateway

func (s *Session) Gateway() *gateway.Gateway

Gateway returns the current session's gateway. If Open has never been called or Session was never constructed with a gateway, then nil is returned.

func (*Session) GatewayError

func (s *Session) GatewayError() error

GatewayError returns the gateway's error if the gateway is dead. If it's not dead, then nil is always returned. The check is done with GatewayIsAlive(). If the gateway has never been started, nil will be returned (even though GatewayIsAlive would've returned true).

This method would return what Close() would've returned if a fatal gateway error was found.

func (*Session) GatewayIsAlive

func (s *Session) GatewayIsAlive() bool

GatewayIsAlive returns true if the gateway is still alive, that is, it is either connected or is trying to reconnect after an interruption. In other words, false is returned if the gateway isn't open or it has exited after seeing a fatal error code (and therefore cannot recover).

func (*Session) GatewayOpts

func (s *Session) GatewayOpts() *ws.GatewayOpts

GatewayOpts returns a copy of the current session's gateway options. If Open has never been called or Session was never constructed with a gateway, then the default gateway options are returned.

func (*Session) HasIntents

func (s *Session) HasIntents(intents gateway.Intents) bool

HasIntents reports if the Gateway has the passed Intents.

If no intents are set, e.g. if using a user account, HasIntents will always return true.

func (*Session) Open

func (s *Session) Open(ctx context.Context) error

Open opens the Discord gateway and its handler, then waits until either the Ready or Resumed event gets through. Prefer using Connect instead of Open.

func (*Session) SendGateway

func (s *Session) SendGateway(ctx context.Context, m ws.Event) error

SendGateway is a helper to send messages over the gateway. It will check if the gateway is open and available, then send the message.

func (*Session) Wait

func (s *Session) Wait(ctx context.Context) error

Wait blocks until either ctx is done or the gateway stumbles on an unrecoverable error.

func (*Session) WithContext

func (s *Session) WithContext(ctx context.Context) *Session

WithContext returns a shallow copy of Session with the context replaced in the API client. All methods called on the returned Session will use this given context.

This method is thread-safe only after Open and before Close are called. Open and Close should not be called on the returned Session.