TypeID Prefix

A Rust library that implements a type-safe version of the TypePrefix section of the TypeID Specification.

Combined with the TypeIdSuffix crate to comprise the mti (Magic Type Id) crate.

Use the mti (Magic Type Id) crate for a holistic implementation of the TypeID specification.

Features

• Type-safe: Ensures that TypeID prefixes conform to the specification.
• Validation: Provides robust validation for TypeID prefixes.
• Sanitization: Offers methods to clean and sanitize input strings into valid TypeID prefixes.
• Zero-cost abstractions: Designed to have minimal runtime overhead.
• Optional tracing: Integrates with the tracing crate for logging (optional feature).

Installation

Add this to your Cargo.toml:

[dependencies]
typeid_prefix = "1.0.0"

To enable tracing support, add:

[dependencies]
typeid_prefix = { version = "1.0.0", features = ["instrument"] }

Usage

Basic Usage

use typeid_prefix::{TypeIdPrefix, Sanitize};
use std::convert::TryFrom;

fn main() {
    // Create a TypeIdPrefix from a valid string
    let prefix = TypeIdPrefix::try_from("user").unwrap();
    println!("Valid prefix: {}", prefix);

    // Attempt to create from an invalid string
    let result = TypeIdPrefix::try_from("Invalid_Prefix");
    assert!(result.is_err());

    // Sanitize an invalid string
    let sanitized = "Invalid_Prefix123".sanitize_and_create();
    println!("Sanitized prefix: {}", sanitized);
}

Validation

The TypeIdPrefix type ensures that all instances conform to the TypeID specification:

• Maximum length of 63 characters
• Contains only lowercase ASCII letters and underscores
• Does not start or end with an underscore
• Starts and ends with a lowercase letter

use typeid_prefix::TypeIdPrefix;
use std::convert::TryFrom;

fn validate_prefix(input: &str) {
    match TypeIdPrefix::try_from(input) {
        Ok(prefix) => println!("Valid prefix: {}", prefix),
        Err(e) => println!("Invalid prefix: {}", e),
    }
}

fn main() {
    validate_prefix("valid_prefix");
    validate_prefix("Invalid_Prefix");
    validate_prefix("_invalid");
    validate_prefix("toolong_toolong_toolong_toolong_toolong_toolong_toolong_toolong");
}

Sanitization

The Sanitize trait provides a method to clean and create a valid TypeIdPrefix from any string:

use typeid_prefix::Sanitize;

fn main() {
    let sanitized = "Invalid String 123!@#".sanitize_and_create();
    println!("Sanitized: {}", sanitized); // Outputs: invalidstring
}

Optional Tracing

When the instrument feature is enabled, the crate will log validation errors using the tracing crate:

[dependencies]
typeid_prefix = { version = "1.0.0", features = ["instrument"] }

use typeid_prefix::Sanitize;

fn main() {
    // Set up your tracing subscriber here
    let _sanitized = "Invalid_Prefix!@#".sanitize_and_create();
    // Validation errors will be logged via tracing
}

Use Cases

• Database Systems: Use TypeIdPrefix to ensure consistent and valid type prefixes for database schemas or ORM mappings.
• API Development: Validate and sanitize user input for API endpoints that require type prefixes.
• Code Generation: Generate valid type prefixes for code generation tools or macros.
• Configuration Management: Ensure configuration keys or identifiers conform to a consistent format.

Safety and Correctness

This crate has been thoroughly tested and verified:

• Comprehensive unit tests
• Property-based testing with proptest
• Fuzz testing
• Formal verification with Kani

These measures ensure that the crate behaves correctly and never panics under normal usage.

Minimum Supported Rust Version (MSRV)

This crate is guaranteed to compile on Rust 1.60.0 and later.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

This crate implements a portion of the TypeID Specification created by Jetpack.io.