dnsname 0.1.3

Canonical registrable-domain (eTLD+1) and public-suffix resolution, backed by the Public Suffix List
Documentation
# SPEC.md - dnsname Technical Specification

## Overview

`dnsname` provides zero-copy, canonical registrable-domain (eTLD+1) and public-suffix resolution for network hostnames, backed by the Mozilla Public Suffix List via the `psl` crate snapshot.

## Architecture & Data Flow

```
Input Host (`&str`)
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│ 1. `normalize(host)`                                        │
│    - Trim whitespace & surrounding FQDN dots (`.`)           │
│    - Fast-path reject non-ASCII (U-labels)                  │
│    - Reject ASCII whitespace & control bytes (NUL, tab, etc)│
│    - ASCII-lowercase (Cow::Borrowed if already lowercase)   │
└──────────────────────────────┬──────────────────────────────┘
                               │ `Cow<'_, str>`
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. `is_ip_literal(norm)`                                    │
│    - Strip surrounding brackets `[` `]` (IPv6 Host syntax)  │
│    - Strip zone index `%...` (RFC 6874)                     │
│    - Parse via `std::net::IpAddr`                           │
│    - If valid IP -> return None for domain/suffix           │
└──────────────────────────────┬──────────────────────────────┘
                               │ valid DNS host
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. PSL Lookup (`psl::domain` / `psl::suffix`)                │
│    - Match against compiled Public Suffix List              │
│    - Return owned ASCII subslice                            │
└─────────────────────────────────────────────────────────────┘
```

## API Specification

### Core Functions

```rust
pub fn registrable_domain(host: &str) -> Option<String>;
pub fn public_suffix(host: &str) -> Option<String>;
pub fn is_subdomain_of(child: &str, parent: &str) -> bool;
pub fn same_registrable_domain(a: &str, b: &str) -> bool;
```

### Direct Aliases

```rust
pub use self::registrable_domain as etld_plus_one;
pub use self::registrable_domain as apex_domain;
```

## Invariants & Guarantees

1. **Safety**: `#![forbid(unsafe_code)]` enabled crate-wide.
2. **Zero Allocation on Hot Path**: Inputs that are trimmed, lowercase ASCII are returned as `Cow::Borrowed` during normalization without heap allocation.
3. **No Garbage UTF-8 / Lossy Replacements**: Subslices returned by `psl` are converted via `std::str::from_utf8` (checked invariant), ensuring U+FFFD replacement characters are never introduced.
4. **Control Byte, Junk, and URL Delimiter Rejection**: Input containing ASCII whitespace, control bytes (`0x00..=0x1F`, `0x7F`), URL delimiters (`:`, `/`, `@`, `?`, `#`, `\`), consecutive dots (`..`), or numeric TLDs (`.0`, `.1`) is rejected immediately (`None`).
5. **U-Label Guard**: Non-ASCII input (Unicode hostnames like `bücher.de`) returns `None`. Callers must supply punycode A-labels (`xn--bcher-kva.de`).
6. **IP Literal Exclusions**: Standard IPv4 (`1.2.3.4`), bracketed IPv4 (`[127.0.0.1]`), IPv6 literals (`::1`, `[2001:db8::1]`, `fe80::1%eth0`, `[::ffff:127.0.0.1]`), and alternate IPv4 spellings (`0177.0.0.1`, `127.0.0.01`, `0x7f.0.0.1`, `127.1`) return `None` from `registrable_domain` and `public_suffix`.
7. **Subdomain Label Safety**: `is_subdomain_of` respects label boundaries (e.g. `notexample.com` is NOT a subdomain of `example.com`). Distinct IP literals or IP-to-domain comparisons in `is_subdomain_of` return `false`.

## Edge-Case Behavior Matrix

| Input | `registrable_domain` | `public_suffix` | Notes |
|---|---|---|---|
| `"example.com"` | `Some("example.com")` | `Some("com")` | Standard TLD |
| `"a.b.example.co.uk"` | `Some("example.co.uk")` | `Some("co.uk")` | Multi-label suffix |
| `"com"` | `None` | `Some("com")` | Bare public suffix |
| `"  .EXAMPLE.COM. "` | `Some("example.com")` | `Some("com")` | Trimmed, lowercased, dots dropped |
| `"1.2.3.4"` | `None` | `None` | IPv4 literal |
| `"[::1]"` | `None` | `None` | Bracketed IPv6 literal |
| `"fe80::1%eth0"` | `None` | `None` | Zone-scoped IPv6 literal |
| `"bücher.de"` | `None` | `None` | Non-ASCII U-label rejected |
| `"xn--bcher-kva.de"` | `Some("xn--bcher-kva.de")` | `Some("de")` | A-label accepted |
| `"a\0b.com"` | `None` | `None` | Control byte rejected |
| `"256.1.1.1"` | `None` | `None` | Out-of-range IP with numeric TLD `.1` rejected |
| `"example.com:80"` | `None` | `None` | Port/URL delimiter rejected |
| `"0177.0.0.1"` | `None` | `None` | Alternate IPv4 literal rejected |
| `"example..com"` | `None` | `None` | Empty label rejected |

## Dependency Pinning

The `psl` dependency is pinned to exact version `=2.1.218` in `Cargo.toml`. `dnsname::tests::psl_dependency_is_pinned` verifies this pin at test time to prevent silent drift of the bundled Public Suffix List snapshot.