harmoniser 0.6.0 → 0.7.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +13 -0
- data/README.md +25 -25
- data/harmoniser.gemspec +2 -2
- data/lib/harmoniser/parser.rb +3 -3
- data/lib/harmoniser/publisher.rb +13 -1
- data/lib/harmoniser/version.rb +1 -1
- metadata +5 -6
- data/docs/cli.md +0 -20
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 64be8cb27f910668f1c7d88a546d87b9775f75cfc5a6626ecb6e825409dbc7a4
|
|
4
|
+
data.tar.gz: 0b82a72f0e80548db66341adf5748654f7751f3b74a08fa2e5613c043876d8fc
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: ef1b871763652b0090be1248c259c94846e8132925f6346051b51d4b0d4d2a95a758d5c8762edbb22793ae5c7f9e2e3fafbc1d108551854005d695a79a5927f8
|
|
7
|
+
data.tar.gz: 79643c9b0a50769cc7968740bbb3f6aba2461c3800a136651b1206b523e7fbb8768f9ceac85dba83f0b3a029923d9a148cf0c60bde1397385d449e845899386e
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.7.0] - 2024-01-03
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
- Add a default on_return callback for Publisher. When a message marked as mandatory is published and cannot be routed to any queue, a detailed log is output.
|
|
7
|
+
|
|
8
|
+
### Changed
|
|
9
|
+
- Improve README to highlight Harmoniser golden features
|
|
10
|
+
- Shorten the gemspec summary
|
|
11
|
+
|
|
12
|
+
### Removed
|
|
13
|
+
- Delete docs folder since github wiki is the way to document the library.
|
|
14
|
+
- Delete .travis.yml since we no longer use for CI/CD integration.
|
|
15
|
+
|
|
3
16
|
## [0.6.0] - 2023-12-30
|
|
4
17
|
|
|
5
18
|
### Added
|
data/README.md
CHANGED
|
@@ -3,9 +3,12 @@
|
|
|
3
3
|
[](https://badge.fury.io/rb/harmoniser)
|
|
4
4
|
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
Harmoniser 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).
|
|
7
7
|
|
|
8
|
-
Harmoniser
|
|
8
|
+
* Harmoniser provides a long-lived [connection](https://www.rabbitmq.com/connections.html) to RabbitMQ for efficient publishing and consuming of messages.
|
|
9
|
+
* Harmoniser issues a thread-safe dedicated [channel](https://www.rabbitmq.com/channels.html) for each publish/consume use case defined.
|
|
10
|
+
* Harmoniser offers a concise DSL to differentiate topology definition from other actions such as publishing or consuming.
|
|
11
|
+
* 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.
|
|
9
12
|
|
|
10
13
|
## Getting Started
|
|
11
14
|
|
|
@@ -17,28 +20,27 @@ gem "harmoniser"
|
|
|
17
20
|
|
|
18
21
|
2. Install the gem:
|
|
19
22
|
|
|
20
|
-
```
|
|
23
|
+
```sh
|
|
21
24
|
$ bundle install
|
|
22
25
|
```
|
|
23
26
|
|
|
24
|
-
3. Include `Harmoniser::Publisher` and/or `Harmoniser::Subscriber` in your classes. For instance, [this scenario](examples/multicast.rb)
|
|
27
|
+
3. 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.
|
|
25
28
|
|
|
26
|
-
4. (Optional) Run
|
|
29
|
+
4. (Optional) Run Harmoniser CLI in order to process messages from your subscribers:
|
|
27
30
|
|
|
28
31
|
```sh
|
|
29
32
|
$ bundle exec harmoniser --require ./examples/multicast.rb
|
|
30
33
|
```
|
|
31
34
|
|
|
32
|
-
5. Inspect the logs to see if everything worked as expected. Look for logs
|
|
35
|
+
5. Inspect the logs to see if everything worked as expected. Look for logs containing `harmoniser@`.
|
|
33
36
|
|
|
34
37
|
## Concepts
|
|
35
38
|
|
|
36
|
-
Harmoniser is a library for publishing/consuming messages through RabbitMQ. It
|
|
39
|
+
Harmoniser 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:
|
|
37
40
|
|
|
38
41
|
### Publisher
|
|
39
42
|
|
|
40
|
-
The Publisher runs in any Ruby process (puma, unicorn, passenger, sidekiq, etc) and
|
|
41
|
-
push messages through a [RabbitMQ Exchange](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchanges). Creating a publisher is as simple as:
|
|
43
|
+
The 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:
|
|
42
44
|
|
|
43
45
|
```ruby
|
|
44
46
|
require "harmoniser"
|
|
@@ -51,11 +53,11 @@ end
|
|
|
51
53
|
MyPublisher.publish({ salute: "Hello World!" }.to_json, routing_key: "my_resource.foo.bar")
|
|
52
54
|
```
|
|
53
55
|
|
|
54
|
-
The code above assumes that the exchange is already defined. We
|
|
56
|
+
The 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).
|
|
55
57
|
|
|
56
58
|
### RabbitMQ
|
|
57
59
|
|
|
58
|
-
RabbitMQ is the message broker used to publish/consume messages through Harmoniser. It can be configured
|
|
60
|
+
RabbitMQ is the message broker used to publish/consume messages through Harmoniser. It can be configured using `Harmoniser.configure` as follows:
|
|
59
61
|
|
|
60
62
|
```ruby
|
|
61
63
|
require "harmoniser"
|
|
@@ -67,12 +69,11 @@ Harmoniser.configure do |config|
|
|
|
67
69
|
end
|
|
68
70
|
```
|
|
69
71
|
|
|
70
|
-
The options permitted for `connection_opts` are those accepted by
|
|
71
|
-
[Bunny](https://github.com/ruby-amqp/bunny/blob/80a8fc7aa0cd73f8778df87ae05f28c443d10c0d/lib/bunny/session.rb#L142) since at the end this library is built on top of the most widely used Ruby client for RabbitMQ.
|
|
72
|
+
The 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.
|
|
72
73
|
|
|
73
|
-
###
|
|
74
|
+
### Harmoniser Server
|
|
74
75
|
|
|
75
|
-
Harmoniser server is a process specifically dedicated to
|
|
76
|
+
Harmoniser 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:
|
|
76
77
|
|
|
77
78
|
```ruby
|
|
78
79
|
class MySubscriber
|
|
@@ -81,25 +82,25 @@ class MySubscriber
|
|
|
81
82
|
end
|
|
82
83
|
```
|
|
83
84
|
|
|
84
|
-
The code above assumes that the queue and its binding to an exchange are already defined. You can
|
|
85
|
+
The 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).
|
|
85
86
|
|
|
86
|
-
|
|
87
|
+
To enable subscribers to receive messages from a queue, you should spin up a dedicated Ruby process as follows:
|
|
87
88
|
|
|
88
89
|
```sh
|
|
89
90
|
$ bundle exec harmoniser --require ./a_path_to_your_ruby_file.rb
|
|
90
91
|
```
|
|
91
92
|
|
|
92
|
-
|
|
93
|
+
For 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).
|
|
93
94
|
|
|
94
95
|
## Contributing
|
|
95
96
|
|
|
96
|
-
If you are facing issues
|
|
97
|
+
If 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.
|
|
97
98
|
|
|
98
|
-
If you
|
|
99
|
+
If you believe you have encountered a potential bug, providing detailed information about how to reproduce it can greatly expedite the fix.
|
|
99
100
|
|
|
100
101
|
### Code
|
|
101
102
|
|
|
102
|
-
|
|
103
|
+
To contribute to this codebase, you will need to setup your local development using the following steps:
|
|
103
104
|
|
|
104
105
|
```sh
|
|
105
106
|
# Prepare the environment for working locally.
|
|
@@ -108,14 +109,13 @@ In order to contribute to this codebase, you will need to setup your local devel
|
|
|
108
109
|
$ make test
|
|
109
110
|
```
|
|
110
111
|
|
|
111
|
-
You can also
|
|
112
|
+
You can also access the running container by executing `$ make shell` and then execute any commands related to Harmoniser within its isolated environment.
|
|
112
113
|
|
|
113
114
|
## Future Improvements
|
|
114
115
|
|
|
115
|
-
- [ ]
|
|
116
|
+
- [ ] Feature: Introduce capability of configuring concurrency for Harmoniser process.
|
|
117
|
+
- [ ] Issue: Reopen Channels anytime an exception occurs that closes them automatically. More info can be found [here](https://www.rabbitmq.com/channels.html#error-handling).
|
|
116
118
|
- [ ] Chore: Introduce simplecov gem for code coverage.
|
|
117
|
-
- [ ] Feature: Add default `on_return` handler as well as permitting the definition of on_return method to be called anytime a published message gets returned.
|
|
118
|
-
- [ ] Feature: Introduce capability of configuring number of threads for queue consuming at the CLI.
|
|
119
119
|
|
|
120
120
|
## License
|
|
121
121
|
|
data/harmoniser.gemspec
CHANGED
|
@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
|
|
|
8
8
|
spec.authors = ["Jose Lloret"]
|
|
9
9
|
spec.email = ["jollopre@gmail.com"]
|
|
10
10
|
|
|
11
|
-
spec.summary = "A minimalistic approach to
|
|
12
|
-
spec.description = "A declarative approach to
|
|
11
|
+
spec.summary = "A minimalistic approach to interact with RabbitMQ"
|
|
12
|
+
spec.description = "A declarative approach to communication with RabbitMQ that simplifies the integration of publishing and consuming messages."
|
|
13
13
|
spec.homepage = "https://github.com/jollopre/harmoniser"
|
|
14
14
|
spec.license = "MIT"
|
|
15
15
|
spec.required_ruby_version = ">= 3.2"
|
data/lib/harmoniser/parser.rb
CHANGED
|
@@ -8,13 +8,13 @@ module Harmoniser
|
|
|
8
8
|
@options = {}
|
|
9
9
|
@option_parser = OptionParser.new do |opts|
|
|
10
10
|
opts.banner = "harmoniser [options]"
|
|
11
|
-
opts.on "-e", "--environment ENV", "
|
|
11
|
+
opts.on "-e", "--environment ENV", "Set the application environment (defaults to inferred environment or 'production')" do |arg|
|
|
12
12
|
@options[:environment] = arg
|
|
13
13
|
end
|
|
14
|
-
opts.on "-r", "--require [PATH|DIR]", "
|
|
14
|
+
opts.on "-r", "--require [PATH|DIR]", "Specify a file to require or the location of the Rails application" do |arg|
|
|
15
15
|
@options[:require] = arg
|
|
16
16
|
end
|
|
17
|
-
opts.on("-v", "--[no-]verbose", "Run verbosely") do |arg|
|
|
17
|
+
opts.on("-v", "--[no-]verbose", "Run verbosely (set log severity to 'debug' for detailed RabbitMQ interactions)") do |arg|
|
|
18
18
|
@options[:verbose] = arg
|
|
19
19
|
end
|
|
20
20
|
opts.on "-V", "--version", "Print version and exit" do
|
data/lib/harmoniser/publisher.rb
CHANGED
|
@@ -29,17 +29,29 @@ module Harmoniser
|
|
|
29
29
|
private
|
|
30
30
|
|
|
31
31
|
def harmoniser_exchange
|
|
32
|
-
@harmoniser_exchange ||=
|
|
32
|
+
@harmoniser_exchange ||= create_exchange
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
def create_exchange
|
|
36
|
+
exchange = Bunny::Exchange.new(
|
|
33
37
|
Publisher.create_channel,
|
|
34
38
|
@harmoniser_exchange_definition.type,
|
|
35
39
|
@harmoniser_exchange_definition.name,
|
|
36
40
|
@harmoniser_exchange_definition.opts
|
|
37
41
|
)
|
|
42
|
+
handle_return(exchange)
|
|
43
|
+
exchange
|
|
38
44
|
end
|
|
39
45
|
|
|
40
46
|
def raise_missing_exchange_definition
|
|
41
47
|
raise MissingExchangeDefinition, "Please, call harmoniser_publisher class method first with the exchange_name that will be used for publications"
|
|
42
48
|
end
|
|
49
|
+
|
|
50
|
+
def handle_return(exchange)
|
|
51
|
+
exchange.on_return do |basic_return, properties, payload|
|
|
52
|
+
Harmoniser.logger.warn("Default on_return handler executed for exchange: basic_return = `#{basic_return}`, properties = `#{properties}`, payload = `#{payload}`")
|
|
53
|
+
end
|
|
54
|
+
end
|
|
43
55
|
end
|
|
44
56
|
|
|
45
57
|
class << self
|
data/lib/harmoniser/version.rb
CHANGED
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: harmoniser
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.7.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Jose Lloret
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date:
|
|
11
|
+
date: 2024-01-03 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: bunny
|
|
@@ -66,8 +66,8 @@ dependencies:
|
|
|
66
66
|
- - "~>"
|
|
67
67
|
- !ruby/object:Gem::Version
|
|
68
68
|
version: '1.0'
|
|
69
|
-
description: A declarative approach to
|
|
70
|
-
|
|
69
|
+
description: A declarative approach to communication with RabbitMQ that simplifies
|
|
70
|
+
the integration of publishing and consuming messages.
|
|
71
71
|
email:
|
|
72
72
|
- jollopre@gmail.com
|
|
73
73
|
executables:
|
|
@@ -82,7 +82,6 @@ files:
|
|
|
82
82
|
- bin/console
|
|
83
83
|
- bin/harmoniser
|
|
84
84
|
- bin/setup
|
|
85
|
-
- docs/cli.md
|
|
86
85
|
- harmoniser.gemspec
|
|
87
86
|
- lib/harmoniser.rb
|
|
88
87
|
- lib/harmoniser/channelable.rb
|
|
@@ -126,5 +125,5 @@ requirements: []
|
|
|
126
125
|
rubygems_version: 3.4.10
|
|
127
126
|
signing_key:
|
|
128
127
|
specification_version: 4
|
|
129
|
-
summary: A minimalistic approach to
|
|
128
|
+
summary: A minimalistic approach to interact with RabbitMQ
|
|
130
129
|
test_files: []
|
data/docs/cli.md
DELETED
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
# Harmoniser CLI
|
|
2
|
-
|
|
3
|
-
Harmoniser CLI is a command line tool than run a Ruby process through `bundle exec harmoniser`. This utility accepts the following options:
|
|
4
|
-
|
|
5
|
-
```sh
|
|
6
|
-
bundle exec harmoniser -h
|
|
7
|
-
|
|
8
|
-
harmoniser [options]
|
|
9
|
-
-e, --environment ENV Application environment
|
|
10
|
-
-r, --require [PATH|DIR] File to require or location of Rails application
|
|
11
|
-
-v, --[no-]verbose Run verbosely
|
|
12
|
-
-V, --version Print version and exit
|
|
13
|
-
-h, --help Show help
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
The `environment` is automatically inferred from the environment variables `RAILS_ENV` or `RACK_ENV`, otherwise fallbacks to `production`. However you can specify your preferred value, for instance `development` or `test`.
|
|
17
|
-
|
|
18
|
-
The `require` is by default pointing at `.`, which means that this option when configured under a Rails application, might be ignored. Since Ruby is not Rails only, you can certainly specify the location path of your Ruby file that will be used to load the classes including Harmoniser::Subscriber. In contrast, if a path to a directory is passed, Harmoniser assumes that `./config/environment.rb` lives within the folder passed as option.
|
|
19
|
-
|
|
20
|
-
The `verbose` option, when passed, sets the severity of Harmoniser logs to `debug` being able to see fine-grained details of things like RabbitMQ interactions happening or messages published into exchanges. By default, the verbosity is disabled to prevent your environment to be flooded with unnecessary logs.
|