# Blocktree
Blocktree is a platform for building distributed systems.
It aims to make it easy to create secure and reliable services using the actor model.

The goals of the system include the following:
- Provide a message passing IPC mechanism which is high performance and cryptographically secure.
This interface must support fire-and-forget, remote procedure call, and pub-sub messaging patterns.
- Enable applications to define protocols in terms of the messages they send and receive
(e.g. [session types](https://www.doc.ic.ac.uk/~yoshida/multiparty/multiparty.pdf))
and implement a runtime which checks for protocol adherence.
- Implement a network file system which is highly-available, distributed, and which allows
client-side encryption.
- Perform the cryptographic key management necessary to implement access control.
- Use the network file system to orchestrate OCI containers and Wasm modules.

Non-goals of the systems include:
- Writing device drivers and controlling hardware.
- Providing a framework for building frontend apps.
- Communication over non-IP networks.

## Crates
Blocktree is broken into the following main crates:
* [btlib](./btlib/index.html): Contains common traits and structs. The cryptographic code
lives in the [crypto](./btlib/crypto/index.html) module. TPM support is provided
by the [tpm](./btlib/crypto/tpm/index.html) module.
* [btrun](./btrun/index.html): Contains the actor runtime.
* [btserde](./btserde/index.html): Defines the serde compact binary serialization format used to
store data on disk and transmit over the network.
* [btmsg](./btmsg/index.html): Defines the message passing interface.
* [btfproto](./btfproto/index.html): Defines the message protocol used to communicate with file
servers.
* [btfsd](./btfsd/index.html): Implements a file server daemon.
* [btfuse](./btfuse/index.html): Implements a FUSE daemon which allows local or remote file systems
to be mounted.

The remaining crates contain tests and code which facilitates them.
* [swtpm-harness](./swtpm_harness/index.html): Contains a struct for controlling a child process
running [Stephan Berger's swtpm](https://github.com/stefanberger/swtpm) daemon, a program which
implements the TPM 2.0 interface.
* [btlib-tests](./btlib_tests/index.html): Tests for [btlib](./btlib/index.html).
* [btfproto-tests](./btfproto_tests/index.html): Tests for [btfproto](./btfproto/index.html).

## Building
Blocktree requires the nightly rust compiler. The preferred way of installing this is
using [rustup](https://rustup.rs/). Once you have rustup installed you can install the nightly
toolchain with `rustup toolchain install nightly`.

Building is as simple as executing `cargo build` in the root of this repository. The test suite
can be run with `cargo test`. In order to run the tests `swtpm`, `libtss2` and `libfuse` need to be
installed.

## Design Principles
- The blocktree is the network, and is used for translating blocktree paths to network endpoints.
- IPC is performed by passing messages.
- Messages are addressed using blocktree paths.
- Processes are cryptographically bound to the path where they receive messages.
- File system access is performed by passing messages.

## Performance Measurement with flamegraph on Linux
In order to use the `flamegraph` crate to on Linux you need to setup unprivileged access to the
`perf` utility by your user account. After installing `perf` (on Arch with `pacman -S perf`),
perform the following as root (if `perf` is not installed at `/usr/bin/perf` use `which perf` to
locate it):
```
# groupadd perf_users
# cd /usr/bin
# ls -alhF perf
-rwxr-xr-x  2 root root  11M Oct 19 15:12 perf
# chgrp perf_users perf
# ls -alhF
-rwxr-xr-x  2 root perf_users  11M Oct 19 15:12 perf
# chmod o-rwx perf
# ls -alhF
-rwxr-x---  2 root perf_users  11M Oct 19 15:12 perf
# setcap "cap_perfmon,cap_sys_ptrace,cap_syslog=ep" perf
# setcap -v "cap_perfmon,cap_sys_ptrace,cap_syslog=ep" perf
perf: OK
# getcap perf
perf = cap_sys_ptrace,cap_syslog,cap_perfmon+ep
```
(source: https://www.kernel.org/doc/html/latest/admin-guide/perf-security.html)
Finally add your user account to the perf_users group:
```
# usermod -aG perf_users <your username>
```
You'll need to logout and back in for the new group to take effect. You can confirm you're in the
group with:
```
> groups
tss audio <your username> perf_users
```
The you can run flamegraph as your user account with:
```
> cargo flamegraph --unit-test <crate name> -- test::<test name>
```
(source: https://crates.io/crates/flamegraph)

## Test coverage with tarpaulin
The [tarpaulin](https://github.com/xd009642/tarpaulin) crate can be used to generate code coverage
reports. You can install it with cargo with `cargo install tarpaulin`. To generate an HTML report
for the entire repository, execute `cargo tarpaulin --out Html` from the root of
this repository. The generated report will be saved to the root of the repository. 
You can generate coverage reports for specific crates by first navigating
to the crates directory then executing the above command.
Note that even if you run the tool in a subdirectory, the report will still be saved in the root
of the repository.
Please do not commit the coverage report.

## License
Copyright 2023 Delease, LLC. The software contained in this repository is licensed under the
GNU Affero General Public License Version 3 or later. A copy of this license is provided in the
LICENSE file in the root of this repository. A license which allows for the usage of this software
without disclosing the source code of the system containing it may be purchased by contacting
Delease, LLC.