Rust Plugins - High-Performance Native Extensions

Rust Plugins - High-Performance Native Extensions

!!! success "Production Ready" The Rust plugin system provides 5-10x performance improvements for computationally intensive plugins while maintaining 100% API compatibility with Python plugins.

Overview

ContextForge supports high-performance Rust implementations of plugins through PyO3 bindings. Rust plugins provide significant performance benefits for computationally expensive operations like PII detection, pattern matching, and data transformation, while maintaining a transparent Python interface.

Key Benefits

• 🚀 5-10x Performance: Parallel regex matching, zero-copy operations, and native compilation
• 🔄 Seamless Integration: Automatic fallback to Python when Rust unavailable
• 📦 Zero Breaking Changes: Identical API to Python plugins
• ⚙️ Auto-Detection: Automatically uses Rust when available
• 🛡️ Memory Safe: Rust's ownership system prevents common bugs
• 🔧 Easy Deployment: Single wheel package, no manual compilation needed

Architecture

Hybrid Python + Rust Design

┌─────────────────────────────────────────────────────────┐
│ Python Plugin Layer (plugins/pii_filter/pii_filter.py) │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │ Auto-Detection Logic                             │  │
│  │ - Check MCPGATEWAY_FORCE_PYTHON_PLUGINS          │  │
│  │ - Check Rust availability                        │  │
│  │ - Select implementation                          │  │
│  └──────────────────────────────────────────────────┘  │
│              │                        │                 │
│      ┌───────┴──────┐        ┌───────┴────────┐       │
│      │ Rust Wrapper │        │ Python Fallback│       │
│      │ (5-10x fast) │        │ (Pure Python)  │       │
│      └───────┬──────┘        └────────────────┘       │
└──────────────┼────────────────────────────────────────┘
               │
               │ PyO3 Bindings
               ▼
┌──────────────────────────────────────┐
│ Rust Implementation (plugins_rust/)  │
│                                      │
│  ┌────────────────────────────────┐  │
│  │ PII Detection Engine           │  │
│  │ - RegexSet parallel matching   │  │
│  │ - Zero-copy string ops (Cow)   │  │
│  │ - Efficient nested traversal   │  │
│  └────────────────────────────────┘  │
│                                      │
│  Compiled to: mcpgateway_rust.so    │
└──────────────────────────────────────┘

Available Rust Plugins

PII Filter Plugin (Rust-Accelerated)

The PII Filter plugin is available in both Python and Rust implementations with automatic selection:

Supported PII Types:

• Social Security Numbers (SSN)
• Credit Cards (Visa, Mastercard, Amex, Discover)
• Email Addresses
• Phone Numbers (US/International)
• IP Addresses (IPv4/IPv6)
• Dates of Birth
• Passport Numbers
• Driver's License Numbers
• Bank Account Numbers (including IBAN)
• Medical Record Numbers
• AWS Keys (Access/Secret)
• API Keys

Masking Strategies:

• partial - Show last 4 digits (e.g., ***-**-6789)
• redact - Replace with [REDACTED]
• hash - SHA256 hash prefix (e.g., [HASH:abc123])
• tokenize - UUID-based tokens (e.g., [TOKEN:xyz789])
• remove - Complete removal

Installation

Option 1: Install with Rust Support (Recommended)

# Install with Rust extensions (includes pre-built wheels)
pip install mcpgateway[rust]

# Or install from source with maturin
pip install maturin
cd plugins_rust
maturin develop --release

Option 2: Use Python Fallback

# Standard installation (Python-only)
pip install mcpgateway

# Rust plugins will gracefully fall back to Python implementations

Configuration

Environment Variables

Control which implementation is used:

# Auto-detect (default) - Use Rust if available, Python otherwise
# No configuration needed

# Force Python implementation (for debugging/comparison)
export MCPGATEWAY_FORCE_PYTHON_PLUGINS=true

# Disable Rust preference (will use Python even if Rust available)
export MCPGATEWAY_PREFER_RUST_PLUGINS=false

Plugin Configuration

No changes needed! Rust plugins use the same configuration as Python:

