Qubit MIME

MIME type detection utilities for Rust services based on filename glob rules and content magic rules.

Overview

Qubit MIME is a repository-backed MIME type detector for Rust. It uses the same freedesktop shared MIME-info data model as the Java common-mime module: canonical MIME type names, aliases, localized comments, filename globs, content magic rules, and super-type relationships.

The crate follows the Java common-mime design while exposing idiomatic Rust types. Its public surface is organized into three layers:

MimeDetector: the top-level detector trait, equivalent to the Java MimeDetector interface. Use it when code should work with any detector implementation.
detector: Java-style detector implementations and shared detector logic, including AbstractMimeDetector, RepositoryMimeDetector, FileCommandMimeDetector, StreamBasedMimeDetector, and FileBasedMimeDetector.
MediaStreamClassifier: the top-level media stream classifier trait, equivalent to the Java MediaStreamClassifier interface. The classifier module provides FfprobeCommandMediaStreamClassifier, AbstractMediaStreamClassifier, and file-based classifier helpers.
MimeRepository: the lower-level repository returning MimeType metadata and all matching candidates when callers need richer inspection.

Design Goals

Java parity: follow the behavior and database model of the Java common-mime implementation.
Practical defaults: ship with an embedded freedesktop MIME database.
Filename and content detection: support glob-based and magic-based detection, independently or together.
Detector and classifier hierarchy: mirror the Java detector/classifier split while keeping Rust ownership and error handling.
Predictable conflict resolution: prefer higher glob weights, longer glob patterns, and higher magic priorities.
Rust-friendly API: use borrowed repositories, concrete errors, and standard Read + Seek based detection.
Small dependency surface: keep runtime dependencies focused and stable.

Features

Filename Detection

Literal, extension, and general glob matching.
Case-insensitive matching by default, with support for case-sensitive globs.
Conflict resolution by glob weight and pattern length.
Path-safe detection that only uses the final filename component.

Content Magic Detection

Freedesktop magic value types: string, byte, host16, host32, big16, big32, little16, and little32.
Offset ranges such as 0 and 0:1024.
Optional masks for binary magic values.
Nested magic matchers.
Conflict resolution by magic priority.

Repository Metadata

Canonical names and aliases.
Localized comments and descriptions.
Preferred and complete filename extension lookup.
Super-type metadata parsed from sub-class-of entries.
Maximum byte count required by magic rules.

Detection Entrypoints

Top-level trait: MimeDetector.
Repository detector: RepositoryMimeDetector.
System command detector: FileCommandMimeDetector.
Filename only: detect_by_filename.
Content only: detect_by_content.
Combined filename and bytes: detect or detect_bytes.
Combined filename and reader: detect_reader.
Filesystem path: detect_path.

Media Stream Classification

Top-level trait: MediaStreamClassifier.
Stream result enum: MediaStreamType.
FFprobe-backed implementation: FfprobeCommandMediaStreamClassifier.
Precise refinement for ambiguous media types such as WebM and Ogg when a classifier is configured on AbstractMimeDetector.

Installation

Add this to your Cargo.toml:

[dependencies]
qubit-mime = "0.2"

Quick Start

Detect from filename and content

use qubit_mime::{
    MimeError,
    MimeDetectionPolicy,
    RepositoryMimeDetector,
};

fn main() -> Result<(), MimeError> {
    let detector = RepositoryMimeDetector::new()?;

    let by_name = detector.detect_by_filename("photo.JPG");
    assert_eq!(Some("image/jpeg".to_owned()), by_name);

    let by_content = detector.detect_by_content(b"%PDF-1.7\n");
    assert_eq!(Some("application/pdf".to_owned()), by_content);

    let combined = detector.detect_bytes(
        b"%PDF-1.7\n",
        Some("report.pdf"),
        MimeDetectionPolicy::VerifyContent,
    );
    assert_eq!(Some("application/pdf".to_owned()), combined);

    Ok(())
}

Use the Rust-style `MimeDetector` trait

BoxMimeDetector and ArcMimeDetector provide explicit boxed and shared default detector containers selected from MimeConfig. Code that only needs MIME names can depend on the trait instead of a concrete detector.

