serial-mcp 0.7.2

MCP server for serial port communication. 22 tools (list/open/read/write/subscribe/get_status/reconfigure/list_profiles/open_profile/save_profile/delete_profile/get_log/clear_log/export_log/reconnect/...), resources, prompts, task cancellation, stdio + streamable-HTTP transports.
Documentation
//! Four-layer framing/parser precedence resolution.
//!
//! Single source of truth for the precedence rule:
//!
//! ```text
//! explicit call field > call-time protocol preset > connection default > connection protocol preset
//! ```
//!
//! Shared by `io_ops::write` (tx_framing), `io_ops::read` (rx_framing +
//! rx_parser), and `stream_ops::subscribe` (rx_framing + rx_parser). Keeping
//! the ladder in one place prevents the three hand-written copies from
//! drifting and makes every precedence boundary directly unit-testable.

use crate::framing::ProtocolPreset;

/// Resolve a single framing/parser field using the four-layer precedence
/// ladder.
///
/// Precedence (first non-`None` source wins):
/// 1. `explicit` — the per-call field.
/// 2. `call_protocol` — the per-call `protocol` preset, mapped through
///    `apply_preset`.
/// 3. `conn_default` — the connection default for this field.
/// 4. `conn_protocol` — the connection `protocol` preset, mapped through
///    `apply_preset`.
///
/// `apply_preset` is the matching `preset_*` function from `crate::framing`
/// for the field being resolved. `conn_default` is borrowed and cloned only
/// if reached.
pub(crate) fn resolve_field<T: Clone>(
    explicit: Option<T>,
    call_protocol: Option<ProtocolPreset>,
    apply_preset: impl Fn(ProtocolPreset) -> T,
    conn_default: Option<&T>,
    conn_protocol: Option<ProtocolPreset>,
) -> Option<T> {
    if let Some(explicit) = explicit {
        return Some(explicit);
    }
    if let Some(p) = call_protocol {
        return Some(apply_preset(p));
    }
    if let Some(def) = conn_default {
        return Some(def.clone());
    }
    conn_protocol.map(apply_preset)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::framing::{
        preset_rx_framing, preset_rx_parser, preset_tx_framing, LineEnding, ParserConfig,
        ParserType, ProtocolPreset, RxFramingConfig, RxFramingMode, TxFramingConfig, TxFramingMode,
        TxLineEnding,
    };
    use crate::match_config::PatternEncoding;

    const PROTO: Option<ProtocolPreset> = Some(ProtocolPreset::AtCommand);

    fn explicit_tx() -> TxFramingConfig {
        // A TX config that differs from the AtCommand preset (which uses Cr).
        TxFramingConfig {
            mode: TxFramingMode::Line {
                ending: TxLineEnding::Lf,
            },
        }
    }

    fn conn_default_tx() -> TxFramingConfig {
        // A TX config that differs from the AtCommand preset but is not the
        // same as `explicit_tx`.
        TxFramingConfig {
            mode: TxFramingMode::Line {
                ending: TxLineEnding::Crlf,
            },
        }
    }

    fn explicit_rx() -> RxFramingConfig {
        // An RX config that differs from the AtCommand preset (which uses Auto).
        RxFramingConfig {
            mode: RxFramingMode::Line {
                ending: LineEnding::Lf,
            },
            max_frames: None,
            include_terminators: false,
            skip_empty: false,
        }
    }

    fn conn_default_rx() -> RxFramingConfig {
        RxFramingConfig {
            mode: RxFramingMode::Line {
                ending: LineEnding::Cr,
            },
            max_frames: None,
            include_terminators: false,
            skip_empty: false,
        }
    }

    fn conn_default_parser() -> ParserConfig {
        // A parser config that differs from the AtCommand preset.
        ParserConfig {
            parser_type: ParserType::Raw,
            custom_prompt: None,
            validate: false,
        }
    }

    // --- TxFramingConfig tests ---

    #[test]
    fn explicit_beats_call_protocol() {
        let explicit = explicit_tx();
        let result = resolve_field::<TxFramingConfig>(
            Some(explicit.clone()),
            PROTO,
            preset_tx_framing,
            None,
            None,
        );
        assert!(result.is_some());
        assert_ne!(result, Some(preset_tx_framing(ProtocolPreset::AtCommand)));
        assert_eq!(result, Some(explicit));
    }

    #[test]
    fn call_protocol_beats_conn_default() {
        let conn_def = conn_default_tx();
        let result =
            resolve_field::<TxFramingConfig>(None, PROTO, preset_tx_framing, Some(&conn_def), None);
        assert_eq!(result, Some(preset_tx_framing(ProtocolPreset::AtCommand)));
        assert_ne!(result, Some(conn_def));
    }

    #[test]
    fn conn_default_beats_conn_protocol() {
        let conn_def = conn_default_tx();
        let result =
            resolve_field::<TxFramingConfig>(None, None, preset_tx_framing, Some(&conn_def), PROTO);
        assert_eq!(result, Some(conn_def));
        assert_ne!(result, Some(preset_tx_framing(ProtocolPreset::AtCommand)));
    }

    #[test]
    fn conn_protocol_is_fallback() {
        let result = resolve_field::<TxFramingConfig>(None, None, preset_tx_framing, None, PROTO);
        assert_eq!(result, Some(preset_tx_framing(ProtocolPreset::AtCommand)));
    }

    #[test]
    fn all_none_returns_none() {
        let result = resolve_field::<TxFramingConfig>(None, None, preset_tx_framing, None, None);
        assert_eq!(result, None);
    }

    #[test]
    fn mixed_gap_fill_rx_framing_explicit_plus_conn_protocol_parser() {
        // Explicit rx_framing wins; rx_parser falls through to conn_protocol.
        let explicit = explicit_rx();
        let rx_framing = resolve_field::<RxFramingConfig>(
            Some(explicit.clone()),
            None,
            preset_rx_framing,
            None,
            PROTO,
        );
        assert_eq!(rx_framing, Some(explicit));
        assert_ne!(
            rx_framing,
            Some(preset_rx_framing(ProtocolPreset::AtCommand))
        );

        let rx_parser = resolve_field::<ParserConfig>(None, None, preset_rx_parser, None, PROTO);
        assert_eq!(rx_parser, Some(preset_rx_parser(ProtocolPreset::AtCommand)));
    }

    // --- RxFramingConfig generic boundary test ---

    #[test]
    fn rx_framing_call_protocol_beats_conn_default() {
        let conn_def = conn_default_rx();
        let result =
            resolve_field::<RxFramingConfig>(None, PROTO, preset_rx_framing, Some(&conn_def), None);
        assert_eq!(result, Some(preset_rx_framing(ProtocolPreset::AtCommand)));
        assert_ne!(result, Some(conn_def));
    }

    // --- ParserConfig generic boundary test ---

    #[test]
    fn parser_call_protocol_beats_conn_default() {
        let conn_def = conn_default_parser();
        let result =
            resolve_field::<ParserConfig>(None, PROTO, preset_rx_parser, Some(&conn_def), None);
        assert_eq!(result, Some(preset_rx_parser(ProtocolPreset::AtCommand)));
        assert_ne!(result, Some(conn_def));
    }

    // --- Slip + JsonLines preset precedence tests ---

    #[test]
    fn slip_preset_explicit_framing_wins_over_preset() {
        // Explicit tx_framing (Line/Crlf) wins over call_protocol=Slip.
        let explicit = TxFramingConfig {
            mode: TxFramingMode::Line {
                ending: TxLineEnding::Crlf,
            },
        };
        let result = resolve_field::<TxFramingConfig>(
            Some(explicit.clone()),
            Some(ProtocolPreset::Slip),
            preset_tx_framing,
            None,
            None,
        );
        assert_eq!(result, Some(explicit));
        assert_ne!(result, Some(preset_tx_framing(ProtocolPreset::Slip)));
    }

    #[test]
    fn json_lines_preset_explicit_framing_wins_over_preset() {
        // Explicit rx_framing (Delimiter) wins over call_protocol=JsonLines.
        let explicit = RxFramingConfig {
            mode: RxFramingMode::Delimiter {
                delimiter: ",".into(),
                delimiter_encoding: PatternEncoding::Utf8,
            },
            max_frames: None,
            include_terminators: false,
            skip_empty: false,
        };
        let result = resolve_field::<RxFramingConfig>(
            Some(explicit.clone()),
            Some(ProtocolPreset::JsonLines),
            preset_rx_framing,
            None,
            None,
        );
        assert_eq!(result, Some(explicit));
        assert_ne!(result, Some(preset_rx_framing(ProtocolPreset::JsonLines)));
    }

    // --- COBS preset precedence test ---

    #[test]
    fn cobs_preset_explicit_framing_wins_over_preset() {
        // Explicit tx_framing (Line/Crlf) wins over call_protocol=Cobs.
        let explicit = TxFramingConfig {
            mode: TxFramingMode::Line {
                ending: TxLineEnding::Crlf,
            },
        };
        let result = resolve_field::<TxFramingConfig>(
            Some(explicit.clone()),
            Some(ProtocolPreset::Cobs),
            preset_tx_framing,
            None,
            None,
        );
        assert_eq!(result, Some(explicit));
        assert_ne!(result, Some(preset_tx_framing(ProtocolPreset::Cobs)));
    }

    #[test]
    fn ndjson_preset_explicit_framing_wins_over_preset() {
        // Explicit rx_framing (Delimiter) wins over call_protocol=Ndjson.
        let explicit = RxFramingConfig {
            mode: RxFramingMode::Delimiter {
                delimiter: ",".into(),
                delimiter_encoding: PatternEncoding::Utf8,
            },
            max_frames: None,
            include_terminators: false,
            skip_empty: false,
        };
        let result = resolve_field::<RxFramingConfig>(
            Some(explicit.clone()),
            Some(ProtocolPreset::Ndjson),
            preset_rx_framing,
            None,
            None,
        );
        assert_eq!(result, Some(explicit));
        assert_ne!(result, Some(preset_rx_framing(ProtocolPreset::Ndjson)));
    }

    // --- Nmea0183 preset precedence test ---

    #[test]
    fn nmea0183_preset_explicit_framing_wins_over_preset() {
        // Explicit tx_framing (Line/Crlf) wins over call_protocol=Nmea0183.
        let explicit = TxFramingConfig {
            mode: TxFramingMode::Line {
                ending: TxLineEnding::Crlf,
            },
        };
        let result = resolve_field::<TxFramingConfig>(
            Some(explicit.clone()),
            Some(ProtocolPreset::Nmea0183),
            preset_tx_framing,
            None,
            None,
        );
        assert_eq!(result, Some(explicit));
        assert_ne!(result, Some(preset_tx_framing(ProtocolPreset::Nmea0183)));
    }

    // --- ModbusAscii preset precedence test ---

    #[test]
    fn modbus_ascii_preset_explicit_framing_wins_over_preset() {
        // Explicit rx_framing (Line/Crlf) wins over call_protocol=ModbusAscii.
        let explicit = RxFramingConfig {
            mode: RxFramingMode::Line {
                ending: LineEnding::Crlf,
            },
            ..Default::default()
        };
        let result = resolve_field::<RxFramingConfig>(
            Some(explicit.clone()),
            Some(ProtocolPreset::ModbusAscii),
            preset_rx_framing,
            None,
            None,
        );
        assert_eq!(result, Some(explicit));
        assert_ne!(result, Some(preset_rx_framing(ProtocolPreset::ModbusAscii)));
    }

    // ── Medium-risk gap tests (P3d) ───────────────────────────────────────

    #[test]
    fn nmea0183_full_four_layer_precedence() {
        // Four-layer precedence (explicit > call_protocol > conn_default >
        // conn_protocol) exercised for Nmea0183 preset (gaps: existing
        // per-preset tests cover only 2 layers).
        //
        // Case (a): all 4 layers set; explicit wins over call_protocol,
        // conn_default, and conn_protocol.
        let explicit = RxFramingConfig {
            mode: RxFramingMode::Line {
                ending: LineEnding::Lf,
            },
            ..Default::default()
        };
        let conn_default_nmea = RxFramingConfig {
            mode: RxFramingMode::StartEnd {
                start: vec!["$".into()],
                end: "\r\n".into(),
                marker_encoding: PatternEncoding::Utf8,
                include_markers: false,
            },
            ..Default::default()
        };
        let result = resolve_field::<RxFramingConfig>(
            Some(explicit.clone()),
            Some(ProtocolPreset::Nmea0183),
            preset_rx_framing,
            Some(&conn_default_nmea),
            Some(ProtocolPreset::ModbusAscii),
        );
        assert_eq!(result, Some(explicit));
        assert_ne!(result, Some(preset_rx_framing(ProtocolPreset::Nmea0183)));

        // Case (b): explicit=None, call_protocol=None → conn_default wins
        // over conn_protocol. conn_default=Delimiter, conn_protocol=Nmea0183
        // (which would produce StartEnd framing). Result must be conn_default
        // (Delimiter).
        let conn_default_delim = RxFramingConfig {
            mode: RxFramingMode::Delimiter {
                delimiter: ",".into(),
                delimiter_encoding: PatternEncoding::Utf8,
            },
            max_frames: None,
            include_terminators: false,
            skip_empty: false,
        };
        let result = resolve_field::<RxFramingConfig>(
            None,
            None,
            preset_rx_framing,
            Some(&conn_default_delim),
            Some(ProtocolPreset::Nmea0183),
        );
        assert_eq!(result, Some(conn_default_delim));
        assert_ne!(result, Some(preset_rx_framing(ProtocolPreset::Nmea0183)));
    }
}