mimi-messaging 0.1.9 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 839a61eb8dc38069954026c340bdbd6a530a8542
-  data.tar.gz: faecf24ec54b10447d81b48ca1794438a6d3cf0c
+  metadata.gz: 54a536d257b3a394b605e80e1b24167e5912f785
+  data.tar.gz: 03374246a36903692068863563ec7a111cd18b8b
 SHA512:
-  metadata.gz: b73ee235bc27d40cba7209e4049fd52f50ab8499a85243053bc12f3e7320d8730ad2072af3a91803354fa0472775ac857c21521b824fd62031d8bee7899363ba
-  data.tar.gz: 958de3483a20f933c134b68c0061b632533db04993608f11f75b9b02093017c6e79bee89917b196d56931bb1b52aa8308afeb298474385565450d5ac45d6d099
+  metadata.gz: '0295bb31beb00e6370340e4db43bab2a145e9d463d514bcdf1eba944a171edb614133afc7384a9e1e3010b832c4ff4b547ae9a27e307efb19d4abe3acee0782d'
+  data.tar.gz: 5e3a7f512fc58d688551c9601c26b863872dfeafaf860554796f2493ba30234045c591520c453fa973cae529069516cc19653553cf369eca7f31bc7c5ac29395

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+.DS_Store

data/.rubocop.yml

@@ -0,0 +1,66 @@
+---
+
+require:
+  - rubocop-performance
+
+AllCops:
+  Exclude:
+    - tmp/**/*
+
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+
+  TargetRubyVersion: 2.5
+
+Layout/ExtraSpacing:
+  AllowForAlignment: true
+
+Lint/InterpolationCheck:
+  Enabled: false
+
+Metrics:
+  Enabled: true
+
+Metrics/LineLength:
+  Max: 100
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ModuleLength:
+  Max: 300
+
+Naming/FileName:
+  Exclude:
+    - .simplecov
+
+TrivialAccessors:
+  ExactNameMatch: true
+
+Style/ModuleFunction:
+  EnforcedStyle: extend_self
+
+# https://github.com/bbatsov/rubocop/pull/72
+Style/AsciiComments:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+# Don't see why storing context information in the exception is a bad thing
+Style/RaiseArgs:
+  Enabled: false
+
+# Allow adding comments at `end` of classes and modules
+Style/CommentedKeyword:
+  Enabled: false
+
+# Allow `!!value` for casting to Boolean
+Style/DoubleNegation:
+  Enabled: false
+
+EmptyMethod:
+  EnforcedStyle: expanded

data/README.md

@@ -1,8 +1,73 @@
-# mimi-messaging
+# [WIP] mimi-messaging
 
