freeswitch_types/commands/

variables.rs

//! Channel variable scope and ordered key-value storage for originate commands.

use indexmap::IndexMap;
use std::fmt;
use std::str::FromStr;

use super::originate::OriginateError;

/// Scope for channel variables in an originate command.
///
/// - `Enterprise` (`<>`) -- applies across all threads (`:_:` separated)
/// - `Default` (`{}`) -- applies to all channels in this originate
/// - `Channel` (`[]`) -- applies only to one specific channel
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
#[non_exhaustive]
pub enum VariablesType {
    /// `<>` scope -- applies across all `:_:` separated threads.
    Enterprise,
    /// `{}` scope -- applies to all channels in this originate.
    Default,
    /// `[]` scope -- applies to one specific channel.
    Channel,
}

impl VariablesType {
    pub(super) fn delimiters(self) -> (char, char) {
        match self {
            Self::Enterprise => ('<', '>'),
            Self::Default => ('{', '}'),
            Self::Channel => ('[', ']'),
        }
    }

    fn backslash_escape(self) -> &'static str {
        match self {
            Self::Enterprise | Self::Default => BACKSLASH,
            Self::Channel => BACKSLASH_CHANNEL,
        }
    }
}

/// Ordered set of channel variables with FreeSWITCH escaping.
///
/// A comma is escaped with `\,`, a backslash and a single quote with as many
/// backslashes as the carrier's passes consume, and a value with spaces is
/// wrapped in single quotes. This form round-trips through [`FromStr`]; what the
/// switch itself decodes depends on which command carries the block, and is
/// documented in `docs/dial-string-format.md`.
///
/// # Serde format
///
/// [`Default`](VariablesType::Default) scope with the comma separator
/// serializes as a flat JSON map: `{"key": "value", ...}`. Anything else
/// serializes as `{"scope": "enterprise", "vars": {"key": "value"}}`, carrying
/// a `"separator"` field only when [`with_separator`](Variables::with_separator)
/// chose one. Deserialization accepts both formats; a flat map implies
/// `Default` scope and the comma. A `separator` that cannot delimit the block,
/// or that a value already contains, is refused at load.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Variables {
    vars_type: VariablesType,
    inner: IndexMap<String, String>,
    /// Set by [`with_separator`](Variables::with_separator). Parsing a `^^`
    /// block does not populate it: reading one back and writing it out
    /// canonicalises to a comma, and the other form is asked for explicitly.
    separator: Option<char>,
}

/// Which command carries a dial string, and therefore how deeply its variable
/// values must be escaped.
///
/// FreeSWITCH escape-processes a bracket block a different number of times
/// depending on the command it arrived on, and the correct escaping of a value
/// containing a single quote differs between them with no form that satisfies
/// both. Naming the carrier is the only way a renderer can be right.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
pub enum DialStringCarrier {
    /// `api originate` / `bgapi originate`, whose argument list is split before
    /// the block itself is parsed. The default for [`Display`](fmt::Display).
    EslApi,
    /// A dialplan application such as `bridge`, including via `sendmsg execute`,
    /// which receives its argument whole.
    Dialplan,
}

/// A literal backslash, whatever follows it, in a block parsed before the dial
/// string is split into legs.
const BACKSLASH: &str = r"\\\\\\\\";
/// The same in a `[]` block, which rides through the `|` and `,` leg splits
/// first and so meets two more passes.
const BACKSLASH_CHANNEL: &str = r"\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\";
/// A literal single quote, per carrier: still `\'` entering the last pass.
const QUOTE_DIALPLAN: &str = r"\\\\\\'";
const QUOTE_ESL_API: &str = r"\\\\\\\'";

impl DialStringCarrier {
    fn quote_escape(self) -> &'static str {
        match self {
            Self::EslApi => QUOTE_ESL_API,
            Self::Dialplan => QUOTE_DIALPLAN,
        }
    }
}

/// Reject a value the wire cannot carry, whatever escaping is applied to it.
///
/// Three shapes qualify. An empty value is discarded by the switch under every
/// encoding, and the block's own parse reports nothing when it happens. A value
/// carrying an unbalanced bracket ends the block early, because the switch finds
/// the block's end by counting depth and does not honour escapes while doing so;
/// a balanced pair such as `${var}` is fine and common. A single quote in a
/// channel-scope value pairs with the next quote anywhere before the peer split,
/// escaped or not, and the pair between them is swallowed into the first value.
fn check_representable(
    key: &str,
    value: &str,
    vars_type: VariablesType,
) -> Result<(), OriginateError> {
    if vars_type == VariablesType::Channel && value.contains('\'') {
        return Err(OriginateError::ParseError(format!(
            "variable {key} carries a single quote in channel scope: the switch \
             pairs it with the next quote in the dial string before it parses \
             the block, whatever escaping precedes either. Use default scope, \
             or keep the quote out of the value"
        )));
    }
    if value.is_empty() {
        return Err(OriginateError::ParseError(format!(
            "variable {key} has an empty value: the switch discards such a pair \
             without logging it, so it cannot be told from an absent variable on \
             the wire. Give it a value or remove it -- and if its presence was \
             itself the signal, that signal needs a home outside the dial string"
        )));
    }

    let (open, close) = vars_type.delimiters();
    let mut depth = 0i32;
    for ch in value.chars() {
        if ch == open {
            depth += 1;
        } else if ch == close {
            depth -= 1;
            if depth < 0 {
                return Err(OriginateError::ParseError(format!(
                    "variable {key} closes a '{open}' it never opened, ending the block early"
                )));
            }
        }
    }
    if depth != 0 {
        return Err(OriginateError::ParseError(format!(
            "variable {key} opens a '{open}' it never closes, swallowing the block's end"
        )));
    }
    Ok(())
}

