[feat](trx-rs): harden auth UI and extend planning docs

Co-authored-by: OpenAI Codex <codex@openai.com> Signed-off-by: Stanislaw Grams <stanislawgrams@gmail.com>
2026-02-13 10:44:10 +01:00
parent 8a4e9f5ed3
commit 1b97bc9795
4 changed files with 201 additions and 11 deletions
@@ -0,0 +1,129 @@
+//! APRS.fi integration implementation draft (server-side)
+//!
+//! Goal:
+//! - Add optional APRS.fi upload/logging support for decoded APRS packets.
+//! - Keep feature disabled by default.
+//! - Reuse existing decode pipeline in `trx-server`.
+//!
+//! This is a planning artifact, not active runtime logic.
+
+/// Delivery phases.
+#[allow(dead_code)]
+pub enum Phase {
+    Config,
+    PacketSelection,
+    UplinkWorker,
+    RetryAndRateLimit,
+    PrivacyControls,
+    Tests,
+    Docs,
+}
+
+/// Proposed config block for `trx-server.toml`.
+#[allow(dead_code)]
+pub const CONFIG_PROPOSAL: &str = r#"
+[aprsfi]
+enabled = false
+
+# APRS.fi API token / key (required when enabled)
+api_key = ""
+
+# Optional station identity metadata
+receiver_callsign = "N0CALL"
+receiver_locator = "JO93"
+
+# Upload endpoint override for testing
+endpoint = "https://api.aprs.fi/api"
+
+# Upload policy
+include_third_party = false
+min_interval_ms = 1000
+max_queue = 1000
+"#;
+
+/// Validation rules.
+#[allow(dead_code)]
+pub const VALIDATION: &[&str] = &[
+    "If aprsfi.enabled=false: ignore all aprsfi fields",
+    "If aprsfi.enabled=true: api_key must be non-empty",
+    "min_interval_ms must be > 0",
+    "max_queue must be > 0",
+];
+
+/// Runtime architecture.
+#[allow(dead_code)]
+pub const ARCHITECTURE: &[&str] = &[
+    "Spawn dedicated APRS.fi worker task in src/trx-server/src/main.rs",
+    "Subscribe to decode broadcast channel (existing decode_tx.subscribe())",
+    "Filter DecodedMessage::Aprs only",
+    "Transform AprsPacket into APRS.fi payload DTO",
+    "Queue and POST asynchronously with bounded backpressure",
+    "Never block decoder tasks on network I/O",
+];
+
+/// Integration points in current code.
+#[allow(dead_code)]
+pub const INTEGRATION_POINTS: &[&str] = &[
+    "src/trx-server/src/config.rs: add AprsFiConfig",
+    "src/trx-server/src/main.rs: start worker when enabled",
+    "src/trx-server/src/audio.rs: no direct changes required (consume from decode stream)",
+    "src/trx-server/src/<new>/aprsfi.rs: worker + payload mapping + HTTP client",
+    "trx-server.toml.example + CONFIGURATION.md: docs",
+];
+
+/// Packet handling policy.
+#[allow(dead_code)]
+pub const PACKET_POLICY: &[&str] = &[
+    "Upload only packets with valid callsign and parseable position by default",
+    "Optionally allow non-position packets if APRS.fi endpoint supports them",
+    "Deduplicate burst repeats (same src/info within short window)",
+    "Drop malformed frames silently with debug log",
+];
+
+/// Retry/rate limiting policy.
+#[allow(dead_code)]
+pub const RELIABILITY_POLICY: &[&str] = &[
+    "Bounded mpsc queue (max_queue)",
+    "If queue full: drop oldest or newest by configurable policy (MVP: drop newest)",
+    "Exponential backoff on HTTP/network errors",
+    "Respect min_interval_ms between outbound requests",
+    "Throttle warning logs to avoid spam",
+];
+
+/// Privacy/safety controls.
+#[allow(dead_code)]
+pub const PRIVACY_CONTROLS: &[&str] = &[
+    "Feature disabled by default",
+    "API key never logged",
+    "Optional include_third_party flag for re-published packets",
+    "Document that enabling uploads sends decoded RF data to external service",
+];
+
+/// Test plan.
+#[allow(dead_code)]
+pub const TEST_PLAN: &[&str] = &[
+    "Unit: config parse + validation",
+    "Unit: APRS packet -> APRS.fi payload mapping",
+    "Unit: dedupe and queue/backpressure behavior",
+    "Unit: retry/backoff timing logic",
+    "Integration: mock HTTP endpoint receives expected payloads",
+    "Integration: disabled mode performs no outbound requests",
+];
+
+/// Suggested first implementation milestone (M1).
+#[allow(dead_code)]
+pub const M1: &[&str] = &[
+    "Add config + validation + docs",
+    "Create aprsfi worker skeleton (no uploads yet, just consume + structured logs)",
+    "Add payload mapping function with tests",
+    "Add feature flag + startup logs",
+];
+
+/// Suggested second milestone (M2).
+#[allow(dead_code)]
+pub const M2: &[&str] = &[
+    "Implement real HTTP POST uploads",
+    "Add retry/backoff + queue policy",
+    "Add integration test with mock server",
+    "Add operational metrics counters",
+];