realizehit

an enhanced and scalable uni-directional websocket system for your project

+--------+    +--------+    +--------+    +--------+    +--------+
| API    | -> | API    | -> | Redis  | -> | WS     | -> | WS     |
| Client |    | Server |    | Server |    | Server |    | Client |
+--------+    +--------+    +--------+    +--------+    +--------+
+Scallable    +Scallable    +Scallable    +Scallable    +Scallable

// Pub/Sub example case under the hood, since the first connecting stage:

1. API Client from within your app connects with one of the available API servers;
2. WS Client on your frontend connects with one of the available WS servers;
3. WS Client asks WS Server to subscribe into `{ "foo": "bar" }`;
4. WS Server creates a Subscription based on pattern { foo:bar } and sets it as
   active, which will also make WS Server to subscribe to `Redis`;
5. WS Server responds to WS Client confirming it would now receive payloads
   from the requested subscription;
6. Your app needs to send a payload to `{ "foo": "bar" }` because `foo`
   went to a `bar`, using API Client, it sends the payload `drunk`;
7. API Server handles the request and publishes it to Redis Server;
8. WS Server receives payload **BECAUSE IT HAS A CLIENT NEEDING IT**, which means
   other servers on the network won't even receive the message if they don't have
   clients that need it. It handles the payload directly to the respective
   subscription, and it will route the payload to their clients.
9. WS Client receives the payload and routes it to respective Subscription.

Current development status: Help wanted for building clients for other languages!

We need your help to write clients on other languages!!

• Websocket Server
• API Server
• JS API Client
• JS Websocket Client
• PHP API Client
• PHP Websocket Client
• Python API Client
• Python Websocket Client
• Ruby API Client
• Ruby Websocket Client
• JAVA API Client
• JAVA Websocket Client
• Perl API Client
• Perl Websocket Client
• Go API Client
• Go Websocket Client

Want to contribute with your knowledge? Contact me by email

History

Since findhit was developed it had a lot of realtime communication dependencies
with web-clients.

At first development stage we relied on an excellent realtime service that you may already know: Pusher.

Pusher is wonderful for pub:sub service for stabilish a web-socket based communication, if you could keep on the channel, event model.

After a couple months using Pusher, we decided to create our own software for communicate with clients, on top of Socket.IO (later was refactored to use Engine.IO instead). That software relied on a similar way WebSocket API, where you could listen on a channel and an event.

Everything was great until our first structure problems appeared, we had a way to send individual messages for all user's devices or target only one of them, and some other interesting features, but a bigger one was missing: we relied on client/event and we have to refactor it anytime we wanted to add another filter, and thats bad practice and also insane...

Thats when realizehit was born, a rewrite of our internal comm library with support for:

• Custom filters
• Identification capabilities trought HTTP Headers
  • This allow us to identify static things per request, such as user, device and zone.
  • That enhances our security since we handle them on the load-balancer. If you want to use this feature, please make sure to implement it as we do in order to avoid HTTP Headers injection from BlackHats.

Requirements

Since realizehit is a stateless service, we must have a redis server running somewhere.

Usage

With individual NPM packages

Creating an API and WS Server on the same port

npm i --save realizehit-server-api realizehit-server-ws

var APIServer = require( 'realizehit-server-api' )
var WSServer = require( 'realizehit-server-ws' )
var http = require( 'http' )

var httpServer = http.createServer().listen( 8080 )

var websocketServer = new WSServer({ httpServer: httpServer })
var apiServer = new APIServer({ httpServer: httpServer })

more about Web Socket Server

more about API Server

Subscribing over WebSocket Server using WebSocket Client

npm i --save realizehit-client-ws

var WSClient = require( 'realizehit-client-ws' )
var client = new WSClient( 'ws://realizehit.example.com/' )

// Publish something cool
client.subscribe({ kind: 'news', channel: 'CNN' })
    .on( 'subscribed', function () {
        console.log( 'yolo!!1' )
    })
    .on( 'payload', function ( payload ) {
        console.log( payload ) // will log payloads from channel:CNN|kind:news
    })
    .on( 'unsubscribed', function () {
        console.log( 'ohno!!1' )
    })

// Save subscription instead of chaining
var subscription = client.subscribe({ foo: 'bar' })

if ( subscription.subscribing() ) {
    subscription.once( 'subscribed', function () {
        subscription.unsubscribe()
    })
}

more about WS JS Client

Publishing over API Server using API Client

npm i --save realizehit-client-api

var APIClient = require( 'realizehit-client-api' )
var client = new APIClient( 'https://realizehit.example.com/' )

// Publish something cool
client.publish(
    // On
    {
        kind: 'news',
        channel: 'CNN'
    },
    {
        id: 'deeznuts',
        title: 'deez nuts went viral',
        body: 'this might seem crazy, but right now I am lazy to write some textzy'
    }
)

// Callbacks? I promise not!!
client
.publish({ foo: 'bar' }, 'amazing' )
.then(function () {
    console.log( 'I am a dummy message, just to warn everything went ok' )
})
.catch(function ( err ) {
    console.log( 'Dope!!1 Simpsons error here' )
})

more about API JS Client

Publishing directly to Redis

npm i --save realizehit-publisher

var Publisher = require( 'realizehit-publisher' )

var publisher = new Publisher( 'redis://redis-host:6379' )

// Publish a payload into { foo: 'bar' } subscription
publisher.publish(
    { foo: 'bar' },
    'Hello world'
)

more about publisher

Run with Docker

docker run -d --name=redis redis
docker run -d \
    --name=realizehit-server \
    -p 8080:8080 \
    -e REDIS_URI="redis://redis:6379" \
    --link redis:redis \
    realizehit/realizehit

Other repositories directly related with this

Shared libraries

pattern-to-id

Handles different pattern definition conversion into an unique hash-based id.

subscription

Subscription Class definition, it has been used as a parent Subscription class on other repos.

publisher

Publishes payloads directly into a redis server. It should be only used when you don't want/need to deploy an API server. It doesn't have the same naming pattern as clients do because we don't plan to make it available on other languages, since probably its more secure to make them pass over the API server.

Servers

server-api

Handles payloads publishment and in a near future it would also be used to fetch metrics from other services.

Basically it is the bridge between Api Clients and Redis.

server-ws

Handles clients connections, client & subscription relation management, redis sub based on active subscriptions and so on.

Basically it is the bridge between Redis and WebSocket clients.

Javascript Clients

client-api.js

client-socket.js

Others

Have you ported a client into another language? PR us and we will publish them here! :)