/// Reject a separator that cannot delimit the block it was chosen for.
///
/// Either bracket moves the end the switch counts its way to, `=` splits the
/// pair instead, `^` leaves the `^^` prefix reading as its own separator, and
/// `|` in a `[]` block is read by the leg split before the block is parsed.
fn check_separator(sep: char, vars_type: VariablesType) -> Result<(), OriginateError> {
    let (open, close) = vars_type.delimiters();
    if sep == open
        || sep == close
        || sep == '='
        || sep == '^'
        || (sep == '|' && vars_type == VariablesType::Channel)
    {
        return Err(OriginateError::ParseError(format!(
            "invalid ^^ separator: '{sep}'"
        )));
    }
    Ok(())
}

/// Escape a value for the wire, escaping the comma only when `commas_separate`
/// says it is this block's separator; a `^^` block separates on something else
/// and refuses a value carrying it, so a comma there is ordinary text. A `[]`
/// block also escapes the pipe, which the leg split would otherwise read.
fn escape_value(
    value: &str,
    carrier: DialStringCarrier,
    commas_separate: bool,
    vars_type: VariablesType,
) -> String {
    // The backslash goes first, or the ones the other rules introduce get
    // escaped in turn.
    let escaped = value
        .replace('\\', vars_type.backslash_escape())
        .replace('\'', carrier.quote_escape());
    let escaped = if commas_separate {
        escaped.replace(',', "\\,")
    } else {
        escaped
    };
    let escaped = if vars_type == VariablesType::Channel {
        escaped.replace('|', "\\|")
    } else {
        escaped
    };
    if escaped.contains(' ') {
        format!("'{}'", escaped)
    } else {
        escaped
    }
}

/// Inverts [`escape_value`], undoing each substitution in the reverse order it
/// was applied so an escape introduced by a later rule is not read as input to
/// an earlier one.
fn unescape_value(
    value: &str,
    carrier: DialStringCarrier,
    commas_separate: bool,
    vars_type: VariablesType,
) -> String {
    let s = value
        .strip_prefix('\'')
        .and_then(|s| s.strip_suffix('\''))
        .unwrap_or(value);

    let s = if vars_type == VariablesType::Channel {
        s.replace("\\|", "|")
    } else {
        s.to_string()
    };
    let s = if commas_separate {
        s.replace("\\,", ",")
    } else {
        s
    };
    s.replace(carrier.quote_escape(), "'")
        .replace(vars_type.backslash_escape(), "\\")
}

impl Variables {
    /// Create an empty variable set with the given scope.
    pub fn new(vars_type: VariablesType) -> Self {
        Self {
            vars_type,
            inner: IndexMap::new(),
            separator: None,
        }
    }

    /// Create from an existing set of key-value pairs.
    pub fn with_vars(
        vars_type: VariablesType,
        vars: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
    ) -> Self {
        Self {
            vars_type,
            inner: vars
                .into_iter()
                .map(|(k, v)| (k.into(), v.into()))
                .collect(),
            separator: None,
        }
    }

    /// Separate the pairs with `sep` instead of a comma, emitting the block in
    /// FreeSWITCH's `^^<sep>` form.
    ///
    /// A value expanded from `${...}` in a dialplan is substituted before the
    /// block is parsed, so no escaping can be inserted into it; choosing a
    /// separator none of the values contain is the only way such a value can
    /// carry a comma. The separator is given rather than derived, so a block
    /// renders the same way whatever its values happen to be that call.
    ///
    /// Fails if `sep` cannot delimit this block, or if a value already present
    /// contains it. A value inserted afterwards is not checked: one carrying
    /// `sep` splits into a pair nobody wrote, silently, until
    /// [`insert`](Self::insert) becomes fallible (`docs/next-major.md`).
    pub fn with_separator(mut self, sep: char) -> Result<Self, OriginateError> {
        check_separator(sep, self.vars_type)?;
        if let Some((key, _)) = self
            .inner
            .iter()
            .find(|(_, v)| v.contains(sep))
        {
            return Err(OriginateError::ParseError(format!(
                "variable {key} contains the chosen '{sep}' separator"
            )));
        }
        self.separator = Some(sep);
        Ok(self)
    }

    /// The `^^` separator this block renders with, if one was chosen.
    pub fn separator(&self) -> Option<char> {
        self.separator
    }

    /// Insert or overwrite a variable.
    pub fn insert(&mut self, key: impl Into<String>, value: impl Into<String>) {
        self.inner
            .insert(key.into(), value.into());
    }

    /// Remove a variable by name, returning its value if it existed.
    pub fn remove(&mut self, key: &str) -> Option<String> {
        self.inner
            .shift_remove(key)
    }

