gevent-socketio

https://github.com/abourget/gevent-socketiohttps://github.com/Automattic/socket.io

Presentation

gevent-socketio is a Python implementation of the Socket.IO protocol, developed originally for Node.js by LearnBoostand then ported to other languages. Socket.IO enables real-time web communications between a browser and a server, using a WebSocket-like API. One aim of this project is to provide a single gevent-basedAPI that works across the different WSGI-based web frameworks out there (Pyramid, Pylons, Flask, web2py, Django, etc...). Only ~3 lines of code are required to tie-in gevent-socketio inyour framework. Note: you need to use the gevent python WSGI server to use gevent-socketio.

Technicaloverview

Most of the gevent-socketio implementation is pure Python. There is an obvious dependency ongevent,and another on gevent-websocket. There are integration examples for Pyramid, Flask, Django and BYOF (bring yourown framework!).

Documentationand References

You can read the renderered Sphinx docs at:http://readthedocs.org/docs/gevent-socketio/en/latest/Discussion and questions happen on the mailing list:https://groups.google.com/forum/#!forum/gevent-socketioor in the Github issue tracking:https://github.com/abourget/gevent-socketio/issuesYou can also contact the maintainer:https://twitter.com/#!/bourgetalexndrehttps://plus.google.com/109333785244622657612

Installation

You can install with standard Python methods:

pip install gevent-socketio

or from source:

git clone git://github.com/abourget/gevent-socketio.git
cd gevent-socketio
python setup.py install

For development, run instead of install:

python setup.py develop

If you want to do all of that in a virtualenv, run:

virtualenv env
. env/bin/activate
python setup.py develop   # or install

socket.io
 
How to use
The following example attaches socket.io to a plain Node.JS HTTP server listening on port [code]3000

.var server = require('http').Server();var io = require('socket.io')(server);io.on('connection', function(socket){socket.on('event', function(data){});socket.on('disconnect', function(){});});server.listen(3000);[/code]

Standalone

var io = require('socket.io')();io.on('connection', function(socket){});io.listen(3000);

In conjunction with Express

Starting with 3.0, express applications have become request handler functions that you pass to

http

or

http

Server

instances. You need to pass the

Server

to

socket.io

, and not the express application function.

var app = require('express')();var server = require('http').Server(app);var io = require('socket.io')(server);io.on('connection', function(){ /* … */ });server.listen(3000);

In conjunction with Koa

Like Express.JS, Koa works by exposing an application as a request handler function, but only by calling the

callback

method.

var app = require('koa')();var server = require('http').Server(app.callback());var io = require('socket.io')(server);io.on('connection', function(){ /* … */ });server.listen(3000);

API

Server

Exposed by

require('socket.io')

.

Server()

Creates a new

Server

. Works with and without

new

:

  var io = require('socket.io')();// orvar Server = require('socket.io');var io = new Server();

Server(opts:Object)

Optionally, the first or second argument (see below) of the

Server

constructor can be an options object.The following options are supported:

serveClient

sets the value for Server#serveClient()

path

sets the value for Server#path()The same options passed to socket.io are always passed to the

engine.io

Server

that gets created. See engine.io options as reference.

