feat(forward): SFM event forwarder (v1.5.0)

When SFM_FORWARD_ENABLED=true and SFM_URL is set, every Blastware
event binary in the ACH watch folder is forwarded to an SFM server's
/db/import/blastware_file endpoint as a multipart POST.  The paired
<binary>.TXT ASCII report (which Blastware's ACH writes alongside
each event) is shipped in the same request, letting the SFM server
index the full per-channel stats — PPV, ZC Freq, Time of Peak, Peak
Acceleration / Displacement, Peak Vector Sum + time, sensor
self-check Pass/Fail per channel, and monitor-log timestamps —
without depending on the still-undecoded BW waveform body codec.

New module event_forwarder.py:
  - is_event_binary() filename matcher (BW's <P><serial3><stem>.<ext>
    scheme; rejects .MLG, .TXT, .log, .ini, .h5, etc.)
  - ForwardState (.json file keyed by sha256 — idempotent across
    restarts and auto-updates)
  - find_pending_events() with quiescence + grace-period guards
  - Hand-rolled multipart encoder (stdlib-only)
  - forward_event_pair() / forward_pending() — POST loop with
    structured per-event outcomes

Wired into series3_watcher.run_watcher() on its own cadence
(SFM_FORWARD_INTERVAL_SECONDS, default 60s) so it doesn't slow the
existing 5-min heartbeat scan.

Default-off: existing 1.4.x deployments keep their old behaviour
after auto-updating until an operator sets SFM_URL +
SFM_FORWARD_ENABLED=true and restarts.

17 unit tests in test_event_forwarder.py cover filename matching,
state idempotency, scan logic (quiescence, grace, max age,
already-forwarded, .TXT pairing), multipart byte shape, and an
end-to-end POST against a tiny stdlib http.server fake.

Bumps version 1.4.4 → 1.5.0 (minor — additive feature, no API break).
Requires SFM server v0.16+ for the paired-.TXT import endpoint.
This commit is contained in:
2026-05-09 00:03:31 +00:00
parent 010016d515
commit f4ec6ef945
8 changed files with 1052 additions and 5 deletions
+31
View File
@@ -32,3 +32,34 @@ UPDATE_SOURCE = gitea
# If UPDATE_SOURCE = url, set UPDATE_URL to the base URL of the update server (e.g. terra-view)
UPDATE_URL =
# --- SFM Event Forwarder ---
# When enabled, every Blastware event binary (and its paired .TXT
# report when present) is forwarded to an SFM server's
# /db/import/blastware_file endpoint as a multipart POST. The SFM
# server parses the .TXT and indexes the event's full per-channel
# stats (PPV, ZC Freq, Time of Peak, Peak Acceleration, Peak
# Displacement, sensor self-check) for sortable / filterable review.
#
# Default-off so existing deployments don't change behaviour after an
# auto-update. To enable on a field machine: set SFM_URL, then flip
# SFM_FORWARD_ENABLED to true and restart the watcher.
SFM_FORWARD_ENABLED = false
SFM_URL = ; e.g. http://10.0.0.44:8200
SFM_FORWARD_INTERVAL_SECONDS = 60 ; scan-and-forward cadence (independent of heartbeat)
# Files modified within the last N seconds are skipped (BW may still
# be writing them). Defence against truncated uploads.
SFM_QUIESCENCE_SECONDS = 5
# If a binary's .TXT report hasn't appeared after this many seconds,
# forward the binary alone rather than blocking forever waiting.
SFM_MISSING_REPORT_GRACE_SECONDS = 60
# Per-request HTTP timeout (seconds).
SFM_HTTP_TIMEOUT = 60
# Path to the JSON state file tracking which events have been
# forwarded (sha256-keyed, idempotent across restarts). Leave blank
# to default to <log dir>/sfm_forwarded.json.
SFM_STATE_FILE =