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.
This article is based on the repository’s integration tests and public API surface. The code shows that Vetis is designed to evaluate match conditions against live HTTP requests and responses, and it does so in a way that is both programmable and testable.
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 integration tests in the repository validate this through real HTTP calls against a running server. They start a TLS-enabled local endpoint, issue requests using a deboa client, and verify response codes, host configuration, and server behavior. This is a strong signal that the matcher layer is an operational component, not just a theoretical abstraction.
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, }; 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()?; 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()?; 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()?; 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()?; 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() .build()?; let config = vetis_matchers::request::VersionMatcherConfig::builder() .build()?; 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()?; 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(()) } 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()?; 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()?; 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()?; 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.
Why the integration tests matter
The repository’s integration tests validate the API in a realistic server environment. They do not only assert that a matcher config compiles; they run a real server and send real HTTPS requests.
One test loads a YAML server configuration from disk, starts the Vetis server, makes a request to localhost with a trusted certificate, and expects an HTTP 200 status. Another test verifies a not-found condition by hitting a missing resource and checking for HTTP 404.
These tests validate important operational guarantees:
- YAML-backed configuration can be loaded and used
- TLS is set up correctly
- host configuration works
- routing logic recognizes both success and not-found states
- the overall matcher system integrates correctly with the server runtime
This gives the library a stronger story than a unit-test-only implementation. It shows that the matcher API is not an isolated type system; it is part of a running request pipeline.
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.
The integration tests show that the API is not only expressive but also dependable under real server conditions. For Rust engineers building gateway logic, policy enforcement, or request-driven hooks, Vetis offers a compact and powerful way to express routing and filtering rules in a type-safe, composable form.
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.
