{"id":31697691,"url":"https://github.com/jollopre/harmoniser","last_synced_at":"2025-10-08T18:12:15.834Z","repository":{"id":40394573,"uuid":"387698657","full_name":"jollopre/harmoniser","owner":"jollopre","description":"A minimalistic approach to interact with RabbitMQ","archived":false,"fork":false,"pushed_at":"2025-05-19T18:59:45.000Z","size":225,"stargazers_count":10,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-07T00:09:11.817Z","etag":null,"topics":["bunny","pubsub","rabbitmq","ruby","ruby-gem","ruby-on-rails"],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/jollopre.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null}},"created_at":"2021-07-20T06:45:13.000Z","updated_at":"2025-05-19T18:59:38.000Z","dependencies_parsed_at":"2024-01-13T22:50:41.120Z","dependency_job_id":"eb1f971d-1288-4ec8-82e8-29bb6c8ff793","html_url":"https://github.com/jollopre/harmoniser","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/jollopre/harmoniser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jollopre%2Fharmoniser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jollopre%2Fharmoniser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jollopre%2Fharmoniser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jollopre%2Fharmoniser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jollopre","download_url":"https://codeload.github.com/jollopre/harmoniser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jollopre%2Fharmoniser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278838447,"owners_count":26054723,"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","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["bunny","pubsub","rabbitmq","ruby","ruby-gem","ruby-on-rails"],"created_at":"2025-10-08T18:12:14.945Z","updated_at":"2025-10-08T18:12:15.829Z","avatar_url":"https://github.com/jollopre.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Harmoniser\n\n[![Gem Version](https://badge.fury.io/rb/harmoniser.svg)](https://badge.fury.io/rb/harmoniser)\n![CI workflow](https://github.com/jollopre/harmoniser/actions/workflows/ci.yml/badge.svg)\n\nHarmoniser is a minimalistic approach to interact with the RabbitMQ implementation of [AMQP 0-9-1](https://www.rabbitmq.com/amqp-0-9-1-reference.html) through [Bunny](https://github.com/ruby-amqp/bunny).\n\n* Harmoniser provides a long-lived [connection](https://www.rabbitmq.com/connections.html) to RabbitMQ for efficient publishing and consuming of messages.\n* Harmoniser issues a thread-safe dedicated [channel](https://www.rabbitmq.com/channels.html) for each publish/consume use case defined.\n* Harmoniser offers a concise DSL to differentiate topology definition from other actions such as publishing or consuming.\n* Harmoniser may run as a dedicated Ruby Process through its [CLI](https://github.com/jollopre/harmoniser/wiki/Harmoniser-CLI) as well as a part of other processes like Puma, Unicorn, Sidekiq, or similar.\n\n## Getting Started\n\n1. Add this line to your application's Gemfile:\n\n```ruby\ngem \"harmoniser\"\n```\n\n2. Install the gem:\n\n```sh\n  $ bundle install\n```\n\n3. Include `Harmoniser::Publisher` and/or `Harmoniser::Subscriber` in your classes. For instance, in [this scenario](examples/multicast.rb), it is assumed that you would like to run publishers and subscribers under the same process.\n\n4. (Optional) Run Harmoniser CLI in order to process messages from your subscribers:\n\n```sh\n  $ bundle exec harmoniser --require ./examples/multicast.rb\n```\n\n5. Inspect the logs to see if everything worked as expected. Look for logs containing `harmoniser@`.\n\n## Concepts\n\nHarmoniser is a library for publishing/consuming messages through RabbitMQ. It enables not only the connection of applications but also the scaling of an application by performing work in the background. This gem is comprised of three parts:\n\n### Publisher\n\nThe Publisher runs in any Ruby process (puma, unicorn, passenger, sidekiq, etc) and enables you to push messages through a [RabbitMQ Exchange](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchanges). Creating a publisher is as simple as:\n\n```ruby\nrequire \"harmoniser\"\n\nclass MyPublisher\n  include Harmoniser::Publisher\n  harmoniser_publisher exchange_name: \"my_topic_exchange\"\nend\n\nMyPublisher.publish({ salute: \"Hello World!\" }.to_json, routing_key: \"my_resource.foo.bar\")\n```\n\nThe code above assumes that the exchange is already defined. We would like to emphasize that defining RabbitMQ topology (exchanges, queues and bindings) should be performed outside of the class whose role is purely focused on publishing. For more details on how to define the topology, refer to [this example](examples/multicast.rb#L11-L19).\n\n### RabbitMQ\n\nRabbitMQ is the message broker used to publish/consume messages through Harmoniser. It can be configured using `Harmoniser.configure` as follows:\n\n```ruby\nrequire \"harmoniser\"\n\nHarmoniser.configure do |config|\n  config.connection_opts = {\n    host: \"rabbitmq\"\n  }\nend\n```\n\nThe options permitted for `connection_opts` are those accepted by [Bunny](https://github.com/ruby-amqp/bunny/blob/main/docs/guides/connecting.md#using-a-map-of-parameters) since Harmoniser is built on top of the widely used Ruby client for RabbitMQ.\n\n### Harmoniser Server\n\nHarmoniser server is a process specifically dedicated to running Subscribers that listen to [Rabbit Queues](https://www.rabbitmq.com/tutorials/amqp-concepts.html#queues). Like any other Ruby process (puma, unicorn, passenger, sidekiq, etc), Harmoniser remains up and running unless OS Signals such as SIGINT or SIGTERM  are sent to it. During boot time, the server can register each class from your code that includes `Harmoniser::Subscriber` module. Creating a subscriber is as simple as:\n\n```ruby\nclass MySubscriber\n  include Harmoniser::Subscriber\n  harmoniser_subscriber queue_name: \"my_queue\"\nend\n```\n\nThe code above assumes that the queue and its binding to an exchange are already defined. You can find more details about how this is specified [here](examples/multicast.rb#L11-L19).\n\nTo enable subscribers to receive messages from a queue, you should spin up a dedicated Ruby process as follows:\n\n```sh\n  $ bundle exec harmoniser --require ./a_path_to_your_ruby_file.rb\n```\n\nFor more information about the various options accepted by the Harmoniser process, refer to the [Harmoniser CLI documentation](https://github.com/jollopre/harmoniser/wiki/Harmoniser-CLI).\n\n## Contributing\n\nIf you are facing issues that you suspect are related to Harmoniser, please consider opening an issue [here](https://github.com/jollopre/harmoniser/issues). Remember to include as much information as possible such as version of Ruby, Rails, Harmoniser, OS, etc.\n\nIf you believe you have encountered a potential bug, providing detailed information about how to reproduce it can greatly expedite the fix.\n\n### Code\n\nTo contribute to this codebase, you will need to setup your local development using the following steps:\n\n```sh\n# Prepare the environment for working locally.\n  $ make build\n# Perform the desired changes into your local copy\n  $ make test\n```\n\nYou can also access the running container by executing `$ make shell` and then execute any commands related to Harmoniser within its isolated environment.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Author\n\nJose Lloret, [\u003cjollopre@gmail.com\u003e](mailto:jollopre@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjollopre%2Fharmoniser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjollopre%2Fharmoniser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjollopre%2Fharmoniser/lists"}