use qubit_mime::{
    BoxMimeDetector,
    MimeDetectionPolicy,
    MimeDetector,
};

fn detect_upload(detector: &dyn MimeDetector, filename: &str, content: &[u8]) -> Option<String> {
    detector.detect(content, Some(filename), MimeDetectionPolicy::VerifyContent)
}

fn main() {
    let detector = BoxMimeDetector::default();

    assert_eq!(
        Some("application/pdf".to_owned()),
        detect_upload(detector.as_ref(), "upload.bin", b"%PDF-1.7\n"),
    );
}

Configure global defaults with `Config`

MimeConfig::default() returns a snapshot of the current global default MIME configuration. Use MimeConfig::reload_default() to replace it from an rs-config Config, or MimeConfig::reload_default_from_env() to load from Config::from_env().

use qubit_config::Config;
use qubit_mime::{
    BoxMimeDetector,
    CONFIG_MEDIA_STREAM_CLASSIFIER_DEFAULT,
    CONFIG_MIME_AMBIGUOUS_MIME_MAPPING,
    CONFIG_MIME_DETECTOR_DEFAULT,
    CONFIG_MIME_ENABLE_PRECISE_DETECTION,
    CONFIG_MIME_PRECISE_DETECTION_PATTERNS,
    DEFAULT_AMBIGUOUS_MIME_MAPPING,
    DEFAULT_PRECISE_DETECTION_PATTERNS,
    MimeConfig,
    MimeDetector,
    MimeError,
};

fn main() -> Result<(), MimeError> {
    let original = MimeConfig::default();
    let mut config = Config::new();
    config.set(CONFIG_MIME_DETECTOR_DEFAULT, "repository")?;
    config.set(CONFIG_MEDIA_STREAM_CLASSIFIER_DEFAULT, "ffprobe")?;
    config.set(CONFIG_MIME_ENABLE_PRECISE_DETECTION, true)?;
    config.set(CONFIG_MIME_PRECISE_DETECTION_PATTERNS, DEFAULT_PRECISE_DETECTION_PATTERNS)?;
    config.set(CONFIG_MIME_AMBIGUOUS_MIME_MAPPING, DEFAULT_AMBIGUOUS_MIME_MAPPING)?;

    MimeConfig::reload_default(&config)?;
    let detector = BoxMimeDetector::default();

    assert_eq!(
        Some("application/pdf".to_owned()),
        detector.detect_by_filename("document.pdf"),
    );

    MimeConfig::set_default(original);
    Ok(())
}

Detect a filesystem path

use qubit_mime::{
    MimeDetectionPolicy,
    MimeError,
    RepositoryMimeDetector,
};

fn main() -> Result<(), MimeError> {
    let detector = RepositoryMimeDetector::new()?;
    let path = std::env::temp_dir().join("qubit-mime-example.pdf");

    std::fs::write(&path, b"%PDF-1.7\n")?;
    let detected = detector.detect_path(&path, MimeDetectionPolicy::VerifyContent)?;
    std::fs::remove_file(&path).ok();

    assert_eq!(Some("application/pdf".to_owned()), detected);
    Ok(())
}

Use the system `file` command detector

FileCommandMimeDetector mirrors the Java file-command detector. It uses the embedded repository for filename candidates and file --mime-type --brief for content detection.

use std::time::Duration;

use qubit_command::CommandRunner;
use qubit_mime::{
    FileCommandMimeDetector,
    MimeDetectionPolicy,
    MimeDetector,
    MimeError,
};

fn main() -> Result<(), MimeError> {
    if !FileCommandMimeDetector::is_available() {
        return Ok(());
    }

    let detector = FileCommandMimeDetector::new();
    let detected = detector.detect(
        b"%PDF-1.7\n",
        Some("report.bin"),
        MimeDetectionPolicy::VerifyContent,
    );

    assert_eq!(Some("application/pdf".to_owned()), detected);

    let runner = CommandRunner::new()
        .timeout(Duration::from_secs(2))
        .disable_logging(true)
        .lossy_output(true);
    let detector = FileCommandMimeDetector::new().with_command_runner(runner);
    assert!(detector.command_runner().configured_timeout().is_some());

    Ok(())
}

