ferroni 0.1.0

Ferroni is a line-by-line port of Oniguruma's C source into Rust -- same structure, same function names, same semantics. On top of that foundation, the search pipeline uses SIMD-vectorized scanning (NEON on ARM, SSE2/AVX2 on x86-64) via the memchr crate, making it up to 6x faster than C Oniguruma on full-text search workloads. No bindings, no FFI -- pure Rust.

Why Ferroni?

Security first. C Oniguruma has a history of memory safety CVEs (CVE-2019-13224 CVSS 9.8, CVE-2019-19204, CVE-2019-19246, CVE-2019-19012, CVE-2019-13225) affecting Ruby, PHP, and any application linking against it. Ferroni eliminates buffer overflows, use-after-free, and NULL dereferences structurally through Rust's type system. See ADR-005 for our unsafe policy.

Drop-in behavior. Every regex feature, every opcode, every optimization pass is ported 1:1 from C. If your pattern works in Oniguruma, it works in Ferroni -- verified by 1,695 tests ported directly from the C test suite.

No C toolchain required. Pure cargo build. Cross-compiles to wasm32-unknown-unknown out of the box.

Easy Node.js bindings. Rust's napi-rs ecosystem makes it straightforward to publish a native Node.js module -- no node-gyp, no C compiler on the user's machine.

Quick Start

Add to your Cargo.toml:

[dependencies]
ferroni = { git = "https://github.com/sebastian-software/ferroni.git" }

use ferroni::regcomp::onig_new;
use ferroni::regexec::onig_search;
use ferroni::oniguruma::*;
use ferroni::regsyntax::OnigSyntaxOniguruma;

fn main() {
    let reg = onig_new(
        b"(?<year>\\d{4})-(?<month>\\d{2})-(?<day>\\d{2})",
        ONIG_OPTION_NONE,
        &ferroni::encodings::utf8::ONIG_ENCODING_UTF8,
        &OnigSyntaxOniguruma as *const OnigSyntaxType,
    ).unwrap();

    let input = b"Date: 2026-02-12";
    let (result, region) = onig_search(
        &reg, input, input.len(), input.len(), 0,
        Some(OnigRegion::new()), ONIG_OPTION_NONE,
    );

    let region = region.unwrap();
    assert!(result >= 0);
    assert_eq!(region.beg[0], 6);  // "2026-02-12" starts at byte 6
    assert_eq!(region.end[0], 16);
}

Supported Features

• All Perl/Ruby/Python syntax -- (?:...), (?=...), (?!...), (?<=...), (?<!...), (?>...)
• Named captures -- (?<name>...), (?'name'...), (?P<name>...)
• Backreferences -- \k<name>, \g<name>, relative \g<-1>
• Conditionals -- (?(cond)T|F)
• Absent expressions -- (?~...)
• Unicode properties -- \p{Script_Extensions=Greek}, \p{Lu}, \p{Emoji} (886 names)
• Grapheme clusters -- \X, text segment boundaries \y, \Y
• Callouts -- (?{...}), (*FAIL), (*MAX{n}), (*COUNT), (*CMP)
• 12 syntax modes -- Oniguruma, Ruby, Perl, Perl_NG, Python, Java, Emacs, Grep, GNU, POSIX Basic/Extended, ASIS
• Safety limits -- retry, time, stack, subexp call depth (global + per-search)

Performance

Criterion benchmarks vs. C Oniguruma at -O3 on Apple M1 Ultra. Bold = faster engine. Full tables in the expandable section below.

Highlights

Ferroni wins 29 of 39 execution benchmarks. The SIMD-accelerated forward search is the standout: memchr replaces hand-written byte loops with vectorized scans, delivering 5-6x gains on full-text scanning. See ADR-006.

Compilation is 1.2-1.7x slower (Rust allocates more than C's pre-allocated buffers), but compilation is a one-time cost -- real-world consumers compile patterns once and match millions of times.

Regex Execution

Regex Compilation

Running Benchmarks

cargo bench --features ffi               # full suite (~8 min)
cargo bench --features ffi -- compile    # specific group
cargo bench --features ffi -- "large_"   # pattern filter
# HTML report: target/criterion/report/index.html

Architecture

Each C source file maps 1:1 to a Rust module (ADR-001):

Compilation pipeline (same as C):

onig_new() -> onig_compile()
  -> onig_parse_tree()     (pattern -> AST)
  -> reduce_string_list()  (merge adjacent strings)
  -> tune_tree()           (6 optimization sub-passes)
  -> compile_tree()        (AST -> VM bytecode)
  -> set_optimize_info()   (extract search strategy)

Scope

Ferroni targets ASCII/UTF-8 workloads. The following are intentionally not included:

• 27 of 29 encodings -- only ASCII and UTF-8 (ADR-002)
• POSIX/GNU API -- regcomp/regexec/regfree (ADR-007)
• C memory management -- replaced by Rust's Drop trait
• onig_new_deluxe -- C-specific allocation, use onig_new() instead

Running Tests

# Full UTF-8 suite (requires increased stack for debug builds)
RUST_MIN_STACK=268435456 cargo test --test compat_utf8 -- --test-threads=1

# Other suites
cargo test --test compat_syntax
cargo test --test compat_options
cargo test --test compat_regset
RUST_MIN_STACK=268435456 cargo test --test compat_back -- --test-threads=1

Warning: Never run cargo test -- --ignored -- the conditional_recursion_complex test intentionally hangs.

Architecture Decision Records

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and review the ADRs before submitting a PR.

Acknowledgments

Ferroni is built on the work of K. Kosako and the Oniguruma contributors. The C original powers regex in Ruby, PHP, TextMate, and many other projects.

License

BSD-2-Clause (same as Oniguruma)