bare_types/lib.rs
1//! # bare-types
2//!
3//! A zero-cost foundation for type-safe domain modeling in Rust.
4//!
5//! ## Overview
6//!
7//! `bare-types` provides strongly-typed, zero-cost abstractions for domain modeling in Rust.
8//! It implements the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) and follows strict design principles to ensure
9//! type safety, performance, and correctness.
10//!
11//! ## Design Philosophy
12//!
13//! ### Parse, Don't Validate
14//!
15//! This project follows the "Parse, don't validate" philosophy. Instead of validating data throughout your codebase,
16//! parse it once at the system boundary and use strong types to ensure invariants are maintained.
17//!
18//! This approach provides:
19//! - **Type safety**: Invalid states are unrepresentable
20//! - **Zero-cost abstractions**: Validation happens once at construction
21//! - **Clear error handling**: Errors are caught early and explicitly
22//! - **Self-documenting code**: Types convey meaning
23//!
24//! ## Design Rules
25//!
26//! This project adheres to the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) and implements the following design rules:
27//!
28//! ### 1. Type Safety (C-NEWTYPE, C-CUSTOM-TYPE)
29//!
30//! - Use newtype pattern to provide static distinctions between types (C-NEWTYPE)
31//! - Arguments convey meaning through types, not `bool` or `Option` (C-CUSTOM-TYPE)
32//! - All validation is performed at construction time
33//! - Invalid states are unrepresentable
34//!
35//! ### 2. Zero-Cost Abstractions
36//!
37//! - All validation is performed at compile time or construction time
38//! - No runtime cost for accessing validated data
39//! - Use `#[repr(transparent)]` for newtypes over primitive types
40//! - Memory layout matches underlying types
41//!
42//! ### 3. RFC Compliance
43//!
44//! Strictly follow relevant standards:
45//! - Domain names: RFC 1035
46//! - Hostnames: RFC 1123
47//! - IP addresses: Standard IPv4/IPv6
48//!
49//! ### 4. Composability (C-COMMON-TRAITS, C-CONV-TRAITS)
50//!
51//! All types implement standard traits for easy composition:
52//! - **Common traits** (C-COMMON-TRAITS): `Debug`, `Clone`, `Display`, `Hash`, `Eq`, `PartialEq`, `Ord`, `PartialOrd`, `Default`
53//! - **Conversion traits** (C-CONV-TRAITS): `From`, `TryFrom`, `AsRef`, `AsMut` (NOT `Into` or `TryInto`)
54//! - **Collection traits** (C-COLLECT): `FromIterator`, `Extend` (for collection types)
55//!
56//! ### 5. Security (C-SEND-SYNC, C-GOOD-ERR)
57//!
58//! - Types are `Send` and `Sync` where possible (C-SEND-SYNC)
59//! - Error types implement `std::error::Error`, `Send`, `Sync` (C-GOOD-ERR)
60//! - No unsafe code allowed (`unsafe_code = "forbid"`)
61//! - Sensitive data uses `Zeroize` for automatic memory clearing
62//!
63//! ### 6. Explicit Over Implicit (C-DEREF, C-CTOR)
64//!
65//! - Only smart pointers implement `Deref` and `DerefMut` (C-DEREF)
66//! - Constructors are static, inherent methods (C-CTOR)
67//! - Prefer explicit code over implicit behavior
68//! - No declarative macros except for serde derives
69//!
70//! ### 7. Strict Linting
71//!
72//! The project enforces strict linting rules:
73//! - `unsafe_code = "forbid"`
74//! - `missing_docs = "warn"`
75//! - Deny-level clippy rules for safety and correctness
76//!
77//! ## Design Goals
78//!
79//! ### Performance
80//!
81//! - Zero-cost abstractions for type safety
82//! - Efficient memory usage with optimized data structures
83//! - No runtime overhead for validated types
84//!
85//! ### Portability
86//!
87//! - Cross-platform: Linux, macOS, Windows
88//! - `no_std` support for embedded and WASM
89//! - Minimal dependencies for reduced attack surface
90//!
91//! ### Ergonomics
92//!
93//! - Type-safe APIs prevent common errors
94//! - Clear error messages with detailed context
95//! - Comprehensive documentation with examples
96//! - Follow Rust naming conventions (RFC 430)
97//!
98//! ### Security
99//!
100//! - Memory safety guaranteed by Rust
101//! - Type safety prevents many classes of bugs
102//! - No unsafe code in codebase
103//! - Minimal external dependencies
104//!
105//! ## Features
106//!
107//! - **`std`** - Enable standard library support (default)
108//! - **`net`** - Network-related types (IP addresses, ports, hostnames, etc.)
109//! - **`sys`** - System information types (architecture, OS, versions, etc.)
110//! - **`serde`** - Enable serde serialization/deserialization support
111//! - **`arbitrary`** - Enable arbitrary value generation for fuzzing
112//! - **`zeroize`** - Enable automatic memory clearing for sensitive data
113//!
114//! ## Modules
115//!
116//!//! ### net (requires `net` feature)
117//!
118//! Network-related types for building type-safe network applications:
119//! - IP addresses (IPv4 and IPv6) with validation
120//! - Port numbers with IANA range validation
121//! - Hostnames with RFC 1123 validation
122//! - Domain names with RFC 1035 validation
123//! - Host type unifying IP, domain name, and hostname
124//! - Socket addresses combining host and port
125//! - CIDR notation for IP network prefixes
126//!
127//! ### sys (requires `sys` feature)
128//!
129//! System information types for building type-safe system-level applications:
130//! - CPU architecture (`Arch`) with compile-time detection
131//! - Operating system type (`OsType`) with compile-time detection
132//! - OS version (`OsVersion`) with semantic versioning
133//! - Kernel version (`KernelVersion`) with release strings
134//! - System hostname (`Hostname`) with RFC 1123 validation (re-exported from `net` module)
135//! - System username (`Username`) with POSIX validation
136//! - OS distribution name (`Distro`) with family detection
137//!
138//! ## License
139//!
140//! MIT OR Apache-2.0
141
142#![cfg_attr(docsrs, feature(doc_cfg))]
143#![deny(unsafe_code)]
144#![warn(missing_docs)]
145#![warn(clippy::missing_docs_in_private_items)]
146
147#[cfg(feature = "net")]
148pub mod net;
149
150#[cfg(feature = "sys")]
151pub mod sys;
152
153#[cfg(feature = "std")]
154pub mod prelude;