    /// Look up a variable by name.
    pub fn get(&self, key: &str) -> Option<&str> {
        self.inner
            .get(key)
            .map(|s| s.as_str())
    }

    /// Whether the set contains no variables.
    pub fn is_empty(&self) -> bool {
        self.inner
            .is_empty()
    }

    /// Number of variables.
    pub fn len(&self) -> usize {
        self.inner
            .len()
    }

    /// Variable scope (Enterprise, Default, or Channel).
    pub fn scope(&self) -> VariablesType {
        self.vars_type
    }

    /// Change the variable scope.
    pub fn set_scope(&mut self, scope: VariablesType) {
        self.vars_type = scope;
    }

    /// Iterate over key-value pairs in insertion order.
    pub fn iter(&self) -> impl Iterator<Item = (&str, &str)> {
        self.inner
            .iter()
            .map(|(k, v)| (k.as_str(), v.as_str()))
    }

    /// Mutable iterator over key-value pairs in insertion order.
    pub fn iter_mut(&mut self) -> impl Iterator<Item = (&str, &mut String)> {
        self.inner
            .iter_mut()
            .map(|(k, v)| (k.as_str(), v))
    }

    /// Mutable iterator over values in insertion order.
    pub fn values_mut(&mut self) -> impl Iterator<Item = &mut String> {
        self.inner
            .values_mut()
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for Variables {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        if self.vars_type == VariablesType::Default
            && self
                .separator
                .is_none()
        {
            self.inner
                .serialize(serializer)
        } else {
            use serde::ser::SerializeStruct;
            let fields = 2 + usize::from(
                self.separator
                    .is_some(),
            );
            let mut s = serializer.serialize_struct("Variables", fields)?;
            s.serialize_field("scope", &self.vars_type)?;
            s.serialize_field("vars", &self.inner)?;
            if let Some(sep) = self.separator {
                s.serialize_field("separator", &sep)?;
            }
            s.end()
        }
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for Variables {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        #[derive(serde::Deserialize)]
        #[serde(untagged)]
        enum VariablesRepr {
            Scoped {
                scope: VariablesType,
                vars: IndexMap<String, String>,
                #[serde(default)]
                separator: Option<char>,
            },
            Flat(IndexMap<String, String>),
        }

        let (vars_type, inner, separator) = match VariablesRepr::deserialize(deserializer)? {
            VariablesRepr::Scoped {
                scope,
                vars,
                separator,
            } => (scope, vars, separator),
            VariablesRepr::Flat(map) => (VariablesType::Default, map, None),
        };
        // A config naming a value the wire cannot carry fails at load rather
        // than on the call it was loaded for.
        for (key, value) in &inner {
            check_representable(key, value, vars_type).map_err(serde::de::Error::custom)?;
        }
        let vars = Self {
            vars_type,
            inner,
            separator: None,
        };
        match separator {
            Some(sep) => vars
                .with_separator(sep)
                .map_err(serde::de::Error::custom),
            None => Ok(vars),
        }
    }
}

/// Renders a [`Variables`] for one carrier. Returned by
/// [`Variables::display_for`].
#[derive(Debug, Clone, Copy)]
pub struct VariablesDisplay<'a> {
    vars: &'a Variables,
    carrier: DialStringCarrier,
}

impl fmt::Display for VariablesDisplay<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.vars
            .write_for(f, self.carrier)
    }
}

impl Variables {
    /// Render for a named carrier, rather than the [`DialStringCarrier::EslApi`]
    /// default that [`Display`](fmt::Display) uses.
    pub fn display_for(&self, carrier: DialStringCarrier) -> VariablesDisplay<'_> {
        VariablesDisplay {
            vars: self,
            carrier,
        }
    }

    pub(super) fn write_for(
        &self,
        f: &mut fmt::Formatter<'_>,
        carrier: DialStringCarrier,
    ) -> fmt::Result {
        let (open, close) = self
            .vars_type
            .delimiters();
        f.write_fmt(format_args!("{}", open))?;
        if let Some(sep) = self.separator {
            write!(f, "^^{sep}")?;
        }
        // A chosen separator carries the values that a comma would have needed
        // escaping for, so only the comma form escapes them.
        let commas_separate = self
            .separator
            .is_none();
        let sep = self
            .separator
            .unwrap_or(',');
        for (i, (key, value)) in self
            .inner
            .iter()
            .enumerate()
        {
            if i > 0 {
                write!(f, "{sep}")?;
            }
            let value = escape_value(value, carrier, commas_separate, self.vars_type);
            write!(f, "{}={}", key, value)?;
        }
        f.write_fmt(format_args!("{}", close))
    }
}

impl fmt::Display for Variables {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.write_for(f, DialStringCarrier::EslApi)
    }
}

impl FromStr for Variables {
    type Err = OriginateError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        Self::parse_for(s, DialStringCarrier::EslApi)
    }
}

