rf-api-websocket

    0.2.3 • Public • Published

    rf-api-websocket

    rf-api implementation for RPC over websockets using JSON messages with optional ACL.

    ws server

    • Uses express server instance
    • Websocket communication service
    • Allows safe RPC
    • Uses JSON messages

    ws methods

    addHandler

    Add a simple callback handler. Errors can be signalled via exceptions Any previous handler with the same func name will be replaced.

    services.addHandler (funcName, callback, acl = {})
    • funcName The name of the handler. In order for the handler to be called, this needs to be used in the func attribute of the received websocket message.
    • callback The handler function(msg, responseCallback(msg))
    • acl Optional ACD configuraton

    addPromiseHandler

    Add a promise callback handler that either resolves to null (no response) or to response data and signals exceptions via rejection (logged, no response. Any previous handler with the same func name will be replaced.

    services.addPromiseHandler (funcName, genPromise, acl = {})
    • funcName The name of the handler. In order for the handler to be called, this needs to be used in the func attribute of the received websocket message.
    • callback The handler function(msg, responseCallback(msg))
    • acl Optional ACD configuraton

    sendObj

    services.sendObj (ws, obj)

    TODO: integrate callbackID maybe one raw send method, and one preconfigured (default to use)

    broadcast

    Send the given object to ALL the currently connected websockets NOTE: This sends the object as-is.

    services.broadcast (obj)

    Getting started

    start the package

    When the module is started, the websocket server and handler is automatically registered against the HTTP server. You dont need to start the server manually!

     
     
    // prepare backend
    var config = require('rf-config').init(__dirname); // config
    var http = require('rf-http').start({ // webserver
       pathsWebserver: config.paths.webserver,
       port: config.port
    });
    var API = require('rf-api').start({app: http.app}); // prepare api
    var mongooseMulti = require('mongoose-multi'); // databases
    var db = mongooseMulti.start(config.db.urls, config.paths.schemas);
     
     
    db.global.mongooseConnection.once('open', function () {
     
       // optional: start access control; has to be done before starting the websocket
       require('rf-acl').start({
          API: API,
          db: db,
          app: http.app,
          sessionSecret: dbSettings.sessionSecret.value
       });
     
       // start websocket connection;
       require('rf-api-websocket').start({API: API, http: http});
     
       // start requests
       API.startApiFiles(config.paths.apis, function (startApi) {
          startApi(db, API, services);
       });
    });
     
     

    Use Websocket requests

    Websocket messages have the form: {func: "", data: {...}, token: ""} Any other attributes are copied to the response

    Register a handler like this:

    API.onWSMessage("myfunc", (msg, respondWS, userInfo) => {
        // userInfo contains the object extracted from the JWT (or {} if no token was supplied)
        // If the user does not have the required permissions or the message is malformed,
        // this function is not called but instead an error msg is sent!
        if(!userInfo.isAdmin) {
          return false;
        }
        // Handle message (msg is .data of the original message)
        console.log(msg.foobar)
        // Then send response. Convention is to have an err attribute
        respondWS({err: null, info: "It works"});
        // NOTE: You can call respondWS multiple times if required!
    }, {}) // Empty ACL => no auth required

    See the rf-acl package for documentation about the ACL syntax

    If you are using Promises, use this syntax

    API.onWSMessagePromise("myfunc", (msg, respondWS, userInfo) => {
      return new Promise((resolve, reject) => {
        if(!userInfo.isAdmin) {
          return reject("nope"); // Will send {err: "nope"}
        }
        return resolve({"foo": "bar"}); // will send {err: null, "foo": "bar"}
      });
    }, {}) // Empty ACL => no auth required

    Development

    Install the dev tools with

    npm install

    Then you can runs some test cases and eslint with:

    npm test

    Generate Docs:

    npm run-script doc

    To Do

    • get the everything running

    Legal Issues

    • License: MIT
    • Author: Rapidfacture GmbH

    Keywords

    none

    Install

    npm i rf-api-websocket

    DownloadsWeekly Downloads

    8

    Version

    0.2.3

    License

    MIT

    Unpacked Size

    24.4 kB

    Total Files

    5

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar