pusher

README

pusher-ws-go

This package implements a Pusher websocket client. It is based on the official Pusher JavaScript client libary as well as go-pusher.

Installation

$ go get github.com/goguardian/pusher-ws-go

Features

• Connect to app
  • Custom cluster
  • Insecure connection
• Subscribe to channel
  • Auth for private and presence channels
  • Custom auth parameters
  • Custom auth headers
• Unsubscribe from channel
• Bind to events
  • Bind at app level
  • Bind at channel level
  • Bind global at app level
  • Bind global at channel level
• Unbind events
• Presence channel member data
• Cancel subscribing
• Handle pong timeout/reconnect

Documentation

Index

• Variables
• func UnmarshalDataString(data json.RawMessage, dest interface{}) error
• type AuthError
  • func (e AuthError) Error() string
• type Channel
• type Client
  • func (c *Client) Bind(event string) chan Event
  • func (c *Client) Connect(appKey string) error
  • func (c *Client) Disconnect() error
  • func (c *Client) SendEvent(event string, data interface{}, channelName string) error
  • func (c *Client) Subscribe(channelName string, opts ...SubscribeOption) (Channel, error)
  • func (c *Client) SubscribePresence(channelName string, opts ...SubscribeOption) (PresenceChannel, error)
  • func (c *Client) Unbind(event string, chans ...chan Event)
  • func (c *Client) Unsubscribe(channelName string) error
• type Event
• type EventError
  • func (e EventError) Error() string
• type Member
• type PresenceChannel
• type SubscribeOption
  • func WithSuccessTimeout(d time.Duration) SubscribeOption

Variables

var (
	// ErrNotSubscribed is returned by functions that require the channel to be
	// subscribed before being called.
	ErrNotSubscribed = errors.New("not subscribed")
	// ErrMissingMe indicates a presence channel was subscribed to, but the pusher
	// server violated the message protocol by not providing a member for the
	// current user.
	ErrMissingMe = errors.New("missing member for current user")
)

var ErrTimedOut = errors.New("timed out")

ErrTimedOut is the error returned when there is a timeout waiting for a subscription confirmation from Pusher

Functions

func UnmarshalDataString

func UnmarshalDataString(data json.RawMessage, dest interface{}) error

UnmarshalDataString is a convenience function to unmarshal double-encoded JSON data from a Pusher event. See https://pusher.com/docs/pusher_protocol#double-encoding

Types

type AuthError

type AuthError struct {
	Status int
	Body   string
}

An AuthError is returned when a non-200 status code is returned in a channel subscription authentication request.

func (AuthError) Error

func (e AuthError) Error() string

type Channel

type Channel interface {
	// IsSubscribed indicates if the channel is currently subscribed
	IsSubscribed() bool
	// Subscribe attempts to subscribe to the channel if the subscription is not
	// already active. Authentication will be attempted for private and presence
	// channels.
	Subscribe(...SubscribeOption) error
	// Unsubscribe attempts to unsubscribe from the channel. Note that a nil error
	// does not mean that the unsubscription was successful, just that the request
	// was sent.
	Unsubscribe() error
	// Bind returns a channel to which all the data from all matching events received
	// on the channel will be sent.
	Bind(event string) chan json.RawMessage
	// Unbind removes bindings for an event. If chans are passed, only those bindings
	// will be removed. Otherwise, all bindings for an event will be removed.
	Unbind(event string, chans ...chan json.RawMessage)
	// Trigger sends an event to the channel.
	Trigger(event string, data interface{}) error
}

Channel represents a subscription to a Pusher channel.

type Client

type Client struct {
	// The cluster to connect to. The default is Pusher's "mt1" cluster in the
	// "us-east-1" region.
	Cluster string
	// Whether to connect to Pusher over an insecure websocket connection.
	Insecure bool

	// The URL to call when authenticating private or presence channels.
	AuthURL string
	// Additional parameters to be sent in the POST body of an authentication request.
	AuthParams url.Values
	// Additional HTTP headers to be sent in an authentication request.
	AuthHeaders http.Header

	// If provided, errors that occur while receiving messages and errors emitted
	// by Pusher will be sent to this channel.
	Errors chan error
	// contains filtered or unexported fields
}

Client represents a Pusher websocket client. After creating an instance, it is necessary to call Connect to establish the connection with Pusher. Calling any other methods before a connection is established is an invalid operation and may panic.

func (*Client) Bind

func (c *Client) Bind(event string) chan Event

Bind returns a channel to which all matching events received on the connection will be sent.

func (*Client) Connect

