magical_rs

A zero-dependency, no_std-friendly Rust crate that detects file types with surgical precision by matching magic bytes at exact offsets — including deep-offset formats like ISO and TAR. Built for speed, safety, and extensibility.

magical_rs is a lightweight, dependency-free Rust crate that detects file types by matching magic bytes (signatures) at specific offsets — including tricky formats like .iso with signatures 32KB into the file.

Infinite Customization with magical_dyn:

• While magical_rs is zero-cost and no_std-friendly by default, it also scales up to full runtime flexibility when you need it.

Enable the magical_dyn feature to unlock:

• Closures as matchers: Define logic inline with |bytes| bytes.starts_with(b"MAGIC").
• Arbitrary return types: Attach any value — strings, structs, enums, configs — as the detection result.
• Dynamic rule tables: Build file type detectors that are defined at runtime, driven by config, plugins, or user input.

No external tools. No bloated dependencies. Just fast, reliable file type detection.

Table of Contents:

• magical_rs
  • Table of Contents:
  • Features
  • Supported File Types
  • How to Install
  • Example
  • No Std Features
  • Dyn Magical Features
  • License

Features

• Zero dependencies — pure Rust, no_std-friendly (with minor tweaks).
• Accurate detection — supports common formats (PNG, JPG, ZIP) and deep-offset types like ISO, RPM, TAR.
• Smart header reading — reads just enough bytes to detect all known types.
• Python-compatible — exposes clean PyO3 bindings for Python interop.
• Fast & safe — uses compile-time constants and safe slicing.
• Extensible — easy to add new signatures.

Supported File Types

How to Install

• With Cargo:

cargo add magical_rs

Example

• With default constant DEFAULT_MAX_BYTES_READ:

use magical_rs::magical::bytes_read::DEFAULT_MAX_BYTES_READ;
use magical_rs::magical::{
        bytes_read::{read_file_header, with_bytes_read},
        magic::FileKind,
};

let png_file = "example.png";
let header_bytes = read_file_header(png_file, DEFAULT_MAX_BYTES_READ).unwrap();

assert_eq!(FileKind::match_types(&header_bytes).unwrap(), FileKind::Png);

• Use with with_bytes_read():

use magical_rs::magical::{
    bytes_read::{read_file_header, with_bytes_read},
    magic::FileKind,
};

let iso_file = "example.iso";

let bytes_max = with_bytes_read();
let header_bytes = read_file_header(iso_file, bytes_max).unwrap();

assert_eq!(FileKind::match_types(&header_bytes).unwrap(), FileKind::ISO);

No Std Features

• magical_rs is designed to be no_std-friendly out of the box. While the default build includes std for convenience (e.g., file I/O utilities), the core detection logic is built on zero-allocation, &[u8]-based matching — making it fully compatible with embedded systems, kernels, WASM, and other constrained environments.

• Zero dependency on std: The core signature matching engine uses only core.
• No heap allocation: All rules are &'static, and matching is done via slicing and comparison.
• const fn-friendly utilities: Helper functions like no_std_max_bytes can be evaluated at compile time.
• Extensible without Vec or Box: Use MagicCustom<K> with &'static data for custom detection logic.

• To use magical_rs in a no_std context, you can use Cargo

cargo add magical_rs --no-default-features

Example:

• With DEFAULT_MAX_BYTES_READ:

#![no_std]
use magical_rs::magical::bytes_read::DEFAULT_MAX_BYTES_READ;
use magical_rs::magical::magic::FileKind;

const PNG_BYTES: &[u8] = &[
  0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D,
];

let result = FileKind::match_with_max_read_rule(PNG_BYTES, DEFAULT_MAX_BYTES_READ).unwrap();

assert_eq!(result, FileKind::Png);

• With customize max bytes read:

#![no_std]
use magical_rs::magical::magic::FileKind;

const PNG_BYTES: &[u8] = &[
  0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D,
];
const MY_MAX_BYTES_READ: usize = 8;
let result = FileKind::match_with_custom_max_read(PNG_BYTES, MY_MAX_BYTES_READ).unwrap();

assert_eq!(result, FileKind::Png);

• With customize signature:

#![no_std]
use magical_rs::magical::magic_custom::{CustomMatchRules, MagicCustom, match_types_custom};

#[derive(Debug, Clone, Copy, PartialEq)]
  enum ShoujuFile {
  MahouShouju,
  Unknown,
}

fn is_shoujo_girl(bytes: &[u8]) -> bool {
  bytes.starts_with(b"MagicalGirl")
}

static SHOUJO_RULE: MagicCustom<ShoujuFile> = MagicCustom {
  signatures: &[],
  offsets: &[],
  max_bytes_read: 2048,
  kind: ShoujuFile::MahouShouju,
  rules: CustomMatchRules::WithFn(is_shoujo_girl),
};

let magical_girl = b"MagicalGirl";
let result = match_types_custom(magical_girl, &[SHOUJO_RULE], ShoujuFile::Unknown);

assert_eq!(result, ShoujuFile::MahouShouju);
assert_ne!(result, ShoujuFile::Unknown);

Dyn Magical Features

Description:

• This crate supports runtime-flexible file type detection via the optional magical_dyn feature.
• Enable it when you need closures, dynamic dispatch, and arbitrary return types — perfect for plugins, config-driven systems, or interactive tools.

Features:

• Closures as matchers: Use inline logic like |bytes| bytes.starts_with(b"MAGIC").
• Arbitrary kind types: Store any type (&str, String, structs, enums, etc.) as the detection result.
• Dynamic downcasting: Recover original types safely using .kind_downcast_ref::<T>().
• Zero-cost when disabled: This feature is off by default and does not affect no_std or performance-critical use cases.

Note:

• Requires std: This feature uses Box<dyn Fn> and Box<dyn Any>, so it only works in std environments.
• Not compatible with no_std: If your target doesn’t have std, do not enable magical_dyn.
• Heap allocation: Uses Box — not suitable for static contexts unless combined with LazyLock.

To use this feature:

• Add with Cargo

cargo add magical-rs --features magical_dyn

Example:

• Dynamic file detection:

use magical_rs::magical::dyn_magic::DynMagicCustom;

let rule_fn = |bytes: &[u8]| bytes.starts_with(b"Shoujo");
let rule = DynMagicCustom::new(rule_fn, "Magical", 32);

assert!(rule.matches(b"Shoujo<3"));
assert!(!rule.matches(b"Not Shoujo Here..."));

use magical_rs::magical::dyn_magic::{DynMagicCustom, match_dyn_types_as};

let rules = vec![
    DynMagicCustom::new(|bytes: &[u8]| bytes.starts_with(b"PNG"), "image/png", 8),
    DynMagicCustom::new(
    |bytes: &[u8]| bytes.starts_with(b"Shoujo"),
    String::from("MagicalGirl"),
    6969,
  ),
];

let data = b"Shoujo";
let result = match_dyn_types_as::<String>(data, &rules).unwrap();

assert_eq!(result, &"MagicalGirl".to_string());

License

• magical_rs is licensed under the GNU General Public License v3.0. See here