shep_core/

selector.rs

//! Target selection: one parse for every CLI verb and RPC filter
//!
//! Precedence: `all` > `fold:<name>` > `/regex/` > all-digits id > glob >
//! `name:slot` > name.

use core::fmt;

/// A parsed process selector (spec §9: name, id, `all`, `/regex/`, `fold:`)
#[derive(Debug, Clone)]
pub enum ProcessSelector {
    /// Every sheep in the flock
    All,
    /// By numeric id
    Id(u32),
    /// By exact name
    Name(String),
    /// By regex over names (slash-delimited on the CLI)
    Regex(regex::Regex),
    /// Every sheep in a fold
    Fold(String),
    /// One instance of one app, written `name:slot` on the CLI
    Instance {
        /// The app name, which cannot itself contain a colon
        name: String,
        /// The instance slot, counting from 0
        slot: u32,
    },
}

/// Whether `input` carries a glob metacharacter, and so was meant as a
/// pattern rather than as a name.
///
/// Checked after `all`, `fold:`, `/regex/` and the id form, so none of those
/// can be shadowed by a name that happens to contain one of these.
///
/// A name with no metacharacter stays an exact name: `web.1` is the sheep
/// called `web.1`, not a pattern where `.` means "any character". Ordinary
/// punctuation in a name means nothing.
fn is_glob(input: &str) -> bool {
    input.contains(['*', '?', '[', '{'])
}

/// Compiles a glob into a regex.
///
/// `globset`'s pattern is already anchored, so `web-*` matches `web-api`
/// and not `my-web-api`. Strips the `(?-u)` prefix, since `globset`
/// compiles for bytes and `regex::Regex` refuses that for a `String`.
/// Returns [`ProcessSelector::Regex`] rather than its own variant: a new
/// variant on `SelectorSpec` is a protocol change an older daemon could not
/// deserialize.
///
/// # Errors
///
/// - [`SelectorError::BadGlob`]: the pattern is not a valid glob.
/// - [`SelectorError::BadRegex`]: `globset` translated the glob to a regex
///   that the `regex` crate itself rejects.
fn glob_to_regex(input: &str) -> Result<regex::Regex, SelectorError> {
    let glob = globset::Glob::new(input).map_err(|e| SelectorError::BadGlob(e.to_string()))?;
    let source = glob.regex();
    let source = source.strip_prefix("(?-u)").unwrap_or(source);
    regex::Regex::new(source).map_err(|e| SelectorError::BadRegex(e.to_string()))
}

/// `s` as a `u32`, if every byte of it is an ASCII digit.
///
/// The digit check is not redundant beside `parse`: `u32::from_str` accepts
/// a leading `+`, so `"+5"` would otherwise be an id and `"web:+2"` an
/// instance slot. Both of the places this grammar reads a number want the
/// same answer, and `None` means "not a number here", which lets each caller
/// fall through to the form it tries next.
fn parse_u32_digits(s: &str) -> Option<u32> {
    if s.is_empty() || !s.bytes().all(|b| b.is_ascii_digit()) {
        return None;
    }
    s.parse().ok()
}

