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(wsURL 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) Unbind(event string, chans ...chan Event)
  • func (c *Client) Unsubscribe(channelName string) error
• type Event
• type EventError
  • func (e EventError) Error() string
• type SubscribeOption
  • func WithSuccessTimeout(d time.Duration) SubscribeOption

Variables

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
	// contains filtered or unexported methods
}

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(wsURL 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.

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 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.