Classify media streams with FFprobe

FfprobeCommandMediaStreamClassifier mirrors the Java FFprobe classifier. It classifies a media file as no media, audio-only, video-only, or video with audio.

use std::path::Path;

use qubit_mime::{
    FfprobeCommandMediaStreamClassifier,
    MediaStreamClassifier,
    MediaStreamType,
    MimeError,
};

fn main() -> Result<(), MimeError> {
    if !FfprobeCommandMediaStreamClassifier::is_available() {
        return Ok(());
    }

    let classifier = FfprobeCommandMediaStreamClassifier::new();
    let stream_type = classifier.classify_file(Path::new("sample.webm"))?;

    assert!(matches!(
        stream_type,
        MediaStreamType::AudioOnly
            | MediaStreamType::VideoOnly
            | MediaStreamType::VideoWithAudio
            | MediaStreamType::None,
    ));
    Ok(())
}

Detect from a seekable reader

detect_reader reads up to the repository's required magic byte count and then restores the original stream position.

use std::io::{
    Cursor,
    Seek,
};

use qubit_mime::{
    MimeDetectionPolicy,
    MimeError,
    RepositoryMimeDetector,
};

fn main() -> Result<(), MimeError> {
    let detector = RepositoryMimeDetector::new()?;
    let mut reader = Cursor::new(b"%PDF-1.7\npayload".to_vec());

    let detected = detector.detect_reader(
        &mut reader,
        Some("document.bin"),
        MimeDetectionPolicy::VerifyContent,
    )?;
    assert_eq!(Some("application/pdf".to_owned()), detected);
    assert_eq!(0, reader.stream_position()?);

    Ok(())
}

Combined Detection Strategy

Combined detection accepts both a filename and content bytes. The MimeDetectionPolicy value makes the filename/content resolution strategy explicit at each call site.

use qubit_mime::{
    MimeDetectionPolicy,
    MimeError,
    RepositoryMimeDetector,
};

fn main() -> Result<(), MimeError> {
    let detector = RepositoryMimeDetector::new()?;
    let pdf_bytes = b"%PDF-1.7\n";

    // Prefer a definitive filename result and avoid extra content inspection.
    let by_filename = detector.detect_bytes(
        pdf_bytes,
        Some("photo.jpg"),
        MimeDetectionPolicy::PreferFilename,
    );
    assert_eq!(Some("image/jpeg".to_owned()), by_filename);

    // Verify content magic when content is more authoritative.
    let by_magic = detector.detect_bytes(
        pdf_bytes,
        Some("photo.jpg"),
        MimeDetectionPolicy::VerifyContent,
    );
    assert_eq!(Some("application/pdf".to_owned()), by_magic);

    Ok(())
}

Use MimeDetectionPolicy::PreferFilename when filenames come from a trusted source and you want less I/O. Use MimeDetectionPolicy::VerifyContent when uploaded or user-controlled filenames may be wrong or misleading.

Repository Metadata

The default detector exposes the parsed repository. Use it when you need metadata instead of just a MIME name.

use qubit_mime::{
    MimeError,
    RepositoryMimeDetector,
};

fn main() -> Result<(), MimeError> {
    let detector = RepositoryMimeDetector::new()?;
    let repository = detector.repository();

    let png = repository
        .get("image/png")
        .expect("default repository should contain image/png");

    assert_eq!("image/png", png.name());
    assert_eq!(Some("png"), png.preferred_extension());
    assert!(png.description().is_some());
    assert!(png.matches_filename("ICON.PNG"));

    let extensions = png.all_extensions();
    assert!(extensions.contains(&"png"));

    Ok(())
}

MimeRepository::detect_by_filename and MimeRepository::detect_by_content return all best candidates instead of a single string:

use qubit_mime::{
    MimeError,
    RepositoryMimeDetector,
};

fn main() -> Result<(), MimeError> {
    let detector = RepositoryMimeDetector::new()?;
    let repository = detector.repository();

    let candidates = repository.detect_by_filename("archive.tar.gz");
    assert!(!candidates.is_empty());

    for candidate in candidates {
        println!("{} {:?}", candidate.name(), candidate.description());
    }

    Ok(())
}

