{"id":17133712,"url":"https://github.com/mjc-gh/esper","last_synced_at":"2025-04-13T06:52:03.932Z","repository":{"id":138589421,"uuid":"62929810","full_name":"mjc-gh/esper","owner":"mjc-gh","description":"📻 Event Source powered by hyper written in Rust","archived":false,"fork":false,"pushed_at":"2018-07-24T01:30:28.000Z","size":41,"stargazers_count":49,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-10T19:32:48.058Z","etag":null,"topics":["event-source-server","http-server","hyper","rust","server-sent-events"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mjc-gh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-09T03:18:43.000Z","updated_at":"2024-11-24T06:03:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"91ddec3b-5c81-426a-a4b5-994a55b05897","html_url":"https://github.com/mjc-gh/esper","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjc-gh%2Fesper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjc-gh%2Fesper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjc-gh%2Fesper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjc-gh%2Fesper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mjc-gh","download_url":"https://codeload.github.com/mjc-gh/esper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248675455,"owners_count":21143767,"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":["event-source-server","http-server","hyper","rust","server-sent-events"],"created_at":"2024-10-14T19:42:50.088Z","updated_at":"2025-04-13T06:52:03.912Z","avatar_url":"https://github.com/mjc-gh.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"## esper\n\nEsper is a standalone Event Source /\n[Server Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) (SSE) broker. It is powered by the most excellent event\ndriven [hyper](https://github.com/hyperium/hyper) library.\n\n### Usage\n\nThere are two main routes provided by esper; one for subscribing and one\nfor publishing:\n\n- `GET /subscribe/:topic_id`\n  - When requested with a valid `topic_id`, this route will respond with\n    the Event Source content type and will leave the connection open.\nThe client is now subscribed for the given `topic_id` and will receive\nall published messages for this topic.\n\n- `POST /publish/:topic_id`\n  - When requested with a valid `topic_id`, this route will publish a\n    message to all subscribed clients. The entire POST body is\nconsidered to be the message payload. Thus, the POST data should be\nformatted like a server-sent event and include a `data` field with an\noptional `event` and `id` field.\n\nThe `:topic_id` is specified as the second part of the request path.\nThis ID must be alphanumeric characters only (case insensitive) and must\nbe between 8 and 64 characters in length. Further validation may be\nintroduced at a later time.\n\n### Authentication\n\nEsper uses JSON Web Tokens to ensure requests are legitimate. For tokens\nto be considered valid, they must include an `exp` field set to some\nfuture timestamp (in seconds as an integer) as well as a `sub` field set\nto the `topic_id`.\n\nAuthentication is available for both the subscribe and publish routes\nand is enabled by setting one or both environmental variables. These\nvariables are named `ESPER_SUBSCRIBER_SECRET` and `ESPER_PUBLISHER_SECRET`.\nIt is possible to enable just one kind of authentication by leaving the\nother secret undefined.\n\nAlso, please note that, the `/stats` route is protected by JWT using the\npublisher secret since this route is intended for developer use.\n\n### Examples\n\nHere is a quick example of what to expect from esper using `curl`.\nFirst, we subscribe a client to the topic `abcdef123`:\n\n```bash\ncurl -v -X GET http://localhost:3000/subscribe/abcdef123\n\u003e GET /subscribe/abcdef123 HTTP/1.1\n\u003e Host: localhost:3001\n\u003e\n\u003c HTTP/1.1 200 OK\n\u003c Content-Type: text/event-stream\n\u003c Date: Mon, 11 Jul 2016 20:27:53 GMT\n\u003c Transfer-Encoding: chunked\n\u003c\n```\n\nNext, using another shell, lets publish a message with `curl` to the\nsame topic:\n\n```bash\ncurl -v -X POST http://localhost:3000/publish/abcdef123 -d $'event:\ntesting\\ndata: {some:\"data\"}'\n\u003e POST /publish/abcdef123 HTTP/1.1\n\u003e Host: localhost:3001\n\u003e Content-Length: 36\n\u003e Content-Type: application/x-www-form-urlencoded\n```\n\nNow if we go back to the first subscribed `curl` client, we will see the\nfollowing output:\n\n```bash\nevent: testing\ndata: {\"some\":\"data\"}\n```\n\nWe can also subscribe using the `EventSource` object in the browser.\nIn fact, esper is mainly designed for this use case!\n\nA quick example use some JavaScript would be as follows:\n\n```javascript\nvar evtSource = new EventSource('localhost:3000/subscribe/abcdef123');\n\nevtSource.onmessage = function(evt) {\n    console.log(evt.data);\n};\n```\n\nThere you have it, the essence of esper!\n\n\n### Building\n\nEsper can be built with stable Rust and the `cargo` command-line tool\n```bash\ngit clone https://github.com/mikeycgto/esper.git \u0026\u0026 cd esper\ncargo build --release \n```\n\n### Deploying\n\nEsper ships as a standalone executable with a small set of command-line\noptions. Here is esper's help screen for more details on the supported\noptions:\n\n```\n$ esper --help\nesper - Event Source HTTP server, powered by hyper.\n\nUsage:\n  esper [--bind=\u003cbind\u003e] [--port=\u003cport\u003e] [--threads=\u003cst\u003e]\n  esper (-h | --help)\n  esper --version\n\nOptions:\n  -h --help          Show this screen.\n  --version          Show version.\n  -b --bind=\u003cbind\u003e   Bind to specific IP [default: 127.0.0.1]\n  -p --port=\u003cport\u003e   Run on a specific port number [default: 3000]\n  -t --threads=\u003cst\u003e  Number of server threads [default: 2].\n  --no-auth          Run without JWT authentication.\n```\n\n### Docker\n\nEsper can run in docker container\n\n#### Create docker image and build\n```\ngit clone https://github.com/mikeycgto/esper.git \u0026\u0026 cd esper\ndocker build -t unique-image-name .\n```\n\n#### Run in interactive mode (twice CTRL+C for exit)\n```\ndocker run -it -p 3000:3000 unique-image-name\n```\n\n#### Run in background (Daemon)\n\n```\n# First launch\ndocker run -d --name esper_server_name -p 3000:3000\n\n# Stop\ndocker stop esper_server_name\n\n# Start\ndocker start esper_server_name\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjc-gh%2Fesper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmjc-gh%2Fesper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjc-gh%2Fesper/lists"}