ACA-PY Redis Queue Plugin

This plugin provides mechansim to persists both inbound and outbound messages, deliver messages and webhooks, and dispatch events.

For receiving inbound messages, you have an option to either setup a mediator or a relay [supports direct response].

For the mediator scenario:

  flowchart LR;
      InboundMsg([Inbound Msg])-->Mediator;
      Mediator-->InboundQueue[(Inbound Queue)];
      InboundQueue-->YourAgent{{Your Agent}};

For the relay scenario:

  flowchart LR;
      InboundMsg([Inbound Msg])-->Relay;
      Relay-->InboundQueue[(Inbound Queue)];
      InboundQueue-->YourAgent{{Your Agent}};

The demo directory contains a working example/template for both:

docker-compose.yml for mediation, and
docker-compose.relay.yml for relay

The deliverer service dispatches the outbound messages and webhooks. For the events, the payload is pushed to the relevant Redis LIST [for the topic name, refer to event.event_topic_maps] and further action is delegated to the controllers.

For the outbound scenario:

  flowchart LR;
      YourAgent{{Your Agent}}-->OutboundQueue[(Outbound Queue)];
      OutboundQueue-->Deliverer;
      Deliverer-->OutboundMsg([Outbound Msg]);

Code Structure

The directory structure within this repository is as follows:

│    
│
└───redis_deliverer
│   deliver.py
└───redis_queue
│   └───events
│   inbound
│   outbound
│   config
│   utils
└───redis_relay
│   └───relay
|   |   relay
└───status_endpoint
|   status_endpoint
└───int
└───demo
└───docker
|

The code for the Deliverer and Relay processes are in the redis_deliverer and redis_relay directories, respectively. The status_endpoint directory contains code for health endpoints that is used by both of these processes.

The docker directory contains a dockerfile (and instructions) for running aca-py with the redis plugin.

The demo diretory contains example docker-compose files for running aca-py with redis using either of the Relay or Mediator scenarios.

Documentation

Design

Covered in ./redis_queue/README.md

Demo

Covered in ./demo/README.md

Docker

Covered in ./docker/README.md

Installation and Usage

First, install this plugin into your environment:

$ pip install git+https://github.com/bcgov/aries-acapy-plugin-redis-events.git

When starting up ACA-Py, load the plugin along with any other startup parameters:

$ aca-py start --arg-file my_config.yml --plugin redis_queue.v1_0.events

Plugin configuration

The redis plugin is configured using an external yaml file. An example yaml configuration is:

redis_queue:
  connection: 
    connection_url: "redis://default:test1234@172.28.0.103:6379"

  ### For Inbound ###
  inbound:
    acapy_inbound_topic: "acapy_inbound"
    acapy_direct_resp_topic: "acapy_inbound_direct_resp"

  ### For Outbound ###
  outbound:
    acapy_outbound_topic: "acapy_outbound"
    mediator_mode: false

  ### For Event ###
  event:
    event_topic_maps:
      ^acapy::webhook::(.*)$: acapy-webhook-$wallet_id
      ^acapy::record::([^:]*)::([^:]*)$: acapy-record-with-state-$wallet_id
      ^acapy::record::([^:])?: acapy-record-$wallet_id
      acapy::basicmessage::received: acapy-basicmessage-received
      acapy::problem_report: acapy-problem_report
      acapy::ping::received: acapy-ping-received
      acapy::ping::response_received: acapy-ping-response_received
      acapy::actionmenu::received: acapy-actionmenu-received
      acapy::actionmenu::get-active-menu: acapy-actionmenu-get-active-menu
      acapy::actionmenu::perform-menu-action: acapy-actionmenu-perform-menu-action
      acapy::keylist::updated: acapy-keylist-updated
      acapy::revocation-notification::received: acapy-revocation-notification-received
      acapy::revocation-notification-v2::received: acapy-revocation-notification-v2-received
      acapy::forward::received: acapy-forward-received
    event_webhook_topic_maps:
      acapy::basicmessage::received: basicmessages
      acapy::problem_report: problem_report
      acapy::ping::received: ping
      acapy::ping::response_received: ping
      acapy::actionmenu::received: actionmenu
      acapy::actionmenu::get-active-menu: get-active-menu
      acapy::actionmenu::perform-menu-action: perform-menu-action
      acapy::keylist::updated: keylist
    deliver_webhook: true

The configuration parameters in the above example are:

Connection:

redis_queue.connection.connection_url: This is required and is expected in redis://{username}:{password}@{host}:{port} format.

Inbound:

redis_queue.inbound.acapy_inbound_topic: This is the topic prefix for the inbound message queues. Recipient key of the message are also included in the complete topic name. The final topic will be in the following format acapy_inbound_{recip_key}
redis_queue.inbound.acapy_direct_resp_topic: Queue topic name for direct responses to inbound message.

Outbound:

redis_queue.outbound.acapy_outbound_topic: Queue topic name for the outbound messages. Used by Deliverer service to deliver the payloads to specified endpoint.
redis_queue.outbound.mediator_mode: Set to true, if using Redis as a http bridge when setting up a mediator agent. By default, it is set to false.

Events:

event.event_topic_maps: Event topic map
event.event_webhook_topic_maps: Event to webhook topic map
event.deliver_webhook: When set to true, this will deliver webhooks to endpoints specified in admin.webhook_urls. By default, set to true.

Plugin deployment

Once the plugin config is defined, it is possible to deploy the plugin inside ACA-Py.

$ aca-py start \
    --plugin redis_queue.v1_0.events \
    --plugin-config plugins-config.yaml \
    -it redis_queue.v1_0.inbound redis 0 -ot redis_queue.v1_0.outbound
    # ... the remainder of your startup arguments

Status Endpoints

Relay and Deliverer service have the following service endpoints available:

GET http://{STATUS_ENDPOINT_HOST}:{STATUS_ENDPOINT_PORT}/status/ready
GET http://{STATUS_ENDPOINT_HOST}:{STATUS_ENDPOINT_PORT}/status/live

The configuration for the endpoint service can be provided as following for relay and deliverer. The API KEY should be provided in the header with access_token as key name.

environment:
    - STATUS_ENDPOINT_HOST=0.0.0.0
    - STATUS_ENDPOINT_PORT=7001
    - STATUS_ENDPOINT_API_KEY=test_api_key_1

dbluhm / aries-acapy-plugin-redis-events