# plugins/config.yaml
plugins:
  - name: "PIIFilterPlugin"
    kind: "plugins.pii_filter.pii_filter.PIIFilterPlugin"
    hooks:
      - "prompt_pre_fetch"
      - "tool_pre_invoke"
      - "tool_post_invoke"
    mode: "enforce"
    priority: 50
    config:
      detect_ssn: true
      detect_credit_card: true
      detect_email: true
      detect_phone: true
      default_mask_strategy: "partial"
      redaction_text: "[REDACTED]"

Usage

Automatic Detection

The plugin system automatically detects and uses the Rust implementation:

from plugins.pii_filter.pii_filter import PIIFilterPlugin
from plugins.framework import PluginConfig

# Create plugin (automatically uses Rust if available)
config = PluginConfig(
    name="pii_filter",
    kind="plugins.pii_filter.pii_filter.PIIFilterPlugin",
    config={}
)
plugin = PIIFilterPlugin(config)

# Check which implementation is being used
print(f"Implementation: {plugin.implementation}")
# Output: "rust" or "python"

Direct API Usage

You can also use the implementations directly:

# Use Rust implementation explicitly
from plugins.pii_filter.pii_filter_rust import RustPIIDetector
from plugins.pii_filter.pii_filter_python import PIIFilterConfig

config = PIIFilterConfig(
    detect_ssn=True,
    detect_email=True,
    default_mask_strategy="partial"
)

detector = RustPIIDetector(config)

# Detect PII
text = "My SSN is 123-45-6789 and email is john@example.com"
detections = detector.detect(text)

# Mask PII
masked = detector.mask(text, detections)
print(masked)
# Output: "My SSN is ***-**-6789 and email is j***n@example.com"

# Process nested structures
data = {
    "user": {
        "ssn": "123-45-6789",
        "email": "alice@example.com"
    }
}
modified, new_data, detections = detector.process_nested(data)

Verification

Check Installation

# Verify Rust plugin is available
python -c "from plugins_rust import PIIDetectorRust; print('✓ Rust PII filter available')"

# Check implementation being used
python -c "
from plugins.pii_filter.pii_filter import PIIFilterPlugin
from plugins.framework import PluginConfig
config = PluginConfig(name='test', kind='test', config={})
plugin = PIIFilterPlugin(config)
print(f'Implementation: {plugin.implementation}')
"

Logging

The gateway logs which implementation is being used:

# With Rust available
INFO - ✓ PII Filter: Using Rust implementation (5-10x faster)

# Without Rust
WARNING - PII Filter: Using Python implementation
WARNING - 💡 Install mcpgateway[rust] for 5-10x better performance

# Forced Python
INFO - PII Filter: Using Python implementation (forced via MCPGATEWAY_FORCE_PYTHON_PLUGINS)

Building from Source

Prerequisites

• Rust 1.70+ (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh)
• Python 3.11+
• maturin (pip install maturin)

Build Steps

# Navigate to Rust plugins directory
cd plugins_rust

# Build in development mode (with debug symbols)
maturin develop

# Build in release mode (optimized)
maturin develop --release

# Build wheel package
maturin build --release

# The wheel will be in plugins_rust/dist/
# Install it: pip install dist/mcpgateway_rust-*.whl

Using Make

# From project root
make rust-dev              # Build and install (development mode)
make rust-build            # Build release wheel
make rust-test             # Run Rust unit tests
make rust-verify           # Verify installation

# From plugins_rust/
make dev                   # Build and install
make test                  # Run tests
make bench                 # Run benchmarks
make bench-compare         # Compare Rust vs Python performance

Performance Benchmarking

Built-in Benchmarks

# Run Rust benchmarks (Criterion)
cd plugins_rust
make bench

# Run Python vs Rust comparison
make bench-compare

# Or from project root
make rust-bench-compare

Sample Benchmark Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PII Filter Performance Comparison: Python vs Rust
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Single SSN Detection
────────────────────────────────────────────────────────────────
Python: 0.150 ms (7.14 MB/s)
Rust:   0.020 ms (53.57 MB/s)
Speedup: 7.5x faster

2. Multiple PII Types Detection
────────────────────────────────────────────────────────────────
Python: 0.300 ms (3.57 MB/s)
Rust:   0.040 ms (26.79 MB/s)
Speedup: 7.5x faster

