Wirerust

A high-performance, modular filter engine for structured data written in Rust. Wirerust provides a clean, extensible implementation for parsing, compiling, and executing filter expressions against runtime data with strong type safety and excellent performance.

Features

✨ Core Capabilities

• Schema-driven filtering: Define field types and constraints for your data
• Expression parsing: Parse human-readable filter expressions into an AST
• Compilation: Compile expressions to efficient closures for fast execution
• Type safety: Strong type checking with comprehensive error handling
• Extensible functions: Register built-in or custom filter functions
• Serialization: Full Serde support for schemas, contexts, and expressions

🔧 Supported Types

• Primitives: bool, int, bytes, string
• Network: ip (IPv4/IPv6 addresses)
• Collections: array, map with type inference
• Special: unknown for dynamic typing

⚡ Performance

• Zero-copy parsing where possible
• Compiled expressions for optimal runtime performance
• Efficient memory usage with Arc-based sharing
• Property-based testing ensures correctness

Quick Start

Add to your Cargo.toml:

[dependencies]
wirerust = "0.1.0"

Basic usage:

use wirerust::{
    WirerustEngineBuilder, FilterContext, LiteralValue, FieldType
};

// Create an engine with schema
let engine = WirerustEngineBuilder::new()
    .field("status", FieldType::Int)
    .field("method", FieldType::Bytes)
    .field("path", FieldType::Bytes)
    .build();

// Parse and compile a filter
let filter = engine.parse_and_compile("status == 200 && method == \"GET\"").unwrap();

// Create context with data
let mut ctx = FilterContext::new();
ctx.set("status", LiteralValue::Int(200), engine.schema()).unwrap();
ctx.set("method", LiteralValue::Bytes(b"GET".to_vec()), engine.schema()).unwrap();

// Execute the filter
assert!(filter.execute(&ctx).unwrap());

Advanced Usage

Custom Functions

use wirerust::{FilterFunction, LiteralValue, WirerustEngineBuilder, FieldType};

struct CustomFilter;

impl FilterFunction for CustomFilter {
    fn call(&self, args: &[LiteralValue]) -> Option<LiteralValue> {
        // Your custom logic here
        Some(LiteralValue::Bool(true))
    }
}

let engine = WirerustEngineBuilder::new()
    .field("data", FieldType::Bytes)
    .register_function("custom_filter", CustomFilter)
    .build();

Complex Expressions

// IP address filtering
let filter = engine.parse_and_compile(
    "ip in [\"192.168.1.1\", \"10.0.0.1\"] && status >= 200 && status < 300"
).unwrap();

// String operations with functions
let filter = engine.parse_and_compile(
    "starts_with(path, \"/api/\") && len(path) > 10"
).unwrap();

// Logical combinations
let filter = engine.parse_and_compile(
    "(method == \"POST\" || method == \"PUT\") && status != 404"
).unwrap();

Built-in Functions

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Filter String │───▶│ AST (FilterExpr)│───▶│ CompiledFilter  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                      │
                                ▼                      ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   Type Checker  │    │   Execution     │
                       └─────────────────┘    └─────────────────┘
                                │                      │
                                ▼                      ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   Schema        │    │   Context       │
                       └─────────────────┘    └─────────────────┘

Core Components

• Schema: Field definitions and type constraints
• Parser: Converts filter strings to AST
• Compiler: Optimizes AST to executable closures
• Context: Runtime value storage with type checking
• Functions: Extensible function registry
• Types: Strong type system with inference

Performance

Wirerust is designed for high-performance scenarios:

• Zero-copy parsing where possible
• Compiled expressions avoid repeated parsing
• Efficient memory usage with smart pointer sharing
• Type-safe execution prevents runtime errors
• Property-based testing ensures correctness

Benchmarks show excellent performance for typical filter operations.

Development

Prerequisites

• Rust 1.88.0 or later
• Git

Setup

git clone https://github.com/pyrowall/wirerust.git
cd wirerust
cargo test

Running Tests

# Run all tests
cargo test

# Run with all features
cargo test --all-features

# Run benchmarks
cargo bench

# Run clippy
cargo clippy --all-targets --all-features -- -D warnings

Version Management

# Bump patch version (0.1.0 -> 0.1.1)
./scripts/bump-version.sh patch

# Bump minor version (0.1.0 -> 0.2.0)
./scripts/bump-version.sh minor

# Bump major version (0.1.0 -> 1.0.0)
./scripts/bump-version.sh major

Roadmap

Current Status ✅

• Core filter engine with schema support
• Expression parsing and compilation
• Type-safe execution context
• Built-in function library
• Comprehensive test suite
• Property-based testing
• Serialization support

Planned Features 🚧

• Enhanced type inference for arrays and maps
• Dynamic operator registration for extensibility
• FFI/WASM bindings for cross-language use
• Advanced error handling with detailed diagnostics
• Performance benchmarks and optimization
• Query optimization for complex expressions
• Caching layer for compiled filters

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Guidelines

1. Tests: Ensure all tests pass with cargo test
2. Style: Follow Rust idioms and run cargo clippy
3. Documentation: Add docs for new features
4. Commits: Use conventional commit messages

Getting Started

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the full test suite
6. Submit a pull request

License

This project is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Acknowledgments

• Inspired by Cloudflare's wirefilter
• Built with modern Rust idioms and best practices
• Community-driven development and feedback

Wirerust - Fast, safe, and extensible filtering for Rust applications.