# Contributing to libsockbus

## Architecture

```
sockbus.hpp (single public header)

Namespace: sockbus
  create(name, size)       Start broker on host:port
  destroy(name)            Stop broker, disconnect all clients

Class: Bus (pimpl)
  Bus(name)                Connect to broker (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
```

## Source Files

| File | Purpose |
|------|---------|
| sockbus.cpp | Full implementation: broker threads, TCP framing, name resolution, client management |

## Canonical Spec

[`docs/SOCKBUS_SPEC.md`](docs/SOCKBUS_SPEC.md) is the specification.
All implementation decisions defer to this document.

## Build

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

## Coding Standards

- **C++17**, compiled with `-Wall -Wextra -Werror -O2 -fPIC`
- **No external dependencies** — libc, libpthread only
- **Linux only** — POSIX sockets, poll()
- **Single public header**: `sockbus.hpp`
- Errors: `std::system_error` for connection/send failures
- Wire format: 4-byte length prefix (network byte order) + payload
- No commented-out code, no bare TODOs, no debug prints
- No routing, framing logic, 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`:

```cpp
static void test_my_feature() {
    sockbus::create("127.0.0.1:19100");
    sockbus::Bus bus("127.0.0.1:19100");
    // ... test logic ...
    sockbus::destroy("127.0.0.1:19100");
}
```

Register in `main()` and it will be included in `make test`.

## Test Suite

48 tests covering: lifecycle, open/close, write/read, broadcast semantics,
blocking reads, data integrity, multi-bus isolation, name resolution,
edge cases, move semantics.

## Before Submitting

- Run `make clean && make test` — all 48 tests must pass
- New public API requires documentation in `sockbus.hpp` header comments