Operational Modes & Deployment ================================= The `fleetmesh-strfry` bridge supports two primary deployment topologies depending on whether you want an all-in-one embedded setup or decoupled service isolation: 1. **Mode 1: In-Process Node Compartment Plugin** 2. **Mode 2: Standalone Service Daemon** Mode 1: In-Process Plugin ------------------------- In Mode 1, `meshnode` loads `StrfryBridgePlugin` as an internal compartment subsystem. The bridge starts and stops automatically with the node, participates in the periodic event loop tick, and exposes metrics under `health.subsystems.strfry`. Configuration ^^^^^^^^^^^^^ Declare the plugin in the node's ``config.json``: .. code-block:: json { "plugins": [ { "ref": "fleetmesh_strfry.plugin:StrfryBridgePlugin", "after": "bridge" } ], "extensions": { "strfry": { "url": "ws://127.0.0.1:7777", "policy": { "enforce_grants": false, "shadow_reject": false, "max_event_bytes": 131072, "rate_limit_per_min": 120 }, "kinds": [0, 1, 3, 6, 7, 1059, 11801, 11802, 11803, 30801, 30802, 30803] } } } Configuration Parameters: - ``plugins[].ref``: Must point to ``fleetmesh_strfry.plugin:StrfryBridgePlugin``. - ``plugins[].after``: (Optional) Configures compartment boot ordering. Specifying ``bridge`` ensures the strfry bridge starts alongside the native relay bridge. - ``extensions.strfry.url``: WebSocket URL of the running strfry relay. - ``extensions.strfry.policy``: Policy configuration dictionary (see :doc:`policy`). - ``extensions.strfry.kinds``: Subscription filter specifying which event kinds should be streamed from strfry into the node's local store. Lifecycle & Tick Behavior ^^^^^^^^^^^^^^^^^^^^^^^^^ - **Start**: Initializes the WebSocket client and establishes an active subscription against strfry. If the node has an active ``bridge`` compartment, it softly binds to it to coordinate telemetry. - **Tick**: On every node clock tick (by default every 10–30 seconds), calls ``flush_egress()`` to drain any buffered egress events that could not be transmitted immediately. - **Stop**: Flushes remaining queues and cleanly terminates the WebSocket connection. CLI Integration ^^^^^^^^^^^^^^^ When the plugin is loaded, `meshnode` gains the `strfry` command group: .. code-block:: sh # Inspect active bridge status and telemetry counters meshnode strfry /var/lib/fleetmesh status # Flush queued egress events to strfry meshnode strfry /var/lib/fleetmesh flush # Run write-policy evaluation on a raw event meshnode strfry /var/lib/fleetmesh eval --event '{"kind": 1, ...}' Mode 2: Standalone Service Daemon --------------------------------- In Mode 2, `fleetmesh-strfry` runs as an independent OS-level service daemon separate from `meshnode`. This is ideal for setups where strfry runs in a dedicated container or dedicated virtual machine, or when operators prefer independent process supervision. Running the Daemon ^^^^^^^^^^^^^^^^^^ .. code-block:: sh # Run the live relay bridge service python3 -m fleetmesh_strfry run --dir /var/lib/fleetmesh --url ws://127.0.0.1:7777 --every 30 The service opens `store.sqlite` and `grants.sqlite` directly from the node directory, maintains a persistent connection to strfry, and periodically flushes egress events every `--every` seconds until receiving SIGTERM or SIGINT. Exit Codes: - ``0``: Clean exit on signal. - ``1``: Runtime error or policy failure. - ``2``: Invalid CLI arguments (missing directory, missing ``keys.json``). Systemd Service Unit ^^^^^^^^^^^^^^^^^^^^ A pre-configured systemd unit is provided in ``contrib/fleetmesh-strfry.service``: .. code-block:: ini [Unit] Description=Fleetmesh strfry Relay Bridge After=network.target strfry.service meshnode.service Wants=strfry.service [Service] Type=simple User=fleetmesh Group=fleetmesh Environment="NODE_DIR=/var/lib/fleetmesh" Environment="STRFRY_URL=ws://127.0.0.1:7777" Environment="PYTHONPATH=/opt/fleetmesh/strfry-bridge:/opt/fleetmesh/meshnode:/opt/fleetmesh/core:/opt/fleetmesh/schema" ExecStart=/usr/bin/python3 -m fleetmesh_strfry run --dir ${NODE_DIR} --url ${STRFRY_URL} --every 30 Restart=always RestartSec=5s [Install] WantedBy=multi-user.target To install and activate the service: .. code-block:: sh sudo install -m 644 contrib/fleetmesh-strfry.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now fleetmesh-strfry