Crate matchy

Crate matchy 

Source
Expand description

Matchy - Fast Database for IP Address and Pattern Matching

Matchy is a high-performance database library for querying IP addresses, CIDR ranges, and glob patterns with rich associated data. Perfect for threat intelligence, GeoIP, domain categorization, and network security applications.

§Quick Start - Unified Database

use matchy::{Database, DatabaseBuilder, MatchMode, DataValue};
use std::collections::HashMap;

// Build a database with both IP and pattern entries
let mut builder = DatabaseBuilder::new(MatchMode::CaseSensitive);

// Add IP address
let mut data = HashMap::new();
data.insert("threat_level".to_string(), DataValue::String("high".to_string()));
builder.add_entry("1.2.3.4", data)?;

// Add pattern
let mut data = HashMap::new();
data.insert("category".to_string(), DataValue::String("malware".to_string()));
builder.add_entry("*.evil.com", data)?;

// Build and save
let db_bytes = builder.build()?;

// Query the database
let db = Database::from("threats.db").open()?;

// Automatic IP detection
if let Some(result) = db.lookup("1.2.3.4")? {
    println!("Found: {:?}", result);
}

// Automatic pattern matching
if let Some(result) = db.lookup("malware.evil.com")? {
    println!("Matches pattern: {:?}", result);
}

§Key Features

  • Unified Queries: Automatically detects IP addresses vs patterns
  • Rich Data: Store JSON-like structured data with each entry
  • Zero-Copy Loading: Memory-mapped files load instantly (~1ms)
  • MMDB Compatible: Drop-in replacement for libmaxminddb
  • Shared Memory: Multiple processes share physical RAM
  • C/C++ API: Stable FFI for any language
  • Fast Lookups: O(log n) for IPs, O(n) for patterns

§Architecture

Matchy uses a hybrid binary format combining IP tree structures with pattern matching automata:

┌──────────────────────────────────────┐
│  Database File Format                │
├──────────────────────────────────────┤
│  1. IP Search Tree (binary trie)     │
│  2. Data Section (deduplicated)      │
│  3. Pattern Matcher (Aho-Corasick)   │
│  4. Metadata                         │
└──────────────────────────────────────┘
         ↓ mmap() syscall (~1ms)
┌──────────────────────────────────────┐
│  Memory (read-only, shared)          │
│  Ready for queries immediately!      │
└──────────────────────────────────────┘

Re-exports§

pub use crate::database::Database;
pub use crate::database::DatabaseError;
pub use crate::database::DatabaseOpener;
pub use crate::database::DatabaseOptions;
pub use crate::database::DatabaseStats;
pub use crate::database::LookupRef;
pub use crate::database::QueryResult;
pub use crate::database::ReloadEvent;
pub use crate::database::ReloadSource;
pub use crate::error::MatchyError;
pub use crate::error::Result;
pub use crate::schema_validation::SchemaError;
pub use crate::schema_validation::SchemaValidationError;
pub use crate::schema_validation::SchemaValidator;
pub use crate::schema_validation::ValidationErrorDetail;
pub use matchy_extractor as extractor;

Modules§

c_api
C API for Matchy
database
Unified database API Unified Database API
error
Error types for Paraglob operations Error types for the matchy library
file_reader
File reading utilities with automatic gzip decompression Streaming file reader with automatic gzip decompression
misp_importer
MISP JSON threat intelligence importer MISP JSON Threat Intelligence Importer
processing
Batch processing infrastructure for efficient file analysis
schema_validation
Schema validation for yield values
schemas
Built-in database schemas for yield value validation
simd_utils
SIMD-accelerated utilities for pattern matching
updater
Live database with automatic file watching and optional network updates (native only) Live database update support.
validation
Database validation for untrusted files

Structs§

DatabaseBuilder
Unified database builder for creating databases with IP addresses and patterns

Enums§

DataValue
Data value type for database entries Data value that can be stored in the data section
EntryType
Entry type classification for database builder
FormatError
Errors that can occur during database format operations
MatchMode
Match mode for text operations (case sensitive/insensitive) Match mode for text matching operations.
ParaglobError
Main error type for paraglob operations

Constants§

MATCHY_VERSION
Library version string
MATCHY_VERSION_MAJOR
Library major version
MATCHY_VERSION_MINOR
Library minor version
MATCHY_VERSION_PATCH
Library patch version

Traits§

DatabaseBuilderExt
Extension trait for adding schema validation to DatabaseBuilder
EntryValidator
Trait for custom entry validation