bare-types 0.1.8

# bare-types

[![Latest Version](https://img.shields.io/crates/v/bare-types.svg)](https://crates.io/crates/bare-types)
[![Documentation](https://img.shields.io/docsrs/bare-types)](https://docs.rs/bare-types)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE-APACHE)

**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](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

### Why bare-types? Counterexamples

Without proper type abstractions, your code faces several security and reliability risks:

#### 1. Integer Overflow in Port Numbers

```rust
// Without bare-types: Silent overflow, undefined behavior
fn set_port(port: u16) -> u16 {
    port + 1  // Can wrap around to 0!
}

// With bare-types: Compile-time rejection of invalid values
let port: Port = 65536.try_into()?; // ERROR: value out of range
```

#### 2. Invalid Hostnames Leading to DNS Rebinding Attacks

```rust
// Without bare-types: Accepts invalid hostnames that could be exploited
fn connect_to_host(hostname: &str) { /* ... */ }
connect_to_host("-invalid"); // Might bypass security checks

// With bare-types: RFC 1123 validation at construction
let hostname: Hostname = "-invalid".parse()?; // ERROR: Invalid character
```

#### 3. Unvalidated URLs Leading to SSRF Vulnerabilities

```rust
// Without bare-types: URL parsed lazily, vulnerabilities discovered late
let url = request.url(); // May contain malicious schemes or hosts

// With bare-types: URL validated at construction, failures caught immediately
let url: Url = request.url().parse()?; // Fails fast on invalid URLs
```

#### 4. Missing Port Range Validation Leading to Security Misconfigurations

```rust
// Without bare-types: Using privileged ports by accident
fn start_server(port: u16) { /* ... */ }
start_server(22); // Accidentally using SSH port!

// With bare-types: Explicit constants and range checking
let port = Port::SSH; // Compile-time known constant
let custom: Port = 80.try_into()?;
custom.is_system_port(); // true - warns about privileged ports
```

#### 5. Process ID Validation Failures Leading to Signal Injection

```rust
// Without bare-types: Negative PIDs or zero values
fn send_signal(pid: i32, sig: i32) { /* ... */ }
send_signal(-1, 15); // Undefined behavior!
send_signal(0, 15);  // Sends to process group, not self!

// With bare-types: Only valid positive PIDs accepted
let pid: Pid = (-1).try_into()?; // ERROR: must be positive
let pid: Pid = 0.try_into()?;    // ERROR: invalid PID
let pid: Pid = 1234.try_into()?; // OK - valid positive PID
```

By using bare-types, these security vulnerabilities are caught at **compile time** or **at the boundary of your system**, preventing runtime exploitation.

## 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
- 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`](https://serde.rs/)
  - Derives: `Serialize` and `Deserialize` for all public types
  - Works with: `no_std` + `alloc` or `std`
- **`arbitrary`** - Fuzzing support via [`arbitrary`](https://docs.rs/arbitrary/)
  - Enables: Property-based testing and fuzzing workflows
  - Works with: `no_std` or `std`
- **`zeroize`** - Secure memory clearing via [`zeroize`](https://docs.rs/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:

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

**Compatibility Matrix:**

| Feature | `no_std` | `no_std` + `alloc` | `std` |
|---------|----------|-------------------|-------|
| Core types | ✅ | ✅ | ✅ |
| `net` module | ✅ | ✅ | ✅ |
| `sys` module | ✅ | ✅ | ✅ |
| `serde` | ❌ | ✅ | ✅ |
| `arbitrary` | ✅ | ✅ | ✅ |
| `zeroize` | ✅ | ✅ | ✅ |

**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
- Process ID (Pid) with validation and utility methods
- File descriptor (Fd) with validation and standard FD constants

## Getting Started

Add `bare-types` to your `Cargo.toml`:

```toml
[dependencies]
bare-types = "0.1.3"
```

Enable specific features as needed:

```toml
[dependencies]
bare-types = { version = "0.1.3", features = ["net", "serde"] }
```

## Usage Examples

### Network Types (net feature)

```rust
use bare_types::net::{IpAddr, Port, Hostname, DomainName, SocketAddr};

// IP addresses with validation
let ipv4: IpAddr = "192.168.1.1".parse()?;
let ipv6: IpAddr = "::1".parse()?;

// Port numbers with IANA range validation
let http_port = Port::HTTP; // 80
let custom_port: Port = 8080.try_into()?;

// Hostnames with RFC 1123 validation
let hostname: Hostname = "my-server".parse()?;

// Domain names with RFC 1035 validation
let domain: DomainName = "example.com".parse()?;

// Socket addresses combining host and port
let socket: SocketAddr = "example.com:443".parse()?;
let (host, port) = socket.into_parts();
```

### System Types (sys feature)

```rust
use bare_types::sys::{Arch, OsType, OsVersion, KernelVersion, Username, Distro, Pid, Fd};

// Compile-time architecture detection
let arch = Arch::current();
assert!(arch.is_64_bit());

// Compile-time OS detection
let os = OsType::current();
assert!(os.is_unix());

// Semantic versioning for OS versions
let os_ver: OsVersion = "22.04".parse()?;
assert_eq!(os_ver.major(), 22);

// Kernel versions with release strings
let kernel: KernelVersion = "6.8.0-40-generic".parse()?;
assert!(kernel.is_stable());

// POSIX-compliant usernames
let username: Username = "www-data".parse()?;

// OS distribution names
let distro: Distro = "ubuntu".parse()?;
assert!(distro.is_debian_based());

// Process IDs with validation
let pid: Pid = 1234.try_into()?;
assert!(!pid.is_init());

// File descriptors with standard FD constants
assert_eq!(Fd::STDIN.as_i32(), 0);
assert_eq!(Fd::STDOUT.as_i32(), 1);
assert_eq!(Fd::STDERR.as_i32(), 2);
```

## Documentation

Full API documentation is available on [docs.rs](https://docs.rs/bare-types).

### Tutorials

- [Getting Started](docs/getting_started.md) - Learn the basics of using `bare-types`
- [Network Programming](docs/network_programming.md) - Build type network applications
- [System Information](docs/system_information.md) - Work with system information types
- [Zero-Cost Abstractions](docs/zero_cost_abstractions.md) - Understand zero-cost abstractions
- [Error Handling](docs/error_handling.md) - Best practices for error handling
- [Serialization](docs/serialization.md) - Using `serde` for serialization
- [Testing](docs/testing.md) - Testing strategies and property-based testing

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Support

Need help? See [SUPPORT.md](SUPPORT.md) for resources and how to get assistance.

## Governance

Learn about project governance and decision-making in [GOVERNANCE.md](GOVERNANCE.md).

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

## Security

See [SECURITY.md](SECURITY.md) for security policy and vulnerability reporting.

## Code of Conduct

This project follows the [Rust Code of Conduct](CODE_OF_CONDUCT.md).

## License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT License ([LICENSE-MIT](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](https://github.com/bare-rs/bare-config) - Type-safe configuration authority
- [bare-script](https://github.com/bare-rs/bare-script) - Type-safe scripting authority