fbi-proxy 1.9.0 → 1.10.0

package/rs/routes.rs

@@ -0,0 +1,976 @@
+//! Rule-based routing engine for fbi-proxy.
+//!
+//! This module implements a configurable, placeholder-based rule system
+//! that replaces (eventually) the hardcoded `parse_host` logic in
+//! `rs/fbi-proxy.rs`. Routes are described declaratively (e.g. in YAML)
+//! as a `match` pattern + a `target` template + optional `headers`
+//! templates. The engine compiles each rule into a regular expression
+//! and, at request time, picks the first rule whose pattern matches
+//! the incoming host, then expands the templates using the captured
+//! placeholder values.
+//!
+//! # Placeholder syntax
+//!
+//! Placeholders in patterns and templates use brace syntax:
+//!
+//! * `{name}`       — matches one host segment: `[^.]+`
+//! * `{name:int}`   — matches one numeric segment: `\d+`
+//! * `{name:slug}`  — matches `[a-z0-9-]+`
+//! * `{name:multi}` — matches one or more dot-separated segments:
+//!                    `[^.]+(\.[^.]+)*`. Use this for DNS-passthrough
+//!                    patterns like `{upstream:multi}.{domain}` that
+//!                    need to capture e.g. `github.com` as one value.
+//!
+//! A given placeholder name can appear in both the `match` pattern
+//! (where it captures) and in the `target` / `headers` templates
+//! (where it is substituted from the corresponding capture).
+//!
+//! Literal characters in patterns (dots, dashes, etc.) are anchored
+//! by Rust's `regex` crate after escaping; the whole pattern is
+//! implicitly anchored with `^...$`.
+//!
+//! # `{domain}` and multi-dot subdomain semantics
+//!
+//! `{domain}` is **not** special-cased by this engine. It is just a
+//! placeholder name like any other. The default `routes.yaml` uses
+//! `{domain}` by convention to mean "the trailing fbi-proxy domain
+//! (e.g. `fbi.com`)" but the engine treats it the same as `{host}`,
+//! `{port}`, etc.
+//!
+//! This means a pattern like `{prefix}.{host}.{domain}` is *greedy
+//! left-to-right* in the sense that each placeholder matches a single
+//! dot-free segment. For a host like `a.b.c.fbi.com` against
+//! `{prefix}.{host}.{domain}`, no match is produced because `{domain}`
+//! can only consume one segment (`com`), `{host}` consumes `fbi`, and
+//! `{prefix}` would have to consume `a.b.c` — which it can't, because
+//! `{prefix}` is `[^.]+`.
+//!
+//! Callers that want multi-dot domains (e.g. `fbi.example.com`) should
+//! either:
+//!   1. Strip the domain suffix before calling `match_host` (which is
+//!      what `match_host_with_domain` does), or
+//!   2. Encode the multi-dot literal directly in the pattern
+//!      (e.g. `{prefix}.{host}.fbi.example.com`).
+//!
+//! `match_host_with_domain(routes, host, Some("fbi.example.com"))` is
+//! the convenience helper: it strips `.fbi.example.com` from the host
+//! before matching, then re-injects the value as the `{domain}`
+//! capture for template expansion.
+
+use regex::Regex;
+use serde::Deserialize;
+use std::collections::HashMap;
+use std::fmt;
+
+/// Placeholder kind — controls the regex fragment used to match.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PlaceholderKind {
+    /// `{name}` — matches one host segment (no dot): `[^.]+`.
+    Any,
+    /// `{name:int}` — matches `\d+`.
+    Int,
+    /// `{name:slug}` — matches `[a-z0-9-]+`.
+    Slug,
+    /// `{name:multi}` — matches one or more dot-separated segments.
+    /// Use for DNS-passthrough patterns (e.g. `{upstream:multi}.fbi.com`
+    /// capturing `github.com` as one value).
+    Multi,
+}
+
+impl PlaceholderKind {
+    fn regex_fragment(self) -> &'static str {
+        match self {
+            PlaceholderKind::Any => "[^.]+",
+            PlaceholderKind::Int => r"\d+",
+            PlaceholderKind::Slug => "[a-z0-9-]+",
+            PlaceholderKind::Multi => r"[^.]+(?:\.[^.]+)*",
+        }
+    }
+}
+
+/// Special-cased placeholder names that need to match more than a
+/// single dot-free segment. Currently only `{domain}`: it matches
+/// two-or-more dot-separated segments (e.g. `fbi.com`, `fbi.example.com`)
+/// but NOT a single bare segment like `com`. This is important because
+/// it makes the default rule ordering unambiguous: in
+/// `{prefix}.{host}.{domain}`, the trailing `{domain}` greedily eats
+/// the multi-segment suffix instead of collapsing to a single segment
+/// (which would cause `myserver.fbi.com` to be mis-classified as
+/// `prefix=myserver, host=fbi, domain=com`).
+fn special_regex_fragment(name: &str) -> Option<&'static str> {
+    match name {
+        "domain" => Some(r"[a-zA-Z0-9\-]+(?:\.[a-zA-Z0-9\-]+)+"),
+        _ => None,
+    }
+}
+
+/// A single named placeholder captured by a compiled route.
+#[derive(Debug, Clone)]
+pub struct Placeholder {
+    pub name: String,
+    pub kind: PlaceholderKind,
+}
+
+/// User-supplied route configuration (e.g. from `routes.yaml`).
+#[derive(Debug, Clone, Deserialize)]
+pub struct RouteConfig {
+    pub name: String,
+    /// Pattern matched against the Host header (without port).
+    /// E.g. `"{port:int}.{domain}"`.
+    #[serde(rename = "match")]
+    pub r#match: String,
+    /// Target template, e.g. `"127.0.0.1:{port}"`.
+    pub target: String,
+    /// Header templates. The special key `"Host"` (case-insensitive)
+    /// is surfaced separately on `RouteHit::host_header`.
+    #[serde(default)]
+    pub headers: Option<HashMap<String, String>>,
+}
+
+/// Top-level shape of `routes.yaml`.
+#[derive(Debug, Clone, Deserialize)]
+pub struct RoutesFile {
+    #[serde(default = "default_version")]
+    pub version: u32,
+    pub routes: Vec<RouteConfig>,
+}
+
+fn default_version() -> u32 {
+    1
+}
+
+/// Parse a `routes.yaml`-style document.
+pub fn parse_yaml(src: &str) -> Result<RoutesFile, serde_yaml::Error> {
+    serde_yaml::from_str(src)
+}
+
+/// A compiled route — regex + templates — ready to evaluate per request.
+#[derive(Debug, Clone)]
+pub struct CompiledRoute {
+    pub name: String,
+    pub pattern: Regex,
+    pub placeholders: Vec<Placeholder>,
+    pub target_template: String,
+    pub header_templates: HashMap<String, String>,
+}
+
+/// Result of a successful match.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RouteHit {
+    pub route_name: String,
+    /// Expanded `target` template (e.g. `"api:3001"`).
+    pub target: String,
+    /// Expanded `Host` header from the `headers` map, if any.
+    pub host_header: Option<String>,
+    /// Other expanded headers, excluding `Host` (case-insensitive).
+    pub other_headers: HashMap<String, String>,
+}
+
+/// Compile-time error from `compile`.
+#[derive(Debug, Clone)]
+pub enum CompileError {
+    /// A placeholder spec was malformed, e.g. `{na me}` or `{:int}`.
+    InvalidPlaceholder { route: String, placeholder: String, reason: String },
+    /// An unknown placeholder kind, e.g. `{name:foo}`.
+    UnknownKind { route: String, name: String, kind: String },
+    /// The same placeholder name was declared twice in the same pattern.
+    DuplicatePlaceholder { route: String, name: String },
+    /// The generated regex failed to compile (very unlikely — usually
+    /// an indication of weird literal characters that escaped wrong).
+    InvalidRegex { route: String, source: String },
+    /// A `{name}` appeared in the target/header template but was never
+    /// declared in the match pattern.
+    UndeclaredPlaceholder { route: String, name: String, location: String },
+    /// Unbalanced braces in pattern or template.
+    UnbalancedBraces { route: String, location: String },
+}
+
+impl fmt::Display for CompileError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            CompileError::InvalidPlaceholder { route, placeholder, reason } => {
+                write!(f, "route '{}': invalid placeholder '{{{}}}': {}", route, placeholder, reason)
+            }
+            CompileError::UnknownKind { route, name, kind } => {
+                write!(f, "route '{}': unknown placeholder kind ':{}' for '{{{}}}' (expected int|slug|multi or none)", route, kind, name)
+            }
+            CompileError::DuplicatePlaceholder { route, name } => {
+                write!(f, "route '{}': placeholder '{{{}}}' declared twice in match pattern", route, name)
+            }
+            CompileError::InvalidRegex { route, source } => {
+                write!(f, "route '{}': internal regex compile error: {}", route, source)
+            }
+            CompileError::UndeclaredPlaceholder { route, name, location } => {
+                write!(f, "route '{}': placeholder '{{{}}}' used in {} but never declared in match pattern", route, name, location)
+            }
+            CompileError::UnbalancedBraces { route, location } => {
+                write!(f, "route '{}': unbalanced braces in {}", route, location)
+            }
+        }
+    }
+}
+
+impl std::error::Error for CompileError {}
+
+// ---------------------------------------------------------------------------
+// Parsing helpers
+// ---------------------------------------------------------------------------
+
+/// A token of a parsed pattern / template string.
+#[derive(Debug, Clone, PartialEq, Eq)]
+enum Token {
+    Literal(String),
+    Placeholder { name: String, kind: Option<String> },
+}
+
+/// Tokenize a `{name[:kind]}`-style template. Returns the token list
+/// or `Err(UnbalancedBraces)` on malformed input.
+fn tokenize(s: &str, route: &str, location: &str) -> Result<Vec<Token>, CompileError> {
+    let mut out = Vec::new();
+    let mut buf = String::new();
+    let mut chars = s.chars().peekable();
+
+    while let Some(c) = chars.next() {
+        if c == '{' {
+            // flush literal
+            if !buf.is_empty() {
+                out.push(Token::Literal(std::mem::take(&mut buf)));
+            }
+            // collect until '}'
+            let mut spec = String::new();
+            let mut closed = false;
+            while let Some(&nc) = chars.peek() {
+                chars.next();
+                if nc == '}' {
+                    closed = true;
+                    break;
+                }
+                spec.push(nc);
+            }
+            if !closed {
+                return Err(CompileError::UnbalancedBraces {
+                    route: route.to_string(),
+                    location: location.to_string(),
+                });
+            }
+            // parse "name" or "name:kind"
+            let (name, kind) = match spec.split_once(':') {
+                Some((n, k)) => (n.to_string(), Some(k.to_string())),
+                None => (spec.clone(), None),
+            };
+            out.push(Token::Placeholder { name, kind });
+        } else if c == '}' {
+            return Err(CompileError::UnbalancedBraces {
+                route: route.to_string(),
+                location: location.to_string(),
+            });
+        } else {
+            buf.push(c);
+        }
+    }
+    if !buf.is_empty() {
+        out.push(Token::Literal(buf));
+    }
+    Ok(out)
+}
+
+fn parse_kind(route: &str, name: &str, kind: Option<&str>) -> Result<PlaceholderKind, CompileError> {
+    match kind {
+        None | Some("") => Ok(PlaceholderKind::Any),
+        Some("int") => Ok(PlaceholderKind::Int),
+        Some("slug") => Ok(PlaceholderKind::Slug),
+        Some("multi") => Ok(PlaceholderKind::Multi),
+        Some(other) => Err(CompileError::UnknownKind {
+            route: route.to_string(),
+            name: name.to_string(),
+            kind: other.to_string(),
+        }),
+    }
+}
+
+fn validate_name(route: &str, raw_spec: &str, name: &str) -> Result<(), CompileError> {
+    if name.is_empty() {
+        return Err(CompileError::InvalidPlaceholder {
+            route: route.to_string(),
+            placeholder: raw_spec.to_string(),
+            reason: "empty placeholder name".to_string(),
+        });
+    }
+    let first = name.chars().next().unwrap();
+    if !(first.is_ascii_alphabetic() || first == '_') {
+        return Err(CompileError::InvalidPlaceholder {
+            route: route.to_string(),
+            placeholder: raw_spec.to_string(),
+            reason: "name must start with a letter or '_'".to_string(),
+        });
+    }
+    for c in name.chars() {
+        if !(c.is_ascii_alphanumeric() || c == '_') {
+            return Err(CompileError::InvalidPlaceholder {
+                route: route.to_string(),
+                placeholder: raw_spec.to_string(),
+                reason: format!("name contains invalid character '{}'", c),
+            });
+        }
+    }
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Compile
+// ---------------------------------------------------------------------------
+
+/// Compile a list of `RouteConfig`s into ready-to-use `CompiledRoute`s.
+///
+/// Returns the first error encountered.
+pub fn compile(routes: Vec<RouteConfig>) -> Result<Vec<CompiledRoute>, CompileError> {
+    let mut out = Vec::with_capacity(routes.len());
+    for r in routes {
+        out.push(compile_one(r)?);
+    }
+    Ok(out)
+}
+
+fn compile_one(cfg: RouteConfig) -> Result<CompiledRoute, CompileError> {
+    let route_name = cfg.name.clone();
+    let tokens = tokenize(&cfg.r#match, &route_name, "match pattern")?;
+
+    let mut declared: Vec<Placeholder> = Vec::new();
+    let mut regex_src = String::from("^");
+    for tok in &tokens {
+        match tok {
+            Token::Literal(lit) => {
+                regex_src.push_str(&regex::escape(lit));
+            }
+            Token::Placeholder { name, kind } => {
+                let raw_spec = match kind {
+                    Some(k) => format!("{}:{}", name, k),
+                    None => name.clone(),
+                };
+                validate_name(&route_name, &raw_spec, name)?;
+                let parsed_kind = parse_kind(&route_name, name, kind.as_deref())?;
+                if declared.iter().any(|p| p.name == *name) {
+                    return Err(CompileError::DuplicatePlaceholder {
+                        route: route_name,
+                        name: name.clone(),
+                    });
+                }
+                declared.push(Placeholder { name: name.clone(), kind: parsed_kind });
+                regex_src.push('(');
+                regex_src.push_str("?P<");
+                regex_src.push_str(name);
+                regex_src.push('>');
+                // If the user did not specify an explicit kind (e.g.
+                // `{domain}` not `{domain:slug}`) AND the name is one
+                // of the well-known multi-segment names, broaden the
+                // fragment to allow dots. This is what makes
+                // `{port:int}.{domain}` work for `3000.fbi.com`.
+                if kind.is_none() {
+                    if let Some(frag) = special_regex_fragment(name) {
+                        regex_src.push_str(frag);
+                    } else {
+                        regex_src.push_str(parsed_kind.regex_fragment());
+                    }
+                } else {
+                    regex_src.push_str(parsed_kind.regex_fragment());
+                }
+                regex_src.push(')');
+            }
+        }
+    }
+    regex_src.push('$');
+
+    let pattern = Regex::new(&regex_src).map_err(|e| CompileError::InvalidRegex {
+        route: route_name.clone(),
+        source: e.to_string(),
+    })?;
+
+    // Validate target template references known placeholders only.
+    let target_tokens = tokenize(&cfg.target, &route_name, "target template")?;
+    for tok in &target_tokens {
+        if let Token::Placeholder { name, .. } = tok {
+            validate_name(&route_name, name, name)?;
+            if !declared.iter().any(|p| p.name == *name) {
+                return Err(CompileError::UndeclaredPlaceholder {
+                    route: route_name,
+                    name: name.clone(),
+                    location: "target template".to_string(),
+                });
+            }
+        }
+    }
+
+    let mut header_templates: HashMap<String, String> = HashMap::new();
+    if let Some(headers) = cfg.headers {
+        for (k, v) in headers {
+            let header_tokens = tokenize(&v, &route_name, &format!("header '{}'", k))?;
+            for tok in &header_tokens {
+                if let Token::Placeholder { name, .. } = tok {
+                    validate_name(&route_name, name, name)?;
+                    if !declared.iter().any(|p| p.name == *name) {
+                        return Err(CompileError::UndeclaredPlaceholder {
+                            route: route_name.clone(),
+                            name: name.clone(),
+                            location: format!("header '{}'", k),
+                        });
+                    }
+                }
+            }
+            header_templates.insert(k, v);
+        }
+    }
+
+    Ok(CompiledRoute {
+        name: route_name,
+        pattern,
+        placeholders: declared,
+        target_template: cfg.target,
+        header_templates,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Match
+// ---------------------------------------------------------------------------
+
+/// Strip a trailing `:port` from a host string. Used for normalization
+/// before matching.
+fn strip_port(host: &str) -> &str {
+    match host.rfind(':') {
+        Some(i) => &host[..i],
+        None => host,
+    }
+}
+
+/// Strip trailing slash if present (some clients include one).
+fn strip_trailing_slash(host: &str) -> &str {
+    host.strip_suffix('/').unwrap_or(host)
+}
+
+fn normalize(host: &str) -> String {
+    // Host header is case-insensitive per RFC 7230 §5.4.
+    strip_trailing_slash(strip_port(host)).to_ascii_lowercase()
+}
+
+/// Expand a template string using captured placeholders.
+fn expand(template: &str, captures: &HashMap<String, String>) -> String {
+    // We can re-use the tokenizer here, but since we already validated
+    // at compile-time, this is purely substitution: scan for {name[:kind]}
+    // and replace.
+    let mut out = String::with_capacity(template.len());
+    let mut chars = template.chars().peekable();
+    while let Some(c) = chars.next() {
+        if c == '{' {
+            let mut spec = String::new();
+            while let Some(&nc) = chars.peek() {
+                chars.next();
+                if nc == '}' {
+                    break;
+                }
+                spec.push(nc);
+            }
+            // strip optional :kind
+            let name = match spec.split_once(':') {
+                Some((n, _)) => n.to_string(),
+                None => spec,
+            };
+            if let Some(v) = captures.get(&name) {
+                out.push_str(v);
+            }
+            // if not present, drop silently — compile() has already
+            // validated that all placeholders are declared.
+        } else {
+            out.push(c);
+        }
+    }
+    out
+}
+
+/// Try to match a host against the compiled routes. Returns the first
+/// match (top-to-bottom order in the config).
+pub fn match_host(routes: &[CompiledRoute], host: &str) -> Option<RouteHit> {
+    match_host_with_domain(routes, host, None)
+}
+
+/// Like `match_host`, but if `default_domain` is `Some("fbi.com")`,
+/// the host must end with `.fbi.com` (or be exactly `fbi.com`),
+/// otherwise no match is produced. The full host (including the
+/// domain suffix) is then matched against each compiled route's
+/// pattern, so `{domain}` in the pattern naturally captures the
+/// multi-dot suffix.
+///
+/// If `default_domain` is `None`, the host is matched as-is.
+pub fn match_host_with_domain(
+    routes: &[CompiledRoute],
+    host: &str,
+    default_domain: Option<&str>,
+) -> Option<RouteHit> {
+    let host = normalize(host);
+
+    if let Some(domain) = default_domain {
+        if !domain.is_empty() {
+            let domain_lc = domain.to_ascii_lowercase();
+            if host != domain_lc && !host.ends_with(&format!(".{}", domain_lc)) {
+                return None;
+            }
+        }
+    }
+
+    for route in routes {
+        if let Some(caps) = route.pattern.captures(&host) {
+            let mut values: HashMap<String, String> = HashMap::new();
+            for p in &route.placeholders {
+                if let Some(m) = caps.name(&p.name) {
+                    values.insert(p.name.clone(), m.as_str().to_string());
+                }
+            }
+
+            let target = expand(&route.target_template, &values);
+
+            let mut host_header: Option<String> = None;
+            let mut other_headers: HashMap<String, String> = HashMap::new();
+            for (k, tmpl) in &route.header_templates {
+                let v = expand(tmpl, &values);
+                if k.eq_ignore_ascii_case("host") {
+                    host_header = Some(v);
+                } else {
+                    other_headers.insert(k.clone(), v);
+                }
+            }
+
+            return Some(RouteHit {
+                route_name: route.name.clone(),
+                target,
+                host_header,
+                other_headers,
+            });
+        }
+    }
+    None
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn default_routes() -> Vec<CompiledRoute> {
+        let configs = vec![
+            RouteConfig {
+                name: "port-as-host".into(),
+                r#match: "{port:int}.{domain}".into(),
+                target: "127.0.0.1:{port}".into(),
+                headers: None,
+            },
+            RouteConfig {
+                name: "host-double-dash-port".into(),
+                r#match: "{host}--{port:int}.{domain}".into(),
+                target: "{host}:{port}".into(),
+                headers: Some({
+                    let mut h = HashMap::new();
+                    h.insert("Host".into(), "{host}".into());
+                    h
+                }),
+            },
+            RouteConfig {
+                name: "subdomain-hoisting".into(),
+                r#match: "{prefix}.{host}.{domain}".into(),
+                target: "{host}:80".into(),
+                headers: Some({
+                    let mut h = HashMap::new();
+                    h.insert("Host".into(), "{prefix}".into());
+                    h
+                }),
+            },
+            RouteConfig {
+                name: "direct-forward".into(),
+                r#match: "{host}.{domain}".into(),
+                target: "{host}:80".into(),
+                headers: Some({
+                    let mut h = HashMap::new();
+                    h.insert("Host".into(), "{host}".into());
+                    h
+                }),
+            },
+        ];
+        compile(configs).expect("compile default routes")
+    }
+
+    /// All default-rule tests use the `fbi.com` domain filter, which
+    /// is the way these rules are intended to be used (domain stripping
+    /// is handled by the filter; the rules then route the remaining
+    /// prefix).
+    fn m(routes: &[CompiledRoute], host: &str) -> Option<RouteHit> {
+        match_host_with_domain(routes, host, Some("fbi.com"))
+    }
+
+    #[test]
+    fn empty_routes_no_match() {
+        let hit = match_host(&[], "anything.fbi.com");
+        assert!(hit.is_none());
+    }
+
+    #[test]
+    fn port_as_host_matches() {
+        let routes = default_routes();
+        let hit = m(&routes, "3000.fbi.com").expect("should match");
+        assert_eq!(hit.route_name, "port-as-host");
+        assert_eq!(hit.target, "127.0.0.1:3000");
+        assert_eq!(hit.host_header, None);
+    }
+
+    #[test]
+    fn host_double_dash_port_matches() {
+        let routes = default_routes();
+        let hit = m(&routes, "api--3001.fbi.com").expect("should match");
+        assert_eq!(hit.route_name, "host-double-dash-port");
+        assert_eq!(hit.target, "api:3001");
+        assert_eq!(hit.host_header.as_deref(), Some("api"));
+    }
+
+    #[test]
+    fn subdomain_hoisting_matches() {
+        let routes = default_routes();
+        let hit = m(&routes, "admin.app.fbi.com").expect("should match");
+        assert_eq!(hit.route_name, "subdomain-hoisting");
+        assert_eq!(hit.target, "app:80");
+        assert_eq!(hit.host_header.as_deref(), Some("admin"));
+    }
+
+    #[test]
+    fn direct_forward_matches() {
+        let routes = default_routes();
+        let hit = m(&routes, "myserver.fbi.com").expect("should match");
+        assert_eq!(hit.route_name, "direct-forward");
+        assert_eq!(hit.target, "myserver:80");
+        assert_eq!(hit.host_header.as_deref(), Some("myserver"));
+    }
+
+    #[test]
+    fn port_in_host_is_stripped_before_match() {
+        let routes = default_routes();
+        let hit = m(&routes, "myserver.fbi.com:8080").expect("should match");
+        assert_eq!(hit.route_name, "direct-forward");
+        assert_eq!(hit.target, "myserver:80");
+    }
+
+    #[test]
+    fn trailing_slash_stripped() {
+        let routes = default_routes();
+        let hit = m(&routes, "3000.fbi.com/").expect("should match");
+        assert_eq!(hit.route_name, "port-as-host");
+    }
+
+    #[test]
+    fn host_header_is_case_insensitive() {
+        let routes = default_routes();
+        let hit = m(&routes, "API--3001.FBI.COM").expect("should match");
+        assert_eq!(hit.route_name, "host-double-dash-port");
+        assert_eq!(hit.target, "api:3001");
+    }
+
+    #[test]
+    fn multi_dot_subdomain_assigns_domain_greedily() {
+        // For `a.b.c.fbi.com` against `{prefix}.{host}.{domain}`, the
+        // regex anchors left-to-right: {prefix} and {host} each
+        // capture one dot-free segment, and {domain} (which has the
+        // special multi-dot fragment) captures the rest.
+        //
+        // So the match is: prefix=a, host=b, domain=c.fbi.com.
+        //
+        // This may or may not be what the user intends. Document this
+        // ambiguity: if the user wants `prefix=a.b.c, host=fbi,
+        // domain=com`, they need a different pattern (with explicit
+        // literals for the trailing domain).
+        let routes = default_routes();
+        let hit = match_host(&routes, "a.b.c.fbi.com").expect("should match");
+        assert_eq!(hit.route_name, "subdomain-hoisting");
+        // host=b, target={host}:80 = b:80
+        assert_eq!(hit.target, "b:80");
+        // Host header = {prefix} = "a"
+        assert_eq!(hit.host_header.as_deref(), Some("a"));
+    }
+
+    #[test]
+    fn multi_dot_subdomain_with_domain_filter_is_unambiguous() {
+        // When the caller passes the default-domain (`fbi.com`), the
+        // regex still matches the full host but {domain} is now
+        // constrained to exactly the trailing "fbi.com" suffix via
+        // the domain filter. Actually, the filter only validates the
+        // suffix — the regex itself is still greedy. But for the
+        // typical "this is my fbi-proxy domain" usage, the host shape
+        // is single-prefix.subdomain.{domain}, which works as
+        // expected.
+        let routes = default_routes();
+        // admin.app.fbi.com -> subdomain-hoisting (prefix=admin, host=app, domain=fbi.com)
+        let hit = match_host_with_domain(&routes, "admin.app.fbi.com", Some("fbi.com"))
+            .expect("should match");
+        assert_eq!(hit.route_name, "subdomain-hoisting");
+        assert_eq!(hit.target, "app:80");
+        assert_eq!(hit.host_header.as_deref(), Some("admin"));
+    }
+
+    #[test]
+    fn first_match_wins() {
+        let routes = compile(vec![
+            RouteConfig {
+                name: "first".into(),
+                r#match: "{x}.{y}".into(),
+                target: "first-target".into(),
+                headers: None,
+            },
+            RouteConfig {
+                name: "second".into(),
+                r#match: "{x}.{y}".into(),
+                target: "second-target".into(),
+                headers: None,
+            },
+        ])
+        .unwrap();
+        let hit = match_host(&routes, "a.b").expect("should match");
+        assert_eq!(hit.route_name, "first");
+        assert_eq!(hit.target, "first-target");
+    }
+
+    #[test]
+    fn unknown_placeholder_kind_errors() {
+        let err = compile(vec![RouteConfig {
+            name: "bad".into(),
+            r#match: "{port:zzz}.com".into(),
+            target: "x".into(),
+            headers: None,
+        }])
+        .unwrap_err();
+        match err {
+            CompileError::UnknownKind { kind, .. } => assert_eq!(kind, "zzz"),
+            e => panic!("expected UnknownKind, got {:?}", e),
+        }
+    }
+
+    #[test]
+    fn unbalanced_braces_in_pattern_errors() {
+        let err = compile(vec![RouteConfig {
+            name: "bad".into(),
+            r#match: "{port".into(),
+            target: "x".into(),
+            headers: None,
+        }])
+        .unwrap_err();
+        match err {
+            CompileError::UnbalancedBraces { location, .. } => {
+                assert!(location.contains("match"))
+            }
+            e => panic!("expected UnbalancedBraces, got {:?}", e),
+        }
+    }
+
+    #[test]
+    fn duplicate_placeholder_errors() {
+        let err = compile(vec![RouteConfig {
+            name: "bad".into(),
+            r#match: "{x}.{x}".into(),
+            target: "y".into(),
+            headers: None,
+        }])
+        .unwrap_err();
+        match err {
+            CompileError::DuplicatePlaceholder { name, .. } => assert_eq!(name, "x"),
+            e => panic!("expected DuplicatePlaceholder, got {:?}", e),
+        }
+    }
+
+    #[test]
+    fn undeclared_placeholder_in_target_errors() {
+        let err = compile(vec![RouteConfig {
+            name: "bad".into(),
+            r#match: "{x}.{y}".into(),
+            target: "{z}".into(),
+            headers: None,
+        }])
+        .unwrap_err();
+        match err {
+            CompileError::UndeclaredPlaceholder { name, location, .. } => {
+                assert_eq!(name, "z");
+                assert!(location.contains("target"));
+            }
+            e => panic!("expected UndeclaredPlaceholder, got {:?}", e),
+        }
+    }
+
+    #[test]
+    fn invalid_placeholder_name_errors() {
+        let err = compile(vec![RouteConfig {
+            name: "bad".into(),
+            r#match: "{1foo}".into(),
+            target: "x".into(),
+            headers: None,
+        }])
+        .unwrap_err();
+        match err {
+            CompileError::InvalidPlaceholder { .. } => {}
+            e => panic!("expected InvalidPlaceholder, got {:?}", e),
+        }
+    }
+
+    #[test]
+    fn int_kind_rejects_non_numeric() {
+        let routes = default_routes();
+        // "abc.fbi.com" should NOT match port-as-host (because abc isn't \d+),
+        // but should fall through to direct-forward.
+        let hit = m(&routes, "abc.fbi.com").expect("should match");
+        assert_eq!(hit.route_name, "direct-forward");
+        assert_eq!(hit.target, "abc:80");
+    }
+
+    #[test]
+    fn match_host_with_domain_filter_accepts_matching() {
+        let routes = default_routes();
+        let hit = match_host_with_domain(&routes, "3000.fbi.com", Some("fbi.com"))
+            .expect("should match");
+        assert_eq!(hit.route_name, "port-as-host");
+        assert_eq!(hit.target, "127.0.0.1:3000");
+    }
+
+    #[test]
+    fn match_host_with_domain_filter_rejects_non_matching() {
+        let routes = default_routes();
+        let hit = match_host_with_domain(&routes, "evil.example.com", Some("fbi.com"));
+        assert!(hit.is_none());
+    }
+
+    #[test]
+    fn match_host_with_multi_dot_domain() {
+        // The default-domain filter (`fbi.example.com`) only validates
+        // the suffix. The pattern itself still matches the full host,
+        // and {domain} naturally captures multi-segment trailing parts.
+        let routes = compile(vec![RouteConfig {
+            name: "direct".into(),
+            r#match: "{host}.{domain}".into(),
+            target: "{host}:80".into(),
+            headers: None,
+        }])
+        .unwrap();
+        let hit =
+            match_host_with_domain(&routes, "myserver.fbi.example.com", Some("fbi.example.com"))
+                .expect("should match");
+        assert_eq!(hit.target, "myserver:80");
+    }
+
+    #[test]
+    fn match_host_with_multi_dot_domain_rejects_wrong_suffix() {
+        let routes = compile(vec![RouteConfig {
+            name: "direct".into(),
+            r#match: "{host}.{domain}".into(),
+            target: "{host}:80".into(),
+            headers: None,
+        }])
+        .unwrap();
+        let hit = match_host_with_domain(&routes, "myserver.other.com", Some("fbi.example.com"));
+        assert!(hit.is_none());
+    }
+
+    #[test]
+    fn multi_kind_captures_multi_dot_segments() {
+        let routes = compile(vec![RouteConfig {
+            name: "dns-passthrough".into(),
+            r#match: "{upstream:multi}.fbi.com".into(),
+            target: "{upstream}:80".into(),
+            headers: None,
+        }])
+        .unwrap();
+
+        let hit = match_host(&routes, "github.com.fbi.com").unwrap();
+        assert_eq!(hit.target, "github.com:80");
+
+        let hit = match_host(&routes, "api.example.org.fbi.com").unwrap();
+        assert_eq!(hit.target, "api.example.org:80");
+
+        // Single segment still matches (one-or-more).
+        let hit = match_host(&routes, "single.fbi.com").unwrap();
+        assert_eq!(hit.target, "single:80");
+    }
+
+    #[test]
+    fn multi_kind_with_host_header_rewrite() {
+        let routes = compile(vec![RouteConfig {
+            name: "dns-with-host".into(),
+            r#match: "{upstream:multi}.fbi.com".into(),
+            target: "{upstream}:443".into(),
+            headers: Some(HashMap::from([("Host".into(), "{upstream}".into())])),
+        }])
+        .unwrap();
+        let hit = match_host(&routes, "api.example.com.fbi.com").unwrap();
+        assert_eq!(hit.target, "api.example.com:443");
+        assert_eq!(hit.host_header.as_deref(), Some("api.example.com"));
+    }
+
+    #[test]
+    fn multi_kind_with_routes_yaml() {
+        let yaml = r#"
+routes:
+  - name: dns-passthrough
+    match: "{upstream:multi}.{domain}"
+    target: "{upstream}:80"
+"#;
+        let parsed = parse_yaml(yaml).unwrap();
+        let routes = compile(parsed.routes).unwrap();
+        let hit = match_host(&routes, "github.com.fbi.com").unwrap();
+        assert_eq!(hit.target, "github.com:80");
+    }
+
+    #[test]
+    fn slug_kind_accepts_lowercase_and_dashes() {
+        let routes = compile(vec![RouteConfig {
+            name: "slugged".into(),
+            r#match: "{name:slug}.example".into(),
+            target: "{name}".into(),
+            headers: None,
+        }])
+        .unwrap();
+        assert!(match_host(&routes, "my-service.example").is_some());
+        // Uppercase normalized to lowercase by `normalize`, so it matches.
+        assert!(match_host(&routes, "MY-SERVICE.example").is_some());
+        // Underscores not allowed in slug.
+        assert!(match_host(&routes, "my_service.example").is_none());
+    }
+
+    #[test]
+    fn parse_yaml_default_routes() {
+        let yaml = r#"
+version: 1
+routes:
+  - name: port-as-host
+    match: "{port:int}.{domain}"
+    target: "127.0.0.1:{port}"
+  - name: direct-forward
+    match: "{host}.{domain}"
+    target: "{host}:80"
+    headers:
+      Host: "{host}"
+"#;
+        let parsed = parse_yaml(yaml).expect("yaml should parse");
+        assert_eq!(parsed.version, 1);
+        assert_eq!(parsed.routes.len(), 2);
+        assert_eq!(parsed.routes[0].name, "port-as-host");
+        assert_eq!(parsed.routes[0].r#match, "{port:int}.{domain}");
+        assert_eq!(parsed.routes[1].headers.as_ref().unwrap()["Host"], "{host}");
+
+        let compiled = compile(parsed.routes).unwrap();
+        let hit = match_host(&compiled, "3000.fbi.com").unwrap();
+        assert_eq!(hit.target, "127.0.0.1:3000");
+    }
+
+    #[test]
+    fn expand_passes_through_unknown_placeholders_silently() {
+        // expand() is internal but exercised here as a sanity check:
+        // a template referencing an unknown name returns the template
+        // minus the placeholder. (compile() rejects this, so users
+        // can't hit it; this just guards against panics in expand.)
+        let mut caps = HashMap::new();
+        caps.insert("a".to_string(), "X".to_string());
+        assert_eq!(expand("{a}-{b}", &caps), "X-");
+    }
+}