Custom Repository

Use MimeRepository::from_xml when you need a small test repository, a product specific MIME database, or a database generated from another source.

use qubit_mime::{
    MimeError,
    MimeRepository,
    RepositoryMimeDetector,
};

fn main() -> Result<(), MimeError> {
    let xml = r#"
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
  <mime-type type="application/x-example">
    <comment>Example bundle</comment>
    <alias type="application/example"/>
    <glob pattern="*.example" weight="80"/>
    <magic priority="90">
      <match type="string" value="EXAMPLE" offset="0"/>
    </magic>
  </mime-type>
</mime-info>
"#;

    let repository = MimeRepository::from_xml(xml)?;
    let detector = RepositoryMimeDetector::with_repository(&repository);

    assert_eq!(
        Some("application/x-example".to_owned()),
        detector.detect_by_filename("demo.example"),
    );
    assert_eq!(
        Some("application/x-example".to_owned()),
        detector.detect_by_content(b"EXAMPLE payload"),
    );

    let mime_type = repository
        .get("application/example")
        .expect("alias should resolve to the canonical MIME type");
    assert_eq!("application/x-example", mime_type.name());
    assert_eq!(Some("example"), mime_type.preferred_extension());

    Ok(())
}

Low-Level Rule Types

The low-level types are useful in tests and integrations that need to inspect or validate MIME rules directly.

use qubit_mime::{
    MagicValueType,
    MimeError,
    MimeGlob,
    MimeMagic,
    MimeMagicMatcher,
    MimeType,
};

fn main() -> Result<(), MimeError> {
    let glob = MimeGlob::new("*.png", MimeGlob::DEFAULT_WEIGHT, false)?;
    assert!(glob.matches("ICON.PNG"));

    let matcher = MimeMagicMatcher::new(
        MagicValueType::String,
        0,
        0,
        b"\x89PNG\r\n\x1a\n".to_vec(),
        None,
        vec![],
    )?;
    let magic = MimeMagic::new(80, vec![matcher]);

    let png = MimeType::builder("image/png")
        .description("en", "PNG image")
        .alias("image/x-png")
        .glob(glob)
        .magic(magic)
        .build();

    assert_eq!("image/png", png.name());
    assert_eq!(Some("png"), png.preferred_extension());
    assert!(png.matches_filename("icon.png"));
    assert!(png.magics()[0].matches(b"\x89PNG\r\n\x1a\npayload"));

    Ok(())
}

API Reference

`MimeDetector`

Method	Description
`BoxMimeDetector::default()`	Select the configured/default boxed detector
`BoxMimeDetector::from_name(name)`	Select a boxed detector by implementation name
`BoxMimeDetector::from_mime_config(config)`	Select a boxed detector from explicit MIME configuration
`ArcMimeDetector::default()`	Select the configured/default shared detector
`ArcMimeDetector::from_name(name)`	Select a shared detector by implementation name
`ArcMimeDetector::from_mime_config(config)`	Select a shared detector from explicit MIME configuration
`detect_by_filename(filename)`	Detect one MIME name from filename
`detect_by_content(bytes)`	Detect one MIME name from content bytes
`detect(bytes, filename, policy)`	Detect from bytes and optional filename

`RepositoryMimeDetector`

Method	Description
`new()`	Create a detector backed by the embedded freedesktop repository
`with_repository(repository)`	Create a detector borrowing an explicit repository
`with_repository_and_config(repository, config)`	Create a detector borrowing an explicit repository and MIME configuration
`repository()`	Borrow the underlying repository
`detect_by_filename(filename)`	Return the first MIME name matched by filename
`detect_by_content(bytes)`	Return the first MIME name matched by content magic
`detect_bytes(bytes, filename, policy)`	Detect from bytes and optional filename
`detect_reader(reader, filename, policy)`	Detect from a `Read + Seek` reader and restore its position
`detect_path(path, policy)`	Open and detect a filesystem path

`FileCommandMimeDetector`

