Nefarious Planetary Meddling

    wesley

    0.3.5 • Public • Published

    Wesley

    Version: 0.3.5
    Master build: Master branch build status

    Wesley? What the frig?

    Wesley is a protocol compliant web socket server with some awesome extras.

    $ npm install wesley

    Usage

    var server = require('wesley').listen(3000);
     
    server.on('connection', function(client) {
     
        // Relay data to all clients on the server
        client.on('data', function(data) {
            server.write(data);
        });
     
    });

    Pooling

    Sometimes it's necessary to maintain logical pools of clients (AKA namespaces, rooms, topics, etc).

    var server = require('wesley').listen(3000);
     
    server.on('connection', function(client, pool) {
     
        // Relay data to the current pool of clients
        client.on('data', function(data) {
            pool.write(data);
        });
     
    });

    The default pooling strategy separates clients based on the path they connect to.

    ws://localhost:3000/            # Server and / events 
    ws://localhost:3000/pool        # Server and /pool events 
    ws://localhost:3000/pool/child  # Server and /pool/child events 

    This behavoiur can be overridden by passing in your own handler. The callback expects to be called with the name of the pool to join.

    var pooling = function(client, callback) {
        callback('pool-name');
    };
    var server = require('wesley').listen(3000).pool(pooling);
     
    server.on('connection', function(client, pool) {
     
        // Handle the client
        client.write('You\'ve just joined the ' + pool.name + ' pool.');
     
    });

    Inbound messages

    By default, a Wesley client will emit data for every message sent from the client. You can entirely replace this behaviour at your leisure.

    var inbound = function(data, emit) {
        emit('message', data);
    };
    var server = require('wesley').listen(3000).in(inbound);
     
    server.on('connection', function(client) {
     
        client.on('message', function(message) {
            // Handle the message
        });
     
    });

    This also means you could handle more complicated messages than simple strings.

    var inbound = function(json, emit) {
        var data = JSON.parse(json);
        emit('data', data);
    };
    var server = require('wesley').listen(3000).in(inbound);
     
    server.on('connection', function(client) {
     
        client.on('data', function(data) {
            // Handle the data
        });
     
    });

    Wesley clients inherit from EventEmitter2, so even more complex events can be listened to.

    var inbound = function(json, emit) {
        var data = JSON.parse(json);
        emit(['client', data.type], data);
    };
    var server = require('wesley').listen(3000).in(inbound);
     
    server.on('connection', function(client) {
     
        client.on(['client', 'message'], function(data) {
            // Handle data with `data.type === message`
        });
     
        client.on(['client', '*'], function(data) {
            // Handle all client data
        });
     
    });

    Outbound messages

    In much the same way as handling inbound messages, you can also handle outbound messages.

    var outbound = function(type, message, emit) {
        var packed = JSON.stringify{type:type, body:message};
        emit(packed);
    };
    var server = require('wesley').listen(3000).out(outbound);
     
    server.on('connection', function(client) {
     
        // Send data to the client
        client.write('message', 'Derp.');
     
    });

    Transports

    As Wesley is a web socket server, it uses a socket transport by default. You can create custom transports by extending wesley.Transport. It is the job of the transport to proxy events listened to by the client or server. Please see the documentation for more detail (Coming soon).

    Once you have a client, using it is simple.

    var wesley = require('wesley');
    var server = new wesley.Server([
        // An array of transports
        new CustomTransport()
    ]);
     
    server.on('connection', function(client, pool) {
     
        // Client wraps the the transport the connection came through
        client.write('Derp.');
     
    });

    Command line client

    I can tell you're super excited to start working on your web socket server. One thing you may find useful is a client to start interacting with. This command line client will hopefully give you what you need to get started.

    $ wesley --help
     
      Usage: wesley [options]
     
      Options:
     
        -h, --help                output usage information
        -V, --version             output the version number
        -u, --uri <string>        host address
        -p, --protocol <integer>  web socket protocol
     
      Default:
     
        wesley --uri ws://localhost:3000 --protocol 13

    Contributing

    I accept contributions to the source via Pull Request, but passing unit tests must be included before it will be considered for merge.

    $ make install
    $ make tests

    If you have Vagrant installed, you can build our dev environment to assist development. The repository will be mounted in /srv.

    $ vagrant up
    $ vagrant ssh
    cd /srv

    License

    The content of this library is released under the MIT License by Andrew Lawson.
    You can find a copy of this license at http://www.opensource.org/licenses/mit

    Keywords

    none

    Install

    npm i wesley

    DownloadsWeekly Downloads

    2

    Version

    0.3.5

    License

    none

    Last publish

    Collaborators

    • adlawson