# Dmn: Distributed Messaging & Synchronization

Dmn is a C++ library for distributed messaging and data synchronization. It
provides building blocks for networking, message exchange, concurrency control,
and conflict resolution, with an emphasis on delegation and integration into
existing applications.

## Documentation

Generated documentation: <https://cheebinhoh.github.io/Dmn/>

## Build and test on Linux

The project uses CMake and fetches its third-party dependencies during
configuration when they are not available locally. ICU development files are
required. On Ubuntu, install the native build prerequisites with:

```bash
sudo apt-get update
sudo apt-get install build-essential cmake git libicu-dev
```

Then configure, build, and run the regular unit tests:

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j2
ctest --test-dir build -L dmn --output-on-failure
```

### Valgrind tests

Install Valgrind (on Ubuntu, `sudo apt-get install valgrind`) and enable its
test variants at configure time:

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_VALGRIND=ON
cmake --build build -j2
ctest --test-dir build -L 'dmn|valgrind' --output-on-failure
```

This runs the regular tests plus their Valgrind variants. The `valgrind`
variants are only registered when `ENABLE_VALGRIND=ON`.

### Kafka integration tests

Kafka tests are optional and require a broker available at
`localhost:9092`. Start a broker and create the `timer_counter` topic before
running them. For example, with Kafka's command-line tools:

```bash
kafka-topics.sh --create --topic timer_counter --bootstrap-server localhost:9092
```

Then configure, build, and run the Kafka tests:

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_KAFKA_TEST=ON
cmake --build build -j2
ctest --test-dir build -L kafka --output-on-failure
```

The Docker entrypoint starts its bundled broker and creates this topic
automatically; native runs must provide both themselves.

### D-Bus extension

The optional D-Bus extension provides byte-oriented input/output adapters that
send and receive D-Bus signals. They can carry serialized DMesg messages
through `Dmn_DMesgNet` or other application payloads using a configured signal
routing tuple. It is intended for inter-process communication on one host and
does not provide cross-host transport. The core `dmn` library does not depend
on D-Bus; the extension is built separately as `dmn-dbus` and is disabled by
default. `Dmn_DMesgDbus` is the DMesg-specific composition facade for
applications that do not need to construct the underlying D-Bus endpoints
directly; advanced callers can continue to inject `Dmn_DbusInput` and
`Dmn_DbusOutput` into `Dmn_DMesgNet`. When an application links `dmn-dbus`,
the target defines `DMN_ENABLE_DBUS`, so `dmn.hpp` also includes the D-Bus
configuration, endpoint, and facade headers. Without that target and macro,
the umbrella header does not include the optional D-Bus API. The
`dmn-fault-injection.hpp` header is included by `dmn.hpp` only when
`ENABLE_FAULT_INJECTION=ON` defines `FIU_ENABLE`; its CMake target-source
registration is gated by the same option.

On Ubuntu, install the libdbus development files, pkg-config, and daemon used
by the private-bus unit test:

```bash
sudo apt-get install libdbus-1-dev pkg-config dbus-daemon
```

Enable the extension and run its test (registered under the regular `dmn`
CTest label):

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_DBUS=ON
cmake --build build -j2
ctest --test-dir build -R '^dmn-test-dbus-io$' --output-on-failure
ctest --test-dir build -R '^dmn-test-dbus-facade$' --output-on-failure
```

## Fault-injection tests

Fault-injection support is optional and disabled by default. Enabling it links
libfiu into the fault-injection build. CMake uses an installed libfiu package
found through pkg-config when available; otherwise it fetches and builds
libfiu 1.2 and its `fiu-run` launcher.

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_FAULT_INJECTION=ON
cmake --build build --target fault-injection-tests -j2
ctest --test-dir build -L fault-injection --output-on-failure
```

Fault-injection tests are GoogleTest executables invoked by CTest through
`fiu-run`. They use the separate `fault-injection` label and are not included
in the regular `dmn` test group. To run one test by name:

```bash
ctest --test-dir build -R '^dmn-test-fi-timer-thread-start-failure$' \
  --output-on-failure
```

The recurring-reschedule failure test can be run individually with:

```bash
ctest --test-dir build -R '^dmn-test-fi-timer-reschedule-failure$' \
  --output-on-failure
```

## Docker

From the repository root, build the image:

```bash
docker build -t dmn .
```

Start it interactively with its normal entrypoint:

```bash
docker run -it --rm dmn
```

The image enables every CMake option. On startup, the entrypoint bootstraps
the Kafka topic and runs the `dmn`, `kafka`, `valgrind`, and `fault-injection`
CTest groups. If they pass, it opens a Bash prompt in the container; if they
fail, the entrypoint exits without opening the prompt. The run command removes
the container when you exit because it uses `--rm`.

To enter a shell immediately without starting Kafka or running tests, bypass
the entrypoint:

```bash
docker run -it --rm --entrypoint /bin/bash dmn
```

The image is built with `BUILD_NDEBUG=ON`, which disables assertions. Use a
native build with `BUILD_NDEBUG=OFF` when assertions are needed. To build with
Docker Buildx and load the image into the local Docker engine:

```bash
docker buildx build -t dmn:latest --load .
```

Remove the image when it is no longer needed:

```bash
docker rmi dmn
```

## CMake options

| Option | Default | Purpose |
| --- | --- | --- |
| `BUILD_NDEBUG` | `OFF` | Define `NDEBUG` for the build. |
| `BUILD_KAFKA_TEST` | `OFF` | Build the additional Kafka integration tests. |
| `ENABLE_DBUS` | `OFF` | Build the optional D-Bus signal I/O extension and its private-bus test. Requires libdbus development files, pkg-config, and `dbus-daemon`. |
| `ENABLE_VALGRIND` | `OFF` | Register Valgrind test variants; requires Valgrind. |
| `ENABLE_FAULT_INJECTION` | `OFF` | Build libfiu support and register tests run through `fiu-run`. |

The options are cached in the build directory. Reconfigure that directory
with the desired options before building. The `dmn` CTest label selects the
regular unit tests; `kafka`, `fault-injection`, and `valgrind` select their
respective optional test groups.

To enable every CMake option, including Kafka and D-Bus integration tests,
configure and build with the commands below. The first command enables all
five options; the second builds all targets. The D-Bus test runs with the
regular `dmn` test group:

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug \
  -DBUILD_NDEBUG=ON \
  -DBUILD_KAFKA_TEST=ON \
  -DENABLE_DBUS=ON \
  -DENABLE_VALGRIND=ON \
  -DENABLE_FAULT_INJECTION=ON
cmake --build build -j2
```

This configuration requires libdbus development files, pkg-config,
`dbus-daemon`, Valgrind, and a Kafka broker listening at `localhost:9092` with
the `timer_counter` topic for Kafka integration tests. Run every registered
test group with:

```bash
ctest --test-dir build -L 'dmn|kafka|valgrind|fault-injection' \
  --output-on-failure
```

`BUILD_NDEBUG=ON` disables assertions, so use `OFF` if you want assertions
enabled while running the full test groups.