Skip to main content

laser_wire/filter/
expr.rs

1use crate::codes::FILTER_OP_VERSION;
2use crate::error::InvalidError;
3use crate::filter::coerce::{ExactDecimal, TimestampFormat};
4use crate::filter::path::FieldPath;
5use crate::filter::text::{MAX_REGEX_PREDICATES, TextMatch, TextPredicate};
6use crate::limits::{
7    MAX_FILTER_BYTES, MAX_FILTER_DEPTH, MAX_FILTER_LIST_ITEMS, MAX_FILTER_NODES,
8    MAX_FILTER_PATH_BYTES, MAX_FILTER_STRING_BYTES,
9};
10use crate::query::{CmpOp, Predicate};
11use crate::schema::{Digest32, TypedValue};
12use crate::validate::Validate;
13use serde::{Deserialize, Serialize};
14use sha2::{Digest as _, Sha256};
15
16/// Version of the evaluation rules a filter was written against. Part of the
17/// digest, so a rule change can never silently reinterpret a saved revision.
18pub const FILTER_EVALUATOR_VERSION: u32 = 1;
19
20const DIGEST_DOMAIN: &[u8] = b"agdx.consumer-filter.v1\0";
21
22/// A declarative predicate over one record: payload fields, typed user
23/// headers, presence tests, and boolean composition. It never runs user code.
24///
25/// Comparison truth is three-valued. A missing field or a type mismatch is
26/// unknown, `not` keeps unknown, and an unknown root selects nothing. A decode
27/// fault is separate from truth and follows the filter's [`FaultPolicy`].
28#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
29#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
30#[serde(rename_all = "snake_case")]
31pub enum FilterExpr {
32    All(Vec<FilterExpr>),
33    Any(Vec<FilterExpr>),
34    Not(Box<FilterExpr>),
35    /// A payload comparison. The field is a [`FieldPath`] text form.
36    Pred(Predicate),
37    /// A payload comparison after an explicit value coercion.
38    PredAs(CoercedPredicate),
39    /// The payload path exists. An explicit `null` value is present.
40    Present(FieldPath),
41    /// The payload path does not exist.
42    Absent(FieldPath),
43    /// A typed user-header comparison. The key is matched exactly.
44    Header(HeaderPredicate),
45    /// A text match on a payload field: equals, prefix, suffix, contains,
46    /// glob, or regex, optionally case-insensitive.
47    Text(TextPredicate),
48    /// A text match on one user header, keyed exactly.
49    HeaderText(TextPredicate),
50}
51
52/// A payload comparison whose field and literal are both coerced before the
53/// compare, so `"2026-09-21T18:04:12Z"` orders as an instant and `"12.50"` as a
54/// number. The coercion is part of the expression and its digest.
55#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
56#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
57pub struct CoercedPredicate {
58    pub pred: Predicate,
59    pub coerce: Coerce,
60}
61
62/// An explicit value coercion. A value that does not parse under it compares
63/// as unknown.
64#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
65#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
66#[serde(tag = "kind", rename_all = "snake_case")]
67pub enum Coerce {
68    /// Compare as an instant in microseconds.
69    Timestamp { format: TimestampFormat },
70    /// Compare as an exact decimal. Accepts numbers and decimal strings.
71    Number,
72}
73
74/// A comparison against one user header, keyed exactly (`agdx.ct` is one key).
75#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
76#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
77pub struct HeaderPredicate {
78    pub key: String,
79    pub op: CmpOp,
80    pub value: TypedValue,
81}
82
83/// How the record payload is decoded before payload predicates run. Chosen
84/// explicitly by the filter: a content-type header never overrides it. A
85/// record whose `agdx.ct` header names another codec is never decoded, it
86/// follows the filter's `foreign_policy` instead.
87#[derive(
88    Clone,
89    Copy,
90    Debug,
91    PartialEq,
92    Eq,
93    Serialize,
94    Deserialize,
95    strum::Display,
96    strum::EnumString,
97    strum::VariantArray,
98)]
99#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
100#[serde(rename_all = "snake_case")]
101#[strum(serialize_all = "snake_case")]
102pub enum FilterCodec {
103    /// Decode the payload as JSON.
104    Json,
105    /// Decode one CBOR data item.
106    Cbor,
107    /// Decode a raw Avro datum under its registered writer schema.
108    Avro,
109    /// Decode a Protobuf message under its registered descriptor.
110    Protobuf,
111    /// Never decode the payload. Only header predicates are allowed, so the
112    /// payload may be in any format.
113    HeadersOnly,
114    /// A codec this build does not know, for example one a newer catalog
115    /// saved. It decodes so that listings stay readable, but it never
116    /// validates or compiles.
117    #[serde(other)]
118    Unknown,
119}
120
121/// What happens to a record the filter cannot judge on its own terms.
122///
123/// `foreign_policy` covers a record in another format: its `agdx.ct` header
124/// names another codec, or its writer schema is missing, not listed by the
125/// filter, or of another schema family. `mismatch_policy` covers a record
126/// where a predicate's value exists but has a type the predicate cannot
127/// compare, so the filter could not decide. A mixed log keeps both at
128/// `reject`. A consumer that wants to see edge cases sets `pass`.
129#[derive(
130    Clone,
131    Copy,
132    Debug,
133    Default,
134    PartialEq,
135    Eq,
136    Serialize,
137    Deserialize,
138    strum::Display,
139    strum::EnumString,
140    strum::VariantArray,
141)]
142#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
143#[serde(rename_all = "snake_case")]
144#[strum(serialize_all = "snake_case")]
145pub enum RecordPolicy {
146    /// Skip the record. It is not selected and never a fault.
147    #[default]
148    Reject,
149    /// Deliver the record marked unevaluated, so the consumer decides.
150    Pass,
151}
152
153impl RecordPolicy {
154    pub const fn is_reject(&self) -> bool {
155        matches!(self, RecordPolicy::Reject)
156    }
157}
158
159/// What happens to a record whose payload cannot be decoded (malformed, over
160/// the size or depth limit). A valid record missing a field is not a fault.
161#[derive(
162    Clone,
163    Copy,
164    Debug,
165    Default,
166    PartialEq,
167    Eq,
168    Serialize,
169    Deserialize,
170    strum::Display,
171    strum::EnumString,
172    strum::VariantArray,
173)]
174#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
175#[serde(rename_all = "snake_case")]
176#[strum(serialize_all = "snake_case")]
177pub enum FaultPolicy {
178    /// Stop the page before the record. It stays unacknowledged until the
179    /// reader changes policy or the record ages out.
180    #[default]
181    Stop,
182    /// Deliver the record marked unevaluated.
183    Pass,
184    /// Skip the record, counted as a fault.
185    Drop,
186}
187
188/// One consumer filter: the expression plus everything that changes what it
189/// selects. Its [`digest`](Self::digest) identifies these semantics.
190#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
191#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
192pub struct ConsumerFilter {
193    pub v: u32,
194    pub evaluator_version: u32,
195    pub expr: FilterExpr,
196    pub codec: FilterCodec,
197    #[serde(default)]
198    pub fault_policy: FaultPolicy,
199    #[serde(default, skip_serializing_if = "RecordPolicy::is_reject")]
200    pub foreign_policy: RecordPolicy,
201    #[serde(default, skip_serializing_if = "RecordPolicy::is_reject")]
202    pub mismatch_policy: RecordPolicy,
203    /// Immutable writer schema IDs permitted for Avro or Protobuf payloads.
204    /// A record selects one of these with its agdx.sid header.
205    #[serde(default, skip_serializing_if = "Vec::is_empty")]
206    pub schema_refs: Vec<u32>,
207    /// The stream whose writer-schema registry holds `schema_refs`. Absent
208    /// resolves them in the deployment-wide registry and leaves the encoding
209    /// and the digest unchanged.
210    #[serde(default, skip_serializing_if = "Option::is_none")]
211    pub schema_stream: Option<String>,
212}
213
214impl FilterExpr {
215    pub fn all(children: impl IntoIterator<Item = FilterExpr>) -> Self {
216        Self::All(children.into_iter().collect())
217    }
218
219    pub fn any(children: impl IntoIterator<Item = FilterExpr>) -> Self {
220        Self::Any(children.into_iter().collect())
221    }
222
223    pub fn negate(child: FilterExpr) -> Self {
224        Self::Not(Box::new(child))
225    }
226
227    pub fn pred(field: impl Into<String>, op: CmpOp, value: impl Into<TypedValue>) -> Self {
228        Self::Pred(Predicate {
229            field: field.into(),
230            op,
231            value: value.into(),
232        })
233    }
234
235    pub fn pred_as(
236        field: impl Into<String>,
237        op: CmpOp,
238        value: impl Into<TypedValue>,
239        coerce: Coerce,
240    ) -> Self {
241        Self::PredAs(CoercedPredicate {
242            pred: Predicate {
243                field: field.into(),
244                op,
245                value: value.into(),
246            },
247            coerce,
248        })
249    }
250
251    /// Presence of a payload path. Returns the parse error of an invalid
252    /// path, so it suits untrusted input where [`Self::present`] would panic.
253    pub fn try_present(path: &str) -> Result<Self, InvalidError> {
254        FieldPath::parse(path).map(Self::Present)
255    }
256
257    /// Presence of a trusted path. Panics if it is invalid.
258    pub fn present(path: &str) -> Self {
259        Self::Present(FieldPath::parse(path).expect("a valid field path"))
260    }
261
262    /// Absence of a payload path. Returns the parse error of an invalid
263    /// path, so it suits untrusted input where [`Self::absent`] would panic.
264    pub fn try_absent(path: &str) -> Result<Self, InvalidError> {
265        FieldPath::parse(path).map(Self::Absent)
266    }
267
268    /// Absence of a trusted path. Panics if it is invalid.
269    pub fn absent(path: &str) -> Self {
270        Self::Absent(FieldPath::parse(path).expect("a valid field path"))
271    }
272
273    pub fn header(key: impl Into<String>, op: CmpOp, value: impl Into<TypedValue>) -> Self {
274        Self::Header(HeaderPredicate {
275            key: key.into(),
276            op,
277            value: value.into(),
278        })
279    }
280
281    pub fn text(field: impl Into<String>, kind: TextMatch, pattern: impl Into<String>) -> Self {
282        Self::Text(TextPredicate {
283            field: field.into(),
284            kind,
285            pattern: pattern.into(),
286            case_insensitive: false,
287        })
288    }
289
290    pub fn header_text(
291        key: impl Into<String>,
292        kind: TextMatch,
293        pattern: impl Into<String>,
294    ) -> Self {
295        Self::HeaderText(TextPredicate {
296            field: key.into(),
297            kind,
298            pattern: pattern.into(),
299            case_insensitive: false,
300        })
301    }
302
303    /// Make a text match case-insensitive. Any other node is returned as is.
304    #[must_use]
305    pub fn case_insensitive(mut self) -> Self {
306        if let Self::Text(predicate) | Self::HeaderText(predicate) = &mut self {
307            predicate.case_insensitive = true;
308        }
309        self
310    }
311
312    /// Whether evaluating this node can require the decoded payload.
313    pub fn reads_payload(&self) -> bool {
314        match self {
315            Self::All(children) | Self::Any(children) => children.iter().any(Self::reads_payload),
316            Self::Not(child) => child.reads_payload(),
317            Self::Pred(_)
318            | Self::PredAs(_)
319            | Self::Present(_)
320            | Self::Absent(_)
321            | Self::Text(_) => true,
322            Self::Header(_) | Self::HeaderText(_) => false,
323        }
324    }
325
326    /// Whether evaluating this node can require the record headers.
327    pub fn reads_headers(&self) -> bool {
328        match self {
329            Self::All(children) | Self::Any(children) => children.iter().any(Self::reads_headers),
330            Self::Not(child) => child.reads_headers(),
331            Self::Header(_) | Self::HeaderText(_) => true,
332            Self::Pred(_)
333            | Self::PredAs(_)
334            | Self::Present(_)
335            | Self::Absent(_)
336            | Self::Text(_) => false,
337        }
338    }
339}
340
341impl ConsumerFilter {
342    /// A JSON-decoding filter with the default `stop` fault policy.
343    pub fn json(expr: FilterExpr) -> Self {
344        Self::new(expr, FilterCodec::Json)
345    }
346
347    /// Decode a self-describing CBOR payload.
348    pub fn cbor(expr: FilterExpr) -> Self {
349        Self::new(expr, FilterCodec::Cbor)
350    }
351
352    /// Decode a raw Avro datum with one of the listed writer schemas.
353    pub fn avro(expr: FilterExpr, schema_refs: impl IntoIterator<Item = u32>) -> Self {
354        Self::schema_codec(expr, FilterCodec::Avro, schema_refs)
355    }
356
357    /// Decode a Protobuf message with one of the listed writer schemas.
358    pub fn protobuf(expr: FilterExpr, schema_refs: impl IntoIterator<Item = u32>) -> Self {
359        Self::schema_codec(expr, FilterCodec::Protobuf, schema_refs)
360    }
361
362    fn schema_codec(
363        expr: FilterExpr,
364        codec: FilterCodec,
365        schema_refs: impl IntoIterator<Item = u32>,
366    ) -> Self {
367        let mut filter = Self::new(expr, codec);
368        filter.schema_refs = schema_refs.into_iter().collect();
369        filter.schema_refs.sort_unstable();
370        filter.schema_refs.dedup();
371        filter
372    }
373
374    /// A header-only filter. The payload is never decoded.
375    pub fn headers_only(expr: FilterExpr) -> Self {
376        Self::new(expr, FilterCodec::HeadersOnly)
377    }
378
379    fn new(expr: FilterExpr, codec: FilterCodec) -> Self {
380        Self {
381            v: FILTER_OP_VERSION,
382            evaluator_version: FILTER_EVALUATOR_VERSION,
383            expr,
384            codec,
385            fault_policy: FaultPolicy::Stop,
386            foreign_policy: RecordPolicy::Reject,
387            mismatch_policy: RecordPolicy::Reject,
388            schema_refs: Vec::new(),
389            schema_stream: None,
390        }
391    }
392
393    #[must_use]
394    pub fn with_fault_policy(mut self, fault_policy: FaultPolicy) -> Self {
395        self.fault_policy = fault_policy;
396        self
397    }
398
399    #[must_use]
400    pub fn with_foreign_policy(mut self, foreign_policy: RecordPolicy) -> Self {
401        self.foreign_policy = foreign_policy;
402        self
403    }
404
405    #[must_use]
406    pub fn with_mismatch_policy(mut self, mismatch_policy: RecordPolicy) -> Self {
407        self.mismatch_policy = mismatch_policy;
408        self
409    }
410
411    /// Resolve `schema_refs` in the writer-schema registry of `stream`.
412    #[must_use]
413    pub fn with_schema_stream(mut self, stream: impl Into<String>) -> Self {
414        self.schema_stream = Some(stream.into());
415        self
416    }
417
418    /// SHA-256 over a domain tag and the JSON encoding of the filter. Every
419    /// semantic field is covered. Two filters get the same digest exactly when
420    /// their encodings are equal: logically equivalent but differently written
421    /// expressions keep distinct digests.
422    pub fn digest(&self) -> Digest32 {
423        let encoded = serde_json::to_vec(self).expect("a consumer filter always encodes as JSON");
424        let mut hasher = Sha256::new();
425        hasher.update(DIGEST_DOMAIN);
426        hasher.update(&encoded);
427        Digest32::new(hasher.finalize().into())
428    }
429}
430
431impl Validate for ConsumerFilter {
432    fn validate(&self) -> Result<(), InvalidError> {
433        if self.v != FILTER_OP_VERSION {
434            return Err(InvalidError::new(format!(
435                "filter version {} is not supported, expected {FILTER_OP_VERSION}",
436                self.v
437            )));
438        }
439        if self.evaluator_version != FILTER_EVALUATOR_VERSION {
440            return Err(InvalidError::new(format!(
441                "evaluator version {} is not supported, expected {FILTER_EVALUATOR_VERSION}",
442                self.evaluator_version
443            )));
444        }
445        let schema_codec = matches!(self.codec, FilterCodec::Avro | FilterCodec::Protobuf);
446        if schema_codec == self.schema_refs.is_empty() {
447            return Err(InvalidError::new(
448                "Avro and Protobuf require schema_refs, other codecs require no schema_refs",
449            ));
450        }
451        if self.schema_refs.windows(2).any(|ids| ids[0] >= ids[1]) {
452            return Err(InvalidError::new(
453                "schema_refs must be sorted and contain no duplicates",
454            ));
455        }
456        if let Some(stream) = &self.schema_stream {
457            if self.schema_refs.is_empty() {
458                return Err(InvalidError::new(
459                    "schema_stream applies only to a filter with schema_refs",
460                ));
461            }
462            if stream.is_empty() || stream.contains('/') || stream.chars().any(char::is_control) {
463                return Err(InvalidError::new(
464                    "schema_stream must be a non-empty stream name without '/' or control characters",
465                ));
466            }
467        }
468        let encoded_bytes = serde_json::to_vec(self)
469            .map_err(|error| InvalidError::new(format!("filter does not encode: {error}")))?
470            .len();
471        if encoded_bytes > MAX_FILTER_BYTES {
472            return Err(InvalidError::new(format!(
473                "filter is {encoded_bytes}B, exceeds cap {MAX_FILTER_BYTES}B"
474            )));
475        }
476        if self.codec == FilterCodec::Unknown {
477            return Err(InvalidError::new(
478                "the filter codec is not supported by this build",
479            ));
480        }
481        if self.codec == FilterCodec::HeadersOnly && self.expr.reads_payload() {
482            return Err(InvalidError::new(
483                "a headers_only filter cannot use payload predicates",
484            ));
485        }
486        let mut nodes = 0;
487        validate_node(&self.expr, 1, &mut nodes)?;
488        if regex_predicates(&self.expr) > MAX_REGEX_PREDICATES {
489            return Err(InvalidError::new(format!(
490                "a filter holds at most {MAX_REGEX_PREDICATES} compiled text predicates (glob or regex)"
491            )));
492        }
493        Ok(())
494    }
495}
496
497// Every regex compiles to a bounded program, and this bounds their number, so
498// one filter and the per-shard cache of compiled filters stay bounded too.
499fn regex_predicates(expr: &FilterExpr) -> usize {
500    match expr {
501        FilterExpr::All(children) | FilterExpr::Any(children) => {
502            children.iter().map(regex_predicates).sum()
503        }
504        FilterExpr::Not(child) => regex_predicates(child),
505        FilterExpr::Text(predicate) | FilterExpr::HeaderText(predicate) => {
506            usize::from(matches!(predicate.kind, TextMatch::Regex | TextMatch::Glob))
507        }
508        FilterExpr::Pred(_)
509        | FilterExpr::PredAs(_)
510        | FilterExpr::Present(_)
511        | FilterExpr::Absent(_)
512        | FilterExpr::Header(_) => 0,
513    }
514}
515
516fn validate_node(expr: &FilterExpr, depth: usize, nodes: &mut usize) -> Result<(), InvalidError> {
517    if depth > MAX_FILTER_DEPTH {
518        return Err(InvalidError::new(format!(
519            "filter nesting exceeds depth {MAX_FILTER_DEPTH}"
520        )));
521    }
522    count_nodes(nodes, 1)?;
523    match expr {
524        FilterExpr::All(children) | FilterExpr::Any(children) => {
525            if children.is_empty() {
526                return Err(InvalidError::new("`all` and `any` need at least one child"));
527            }
528            children
529                .iter()
530                .try_for_each(|child| validate_node(child, depth + 1, nodes))
531        }
532        FilterExpr::Not(child) => validate_node(child, depth + 1, nodes),
533        FilterExpr::Pred(predicate) => {
534            FieldPath::parse(&predicate.field)?;
535            validate_literal(predicate.op, &predicate.value, LiteralSite::Payload, nodes)
536        }
537        FilterExpr::PredAs(coerced) => {
538            FieldPath::parse(&coerced.pred.field)?;
539            validate_coerced(coerced, nodes)
540        }
541        FilterExpr::Present(_) | FilterExpr::Absent(_) => Ok(()),
542        FilterExpr::Header(header) => {
543            validate_header_key(&header.key)?;
544            validate_literal(header.op, &header.value, LiteralSite::Header, nodes)
545        }
546        FilterExpr::Text(predicate) => {
547            FieldPath::parse(&predicate.field)?;
548            predicate.validate()
549        }
550        FilterExpr::HeaderText(predicate) => {
551            validate_header_key(&predicate.field)?;
552            predicate.validate()
553        }
554    }
555}
556
557fn validate_header_key(key: &str) -> Result<(), InvalidError> {
558    if key.is_empty() || key.len() > MAX_FILTER_PATH_BYTES {
559        return Err(InvalidError::new(format!(
560            "header key must be 1..={MAX_FILTER_PATH_BYTES} bytes"
561        )));
562    }
563    Ok(())
564}
565
566fn count_nodes(nodes: &mut usize, added: usize) -> Result<(), InvalidError> {
567    *nodes += added;
568    if *nodes > MAX_FILTER_NODES {
569        return Err(InvalidError::new(format!(
570            "filter has more than {MAX_FILTER_NODES} nodes"
571        )));
572    }
573    Ok(())
574}
575
576#[derive(Clone, Copy, PartialEq, Eq)]
577enum LiteralSite {
578    Payload,
579    Header,
580}
581
582fn validate_literal(
583    op: CmpOp,
584    value: &TypedValue,
585    site: LiteralSite,
586    nodes: &mut usize,
587) -> Result<(), InvalidError> {
588    match (op, value) {
589        (CmpOp::Eq | CmpOp::Ne, TypedValue::Null) if site == LiteralSite::Payload => Ok(()),
590        (_, TypedValue::Null) => Err(InvalidError::new(match site {
591            LiteralSite::Payload => "a null literal only supports eq and ne",
592            LiteralSite::Header => "a header predicate cannot compare against null",
593        })),
594        (CmpOp::In, TypedValue::List(items)) => {
595            if items.is_empty() || items.len() > MAX_FILTER_LIST_ITEMS {
596                return Err(InvalidError::new(format!(
597                    "an `in` list needs 1..={MAX_FILTER_LIST_ITEMS} items"
598                )));
599            }
600            count_nodes(nodes, items.len())?;
601            items.iter().try_for_each(|item| {
602                if matches!(item, TypedValue::Null | TypedValue::List(_)) {
603                    return Err(InvalidError::new(
604                        "`in` list items must be non-null scalars",
605                    ));
606                }
607                validate_scalar(item)
608            })
609        }
610        (CmpOp::In, _) => Err(InvalidError::new("`in` expects a list literal")),
611        (_, TypedValue::List(_)) => Err(InvalidError::new("a list literal only supports `in`")),
612        (CmpOp::Lt | CmpOp::Lte | CmpOp::Gt | CmpOp::Gte, TypedValue::Boolean(_)) => Err(
613            InvalidError::new("ordered comparisons need a number or string literal"),
614        ),
615        (CmpOp::Prefix, value) if !matches!(value, TypedValue::String(_)) => {
616            Err(InvalidError::new("`prefix` expects a string literal"))
617        }
618        (_, value) => validate_scalar(value),
619    }
620}
621
622fn validate_scalar(value: &TypedValue) -> Result<(), InvalidError> {
623    match value {
624        TypedValue::Boolean(_) | TypedValue::Int(_) | TypedValue::Long(_) => Ok(()),
625        TypedValue::Double(number) if number.is_finite() => Ok(()),
626        TypedValue::Double(_) => Err(InvalidError::new("a double literal must be finite")),
627        TypedValue::String(text) if text.len() <= MAX_FILTER_STRING_BYTES => Ok(()),
628        TypedValue::String(_) => Err(InvalidError::new(format!(
629            "a string literal exceeds {MAX_FILTER_STRING_BYTES}B"
630        ))),
631        _ => Err(InvalidError::new(
632            "supported literals are null, boolean, int, long, double, string, and list",
633        )),
634    }
635}
636
637fn validate_coerced(coerced: &CoercedPredicate, nodes: &mut usize) -> Result<(), InvalidError> {
638    let op = coerced.pred.op;
639    if matches!(op, CmpOp::Contains | CmpOp::Prefix) {
640        return Err(InvalidError::new(
641            "a coerced predicate supports eq, ne, lt, lte, gt, gte, and in",
642        ));
643    }
644    let items: Vec<&TypedValue> = match (&coerced.pred.value, op) {
645        (TypedValue::List(items), CmpOp::In) => {
646            if items.is_empty() || items.len() > MAX_FILTER_LIST_ITEMS {
647                return Err(InvalidError::new(format!(
648                    "an `in` list needs 1..={MAX_FILTER_LIST_ITEMS} items"
649                )));
650            }
651            count_nodes(nodes, items.len())?;
652            items.iter().collect()
653        }
654        (_, CmpOp::In) => return Err(InvalidError::new("`in` expects a list literal")),
655        (TypedValue::List(_), _) => {
656            return Err(InvalidError::new("a list literal only supports `in`"));
657        }
658        (value, _) => vec![value],
659    };
660    items.into_iter().try_for_each(|item| {
661        if coerced_literal_parses(coerced.coerce, item) {
662            Ok(())
663        } else {
664            Err(InvalidError::new(format!(
665                "literal {} does not parse under the {} coercion",
666                item.diagnostic_text(),
667                coerce_label(coerced.coerce)
668            )))
669        }
670    })
671}
672
673pub(crate) fn coerced_literal_parses(coerce: Coerce, value: &TypedValue) -> bool {
674    match coerce {
675        Coerce::Timestamp { format } => match value {
676            TypedValue::String(text) => format.micros_from_text(text).is_some(),
677            TypedValue::Int(number) => format.micros_from_integer(i128::from(*number)).is_some(),
678            TypedValue::Long(number) => format.micros_from_integer(i128::from(*number)).is_some(),
679            _ => false,
680        },
681        Coerce::Number => match value {
682            TypedValue::String(text) => ExactDecimal::parse(text).is_some(),
683            TypedValue::Int(_) | TypedValue::Long(_) => true,
684            _ => false,
685        },
686    }
687}
688
689fn coerce_label(coerce: Coerce) -> String {
690    match coerce {
691        Coerce::Timestamp { format } => format!("timestamp ({format})"),
692        Coerce::Number => "number".to_owned(),
693    }
694}
695
696#[cfg(test)]
697mod tests {
698    use super::*;
699
700    fn safe_mode_filter() -> ConsumerFilter {
701        ConsumerFilter::json(FilterExpr::all([
702            FilterExpr::pred("table", CmpOp::Eq, "satellites"),
703            FilterExpr::pred("changed", CmpOp::Contains, "mode"),
704            FilterExpr::pred("after.mode", CmpOp::Eq, "safe"),
705        ]))
706    }
707
708    #[test]
709    fn given_a_well_formed_filter_when_validated_then_should_pass() {
710        safe_mode_filter().validate().expect("the filter is valid");
711    }
712
713    #[test]
714    fn given_compiled_text_predicates_when_the_filter_budget_is_exceeded_then_should_reject() {
715        for kind in [TextMatch::Glob, TextMatch::Regex] {
716            let children = (0..4).map(|_| FilterExpr::text("name", kind, "safe"));
717            ConsumerFilter::json(FilterExpr::all(children))
718                .validate()
719                .expect("four programs fit");
720            let children = (0..5).map(|_| FilterExpr::text("name", kind, "safe"));
721            assert!(
722                ConsumerFilter::json(FilterExpr::all(children))
723                    .validate()
724                    .is_err()
725            );
726        }
727    }
728
729    #[test]
730    fn given_a_schema_stream_when_encoded_then_should_change_only_a_filter_that_sets_it() {
731        let filter = ConsumerFilter::avro(FilterExpr::pred("mode", CmpOp::Eq, "safe"), [7]);
732        let json = serde_json::to_string(&filter).expect("filter encodes");
733        assert!(!json.contains("schema_stream"), "unset is omitted: {json}");
734        let scoped = filter.clone().with_schema_stream("acme");
735        scoped.validate().expect("a scoped schema filter is valid");
736        assert_ne!(scoped.digest(), filter.digest());
737        let back: ConsumerFilter =
738            serde_json::from_str(&serde_json::to_string(&scoped).expect("filter encodes"))
739                .expect("filter decodes");
740        assert_eq!(back.schema_stream.as_deref(), Some("acme"));
741    }
742
743    #[test]
744    fn given_an_invalid_schema_stream_when_validated_then_should_reject() {
745        let avro = ConsumerFilter::avro(FilterExpr::pred("mode", CmpOp::Eq, "safe"), [7]);
746        assert!(avro.clone().with_schema_stream("").validate().is_err());
747        assert!(avro.with_schema_stream("a/b").validate().is_err());
748        assert!(
749            safe_mode_filter()
750                .with_schema_stream("acme")
751                .validate()
752                .is_err(),
753            "a filter without schema_refs names no registry"
754        );
755    }
756
757    #[test]
758    fn given_equal_filters_when_digested_then_should_match_and_differ_on_any_change() {
759        let digest = safe_mode_filter().digest();
760        assert_eq!(digest, safe_mode_filter().digest());
761        assert_eq!(digest.as_bytes().len(), Digest32::BYTES);
762        let dropped = safe_mode_filter().with_fault_policy(FaultPolicy::Drop);
763        assert_ne!(digest, dropped.digest(), "the fault policy is semantic");
764        let reordered = ConsumerFilter::json(FilterExpr::all([
765            FilterExpr::pred("changed", CmpOp::Contains, "mode"),
766            FilterExpr::pred("table", CmpOp::Eq, "satellites"),
767            FilterExpr::pred("after.mode", CmpOp::Eq, "safe"),
768        ]));
769        assert_ne!(digest, reordered.digest(), "expression order is preserved");
770    }
771
772    #[test]
773    fn given_payload_nodes_in_a_headers_only_filter_when_validated_then_should_be_rejected() {
774        let filter = ConsumerFilter::headers_only(FilterExpr::any([
775            FilterExpr::header("table", CmpOp::Eq, "satellites"),
776            FilterExpr::present("kind"),
777        ]));
778        assert!(filter.validate().is_err());
779        let filter =
780            ConsumerFilter::headers_only(FilterExpr::header("table", CmpOp::Eq, "satellites"));
781        filter.validate().expect("header predicates are allowed");
782    }
783
784    #[test]
785    fn given_invalid_literals_when_validated_then_should_be_rejected() {
786        let cases = [
787            FilterExpr::pred("a", CmpOp::Gt, TypedValue::Null),
788            FilterExpr::pred("a", CmpOp::In, "x"),
789            FilterExpr::pred("a", CmpOp::Eq, TypedValue::List(vec!["x".into()])),
790            FilterExpr::pred("a", CmpOp::In, TypedValue::List(Vec::new())),
791            FilterExpr::pred("a", CmpOp::In, TypedValue::List(vec![TypedValue::Null])),
792            FilterExpr::pred("a", CmpOp::Prefix, 5),
793            FilterExpr::pred("a", CmpOp::Lt, true),
794            FilterExpr::pred("a", CmpOp::Eq, f64::NAN),
795            FilterExpr::pred("a", CmpOp::Eq, TypedValue::Date(3)),
796            FilterExpr::pred("a..b", CmpOp::Eq, 1),
797            FilterExpr::header("", CmpOp::Eq, "x"),
798            FilterExpr::header("kind", CmpOp::Eq, TypedValue::Null),
799            FilterExpr::all([]),
800        ];
801        for expr in cases {
802            let filter = ConsumerFilter::json(expr.clone());
803            assert!(filter.validate().is_err(), "{expr:?} must be rejected");
804        }
805    }
806
807    #[test]
808    fn given_coerced_literals_when_validated_then_should_parse_under_their_coercion() {
809        let valid = [
810            FilterExpr::pred_as(
811                "date",
812                CmpOp::Gte,
813                "2026-09-21T00:00:00Z",
814                Coerce::Timestamp {
815                    format: TimestampFormat::Rfc3339,
816                },
817            ),
818            FilterExpr::pred_as(
819                "timestamp_ms",
820                CmpOp::Lt,
821                1_758_470_652_331_i64,
822                Coerce::Timestamp {
823                    format: TimestampFormat::EpochMillis,
824                },
825            ),
826            FilterExpr::pred_as("cpu", CmpOp::Gt, "12.50", Coerce::Number),
827            FilterExpr::pred_as(
828                "cpu",
829                CmpOp::In,
830                TypedValue::List(vec!["1".into(), 2_i64.into()]),
831                Coerce::Number,
832            ),
833        ];
834        for expr in valid {
835            ConsumerFilter::json(expr.clone())
836                .validate()
837                .unwrap_or_else(|error| panic!("{expr:?} must be valid: {error}"));
838        }
839        let invalid = [
840            FilterExpr::pred_as(
841                "date",
842                CmpOp::Gte,
843                "2026-09-21T00:00:00",
844                Coerce::Timestamp {
845                    format: TimestampFormat::Rfc3339,
846                },
847            ),
848            FilterExpr::pred_as("cpu", CmpOp::Gt, "1e5", Coerce::Number),
849            FilterExpr::pred_as("cpu", CmpOp::Contains, "1", Coerce::Number),
850            FilterExpr::pred_as("cpu", CmpOp::Gt, 1.5, Coerce::Number),
851        ];
852        for expr in invalid {
853            assert!(
854                ConsumerFilter::json(expr.clone()).validate().is_err(),
855                "{expr:?} must be rejected"
856            );
857        }
858    }
859
860    #[test]
861    fn given_limits_when_exceeded_then_should_be_rejected() {
862        let mut expr = FilterExpr::pred("a", CmpOp::Eq, 1);
863        for _ in 0..MAX_FILTER_DEPTH {
864            expr = FilterExpr::negate(expr);
865        }
866        assert!(ConsumerFilter::json(expr).validate().is_err(), "too deep");
867        let wide = FilterExpr::any(
868            (0..MAX_FILTER_NODES).map(|index| FilterExpr::pred(format!("f{index}"), CmpOp::Eq, 1)),
869        );
870        assert!(
871            ConsumerFilter::json(wide).validate().is_err(),
872            "too many nodes"
873        );
874        let mut filter = safe_mode_filter();
875        filter.schema_refs = vec![7];
876        assert!(
877            filter.validate().is_err(),
878            "schema references are not served yet"
879        );
880        let mut filter = safe_mode_filter();
881        filter.evaluator_version = 2;
882        assert!(filter.validate().is_err(), "unknown evaluator version");
883    }
884
885    #[test]
886    fn given_a_filter_when_json_round_tripped_then_should_use_typed_value_tags() {
887        let filter = ConsumerFilter::json(FilterExpr::all([
888            FilterExpr::pred("op", CmpOp::Eq, "d"),
889            FilterExpr::present("fields.mode"),
890        ]));
891        let json = serde_json::to_value(&filter).expect("encodes");
892        assert_eq!(
893            json,
894            serde_json::json!({
895                "v": 1,
896                "evaluator_version": 1,
897                "expr": {"all": [
898                    {"pred": {"field": "op", "op": "eq", "value": {"kind": "string", "value": "d"}}},
899                    {"present": "fields.mode"}
900                ]},
901                "codec": "json",
902                "fault_policy": "stop"
903            })
904        );
905        let back: ConsumerFilter = serde_json::from_value(json).expect("decodes");
906        assert_eq!(back, filter);
907    }
908}