# backbone-adapter-javascript

Generic adapter for the communications-backbone. 

Implements:

- client credentials grant 
- http send/receive/notify to backbone 
- websockets send and receive 
- validation of messages against a specified OpenAPI schema 
- decode/encode stubs

## Setup 

```
yarn install
# move testsuite files into view
yarn copytests
```

## Test 

The tests are written in [cucumber](https://cucumber.io/docs/installation/javascript/)

This means we can have a common suite of [gherkin](https://github.com/cucumber/gherkin)
tests across adapter ports written in multiple languages. 

```
yarn test
```

## Installing in your project 

We may publish this to a public registry but for now you need to install the package 
from git. 

### Requirements 

An `axios` library. Axios is included as a dev dependency to run the tests. 
I've not installed it as a runtime dependency because in nuxt you need to 
use `@nuxtjs/axios` instead. 

**TODO fix this in rollup config**

### Yarn

```yarn
yarn add git+https://git.noc.ac.uk/communications-backbone-system/backbone-adapter-javascript.git
```

### NPM

```npm
npm install git+https://git.noc.ac.uk/communications-backbone-system/backbone-adapter-javascript.git
```

## 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. 

```json
{
  "api": "[backbone api root url]",
  "client_id": "unique-client-id",
  "client_name": "UniqueClientName",
  "subscription": "dot.delimited.topic.subscription.#",
  "secret": "[a generated secret]"
}
```

### Topics and Subscriptions 

The topics have the following structure: 

```
project.operator.vehicleType.vehicleID.[send|receive].messageType
# eg 
soar.noc.autosub.ah1.send.platform-mission 
# or 
soar.po.ecosub.eco1.receive.platform-status
```

Subscriptions may contain single-word wildcards (*) or multi-word wildcards (#).

## 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.