s# Hyperledger Indy Catalyst Agent

Table of Contents

• Introduction
• Installing
• Running
• Developing
  • Prerequisites
  • Running Locally
    • Caveats
  • Running Tests
  • Development Workflow

Introduction

Indy Catalyst Agent is a configurable instance of a "Cloud Agent".

Installing

Instructions forthcoming. indy_catalyst_agent will be made available in the future as a python package at pypi.org.

Running

After installing the package, icatagent should be available in your PATH.

Find out more about the available command line parameters by running:

icatagent --help

Currently you must specify at least one inbound and one outbound transport.

For example:

icatagent   --inbound-transport http 0.0.0.0 8000 \
            --inbound-transport http 0.0.0.0 8001 \
            --inbound-transport ws 0.0.0.0 8002 \
            --outbound-transport ws \
            --outbound-transport http

Currently, Indy Catalyst Agent ships with both inbound and outbound transport drivers for http and websockets. More information on how to develop your own drivers will be coming soon.

Developing

Prerequisites

Docker must be installed to run software locally and to run the test suite.

Running Locally

To run the locally, we recommend using the provided Docker images to run the software.

./scripts/run_docker <args>

./scripts/run_docker --inbound-transport http 0.0.0.0 10000 --outbound-transport http --debug --log-level DEBUG

To enable the ptvsd Python debugger for Visual Studio/VSCode use the debug flag

For any ports you will be using, you can publish these ports from the docker container using the PORTS environment variable. For example:

PORTS="5000:5000 8000:8000 1000:1000" ./scripts/run_docker --inbound-transport http 0.0.0.0 10000 --outbound-transport http --debug --log-level DEBUG

Refer to the previous section for instructions on how to run the software.

Running Tests

To run the test suite, use the following script:

./scripts/run_tests

To run the test including Indy SDK and related dependencies, run the script:

./scripts/run_tests_indy

Development Workflow

We use Flake8 to enforce a coding style guide.

We use Black to automatically format code.

Please write tests for the work that you submit.

Tests should reside in a directory named tests alongside the code under test. Generally, there is one test file for each file module under test. Test files must have a name starting with test_ to be automatically picked up the test runner.

There are some good examples of various test scenarios for you to work from including mocking external imports and working with async code so take a look around!

The test suite also displays the current code coverage after each run so you can see how much of your work is covered by tests. Use your best judgement for how much coverage is sufficient.

Please also refer to the contributing guidelines and code of conduct.

Dynamic Injection of Services

The Agent employs a dynamic injection system whereby providers of base classes are registered with the RequestContext instance, currently within conductor.py. Message handlers and services request an instance of the selected implementation using await context.inject(BaseClass); for instance the wallet instance may be injected using wallet = await context.inject(BaseWallet). The inject method normally throws an exception if no implementation of the base class is provided, but can be called with required=False for optional dependencies (in which case a value of None may be returned).

Providers are registered with either context.injector.bind_instance(BaseClass, instance) for previously-constructed (singleton) object instances, or context.injector.bind_provider(BaseClass, provider) for dynamic providers. In some cases it may be desirable to write a custom provider which switches implementations based on configuration settings, such as the wallet provider.

The BaseProvider classes in the config.provider module include ClassProvider, which can perform dynamic module inclusion when given the combined module and class name as a string (for instance indy_catalyst_agent.wallet.indy.IndyWallet). ClassProvider accepts additional positional and keyword arguments to be passed into the class constructor. Any of these arguments may be an instance of ClassProvider.Inject(BaseClass), allowing dynamic injection of dependencies when the class instance is instantiated.