{"id":27197694,"url":"https://github.com/preaction/mercury","last_synced_at":"2025-04-09T20:29:23.711Z","repository":{"id":56835169,"uuid":"43228547","full_name":"preaction/Mercury","owner":"preaction","description":"A message broker for WebSockets","archived":false,"fork":false,"pushed_at":"2018-03-15T20:04:53.000Z","size":172,"stargazers_count":10,"open_issues_count":15,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-06-18T17:06:58.810Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/preaction.png","metadata":{"files":{"readme":"README","changelog":"CHANGES","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-27T00:38:33.000Z","updated_at":"2022-08-23T02:01:53.000Z","dependencies_parsed_at":"2022-09-02T03:50:53.444Z","dependency_job_id":null,"html_url":"https://github.com/preaction/Mercury","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preaction%2FMercury","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preaction%2FMercury/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preaction%2FMercury/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preaction%2FMercury/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/preaction","download_url":"https://codeload.github.com/preaction/Mercury/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248106799,"owners_count":21048797,"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-04-09T20:29:22.928Z","updated_at":"2025-04-09T20:29:23.684Z","avatar_url":"https://github.com/preaction.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"=head1 SYNOPSIS\n\n    mercury broker [-l \u003clisten\u003e]\n\n=head1 DESCRIPTION\n\nThis is a message broker that enables some common messaging patterns over\nWebSockets.\n\nWebSockets are a powerful tool, enabling many features previously impossible,\ndifficult, or ugly for web developers to implement. Where once only an HTTP\nrequest could get data from a server, now a persistent socket can allow the\nserver to send updates without the client needing to specifically request it.\n\n=head2 Server-side Communication\n\nWebSockets do not need to be a communication channel purely between browser and\nserver. The Mojolicious web framework has excellent support for WebSockets.\nUsing that support, we can communicate between different server processes.\n\nThis solves the problem with client-to-client communication in a parallelized\nweb server where all clients may not be connected to the same server process.\nThe server processes can use a central message broker to coordinate and pass\nmessages from one client to another.\n\n=head2 Message Bus\n\nA message bus allows for all connected peers to send and receive messages in a\ngroup.\n\nRequesting a WebSocket from the URL C\u003c/bus/fry\u003e joins the peer-to-peer message\nbus topic C\u003cfry\u003e. All peers joined to the same topic will receive all the\nmessages published to that topic by other peers.\n\nThis is useful for sharing state changes between multiple peers, for example,\nin a forking web app server like L\u003cHypnotoad\u003e or L\u003cStarman\u003e.\n\n=head2 Pub/Sub Messaging\n\nThe pub/sub pattern allows for 1-to-many delivery of messages from one\npublisher to any number of active subscribers.\n\nRequesting a WebSocket from the URL C\u003c/sub/leela\u003e creates a subscription to the\ntopic C\u003cleela\u003e. Requesting a WebSocket from the URL C\u003c/pub/leela\u003e allows\nsending messages to the C\u003cleela\u003e topic, which are then received by all the\nsubscribers.\n\nTopics are heirarchical to allow for broad subscriptions without requring more\nsockets. A subscription to the topic C\u003cwong\u003e receives all messages published to\nthe topic C\u003cwong\u003e or any child topic like C\u003cwong/amy\u003e or C\u003cwong/leo\u003e.\n\nThis pattern is useful for keeping clients informed of backend processes,\ntapping into an event or logging stream.\n\n=head2 Push/Pull\n\nPush/pull deals out messages in a round-robin manner. Pushers send messages\nwhich are handled by a single puller.\n\nHandlers request WebSockets from the URL C\u003c/pull/bender\u003e. Senders request\nWebSockets from the URL C\u003c/push/bender\u003e. Senders send messages which will\nbe received by a single handler.\n\nThis pattern is useful for load balancing incoming updates, or creating\nprocessing pipelines using multiple push/pull endpoints.\n\n=head2 Example App\n\nIn C\u003cdevelopment\u003e mode (the default), the broker provides an example\napplication to test the messaging patterns.\n\nYou can change the mode by using the C\u003c-m\u003e flag to the L\u003cC\u003cmercury broker\u003e\ncommand|Mercury::Command::mercury::broker\u003e or the C\u003cMOJO_MODE\u003e environment\nvariable.\n\n=head1 CONFIGURATION\n\nYou can have an optional configuration file C\u003cmercury.conf\u003e in the current\nworking directory. The configuration file is a Perl hash, with the broker\nconfiguration in the C\u003cbroker\u003e key, like so:\n\n    # mercury.conf\n    {\n        broker =\u003e {\n            listen =\u003e \"http://*:4000\",\n            allow_origin =\u003e [\n                'example.com',\n            ],\n        },\n    }\n\nThe individual configuration keys are:\n\n=head2 listen\n\n    # mercury.conf\n    {\n        broker =\u003e {\n            listen =\u003e \"http://*:4000\",\n        },\n    }\n\nYou can set the default for the C\u003c-l|--listen\u003e option in the configuration\nfile.\n\n=head2 allow_origin\n\n    # mercury.conf\n    {\n        broker =\u003e {\n            allow_origin =\u003e [\n                'example.com',\n            ],\n        },\n    }\n\nInstead of CORS (used by Ajax), WebSockets send an C\u003cOrigin\u003e header with the\ninitial handshake. This header contains the protocol, host, and port used by\nthe page requesting the socket.\n\nAs a basic security measure, you can configure the allowed origin values with\nthe C\u003callow_origin\u003e configuration key. When this is set, only WebSocket\nhandshakes with an C\u003cOrigin\u003e header matching one of the values will be allowed.\nIf there is no C\u003cOrigin\u003e header, or the header does not match, the connection\nwill be denied with a C\u003c401 Unauthorized\u003e response.\n\nC\u003callow_origin\u003e key can be a single string, or an array of strings, containing\na string to match against the incoming C\u003cOrigin\u003e header. The C\u003c*\u003e character is\na wildcard.\n\nEach of the following examples will match the origin\nC\u003chttp://www.example.com:3000\u003e.\n\n    example.com\n    *.example.com\n    *://www.example.com\n    http://www.example.com:*\n\nThis is not a comprehensive security measure. The server is trusting that the\nclient is not lying about its C\u003cOrigin\u003e. The client can claim any origin it\nwants.\n\n=head1 USAGE\n\n=head2 Mojolicious\n\nTo use Mercury to communicate between Mojolicious server processes, use\nL\u003cMojo::UserAgent's websocket method|Mojo::UserAgent/websocket\u003e.\n\n=head2 Dancer\n\nTo use Mercury inside of a L\u003cDancer\u003e or L\u003cDancer2\u003e app, you can use\nL\u003cAnyEvent::WebSocket::Client\u003e with the L\u003cTwiggy\u003e PSGI server.\n\n=head2 Catalyst\n\nLike Dancer, you can use L\u003cAnyEvent::WebSocket::Client\u003e and L\u003cTwiggy\u003e to use\nMercury in your Catalyst app.\n\n=head2 JavaScript\n\nFor simple applications that only need some peer-to-peer message passing, you\ncan directly connect clients to Mercury.\n\n=head1 SEE ALSO\n\n=over 4\n\n=item L\u003cThe Mercury web site|http://preaction.me/mercury\u003e\n\n=item L\u003csocket.io|http://socket.io\u003e\n\nA JavaScript WebSocket messaging library (client and server). For a\nsocket.io-compatible server written in Perl, see L\u003cPocketIO\u003e.\n\n=item L\u003czeromq|http://zeromq.org\u003e\n\nA socket library that provides communication patterns for scalability.\nThe inspiration to build Mercury (Mercury requires only Perl 5.10 or higher).\nFor a Perl API to ZeroMQ, see L\u003cZMQ::FFI\u003e.\n\n=item L\u003cnanomsg|http://nanomsg.org\u003e\n\nA socket library that provides communication patterns for scalability. The\nsuccessor to ZeroMQ. The inspiration of the features provided by Mercury. For a\nPerl API, see L\u003cNanoMsg::Raw\u003e.\n\n=back\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpreaction%2Fmercury","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpreaction%2Fmercury","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpreaction%2Fmercury/lists"}