Method	Description
`new()`	Create a detector backed by the embedded repository and the system `file` command
`with_repository(repository)`	Create a detector borrowing an explicit repository
`with_repository_and_runner(repository, runner)`	Create a detector with an explicit `qubit_command::CommandRunner`
`with_repository_runner_and_config(repository, runner, config)`	Create a detector with explicit repository, runner, and MIME configuration
`command_runner()`	Borrow the runner used for command execution
`set_command_runner(runner)`	Replace the runner used for command execution
`is_available()`	Check whether the `file` command can be executed
`detect_path_by_content(path)`	Detect a local file using command output only
`detect_path(path, policy)`	Detect a path by filename and command-backed content inspection
`detect_reader(reader, filename, policy)`	Detect a seekable reader through the file-backed path
`set_execution_timeout(timeout)`	Configure the runner timeout for `file` commands
`set_working_directory(directory)`	Configure the runner working directory
`set_disable_logging(value)`	Configure command runner logging

`MediaStreamClassifier`

Method	Description
`BoxMediaStreamClassifier::default()`	Select the configured/default boxed classifier
`BoxMediaStreamClassifier::from_name(name)`	Select a boxed classifier by implementation name
`BoxMediaStreamClassifier::from_mime_config(config)`	Select a boxed classifier from explicit MIME configuration
`ArcMediaStreamClassifier::default()`	Select the configured/default shared classifier
`ArcMediaStreamClassifier::from_name(name)`	Select a shared classifier by implementation name
`ArcMediaStreamClassifier::from_mime_config(config)`	Select a shared classifier from explicit MIME configuration
`classify_file(file)`	Classify a local media file
`classify_content(bytes)`	Classify in-memory media content

`FfprobeCommandMediaStreamClassifier`

Method	Description
`new()`	Create an FFprobe-backed classifier
`is_available()`	Check whether `ffprobe` can be executed
`classify_stream_listing(output)`	Classify parsed FFprobe `codec_type` output
`set_execution_timeout(timeout)`	Store the Java-compatible command timeout setting
`set_working_directory(directory)`	Set the command working directory
`set_disable_logging(value)`	Store the Java-compatible disable-logging flag

`MimeRepository`

Method	Description
`from_xml(xml)`	Parse a freedesktop shared MIME-info XML document
`empty()`	Create an empty repository
`all()`	Return all parsed MIME types in database order
`get(name)`	Resolve a canonical MIME name or alias
`max_test_bytes()`	Return the maximum byte prefix needed by magic rules
`detect_by_filename(filename)`	Return best filename candidates
`detect_by_content(bytes)`	Return best content candidates
`detect(filename, bytes, policy)`	Merge filename and content detection

Metadata and Rule Types

Type	Purpose
`MimeType`	Metadata and rules for one MIME type
`MimeTypeBuilder`	Builder for standalone `MimeType` values
`MimeGlob`	Filename glob rule with weight and case-sensitivity
`MimeMagic`	Priority-ranked collection of magic matchers
`MimeMagicMatcher`	One magic matcher with offset, value, mask, and children
`MagicValueType`	Freedesktop magic value type enum
`MediaStreamType`	Audio/video stream classification result
`MimeConfig`	Precise detection and ambiguous media mapping configuration
`MimeError`	Error type for XML parsing, rule validation, and I/O

`MimeConfig`

Method	Description
`new(detector, classifier, enabled, patterns, mapping)`	Create explicit MIME configuration
`from_config(config)`	Parse MIME configuration from a `qubit_config::Config`
`from_env()`	Parse MIME configuration from `Config::from_env()`
`default()`	Clone the current global default MIME configuration
`set_default(config)`	Replace the global default used by future default instances
`reload_default(config)`	Parse and replace the global default from a `Config`
`reload_default_from_env()`	Parse and replace the global default from process environment
`mime_detector_default()`	Read the configured detector selector
`media_stream_classifier_default()`	Read the configured media classifier selector

Module Layout

The source layout intentionally mirrors the Java implementation:

src/
  mime_detector.rs              # top-level MimeDetector trait
  mime_config.rs                # precise detection configuration
  detector/                     # detector implementations
  classifier/                   # media stream classifier interface and implementations
  repository/                   # MIME database, glob, magic, and metadata types

