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
- Variables
- type Client
- type Codec
- type Config
- type Conn
- type Decoder
- type Encoder
- type Message
- type SIOCodec
- type SIOStreamingCodec
- type ServeMux
- type SessionID
- type SocketIO
- func (sio *SocketIO) Broadcast(data interface{})
- func (sio *SocketIO) BroadcastExcept(c *Conn, data interface{})
- func (sio *SocketIO) GetConn(sessionid SessionID) (c *Conn)
- func (sio *SocketIO) ListenAndServeFlashPolicy(laddr string) os.Error
- func (sio *SocketIO) Log(v ...interface{})
- func (sio *SocketIO) Logf(format string, v ...interface{})
- func (sio *SocketIO) OnConnect(f func(*Conn)) os.Error
- func (sio *SocketIO) OnDisconnect(f func(*Conn)) os.Error
- func (sio *SocketIO) OnMessage(f func(*Conn, Message)) os.Error
- func (sio *SocketIO) ServeMux() *ServeMux
- type Transport
- func NewFlashsocketTransport(rtimeout, wtimeout int64) Transport
- func NewHTMLFileTransport(rtimeout, wtimeout int64) Transport
- func NewJSONPPollingTransport(rtimeout, wtimeout int64) Transport
- func NewWebsocketTransport(rtimeout, wtimeout int64) Transport
- func NewXHRMultipartTransport(rtimeout, wtimeout int64) Transport
- func NewXHRPollingTransport(rtimeout, wtimeout int64) Transport
- type WebsocketClient
- func (wc *WebsocketClient) Close() os.Error
- func (wc *WebsocketClient) Dial(rawurl string, origin string) (err os.Error)
- func (wc *WebsocketClient) OnDisconnect(f func())
- func (wc *WebsocketClient) OnMessage(f func(Message))
- func (wc *WebsocketClient) Send(payload interface{}) os.Error
- func (wc *WebsocketClient) SessionID() SessionID
Constants ¶
const ( SIOAnnotationRealm = "r" SIOAnnotationJSON = "j" )
The various delimiters used for framing in the socket.io protocol.
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.
const ( // Length of the session ids. SessionIDLength = 16 // Charset from which to build the session ids. SessionIDCharset = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz" )
Variables ¶
var ( // ErrDestroyed is used when the connection has been disconnected (i.e. can't be used anymore). ErrDestroyed = os.NewError("connection is disconnected") // ErrQueueFull is used when the send queue is full. ErrQueueFull = os.NewError("send queue is full") )
var ( // ErrNotConnected is used when some action required the connection to be online, // but it wasn't. ErrNotConnected = os.NewError("not connected") // ErrConnected is used when some action required the connection to be offline, // but it wasn't. ErrConnected = os.NewError("already connected") )
var ( NOPLogger = log.New(nopWriter{}, "", 0) DefaultLogger = log.New(os.Stdout, "", log.Ldate|log.Ltime) )
var DefaultConfig = Config{ MaxConnections: 0, QueueLength: 10, ReadBufferSize: 2048, HeartbeatInterval: 10e9, ReconnectTimeout: 10e9, Origins: nil, Transports: DefaultTransports, Codec: SIOCodec{}, Resource: "/socket.io/", Logger: DefaultLogger, }
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
var (
ErrMalformedPayload = os.NewError("malformed payload")
)
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client interface { io.Closer Dial(string, string) os.Error Send(interface{}) os.Error OnDisconnect(func()) OnMessage(func(Message)) SessionID() SessionID }
Client is a toy interface.
type Codec ¶
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 int64 // Period in ns during which the client must reconnect or it is considered // disconnected. ReconnectTimeout int64 // 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 {
// contains filtered or unexported fields
}
Conn represents a single session and handles its handshaking, message buffering and reconnections.
func (*Conn) Send ¶
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.
type Message ¶
type Message interface { Annotations() map[string]string Annotation(string) (string, bool) Data() string Type() uint8 JSON() (string, 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) NewEncoder ¶
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 ¶
func NewServeMux ¶
type SessionID ¶
type SessionID string
SessionID is just a string for now.
func NewSessionID ¶
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 ¶
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 ¶
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) ListenAndServeFlashPolicy ¶
func (*SocketIO) OnConnect ¶
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 ¶
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 ¶
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 ¶
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/.
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 ¶
Creates a new flashsocket transport with the given read and write timeouts.
func NewHTMLFileTransport ¶
Creates a new xhr-multipart transport with the given read and write timeouts.
func NewJSONPPollingTransport ¶
Creates a new json-polling transport with the given read and write timeouts.
func NewWebsocketTransport ¶
Creates a new websocket transport with the given read and write timeouts.
func NewXHRMultipartTransport ¶
Creates a new xhr-multipart transport with the given read and write timeouts.
func NewXHRPollingTransport ¶
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() os.Error
func (*WebsocketClient) Dial ¶
func (wc *WebsocketClient) Dial(rawurl string, origin string) (err os.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{}) os.Error
func (*WebsocketClient) SessionID ¶
func (wc *WebsocketClient) SessionID() SessionID