Server(srv:http#Server, opts:Object)

Creates a new

Server

and attaches it to the given

srv

. Optionally

opts

can be passed.

Server(port:Number, opts:Object)

Binds socket.io to a new

http.Server

that listens on

port

.

Server#serveClient(v:Boolean):Server

If

v

is

true

the attached server (see

Server#attach

) will serve the client files. Defaults to

true

.This method has no effect after

attach

is called.

  // pass a server and the `serveClient` optionvar io = require('socket.io')(http, { serveClient: false });// or pass no server and then you can call the methodvar io = require('socket.io')();io.serveClient(false);io.attach(http);

If no arguments are supplied this method returns the current value.

Server#path(v:String):Server

Sets the path

v

under which

engine.io

and the static files will be served. Defaults to

/socket.io

.If no arguments are supplied this method returns the current value.

Server#adapter(v:Adapter):Server

Sets the adapter

v

. Defaults to an instance of the

Adapter

that ships with socket.io which is memory based. See socket.io-adapter.If no arguments are supplied this method returns the current value.

Server#origins(v:String):Server

Sets the allowed origins

v

. Defaults to any origins being allowed.If no arguments are supplied this method returns the current value.

Server#sockets:Namespace

The default (

/

) namespace.

Server#attach(srv:http#Server, opts:Object):Server

Attaches the

Server

to an engine.io instance on

srv

with the supplied

opts

(optionally).

Server#attach(port:Number, opts:Object):Server

Attaches the

Server

to an engine.io instance that is bound to

port

with the given

opts

(optionally).

Server#listen

Synonym of

Server#attach

.

Server#bind(srv:engine#Server):Server

Advanced use only. Binds the server to a specific engine.io

Server

(or compatible API) instance.

Server#onconnection(socket:engine#Socket):Server

Advanced use only. Creates a new

socket.io

client from the incoming engine.io (or compatible API)

socket

.

Server#of(nsp:String):Namespace

Initializes and retrieves the given

Namespace

by its pathname identifier

nsp

.If the namespace was already initialized it returns it right away.

Server#emit

Emits an event to all connected clients. The following two are equivalent:

  var io = require('socket.io')();io.sockets.emit('an event sent to all connected clients');io.emit('an event sent to all connected clients');

For other available methods, see

Namespace

below.

Server#close

Closes socket server

  var io     = require('socket.io');var PORT   = 3030;var server = require('http').Server();io(PORT);io.close(); // Close current serverserver.listen(PORT); // PORT is free to useio(server);

Server#use

See

Namespace#use

below.

Namespace

Represents a pool of sockets connected under a given scope identified by a pathname (eg:

/chat

).By default the client always connects to

/

.

Events

connection

/

connect

. Fired upon a connection.Parameters:

Socket

the incoming socket.

Namespace#name:String

The namespace identifier property.

Namespace#connected:Object

Hash of

Socket

objects that are connected to this namespace indexed by

id

.

Namespace#use(fn:Function):Namespace

Registers a middleware, which is a function that gets executed for every incoming

Socket

and receives as parameter the socket and a function to optionally defer execution to the next registered middleware.

  var io = require('socket.io')();io.use(function(socket, next){if (socket.request.headers.cookie) return next();next(new Error('Authentication error'));});

Errors passed to middleware callbacks are sent as special

error

packets to clients.

Socket

A

Socket

is the fundamental class for interacting with browser clients. A

Socket

belongs to a certain

Namespace

(by default

/

) and uses an underlying

Client

to communicate.

Socket#rooms:Array

A list of strings identifying the rooms this socket is in.

Socket#client:Client

A reference to the underlying

Client

object.

Socket#conn:Socket

A reference to the underyling

Client

transport connection (engine.io

Socket

object).

Socket#request:Request

A getter proxy that returns the reference to the

request

that originated the underlying engine.io

Client

. Useful for accessing request headers such as

Cookie

or

User-Agent

.

Socket#id:String

A unique identifier for the socket session, that comes from the underlying

Client

.

Socket#emit(name:String[, …]):Socket

Emits an event to the socket identified by the string

name

. Any other parameters can be included.All datastructures are supported, including

Buffer

. JavaScript functions can't be serialized/deserialized.

  var io = require('socket.io')();io.on('connection', function(socket){socket.emit('an event', { some: 'data' });});

Socket#join(name:String[, fn:Function]):Socket

Adds the socket to the

room

, and fires optionally a callback

fn

with

err

signature (if any).The socket is automatically a member of a room identified with its session id (see

Socket#id

).The mechanics of joining rooms are handled by the

Adapter

that has been configured (see

Server#adapter

above), defaulting to socket.io-adapter.

Socket#leave(name:String[, fn:Function]):Socket

Removes the socket from

room

, and fires optionally a callback

fn

with

err

signature (if any).Rooms are left automatically upon disconnection.The mechanics of leaving rooms are handled by the

Adapter

that has been configured (see

Server#adapter

above), defaulting to socket.io-adapter.

Socket#to(room:String):Socket

Socket#in(room:String):Socket

Sets a modifier for a subsequent event emission that the event will only be broadcasted to sockets that have joined the given

room

.To emit to multiple rooms, you can call

to

several times.

  var io = require('socket.io')();io.on('connection', function(socket){socket.to('others').emit('an event', { some: 'data' });});

Client

The

Client

class represents an incoming transport (engine.io) connection. A

Client

can be associated with many multiplexed

Socket

that belong to different

Namespace

s.

Client#conn

A reference to the underlying

engine.io

Socket

connection.

Client#request

A getter proxy that returns the reference to the

request

that originated the engine.io connection. Useful for accessing request headers such as

Cookie

or

User-Agent

.

Debug / logging

Socket.IO is powered by debug. In order to see all the debug output, run your app with the environment variable

DEBUG

including the desired scope.To see the output from all of Socket.IO's debugging scopes you can use:

DEBUG=socket.io* node myapp

License

MIT