backbone-adapter-python
Generic adapter for the communications-backbone.
Implements:
- client credentials grant
- http send/receive/notify to backbone
- validation of messages against a specified OpenAPI schema
- decode/encode stubs
Setup
pip install -r requirements.txt
python -m testsuite.copy_tests
Test
The tests are written in behave
This means we can have a common suite of gherkin tests across adapter ports written in multiple languages.
behave
Example implementation
There's an example using the python client in ./example.
There's a README to explain what it does and how to set it up.
Installing in your project
We may publish this to a public registry but for now you need to install the package from git.
Requirements
Python >= 3.8
Pip
It should also work with pipenv or poetry. You might have to tinker with the git url syntax in different package managers.
echo backbone-adapter-python @ git+https://git.noc.ac.uk/communications-backbone-system/backbone-adapter-python.git@[tag|branch|commit]#egg=backbone-adapter-python >> requirements.txt
pip install -r requirements.txt
Importing
Because the repo name contains hyphens I've named the importable package
from backbone_adapter.adapter import Adapter
from backbone_adapter.protocol import GenericProtocol
Schema
The example code uses a mock schema with some example messages. The intention is the message protocol schema is retreived from an external source.
Config
To run the adapter you need a credentials file called soar-config.json
.
This will be provided by the backbone operator or requested via the API.
{
"api": "[backbone api root url]",
"client_id": "unique-client-id",
"client_name": "UniqueClientName",
"subscription": "dot.delimited.topic.subscription.#",
"secret": "[a generated secret]"
}
Topics
When sending messages you should publish them using a topic matching this definition.
Encoding and decoding
Decoding
Decoding refers to translation from the backbone message protocol into a native format for the client app to process.
All messages received from the backbone are parsed and validated against the protocol schema and then passed to the protocol decode function.
By overriding the decode function the client can define local actions to be executed when a message of a given type is received.
Encoding
Encoding refers to translation from the client app's native format into a message conforming to the backbone message protocol.
The equivalent encode method allows the client to define translations per message type to transform local data into a message conforming to the protocol schema for transmission.
Messages passed to the publish and broadcast methods should have been encoded and validated against the protocol schema.
Publish vs Broadcast
It is intended that all normal-operation messages will be published on a given topic allowing clients to choose which message topics to subscribe to.
Broadcast is provided for contingency scenarios. The intention is that in the case of a failure/abort a message can be sent to all parties which bypasses any existing messages in the publish queue.
The client implementation can chose to take no-action on decoding one of these messages but they will be made available to all clients.