impl Variables {
    /// Parse a block written for a named carrier, mirroring
    /// [`display_for`](Self::display_for). [`FromStr`] uses the same
    /// [`DialStringCarrier::EslApi`] default as [`Display`](fmt::Display), so
    /// the two round-trip.
    pub fn parse_for(s: &str, carrier: DialStringCarrier) -> Result<Self, OriginateError> {
        let s = s.trim();
        if s.len() < 2 {
            return Err(OriginateError::ParseError(
                "variable block too short".into(),
            ));
        }

        let (vars_type, inner_str) = match (s.as_bytes()[0], s.as_bytes()[s.len() - 1]) {
            (b'{', b'}') => (VariablesType::Default, &s[1..s.len() - 1]),
            (b'<', b'>') => (VariablesType::Enterprise, &s[1..s.len() - 1]),
            (b'[', b']') => (VariablesType::Channel, &s[1..s.len() - 1]),
            (open, close) => {
                return Err(OriginateError::ParseError(format!(
                    "unknown variable delimiters: {:?}..{:?}",
                    open as char, close as char
                )));
            }
        };

        let (sep, var_str) = match inner_str.strip_prefix("^^") {
            Some(rest) => {
                let sep = rest
                    .chars()
                    .next()
                    .ok_or_else(|| {
                        OriginateError::ParseError("^^ without separator character".into())
                    })?;
                check_separator(sep, vars_type)?;
                (sep, &rest[sep.len_utf8()..])
            }
            None => (',', inner_str),
        };
        let commas_separate = sep == ',';

        let mut inner = IndexMap::new();
        if !var_str.is_empty() {
            for (i, part) in split_unescaped(var_str, sep)
                .into_iter()
                .enumerate()
            {
                let (key, value) = part
                    .split_once('=')
                    .ok_or_else(|| {
                        OriginateError::ParseError(format!("missing = in variable {i}"))
                    })?;
                let value = unescape_value(value, carrier, commas_separate, vars_type);
                check_representable(key, &value, vars_type)?;
                inner.insert(key.to_string(), value);
            }
        }

        Ok(Self {
            vars_type,
            inner,
            separator: None,
        })
    }
}

