bare-types

A zero-cost foundation for type-safe domain modeling in Rust.

Overview

bare-types is a collection of strongly-typed, zero-cost abstractions for domain modeling in Rust. It implements the Rust API Guidelines and follows strict design principles to ensure type safety, performance, and correctness.

Design Philosophy

Parse, Don't Validate

This project follows the "Parse, don't validate" philosophy. Instead of validating data throughout your codebase, parse it once at the system boundary and use strong types to ensure invariants are maintained.

This approach provides:

• Type safety: Invalid states are unrepresentable
• Zero-cost abstractions: Validation happens once at construction
• Clear error handling: Errors are caught early and explicitly
• Self-documenting code: Types convey meaning

Design Rules

This project adheres to the Rust API Guidelines and implements the following design rules:

1. Type Safety (C-NEWTYPE, C-CUSTOM-TYPE)

• Use newtype pattern to provide static distinctions between types
• Arguments convey meaning through types, not bool or Option
• All validation is performed at construction time
• Invalid states are unrepresentable

2. Zero-Cost Abstractions

• All validation is performed at compile time or construction time
• No runtime cost for accessing validated data
• Use #[repr(transparent)] for newtypes over primitive types
• Memory layout matches underlying types

3. RFC Compliance

Strictly follow relevant standards:

• Domain names: RFC 1035
• Hostnames: RFC 1123
• IP addresses: Standard IPv4/IPv6

4. Composability (C-COMMON-TRAITS, C-CONV-TRAITS)

All types implement standard traits for easy composition:

• Common traits: Clone, Debug, Display, Eq, Hash, Ord, PartialEq, PartialOrd
• Conversion traits: From, TryFrom, AsRef, AsMut
  • Note: Into and TryInto are automatically provided via blanket impls when From/TryFrom are implemented
• Collection traits: FromIterator, Extend (for collection types)

5. Security (C-SEND-SYNC, C-GOOD-ERR)

• Types are Send and Sync where possible
• Error types implement std::error::Error, Send, Sync
• No unsafe code allowed (unsafe_code = "forbid")
• Sensitive data uses Zeroize for automatic memory clearing

6. Explicit Over Implicit (C-DEREF, C-CTOR)

• Only smart pointers implement Deref and DerefMut
• Constructors are static, inherent methods
• Prefer explicit code over implicit behavior
• No declarative macros except for serde derives

7. Strict Linting

The project enforces strict linting rules:

• unsafe_code = "forbid"
• missing_docs = "warn"
• Deny-level clippy rules for safety and correctness

Design Goals

1. Performance

Zero-cost abstractions that compile to the same code as raw primitives:

• Validation happens once at construction time
• No runtime overhead for accessing validated data
• #[repr(transparent)] ensures memory layout matches underlying types

2. Portability

Designed for diverse deployment targets:

• Platforms: Linux, macOS, Windows, BSD variants
• Embedded: no_std support for resource-constrained environments
• WebAssembly: Compatible with WASM targets (browser and WASI)
• Dependencies: Minimal external dependencies to reduce attack surface and compile times

3. Ergonomics

Developer experience is a first-class concern:

• Type-safe APIs catch errors at compile time
• Detailed error messages with context for debugging
• Extensive documentation with runnable examples
• Consistent naming following RFC 430
• AI-friendly: Clear constraints and patterns for automated tooling

4. Security

Defense in depth through type safety:

• Memory safety via Rust's ownership system
• Input validation at system boundaries ("Parse, don't validate")
• No unsafe code in the entire codebase
• Optional zeroize integration for sensitive data

Features

All features are additive and composable. You can enable any combination without conflicts.

Default Behavior:

• No features are enabled by default
• All core types work with no_std (using core library)
• Opt-in features provide additional functionality

Available Features:

• std - Enable standard library support
  • Provides: std::error::Error implementations for error types
  • Optional: All core types work without std
• net - Network-related types
  • Includes: IP addresses, ports, hostnames, domain names, socket addresses
  • Built on: core::net (Rust 1.82+), fully no_std compatible
• serde - Serialization support via serde
  • Derives: Serialize and Deserialize for all public types
  • Works with: no_std + alloc or std
• arbitrary - Fuzzing support via arbitrary
  • Enables: Property-based testing and fuzzing workflows
  • Works with: no_std or std
• zeroize - Secure memory clearing via zeroize
  • Provides: Automatic memory zeroing for sensitive data types
  • Works with: no_std or std

no_std Support

This crate is designed for no_std environments by default:

[dependencies]
bare-types = { version = "0.1", default-features = false }

Compatibility Matrix:

Notes:

• net module uses core::net (Rust 1.82+) and is fully no_std compatible
• serde feature requires alloc for owned data types
• std feature is optional and only adds std::error::Error implementations

Modules

net (requires net feature)

Network-related types for building type-safe network applications:

• IP addresses (IPv4 and IPv6) with validation
• Port numbers with IANA range validation
• Hostnames with RFC 1123 validation
• Domain names with RFC 1035 validation
• Host type unifying IP, domain name, and hostname
• Socket addresses combining host and port

sys (requires sys feature)

System information types for building type-safe system-level applications:

• CPU architecture (Arch) with compile-time detection
• Operating system type (OsType) with compile-time detection
• OS version (OsVersion) with semantic versioning
• Kernel version (KernelVersion) with release strings
• System hostname (Hostname) with RFC 1123 validation (re-exported from net module)
• System username (Username) with POSIX validation
• OS distribution name (Distro) with family detection

Getting Started

Add bare-types to your Cargo.toml:

[dependencies]
bare-types = "0.1"

Enable specific features as needed:

[dependencies]
bare-types = { version = "0.1", features = ["net", "serde"] }

Documentation

Full API documentation is available on docs.rs.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Support

Need help? See SUPPORT.md for resources and how to get assistance.

Governance

Learn about project governance and decision-making in GOVERNANCE.md.

Changelog

See CHANGELOG.md for version history.

Security

See SECURITY.md for security policy and vulnerability reporting.

Code of Conduct

This project follows the Rust Code of Conduct.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Related Projects

• bare-config - Type-safe configuration authority
• bare-script - Type-safe scripting authority