hostaddr 0.3.0

Type-safe, validated DNS domain names, hosts, and host addresses for Rust.

Overview

hostaddr provides type-safe, validated types for working with network host identifiers:

• Domain<S> -- A validated DNS domain name, with IDNA/punycode and percent-encoding support
• Host<S> -- Either a domain name or an IP address (v4/v6)
• HostAddr<S> -- A host with an optional port number (e.g. example.com:8080, [::1]:443)

All types are generic over their storage backend S, allowing you to choose the representation that best fits your use case -- from zero-alloc stack buffers (Buffer) to shared smart pointers (Arc<str>).

Features

• no_std and no-alloc compatible: Use the Buffer type for stack-allocated domains without any heap allocation
• Generic storage: Works with String, Arc<str>, Box<str>, Vec<u8>, SmolStr, Bytes, and more
• IDNA/Punycode support: Automatic conversion of international domain names (e.g. 测试.中国 to punycode)
• Type-safe validation: Domain names are validated at construction time per RFC 1035 rules
• Percent-encoding: Transparent decoding of percent-encoded domains
• IPv4/IPv6: Full support for IP addresses, including proper [::1]:port bracket syntax
• Semantic IP/socket wrappers: LoopbackIpAddr/LoopbackAddr, PrivateIpAddr/PrivateAddr, and other validated address classes
• Transport taxonomy: Addr, IpcAddr, and LocalAddr model host, IPC, and local-only addresses
• Serde: Optional serialization/deserialization support
• Fuzzing: Built-in arbitrary and quickcheck generators for property-based testing

Installation

[dependencies]
hostaddr = "0.2"

Feature Flags

Quick Start

use hostaddr::HostAddr;

// Domain with port
let addr: HostAddr<String> = "example.com:8080".parse().unwrap();
assert!(addr.is_domain());
assert_eq!(addr.port(), Some(8080));

// IPv4 with port
let addr: HostAddr<String> = "127.0.0.1:3000".parse().unwrap();
assert!(addr.is_ipv4());

// IPv6 with port (bracket syntax)
let addr: HostAddr<String> = "[::1]:443".parse().unwrap();
assert!(addr.is_ipv6());
assert_eq!(addr.to_string(), "[::1]:443");

// International domain names (auto punycode)
let addr: HostAddr<String> = "测试.中国:80".parse().unwrap();

Address Taxonomy

Addr separates Internet host addresses from IPC transports while preserving generic storage for each address family. LocalAddr::Loopback is validated as a loopback IP socket address, while LocalAddr::Ipc groups non-IP IPC transport addresses without treating every IPC endpoint as a same-machine trust boundary.

Semantic address classes are available in IP-only and socket-with-port forms. The *IpAddr types wrap core::net::IpAddr; the matching *Addr types wrap core::net::SocketAddr and validate the socket IP component. Common classes include Loopback, Private, LinkLocal, Documentation, Benchmark, Shared, Multicast, Unspecified, and Broadcast.

The transparent IPC wrappers support borrowed DST storage such as &UnixAddr<Path> on Unix and &AbstractAddr<[u8]> on Linux. Windows named-pipe addresses are exposed through NamedPipeAddr; Linux VsockAddr support is available through the default-enabled vsock feature.

use hostaddr::{Addr, HostAddr, LocalAddr, LoopbackAddr, PrivateIpAddr};

let host = HostAddr::<&str>::from(("127.0.0.1".parse::<core::net::IpAddr>().unwrap(), 8080));
let addr: Addr<&str, &str, &[u8]> = host.into();

let private = PrivateIpAddr::try_from("10.0.0.1".parse::<core::net::IpAddr>().unwrap()).unwrap();

#[cfg(unix)]
{
  use hostaddr::{IpcAddr, UnixAddr};

  let unix: IpcAddr<&str, &[u8]> = UnixAddr::new("/tmp/app.sock").into();
}

let local_ip = LoopbackAddr::try_from("127.0.0.1:8080".parse::<core::net::SocketAddr>().unwrap()).unwrap();
let local: LocalAddr<&str, &[u8]> = local_ip.into();

Examples

Working with Domains

use hostaddr::Domain;

// Validated at construction -- invalid names are rejected
assert!(Domain::<String>::try_from("example.com").is_ok());
assert!(Domain::<String>::try_from("-invalid.com").is_err());

// International domain names are converted to punycode
let domain: Domain<String> = "测试.中国".parse().unwrap();
assert_eq!(domain.as_inner().as_str(), "xn--g6w251d.xn--fiqz9s");

// FQDN support
let domain: Domain<String> = "example.com.".parse().unwrap();
assert!(domain.is_fqdn());

// ASCII-only fast path (no punycode or percent-decoding)
let domain = Domain::try_from_ascii_str("example.com").unwrap();

Choosing a Storage Type

use hostaddr::HostAddr;
use std::sync::Arc;

// Heap-allocated String
let addr: HostAddr<String> = "example.com:8080".parse().unwrap();

// Shared ownership with Arc<str>
let addr: HostAddr<Arc<str>> = "example.com:8080".parse().unwrap();

// Byte storage
let addr: HostAddr<Vec<u8>> = "example.com".parse().unwrap();

Stack-Allocated Domains (no_std / no-alloc)

use hostaddr::{HostAddr, Buffer, Domain};

// No heap allocation -- 255-byte stack buffer
let domain: Domain<Buffer> = Domain::try_from("example.com").unwrap();
let addr: HostAddr<Buffer> = HostAddr::try_from("example.com:443").unwrap();

Manipulating Addresses

use hostaddr::HostAddr;

let mut addr: HostAddr<String> = "example.com".parse().unwrap();
addr.set_port(8080);
assert_eq!(addr.to_string(), "example.com:8080");

// Builder-style with default port
let addr = "example.com".parse::<HostAddr<String>>().unwrap()
    .with_default_port(443);
assert_eq!(addr.port(), Some(443));

Verification Functions

use hostaddr::{verify_domain, verify_ascii_domain};

assert!(verify_domain(b"example.com").is_ok());
assert!(verify_domain("测试.中国".as_bytes()).is_ok());

assert!(verify_ascii_domain(b"example.com").is_ok());
assert!(verify_ascii_domain("测试.中国".as_bytes()).is_err());

License

hostaddr is under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT for details.

Copyright (c) 2026 Al Liu.