socketio

package
v0.5.2-0...-1f6a84e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2012 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

The socketio package is a simple abstraction layer for different web browser- supported transport mechanisms. It is fully compatible with the Socket.IO client side JavaScript socket API library by LearnBoost Labs (http://socket.io/), but through custom codecs it might fit other client implementations too.

It (together with the LearnBoost's client-side libraries) provides an easy way for developers to access the most popular browser transport mechanism today: multipart- and long-polling XMLHttpRequests, HTML5 WebSockets and forever-frames. The socketio package works hand-in-hand with the standard http package by plugging itself into a configurable ServeMux. It has an callback-style API for handling connection events. The callbacks are:

- SocketIO.OnConnect - SocketIO.OnDisconnect - SocketIO.OnMessage

Other utility-methods include:

- SocketIO.ServeMux - SocketIO.Broadcast - SocketIO.BroadcastExcept - SocketIO.GetConn - Conn.Send

Each new connection will be automatically assigned an unique session id and using those the clients can reconnect without losing messages: the server persists clients' pending messages (until some configurable point) if they can't be immediately delivered. All writes through Conn.Send by design asynchronous.

Finally, the actual format on the wire is described by a separate Codec. The default codecs (SIOCodec and SIOStreamingCodec) are compatible with the LearnBoost's Socket.IO client.

For example, here is a simple chat server: 

package main

import (
	"http"
	"log"
	"socketio"
)

func main() {
	sio := socketio.NewSocketIO(nil)

	sio.OnConnect(func(c *socketio.Conn) {
		sio.Broadcast(struct{ announcement string }{"connected: " + c.String()})
	})

	sio.OnDisconnect(func(c *socketio.Conn) {
		sio.BroadcastExcept(c,
			struct{ announcement string }{"disconnected: " + c.String()})
	})

	sio.OnMessage(func(c *socketio.Conn, msg socketio.Message) {
		sio.BroadcastExcept(c,
			struct{ message []string }{[]string{c.String(), msg.Data()}})
	})

	mux := sio.ServeMux()
	mux.Handle("/", http.FileServer("www/", "/"))

	if err := http.ListenAndServe(":8080", mux); err != nil {
		log.Fatal("ListenAndServe:", err)
	}
}

Index

Constants

View Source 
const (
	SIOAnnotationRealm = "r"
	SIOAnnotationJSON  = "j"
)

The various delimiters used for framing in the socket.io protocol.

View Source 
const (
	// MessageText is interpreted just as a string.
	MessageText = iota

	// MessageJSON is interpreted as a JSON encoded string.
	MessageJSON

	// MessageHeartbeat is interpreted as a heartbeat.
	MessageHeartbeat

	// MessageHeartbeat is interpreted as a heartbeat.
	MessageHandshake

	// MessageDisconnect is interpreted as a forced disconnection.
	MessageDisconnect
)

The different message types that are available.

View Source 
const (
	// Length of the session ids.
	SessionIDLength = 16

	// Charset from which to build the session ids.
	SessionIDCharset = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
)

Variables

View Source 
var (
	// ErrDestroyed is used when the connection has been disconnected (i.e. can't be used anymore).
	ErrDestroyed = errors.New("connection is disconnected")

	// ErrQueueFull is used when the send queue is full.
	ErrQueueFull = errors.New("send queue is full")
)
View Source 
var (
	// ErrNotConnected is used when some action required the connection to be online,
	// but it wasn't.
	ErrNotConnected = errors.New("not connected")

	// ErrConnected is used when some action required the connection to be offline,
	// but it wasn't.
	ErrConnected = errors.New("already connected")
)
View Source 
var (
	NOPLogger     = log.New(nopWriter{}, "", 0)
	DefaultLogger = log.New(os.Stdout, "", log.Ldate|log.Ltime)
)
View Source 
var DefaultConfig = Config{
	MaxConnections:    0,
	QueueLength:       10,
	ReadBufferSize:    2048,
	HeartbeatInterval: 10e9,
	ReconnectTimeout:  10e9,
	Origins:           nil,
	Transports:        DefaultTransports,
	Codec:             SIOCodec{},
	Resource:          "/socket.io/",
	Logger:            DefaultLogger,
}
View Source 
var DefaultTransports = []Transport{
	NewXHRPollingTransport(10e9, 5e9),
	NewXHRMultipartTransport(0, 5e9),
	NewWebsocketTransport(0, 5e9),
	NewHTMLFileTransport(0, 5e9),
	NewFlashsocketTransport(0, 5e9),
	NewJSONPPollingTransport(0, 5e9),
}

DefaultTransports holds the defaults

View Source 
var (
	ErrMalformedPayload = errors.New("malformed payload")
)

Functions

This section is empty.

Types

type Client 

type Client interface {
	io.Closer

	Dial(string, string) error
	Send(interface{}) error
	OnDisconnect(func())
	OnMessage(func(Message))
	SessionID() SessionID
}

Client is a toy interface.

type Codec 

type Codec interface {
	NewEncoder() Encoder
	NewDecoder(*bytes.Buffer) Decoder
}

A Codec wraps Encode and Decode methods.

Encode takes an interface{}, encodes it and writes it to the given io.Writer. Decode takes a slice of bytes and decodes them into messages. If the given payload can't be decoded, an ErrMalformedPayload error will be returned.

type Config 

type Config struct {
	// Maximum number of connections.
	MaxConnections int

	// Maximum amount of messages to store for a connection. If a connection
	// has QueueLength amount of undelivered messages, the following Sends will
	// return ErrQueueFull error.
	QueueLength int

	// The size of the read buffer in bytes.
	ReadBufferSize int

	// The interval between heartbeats
	HeartbeatInterval time.Duration

	// Period in ns during which the client must reconnect or it is considered
	// disconnected.
	ReconnectTimeout time.Duration

	// Origins to allow for cross-domain requests.
	// For example: ["localhost:8080", "myblog.com:*"].
	Origins []string

	// Transports to use.
	Transports []Transport

	// Codec to use.
	Codec Codec

	// The resource to bind to, e.g. /socket.io/
	Resource string

	// Logger to use.
	Logger *log.Logger
}

Config represents a set of configurable settings used by the server

type Conn 

type Conn struct {
	UserData interface{} // User data
	// contains filtered or unexported fields
}

Conn represents a single session and handles its handshaking, message buffering and reconnections.

func (*Conn) Close 

func (c *Conn) Close() error

func (*Conn) RemoteAddr 

func (c *Conn) RemoteAddr() string

RemoteAddr returns the remote network address of the connection in IP:port format

func (*Conn) Send 

func (c *Conn) Send(data interface{}) (err error)

Send queues data for a delivery. It is totally content agnostic with one exception: the given data must be one of the following: a handshake, a heartbeat, an int, a string or it must be otherwise marshallable by the standard json package. If the send queue has reached sio.config.QueueLength or the connection has been disconnected, then the data is dropped and a an error is returned.

func (*Conn) SessionID 

func (c *Conn) SessionID() SessionID

SessionID return the session id of Conn

func (*Conn) String 

func (c *Conn) String() string

String returns a string representation of the connection and implements the fmt.Stringer interface.

type Decoder 

type Decoder interface {
	Decode() ([]Message, error)
	Reset()
}

type DelayTimer 

type DelayTimer struct {
	Timeouts chan time.Time
	// contains filtered or unexported fields
}

func NewDelayTimer 

func NewDelayTimer() *DelayTimer

func (*DelayTimer) Reset 

func (w *DelayTimer) Reset(t time.Duration)

func (*DelayTimer) Stop 

func (w *DelayTimer) Stop()

type Encoder 

type Encoder interface {
	Encode(io.Writer, interface{}) error
}

type Message 

type Message interface {
	Annotations() map[string]string
	Annotation(string) (string, bool)
	Data() string
	Bytes() []byte
	Type() uint8
	JSON() ([]byte, bool)
	// contains filtered or unexported methods
}

Message wraps heartbeat, messageType and data methods.

Heartbeat returns the heartbeat value encapsulated in the message and an true or if the message does not encapsulate a heartbeat a false is returned. MessageType returns messageText, messageHeartbeat or messageJSON. Data returns the raw (full) message received.

type SIOCodec 

type SIOCodec struct{}

SIOCodec is the codec used by the official Socket.IO client by LearnBoost. Each message is framed with a prefix and goes like this: <DELIM>DATA-LENGTH<DELIM>[<OPTIONAL DELIM>]DATA.

func (SIOCodec) NewDecoder 

func (sc SIOCodec) NewDecoder(src *bytes.Buffer) Decoder

func (SIOCodec) NewEncoder 

func (sc SIOCodec) NewEncoder() Encoder

type SIOStreamingCodec 

type SIOStreamingCodec struct{}

SIOStreamingCodec is the codec used by the official Socket.IO client by LearnBoost under the development branch. This will be the default codec for 0.7 release.

func (SIOStreamingCodec) NewDecoder 

func (sc SIOStreamingCodec) NewDecoder(src *bytes.Buffer) Decoder

func (SIOStreamingCodec) NewEncoder 

func (sc SIOStreamingCodec) NewEncoder() Encoder

type ServeMux 

type ServeMux struct {
	*http.ServeMux
	// contains filtered or unexported fields
}

func NewServeMux 

func NewServeMux(sio *SocketIO) *ServeMux

func (*ServeMux) ServeHTTP 

func (mux *ServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)

type SessionID 

type SessionID string

SessionID is just a string for now.

func NewSessionID 

func NewSessionID() (sid SessionID, err error)

NewSessionID creates a new ~random session id that is SessionIDLength long and consists of random characters from the SessionIDCharset.

type SocketIO 

type SocketIO struct {
	// contains filtered or unexported fields
}

SocketIO handles transport abstraction and provide the user a handfull of callbacks to observe different events.

func NewSocketIO 

func NewSocketIO(config *Config) *SocketIO

NewSocketIO creates a new socketio server with chosen transports and configuration options. If transports is nil, the DefaultTransports is used. If config is nil, the DefaultConfig is used.

func (*SocketIO) Broadcast 

func (sio *SocketIO) Broadcast(data interface{})

Broadcast schedules data to be sent to each connection.

func (*SocketIO) BroadcastExcept 

func (sio *SocketIO) BroadcastExcept(c *Conn, data interface{})

BroadcastExcept schedules data to be sent to each connection except c. It does not care about the type of data, but it must marshallable by the standard json-package.

func (*SocketIO) GetConn 

func (sio *SocketIO) GetConn(sessionid SessionID) (c *Conn)

GetConn digs for a session with sessionid and returns it.

func (*SocketIO) ListenAndServeFlashPolicy 

func (sio *SocketIO) ListenAndServeFlashPolicy(laddr string) error

func (*SocketIO) Log 

func (sio *SocketIO) Log(v ...interface{})

func (*SocketIO) Logf 

func (sio *SocketIO) Logf(format string, v ...interface{})

func (*SocketIO) OnConnect 

func (sio *SocketIO) OnConnect(f func(*Conn)) error

OnConnect sets f to be invoked when a new session is established. It passes the established connection as an argument to the callback.

func (*SocketIO) OnDisconnect 

func (sio *SocketIO) OnDisconnect(f func(*Conn)) error

OnDisconnect sets f to be invoked when a session is considered to be lost. It passes the established connection as an argument to the callback. After disconnection the connection is considered to be destroyed, and it should not be used anymore.

func (*SocketIO) OnMessage 

func (sio *SocketIO) OnMessage(f func(*Conn, Message)) error

OnMessage sets f to be invoked when a message arrives. It passes the established connection along with the received message as arguments to the callback.

func (*SocketIO) ServeMux 

func (sio *SocketIO) ServeMux() *ServeMux

Mux maps resources to the http.ServeMux mux under the resource given. The resource must end with a slash and if the mux is nil, the http.DefaultServeMux is used. It registers handlers for URLs like: <resource><t.resource>[/], e.g. /socket.io/websocket && socket.io/websocket/.

func (*SocketIO) SetAuthorization 

func (sio *SocketIO) SetAuthorization(f func(*http.Request) bool) error

SetAuthorization sets f to be invoked when a new http request is made. It passes the http.Request as an argument to the callback. The callback should return true if the connection is authorized or false if it should be dropped. Not setting this callback results in a default pass-through.

type Transport 

type Transport interface {
	Resource() string
	// contains filtered or unexported methods
}

Transport is the interface that wraps the Resource and newSocket methods.

Resource returns the resource name of the transport, e.g. "websocket". NewSocket creates a new socket that embeds the corresponding transport mechanisms.

func NewFlashsocketTransport 

func NewFlashsocketTransport(rtimeout, wtimeout time.Duration) Transport

Creates a new flashsocket transport with the given read and write timeouts.

func NewHTMLFileTransport 

func NewHTMLFileTransport(rtimeout, wtimeout int64) Transport

Creates a new xhr-multipart transport with the given read and write timeouts.

func NewJSONPPollingTransport 

func NewJSONPPollingTransport(rtimeout, wtimeout int64) Transport

Creates a new json-polling transport with the given read and write timeouts.

func NewWebsocketTransport 

func NewWebsocketTransport(rtimeout, wtimeout time.Duration) Transport

Creates a new websocket transport with the given read and write timeouts.

func NewXHRMultipartTransport 

func NewXHRMultipartTransport(rtimeout, wtimeout time.Duration) Transport

Creates a new xhr-multipart transport with the given read and write timeouts.

func NewXHRPollingTransport 

func NewXHRPollingTransport(rtimeout, wtimeout time.Duration) Transport

Creates a new xhr-polling transport with the given read and write timeouts.

type WebsocketClient 

type WebsocketClient struct {
	// contains filtered or unexported fields
}

WebsocketClient is a toy that implements the Client interface.

func NewWebsocketClient 

func NewWebsocketClient(codec Codec) (wc *WebsocketClient)

func (*WebsocketClient) Close 

func (wc *WebsocketClient) Close() error

func (*WebsocketClient) Dial 

func (wc *WebsocketClient) Dial(rawurl string, origin string) (err error)

func (*WebsocketClient) OnDisconnect 

func (wc *WebsocketClient) OnDisconnect(f func())

func (*WebsocketClient) OnMessage 

func (wc *WebsocketClient) OnMessage(f func(Message))

func (*WebsocketClient) Send 

func (wc *WebsocketClient) Send(payload interface{}) error

func (*WebsocketClient) SessionID 

func (wc *WebsocketClient) SessionID() SessionID

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.