From 985f562e923a0079663dda4cd2c6621b9dcbe101 Mon Sep 17 00:00:00 2001 From: "Colton Wolkins (Indicio work address)" Date: Wed, 13 Jul 2022 07:11:38 -0600 Subject: [PATCH 1/5] chore: Update documentation Signed-off-by: Colton Wolkins (Indicio work address) --- README.md | 42 ++++++++++++++++++++++++++++++++---------- 1 file changed, 32 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 0f45ba6..e7ef1dc 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,30 @@ -# acapy-cache-redis -Redis Base Cache Plugin +# aries-acapy-cache-redis +ACA-Py Redis Base Cache Plugin ======================================= -[Add description] +ACA-Py uses a modular cache layer to story key-value pairs of data. The purpose +of this plugin is to allow ACA-Py to use Redis as the storage medium for it's +caching needs. ## Installation and Usage +### With Docker (Recommended) +Running the plugin with docker is simple and straight-forward. There is an +example [docker-compose.yml](./docker-compose.yml) file in the root of the +project that launches both ACA-Py and an accompanying Redis instance. Running +it is as simple as: + +```sh +$ docker-compose up --build +``` + +If you are looking to integrate the plugin with your own projects, it is highly +recommended to take a look at both th +[docker-compose.yml](./docker-compose.yml) and the [ACA-Py +default.yml](./docker/default.yml) files to help kickstart your project. + +### Without Docker + First, install this plugin into your environment. ```sh @@ -13,14 +32,15 @@ $ poetry install $ poetry shell ``` -Local redis server for development. +Launch a local redis server for development. ```sh -$ docker run -v /redis.conf:/usr/local/etc/redis --name redis_cache redis redis-server /usr/local/etc/redis/redis.conf +$ docker run -d -v `pwd`/redis.conf:/usr/local/etc/redis/redis.conf \ + --name redis_cache -p 6379:6379 redis redis-server /usr/local/etc/redis/ ``` When starting up ACA-Py, load the plugin along with any other startup -parameters. +parameters. *Note: You may need to change the redis hostname* ```sh $ aca-py start --arg-file ./docker/default.yml @@ -29,11 +49,13 @@ $ aca-py start --arg-file ./docker/default.yml For manual testing with a second ACA-Py instance, you can run the following. ```sh -$ aca-py start --arg-file ./docker/default.yml --admin 0.0.0.0 3003 -it http 0.0.0.0 3002 -e http://localhost:3002 +$ aca-py start --arg-file ./docker/default.yml --admin 0.0.0.0 3003 \ + -it http 0.0.0.0 3002 -e http://localhost:3002 ``` -## Running Tests for development +## Running The Integration Tests ```sh -pytest --cov-report term-missing --cov -``` \ No newline at end of file +$ docker-compose -f int/docker-compose.yml build +$ docker-compose -f int/docker-compose.yml run tests +``` From 4dcdde798ddd31c61bd221854759a56cf3038638 Mon Sep 17 00:00:00 2001 From: "Colton Wolkins (Indicio work address)" Date: Wed, 13 Jul 2022 07:27:11 -0600 Subject: [PATCH 2/5] chore: Add configuration section to the readme Signed-off-by: Colton Wolkins (Indicio work address) --- README.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e7ef1dc..f9f4f58 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,9 @@ $ docker-compose up --build ``` If you are looking to integrate the plugin with your own projects, it is highly -recommended to take a look at both th -[docker-compose.yml](./docker-compose.yml) and the [ACA-Py -default.yml](./docker/default.yml) files to help kickstart your project. +recommended to take a look at both [docker-compose.yml](./docker-compose.yml) +and the [ACA-Py default.yml](./docker/default.yml) files to help kickstart your +project. ### Without Docker @@ -53,6 +53,22 @@ $ aca-py start --arg-file ./docker/default.yml --admin 0.0.0.0 3003 \ -it http 0.0.0.0 3002 -e http://localhost:3002 ``` +### Configuration +Within the [default.yml](./docker/default.yml) file, all configuration for the +Redis Base Cache Plugin resides within the `plugin-config-value` block. The +configuration options are defined as follows: + - `redis_cache.connection` The host connection URI for the Redis server. A + different DB can be selected by adding a `/0` or `/1` to the end of the URI + - The URI may start with `rediss://` for SSL connections and `redis://` for + non-SSL connections + - `redis_cache.max_connections` The maximum number of connections to Redis + that the connection pool may allocate + - `redis_cache.credentials.username` Username for the Redis server (if not + using the default user) + - `redis_cache.credentials.password` The password for the Redis server/user + - `redis_cache.ssl.cacerts` Path to the root CA information. Useful for when + using self-signed certificates. + ## Running The Integration Tests ```sh From 0a2ea6d3f3548462daae523e63a340d855c2d78e Mon Sep 17 00:00:00 2001 From: "Colton Wolkins (Indicio work address)" Date: Wed, 13 Jul 2022 10:24:35 -0600 Subject: [PATCH 3/5] chore: Add reason for plugin in README.md Signed-off-by: Colton Wolkins (Indicio work address) --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f9f4f58..9c93f95 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,13 @@ ACA-Py Redis Base Cache Plugin ACA-Py uses a modular cache layer to story key-value pairs of data. The purpose of this plugin is to allow ACA-Py to use Redis as the storage medium for it's -caching needs. +caching needs. When multiple instances of ACA-Py are running, and have a load +balancer distributing the requests, it is possible for requests during the same +exchange to be sent to different instances of ACA-Py. Normally, information for +these requests is cached using the built-in in-memory cache. However, if the +requests go from agent A, to agent B, then back to agent A, the cache may have +invalid data that needs to be refreshed since it is all in-memory. Switching +the backing store from memory to Redis should eliminate this problem entirely. ## Installation and Usage From 257aa43955d4c4a4e15d5bbfbc5455944d44a21e Mon Sep 17 00:00:00 2001 From: "Colton Wolkins (Indicio work address)" Date: Wed, 13 Jul 2022 10:39:05 -0600 Subject: [PATCH 4/5] Revert "chore: Add reason for plugin in README.md" This reverts commit 0a2ea6d3f3548462daae523e63a340d855c2d78e. Signed-off-by: Colton Wolkins (Indicio work address) --- README.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/README.md b/README.md index 9c93f95..f9f4f58 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,7 @@ ACA-Py Redis Base Cache Plugin ACA-Py uses a modular cache layer to story key-value pairs of data. The purpose of this plugin is to allow ACA-Py to use Redis as the storage medium for it's -caching needs. When multiple instances of ACA-Py are running, and have a load -balancer distributing the requests, it is possible for requests during the same -exchange to be sent to different instances of ACA-Py. Normally, information for -these requests is cached using the built-in in-memory cache. However, if the -requests go from agent A, to agent B, then back to agent A, the cache may have -invalid data that needs to be refreshed since it is all in-memory. Switching -the backing store from memory to Redis should eliminate this problem entirely. +caching needs. ## Installation and Usage From 155e5bbb2b825bb873b27ce7f879c88a139e4fb2 Mon Sep 17 00:00:00 2001 From: "Colton Wolkins (Indicio work address)" Date: Wed, 13 Jul 2022 10:57:28 -0600 Subject: [PATCH 5/5] chare: Rework description about how the plugin helps Signed-off-by: Colton Wolkins (Indicio work address) --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index f9f4f58..5f1d1c8 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,18 @@ ACA-Py uses a modular cache layer to story key-value pairs of data. The purpose of this plugin is to allow ACA-Py to use Redis as the storage medium for it's caching needs. +_**Why might I need this plugin?**_ +When demand increases, horizontal scaling helps relieve the stress on systems +by spreading the load across multiple systems. Depending on the algorithm used +to distribute requests across a cluster, the requests from an individual +connection may end up on different hosts partway though an exchange of +information. Normally, ACA-Py caches certain key data *in-memory* to create +some relief on the database. This has the unintended side-effect of the cache +getting out of data if the requests switch between machines. Using an external +system, such as Redis, to manage the cache can ensure that it stays up-to-date +amongst machines and continues to provide some relief to the database. + + ## Installation and Usage ### With Docker (Recommended)