{"id":15817062,"url":"https://github.com/numminorihsf/herald-client","last_synced_at":"2025-04-01T04:32:52.367Z","repository":{"id":31160434,"uuid":"34720547","full_name":"NumminorihSF/herald-client","owner":"NumminorihSF","description":"Client lib for herald server","archived":false,"fork":false,"pushed_at":"2015-11-03T08:56:31.000Z","size":248,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-06T05:21:45.516Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NumminorihSF.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-04-28T09:12:34.000Z","updated_at":"2015-05-08T08:10:50.000Z","dependencies_parsed_at":"2022-08-25T04:20:36.048Z","dependency_job_id":null,"html_url":"https://github.com/NumminorihSF/herald-client","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NumminorihSF%2Fherald-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NumminorihSF%2Fherald-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NumminorihSF%2Fherald-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NumminorihSF%2Fherald-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NumminorihSF","download_url":"https://codeload.github.com/NumminorihSF/herald-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246586105,"owners_count":20801026,"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":[],"created_at":"2024-10-05T05:21:54.994Z","updated_at":"2025-04-01T04:32:52.347Z","avatar_url":"https://github.com/NumminorihSF.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"herald-client\n===========================\n\n**v1 is not backward compatible with v0** \n\nClient lib for herald server\n\nInstall with:\n\n    npm install herald-client\n\nDependencies:\n\n    crypt-maker\n\n\n[Documentation by jsDuck. Also in RUS](http://numminorihsf.github.io/herald). \n\n\n# Usage\n\nSimple example:\n\n```js\n\n    var hc = new (require('herald-client'))();\n        hc.on('error', function(error){\n            console.log('HC error:', error);\n        });\n    \n        setTimeout(function() {\n            hc.subscribe(\"channel1\", function (sendedBy, obj) {\n                console.error('chan1:', obj);\n            });\n            hc.subscribe(\"channel2\", function (sendedBy, obj) {\n                console.log('chan2:', sendedBy, obj);\n            });\n    \n    \n            setTimeout(function () {\n                hc.unsubscribe(\"channel1\", function(err){\n                    if (err) console.error('Error in unsubscribing', err);\n                });\n                setInterval(function(){\n                    hc.publish('channel1', 'C1: '+Math.random());\n                    hc.publish('channel2', 'C2: '+Math.random());\n                },10);\n            }, 1000);\n        }, 1000);\n        process.on('SIGINT', function(){\n            hc.close();\n            process.exit();\n        });\n        process.on('SIGTERM', function(){\n            hc.close();\n            process.exit();\n        });\n        \n```\n\nIn this example hc will try connect to `127.0.0.1:8765`.\n\n# Methods\n\n## new HeraldClient([options], [algorithm[, key]])\n\n`options` is an Object. May be `{}`. Contains properties:\n* `.logger` - Logger object - to log inner events\n* `.name` - String|Numeric - your application class identified. Default: `Math.floor(Math.random()*1000000)`\n* `.uid` - String|Numeric - your application unique identified. \nDefault: `name + '_' + Math.floor(Math.random()*1000000)`\n* `.messageMaker` - Object. Some module, that make and parse messages. See below. Default: `crypt-maker`\n* `.connect` - Object. Options for new.Socket.connect. Default: `{port: 8765}` \n \nSee [https://nodejs.org/api/net.html#net_net_connect_options_connectionlistener]\n(https://nodejs.org/api/net.html#net_net_connect_options_connectionlistener). Default: `{port:8765}`\n\nIf use `crypt-maker` and if `algorithm \u0026\u0026 algorithm !== 'no'` and no key passed to constructor - throws error.\n\n\n## hc.connect([options]) \n\nConnect to server. If options aren't passed, connect with last options.\nIf already connected - do nothing.\nOptions are:\n* `options` {Object} [optional] \n\nSupports the following properties:\n  * `port` {Number} [optional]\n  * `host` {String} [optional]\n  * `backlog` {Number} [optional]\n  * `path` {String} [optional]\n  * `exclusive` {Boolean} [optional]\n\nFor all info about this see: See \n[https://nodejs.org/api/net.html#net_net_connect_options_connectionlistener]\n(https://nodejs.org/api/net.html#net_net_connect_options_connectionlistener).\n\n\n\n## hc.close([callback])\n\nStops the client and close connect from accepting new connections and keeps existing\nconnections.\n\n* `callback` {Function} [optional]\n\n\n## hc.subscribe(eventName, callback)\n\nCreate subscribing on server. Then event emitted - call `callback(senderIdentifier, bodyOfMessage)`. \nIf error on subscribe `hc` will emit `'error'` event.\n\n* `eventName` {String} - name of event\n* `callback` {Function}\n\n\n## hc.unsubscribe(eventName[, callback])\n\nUnsubscribe from event with name. If no `callback` and error on unsubscribe `hc` will emit `'error'` event.\n\n* `eventName` {String} - name of event\n* `callback` {Function} [optional]\n\n\n## hc.publish(eventName, body[, callback])\n\nPublish event on server. If no `callback` and error on publish `hc` will emit `'error'` event.\n\n* `whom` {String} - application name to send.\n* `eventName` {String} - name of event\n* `eventBody` {String | Object} - body of event\n* `callback` {Function} [optional]\n\n\n\n## hc.whisper(whom, body[, header]) removed\n\n\n\n## hc.whisp(whom, eventName, eventBody, callback)\n\nSend event message to one application with name. \n(Will send to one instance, but not for all application with name).\n\n* `whom` {String} - application name to send.\n* `eventName` {String} - name of event\n* `eventBody` {String | Object} - body of event\n* `callback` {Function}\n\n\n\n## hc.whispUid(whomUid, eventName, eventBody, callback)\n\nSend event message to one application with uid.\n\n* `whomUid` {String} - application name to send.\n* `eventName` {String} - name of event\n* `eventBody` {String | Object} - body of event\n* `callback` {Function}\n\n\n## hc.rpc(whom, action[, options][, callback])\n\nTry call procedure on application with name. \n(Will send to one instance, but not for all application with name).\n\n* `whom` {String} - application name to send.\n* `action` {Object} - action object, that you want to call at application.\n* `action.name` {String} - action name, that you want to call at application.\n* `action.args` {Object | String | Number | Array} - arguments for action. `!!action.args` should return true.\n* `options` {Object} [optional] Options for rpc. *not ready yet*.\n* `callback` {Function} [optional]\n\n\n\n## hc.rpcUid(whomUid, action[, options][, callback])\n\nTry call procedure on application with uid.\n\n* `whomUid` {String} - application name to send.\n* `action` {Object} - action object, that you want to call at application.\n* `action.name` {String} - action name, that you want to call at application.\n* `action.args` {Object | String | Number | Array} - arguments for action. `!!action.args` should return true.\n* `options` {Object} [optional] Options for rpc. *not ready yet*.\n* `callback` {Function} [optional]\n\n\n\n## hc.write(header, body[, options][, callback])\n\nSend some message to server. *At now ignored by server*\n\n* `header` {Object} - header of message to send.\n* `body` {Object|string} - body of message yo send.\n* `options` {Object} [optional] Options for rpc. *not ready yet*.\n* `callback` {Function} [optional]\n\n\n\n## hc.addRpcWorker(actionName, callback)\n\nAdd function to work with rpc calls.\n\n* `actionName` {String} - action name.\n* `callback` {Function} - function to call. See \n[doc](http://numminorihsf.github.io/herald/index.html#!/api/HeraldClient-method-remoteProcedure)\n\nReturns `true` if added or `false` if there was function with such name.\n\n\n## hc.removeRpcWorker(actionName)\n\nRemove function from work with rpc calls.\n\n* `actionName` {String} - action name.\n\nReturns `true` if was such function else returns `false`.\n\n\n\n\n## hc.unref()\n\nCalling `unref` on a client will allow the program to exit if this is the only\nactive client in the event system. If the server is already `unref`d calling\n`unref` again will have no effect.\nEvery success `.connect()` create new connection. That's why you should call `unref` again. \n\n## hc.ref()\n\nOpposite of `unref`, calling `ref` on a previously `unref`d server will *not*\nlet the program exit if it's the only server left (the default behavior). If\nthe server is `ref`d calling `ref` again will have no effect.\n\n\n# Events\n\n## 'ping'\n\nEmitted when a server send 'ping' event.\n\n## 'connect'\n\nEmitted when the socket has been connected to server.\n\n## 'close'\n\nEmitted when the socket closes. Note that if connections exist, this\nevent is not emitted until all connections are ended.\n\n## 'error'\n\n* {Error Object}\n\nEmitted when an error occurs.  The `'close'` event will be called directly\nfollowing this event.\n\n\n\n# Message format\n\nEvery message should has `header` and `body`.\nIf there is no `header` or `body` - message will not sent.\n\n\n## Authorize\n\n**Be careful** by default without any encrypt algorithm any can connect to your server if he know format.\n\nExample of message to authorize (without encrypt):\n\n```\n    '{\"rpc\":\"herald-server\",\"action\":\"authorize\",\"actionId\":7,\"name\":\"156512\",\n    \"uid\":\"156512_86835\",\"messId\":76688,\"retry\":5,\"timeout\":15000}\\r\\n\n     {\"args\":{\"wellKnown\":\"pHrAsE\",\"name\":\"156512\",\"uid\":\"156512_86835\",\"rand\":459}}\\r\\n\\r\\n' \n```\n\nIf there is some connection with same uid - will not authorize new connection and close it.\n\n\n\n## Message header format\n\nFields:\n* `messId` Number - id of message. Client set it automaticaly.\n* `name` String - connection name. Used for whispering and rpc. Client set it to HeraldClient.name.\n* `uid` String - connection uid. Used for whispering and rpc. Unique for every connect. Client set it to HeraldClient.uid.\n* `retry` Number [optional] - Count of retries of sending this message. If no field - will not retry.\n*Now it is ignored by server. Will work soon.*\n* `timeout` Number [optional] - Duration in ms to wait answer from client. If no field - will not retry.\n*Now it is ignored by server. Will work soon.*\n\nEvent:\n* `whisp` String [optional] - name of connection to send event message.\n* `whispUid` String [optional] - uid of connection to send event message.\n* `event` String - event name. If no `whisp` or `whispUid` sends to all subscribers.\n\nRPC:\n* `actionId` Number - id of action. Client set it automaticaly.\n* `action` String - name of action.\n* `rpc` String [optional] - name of connection to send rpc message.\n* `rpcUid` String [optional] - uid of connection to send rpc message.\n* `rpcRegExp` String|RegExp [optional] - regexp to find connections by name to send rpc message.\n\n\n## Message body format\n\nBody can by plain string, json, number or something else, except functions.\n\n## Message examples\n\nExamples shown without any encryption.\n\nRPC by client name message:\n```js\n     '{\"rpc\":\"applicationToCall\",\"action\":\"actionToCall\",\"actionId\":numberActionIdFromSender,\n     \"name\":\"nameOfSender\",\"uid\":\"uidOfSender\",\"messId\":numberMessageId}\\r\\n\n         {\"args\":{argsObject}}\\r\\n\\r\\n' \n```\n\nRPC by client UID message:\n```js\n     '{\"rpcUid\":\"applicationToCall\",\"action\":\"actionToCall\",\"actionId\":numberActionIdFromSender,\n     \"name\":\"nameOfSender\",\"uid\":\"uidOfSender\",\"messId\":numberMessageId}\\r\\n\n         {\"args\":{argsObject}}\\r\\n\\r\\n' \n```\n\nWhispering message:\n```js\n    '{\"whisp\":\"nameOfAppToWhisp\",\"event\":\"someSecretEvent\",\"name\":\"nameOfSender\",\"uid\":\"uidOfSender\",\n    \"messId\":numberMessageId}\\r\\n\"eventBody\"\\r\\n\\r\\n'\n```\n\nEvent message:\n```js\n    '{\"event\":\"someEvent\",\"name\":\"nameOfSender\",\"uid\":\"uidOfSender\",\"messId\":numberMessageId}\\r\\n\"eventBody\"\\r\\n\\r\\n'\n```\n\n# LICENSE - \"MIT License\"\n\nCopyright (c) 2015 Konstantine Petryaev\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumminorihsf%2Fherald-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnumminorihsf%2Fherald-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnumminorihsf%2Fherald-client/lists"}