# A python toolkit to develop services within the Allo-Media event-driven architecture, with debug utilities.
## Overview
The Allo-Media event-driven service architecture is language and framework independent and is described in the following document:
https://blog.uh.live/2020/02/17/an-event-drive-architecture/
### eventail.async_service
This package provides base classes for implementating fully asynchronous services conforming to this architecture on RabbitMQ.
To develop a service, just inherit one of the class (either `async_service.pika.Service` or `async_service.aio.Service` if you want async/await) and provide a concrete implementation of the abstract methods to code the specific behavior of your service.
All the burden of communication, message safety, recovery, availability, load balancing and queue/exchange setup is taken care for you by this base class and RabbitMQ. It also provides a kind of supervisor to ensure automatic reconnection after a network failure.
You just need to focus on the service logic you develop and then you can deploy as many instances of your service as you see fit, anywhere on the network, and the load will be automatically load-balanced between them.
### eventail.sync_publisher
A kombu based synchronous Endpoint for publishing purposes only (events and logs). This is provided to help you port legacy applications to the EDA.
### Command line utilities
This package also provide some debugging command line tools :
- a logger that can target specific logs (service & criticity) through topic subscription;
- a utility to send events on the bus;
- a utility to send a command on the bus, wait for its result and display the outcome;
- a utility to monitor events and/or commands;
- a utility to inspect queues;
- and a utility to resurrect (replay) dead messages.
### Note about dead letters
The base code does not create the dead-letters exchange (DLX) for you, nor the dead-letter queues. It's good practice to do it once and configure the queues with a policy :
```
rabbitmqctl set_policy DLX ".*\.events|.*\.commands" '{"dead-letter-exchange":"am-dlx"}' --apply-to queues
```
Note that a policy applies to existing **and future** queues as well, so you don't have to reissue those commands each time a new service appears!
## Usage
### API
The API documentation is on [ReadTheDocs](https://eventail.readthedocs.io/).
### Utilities
Once installed (`pip install -e .`), these commands are in you virtualenv path:
```
logger.py --help
usage: logger.py [-h] [--filter [FILTER [FILTER ...]]] amqp_url
Display selected logs in realtime on the given broker
positional arguments:
amqp_url URL of the broker, including credentials
optional arguments:
-h, --help show this help message and exit
--filter [FILTER [FILTER ...]]
Log patterns to subscribe to (default to all)
```
```
usage: monitor.py [-h] [--events [EVENTS [EVENTS ...]]] [--commands [COMMANDS [COMMANDS ...]]] [--save]
amqp_url
Monitor selected Events and/or Commands on the given broker
positional arguments:
amqp_url URL of the broker, including credentials
optional arguments:
-h, --help show this help message and exit
--events [EVENTS [EVENTS ...]]
Event patterns to subscribe to (default to all)
--commands [COMMANDS [COMMANDS ...]]
Command patterns to subscribe to (default to all)
--save save payloads in CBOR format.
```
```
publish_event.py --help
usage: publish_event.py [-h] amqp_url event payload
Publish an Event and its payload on the given broker
positional arguments:
amqp_url URL of the broker, including credentials
event Event Name
payload The path to the file containing the payload, in JSON or
CBOR format (from file extension).
optional arguments:
-h, --help show this help message and exit
```
```
usage: publish_configuration.py [-h] amqp_url event payload
Publish a configuration event and its payload on the given broker
positional arguments:
amqp_url URL of the broker, including credentials
event Configuration event name
payload The path to the file containing the payload, in JSON or
CBOR format (from file extension).
optional arguments:
-h, --help show this help message and exit
```
```
send_command.py --help
usage: send_command.py [-h] amqp_url command payload
Send a service command and its payload on the given broker and waits for its result.
positional arguments:
amqp_url URL of the broker, including credentials
command Command in the form service.command
payload The path to the file containing the payload, in JSON or
CBOR format (from file extension).
optional arguments:
-h, --help show this help message and exit
```
```
inspect_queue.py --help
usage: inspect_queue.py [-h] [--count COUNT] [--save] amqp_url queue
Dump the content of a queue without consuming it.
positional arguments:
amqp_url URL of the broker, including credentials.
queue Name of queue to inspect.
optional arguments:
-h, --help show this help message and exit
--count COUNT Number of message to dump (default is 0 = all).
--save save payloads in original format.
```
```
resurrect.py --help
usage: resurrect.py [-h] [--count COUNT] [--batch_size BATCH_SIZE] amqp_url queue
Resend dead letters.
positional arguments:
amqp_url URL of the broker, including credentials.
queue Name of dead-letter queue.
optional arguments:
-h, --help show this help message and exit
--count COUNT Number of message to resurrect (default is 0 = all).
--batch_size BATCH_SIZE
for more efficiency, if the messages are small, process them in batches of
this size (default is 1).
```
Raw data
{
"_id": null,
"home_page": "https://github.com/allo-media/eventail",
"name": "eventail",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Allo-Media",
"author_email": "dev@allo-media.fr",
"download_url": "https://files.pythonhosted.org/packages/c2/f7/74e3c93401461aa1fce1b9be776a4922bf4316111668f537f55c42e82650/eventail-2.3.3.tar.gz",
"platform": null,
"description": "\n\n\n\n# A python toolkit to develop services within the Allo-Media event-driven architecture, with debug utilities.\n\n## Overview\n\nThe Allo-Media event-driven service architecture is language and framework independent and is described in the following document:\n\nhttps://blog.uh.live/2020/02/17/an-event-drive-architecture/\n\n### eventail.async_service\n\nThis package provides base classes for implementating fully asynchronous services conforming to this architecture on RabbitMQ.\nTo develop a service, just inherit one of the class (either `async_service.pika.Service` or `async_service.aio.Service` if you want async/await) and provide a concrete implementation of the abstract methods to code the specific behavior of your service.\n\nAll the burden of communication, message safety, recovery, availability, load balancing and queue/exchange setup is taken care for you by this base class and RabbitMQ. It also provides a kind of supervisor to ensure automatic reconnection after a network failure.\n\nYou just need to focus on the service logic you develop and then you can deploy as many instances of your service as you see fit, anywhere on the network, and the load will be automatically load-balanced between them.\n\n### eventail.sync_publisher\n\nA kombu based synchronous Endpoint for publishing purposes only (events and logs). This is provided to help you port legacy applications to the EDA.\n\n### Command line utilities\n\nThis package also provide some debugging command line tools :\n\n - a logger that can target specific logs (service & criticity) through topic subscription;\n - a utility to send events on the bus;\n - a utility to send a command on the bus, wait for its result and display the outcome;\n - a utility to monitor events and/or commands;\n - a utility to inspect queues;\n - and a utility to resurrect (replay) dead messages.\n\n### Note about dead letters\n\nThe base code does not create the dead-letters exchange (DLX) for you, nor the dead-letter queues. It's good practice to do it once and configure the queues with a policy :\n\n```\nrabbitmqctl set_policy DLX \".*\\.events|.*\\.commands\" '{\"dead-letter-exchange\":\"am-dlx\"}' --apply-to queues\n```\n\nNote that a policy applies to existing **and future** queues as well, so you don't have to reissue those commands each time a new service appears!\n\n## Usage\n\n\n### API\n\nThe API documentation is on [ReadTheDocs](https://eventail.readthedocs.io/).\n\n\n### Utilities\n\nOnce installed (`pip install -e .`), these commands are in you virtualenv path:\n\n```\nlogger.py --help\nusage: logger.py [-h] [--filter [FILTER [FILTER ...]]] amqp_url\n\nDisplay selected logs in realtime on the given broker\n\npositional arguments:\n amqp_url URL of the broker, including credentials\n\noptional arguments:\n -h, --help show this help message and exit\n --filter [FILTER [FILTER ...]]\n Log patterns to subscribe to (default to all)\n```\n\n```\nusage: monitor.py [-h] [--events [EVENTS [EVENTS ...]]] [--commands [COMMANDS [COMMANDS ...]]] [--save]\n amqp_url\n\nMonitor selected Events and/or Commands on the given broker\n\npositional arguments:\n amqp_url URL of the broker, including credentials\n\noptional arguments:\n -h, --help show this help message and exit\n --events [EVENTS [EVENTS ...]]\n Event patterns to subscribe to (default to all)\n --commands [COMMANDS [COMMANDS ...]]\n Command patterns to subscribe to (default to all)\n --save save payloads in CBOR format.\n\n```\n\n```\npublish_event.py --help\nusage: publish_event.py [-h] amqp_url event payload\n\nPublish an Event and its payload on the given broker\n\npositional arguments:\n amqp_url URL of the broker, including credentials\n event Event Name\n payload The path to the file containing the payload, in JSON\u00a0or\n CBOR\u00a0format (from file extension).\n\noptional arguments:\n -h, --help show this help message and exit\n```\n\n```\nusage: publish_configuration.py [-h] amqp_url event payload\n\nPublish a configuration event and its payload on the given broker\n\npositional arguments:\n amqp_url URL of the broker, including credentials\n event Configuration event name\n payload The path to the file containing the payload, in JSON\u00a0or\n CBOR\u00a0format (from file extension).\n\noptional arguments:\n -h, --help show this help message and exit\n```\n\n```\nsend_command.py --help\nusage: send_command.py [-h] amqp_url command payload\n\nSend a service command and its payload on the given broker and waits for its result.\n\npositional arguments:\n amqp_url URL of the broker, including credentials\n command Command in the form service.command\n payload The path to the file containing the payload, in JSON\u00a0or\n CBOR\u00a0format (from file extension).\n\noptional arguments:\n -h, --help show this help message and exit\n```\n\n```\ninspect_queue.py --help\nusage: inspect_queue.py [-h] [--count COUNT] [--save] amqp_url queue\n\nDump the content of a queue without consuming it.\n\npositional arguments:\n amqp_url URL of the broker, including credentials.\n queue Name of queue to inspect.\n\noptional arguments:\n -h, --help show this help message and exit\n --count COUNT Number of message to dump (default is 0 = all).\n --save save payloads in original format.\n```\n\n```\nresurrect.py --help\nusage: resurrect.py [-h] [--count COUNT] [--batch_size BATCH_SIZE] amqp_url queue\n\nResend dead letters.\n\npositional arguments:\n amqp_url URL of the broker, including credentials.\n queue Name of dead-letter queue.\n\noptional arguments:\n -h, --help show this help message and exit\n --count COUNT Number of message to resurrect (default is 0 = all).\n --batch_size BATCH_SIZE\n for more efficiency, if the messages are small, process them in batches of\n this size (default is 1).\n\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A base class and utilities for AM service architecture",
"version": "2.3.3",
"project_urls": {
"Homepage": "https://github.com/allo-media/eventail"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b7b5a7de272d282e1ab0db3d72e06919ca946056f56829a287987088c2877016",
"md5": "c1f3d421f0c4db47512ccc03536b6f63",
"sha256": "40771d8018d1dccf048eb2dfdf60257cb09c6ce318511945bbfe42dc61942f4e"
},
"downloads": -1,
"filename": "eventail-2.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c1f3d421f0c4db47512ccc03536b6f63",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 42378,
"upload_time": "2024-12-13T09:24:54",
"upload_time_iso_8601": "2024-12-13T09:24:54.254788Z",
"url": "https://files.pythonhosted.org/packages/b7/b5/a7de272d282e1ab0db3d72e06919ca946056f56829a287987088c2877016/eventail-2.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c2f774e3c93401461aa1fce1b9be776a4922bf4316111668f537f55c42e82650",
"md5": "c4da251396b1ddcd3c519153484d4362",
"sha256": "9851c5611554f8b80740d94b930a66d7014bbf60faf121bbdb7304206a500577"
},
"downloads": -1,
"filename": "eventail-2.3.3.tar.gz",
"has_sig": false,
"md5_digest": "c4da251396b1ddcd3c519153484d4362",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29263,
"upload_time": "2024-12-13T09:24:55",
"upload_time_iso_8601": "2024-12-13T09:24:55.381913Z",
"url": "https://files.pythonhosted.org/packages/c2/f7/74e3c93401461aa1fce1b9be776a4922bf4316111668f537f55c42e82650/eventail-2.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 09:24:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "allo-media",
"github_project": "eventail",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"tox": true,
"lcname": "eventail"
}
JSON
