Neglected Parking Meter

    dwsps

    1.0.1 • Public • Published

    dwsps

    distributed websocket publish/subscribe

    CircleCI npm

    dwsps is a distributed nodejs pub/sub system. It uses websockets to transmit messages between client and server, and between peered servers.

    Topics

    dwsps uses a heirarchical topic system for client subscriptions, each level divided by a full-stop .. For example, a client could subscribe to the topic news.uk. They would then recieve messages published to news.uk, news.uk.london, news.uk.birmingham etc. but not from news.fr or news.de.

    Note: if a client is subscribed to a parent topic and a sub-topic of the parent, unsubscribing from the parent topic will not also unsubscribe the client from the sub-topic. Each subscription must be unsubscribed from explicitly.

    Messages

    Messages are JSON format and look like the following:

    {
      "type": "publish",
      "timestamp": "2020-01-21T17:03:13.625Z",
      "topic": "news.uk",
      "context": "news",
      "message": "Hello news.uk channel!"
    }
    
    • topic lets a client know where the message was published to
    • context lets a client know why they are receiving a certain message - in this instance the client is subscribed to news, where they received it, but not news.uk, where it was sent.
    • message can be any valid JSON data

    Acknowledgements

    When a client performs an action, the server will send an acknowledgment in reply if it received the message and executed the action correctly. These can be listened for with the client ack event.

    Ack messages look like this:

    {
      "type": "ack",
      "action": "subscribe",
      "timestamp": "2020-01-22T15:44:04.674Z",
      "topic": "news"
    }
    

    Distribution

    Multiple dwsps servers can be peered with one another to create a distributed network. Once servers are peered, then a message published to one server will also be published to all servers, and delivered to their own subscribed clients respectively. Subscribed clients are not replicated between servers, instead held in memory on a per server basis.

    Messages that were forwarded from another server will also contain a fromPeerServer: true flag.

    Note: adding Server A as a peer of Server B will not enable 2-way communication: B will forward messages to A but not vice versa. Server B must also be added as a peer of Server A. See example.js for an example of peering servers.

    Usage

    Basic server example

    const PSServer = require('dwsps/server')
     
    const server = new PSServer({ port: 8000 })
     
    server.on('subscribe', (topic, client) => {
      console.log(`${client} subscribed to ${topic}`)
    })

    Basic client example

    In this example, an event listener is used to receive all messages from every topic the client is subscribed to.

    const PSClient = require('dwsps/client')
    //            or require('dwsps')
     
    const client = new PSClient('ws://localhost:8000')
     
    // Must wait for client to establish connection before performing actions
    client.on('open', () => {
      client.subscribe('news')
      client.publish('news', 'Hello news channel!')
      client.publish('news.uk', 'Hello news.uk channel!')
    })
     
    // Log acknowledgments from the server
    client.on('ack', ack => {
      console.log(ack)
    })
     
    // Log messages received by the client
    client.on('message', message => {
      console.log(message)
    })

    If you only want to take action on certain received messages, you can either:

    • Implement this yourself using the event listener method and parsing the message topic, or
    • Pass a callback function to the subscribe method which will only be called when a message is received matching that particular subscription.
    const PSClient = require('dwsps/client')
     
    const client = new PSClient('ws://localhost:8000')
     
    // Create a callback function that will be called when the client receives a
    // message matching the topic `news`.
    const newsHandler = message => {
      console.log(message)
    }
     
    // Must wait for client to establish connection before performing actions
    client.on('open', () => {
      client.subscribe('news', newsHandler)
      client.publish('news', 'Hello news channel!')
    })

    License

    MIT. See LICENSE.

    Keywords

    none

    Install

    npm i dwsps

    DownloadsWeekly Downloads

    7

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    18.4 kB

    Total Files

    7

    Last publish

    Collaborators

    • tdjsnelling