Living Document Notice
Published 2026-09-23. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.
The Modular Fleet Model
Summary
Coupling editing interfaces directly to indexing, synchronization, and telemetry subsystems creates unstable desktop applications that exhaust system resources. A memory leak or runtime panic in a background indexing thread terminates the active document editing session.
Bosun partitions functionality across independent Unix daemons. Each utility operates as a dedicated process, isolating memory boundaries and communicating through local POSIX domain sockets.
Multi-Process Topology Across Decoupled Utilities
The traditional monolithic knowledge management application embeds markdown parsing, file tree watching, local HTTP servers, and synchronization engines inside a single process address space. If the background synchronization routine encounters an unhandled network exception, the entire application interface terminates abruptly.
Bosun isolates these functional areas into distinct service daemons. The architecture distributes workloads across specialized components that execute under unprivileged user permissions.
+-------------------------------------------------------------+
| Client User Interface |
| (Editor / TUI / CLI Tool) |
+-------------------------------------------------------------+
| |
| /run/user/1000/bosun/query.sock | /run/user/1000/bosun/watch.sock
v v
+-----------------------------+ +-----------------------------+
| bosun-queryd | | bosun-watchd |
| (Inverted Index & Search) | | (Inotify Delta Engine) |
+-----------------------------+ +-----------------------------+
| |
+----------------------+----------------------+
|
v
+-------------------------------------------------------------+
| Shared Filesystem |
| (02 Review/ / 03 Published/) |
+-------------------------------------------------------------+
Individual daemons operate within distinct Linux namespaces. The indexing daemon maintains read-only access to note storage directories. The file watcher monitors inotify descriptors and emits discrete delta events. The query daemon evaluates search requests across the SQLite cache without mounting filesystem write primitives.
IPC Transport Mechanism Comparison
Inter-process communication within a local system can be structured using multiple OS primitives. The table below analyzes transport mechanisms evaluated for the Bosun daemon fleet.
| Transport Layer | Kernel Overhead | Framing Discipline | Access Control Primitives | Backpressure Behavior |
|---|---|---|---|---|
Unix Domain Sockets (AF_UNIX) | Low (Direct memory copies) | Length-prefixed byte stream | POSIX filesystem permissions | Built-in socket buffer limits (SO_RCVBUF) |
Localhost TCP (127.0.0.1) | High (IP stack traversal) | Byte stream with TCP framing | Port binding collision risks | TCP window buffer saturation |
POSIX Shared Memory (shm_open) | Minimal (Zero-copy memory) | Manual synchronization rings | Inode permissions on /dev/shm | Requires custom ring semaphore logic |
Named Pipes (mkfifo) | Low (Kernel pipe buffers) | Unstructured byte stream | Inode permissions | Blocking write when buffer fills (64 KB) |
Unix domain sockets provide the optimal compromise: they bypass the kernel networking stack while supporting standard POSIX file permissions for authentication and native backpressure via socket buffer limits.
Domain Socket Framing Protocol
Communication over AF_UNIX stream sockets requires explicit message boundary framing. Bosun employs a 4-byte big-endian length prefix followed by a serialized binary payload.
#include <stdint.h>
#include <unistd.h>
#include <sys/socket.h>
#include <sys/un.h>
typedef struct {
uint32_t payload_len;
uint8_t payload[4096];
} IPCMessage;
int send_ipc_frame(int socket_fd, const uint8_t *data, uint32_t length) {
uint32_t net_len = htonl(length);
if (write(socket_fd, &net_len, sizeof(net_len)) != sizeof(net_len)) {
return -1;
}
if (write(socket_fd, data, length) != (ssize_t)length) {
return -1;
}
return 0;
}
int recv_ipc_frame(int socket_fd, uint8_t *buffer, uint32_t max_len) {
uint32_t net_len = 0;
if (read(socket_fd, &net_len, sizeof(net_len)) != sizeof(net_len)) {
return -1;
}
uint32_t host_len = ntohl(net_len);
if (host_len > max_len) {
return -2; // Buffer overflow protection
}
ssize_t total_read = 0;
while (total_read < host_len) {
ssize_t bytes = read(socket_fd, buffer + total_read, host_len - total_read);
if (bytes <= 0) return -1;
total_read += bytes;
}
return total_read;
}The receiver validates the 4-byte header against the allocated buffer boundary before reading the incoming payload, preventing arbitrary memory overruns over the IPC channel.
Fleet Supervision and Fault Recovery
When a daemon process encounters a fatal segmentation fault or exceeds its memory quota, the supervisor daemon isolates the failure. The client interface receives an ECONNRESET error code, buffers user edits locally in memory, and triggers an automated daemon restart via systemd user units.
[Unit]
Description=Bosun Search Query Daemon
PartOf=bosun-fleet.target
[Service]
ExecStart=/usr/local/bin/bosun-queryd --socket-path /run/user/%U/bosun/query.sock
Restart=on-failure
RestartSec=500ms
MemoryMax=128M
CPUQuota=25%Daemon Health Invariant
The active fleet enforces a strict socket availability invariant: all registered service sockets in /run/user/$UID/bosun/ must respond to a 4-byte ping packet (0x00000004PING) within 15 milliseconds.
Audit the operational state of running domain sockets using the ss utility:
ss -xlp "src = /run/user/$(id -u)/bosun/*.sock"- Directus Target: bosunpkm-blog
- Garden Source Reference: MOC - Bosun PKM Engine, MOC - Bosun PKM Tools, MOC - Harbor Ecosystem, MOC - Fleet Operations, MOC - Harbormaster Protocol, MOC - Outrigger Protocol