[AZ-641] [AZ-642] [AZ-644] mavlink transport + codec + mission pull

Lands the second batch under epic AZ-626's implementation plan.

mavlink_layer (AZ-641 + AZ-642):
- Hand-rolled MAVLink v2 codec covering the §7.7 surface: HEARTBEAT,
  SYS_STATUS, SET_MODE, ATTITUDE, GLOBAL_POSITION_INT, MISSION_* (7),
  COMMAND_LONG, COMMAND_ACK, EXTENDED_SYS_STATE, STATUSTEXT (17 total).
- Streaming decoder demuxes arbitrary-sized byte arrivals, drops malformed
  frames with typed parse-error counters (crc/truncated/unknown_id/seq_gap),
  and surfaces sequence gaps without hard-failing the link.
- Encoder tracks the per-link tx_seq counter and applies the MAVLink v2
  trailing-zero payload truncation rule.
- UDP and POSIX-serial transports behind a single async Transport trait;
  the run loop owns transport open with bounded exponential backoff
  (2 s serial / 5 s UDP cap) and a tokio::select! per-link read+write
  loop.
- 1 Hz outbound HEARTBEAT scheduler + inbound-heartbeat watchdog that
  fires LinkUp / LinkLost on a broadcast channel and feeds health detail
  (connected, last_heartbeat_age_ms, signing_enabled, parse_errors).

mission_client (AZ-644):
- HTTPS GET /missions/{id} over rustls (no OpenSSL on the airframe).
- Bundled JSON Schema (crates/shared/contracts/mission-schema.json,
  draft-07, additionalProperties:false) validates every response;
  schema-invalid bodies surface as FetchError::SchemaInvalid with a
  1 KiB sample of the raw body for offline analysis.
- Transient failures (timeout, 5xx, 429) retry with bounded exponential
  backoff up to MissionClientOptions.max_attempts (default 5); permanent
  failures (4xx, malformed URL) abort immediately.
- Health surface mirrors AC-1's contract: last_fetch_ts,
  fetch_errors_total, schema_version, connection_state.

Caught and fixed before commit (NOT a code-review finding — caught by
the unit test that hand-computed CRC("123456789")): the hand-rolled
X.25 CRC accumulator was operating in u16 throughout. The MAVLink C
reference declares `tmp` as uint8_t, which silently truncates the
shifted-in bits. Round-trip tests passed (encoder and decoder shared
the bug); a real MAVLink peer would have rejected every frame. Fixed
by mirroring the C reference: `let mut tmp: u8 = …; tmp ^= tmp.wrapping_shl(4);`.
Added a regression test asserting CRC("123456789") == 0x6F91 against
pymavlink's reference value (NOT the textbook 0x29B1 — MAVLink uses a
byte-wise variant, not the bit-reflected CCITT).

AC verification (full detail in
_docs/03_implementation/batch_02_cycle1_report.md):

AZ-641: AC-1 + AC-3 + AC-4 verified via UDP loopback integration tests;
        AC-2 (serial) requires a socat pty pair and runs in the SITL/CI
        tier (test exists as #[ignore]-marked stub).
AZ-642: AC-1 + AC-2 + AC-3 verified via exhaustive codec round-trip and
        decoder negative-path tests; AC-4 (SITL round-trip) requires
        ArduPilot SITL — the CRC fix above means the codec is now
        wire-correct, ready for the sitl-conformance Woodpecker stage.
AZ-644: all four ACs verified via wiremock-driven integration tests.

Workspace gates green:
- cargo check --workspace                                clean
- cargo check --workspace --no-default-features          clean
- cargo fmt --all -- --check                             clean
- cargo clippy --workspace --all-targets -- -D warnings  clean
- cargo test --workspace                                 pass (1 expected ignore)

Layering invariants from module-layout.md hold: mavlink_layer and
mission_client are Layer 2 actors importing only `shared`; no sibling
Layer-2 imports; MavlinkHandle implements shared::contracts::MavlinkSink.

Jira: AZ-641, AZ-642, AZ-644 transitioned To Do → In Progress at batch
start; the matching In Testing transitions follow this commit.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-19 12:29:49 +03:00
parent a1ce3a6903
commit 740bf37d76
33 changed files with 5293 additions and 69 deletions
@@ -0,0 +1,46 @@
//! MAVLink v2 codec for the §7.7 command surface (per `architecture.md`).
//!
//! Strictly hand-rolled — no third-party MAVLink SDK. Adding any message
//! outside the §7.7 surface enumerated in [`MavlinkMessage`] requires an
//! explicit design-review note in the PR description.
pub mod crc;
pub mod decoder;
pub mod encoder;
pub mod messages;
pub mod parse_errors;
pub use decoder::{Decoder, DecoderEvent};
pub use encoder::Encoder;
pub use messages::{
Attitude, CommandAck, CommandLong, ExtendedSysState, GlobalPositionInt, Heartbeat,
MavlinkMessage, MissionAck, MissionClearAll, MissionCount, MissionCurrent, MissionItemInt,
MissionItemReached, MissionRequestInt, MissionSetCurrent, SetMode, StatusText, SysStatus,
};
pub use parse_errors::{ParseErrorKind, ParseErrors};
/// MAVLink v2 frame start byte.
pub const MAVLINK_V2_STX: u8 = 0xFD;
/// Frame header size in bytes (STX..msgid inclusive).
pub const HEADER_LEN: usize = 10;
/// CRC trailer length in bytes.
#[allow(dead_code)] // Used in the AZ-642 integration tests below and by AZ-643 signing math.
pub const CRC_LEN: usize = 2;
/// Signature trailer length when `incompat_flags` bit 0 is set.
pub const SIGNATURE_LEN: usize = 13;
/// Maximum possible payload length (255 per the spec).
pub const MAX_PAYLOAD: usize = 255;
/// Incompat-flag bit indicating a signed frame.
pub const INCOMPAT_FLAG_SIGNED: u8 = 0x01;
#[derive(Debug, thiserror::Error)]
pub enum MavlinkParseError {
#[error("truncated payload (have {have} bytes, need {need})")]
TruncatedPayload { have: usize, need: usize },
#[error("wrong CRC (computed {computed:#06x}, frame {frame:#06x})")]
CrcMismatch { computed: u16, frame: u16 },
#[error("unknown message id {0}")]
UnknownMessageId(u32),
#[error("invalid payload for message id {msg_id}: {reason}")]
InvalidPayload { msg_id: u32, reason: &'static str },
}