sanitize-filename

sanitize-filename is a small Rust crate that strips or replaces characters unsafe for use in filenames — illegal characters (/ ? < > \ : * | "), ASCII/Unicode control characters, path-traversal sequences, and Windows-reserved device names like con or lpt1 — following the same rules as Node’s popular sanitize-filename npm package. It exposes both a simple sanitize() function with sensible defaults and a sanitize_with_options() variant for configuring truncation, Windows-specific handling, and replacement text.

The crate also ships a small companion CLI binary (sanitize-filename) that reads a filename argument or stdin and prints the sanitized result, useful for shell scripts or quick manual cleanup without writing Rust code.

What You Get

• A sanitize(name) function with safe, cross-platform defaults for immediate use
• A sanitize_with_options(name, Options) variant exposing truncate, windows, and replacement configuration
• Automatic truncation to 255 bytes by default to respect common filesystem filename limits
• Windows-reserved-name handling (con, prn, aux, nul, com0-com9, lpt0-lpt9) enabled by default on Windows targets
• A bundled CLI binary that sanitizes a filename argument or piped stdin from the shell

Common Use Cases

• Sanitizing user-uploaded file names before writing them to disk in a web service or file-upload handler
• Cleaning titles or user input before using them to generate export filenames (PDF, CSV, image exports)
• Preventing path-traversal attacks (../../etc/passwd-style names) when constructing file paths from external input
• One-off filename cleanup from shell scripts via the bundled CLI binary

Under The Hood

Architecture - The crate is a single src/lib.rs implementing a character-scanning pass: is_illegal_char() and is_control_char() classify unsafe characters, replace_illegal_or_control_char() performs a copy-on-write scan using Cow<str> to avoid allocating when no replacement is needed, and is_reserved() checks the sanitized result against a static WINDOWS_RESERVED name table. The default sanitize() composes these steps and applies truncation; sanitize_with_options() is the same pipeline parameterized by an Options struct. A separate src/main.rs (58 lines) wraps sanitize_with_options() in a small CLI reading arguments or stdin.

Tech Stack - Pure standard-library Rust (std::borrow::Cow is the only import in the core logic) with zero runtime dependencies for the library itself, targeting the 2021 edition with MSRV 1.80.0. The bundled binary presumably uses a lightweight argument-parsing approach, kept out of the library’s own dependency graph.

Code Quality - Test coverage is minimal — a single #[test] function was found in src/lib.rs covering core sanitization behavior, with no separate integration test suite. The crate has seen low, infrequent activity (22 total commits since 2018, most recent commit October 2025) but the core logic is short, simple, and hasn’t needed frequent changes.

API Design - The API is deliberately minimal: a zero-configuration sanitize() for the common case, and a single Options struct for the three knobs (truncate, windows, replacement) most callers would ever need. Both functions accept anything convertible into a string via Into<Cow<str>>, avoiding forced allocations, and the README documents both the library and CLI usage with runnable one-line examples.