docs: middleware and RPC calls

Author: 0xB10C

.gitignore

@@ -32,6 +32,7 @@ tools/bbbconfgen/test/test-output.conf
 /_site
 /docs/.sass-cache
 /docs/_site
+docs/.jekyll-cache/*
 
 # Ignore the binary build outputs (except READMEs)
 /bin/go/*

docs/customapps/middleware/base-streaming-service-info-changes-to-frontend_sequencediagram-org.svg

@@ -7,4 +7,47 @@ nav_order: 300
 ---
 ## Middleware: Communication
 
-(TODO)0xB10C
+
+### BitBoxApp <-> Middleware RPCs
+
+TODO
+
+The Middleware handles the communication between the BitBoxApp and the BitBoxBase.
+
+- minimize traffic
+- RPC Client/Server (Go RPC package)
+- Why Websockets
+- End to End encryption
+- Noise paring / handshake
+- TLS vs Noise
+- JWT Authentication
+
+Specific RPC sequence diagrams:
+
+* [Streaming ServiceInfo changes to App frontend](base-streaming-service-info-changes-to-frontend_sequencediagram-org.svg){:target="_blank"}
+
+
+### HSM communication
+
+TODO
+
+### IPC notifications
+
+The Middleware is able to receive IPC notifications from other processes running on the BitBoxBase.
+IPC notifications are implemented via a Unix named pipe and notifications are formatted in a JSON based protocol.
+Using a named pipe allows simple and dependencyless implementation in other Go, Python or Shell Script based processes running on the BitBoxBase.
+One draw back is that a named pipe blocks writes until the content is read.
+By default the named pipe is located in `/tmp/middleware-notification.pipe` and system level permissions are required to write in the pipe.
+
+![middleware ipc notifications](middleware_ipc_notifications.png)
+
+*Schematic showing multiple scripts writing notifications into the named pipe.*
+
+The JSON based protocol for the notifications is versioned, includes a notification topic and a can contain a  payload.
+The payload can contain any valid JSON structure.
+Since a write operation to a unix pipe only being atomic (i.e. two writes do not interleave) as long as the amount written is smaller than the `PIPE_BUF`, which is 4096 bytes for Linux, the Middleware drops all notifications bigger than 4095 bytes.
+
+*Sample notification:*
+```JSON
+{"version": 1, "topic": "sampletopic", "payload": {"sampleInt":123,"sampleString": "string", "sampleBool": true}}
+```

docs/customapps/middleware/middleware-communication.md

@@ -7,4 +7,48 @@ nav_order: 200
 ---
 ## Middleware: Configuration
 
-(TODO)0xB10C
+
+### Command line interface parameters
+
+Running `bbbmiddleware -h` prints the configuration options for the Middleware on the command line.
+
+Note: *The argument list below was last updated in December 2019.*
+
+```console
+-bbbcmdscript string
+    Path to the bbb-cmd.sh script that allows executing system commands (default "/opt/shift/scripts/bbb-cmd.sh")
+-bbbconfigscript string
+    Path to the bbb-config.sh script that allows setting system configuration (default "/opt/shift/scripts/bbb-config.sh")
+-bbbsystemctlscript string
+    Path to the bbb-systemctl.sh script that allows starting and stopping services on the Base (default "/opt/shift/scripts/bbb-systemctl.sh")
+-datadir string
+    Directory where the Middleware persistent data, like for example the noise encryption keys, is stored (default ".base")
+-electrsport string
+    Electrs RPC port (default "51002")
+-hsmfirmwarefile string
+    Location of the signed HSM firmware binary (default "/opt/shift/hsm/firmware-bitboxbase.signed.bin")
+-hsmserialport string
+    Serial port used to communicate with the HSM (default "/dev/ttyS0")
+-middlewareport string
+    Port the Middleware listens on (default "8845")
+-network string
+    Indicate wether Bitcoin is running on mainnet or testnet (default "testnet")
+-notificationNamedPipePath string
+    Path where the Middleware creates a named pipe to receive notifications from other processes on the BitBoxBase (default "/tmp/middleware-notification.pipe")
+-prometheusurl string
+    URL of the Prometheus server (default "http://localhost:9090")
+-redismock
+    Flag to use the Redis mock for development instead of connecting to a redis server
+-redisport string
+    Port of the Redis server (default "6379")
+-updatehsmfirmware
+    Set to true to force HSM firmware update
+-updateinfourl string
+    URL to query information about Base image updates from (default "https://shiftcrypto.ch/updates/base.json")
+```
+
+### Changing the Middleware systemd file
+
+(TODO)Stadicus
+
+- config in systemd unit (via env variables / config template in /etc/bbbmiddleware)

docs/customapps/middleware/middleware-configuration.md

@@ -7,4 +7,45 @@ nav_order: 100
 ---
 ## Middleware: Functionality
 
-(TODO)0xB10C
+
+The Middleware connects the BitBoxBase system with the BitBoxBase user interfaces, such as the BitBoxApp and the HSM screen.
+The task of the Middleware is to respond to synchronous user request and to asynchronously notify the user about changes on the system.
+A action from the user could for example toggle _SSH access_ or requests for information about the Bitcoin blockchain synchronization progress.
+A notification from the Middleware to the user could be for example about an available software update or the disk running out of space.
+
+### Tasks of the Middleware
+
+The Middleware processes Remote Procedure Calls (RPCs) from the BitBoxApp, keeps a connection to the HSM, queries both Redis and Prometheus servers, executes shell scripts to change system configuration and listens on an inter process communication (IPC) interface for notifications from other processes.
+
+<br>
+![Middleware overview](middleware_overview.png)
+*Schematic showing the Middleware and it's connections.*
+<br>
+<br>
+
+#### App connectivity via RPC
+The BitBoxApp acts as RPC Client talking to the Middleware's RPC Server.
+Available RPCs can for example change system configuration, set the user password, create or restore a backup, update the BitBoxBase software or deliver information on services such as Bitcoin Core or c-lightning running on the Base.
+The [BitBoxApp <-> Middleware communication section](middleware-communication.html) includes more detail on design and implementation decisions.
+
+#### HSM connectivity via UART
+
+The Middleware communicates with the HSM over UART.
+Messages are serialized as Protobuf messages.
+
+#### Querying Redis and Prometheus
+
+The Redis server on the BitBoxBase acts as a store for system configuration and the Prometheus server holds service specific information.
+The Middleware queries information from both.
+
+
+#### Executing shell scripts
+
+The Middleware calls the [bbb-cmd.sh](../bbb-cmd.html) and [bbb-config.sh](../bbb-config.html) scripts to change system configuration and to call standard commands.
+
+
+#### Listening for IPC notifications
+
+Processes running on the BitBoxBase can notify the Middleware about changes the user needs to be made aware of.
+This is for example used to notify the Middleware about a successful completion of system checks after an update.
+The [communication section](middleware-communication.html) includes detailed information about the IPC implementation.

docs/customapps/middleware/middleware-functionality.md

@@ -0,0 +1,15 @@
+title pre-update
+
+participant app
+
+middleware->shiftcrypto.ch/updates/base.json: HTTP GET
+middleware<-shiftcrypto.ch/updates/base.json: response
+box over middleware: parse JSON
+box over middleware: compare base\nversion with \nbase.json version
+
+
+box over middleware: if newer
+middleware -->> app: notify app about newer version avaliable
+
+middleware <- app: GetUpdateVersion 
+middleware -> app: {\nupdateAvaliable: bool, \nversion: string, \ndescription: string, \nseverity: int\n}

docs/customapps/middleware/middleware_ipc_notifications.png

@@ -0,0 +1,33 @@
+
+title Streaming ServiceInfo changes to the Frontend
+
+participant Frontend
+participant App
+participant Middleware
+participant Prometheus
+participant Prometheus Scraper
+
+
+Middleware->Prometheus: query last scrape timestamp
+Middleware<-Prometheus: timestamp: 2
+
+note over Middleware: compare with saved timestamp\n\nequal:\ndo nothing
+note over Middleware: wait 5 seconds
+
+Prometheus <<-- Prometheus Scraper: write new data\ntimestamp: 3
+Middleware->Prometheus: query last scrape timestamp
+Middleware<-Prometheus: timestamp: 3
+note over Middleware: compare with saved timestamp\n\nnot equal:\n1. safe timestamp = 3\n2. check if ServiceInfo changed
+Middleware->Prometheus: query ServiceInfo data\n(multiple querys)
+Middleware<-Prometheus: data ServiceInfo
+note over Middleware: check if ServiceInfo data changed\n\n- not changed: skip\n- changed: fire event
+App<<--Middleware:notify ServiceInfo changed
+note over Middleware:wait 5 seconds
+Frontend<<--App:notify ServiceInfo changed
+
+Frontend->App: GET /service-info
+Prometheus <<-- Prometheus Scraper: write new data\ntimestamp: 4
+App->Middleware:GetServiceInfo RPC
+App<-Middleware:Return cached\nGetServiceInfoResponse
+Frontend<-App:GetServiceInfoResponse
+note over Frontend:Redraw

docs/customapps/middleware/middleware_overview.png

@@ -0,0 +1,39 @@
+title Base Update Process via RPC
+
+note over front-end: user wants to update 
+front-end->App: POST /update-base <version>
+App->Middleware: UpdateBase RPC <version>
+Middleware->bbb-cmd.sh: mender-update install <version>
+
+activate bbb-cmd.sh
+
+bbb-cmd.sh -->> Middleware: read from stdin: progress 1%
+Middleware -->> App: Event: UpdateProgresChanged
+App -->> front-end: Event: UpdateProgressChanged
+note over front-end:Am I ready to query new\nupdate progress info?\n\nNo (do nothing).
+
+bbb-cmd.sh -->> Middleware: read from stdin: progress 2%
+Middleware -->> App: Event: UpdateProgresChanged
+App -->> front-end: Event: UpdateProgressChanged
+note over front-end:Am I ready to query new\nupdate progress info?\n\nYes.
+
+
+front-end->App: GET /base-update-progress
+bbb-cmd.sh -->> Middleware: read from stdin: progress 3%
+
+App->Middleware:GetBaseUpdateProgress
+Middleware->App: 3%
+App->front-end: 3%
+
+
+==when update finished==
+
+bbb-cmd.sh -> Middleware: (no error)
+deactivate bbb-cmd.sh
+
+note over Middleware: set redis keys and restart base 
+
+Middleware -> App: ErrorResponse{Success: true}
+
+App ->front-end: {success: true}
+