/// Split on separators that are not escaped by a backslash.
///
/// A separator preceded by an odd number of backslashes is escaped (e.g. `\,`).
/// One preceded by an even number is a real split point (e.g. `\\,` is an
/// escaped backslash followed by the delimiter).
fn split_unescaped(s: &str, sep: char) -> Vec<&str> {
    let mut parts = Vec::new();
    let mut start = 0;
    let bytes = s.as_bytes();

    for (i, ch) in s.char_indices() {
        if ch == sep {
            let mut backslashes = 0;
            let mut j = i;
            while j > 0 && bytes[j - 1] == b'\\' {
                backslashes += 1;
                j -= 1;
            }
            if backslashes % 2 == 0 {
                parts.push(&s[start..i]);
                start = i + ch.len_utf8();
            }
        }
    }
    parts.push(&s[start..]);
    parts
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Measured on a live switch: an empty value is discarded under every
    /// encoding, silently, so nothing can be emitted for one and the refusal
    /// has to name a remedy the caller could not guess.
    #[test]
    fn an_empty_value_is_refused_at_the_boundary() {
        let err = "{k=,after=sentinel}"
            .parse::<Variables>()
            .unwrap_err()
            .to_string();
        assert!(err.contains('k'), "error does not name the variable: {err}");
        assert!(
            err.contains("remove it"),
            "error does not name a remedy: {err}"
        );
        // Prescribing removal alone is wrong for a caller whose *presence* test
        // is the signal: dropping the key silently reverses that decision.
        assert!(
            err.contains("presence"),
            "error prescribes a fix without allowing that presence meant something: {err}"
        );
    }

    /// The switch finds a block's end by counting bracket depth and honours no
    /// escape while doing so, so a value closing a bracket it never opened ends
    /// the block early and the rest becomes dial-string text.
    #[test]
    fn an_unbalanced_bracket_is_refused_while_a_balanced_one_is_not() {
        assert!("{k=oops}extra}"
            .parse::<Variables>()
            .is_err());

        let balanced: Variables = "{k=${some_var}}"
            .parse()
            .expect("a balanced ${...} is ordinary and must parse");
        assert_eq!(balanced.get("k"), Some("${some_var}"));
    }

    /// A chosen separator is what carries a comma through a value that was
    /// expanded before the block was parsed, so the comma must survive as
    /// ordinary text rather than picking up an escape.
    #[test]
    fn chosen_separator_leaves_commas_alone() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("codecs", "PCMA,PCMU,G729");
        let vars = vars
            .with_separator(':')
            .unwrap();

        assert_eq!(vars.to_string(), "{^^:codecs=PCMA,PCMU,G729}");
        assert_eq!(vars.separator(), Some(':'));
    }

    #[test]
    fn separator_that_cannot_delimit_the_block_is_refused() {
        let vars = Variables::new(VariablesType::Channel);
        for sep in ['[', ']', '=', '^'] {
            assert!(
                vars.clone()
                    .with_separator(sep)
                    .is_err(),
                "accepted {sep:?}"
            );
        }
    }

    /// The parser has to refuse what the builder refuses, `^` included:
    /// accepting a block no render of this crate can reproduce hands the caller
    /// a value that changes when it is written back out.
    #[test]
    fn the_parser_refuses_every_separator_the_builder_does() {
        for sep in ['[', ']', '=', '^'] {
            assert!(
                format!("[^^{sep}a=1{sep}b=2]")
                    .parse::<Variables>()
                    .is_err(),
                "parser accepted {sep:?}"
            );
        }
    }

    /// Refusing here is the whole point: a value carrying the separator would
    /// split into a pair that was never written, and the switch reports nothing.
    #[test]
    fn separator_already_present_in_a_value_is_refused() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("uri", "sip:bob@example.com");
        let err = vars
            .with_separator(':')
            .unwrap_err()
            .to_string();
        assert!(
            err.contains("uri"),
            "error does not name the variable: {err}"
        );
    }

    /// Measured against a live switch, with two awkward values in one block —
    /// a block carrying only one is more forgiving and hides the failure.
    /// Sweeping the backslash count, each carrier succeeds at counts the other
    /// fails, so these forms are the wire contract and not a preference.
    #[test]
    fn escaping_pins_the_measured_wire_forms() {
        let cases = [
            (DialStringCarrier::Dialplan, "it's", r"it\\\\\\'s"),
            (DialStringCarrier::EslApi, "it's", r"it\\\\\\\'s"),
            (DialStringCarrier::Dialplan, "l'a'b", r"l\\\\\\'a\\\\\\'b"),
            (DialStringCarrier::EslApi, "l'a'b", r"l\\\\\\\'a\\\\\\\'b"),
            (DialStringCarrier::Dialplan, r"a\nb", r"a\\\\\\\\nb"),
            (DialStringCarrier::EslApi, r"a\nb", r"a\\\\\\\\nb"),
            (DialStringCarrier::Dialplan, "a,b", r"a\,b"),
            (DialStringCarrier::EslApi, "a,b", r"a\,b"),
            (DialStringCarrier::Dialplan, "a|b", "a|b"),
            (DialStringCarrier::EslApi, "a|b", "a|b"),
        ];
        for (carrier, value, want) in cases {
            assert_eq!(
                escape_value(value, carrier, true, VariablesType::Default),
                want,
                "{value:?} for {carrier:?}"
            );
        }
    }

    /// A `[]` block rides through the leg splits before it is parsed: two more
    /// backslash-consuming passes, and a pipe the first of them would read.
    #[test]
    fn channel_scope_escapes_for_the_leg_splits() {
        let cases = [
            (
                DialStringCarrier::Dialplan,
                r"a\nb",
                r"a\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\nb",
            ),
            (
                DialStringCarrier::EslApi,
                r"a\nb",
                r"a\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\nb",
            ),
            (DialStringCarrier::Dialplan, "a|b", r"a\|b"),
            (DialStringCarrier::EslApi, "a|b", r"a\|b"),
            (DialStringCarrier::EslApi, "a,b", r"a\,b"),
        ];
        for (carrier, value, want) in cases {
            assert_eq!(
                escape_value(value, carrier, true, VariablesType::Channel),
                want,
                "{value:?} for {carrier:?}"
            );
        }
    }

    /// A `^^` block reaches the switch's tokenizer as often as the comma form,
    /// so every rule above still holds there; only the comma stops being the
    /// separator and so stops being escaped.
    #[test]
    fn a_chosen_separator_changes_only_the_comma() {
        let cases = [
            (DialStringCarrier::Dialplan, "it's", r"it\\\\\\'s"),
            (DialStringCarrier::EslApi, "it's", r"it\\\\\\\'s"),
            (DialStringCarrier::Dialplan, "l'a'b", r"l\\\\\\'a\\\\\\'b"),
            (DialStringCarrier::EslApi, "l'a'b", r"l\\\\\\\'a\\\\\\\'b"),
            (DialStringCarrier::Dialplan, r"a\nb", r"a\\\\\\\\nb"),
            (DialStringCarrier::EslApi, r"a\nb", r"a\\\\\\\\nb"),
            (DialStringCarrier::Dialplan, "a,b", "a,b"),
            (DialStringCarrier::EslApi, "a,b", "a,b"),
        ];
        for (carrier, value, want) in cases {
            assert_eq!(
                escape_value(value, carrier, false, VariablesType::Default),
                want,
                "{value:?} for {carrier:?}"
            );
        }
    }

    /// The crate exists to drive `api originate`, so a block rendered with no
    /// carrier named is rendered for that one.
    #[test]
    fn display_defaults_to_the_api_carrier() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("k", "it's");
        assert_eq!(vars.to_string(), r"{k=it\\\\\\\'s}");
        assert_eq!(
            vars.display_for(DialStringCarrier::Dialplan)
                .to_string(),
            r"{k=it\\\\\\'s}"
        );
    }

    #[test]
    fn round_trips_at_either_carrier() {
        for carrier in [DialStringCarrier::EslApi, DialStringCarrier::Dialplan] {
            for value in ["it's", r"a\,b", r"C:\path", "a,b", "with space"] {
                let mut vars = Variables::new(VariablesType::Default);
                vars.insert("k", value);
                vars.insert("after", "sentinel");
                let rendered = vars
                    .display_for(carrier)
                    .to_string();

                let back = Variables::parse_for(&rendered, carrier).unwrap_or_else(|e| {
                    panic!("{value:?} for {carrier:?} rendered {rendered}: {e}")
                });
                assert_eq!(back.get("k"), Some(value), "rendered {rendered}");
                assert_eq!(back.get("after"), Some("sentinel"), "rendered {rendered}");
            }
        }
    }

    /// A chosen separator changes which character needs escaping, not whether
    /// the block is escape-processed: the switch runs the same tokenizer over
    /// it, so a value still comes back through the same undoing.
    #[test]
    fn separated_block_round_trips_at_either_carrier() {
        for carrier in [DialStringCarrier::EslApi, DialStringCarrier::Dialplan] {
            for value in ["it's", "a,b", r"C:\path", r"a\nb", "with space"] {
                let mut vars = Variables::new(VariablesType::Default);
                vars.insert("k", value);
                vars.insert("after", "sentinel");
                let vars = vars
                    .with_separator('~')
                    .expect("'~' appears in none of these values");
                let rendered = vars
                    .display_for(carrier)
                    .to_string();

                let back = Variables::parse_for(&rendered, carrier).unwrap_or_else(|e| {
                    panic!("{value:?} for {carrier:?} rendered {rendered}: {e}")
                });
                assert_eq!(back.get("k"), Some(value), "rendered {rendered}");
                assert_eq!(back.get("after"), Some("sentinel"), "rendered {rendered}");
            }
        }
    }

    /// `split_unescaped_commas` reads a comma behind an even number of
    /// backslashes as a real separator, so a value ending in a backslash has to
    /// be written with its own backslash escaped or the writer contradicts the
    /// reader and the block no longer parses.
    #[test]
    fn value_with_backslash_round_trips() {
        for value in [r"a\,b", r"C:\path", r"trailing\", r"\\", r"a\nb"] {
            let mut vars = Variables::new(VariablesType::Default);
            vars.insert("k", value);
            vars.insert("after", "sentinel");
            let rendered = vars.to_string();

            let back: Variables = rendered
                .parse()
                .unwrap_or_else(|e| {
                    panic!("{value:?} rendered {rendered} and failed to parse: {e}")
                });
            assert_eq!(back.get("k"), Some(value), "rendered {rendered}");
            assert_eq!(
                back.get("after"),
                Some("sentinel"),
                "value {value:?} ate the next variable: {rendered}"
            );
        }
    }

    /// A variable block holds dialled numbers and passthrough header values, so a
    /// malformed part is reported by position.
    #[test]
    fn missing_equals_error_omits_the_fragment() {
        let msg = "{origination_caller_id_number=15551234567,15550009999}"
            .parse::<Variables>()
            .unwrap_err()
            .to_string();
        assert!(
            !msg.contains("15550009999"),
            "error quoted its input: {msg}"
        );
        assert!(
            msg.contains("variable 1"),
            "error does not name the part: {msg}"
        );
    }

    #[test]
    fn unknown_delimiters_error_omits_the_block() {
        let msg = "(origination_caller_id_number=15551234567)"
            .parse::<Variables>()
            .unwrap_err()
            .to_string();
        assert!(
            !msg.contains("15551234567"),
            "error quoted its input: {msg}"
        );
    }

    #[test]
    fn variables_standard_chars() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("test_key", "this_value");
        vars.insert("second", "2");
        assert_eq!(vars.to_string(), "{test_key=this_value,second=2}");
    }

    #[test]
    fn variables_comma_escaped() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("test_key", "this,is,a,value");
        let result = vars.to_string();
        assert!(result.contains("\\,"));
    }

    #[test]
    fn variables_spaces_quoted() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("test_key", "this is a value");
        let result = vars.to_string();
        assert_eq!(
            result
                .matches('\'')
                .count(),
            2
        );
    }

    #[test]
    fn variables_single_quote_escaped() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("test_key", "let's_this_be_a_value");
        let result = vars.to_string();
        assert!(result.contains("\\'"));
    }

    #[test]
    fn variables_enterprise_delimiters() {
        let mut vars = Variables::new(VariablesType::Enterprise);
        vars.insert("k", "v");
        let result = vars.to_string();
        assert!(result.starts_with('<'));
        assert!(result.ends_with('>'));
    }

    #[test]
    fn variables_channel_delimiters() {
        let mut vars = Variables::new(VariablesType::Channel);
        vars.insert("k", "v");
        let result = vars.to_string();
        assert!(result.starts_with('['));
        assert!(result.ends_with(']'));
    }

    #[test]
    fn variables_default_delimiters() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("k", "v");
        let result = vars.to_string();
        assert!(result.starts_with('{'));
        assert!(result.ends_with('}'));
    }

    #[test]
    fn variables_parse_round_trip() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("origination_caller_id_number", "9005551212");
        vars.insert("sip_h_Call-Info", "<url>;meta=123,<uri>");
        let s = vars.to_string();
        let parsed: Variables = s
            .parse()
            .unwrap();
        assert_eq!(
            parsed.get("origination_caller_id_number"),
            Some("9005551212")
        );
        assert_eq!(parsed.get("sip_h_Call-Info"), Some("<url>;meta=123,<uri>"));
    }

    #[test]
    fn split_unescaped_basic() {
        assert_eq!(split_unescaped("a,b,c", ','), vec!["a", "b", "c"]);
        assert_eq!(split_unescaped("a~b~c", '~'), vec!["a", "b", "c"]);
    }

    #[test]
    fn split_unescaped_escaped() {
        assert_eq!(split_unescaped(r"a\,b,c", ','), vec![r"a\,b", "c"]);
    }

    #[test]
    fn split_unescaped_double_backslash() {
        // \\, = escaped backslash + comma delimiter
        assert_eq!(split_unescaped(r"a\\,b", ','), vec![r"a\\", "b"]);
    }

    #[test]
    fn split_unescaped_triple_backslash() {
        // \\\, = escaped backslash + escaped comma (no split)
        assert_eq!(split_unescaped(r"a\\\,b", ','), vec![r"a\\\,b"]);
    }

    #[test]
    fn variables_caret_caret_separator() {
        let vars: Variables =
            "[^^:sip_invite_domain=pbx.example.com:presence_id=1211@pbx.example.com]"
                .parse()
                .unwrap();
        assert_eq!(vars.scope(), VariablesType::Channel);
        assert_eq!(vars.get("sip_invite_domain"), Some("pbx.example.com"));
        assert_eq!(vars.get("presence_id"), Some("1211@pbx.example.com"));
    }

    #[test]
    fn variables_caret_caret_display_uses_canonical_comma() {
        let vars: Variables = "[^^:a=1:b=2]"
            .parse()
            .unwrap();
        assert_eq!(vars.to_string(), "[a=1,b=2]");
    }

    #[test]
    fn variables_caret_caret_default_scope() {
        let vars: Variables = "{^^|x=1|y=2}"
            .parse()
            .unwrap();
        assert_eq!(vars.scope(), VariablesType::Default);
        assert_eq!(vars.get("x"), Some("1"));
        assert_eq!(vars.get("y"), Some("2"));
    }

    #[test]
    fn variables_caret_caret_enterprise_scope() {
        let vars: Variables = "<^^;a=1;b=2>"
            .parse()
            .unwrap();
        assert_eq!(vars.scope(), VariablesType::Enterprise);
        assert_eq!(vars.get("a"), Some("1"));
    }

    /// The switch consumes a backslash only before a quote, another backslash,
    /// the separator in force, or a character it has an escape for -- so in a
    /// block separated on something else, `\,` is two literal characters.
    #[test]
    fn variables_caret_caret_keeps_an_escaped_comma_literal() {
        let vars: Variables = r"[^^:key=val\,ue:other=x]"
            .parse()
            .unwrap();
        assert_eq!(vars.get("key"), Some(r"val\,ue"));
    }

    #[test]
    fn variables_caret_caret_values_with_commas() {
        let vars: Variables = "{^^|sip_h_X-Call-Info=<urn:foo>;purpose=bar,<urn:baz>|other=val}"
            .parse()
            .unwrap();
        assert_eq!(
            vars.get("sip_h_X-Call-Info"),
            Some("<urn:foo>;purpose=bar,<urn:baz>")
        );
        assert_eq!(vars.get("other"), Some("val"));
    }

    #[test]
    fn variables_caret_caret_empty_vars() {
        let vars: Variables = "[^^:]"
            .parse()
            .unwrap();
        assert!(vars.is_empty());
        assert_eq!(vars.scope(), VariablesType::Channel);
    }

    #[test]
    fn variables_caret_caret_missing_separator() {
        assert!("[^^]"
            .parse::<Variables>()
            .is_err());
    }

    #[test]
    fn variables_caret_caret_closing_bracket_as_sep() {
        assert!("[^^]]"
            .parse::<Variables>()
            .is_err());
    }

    #[test]
    fn variables_caret_caret_equals_as_sep() {
        assert!("[^^=a=1]"
            .parse::<Variables>()
            .is_err());
    }

    #[test]
    fn variables_from_str_empty_block() {
        let result = "{}".parse::<Variables>();
        assert!(
            result.is_ok(),
            "empty variable block should parse successfully"
        );
        let vars = result.unwrap();
        assert!(
            vars.is_empty(),
            "parsed empty block should have no variables"
        );
    }

    #[test]
    fn variables_from_str_empty_channel_block() {
        let result = "[]".parse::<Variables>();
        assert!(result.is_ok());
        let vars = result.unwrap();
        assert!(vars.is_empty());
        assert_eq!(vars.scope(), VariablesType::Channel);
    }

    #[test]
    fn variables_from_str_empty_enterprise_block() {
        let result = "<>".parse::<Variables>();
        assert!(result.is_ok());
        let vars = result.unwrap();
        assert!(vars.is_empty());
        assert_eq!(vars.scope(), VariablesType::Enterprise);
    }

    #[test]
    fn serde_variables_type() {
        let json = serde_json::to_string(&VariablesType::Enterprise).unwrap();
        assert_eq!(json, "\"enterprise\"");
        let parsed: VariablesType = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, VariablesType::Enterprise);
    }

    #[test]
    fn serde_variables_flat_default() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("key1", "val1");
        vars.insert("key2", "val2");
        let json = serde_json::to_string(&vars).unwrap();
        let parsed: Variables = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.scope(), VariablesType::Default);
        assert_eq!(parsed.get("key1"), Some("val1"));
        assert_eq!(parsed.get("key2"), Some("val2"));
    }

    #[test]
    fn serde_variables_scoped_enterprise() {
        let mut vars = Variables::new(VariablesType::Enterprise);
        vars.insert("key1", "val1");
        let json = serde_json::to_string(&vars).unwrap();
        assert!(json.contains("\"enterprise\""));
        let parsed: Variables = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.scope(), VariablesType::Enterprise);
        assert_eq!(parsed.get("key1"), Some("val1"));
    }

    #[test]
    fn serde_variables_flat_map_deserializes_as_default() {
        let json = r#"{"key1":"val1","key2":"val2"}"#;
        let vars: Variables = serde_json::from_str(json).unwrap();
        assert_eq!(vars.scope(), VariablesType::Default);
        assert_eq!(vars.get("key1"), Some("val1"));
        assert_eq!(vars.get("key2"), Some("val2"));
    }

    #[test]
    fn serde_variables_scoped_deserializes() {
        let json = r#"{"scope":"channel","vars":{"k":"v"}}"#;
        let vars: Variables = serde_json::from_str(json).unwrap();
        assert_eq!(vars.scope(), VariablesType::Channel);
        assert_eq!(vars.get("k"), Some("v"));
    }

    /// A block whose separator is dropped by a round trip renders as a comma
    /// block, which splits the very value the separator was chosen to carry.
    #[test]
    fn serde_variables_separator_round_trips() {
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("codecs", "PCMA,PCMU");
        let vars = vars
            .with_separator('|')
            .unwrap();

        let json = serde_json::to_string(&vars).unwrap();
        let parsed: Variables = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.separator(), Some('|'));
        assert_eq!(parsed, vars);
        assert_eq!(parsed.to_string(), "{^^|codecs=PCMA,PCMU}");
    }

    /// The default separator has no key, so a config written before the key
    /// existed serializes back byte-identical.
    #[test]
    fn serde_variables_default_separator_is_absent() {
        let mut flat = Variables::new(VariablesType::Default);
        flat.insert("k", "v");
        assert_eq!(serde_json::to_string(&flat).unwrap(), r#"{"k":"v"}"#);

        let mut scoped = Variables::new(VariablesType::Channel);
        scoped.insert("k", "v");
        assert_eq!(
            serde_json::to_string(&scoped).unwrap(),
            r#"{"scope":"channel","vars":{"k":"v"}}"#
        );
    }

    #[test]
    fn serde_variables_separator_deserializes_from_config() {
        let json = r#"{"scope":"channel","vars":{"codecs":"PCMA,PCMU"},"separator":":"}"#;
        let vars: Variables = serde_json::from_str(json).unwrap();
        assert_eq!(vars.scope(), VariablesType::Channel);
        assert_eq!(vars.separator(), Some(':'));
        assert_eq!(vars.to_string(), "[^^:codecs=PCMA,PCMU]");
    }

    /// The leg split reads a `|` before a `[]` block is parsed, so it can
    /// separate nothing there; in `{}` it is ordinary.
    #[test]
    fn pipe_separator_is_refused_in_channel_scope_only() {
        let mut vars = Variables::new(VariablesType::Channel);
        vars.insert("k", "v");
        assert!(vars
            .clone()
            .with_separator('|')
            .is_err());
        let mut vars = Variables::new(VariablesType::Default);
        vars.insert("k", "v");
        assert!(vars
            .with_separator('|')
            .is_ok());
    }

    /// The builder's two refusals have to hold at the config boundary too, or a
    /// YAML file produces a block the same crate would not build.
    #[test]
    fn serde_variables_unusable_separator_is_refused() {
        let undelimitable = r#"{"scope":"default","vars":{"k":"v"},"separator":"="}"#;
        assert!(serde_json::from_str::<Variables>(undelimitable).is_err());

        let in_a_value =
            r#"{"scope":"default","vars":{"uri":"sip:bob@example.com"},"separator":":"}"#;
        let err = serde_json::from_str::<Variables>(in_a_value)
            .unwrap_err()
            .to_string();
        assert!(
            err.contains("uri"),
            "error does not name the variable: {err}"
        );
    }

    /// Measured: `[p1=it's,p2=don't,p3=x]` reaches the channel as
    /// `p1=its,p2=dont` with no `p2`, at every escaping depth, because the scan
    /// ahead of the peer split pairs quotes across values. The same value in
    /// default scope is ordinary.
    #[test]
    fn a_quote_in_channel_scope_is_refused_at_every_boundary() {
        let err = r"[cid=it\\\\\\\'s]"
            .parse::<Variables>()
            .unwrap_err()
            .to_string();
        assert!(
            err.contains("cid") && err.contains("channel scope"),
            "error does not name the variable and scope: {err}"
        );

        let err = serde_json::from_str::<Variables>(r#"{"scope":"channel","vars":{"cid":"it's"}}"#)
            .unwrap_err()
            .to_string();
        assert!(
            err.contains("cid") && err.contains("channel scope"),
            "error does not name the variable and scope: {err}"
        );

        assert!(r"{cid=it\\\\\\\'s}"
            .parse::<Variables>()
            .is_ok());
        assert!(
            serde_json::from_str::<Variables>(r#"{"scope":"default","vars":{"cid":"it's"}}"#)
                .is_ok()
        );
    }
}