3. Large Text Performance (1000 PII instances)
────────────────────────────────────────────────────────────────
Python: 150.000 ms (0.71 MB/s)
Rust:   18.000 ms (5.95 MB/s)
Speedup: 8.3x faster

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Average Speedup: 7.8x
✓ GREAT: 5-10x speedup - Recommended for production

Testing

Running Tests

# Rust unit tests
cd plugins_rust
cargo test

# Python integration tests
pytest tests/unit/mcpgateway/plugins/test_pii_filter_rust.py

# Differential tests (Rust vs Python compatibility)
pytest tests/differential/test_pii_filter_differential.py

# Or use make
make rust-test-all         # Run all tests

Test Coverage

The Rust plugin system includes comprehensive testing:

• Rust Unit Tests: 14 tests covering core Rust functionality
• Python Integration Tests: 45 tests covering PyO3 bindings
• Differential Tests: 40+ tests ensuring Rust = Python outputs
• Performance Tests: Benchmarks verifying >5x speedup

Troubleshooting

Rust Plugin Not Available

Symptom: Logs show "Using Python implementation"

Solutions:

# 1. Check if Rust extension is installed
python -c "from plugins_rust import PIIDetectorRust; print('OK')"

# 2. Install with Rust support
pip install mcpgateway[rust]

# 3. Or build from source
cd plugins_rust
maturin develop --release

Import Errors

Symptom: ImportError: cannot import name 'PIIDetectorRust'

Solutions:

# 1. Verify installation
pip list | grep mcpgateway-rust

# 2. Rebuild
cd plugins_rust
maturin develop --release

# 3. Check Python version (requires 3.11+)
python --version

Performance Not Improved

Symptom: No performance difference between Python and Rust

Checks:

# Verify Rust implementation is being used
from plugins.pii_filter.pii_filter import PIIFilterPlugin
plugin = PIIFilterPlugin(config)
assert plugin.implementation == "rust", "Not using Rust!"

# Check environment variables
import os
assert os.getenv("MCPGATEWAY_FORCE_PYTHON_PLUGINS") != "true"

Build Failures

Symptom: maturin develop fails

Common Causes:

1. Rust not installed: Install from https://rustup.rs
2. Wrong Rust version: Update with rustup update
3. Missing dependencies: cargo clean && cargo build
4. Python version mismatch: Ensure Python 3.11+

Development Guide

Creating New Rust Plugins

1. Add Rust Implementation:

# Create new module in plugins_rust/src/
mkdir plugins_rust/src/my_plugin
touch plugins_rust/src/my_plugin/mod.rs

2. Implement PyO3 Bindings:

// plugins_rust/src/my_plugin/mod.rs
use pyo3::prelude::*;

#[pyclass]
pub struct MyPluginRust {
    // Plugin state
}

#[pymethods]
impl MyPluginRust {
    #[new]
    pub fn new(config: &PyDict) -> PyResult<Self> {
        // Initialize from Python config
        Ok(Self { /* ... */ })
    }

    pub fn process(&self, text: &str) -> PyResult<String> {
        // Plugin logic
        Ok(text.to_uppercase())
    }
}

3. Export in lib.rs:

// plugins_rust/src/lib.rs
mod my_plugin;

#[pymodule]
fn plugins_rust(_py: Python, m: &PyModule) -> PyResult<()> {
    m.add_class::<my_plugin::MyPluginRust>()?;
    Ok(())
}

4. Create Python Wrapper:

# plugins/my_plugin/my_plugin_rust.py
from plugins_rust import MyPluginRust

class RustMyPlugin:
    def __init__(self, config):
        self._rust = MyPluginRust(config.model_dump())

    def process(self, text: str) -> str:
        return self._rust.process(text)

5. Add Auto-Detection:

# plugins/my_plugin/my_plugin.py
try:
    from .my_plugin_rust import RustMyPlugin
    RUST_AVAILABLE = True
except ImportError:
    RUST_AVAILABLE = False

class MyPlugin(Plugin):
    def __init__(self, config):
        if RUST_AVAILABLE:
            self.impl = RustMyPlugin(config)
        else:
            self.impl = PythonMyPlugin(config)

Best Practices

