sjg
1b97bc9795
Co-authored-by: OpenAI Codex <codex@openai.com> Signed-off-by: Stanislaw Grams <stanislawgrams@gmail.com>
130 lines
4.0 KiB
Rust
130 lines
4.0 KiB
Rust
//! 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",
|
|
];
|