func (c *Client) Connect(appKey string) error

Connect establishes a connection to the Pusher app specified by appKey.

func (*Client) Disconnect

func (c *Client) Disconnect() error

Disconnect closes the websocket connection to Pusher. Any subsequent operations are invalid until Connect is called again.

func (*Client) SendEvent

func (c *Client) SendEvent(event string, data interface{}, channelName string) error

SendEvent sends an event on the Pusher connection.

func (*Client) Subscribe

func (c *Client) Subscribe(channelName string, opts ...SubscribeOption) (Channel, error)

Subscribe creates a subscription to the specified channel. Authentication will be attempted for private and presence channels. If the channel has already been subscribed, this method will return the existing Channel instance.

A channel is always returned, regardless of any errors. The error value indicates if the subscription succeeded. Failed subscriptions may be retried with `Channel.Subscribe()`.

See SubscribePresence() for presence channels.

func (*Client) SubscribePresence

func (c *Client) SubscribePresence(channelName string, opts ...SubscribeOption) (PresenceChannel, error)

SubscribePresence creates a subscription to the specified presence channel. If the channel has already been subscribed, this method will return the existing channel instance.

A channel is always returned, regardless of any errors. The error value indicates if the subscription succeeded. Failed subscriptions may be retried with `Channel.Subscribe()`.

An error is returned if channelName is not a presence channel. Use Subscribe() for other channel types.

func (*Client) Unbind

func (c *Client) Unbind(event string, chans ...chan Event)

Unbind removes bindings for an event. If chans are passed, only those bindings will be removed. Otherwise, all bindings for an event will be removed.

func (*Client) Unsubscribe

func (c *Client) Unsubscribe(channelName string) error

Unsubscribe unsubscribes from the specified channel. Events will no longer be received from that channe. Note that a nil error does not mean that the unsubscription was successful, just that the request was sent.

type Event

type Event struct {
	Event   string          `json:"event"`
	Data    json.RawMessage `json:"data"`
	Channel string          `json:"channel,omitempty"`
}

Event represents an event sent to or received from a Pusher connection.

type EventError

type EventError struct {
	Message string `json:"message"`
	Code    int    `json:"code"`
}

EventError represents an error event received from Pusher.

func (EventError) Error

func (e EventError) Error() string

type Member

type Member struct {
	ID string
	// Info is the JSON set by the auth server. Do not modify the underlying byte
	// slice, it's shared by all instances of the member.
	Info json.RawMessage
}

Member represents a channel member.

type PresenceChannel

type PresenceChannel interface {
	Channel

	// BindMemberAdded returns a channel that receives a Member value when a user
	// joins the channel. Events may be delivered out of order. Use
	// UnbindMemberAdded when finished listening to events.
	BindMemberAdded() chan Member

	// UnbindMemberAdded removes bindings created by BindMemberAdded(). If chans
	// are passed, only those bindings will be removed. Otherwise, all bindings
	// for this event will be removed.
	UnbindMemberAdded(...chan Member)

	// BindMemberRemoved returns a channel that receives a user ID when a user
	// leaves the channel. Events may be delivered out of order. Use
	// UnbindMemberRemoved when finished listening for events.
	BindMemberRemoved() chan string

	// UnbindMemberRemoved removes bindings created by UnbindMemberRemoved(). If
	// chans are passed, only those bindings will be removed. Otherwise, all
	// bindings for this event will be removed.
	UnbindMemberRemoved(...chan string)

	// Members returns the member info of each user currently subscribed to the
	// channel.
	Members() map[string]Member

	// Member returns a representation of the channel member with the given ID.
	// `nil` is returned if the member isn't in the channel.
	Member(id string) *Member

	// Me returns the member for the current user.
	//
	// Possible errors:
	//  - not subscribed - subscription must succeed before calling Me()
	//  - invalid channel data - pusher server provided invalid JSON
	//  - missing member for current user - pusher server violated protocol
	Me() (*Member, error)

	// MemberCount returns the number of users connected to the channel.
	MemberCount() int
}

PresenceChannel provides information about the users that are currently subscribed.

Note: Bind() does not fire pusher:member_added/removed, use BindMemberAdded/Removed() instead.

type SubscribeOption

type SubscribeOption func(*subscribeOptions)

SubscribeOption is a configuration option for subscribing to a channel

func WithSuccessTimeout

func WithSuccessTimeout(d time.Duration) SubscribeOption

WithSuccessTimeout returns a SubscribeOption that sets the time that a subscription request will wait for a success response from Pusher before timing out. The default is 10 seconds.