{"id":22681802,"url":"https://github.com/realizehit/realizehit","last_synced_at":"2025-04-12T17:09:56.026Z","repository":{"id":32369193,"uuid":"35945361","full_name":"realizehit/realizehit","owner":"realizehit","description":"an enhanced and scalable uni-directional websocket system for your project","archived":false,"fork":false,"pushed_at":"2016-01-26T16:50:33.000Z","size":45,"stargazers_count":31,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2023-12-26T13:11:23.395Z","etag":null,"topics":["client","pubsub","server","service","websocket"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/realizehit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-20T12:03:55.000Z","updated_at":"2021-03-15T12:51:16.000Z","dependencies_parsed_at":"2022-08-28T04:00:57.254Z","dependency_job_id":null,"html_url":"https://github.com/realizehit/realizehit","commit_stats":null,"previous_names":[],"tags_count":2,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realizehit%2Frealizehit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realizehit%2Frealizehit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realizehit%2Frealizehit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realizehit%2Frealizehit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/realizehit","download_url":"https://codeload.github.com/realizehit/realizehit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228956808,"owners_count":17997596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","pubsub","server","service","websocket"],"created_at":"2024-12-09T20:14:07.519Z","updated_at":"2024-12-09T20:14:08.190Z","avatar_url":"https://github.com/realizehit.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"http://github.com/realizehit/realizehit\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/realizehit/presskit/master/logo/icons/512x512/icon_g.png\" alt=\"realizehit logo\" align=\"left\" width=96px /\u003e\n\u003c/a\u003e\n\n# realizehit [![Build Status](https://travis-ci.org/realizehit/realizehit.svg?branch=master)](https://travis-ci.org/realizehit/realizehit)\n\n**an enhanced and scalable uni-directional websocket system for your project**\n\n```\n+--------+    +--------+    +--------+    +--------+    +--------+\n| API    | -\u003e | API    | -\u003e | Redis  | -\u003e | WS     | -\u003e | WS     |\n| Client |    | Server |    | Server |    | Server |    | Client |\n+--------+    +--------+    +--------+    +--------+    +--------+\n+Scallable    +Scallable    +Scallable    +Scallable    +Scallable\n\n// Pub/Sub example case under the hood, since the first connecting stage:\n\n1. API Client from within your app connects with one of the available API servers;\n2. WS Client on your frontend connects with one of the available WS servers;\n3. WS Client asks WS Server to subscribe into `{ \"foo\": \"bar\" }`;\n4. WS Server creates a Subscription based on pattern { foo:bar } and sets it as\n   active, which will also make WS Server to subscribe to `Redis`;\n5. WS Server responds to WS Client confirming it would now receive payloads\n   from the requested subscription;\n6. Your app needs to send a payload to `{ \"foo\": \"bar\" }` because `foo`\n   went to a `bar`, using API Client, it sends the payload `drunk`;\n7. API Server handles the request and publishes it to Redis Server;\n8. WS Server receives payload **BECAUSE IT HAS A CLIENT NEEDING IT**, which means\n   other servers on the network won't even receive the message if they don't have\n   clients that need it. It handles the payload directly to the respective\n   subscription, and it will route the payload to their clients.\n9. WS Client receives the payload and routes it to respective Subscription.\n```\n\n## Current development status: Help wanted for building clients for other languages!\n\n**We need your help to write clients on other languages!!**\n\n* [x] [Websocket Server](https://github.com/realizehit/server-ws)\n* [x] [API Server](https://github.com/realizehit/server-api)\n* [x] [JS API Client](https://github.com/realizehit/client-api.js)\n* [x] [JS Websocket Client](https://github.com/realizehit/client-ws.js)\n* [ ] PHP API Client\n* [ ] PHP Websocket Client\n* [ ] Python API Client\n* [ ] Python Websocket Client\n* [ ] Ruby API Client\n* [ ] Ruby Websocket Client\n* [ ] JAVA API Client\n* [ ] JAVA Websocket Client\n* [ ] Perl API Client\n* [ ] Perl Websocket Client\n* [ ] Go API Client\n* [ ] Go Websocket Client\n\nWant to contribute with your knowledge? [Contact me by email](mailto:jose.moreira@findhit.com)\n\n## History\n\nSince [findhit](https://www.findhit.com/) was developed it had a lot of realtime communication dependencies  \nwith web-clients.\n\nAt first development stage we relied on an excellent realtime service that you\nmay already know: [Pusher](http://pusher.com).\n\n[Pusher](http://pusher.com) is wonderful for pub:sub service for stabilish a\nweb-socket based communication, if you could keep on the **channel**, **event**\nmodel.\n\nAfter a couple months using [Pusher](http://pusher.com), we decided to create\nour own software for communicate with clients, on top of\n[Socket.IO](http://socket.io/) (later was refactored to use\n[Engine.IO](https://github.com/Automattic/engine.io) instead).\nThat software relied on a similar way WebSocket API, where you could listen on\na channel and an event.\n\nEverything was great until our first structure problems appeared, we had a way\nto send individual messages for all user's devices or target only one of them,\nand some other interesting features, but a bigger one was missing: we relied on\n**client/event** and we have to refactor it anytime we wanted to add another\nfilter, and thats bad practice and also insane...\n\nThats when **realizehit** was born, a rewrite of our internal comm library with\nsupport for:\n\n* Custom filters\n* Identification capabilities trought HTTP Headers\n    * This allow us to identify static things per request, such as `user`,\n      `device` and `zone`.\n    * That enhances our security since we handle them on the `load-balancer`. If\n      you want to use this feature, please make sure to implement it as we do in\n      order to avoid HTTP Headers injection from BlackHats.\n\n\n\n## Requirements\n\nSince **realizehit** is a stateless service, we must have a `redis` server running\nsomewhere.\n\n## Usage\n\n### With individual NPM packages\n\n#### Creating an API and WS Server on the same port\n\n```bash\nnpm i --save realizehit-server-api realizehit-server-ws\n```\n\n```javascript\nvar APIServer = require( 'realizehit-server-api' )\nvar WSServer = require( 'realizehit-server-ws' )\nvar http = require( 'http' )\n\nvar httpServer = http.createServer().listen( 8080 )\n\nvar websocketServer = new WSServer({ httpServer: httpServer })\nvar apiServer = new APIServer({ httpServer: httpServer })\n```\n\n[more about Web Socket Server](https://github.com/realizehit/server-ws)\n\n[more about API Server](https://github.com/realizehit/server-api)\n\n#### Subscribing over WebSocket Server using WebSocket Client\n\n```bash\nnpm i --save realizehit-client-ws\n```\n\n```javascript\nvar WSClient = require( 'realizehit-client-ws' )\nvar client = new WSClient( 'ws://realizehit.example.com/' )\n\n// Publish something cool\nclient.subscribe({ kind: 'news', channel: 'CNN' })\n    .on( 'subscribed', function () {\n        console.log( 'yolo!!1' )\n    })\n    .on( 'payload', function ( payload ) {\n        console.log( payload ) // will log payloads from channel:CNN|kind:news\n    })\n    .on( 'unsubscribed', function () {\n        console.log( 'ohno!!1' )\n    })\n\n// Save subscription instead of chaining\nvar subscription = client.subscribe({ foo: 'bar' })\n\nif ( subscription.subscribing() ) {\n    subscription.once( 'subscribed', function () {\n        subscription.unsubscribe()\n    })\n}\n\n```\n\n[more about WS JS Client](https://github.com/realizehit/client-ws.js)\n\n\n#### Publishing over API Server using API Client \n\n```bash\nnpm i --save realizehit-client-api\n```\n\n```javascript\nvar APIClient = require( 'realizehit-client-api' )\nvar client = new APIClient( 'https://realizehit.example.com/' )\n\n// Publish something cool\nclient.publish(\n    // On\n    {\n        kind: 'news',\n        channel: 'CNN'\n    },\n    {\n        id: 'deeznuts',\n        title: 'deez nuts went viral',\n        body: 'this might seem crazy, but right now I am lazy to write some textzy'\n    }\n)\n\n// Callbacks? I promise not!!\nclient\n.publish({ foo: 'bar' }, 'amazing' )\n.then(function () {\n    console.log( 'I am a dummy message, just to warn everything went ok' )\n})\n.catch(function ( err ) {\n    console.log( 'Dope!!1 Simpsons error here' )\n})\n```\n\n[more about API JS Client](https://github.com/realizehit/client-api.js)\n\n\n#### Publishing directly to Redis\n\n```bash\nnpm i --save realizehit-publisher\n```\n\n```javascript\nvar Publisher = require( 'realizehit-publisher' )\n\nvar publisher = new Publisher( 'redis://redis-host:6379' )\n\n// Publish a payload into { foo: 'bar' } subscription\npublisher.publish(\n    { foo: 'bar' },\n    'Hello world'\n)\n```\n\n[more about publisher](https://github.com/realizehit/publisher)\n\n\n### Run with Docker\n\n```bash\ndocker run -d --name=redis redis\ndocker run -d \\\n    --name=realizehit-server \\\n    -p 8080:8080 \\\n    -e REDIS_URI=\"redis://redis:6379\" \\\n    --link redis:redis \\\n    realizehit/realizehit\n```\n\n\n## Other repositories directly related with this\n\n### Shared libraries\n\n#### [pattern-to-id](https://github.com/realizehit/pattern-to-id) [![Build Status](https://travis-ci.org/realizehit/pattern-to-id.svg?branch=master)](https://travis-ci.org/realizehit/pattern-to-id)\nHandles different pattern definition conversion into an unique hash-based id.\n\n#### [subscription](https://github.com/realizehit/subscription) [![Build Status](https://travis-ci.org/realizehit/subscription.svg?branch=master)](https://travis-ci.org/realizehit/subscription)\nSubscription Class definition, it has been used as a parent Subscription\nclass on other repos.\n\n#### [publisher](https://github.com/realizehit/publisher) [![Build Status](https://travis-ci.org/realizehit/publisher.svg?branch=master)](https://travis-ci.org/realizehit/publisher)\nPublishes payloads directly into a **redis** server. It should be only used\nwhen you don't want/need to deploy an API server. It doesn't have the same\nnaming pattern as clients do because we don't plan to make it available on\nother languages, since probably its more secure to make them pass over\nthe API server.\n\n### Servers\n\n#### [server-api](https://github.com/realizehit/server-api) [![Build Status](https://travis-ci.org/realizehit/server-api.svg?branch=master)](https://travis-ci.org/realizehit/server-api)\nHandles payloads publishment and in a near future it would also be used to\nfetch metrics from other services.\n\nBasically it is the bridge between Api Clients and Redis.\n\n#### [server-ws](https://github.com/realizehit/server-ws) [![Build Status](https://travis-ci.org/realizehit/server-ws.svg?branch=master)](https://travis-ci.org/realizehit/server-ws)\nHandles clients connections, client \u0026 subscription relation management,\nredis sub based on active subscriptions and so on.\n\nBasically it is the bridge between Redis and WebSocket clients.\n\n### Javascript Clients\n\n#### [client-api.js](https://github.com/realizehit/client-api.js) [![Build Status](https://travis-ci.org/realizehit/client-api.js.svg?branch=master)](https://travis-ci.org/realizehit/client-api.js)\n#### [client-socket.js](https://github.com/realizehit/client-ws.js) [![Build Status](https://travis-ci.org/realizehit/client-ws.js.svg?branch=master)](https://travis-ci.org/realizehit/client-ws.js)\n\n### Others\n\nHave you ported a client into another language? PR us and we will publish them\nhere! :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealizehit%2Frealizehit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frealizehit%2Frealizehit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealizehit%2Frealizehit/lists"}