{"id":28398387,"url":"https://github.com/primus/omega-supreme","last_synced_at":"2025-06-28T14:31:12.841Z","repository":{"id":17617102,"uuid":"20421231","full_name":"primus/omega-supreme","owner":"primus","description":"Omega supreme adds messaging between multiple primus servers. It needs a server address, spark id and message and the server will then send the correct message to the connected client.","archived":false,"fork":false,"pushed_at":"2023-01-02T20:19:38.000Z","size":184,"stargazers_count":17,"open_issues_count":1,"forks_count":9,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-06-04T05:09:55.941Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/primus.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":"2014-06-02T22:00:18.000Z","updated_at":"2023-01-02T20:19:42.000Z","dependencies_parsed_at":"2023-01-13T19:25:18.309Z","dependency_job_id":null,"html_url":"https://github.com/primus/omega-supreme","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/primus/omega-supreme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primus%2Fomega-supreme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primus%2Fomega-supreme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primus%2Fomega-supreme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primus%2Fomega-supreme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/primus","download_url":"https://codeload.github.com/primus/omega-supreme/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primus%2Fomega-supreme/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260638979,"owners_count":23040413,"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":"2025-06-01T04:38:34.357Z","updated_at":"2025-06-28T14:31:12.834Z","avatar_url":"https://github.com/primus.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Omega Supreme\n\n[![Version npm](https://img.shields.io/npm/v/omega-supreme.svg?style=flat-square)](https://www.npmjs.com/package/omega-supreme)[![CI](https://img.shields.io/github/actions/workflow/status/primus/omega-supreme/ci.yml?branch=master\u0026label=CI\u0026style=flat-square)](https://github.com/primus/omega-supreme/actions?query=workflow%3ACI+branch%3Amaster)[![Coverage Status](https://img.shields.io/coveralls/primus/omega-supreme/master.svg?style=flat-square)](https://coveralls.io/r/primus/omega-supreme?branch=master)\n\nKnown for his great strength and greater courage, Omega Supreme is the Autobots’\nlast line of defense against the Decepticons. He will stand unwaveringly against\noverwhelming odds, and although outwardly grim, he is known by those with enough\ninsight to actually relish the importance of his task – Omega knows that if he\nfalls, it is unlikely there will be any remaining Autobots to take his place,\nbut he would not have it any other way.\n\nIn Primus mode, Omega Supreme has an incredible configurability, is able to\nbroadcast a message with a single request and can distribute messages to single\nsparks. In place of his left hand, he is armed with authentication which can\npulverize any attacker.\n\nOr in plain English, `omega-supreme` allows you to broadcast messages to Primus\nusing a regular HTTP request. These messages can be broadcasted to every single\nconnection on the server, a single spark or an array of sparks. This allows\nother languages to easily write messages to your server without the need of\ncreating a complex architecture.\n\n## Installation\n\n```\nnpm install --save omega-supreme\n```\n\n## Adding Omega Supreme to Primus\n\nOmega Supreme should be added as a **plugin** in Primus. The plugin will also\nadd a `omega-supreme` middleware which will intercept the incoming HTTP requests\nand will take care of the actual distribution of the message to every single\nconnected client. Adding plugins in Primus is done using the\n`.plugin(name, plugin)` method. The options for the plugin can directly be added\nto the constructor of your Primus server so all the configuration of the server\nand the plugins is in one central location as illustrated in the example below:\n\n```js\n'use strict';\n\nvar Primus = require('primus'),\n  server = require('http').createServer();\n\nvar primus = new Primus(server, {\n  /* Add the options here, in the Primus's options */\n});\n\nprimus.plugin('omega-supreme', require('omega-supreme'));\n\nserver.listen(8080);\n```\n\nThere are various options available, they are all optional but we highly\nrecommend to change the `password` and `username` options to something unique.\nUser name and password are used to authenticate the HTTP requests containing the\ninformation to bradcast. The following options can be configured:\n\n- **method**: HTTP method we should respond to, defaults to `PUT`.\n- **password**: Password for basic authorization, defaults to `supreme`.\n- **username**: Username for basic authorization, defaults to `omega`.\n- **url**: Access path, defaults to `/primus/omega/supreme`.\n- **concurrently**: How many servers can we broadcast to at once, defaults to\n  `10`.\n\n### Messaging\n\nNow that you've added the `omega-supreme` plugin to your Primus server you can\ncommunicate/broadcast with it using plain HTTP requests. We make a couple\nassumptions to the data that is sent to the server:\n\n- The POST/PUT data is JSON encoded.\n- The request is made against the supplied URL option.\n- The request uses Basic Authentication with the supplied username and password.\n- The `msg` Property contains the data that needs to be sent to the connections.\n- The `sparks` Property can be an array of spark ids or a string which is the\n  spark id. If no `sparks` property is supplied we assume that the given message\n  needs to be broadcasted to every single connection on this server.\n\nWhen your message has been successfully processed by the server it returns a\nJSON object with some information:\n\n```js\n{\n  ok: true,\n  send: 10\n}\n```\n\nThe `send` property indicates the amount of connections we've written the\nmessage payload to. If your request has failed a 500 or 401 status code will be\nset and a slightly different JSON object will be returned:\n\n```js\n{\n  ok: false,\n  reason: 'invalid data structure'\n}\n```\n\n## Primus.forward\n\n```js\nprimus.forward(server, msg, [sparks], fn);\n```\n\nIn order to make the messaging even easier to use, `omega-supreme` adds a\n`primus.forward` method to your Primus server instance. It allows you to\nbroadcast messages to the supplied server. It will only write the message to the\nsupplied server if the supplied sparks are not on the current server.\n\nSending a message to a spark on a different server:\n\n```js\nprimus.forward(\n  'http://localhost:8080',\n  {\n    event: 'name'\n  },\n  'ad8a-280z-18',\n  function (err, data) {\n    // data.send = 1 if it was successful.\n  }\n);\n```\n\nSending to a group of sparks:\n\n```js\nprimus.forward(\n  'http://localhost:8080',\n  {\n    event: 'name'\n  },\n  ['ad8a-280z-18', 'y97x-42480-13' /* more spark.id's */],\n  function (err, data) {}\n);\n```\n\nOr just broadcasting by not supplying the optional sparks argument:\n\n```js\nprimus.forward(\n  'http://localhost:8080',\n  {\n    event: 'name'\n  },\n  function (err, data) {}\n);\n```\n\nIn all the examples above, we've sent an `event` packet. If you're using\n[`primus-emit`](https://github.com/primus/primus-emit) and you want to trigger\ncustom events you should use this format:\n\n```js\nprimus.forward('http://localhost:8080', { emit: [eventName, ...args] }, fn);\n```\n\nKeep in mind that you don't have to write event blobs, you can write anything\nyou want.\n\n## Customize the middleware behavior\n\nomega-supreme allows you to customize the behavior of the middleware that is\nadded with the plugin.\n\nTo define a custom logic, you can use the `middleware` option.\n\n```js\nprimus.options.middleware = middleware;\n```\n\nwhere `middleware` is a function which takes the following arguments:\n\n| Name   | Type     | Description                                                                                                            |\n| ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |\n| primus | Object   | The Primus server instance                                                                                             |\n| parse  | Function | The default parsing function has the following signature `parse(primus, buff, res)` where buff is the raw request body |\n| req    | Object   | The HTTP request                                                                                                       |\n| res    | Object   | The HTTP response                                                                                                      |\n| next   | Function | The next callback                                                                                                      |\n\n### Example\n\nThis example adds a custom header to the response.\n\n```js\nfunction middleware(primus, parse, req, res, next) {\n  var raw = '';\n\n  res.setHeader('omegamiddleware', 'true');\n\n  req.setEncoding('utf8');\n  req\n    .on('data', function data(chunk) {\n      raw += chunk;\n    })\n    .on('end', function end() {\n      parse(primus, raw, res);\n    });\n}\n```\n\n### Unofficial middleware\n\n#### [Omega Supreme Rooms Middleware](https://github.com/fadeenk/omega-supreme-rooms-middleware)\n\n[![Version npm](https://img.shields.io/npm/v/omega-supreme-rooms-middleware.svg?style=flat-square)](https://www.npmjs.com/package/omega-supreme-rooms-middleware)\n[![Build Status](https://img.shields.io/travis/fadeenk/omega-supreme-rooms-middleware/master.svg?style=flat-square)](https://travis-ci.org/fadeenk/omega-supreme-rooms-middleware)\n[![Dependencies](https://img.shields.io/david/fadeenk/omega-supreme-rooms-middleware.svg?style=flat-square)](https://david-dm.org/fadeenk/omega-supreme-rooms-middleware)\n[![Coverage Status](https://img.shields.io/coveralls/fadeenk/omega-supreme-rooms-middleware/master.svg?style=flat-square)](https://coveralls.io/r/fadeenk/omega-supreme-rooms-middleware?branch=master)\n\nThis middleware adds support for `primus-rooms` and automatically integrates\nwith `metroplex` if included.\n\n## License\n\n[MIT](LICENSE)\n\n![Omega Supreme](https://raw.githubusercontent.com/primus/omega-supreme/master/logo.jpg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimus%2Fomega-supreme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprimus%2Fomega-supreme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimus%2Fomega-supreme/lists"}