Transmit
npm install transmit
Transmit is two things:
- Abstractions on top of the ws library
- A similar set of abstractions for the client, automatically exposed
Features:
- Callback behavior
- Integration with sessions
- Client grouping
- Broadcasting
Incompatible with Express beta, make sure that you are using Express 2.5.x
Basic example
Server
server.js
var express = app = express var lactate = app app var transmit = transmit
Client
index.html
Transmit example
Integrating with express sessions
To integrate express sessions with Transmit, first make sure you have node_redis
and connect-redis
modules installed.
npm install redis hiredis connect-redis
Then simply set sessions
to true
in the Transmit options.
var express = var app = express var RedisStore = express appapp
Transmit parses incoming connection headers to find the connect session ID, queries Redis for the session data, and JSON parses it. Transmit is then loosely-coupled to your express app.
To query Redis for sessions after the client has connected:
transmit
Grouping clients
Transmit allows you to group clients any way you like, by exposing a mapping function. Combined with Express sessions this can be quite convenient. Example.
{ reqsessionurl = requrl return } app var transmit = sessions:true transmit transmit
Server methods
on (event string, callback function)
Applicable events
connection
socketerror
errorclose
listen (server http(s).Server, callback function)
Callback function is executed for every connection with one argument: the connecting socket
broadcast (event string, message stringifiable)
group (fn function)
This method will map your clients into groups, using fn
. In the following example your clients will be grouped by the someProperty
property of their session object (assuming sessions have been enabled). To access a group you may use either Transmit's of
method or the peers
method attached to Transmit clients.
transmit
of (group string)
Returns an array of clients by group name.
close
Close the server
Socket methods
These methods exist on both the client and server-side.
on (event string, callback function)
Applicable events
error
errorclose
send (event string, message stringifiable, callback function)
The send
method automatically stringifies your second argument. An optional third argument is for callback function.
Transmit's stringification format is: JSON.stringify([event, data])
Server
socket
Client
transmit
sendBinary (data buffer)
peers (fn function)
Without a callback this function returns an array containing the client's peers. Otherwise, your callback will be executed for every peer.
While using a callback to broadcast to a peer group, note that to avoid Transmit's automatic stringification you may use the native send
method attached to the socket
property. At this level Transmit behaves just like the ws
module. However, note also that Transmit stringifies in the format described above.
var ids = socket var dataString = JSON socket
close
Close the client
Options
Transmit
options
The client_name
option refers to the name with which to expose our client script. By default, the client script is accessed from /transmit
.
var id = 'to_defy_the_laws_of_tradition_is_a_crusade_only_of_the_brave' var transmit = 'client_name':id /* The script can now be accessed from /to_defy_the_laws_of_tradition_is_a_crusade_only_of_the_brave*/
To prevent the client script from being served, use no_client
var transmit = no_client:true
To integrate with express sessions using connect-redis, set sessions
to true.
This will automatically fetch sessions from connect-redis and attach the session
property to incoming sockets.
var transmit = sessions:true
ws
options
To set ws
options, you may pass them to the initialization function like so
var transmit = port:2112
You can find all of the available ws
options here
node_redis
options
Transmit uses Redis (node_redis) to fetch sessions from a connect-redis
session store. If you don't care about sessions, these options don't apply to you. If you do care about integrating sessions, see the section above on that topic.
You may pass options to node_redis by way of the redis
property. See available options here
var transmit = redis:
Lactate
options
For serving the client script, Transmit relies on Lactate.
You may set Lactate options using lactate
like so
var _transmit = lactate: expires:'one year'
A complex options example:
var options = port:2112 client_name:'MyScript' sessions:false lactate: expires:'two days' cache:false redis: parser:'javascript' no_ready_check:true var transmit = options