# Contributing to libblebus

## Architecture

```
blebus.hpp (single public header)

Namespace: blebus
  create(name, size)       Start broker: unix socket + BLE L2CAP + advertising
  destroy(name)            Stop broker, stop advertising, disconnect all clients

Class: Bus (pimpl)
  Bus(name)                Connect to broker over the local socket (RAII)
  write(data, len)         Broadcast (length-prefixed frame)
  write(string_view)       Broadcast (string_view overload)
  read(buf, len)           Non-blocking read (one frame per call)
  read_wait(buf, len, ms)  Blocking read with timeout
  set_reader_name(label)   Debug label
  name()                   Bus name
```

`Bus` connects over the **local unix socket**, not the radio. The BLE side is
how a remote peer reaches the broker; it is not how this handle does.

## Source Files

| File | Purpose |
|------|---------|
| src/blebus.cpp | Full implementation: broker thread, dual listener, L2CAP CoC, sd-bus advertising, framing, client management |

One translation unit behind a single header, pimpl-style. That is fine at the
current size and would need decomposition if the implementation grows
materially.

## Build

```bash
make              # Build libblebus.a + libblebus.so
make test         # Build and run all 15 tests
make install      # Install library + header to /usr/local (sudo)
make uninstall    # Remove installed files (sudo)
make clean        # Remove build artifacts
```

Requires `libbluetooth-dev` and `libsystemd-dev` in addition to a C++17 `g++`.

## Coding Standards

- **C++17**, compiled with `-Wall -Wextra -Werror -O2 -fPIC`
- **Linux only** — BlueZ L2CAP, sd-bus, poll()
- **Single public header**: `blebus.hpp`
- Errors: `std::system_error` for connection, send and lifecycle failures
- Wire format: 4-byte length prefix (network byte order) + payload —
  byte-compatible with `libsockbus`, and changing it breaks that compatibility
- No commented-out code, no bare TODOs, no debug prints
- No routing or protocol awareness — bytes only
- Lossy by design — slow readers are dropped, never buffered

## Adding Tests

Tests use a self-contained framework in `tests/unit_test.cpp`. A `TEST(name)`
block registers itself at static-initialisation time, so there is no list to
update:

```cpp
TEST(my_feature) {
    blebus::create("testbus");
    blebus::Bus bus("testbus");
    // ... test logic, using ASSERT(cond) ...
    blebus::destroy("testbus");
}
```

It is picked up by `make test` automatically.

## Test Suite

15 tests covering: broker lifecycle, duplicate and missing-broker errors,
connect, write/read echo, blocking reads and timeouts, non-blocking empty
reads, broadcast to two readers, large messages, the oversize rejection,
multiple queued messages, reader labels, and the `string_view` write overload.

**They exercise the local unix-socket transport only.** The BLE L2CAP listener
needs a real adapter, so it is smoke-tested by hand against one. A green suite
is not evidence about the radio path, and a change to the L2CAP or advertising
code is not covered by anything here — say so in the change rather than letting
a green run imply otherwise.

## Before Submitting

- Run `make clean && make test` — all 15 tests must pass
- New public API requires documentation in the `blebus.hpp` header comments
- A change to the wire format is a change to `libsockbus` compatibility; treat
  it as a breaking release and say so in `CHANGELOG.md`