Allow prefiltering based on string fields

Cargo.toml

@@ -22,12 +22,14 @@ serde = { version = "1.0", features = ["derive"], optional = true }
 serde_regex = { version = "1.1", optional = true }
 fnv = "1"
 bitflags = { version = "2.6", optional = true }
+atc_router_prefilter = { version = "1.0", path = "crates/atc_router_prefilter" }
 
 [dev-dependencies]
 criterion = "0"
 
 [lib]
 crate-type = ["lib", "cdylib", "staticlib"]
+bench = false
 
 [features]
 default = ["ffi"]
@@ -42,3 +44,10 @@ harness = false
 [[bench]]
 name = "match_mix"
 harness = false
+
+[[bench]]
+name = "worst_case"
+harness = false
+
+[workspace]
+members = ["crates/*"]

README.md

@@ -16,6 +16,8 @@ ATC Router library for Kong.
         * [new](#new)
         * [add\_matcher](#add_matcher)
         * [remove\_matcher](#remove_matcher)
+        * [enable\_prefilter](#enable_prefilter)
+        * [disable\_prefilter](#disable_prefilter)
         * [execute](#execute)
         * [get\_fields](#get_fields)
         * [validate](#validate)
@@ -165,6 +167,36 @@ matcher does not exist.
 
 [Back to TOC](#table-of-contents)
 
+### enable\_prefilter
+
+**syntax:** *res, err = r:enable_prefilter(field)*
+
+**context:** *any*
+
+Enables prefiltering on the specified `field`. The field must be of type `String`
+in the router's schema. When enabled, the router uses the prefilter to narrow down
+candidate matchers before performing full evaluation, which can improve match
+performance.
+
+Calling this method requires building a prefilter for all current matchers: it may be 
+expensive. It is expected that this method will be called only once for a router. The
+prefilter will be kept up to date with any added and removed matchers, until this method
+is called again with a different field name, or the disable_prefilter method is called.
+
+If an error occurred, `nil` and a string describing the error will be returned.
+
+[Back to TOC](#table-of-contents)
+
+### disable\_prefilter
+
+**syntax:** *r:disable_prefilter()*
+
+**context:** *any*
+
+Disables prefiltering on the router, reverting to the default matching behavior.
+
+[Back to TOC](#table-of-contents)
+
 ### execute
 
 **syntax:** *res, err = r:execute(context)*

benches/build.rs

@@ -1,15 +1,15 @@
 use atc_router::ast::Type;
 use atc_router::router::Router;
 use atc_router::schema::Schema;
-use criterion::{criterion_group, criterion_main, Criterion};
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
 use uuid::Uuid;
 
 // To run this benchmark, execute the following command:
 // ```shell
 // cargo bench --bench build
 // ```
 
-const N: usize = 1000;
+const N: usize = 5000;
 
 fn make_uuid(a: usize) -> String {
     format!("8cb2a7d0-c775-4ed9-989f-{:012}", a)
@@ -24,23 +24,50 @@ fn criterion_benchmark(c: &mut Criterion) {
         let uuid = make_uuid(i);
         let uuid = Uuid::try_from(uuid.as_str()).unwrap();
 
-        let expr = format!("((a > 0 || a < {}) && a != 0) && a == 1", N + 1);
+        let expr = format!(
+            "((a > 0 || a < {0}) && a != 0) && a == 1 && b == \"{0}\"",
+            N + 1
+        );
 
         data.push((priority, uuid, expr))
     }
 
     let mut schema = Schema::default();
     schema.add_field("a", Type::Int);
+    schema.add_field("b", Type::String);
 
-    c.bench_function("Build Router", |b| {
-        b.iter_with_large_drop(|| {
-            let mut router = Router::new(&schema);
-            for v in &data {
-                router.add_matcher(v.0, v.1, &v.2).unwrap();
-            }
-            router
-        });
-    });
+    let mut g = c.benchmark_group("build router");
+    for n in [1, 10, 100, 500, 1000, 3000, N] {
+        g.throughput(Throughput::Elements(n as u64));
+        g.bench_with_input(
+            BenchmarkId::new("without prefilter", n),
+            &data[..n],
+            |b, data| {
+                b.iter_with_large_drop(|| {
+                    let mut router = Router::new(&schema);
+                    for v in data {
+                        router.add_matcher(v.0, v.1, &v.2).unwrap();
+                    }
+                    router
+                });
+            },
+        );
+
+        g.bench_with_input(
+            BenchmarkId::new("with prefilter", n),
+            &data[..n],
+            |b, data| {
+                b.iter_with_large_drop(|| {
+                    let mut router = Router::new(&schema);
+                    router.enable_prefilter("b");
+                    for v in data {
+                        router.add_matcher(v.0, v.1, &v.2).unwrap();
+                    }
+                    router
+                });
+            },
+        );
+    }
 }
 
 criterion_group!(benches, criterion_benchmark);

benches/match_mix.rs

@@ -2,14 +2,9 @@ use atc_router::ast::{Type, Value};
 use atc_router::context::Context;
 use atc_router::router::Router;
 use atc_router::schema::Schema;
-use criterion::{criterion_group, criterion_main, Criterion};
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
 use uuid::Uuid;
 
-// To run this benchmark, execute the following command:
-// ```shell
-// cargo bench --bench match_mix
-// ```
-
 const N: usize = 100_000;
 
 fn make_uuid(a: usize) -> String {
@@ -26,8 +21,8 @@ fn criterion_benchmark(c: &mut Criterion) {
 
     for i in 0..N {
         let expr = format!(
-            r#"(http.path == "hello{}" && http.version == "1.1") || {} || {} || {}"#,
-            i, "!((a == 2) && (a == 9))", "!(a == 1)", "(a == 3 && a == 4) && !(a == 5)"
+            r#"(http.path == "hello{}" && http.version == "1.1") && ({} || {} || {}) && {}"#,
+            i, "!((a == 2) && (a == 9))", "!(a == 1)", "(a == 3 && a == 4)", "!(a == 5)"
         );
 
         let uuid = make_uuid(i);
@@ -36,33 +31,44 @@ fn criterion_benchmark(c: &mut Criterion) {
         router.add_matcher(N - i, uuid, &expr).unwrap();
     }
 
+    let mut g = c.benchmark_group("match_mix");
+
     let mut ctx = Context::new(&schema);
 
     // match benchmark
-    ctx.add_value("http.path", Value::String("hello49999".to_string()));
-    ctx.add_value("http.version", Value::String("1.1".to_string()));
-    ctx.add_value("a", Value::Int(3_i64));
+    const NUMBERS: &[usize] = &[0, 10, 1_000, 10_000, 40_000, 70_000, N - 1, N + 1];
+    for &i in NUMBERS {
+        ctx.reset();
+        ctx.add_value("http.path", Value::String(format!("hello{}", i)));
+        ctx.add_value("http.version", Value::String("1.1".to_string()));
+        ctx.add_value("a", Value::Int(3_i64));
 
-    c.bench_function("Match", |b| {
-        b.iter(|| {
-            let is_match = router.execute(&mut ctx);
-            assert!(is_match);
+        let expected_match = i < N;
+        g.bench_with_input(BenchmarkId::new("without prefilter", i), &i, |b, _| {
+            b.iter(|| {
+                let is_match = router.execute(&mut ctx);
+                assert_eq!(is_match, expected_match);
+            });
         });
-    });
+    }
 
-    ctx.reset();
+    router.enable_prefilter("http.path");
 
-    // not match benchmark
-    ctx.add_value("http.path", Value::String("hello49999".to_string()));
-    ctx.add_value("http.version", Value::String("1.1".to_string()));
-    ctx.add_value("a", Value::Int(5_i64)); // not match
+    for &i in NUMBERS {
+        ctx.reset();
+        ctx.add_value("http.path", Value::String(format!("hello{}", i)));
+        ctx.add_value("http.version", Value::String("1.1".to_string()));
+        ctx.add_value("a", Value::Int(3_i64));
 
-    c.bench_function("Doesn't Match", |b| {
-        b.iter(|| {
-            let not_match = !router.execute(&mut ctx);
-            assert!(not_match);
+        let expected_match = i < N;
+        g.bench_with_input(BenchmarkId::new("with prefilter", i), &i, |b, _| {
+            b.iter(|| {
+                let is_match = router.execute(&mut ctx);
+                assert_eq!(is_match, expected_match);
+            });
         });
-    });
+    }
+    g.finish();
 }
 
 criterion_group!(benches, criterion_benchmark);

benches/worst_case.rs

@@ -0,0 +1,104 @@
+use atc_router::ast::{Type, Value};
+use atc_router::context::Context;
+use atc_router::router::Router;
+use atc_router::schema::Schema;
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use uuid::Uuid;
+
+fn make_uuid(a: usize) -> String {
+    format!("8cb2a7d0-c775-4ed9-989f-{:012}", a)
+}
+
+fn worst_case(c: &mut Criterion) {
+    const MAX: usize = 2_000;
+    let mut schema = Schema::default();
+    schema.add_field("http.path", Type::String);
+
+    // This is the worst case for the prefilter, we end up finding prefixes as
+    // '/a', '/a/a', '/a/a/a', etc, which means a string that starts with `/a/a/a/...` also
+    // starts with `/a/a/...`, and also starts with `/a/...` etc.
+    let all_matchers: Vec<(usize, Uuid, String)> = (0..MAX)
+        .map(|i| {
+            let expression_str = format!("http.path == r#\"{}\"#", "/a".repeat(i));
+            (MAX - i, make_uuid(i).parse().unwrap(), expression_str)
+        })
+        .collect();
+
+    let mut g = c.benchmark_group("worst-case build");
+    for n in [1, 10, 100, 500, 1000, MAX] {
+        // Get the _last_ matchers, to avoid both growing the number of matchers, and the size of
+        // the matchers
+        let matchers = all_matchers.windows(n).last().unwrap();
+        g.throughput(Throughput::Elements(n as u64));
+        g.bench_with_input(
+            BenchmarkId::new("without prefilter", n),
+            matchers,
+            |b, matchers| {
+                b.iter_with_large_drop(|| {
+                    let mut router = Router::new(&schema);
+                    for &(priority, uuid, ref expression) in matchers {
+                        router.add_matcher(priority, uuid, expression).unwrap();
+                    }
+                    router
+                });
+            },
+        );
+
+        g.bench_with_input(
+            BenchmarkId::new("with prefilter", n),
+            matchers,
+            |b, matchers| {
+                b.iter_with_large_drop(|| {
+                    let mut router = Router::new(&schema);
+                    router.enable_prefilter("http.path");
+                    for &(priority, uuid, ref expression) in matchers {
+                        router.add_matcher(priority, uuid, expression).unwrap();
+                    }
+                    router
+                });
+            },
+        );
+    }
+    g.finish();
+
+    let mut router = Router::new(&schema);
+    for (priority, uuid, expression) in all_matchers {
+        router.add_matcher(priority, uuid, &expression).unwrap();
+    }
+    let mut ctx = Context::new(&schema);
+    let mut g = c.benchmark_group("worst-case match");
+    for n in [1, 10, 100, 500, 1000, MAX] {
+        ctx.reset();
+        ctx.add_value("http.path", Value::String("/a".repeat(n - 1)));
+        g.bench_with_input(
+            BenchmarkId::new("without prefilter", n),
+            &router,
+            |b, router| {
+                b.iter(|| {
+                    let found = router.execute(&mut ctx);
+                    assert!(found);
+                    found
+                })
+            },
+        );
+    }
+    router.enable_prefilter("http.path");
+    for n in [1, 10, 100, 500, 1000, MAX] {
+        ctx.reset();
+        ctx.add_value("http.path", Value::String("/a".repeat(n - 1)));
+        g.bench_with_input(
+            BenchmarkId::new("with prefilter", n),
+            &router,
+            |b, router| {
+                b.iter(|| {
+                    let found = router.execute(&mut ctx);
+                    assert!(found);
+                    found
+                })
+            },
+        );
+    }
+}
+
+criterion_group!(benches, worst_case);
+criterion_main!(benches);

crates/atc_router_prefilter/.gitignore

@@ -0,0 +1 @@
+/target