Use the root re-exports for normal application code. Use the nested modules when you need to inspect or extend a specific detector, classifier, or repository component.

Detection Rules

Filename Rules

Filename detection uses only the final path component. Matches are ranked by:

Higher glob weight.
Longer glob pattern when weights tie.
Database order when the repository returns multiple equal candidates.

Content Rules

Content detection checks the provided byte prefix against each MIME type's direct magic rules. Matches are ranked by higher magic priority. Use repository.max_test_bytes() to know the largest useful prefix length for a repository.

Combined Rules

Combined detection first evaluates filename globs. When there is exactly one filename match and magic checking is not forced, that filename match is used. Otherwise, content magic is evaluated and merged with filename candidates.

Comparison with Java `common-mime`

Aspect	Java `common-mime`	Qubit MIME
Database model	Freedesktop shared MIME-info	Same model
Filename detection	Glob rules	Glob rules
Content detection	Magic rules	Magic rules
Alias lookup	Supported	Supported
Detector interface	`MimeDetector`	`MimeDetector` trait
Media stream classifier	`MediaStreamClassifier`	`MediaStreamClassifier` trait
Repository detector	`RepositoryMimeDetector`	`RepositoryMimeDetector`
File command detector	`FileCommandMimeDetector`	`FileCommandMimeDetector`
FFprobe classifier	`FfprobeCommandMediaStreamClassifier`	`FfprobeCommandMediaStreamClassifier`
Repository loading	XML resource	Embedded XML or explicit XML
Return style	Java objects and collections	Rust `Option`, slices, and vectors
Errors	Java exceptions	Concrete `MimeError`

Testing & Code Coverage

This project keeps tests under tests/ and validates repository parsing, filename matching, content magic matching, reader/path detection, and coverage thresholds.

Running Tests

# Run all tests
cargo test

# Generate a coverage report
./coverage.sh

# Generate a text format coverage report
./coverage.sh text

# Run CI checks (format, clippy, tests, docs, coverage, audit)
./ci-check.sh

Dependencies

Runtime dependencies are intentionally small:

qubit-command runs external file commands with timeout and output capture.
qubit-config loads MIME defaults from configuration objects and environment.
regex compiles and runs filename glob matchers.
roxmltree parses shared MIME-info XML.
thiserror provides the concrete MimeError implementation.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See LICENSE for the full license text.

Contributing

Contributions are welcome. Please keep changes aligned with the existing Rust project structure and run ./ci-check.sh before opening a pull request.

Author

Haixing Hu - Qubit Co. Ltd.

Related Projects

More Rust libraries from Qubit are published under the qubit-ltd GitHub organization.

Repository: https://github.com/qubit-ltd/rs-mime

qubit-mime 0.2.0

Qubit MIME

Overview

Design Goals

Features

Filename Detection

Content Magic Detection

Repository Metadata

Detection Entrypoints

Media Stream Classification

Installation

Quick Start

Detect from filename and content

Use the Rust-style MimeDetector trait

Configure global defaults with Config

Detect a filesystem path

Use the system file command detector

Classify media streams with FFprobe

Detect from a seekable reader

Combined Detection Strategy

Repository Metadata

Custom Repository

Low-Level Rule Types

API Reference

MimeDetector

RepositoryMimeDetector

FileCommandMimeDetector

MediaStreamClassifier

FfprobeCommandMediaStreamClassifier

MimeRepository

Metadata and Rule Types

MimeConfig

Module Layout

Detection Rules

Filename Rules

Content Rules

Combined Rules

Comparison with Java common-mime

Testing & Code Coverage

Running Tests

Dependencies

License

Contributing

Author

Related Projects

Use the Rust-style `MimeDetector` trait

Configure global defaults with `Config`

Use the system `file` command detector

`MimeDetector`

`RepositoryMimeDetector`

`FileCommandMimeDetector`

`MediaStreamClassifier`

`FfprobeCommandMediaStreamClassifier`

`MimeRepository`

`MimeConfig`

Comparison with Java `common-mime`