1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
//! # bare-types
//!
//! A zero-cost foundation for type-safe domain modeling in Rust.
//!
//! ## Overview
//!
//! `bare-types` provides strongly-typed, zero-cost abstractions for domain modeling in Rust.
//! It implements the [Rust API Guidelines](https://rust-lang.github.io/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](https://rust-lang.github.io/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 (C-NEWTYPE)
//! - Arguments convey meaning through types, not `bool` or `Option` (C-CUSTOM-TYPE)
//! - 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** (C-COMMON-TRAITS): `Debug`, `Clone`, `Display`, `Hash`, `Eq`, `PartialEq`, `Ord`, `PartialOrd`, `Default`
//! - **Conversion traits** (C-CONV-TRAITS): `From`, `TryFrom`, `AsRef`, `AsMut` (NOT `Into` or `TryInto`)
//! - **Collection traits** (C-COLLECT): `FromIterator`, `Extend` (for collection types)
//!
//! ### 5. Security (C-SEND-SYNC, C-GOOD-ERR)
//!
//! - Types are `Send` and `Sync` where possible (C-SEND-SYNC)
//! - Error types implement `std::error::Error`, `Send`, `Sync` (C-GOOD-ERR)
//! - 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` (C-DEREF)
//! - Constructors are static, inherent methods (C-CTOR)
//! - 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
//!
//! ### Performance
//!
//! - Zero-cost abstractions for type safety
//! - Efficient memory usage with optimized data structures
//! - No runtime overhead for validated types
//!
//! ### Portability
//!
//! - Cross-platform: Linux, macOS, Windows
//! - `no_std` support for embedded and WASM
//! - Minimal dependencies for reduced attack surface
//!
//! ### Ergonomics
//!
//! - Type-safe APIs prevent common errors
//! - Clear error messages with detailed context
//! - Comprehensive documentation with examples
//! - Follow Rust naming conventions (RFC 430)
//!
//! ### Security
//!
//! - Memory safety guaranteed by Rust
//! - Type safety prevents many classes of bugs
//! - No unsafe code in codebase
//! - Minimal external dependencies
//!
//! ## Features
//!
//! - **`std`** - Enable standard library support (default)
//! - **`net`** - Network-related types (IP addresses, ports, hostnames, etc.)
//! - **`sys`** - System information types (architecture, OS, versions, etc.)
//! - **`serde`** - Enable serde serialization/deserialization support
//! - **`arbitrary`** - Enable arbitrary value generation for fuzzing
//! - **`zeroize`** - Enable automatic memory clearing for sensitive data
//!
//! ## 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
//! - CIDR notation for IP network prefixes
//!
//! ### 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
//!
//! ## License
//!
//! MIT OR Apache-2.0