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.

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
  • 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

• Add to Cargo.toml:

[dependencies]
magical_rs = "0.0.4"

• Or, use with Cargo package manager:

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), FileKind::Png);
assert_ne!(FileKind::match_types(&header_bytes), FileKind::Unknown);

• Use with with_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 iso_file = "example.iso";
let bytes_max = with_bytes_read();
let wrong_max = DEFAULT_MAX_BYTES_READ;

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

assert_eq!(FileKind::match_types(&header_bytes), FileKind::ISO);
assert_ne!(FileKind::match_types(&header_bytes), FileKind::Unknown);

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

[dependencies.magical_rs]
version = "0.0.6"
default-features = false

Example:

• With DEFAULT_MAX_BYTES_READ:

#![no_std]
use magical_rs::magical::no_std::no_std_bytes_read::DEFAULT_MAX_BYTES_READ;
use magical_rs::magical::no_std::nostd_magic::NoStdFileKind;

const PNG_BYTES: &[u8] = &[
  0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D,
];
let result = NoStdFileKind::no_std_match_with_max_read_rule(PNG_BYTES, DEFAULT_MAX_BYTES_READ);

assert_eq!(result, NoStdFileKind::Png);
assert_ne!(result, NoStdFileKind::Unknown);

• 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);

License

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