impl ProcessSelector {
    /// Parses CLI selector syntax
    ///
    /// # Errors
    ///
    /// - [`SelectorError::Empty`]: empty input.
    /// - [`SelectorError::EmptyFold`]: `fold:` with no name.
    /// - [`SelectorError::BadRegex`]: `/re/` body rejected by the regex
    ///   crate (carries its message).
    /// - [`SelectorError::BadGlob`]: a pattern carrying `*`, `?`, `[` or `{`
    ///   was rejected by `globset` (carries its message).
    pub fn parse(input: &str) -> Result<Self, SelectorError> {
        if input.is_empty() {
            return Err(SelectorError::Empty);
        }
        if input == "all" {
            return Ok(Self::All);
        }
        if let Some(fold) = input.strip_prefix("fold:") {
            if fold.is_empty() {
                return Err(SelectorError::EmptyFold);
            }
            return Ok(Self::Fold(fold.to_string()));
        }
        if input.len() >= 2 && input.starts_with('/') && input.ends_with('/') {
            let body = &input[1..input.len() - 1];
            return regex::Regex::new(body)
                .map(Self::Regex)
                .map_err(|e| SelectorError::BadRegex(e.to_string()));
        }
        if let Some(id) = parse_u32_digits(input) {
            return Ok(Self::Id(id));
        }
        if is_glob(input) {
            return glob_to_regex(input).map(Self::Regex);
        }
        // Last, so every earlier form wins. A name cannot contain a colon
        // (`config::normalize` refuses one), so splitting on the last one
        // cannot cut a name in half.
        if let Some((name, slot)) = input.rsplit_once(':')
            && !name.is_empty()
            && let Some(slot) = parse_u32_digits(slot)
        {
            return Ok(Self::Instance {
                name: name.to_string(),
                slot,
            });
        }

        Ok(Self::Name(input.to_string()))
    }

    /// Whether this selector names ONE entry the caller already knew of, by
    /// its name or its id, rather than sweeping whatever matches.
    ///
    /// The distinction a dog turns on: a dog is a process an operator
    /// installed, not a member of the flock `all` means, so a wildcard must
    /// pass it by while `shep restart metrics` still reaches it.
    /// [`Self::Regex`] and [`Self::Fold`] are wildcards even when they
    /// happen to match one entry: the operator did not name it.
    #[must_use]
    pub const fn is_exact(&self) -> bool {
        match self {
            Self::Id(_) | Self::Name(_) | Self::Instance { .. } => true,
            Self::All | Self::Regex(_) | Self::Fold(_) => false,
        }
    }

    /// Tests one sheep against this selector
    #[must_use]
    pub fn matches(&self, name: &str, id: u32, fold: Option<&str>, instance: Option<u32>) -> bool {
        match self {
            Self::All => true,
            Self::Id(want) => *want == id,
            Self::Name(want) => want == name,
            Self::Regex(re) => re.is_match(name),
            Self::Fold(want) => fold == Some(want.as_str()),
            // `None` means the peer daemon predates the slot field, so this
            // row cannot be shown to be the one asked for. Refusing to match
            // is the safe direction: a restart reaches nothing rather than
            // reaching every instance of the name.
            Self::Instance { name: want, slot } => want == name && instance == Some(*slot),
        }
    }
}

/// Error type returned from [`ProcessSelector::parse`]
///
/// `#[non_exhaustive]`: a future selector kind with its own malformed-value
/// class, such as a `status:` filter rejecting an unknown state, needs a new
/// variant rather than stretching [`Self::BadRegex`] to mean something it
/// does not, and shep-core is a published library an out-of-tree matcher
/// should not break for.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SelectorError {
    /// The selector string was empty
    Empty,
    /// `fold:` with no fold name after the colon
    EmptyFold,
    /// The `/regex/` body failed to compile (carries the regex message)
    BadRegex(String),
    /// A glob pattern was rejected by `globset` (carries its message)
    BadGlob(String),
}

impl fmt::Display for SelectorError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty => f.write_str("selector is empty"),
            Self::EmptyFold => f.write_str("fold selector is missing a name"),
            Self::BadRegex(m) => write!(f, "invalid selector regex: {m}"),
            Self::BadGlob(m) => write!(f, "invalid selector glob: {m}"),
        }
    }
}

impl core::error::Error for SelectorError {}

impl std::convert::TryFrom<crate::protocol::SelectorSpec> for ProcessSelector {
    type Error = SelectorError;

