socketio

package module
Version: v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Mar 7, 2011 License: MIT Imports: 16 Imported by: 0

README

go-socket.io

The socketio package is a simple abstraction layer for different web browser- supported transport mechanisms. It is fully compatible with the Socket.IO client JavaScript-library by LearnBoost Labs. By writing custom codecs the socketio could be perhaps used with other clients, too.

It provides an easy way for developers to rapidly prototype with the most popular browser transport mechanism today:

Demo

The Paper Experiment

Crash course

The socketio package works hand-in-hand with the standard http package (by plugging itself into http.ServeMux) and hence it doesn't need a full network port for itself. It has an callback-style event handling API. The callbacks are:

  • SocketIO.OnConnect
  • SocketIO.OnDisconnect
  • SocketIO.OnMessage

Other utility-methods include:

  • SocketIO.ServeMux
  • SocketIO.Broadcast
  • SocketIO.BroadcastExcept
  • SocketIO.GetConn

Each new connection will be automatically assigned an 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 are by design asynchronous and can be made through Conn.Send. The server also abstracts handshaking and various keep-alive mechanisms.

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

Example: 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)
	}
}

tl;dr

You can get the code and run the bundled example by following these steps:

$ git clone git://github.com/madari/go-socket.io.git
$ cd go-socket.io
$ git submodule update --init --recursive
$ make install
$ cd example
$ make
$ ./example

License

(The MIT License)

Copyright (c) 2011 Jukka-Pekka Kekkonen <karatepekka@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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 = os.NewError("connection is disconnected")

	// ErrQueueFull is used when the send queue is full.
	ErrQueueFull = os.NewError("send queue is full")
)
View Source
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")
)
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,
}

DefaultTransports holds the defaults

View Source
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

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 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) Close

func (c *Conn) Close() os.Error

func (*Conn) Send

func (c *Conn) Send(data interface{}) (err os.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) 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, os.Error)
	Reset()
}

type Encoder

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

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) 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 os.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) os.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)) os.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)) os.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)) os.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/.

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 int64) 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 int64) Transport

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

func NewXHRMultipartTransport

func NewXHRMultipartTransport(rtimeout, wtimeout int64) Transport

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

func NewXHRPollingTransport

func NewXHRPollingTransport(rtimeout, wtimeout int64) 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() 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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL