Nonstop Pajama Models

    token-sockjs-client

    3.0.2 • Public • Published

    Token Sockjs Clients

    The client libraries for node-token-sockjs. These modules provide additional websocket functionality on top of sockjs. If required in a node environment this module will export the node.js client library. To access the browser version require the browser client file directly.

    Build Status

    Browser Client

    The browser client does not require any external dependencies other than sockjs.

    The Azuqua CDN also hosts a minified copy of each version.

    <script src="//cdnjs.cloudflare.com/ajax/libs/sockjs-client/1.1.1/sockjs.min.js"></script>
    <script src="//d78vv2h34ll3s.cloudfront.net/tokensockjs-3.0.1.min.js"></script>
    

    API Overview

    Initialization

    The TokenSocket constructor accepts two objects as arguments, options and actions. Neither are required.

    Options

    • host - The hostname of the server. If the protocol is withheld the socket will attempt to connect with the same protocol used by the browser to fetch the page. The module will fall back to jsonp token requests for cross domain requests.
    • tokenPath - The URL path used to request a token. This must match the server's configuration. The default value matches the default value the server uses.
    • socketPrefix - The prefix of the routes owned by the sockjs server. This must match the server's configuration. The default value matches the default value the server uses.
    • reconnect - Whether or not this module should automatically reconnect if the websocket connection closes. Default value is true.
    • authentication - Any extra authentication data to be sent to the server upon a token request. This object will be form encoded and sent as URL parameters. The browser will automatically send your cookies.
    • sockjs - An object containing any valid sockjs configuration changes.
    • ping - An integer indicating the frequency in milliseconds that the client should wait between ping requests. If this property is undefined the client will not make automatic ping requests. This can be useful for maintaining open connections across load balancers or proxies that close unused connections.

    Actions

    The actions argument is an optionally nested object that maps keys to functions. The server will be able to call any of these functions via the RPC interface. The actions can also be modified later with the TokenSocket.register() function.

    var options = {
        host: "https://yourserver.com",
        tokenPath: "/socket/token",
        socketPrefix: "/sockets",
        reconnect: true,
        authentication: {
            foo: "bar"
        },
        // maybe modify sockjs options...
        sockjs: {
            transports: ["xhr-polling"]
        }
    };
    
    var actions = {
    
        ping: function(data, callback){
            callback(null, data);
        },
    
        nested: {
            foo: function(data, callback){
                callback(null, "foo");
            }
        }
    
    };
    
    var socket = new TokenSocket(options, actions);
    
    // when the socket is connected and authenticated the ready function will be called
    socket.ready(function(error){
        if(error)
            console.log("Error creating websocket!", error);
    });
    
    // it's also possible to hook into the reconnection event
    socket.onreconnect(function(error){
        if(error)
            console.log("Error reconnecting websocket!", error);
    });
    
    

    RPC Interface

    This module supports a bidirectional RPC interface between the server and client. This means the client can issue calls to the server and the server can issue calls to the client with a simple function call/callback interface. The examples here will show how to use the RPC API surface from the client. See the server docs for examples of RPC functions going in the other direction.

    // issue remote procedure calls to the server
    socket.rpc("echo", { foo: "bar" }, function(error, resp){
        console.log("Response: ", error, resp);
    });
    
    // issue remote procedure calls to a nested controller on the server
    socket.rpc("something.nested", { foo: "bar" }, function(error, resp){
        console.log("Response: ", error, resp);
    });
    
    // it's also possible to modify the socket's available actions
    // this will overwrite any current actions, to modify them in place change socket.actions directly
    socket.register({
        echo: function(data, callback){
            callback(null, data);
        }
    });
    

    Publish - Subscribe Interface

    Sockets can also subscribe and unsubscribe from channels, publish messages on channels, and broadcast messages on all channels.

    Handle Messages on Channels

    In order to handle pub/sub messages on channels sockets need to declare a function to be executed when a message is received.

    socket.onmessage(function(channel, message){
        console.log("Got message on channel!", channel, message);
    });
    

    Subscribe to a Channel

    socket.subscribe("channel1");
    

    Unsubscribe from a Channel

    socket.unsubscribe("channel1");
    

    Publish on a Channel

    socket.publish("channel1", { foo: "bar" });
    

    Broadcast on all Channels

    socket.broadcast({ foo: "bar" });
    

    Close Socket

    socket.end(function(){
        console.log("Socket closed");
    });
    

    Event Emitter Interface

    The socket is now extended by an EventEmitter and currently emits three events. This interface can replace the earlier ready, onreconnect, and onmessage functions or can be used alongside them. In fact, those functions are now proxies for the event emitter. In order to make cleaning up registered listeners as easy as possible it would be ideal to switch entirely to this interface, however the old interface will remain in place until the next major release.

    • ready - Emitted when the socket is first initialized and authenticated. This will be called with an optional error object.
    • reconnect - Emitted when the socket reconnects after being disconnected. This will be called with an optional error object. If an error is provided the socket will automatically attempt to reconnect again after a few seconds.
    • message - Emitted when a message arrives on the publish-subscribe network. This will be called with the channel and message as arguments.
    socket.on("ready", function(error){
        // ...
    });
    
    socket.on("reconnect", function(error){
        // ...
    });
    
    socket.on("message", function(channel, message){
        // ...
    });
    

    The uncompressed development version of the browser client does not ship with the EventEmitter dependency. Please use the minified version from the CDN or this repository for a full build with all dependencies.

    Server Client

    The server client is backed by sockjs-client-ws and will only use the websocket protocol.

    API Overview

    The API surface to the Node.js version is identical to the browser version with a few minor changes. First, the constructor options argument now requires a "host" property set to the hostname of the TokenSocket server and optionally accepts an associated "port" property. Additionally, the constructor no longer accepts a sockjs configuration object on the options argument. Other than those two initialization changes the functionality is identical to the browser version.

    Build and Test

    To tinker with the code or to build minified versions of the browser client run the grunt tasks. This module uses Mocha, Chai, Sinon, and Phantomjs for testing. The default grunt task will clean, lint, test, and minify the included modules.

    git clone git@github.com:azuqua/token-sockjs-client
    cd token-sockjs-client
    npm install
    grunt
    

    Install

    npm i token-sockjs-client

    DownloadsWeekly Downloads

    27

    Version

    3.0.2

    License

    MIT

    Last publish

    Collaborators

    • azuqua