DEV Community

Rogério Araújo
Rogério Araújo

Posted on Edited on Fully Autonomous

Vetis Matcher API: Building Precise HTTP Routing Rules in Rust

Modern HTTP infrastructure often needs more than a simple path check or a single host gate. In many systems, routing decisions depend on a combination of request method, query values, headers, protocol version, response codes, and even custom business rules. Vetis Matcher API addresses exactly that problem: it provides a fluent, declarative model for matching HTTP traffic before a hook or handler is invoked.

The role of the matcher layer

At a high level, Vetis separates server configuration from matching logic. A request can be evaluated against a matcher configuration, and only if it matches does the hook or server logic proceed. The same is true for response matching, where choices can be made based on status code and headers.

The library structure

The crate exposes a narrow but expressive public surface:

  • request matchers
  • response matchers
  • grouped matchers
  • CEL-based expression matchers

The root module exports the core matcher families:

pub mod expr;
pub mod request;
pub mod response;

pub use grouped::{
    GroupedMatcher, MatcherConfig as GroupedMatcherConfig,
    MatcherConfigBuilder as GroupedMatcherConfigBuilder,
};
Enter fullscreen mode Exit fullscreen mode

This design is intentionally compositional. Request matchers are independent building blocks with their own configuration and evaluation logic, and they can be combined into stronger conditions.

Request matchers

The request-side matchers cover the most common HTTP decision points.

Path matching

The path matcher allows multiple paths to be checked with wildcard semantics. Internally, the matcher compiles a CEL expression based on the configured list of path patterns and evaluates it against the request context.

let config = vetis_matchers::request::PathMatcherConfig::builder()
    .add_path("/api*")
    .add_path("/healthz")
    .build()?;
Enter fullscreen mode Exit fullscreen mode

This is useful for routing all API traffic to a specific hook while keeping health checks separate.

Header matching

Header evaluation compares a field to a value, allowing logic such as:

  • accept JSON only
  • require a specific API key header
  • block unknown tenant requests
let config = vetis_matchers::request::HeaderMatcherConfig::builder()
    .field("x-api-key")
    .value("demo-key")
    .build()?;
Enter fullscreen mode Exit fullscreen mode

The implementation builds a CEL expression using the header field and its expected value. The actual match is resolved against the request context.

Method matching

HTTP method routing is a core concern for APIs. Vetis supports matcher configuration for verbs such as GET, POST, PUT, DELETE, and others.

let config = vetis_matchers::request::MethodMatcherConfig::builder()
    .verbs("GET")
    .build()?;
Enter fullscreen mode Exit fullscreen mode

The library stores allowed values in a list and compiles them into a matcher.

Query matching

Query matchers evaluate parameters against expected values:

let config = vetis_matchers::request::QueryMatcherConfig::builder()
    .param("tenant")
    .value("acme")
    .build()?;
Enter fullscreen mode Exit fullscreen mode

This is especially useful for request classification based on query states, feature flags, or tenant-specific routes.

Scheme and version

The library also includes scheme and protocol version matchers, so a configuration can distinguish between HTTP and HTTPS or limit routing to HTTP/1.1 or HTTP/2:

let config = vetis_matchers::request::SchemeMatcherConfig::builder()
    .add_proto("https")
    .build()?;

let config = vetis_matchers::request::VersionMatcherConfig::builder()
    .add_spec("HTTP/1.1")
    .build()?;
Enter fullscreen mode Exit fullscreen mode

These matchers are not just convenience wrappers. In real deployments, they help enforce protocol choices and separate client compatibility rules from business logic.

Expression-based matching with CEL

The most powerful part of the API is the CEL expression matcher. The repository registers custom function libraries for request and response evaluation, providing a domain-specific language for comparing values.

The request extension library defines macros such as:

  • client_ip(...)
  • version(...)
  • method(...)
  • header(...)
  • scheme(...)
  • host(...)
  • path(...)
  • query(...)

The response extension library defines:

  • header(...)
  • status(...)

This makes the matcher system expressive without embedding ad hoc logic into a routing layer. For example, a rule can be written like this:

let config = vetis_matchers::request::ExpressionMatcherConfig::builder()
    .expression("method('GET') && path('/api/*') && header('x-tenant', 'acme')")
    .build()?;
Enter fullscreen mode Exit fullscreen mode

These macros compile into CEL calls and execute against a structured request context. The use of CEL matters because it gives the project a robust rule language while preserving a strong type model and runtime safety.

The implementation is built around environment registration and compiled programs. Each matcher stores a compiled CEL program and evaluates it against a context:

fn compile(&mut self, engine: Arc<Env>) -> VetisResult<()> {
    self.program = Some(
        engine
            .compile(&self.config.expression)
            .map_err(|e| VetisError::matcher(e.to_compact_string()))?,
    );
    Ok(())
}
Enter fullscreen mode Exit fullscreen mode

This approach avoids repeated parsing and makes runtime evaluation efficient.

Response matchers

Response matching is just as important as request matching. A hook may need to trigger only when a service responds with a particular status category, such as 2xx, 4xx, or 5xx. The response status matcher supports this pattern directly.

let config = vetis_matchers::response::StatusMatcherConfig::builder()
    .add_code("2xx")
    .add_code("404")
    .build()?;
Enter fullscreen mode Exit fullscreen mode

The implementation compares the status string to the configured values and supports wildcard ranges like 2xx, 3xx, 4xx, and 5xx. That is a useful feature for incident handling, fallback logic, and gateway rules.

The response header matcher works similarly:

let config = vetis_matchers::response::HeaderMatcherConfig::builder()
    .field("content-type")
    .value("application/json")
    .build()?;
Enter fullscreen mode Exit fullscreen mode

This makes the matcher layer suitable for both inbound request classification and outbound response classification.

Grouped matchers

The grouped matcher offers a way to compose multiple underlying matchers into a single logical rule. This is useful when a request must satisfy several conditions simultaneously.

The design exposes a builder that accepts matcher configs:

let grouped = vetis_matchers::GroupedMatcherConfig::builder()
    .add_matcher(request::MethodMatcherConfig::builder().verbs("POST").build()?)
    .add_matcher(request::HeaderMatcherConfig::builder()
        .field("content-type")
        .value("application/json")
        .build()?)
    .build()?;
Enter fullscreen mode Exit fullscreen mode

The grouped matcher is conceptually a higher-order matcher: it aggregates multiple matchers and evaluates them inside a CEL context. In other words, it gives developers a natural way to express a conjunction of conditions without manually flattening them into a single expression.

A practical design philosophy

The Vetis Matcher API is shaped by a clear design principle: matchers should be declarative, composable, and close to the HTTP semantics they represent.

That is visible in the public API:

  • method, header, path, query, and scheme matchers map directly to real HTTP concepts
  • CEL extends the model with custom logic for advanced policy evaluation
  • grouped matchers allow composition
  • the configuration builders follow a fluent pattern that reads naturally in Rust
  • serde support allows these matchers to be serialized and loaded from configuration files

This combination makes the library suitable for API gateways, web hooks, routing policies, and service meshes where traffic shaping logic must be both flexible and strongly testable.

Conclusion

Vetis Matcher API is a good example of practical, production-minded Rust design. It emphasizes the core HTTP dimensions that matter most in real systems: method, headers, query, path, protocol, and status, while also opening the door to richer inspection through CEL-based expressions.

If you are designing a service that needs granular request evaluation, you can use Vetis matchers either as direct runtime checks or as configuration-driven rules, and the project’s test suite already points to a pattern that is both operationally sound and easy to extend.

Top comments (0)