-Communications via RabbitMQ for [mimi](https://github.com/kukushkin/mimi).
+Interservice communication via message bus for microservices.
 
-[in development]
+## What
+
+`mimi-messaging` is a Messaging layer -- an interservice
+communication layer based on message bus, for connecting microservice applications.
+
+* Command, Query, Event communication patterns
+* "at-least-once" message delivery guarantees
+* Abstract message bus interface, not bound to specific message broker implementation
+
+See also: [Overview of Messaging layer properties](docs/Messaging_Layer_Properties.md)
+
+## Why
+
+[Why HTTP is a bad choice for interservice communication?](docs/Why_HTTP_is_a_bad_choice.md)
+
+TBD: Message bus pro's and con's.
+
+## How
+
+Concepts:
+
+* Command: one-to-one, send and forget
+* Query: one-to-one, call and wait for response
+* Event: one-to-many, broadcast
+
+## Setup
+
+```
+gem "mimi-messaging", "~> 1.0"
+gem "mimi-messaging-<ADAPTER>"
+```
+
+```
+require "mimi/messaging"
+require "mimi/messaging/<ADAPTER>"
+
+Mimi::Messaging.use serializer: Mimi::Messaging::JsonSerializer
+Mimi::Messaging.configure mq_adapter: "<ADAPTER>", ... # extra adapter specific options
+Mimi::Messaging.start
+```
+
+## Usage
+
+```
+response = Mimi::Messaging.query("orders/show", id: 123)
+```
+
+## Adapters
+
+`mimi-messaging` is not bound to a specific message broker implementation like RabbitMQ or Kafka. It interacts with a message broker using an adapter interface and
+there are several available adapters:
+
+* [Kafka](https://github.com/kukushkin/mimi-messaging-kafka)
+* RabbitMQ (TBD)
+* NATS (TBD)
+* Amazon SQS/SNS
+* in-memory (single process)
+
+## Designing apps
+
+
+There are only two hard problems in distributed systems:
+
+2. Exactly-once delivery
+1. Guaranteed order of messages
+2. Exactly-once delivery
 
 
 ## License

data/TODO.md

@@ -0,0 +1,8 @@
+# TODO
+
+* Terminology:
+  * what is target: for command, query, event
+  * what is target base: for command, query, event
+  * event or broadcast?
+* Higher level processor: Command/QueryProcessor? EventProcessor
+* Higher level message for producers: Mimi::Messaging::Message, Mimi::Messaging::Event ?

data/docs/Messaging_Layer_Properties.md

@@ -0,0 +1,141 @@
+# Messaging Layer Properties
+
+## Communication Patterns
+
+Messaging Layer provides an intersevice communucation layer based on abstracted
+message bus, implementing the range of communication patterns:
+
+* Command
+* Query
+* Event
+
+### Command
+
+![Command pattern diagram](./img/pattern--command.png)
+* one-to-one, send and forget
+
+*Command* is a communication pattern where application A (producer) asynchronously
+sends a message to a queue, from which application B (consumer) receives the message.
+
+In this case the application A sends the message and continues the execution immediately
+after the message has been accepted by the Messaging Layer.
+
+There can be multiple instances of application B running and processing messages from
+the same queue. The Messaging Layer guarantees that only one instance of application B
+will receive this message.
+
+### Query
+
+![Query pattern diagram](./img/pattern--query.png)
+* one-to-one, request/response
+
+*Query* is a communication pattern where application A sends a message (request) to
+a queue, from which application B receives the message, and waits for another
+message (response) from B.
+
+In this case application A sends the message and stops execution until
+the response from application B is received or the timeout is fired.
+
+This communication pattern is synchronous, and there are several things that
+may go wrong during this communication: the target queue name is wrong,
+the application B may be down, or the application B just could not produce a response
+in time and the timeout is fired.
+
+There can be multiple instances of application B running and processing messages from
+the same queue. The Messaging Layer guarantees that only one instance of application B
+will receive this message, and the response message will be delivered to the same
+instance of application A, that produced the request.
+
+
+### Event
+
+![Event pattern diagram](./img/pattern--event.png)
+* one-to-many, pub/sub
+
+*Event* is a communication pattern where application A sends a message (event) to
+a topic, to which many other applications may subscribe and listen for events.
+There can be  multiple instances of the same application B subscribed to this topic,
+or it may be different applications B and C subscribed to the same topic.
+
+In this case the application A sends the message and continues the execution immediately
+after the message has been accepted by the Messaging Layer. The Messaging Layer
+delivers the message to the topic and all the subscribed listeners, if there are any.
+
+#### Listening for events
+
+While producing an event is simple and it only means posting a message to a topic,
+listening for events has two variants:
+
+![Event directly diagram](./img/pattern--event-direct.png)
+* Listening for events on a topic directly
+
+An application can listen for events on a topic directly. That means that
+whenever the event is published on a topic, every application instance listening for the
+events directly will receive this event. If the application listening for the
+events in such a way is down, it is not guaranteed that the events published while it
+was offline will be delivered after it gets back online.
+
+![Event using a queue diagram](./img/pattern--event-using-queue.png)
+* Listening for events on a topic using a queue
+
+An application can listen for events on a topic using a bound queue. That means
+that every event published on the given topic will be additionally put into specified
+queue, from which the message is consumed by only one instance of the application.
+In this case the queue will keep the messages (events) even while the listening
+applications/instances are down, and the messages will be delivered once the
+application gets back online.
+
+## Logical names for message targets
+
+Whenever a message (command, query or event) is sent, Messaging Layer expects
+a "target" for the message to be specified. This target is a logical name
+that defines the destination of a message.
+
+For commands and queries, the target of the message consists of a queue name
+and a method name (e.g. `"customers/create"`).
+
+For events, the target of the message consists of a topic name and an
+event type (e.g. `"customers/created"`).
+
+This allows to model the communication around your business domain concepts,
+and not the implementation details like application or host names.
+
+## Delivery guarantee
+
+Messaging Layer guarantees "at-least-once" message delivery.
+
+Once the call to `command()`, `query()`, `event()` successfully completes,
+it is guaranteed that the Messaging Layer accepted the message,
+and the message will eventually be delivered to the recipient.
+
+"at-least-once" means that in certain cases the same message may be delivered
+more than once, and the applications consuming the messages must be prepared to
+deal with it, which in most cases means implementing idempotent message processors.
+
+
+### Notes:
+
+>  `query()` method successfully returns only after the response has been received,
+at which point the caller may be sure that not only the message has been accepted
+by the Messaging Layer, but that it has been delivered and successfully processed
+by the recepient.
+
+> `event()` method successfully completing guarantees only that the message
+will be delivered to the topic -- the message may still be lost by the listener if
+it does not use a queue for keeping the messages
+
+
+## Load balancing
+
+The Messaging Layer ensures best-effort load balancing of messages in case there
+are multiple message processors for the same request target (for Command and Query
+processors), or multiple listeners (for Event processors with a queue).
+
+
+## Ordering of messages
+
+The Messaging Layer does NOT guarantee that the messages will be delivered
+in the same order as they were produced.
+
+
+--

data/docs/Why_HTTP_is_a_bad_choice.md

@@ -0,0 +1,20 @@
+# Why HTTP is a bad choice for interservice communication
+
+[WIP]
+
+Downsides of HTTP:
+* inherently synchronous
+  * timeouts
+  * retries
+* one-to-one, no pub/sub
+* additional work required:
+  * network
+  * service discovery
+  * routing
+  * load balancing
+  * authentication/authorization
+
+
+Pro's of HTTP:
+* synchronous communication is simple
+* HTTP as technology is well known by engineers

data/docs/diagrams/Pattern -- Command.drawio

@@ -0,0 +1 @@
+<mxfile modified="2019-07-14T14:14:39.587Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36" etag="lgARSmjxxzsn12OMDTwz" version="10.9.6" type="google"><diagram id="y9hzfK7Ta8yHCBsTJmj-" name="Page-1">5Zbfk5owEMf/Gh7bASKoj4rae+lcp85Nbd8ysEqmgdAQT+hf32ASfuUc7c31rp0+mf2yu9l8dg04KMqqDxwX6UeWAHV8N6kctHJ833P9UP40Sq2UwA+UcOAk0U6dsCU/wURq9UgSKAeOgjEqSDEUY5bnEIuBhjlnp6HbntHhrgU+gCVsY0xt9QtJRKrUmTlWo98BOaRmZy+cqycZNs76JGWKE3bqSWjtoIgzJtQqqyKgDTzDRcVtLjxtC+OQi1sCZg+f774VafWQ4cX9fb5cpLB7p7M8YnrUB17oakVtEJxSImBb4LixT7LNDlqmIqPS8uQSl4UCvycVyL2We0JpxCjj53C02Wz8KJJ6KTj7DoMny2Dqyie6COACqoun81pmctiAZSB4LV1MgMFcj+xT17VAS2mvYUbDek4ObeYOpVxomr9B1rfILv9NshP0l5FFFtkfR5DLMV3OjnnScFs1JK6wthBO14tw7drQV5O1twleBq0/GaKd2WRb2q+CNrDQWlQhTxbNvSqtmOKyJPEQJFRE7Hrrrw3/94G2VpVux9mojZHL4nd9oxfVmF3Y2TJxqjhIrCt81AB5AHbkMVy/CAXmBxDXhs9u6I3/BQ4UC/I4LPepLuodPjEiD3LxkrMGQR1TR/XfBeNE01Eid5RIcbASyc7juudWNA7l5YLb17i5O9xgNKMqYzexLdPnD3H43w4xunGI/bccYjQPhjPhPXOIJ+EwUfhnZhjNX3SGpdl98yn37ssZrX8B</diagram></mxfile>

data/docs/diagrams/Pattern -- Event direct.drawio

@@ -0,0 +1 @@
+<mxfile modified="2019-07-14T14:29:20.445Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36" etag="UPJeEwyjqKJsfKu6Yc1A" version="10.9.6" type="google"><diagram id="y9hzfK7Ta8yHCBsTJmj-" name="Page-1">7VhNc5swEP01HNtBYIh9xNhuLp10muk07U2FjdFUSIyQY9xfX8mIT9l1mniSNM0JdqWVdt8+iV0cP86rDwIX2UeeAnU8N60cf+F4HnK9UD20ZldrAi+oFWtBUjOpU1yTX9BYGu2GpFAOJkrOqSTFUJlwxiCRAx0Wgm+H0245He5a4DVYiusEU1v7laQyq7XTJiytvwSyzpqdUTirR3LcTDaRlBlO+ban8peOHwvOZf2WVzFQDV6DS223OjLaOiaAyfsYTL98vvxeZNWXHEdXV2weZXDzroH5DtONiTg27spdg8E2IxKuC5xoeavy7PjzTOZUSUi94rKokb8lFajN5reE0phTLvbm/mq18uJY6Usp+E8YjMyDC1eNGCdASKiOhoda0BTbgOcgxU5NMQYT34RiiNbivu3SFhhV1stYo8OGKOt25Q5L9WLg/AtoZxay89eBLJo8M7LIQjb6N5GdvTBgvddK2ekzA+tbwEpekMQCV/ANSzVsCw3ECagtBC+WUbh0bcwXkyVaBedB1nNPcxZ5T4ltYGFrwQosjXQtoKSE4rJUyA+QhIrIm977N52A94GRFpXJx17YNQJTzt/0hZ6VFjuzvdTY1c5BapUdowyoAPhGJHD6HpRYrEGeYp+d0XseBgEUS3I3dPdQFs0OnzhRgbSEmQ754nsjHtRRGqN++TJaB42/7xejhWoYrIVU4vGuN63QE0qLdS0uDydi+N8S0b8nEb3nJKI/C4Y3F3ogEyfhcKHwsUQ85u/opnWDEWvrFc/KYWSXAG8kPlDXv5DbdOKe6Tb1x5/nc5F45DAKn4LEdrn1RuJDff8bix/GYm/yFCy2C9tIs2Lzg5Iyg1JT5g72bnKmg9F5P9hVqGpf/ql1YJzBqGswKkzJmukjovYBpZ/r3oEkmEZmICdpqrc52KsMuxnn8c0HQkc+4f3mAx3g7bjoPN+vCLvoU0nZ+4yLgiqoJKmzw1K9FislZgojfYQSUCdIp1Fm0CXzteauvTuOt+Roep7UKbH7rVofx+7ntL/8DQ==</diagram></mxfile>

data/docs/diagrams/Pattern -- Event with Queue.drawio

@@ -0,0 +1 @@
+<mxfile modified="2019-07-14T14:31:44.611Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36" etag="knmCqr-WVQHLlz4MjdX8" version="10.9.6" type="google"><diagram id="y9hzfK7Ta8yHCBsTJmj-" name="Page-1">5VnLctowFP0alu34DSx5JtOZJm2YTGl3ii2wprLlygJMv76SLYMtOUATNwG6snT1Puf43iu7Y4+i7IaCJPxMAog7lhFkHXvcsSzTsDz+EJZtYXEttzAsKQpkp71hhn7DcqS0rlAA01pHRghmKKkbfRLH0Gc1G6CUbOrdFgTXV03AEmqGmQ+wbv2GAhYW1l55LGG/hWgZliubXr9oiUDZWZ4kDUFANhWTPenYI0oIK0pRNoJYgFfiUoybPtO62xiFMTtlQO/x4fZHEmaPERjc38fDQQjnH0qY1wCv5IlHcrtsW2KwCRGDswT4or7hPHfsYcgizGsmL4I0KZBfoAzyxYYLhPGIYELz4fZ0OrVGI25PGSU/Ya1l6HYN3qKfRR5vDSmDWcUkz3YDSQQZ3fIustXty6NIoe1w3+xpc6UprDBW2oAUynI38x5LXpBw/gW0fQ3Z4XUgazrvjKypITu4TGTPDVjrWiXbe2dgbQ1YRhLka+BSsooDAdtYAHEEag3B7mTgTQwd87EzMaduO8haxnHNmtZbYutq2GqwwjgYiFyA13wM0pQjX0MSZojNK+XvgoCPrqyNM8lHXtmWlZhvfl6tVEaJ6n5YXivHPctBSlbUh8fdHgN0CdlxscGgltnojJ74MlCIAUPrej7UxKJc4QtB/GQ7wfTqerEtRQfFseWgavqizGPaSnzvKhMVuGgTceLBttItER1STXU7XF4uRO9/EaKtC3HmxRPM/Dv6tb+IvDv8CT8YZTg5EyHafbfuucwXKtHx6hN5rxXiM/v1mj3tXrXFjK1q2NQj1eWLuFGcp3rTUiVnomLFnTpGS+7UVuNzSyp2XcVtO26rKj7EbUXEv1aQFy1Dv9yef8plqzdbQ0+5+g2Kc1rIuA759QZ49evC5cFrNnw4eFN4r9EFvyqPMM/KAytysVUdnOyBHeW17v+jPEL1wFa7eUQjZc4VaviQLzyaRpxXLnxpGnaVdUzjDbII/cPCQIhk9YRRGsJUsLmG+S5JLM4iZND4VYcHInYo0MUkhkqMkyaA0TIWLwhfB3L7UIQ15AM8kA0RCgKxTGNkrcfeFkLlLjSqV6jqxx+zQbbqpb+1WKnfuUtOUJqTlRdjRvjjScDBn3mykl4vS+odoXxZ3o+lrsYSifE2f3Fgzk/KQOyLIlkUWSR3cD7k/k2QyELREsE0Ff/qLGNBSbQzy8zzWrl0DK/GZbenU9lrh0pe3f+MLHzo/peuPfkD</diagram></mxfile>

data/docs/diagrams/Pattern -- Event.drawio

@@ -0,0 +1 @@
+<mxfile modified="2019-07-14T14:31:23.619Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36" etag="mj5YSntAqhnDTmg4xXPi" version="10.9.6" type="google"><diagram id="y9hzfK7Ta8yHCBsTJmj-" name="Page-1">7VnLdpswEP0aL9sDEs+ljR/ZtOlpmtbJTgcUwwkgKuQY9+srgjAg+ZEmxE7irqwZvZg716OLGEAvKWYUZeEXEuB4ALSgGMDxAABdAxb/KT3rymMCs3IsaBSIQY3jKvqD65nCu4wCnHcGMkJiFmVdp0/SFPus40OUklV32B2Ju7tmaIEVx5WPYtX7KwpYWHmdOqzSf4GjRVjvrFtu1ZOgerCIJA9RQFYtF5wMoEcJYVUrKTwcl+DVuFTzpjt6Nw9GccqeMsG5/n5xm4XFdYKGl5fpaBji+aca5gcUL0XEI/G4bF1jsAojhq8y5Jf2iud5AEchS2Ju6byJ8qxC/i4qMN9sdBfFsUdiQh+nw+l0CjyP+3NGyT3u9IxMW+M9aiwivAdMGS5aLhHbDJMEM7rmQ0SvAUUogmhAE/aqSZspXGErY7UPCaIsNis3WPKGgPMfoHU/KrK6cWJkdQXZ4ftE1pGANU8MLPiolHVODCxUgGUki3wFXEqWaVDCNi6BOAC1gqA9GVoTTcV8bEz0qdkPspuyuoezOjgmtqaCrQIrToNhqQW45ccozznyHSRxEbF5q31TJuCzKaxxIfLxaKxrI+UPP28brVml2Ux7tOp5O3OQkyX18eGyxxBdYHaYbDjoKBs1o0/8M1AcIxY9dPXQtiyKHb6RiEe2q8ZBIPGgCltMassXaR1dPt9taaEKF2Uhnni0bg3LygH57ufVbYngtilRtFqxIewG0udz2DoXDsMnchi8KQ5D1+xyQn8miQ2ru5D1OhyGrsRh7Qgc1lVZ5r1P9WBKZxw4tS7TVWF25vXBfVP1QTrjDK2nMw7KjOqrPsgvHtYx6oMqgs+cxPUp8p/FvbAYgGOw2DhjFoOvq+zn7P4HAWPHSeybWTEf168lH4zEmwvoXe8tfZHYkEjsdm5xX0zifSlrcfj3EvOmTOSjXEcoumwLXXdKNWg5XfhsVaq5W9hm9CDVtkKrKrXTieAXISuLYKgfTwRvRfZdygepKh6sxPv+rof1xJuqvLAv+eC8TuU1ZPnwsosebjbf8qrhzRdROPkL</diagram></mxfile>

data/docs/diagrams/Pattern -- Query.drawio

@@ -0,0 +1 @@
+<mxfile modified="2019-07-14T14:14:30.733Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36" etag="VIpIcM9pChy9e7uzRAZn" version="10.9.6" type="google"><diagram id="y9hzfK7Ta8yHCBsTJmj-" name="Page-1">5VdNc5swEP01HJsBZLBzNDZ2Lp106sk07U0BGTQRiAoR4/z6SkYYhOzE8cQdd+qLtU+7+nj7kFYWmGX1ksEi/UpjRCzXjmsLzC3XdWzXF38S2TaI53oNkDAcK6cOWOFX1EYqtMIxKjVHTinhuNDBiOY5iriGQcboRndbU6LPWsAEGcAqgsREf+CYpw06abcl8TuEk7Sd2fFvm54Mts5qJ2UKY7rpQSC0wIxRyptWVs8QkeS1vDRxiyO9+4UxlPNTAiYP3+9+FWn9kMHp/X0eTFP0+EWN8gJJpTY8Vavl25aCTYo5WhUwkvZGpNkCQcozIixHNGFZNMSvcY3EXMEaEzKjhLJdOFgsFu5sJvCSM/qMtJ7AG9uix9xKuy7EOKp7kNraEtEMcbYVLm1vS/N2YG+6rHkKSnsJazGodJLsR+6oFA3F5geYdQ1mg3+T2RG4MmaBwezvConmkF1GqzyWvM0lE+9wbVA4Dqd+aJukz0ehs/A+h1p3pFM7MZnds/1XqPUMag1WUR5P5bkqrIjAssSRTiSqMX/stX9K/m88Zc1rlY6dsW2NXCz+sW/0oqTZhe2sNu5oCkpasQi9f+5xyBLE39cairVbwkzoid8CQwRy/KLfLYeyqGb4RrHY2dFDzhBCs28V1b8LhgONBwPZg4EaYoyBRObhtudWSIfy+IL313h7dtjeQKPNiJ1i95yeL2L/fxExOFHE7lWJGNx6uiacM0U88vWB/MtoGNxeVsN3i3n+EPoAb5YurtgSVqvwwB13toZtTcPjE0Xs6CIeX07F7okqdq5LxYOjGJyrYjA8ik+U8WcpbWQojaGyoHlpFlSiquG6xoQrfoVPOwepAvUtCW8vsLy5rGEJTnIpUaELJEqoQFZHWLyvpqojw3Es4wMCnxAJYPSc7Aq3Xsm13v0OiuzNj2dYh+1fiWrFVv8hdqg+s29sMPE+RS+Do0oPp+t1iT6YXWF2b8fGvXuBg/AP</diagram></mxfile>

data/examples/basic_event_listener.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Base class for an event listener with DSL magic
+#
+# Usage:
+#   class HelloListener < BasicEventListener
+#     topic "hello", using_queue: "listener.hello"
+#
+#     def world
+#      puts "hello/world event received: #{message}"
+#     end
+#   end
+#
+class BasicEventListener
+  attr_reader :message
+
+  def initialize(message, _opts = {})
+    @message = message
+  end
+
+  def self.call_event(method_name, message, opts)
+    new(message, opts).send(method_name.to_sym)
+  end
+
+  # Subclass exposes itself by declaring the event topic that it is going to listen for,
+  # and an optional :using_queue parameter.
+  #
+  def self.topic(topic_name, params = {})
+    if params[:using_queue]
+      Mimi::Messaging.register_event_processor_with_queue(topic_name, params[:using_queue], self)
+    else
+      Mimi::Messaging.register_event_processor(topic_name, params[:using_queue], self)
+    end
+  end
+end # class BasicEventListener

data/examples/basic_request_processor.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Base class for a request (command and query) processor with DSL magic.
+#
+# Usage:
+#   class HelloProcessor < BasicRequestProcessor
+#     queue "hello"
+#
+#     def world
+#      puts "hello/world called with the message: #{message}"
+#     end
+#   end
+#
+#
+class BasicRequestProcessor
+  attr_reader :message
+
+  def initialize(message, _opts = {})
+    @message = message
+  end
+
+  def self.call_command(method_name, message, opts)
+    new(message, opts).send(method_name.to_sym)
+  end
+
+  def self.call_query(method_name, message, opts)
+    result = new(message, opts).send(method_name.to_sym)
+    return result if result.is_a?(Hash)
+
+    raise "#{name}##{method_name}() is expected to return a Hash, but returned #{result.class}"
+  end
+
+  # Subclass exposes itself by declaring the queue that is used to accept requests
+  #
+  def self.queue(queue_name)
+    Mimi::Messaging.register_request_processor(queue_name, self)
+  end
+end # class BasicRequestProcessor

data/examples/using_messaging_low.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+#
+# Using Mimi::Messaging lower-level abstraction,
+# without using the adapter directly
+#
+
+require "mimi/messaging"
+require "logger"
+require_relative "basic_request_processor"
+require_relative "basic_event_listener"
+
+#
+# An example request processor class
+#
+class HelloProcessor < BasicRequestProcessor
+  queue "hello"
+
+  def world
+    puts "hello/world request received: #{message}"
+    { a: 1 }
+  end
+
+  def command
+    puts "hello/command request received: #{message}"
+  end
+end # class HelloProcessor
+
+#
+# An example event listener class
+#
+class HelloListener < BasicEventListener
+  topic "hello", using_queue: "listener.hello"
+
+  def world
+    puts "hello/world event received: #{message}"
+  end
+end # class HelloListener
+
+#
+Mimi::Messaging.use(
+  serializer: Mimi::Messaging::JsonSerializer,
+  logger: Logger.new(STDOUT)
+)
+Mimi::Messaging.configure(mq_adapter: :memory)
+Mimi::Messaging.start
+
+result = Mimi::Messaging.command("hello/world", a: 123)
+puts "Response: #{result}"
+puts
+
+result = Mimi::Messaging.query("hello/world", b: 456)
+puts "Response: #{result}"
+puts
+
+Mimi::Messaging.event("hello/world", c: 789)
+puts
+
+Mimi::Messaging.stop