1. API Compatibility: Ensure Rust and Python implementations have identical APIs
2. Error Handling: Convert Rust errors to Python exceptions properly
3. Type Conversions: Use PyO3's extract() and IntoPy for seamless conversions
4. Testing: Write differential tests to ensure identical behavior
5. Documentation: Document performance characteristics and trade-offs

CI/CD Integration

GitHub Actions Workflow

The repository includes automated CI/CD for Rust plugins:

# .github/workflows/rust-plugins.yml
- Multi-platform builds (Linux, macOS, Windows)
- Rust linting (clippy, rustfmt)
- Comprehensive testing (unit, integration, differential)
- Performance benchmarking
- Security audits (cargo-audit)
- Code coverage tracking
- Automatic wheel publishing to PyPI

Local CI Checks

# Run full CI pipeline locally
make rust-check            # Format, lint, test
make rust-test-all         # All test suites
make rust-bench            # Performance benchmarks
make rust-audit            # Security audit
make rust-coverage         # Code coverage report

Performance Optimizations

Rust-Specific Optimizations

1. RegexSet for Parallel Matching: All patterns matched in single pass (O(M) vs O(N×M))
2. Copy-on-Write Strings: Zero-copy when no masking needed
3. Stack Allocation: Minimize heap allocations for hot paths
4. Inlining: Aggressive inlining for small functions
5. LTO (Link-Time Optimization): Enabled in release builds

Configuration for Best Performance

# plugins_rust/Cargo.toml
[profile.release]
opt-level = 3              # Maximum optimization
lto = "fat"                # Full link-time optimization
codegen-units = 1          # Better optimization, slower compile
strip = true               # Strip symbols for smaller binary

Security Considerations

Memory Safety

• No Buffer Overflows: Rust's ownership system prevents them at compile-time
• No Use-After-Free: Borrow checker ensures memory safety
• No Data Races: Safe concurrency guarantees
• Input Validation: All Python inputs validated before processing

Audit and Compliance

# Run security audit
cd plugins_rust
cargo audit

# Check dependencies for vulnerabilities
cargo deny check

Future Rust Plugins

Planned Rust implementations:

• Regex Filter: Pattern matching and replacement (5-8x speedup)
• JSON Repair: Fast JSON validation and repair (10x+ speedup)
• SQL Sanitizer: SQL injection detection (8-10x speedup)
• Rate Limiter: High-throughput rate limiting (15x+ speedup)
• Compression: Fast compression/decompression (5-10x speedup)

Resources

Documentation

• PyO3 Documentation
• Rust Book
• Maturin Guide

Project Files

• plugins_rust/README.md - Detailed Rust plugin documentation
• plugins_rust/IMPLEMENTATION_STATUS.md - Implementation status and results
• plugins_rust/BUILD_AND_TEST_RESULTS.md - Build and test report

Community

• GitHub Issues: https://github.com/IBM/mcp-context-forge/issues
• Contributing: See CONTRIBUTING.md

Migration Guide

From Python to Rust

If you have an existing Python plugin you want to optimize:

1. Measure First: Profile to identify bottlenecks
2. Start Small: Convert hot paths first
3. Maintain API: Keep identical interface for drop-in replacement
4. Test Thoroughly: Use differential testing
5. Benchmark: Verify actual performance improvements

Gradual Migration

You don't need to convert entire plugins at once:

class MyPlugin(Plugin):
    def __init__(self, config):
        # Use Rust for expensive operations
        if RUST_AVAILABLE:
            self.detector = RustDetector(config)
        else:
            self.detector = PythonDetector(config)

        # Keep other logic in Python
        self.cache = {}
        self.stats = PluginStats()

    async def process(self, payload, context):
        # Rust-accelerated detection
        results = self.detector.detect(payload.text)

        # Python logic for everything else
        self.update_stats(results)
        return self.format_response(results)

Support

For issues, questions, or contributions related to Rust plugins:

1. Check existing GitHub issues

2. Review build and test documentation

3. Open a new issue with:

   • Rust/Python versions
   • Build logs
   • Error messages
   • Minimal reproduction case

Status: Production Ready Performance: 5-10x faster than Python Compatibility: 100% API compatible Installation: pip install mcpgateway[rust]