    /// Compiles a wire selector into a matchable one
    ///
    /// # Errors
    ///
    /// - [`SelectorError::BadRegex`]: the peer-supplied pattern fails to
    ///   compile or exceeds the 1 MiB compiled-size bound.
    fn try_from(spec: crate::protocol::SelectorSpec) -> Result<Self, Self::Error> {
        use crate::protocol::SelectorSpec;
        Ok(match spec {
            SelectorSpec::All => Self::All,
            SelectorSpec::Id(id) => Self::Id(id),
            SelectorSpec::Name(name) => Self::Name(name),
            SelectorSpec::Fold(fold) => Self::Fold(fold),
            SelectorSpec::Instance { name, slot } => Self::Instance { name, slot },
            SelectorSpec::Regex(src) => Self::Regex(
                // Peer-supplied pattern: bound compiled-program memory.
                regex::RegexBuilder::new(&src)
                    .size_limit(1 << 20)
                    .build()
                    .map_err(|e| SelectorError::BadRegex(e.to_string()))?,
            ),
        })
    }
}

impl From<&ProcessSelector> for crate::protocol::SelectorSpec {
    fn from(sel: &ProcessSelector) -> Self {
        use crate::protocol::SelectorSpec;
        match sel {
            ProcessSelector::All => SelectorSpec::All,
            ProcessSelector::Id(id) => SelectorSpec::Id(*id),
            ProcessSelector::Name(name) => SelectorSpec::Name(name.clone()),
            ProcessSelector::Regex(re) => SelectorSpec::Regex(re.as_str().to_string()),
            ProcessSelector::Fold(fold) => SelectorSpec::Fold(fold.clone()),
            ProcessSelector::Instance { name, slot } => SelectorSpec::Instance {
                name: name.clone(),
                slot: *slot,
            },
        }
    }
}

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

    #[test]
    fn a_name_without_a_metacharacter_is_still_an_exact_name() {
        for plain in ["api-auth", "web.1", "api_v2", "a-b-c"] {
            let parsed = ProcessSelector::parse(plain).unwrap();
            assert!(
                matches!(&parsed, ProcessSelector::Name(name) if name == plain),
                "{plain} carries no glob metacharacter and is a name, got {parsed:?}"
            );
        }
    }

    #[test]
    fn a_glob_matches_by_prefix_and_not_by_substring() {
        let ProcessSelector::Regex(re) = ProcessSelector::parse("api-*").unwrap() else {
            panic!("a pattern with `*` is compiled to a regex");
        };
        assert!(re.is_match("api-auth"));
        assert!(re.is_match("api-create"));
        assert!(!re.is_match("my-api-auth"), "anchored: no substring match");
        assert!(!re.is_match("reactmap"));
    }

    /// Every metacharacter the `is_glob` gate names has to actually work,
    /// or the gate is claiming support it does not have.
    #[test]
    fn each_glob_metacharacter_compiles_and_matches() {
        let cases = [
            ("*api*", "my-api-thing", "web"),
            ("api-?", "api-1", "api-auth"),
            ("api-[ab]*", "api-auth", "api-create"),
            ("{web,api}", "api", "worker"),
        ];
        for (pattern, hit, miss) in cases {
            let ProcessSelector::Regex(re) = ProcessSelector::parse(pattern).unwrap() else {
                panic!("{pattern} must compile to a regex");
            };
            assert!(re.is_match(hit), "{pattern} must match {hit}");
            assert!(!re.is_match(miss), "{pattern} must not match {miss}");
        }
    }

    #[test]
    fn the_earlier_forms_are_not_shadowed_by_the_glob_gate() {
        assert!(matches!(
            ProcessSelector::parse("all").unwrap(),
            ProcessSelector::All
        ));
        let fold = ProcessSelector::parse("fold:back*end").unwrap();
        assert!(
            matches!(&fold, ProcessSelector::Fold(name) if name == "back*end"),
            "a fold name may contain a metacharacter and is still a fold, got {fold:?}"
        );
        let ProcessSelector::Regex(re) = ProcessSelector::parse("/^api-/").unwrap() else {
            panic!("an explicit regex stays a regex");
        };
        assert!(re.is_match("api-auth"));
    }

    /// A glob `globset` refuses is reported as such rather than silently
    /// becoming a name that can never match.
    #[test]
    fn an_unparseable_glob_is_refused() {
        let err = ProcessSelector::parse("api-[").expect_err("an unclosed class is not a glob");
        assert!(
            matches!(err, SelectorError::BadGlob(_)),
            "expected BadGlob, got {err:?}"
        );
        assert!(err.to_string().contains("glob"), "{err}");
    }

    #[test]
    fn parse_rules() {
        assert!(matches!(
            ProcessSelector::parse("all").unwrap(),
            ProcessSelector::All
        ));
        assert!(matches!(
            ProcessSelector::parse("3").unwrap(),
            ProcessSelector::Id(3)
        ));
        assert!(matches!(
            ProcessSelector::parse("web").unwrap(),
            ProcessSelector::Name(n) if n == "web"
        ));
        assert!(matches!(
            ProcessSelector::parse("/^w/").unwrap(),
            ProcessSelector::Regex(_)
        ));
        assert!(matches!(
            ProcessSelector::parse("fold:backend").unwrap(),
            ProcessSelector::Fold(fname) if fname == "backend"
        ));
    }

    #[test]
    fn parse_errors() {
        assert_eq!(
            ProcessSelector::parse("").unwrap_err(),
            SelectorError::Empty
        );
        assert_eq!(
            ProcessSelector::parse("fold:").unwrap_err(),
            SelectorError::EmptyFold
        );
        assert!(matches!(
            ProcessSelector::parse("/((/").unwrap_err(),
            SelectorError::BadRegex(_)
        ));
    }

    #[test]
    fn matching() {
        let by_name = ProcessSelector::parse("web").unwrap();
        assert!(by_name.matches("web", 0, None, None));
        assert!(!by_name.matches("worker", 0, None, None));

        let by_regex = ProcessSelector::parse("/^w/").unwrap();
        assert!(by_regex.matches("worker", 9, None, None));
        assert!(!by_regex.matches("api", 9, None, None));

        let by_fold = ProcessSelector::parse("fold:backend").unwrap();
        assert!(by_fold.matches("anything", 0, Some("backend"), None));
        assert!(!by_fold.matches("anything", 0, None, None));

        assert!(
            ProcessSelector::parse("all")
                .unwrap()
                .matches("x", 42, None, None)
        );
        assert!(
            ProcessSelector::parse("42")
                .unwrap()
                .matches("x", 42, None, None)
        );
    }

    /// Either mistake makes `shep reload /^web/` sweep up a dog, invisible
    /// until a flock happens to run one whose name the pattern matches.
    #[test]
    fn only_a_name_or_an_id_names_one_entry_the_caller_knew_of() {
        assert!(ProcessSelector::Name("bark".into()).is_exact());
        assert!(ProcessSelector::Id(4).is_exact());
        assert!(!ProcessSelector::All.is_exact());
        assert!(!ProcessSelector::Fold("api".into()).is_exact());
        // Built through the real parser: a `Regex` is a wildcard even when
        // its pattern is a literal that can only ever match one name.
        assert!(!ProcessSelector::parse("/^bark$/").unwrap().is_exact());
    }

    #[test]
    fn a_name_that_looks_numeric_is_an_id() {
        // Documented precedence (spec §9): digits select by id. A sheep
        // literally named "42" must be selected by /^42$/ or renamed.
        assert!(matches!(
            ProcessSelector::parse("42").unwrap(),
            ProcessSelector::Id(42)
        ));
    }

    #[test]
    fn a_signed_number_is_a_name_at_both_sites_that_read_one() {
        // `u32::from_str` accepts a leading `+`, so without the digit check
        // in `parse_u32_digits` these would be an id and an instance slot.
        // Both readers share that check, so both stay names.
        assert!(matches!(
            ProcessSelector::parse("+5").unwrap(),
            ProcessSelector::Name(name) if name == "+5"
        ));
        assert!(matches!(
            ProcessSelector::parse("web:+2").unwrap(),
            ProcessSelector::Name(name) if name == "web:+2"
        ));
    }

    #[test]
    fn selector_spec_bridges() {
        use crate::protocol::SelectorSpec;
        let sel: ProcessSelector = SelectorSpec::Regex("^w".to_string()).try_into().unwrap();
        assert!(sel.matches("web", 1, None, None));
        assert_eq!(
            SelectorSpec::from(&sel),
            SelectorSpec::Regex("^w".to_string())
        );
        for spec in [
            SelectorSpec::All,
            SelectorSpec::Id(3),
            SelectorSpec::Name("web".to_string()),
            SelectorSpec::Fold("backend".to_string()),
            SelectorSpec::Instance {
                name: "web".to_string(),
                slot: 2,
            },
        ] {
            let sel: ProcessSelector = spec.clone().try_into().unwrap();
            assert_eq!(SelectorSpec::from(&sel), spec);
        }
    }

    #[test]
    fn selector_spec_bad_regex_is_typed_error() {
        use crate::protocol::SelectorSpec;
        assert!(matches!(
            ProcessSelector::try_from(SelectorSpec::Regex("((".to_string())).unwrap_err(),
            SelectorError::BadRegex(_)
        ));
    }

    #[test]
    fn an_instance_form_parses_and_matches_only_its_slot() {
        let sel = ProcessSelector::parse("web:2").expect("parses");
        assert!(matches!(
            &sel,
            ProcessSelector::Instance { name, slot } if name == "web" && *slot == 2
        ));
        assert!(sel.matches("web", 7, None, Some(2)));
        assert!(!sel.matches("web", 7, None, Some(1)));
        assert!(!sel.matches("api", 7, None, Some(2)));
        assert!(
            !sel.matches("web", 7, None, None),
            "an older daemon's row carries no slot, so it cannot be the one asked for"
        );
    }

    #[test]
    fn an_instance_selector_names_one_entry_so_it_is_exact() {
        // The dog rule: an operator who named it reaches it, a wildcard does not.
        assert!(
            ProcessSelector::parse("metrics:0")
                .expect("parses")
                .is_exact()
        );
    }

    #[test]
    fn the_colon_forms_do_not_shadow_each_other() {
        assert!(matches!(
            ProcessSelector::parse("fold:web").expect("parses"),
            ProcessSelector::Fold(_)
        ));
        assert!(matches!(
            ProcessSelector::parse("web:2").expect("parses"),
            ProcessSelector::Instance { .. }
        ));
        // A trailing segment that is not a number is not a slot. Names cannot
        // hold a colon any more, so this is a name that will simply match nothing.
        assert!(matches!(
            ProcessSelector::parse("web:two").expect("parses"),
            ProcessSelector::Name(_)
        ));
        // A glob is still a glob: the glob test runs first.
        assert!(matches!(
            ProcessSelector::parse("web*:2").expect("parses"),
            ProcessSelector::Regex(_)
        ));
        // An id is still an id.
        assert!(matches!(
            ProcessSelector::parse("11").expect("parses"),
            ProcessSelector::Id(11)
        ));
    }

    #[test]
    fn an_instance_selector_round_trips_through_the_wire_form() {
        let sel = ProcessSelector::parse("web:2").expect("parses");
        let spec = crate::protocol::SelectorSpec::from(&sel);
        assert_eq!(
            spec,
            crate::protocol::SelectorSpec::Instance {
                name: "web".to_string(),
                slot: 2
            }
        );
        let back = ProcessSelector::try_from(spec).expect("converts back");
        assert!(matches!(back, ProcessSelector::Instance { .. }));
    }

    #[test]
    fn selector_spec_oversized_regex_is_rejected() {
        // Peer-supplied pattern: size_limit bounds compiled-program memory.
        // The pattern (a|b|...)^N where N is the number of alternations
        // repeated many times generates a huge compiled regex that exceeds
        // the 1 MiB limit: many alternations * repetition factor.
        use crate::protocol::SelectorSpec;
        let huge = format!("(a{}){{10000}}", "|b".repeat(100_000));
        assert!(ProcessSelector::try_from(SelectorSpec::Regex(huge)).is_err());
    }
}