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//! - **`serde`** - Enable serde serialization/deserialization support
110//! - **`arbitrary`** - Enable arbitrary value generation for fuzzing
111//! - **`zeroize`** - Enable automatic memory clearing for sensitive data
112//!
113//! ## Modules
114//!
115//! ### net (requires `net` feature)
116//!
117//! Network-related types for building type-safe network applications.
118//!
119//! ## License
120//!
121//! MIT OR Apache-2.0
122
123#![cfg_attr(docsrs, feature(doc_cfg))]
124#![deny(unsafe_code)]
125#![warn(missing_docs)]
126#![warn(clippy::missing_docs_in_private_items)]
127
128#[cfg(feature = "net")]
129pub mod net;
130
131#[cfg(feature = "sys")]
132pub mod sys;
133
134#[cfg(feature = "std")]
135pub mod prelude;