Crate hostaddr 

hostaddr

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

Feature	Description
std (default)	Standard library support, enables IDNA and percent-decoding
vsock (default)	Linux VM socket address support through VsockAddr and IpcAddr::Vsock
alloc	Allocation support without std
serde	Serialize/deserialize support
arbitrary	Fuzzing with arbitrary crate
cheap-clone	CheapClone trait for smart pointer types
smol_str	SmolStr storage support
bytes	Bytes storage support
triomphe	triomphe::Arc storage support
tinyvec	TinyVec storage support
smallvec	SmallVec storage support

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.

Structs

AbstractAddrLinux

A Linux abstract socket name.

BenchmarkAddr

A socket address whose IP address is reserved for benchmarking.

BenchmarkIpAddr

An IP address reserved for benchmarking.

BroadcastAddr

A socket address whose IP address is the IPv4 limited broadcast address.

BroadcastIpAddr

The IPv4 limited broadcast address.

Buffer

An immutable buffer which contains a valid domain.

DocumentationAddr

A socket address whose IP address is reserved for documentation or examples.

DocumentationIpAddr

An IP address reserved for documentation or examples.

Domain

A DNS domain name, as . dot-separated labels. Non-ASCII labels are encoded in punycode per IDNA if this is the host of a special URL, or percent encoded for non-special URLs.

HostAddr

A host address, which consists of a Host and an optional port number.

LinkLocalAddr

A socket address whose IP address is link-local.

LinkLocalIpAddr

An IPv4 or IPv6 link-local address.

LoopbackAddr

A socket address whose IP address is loopback.

LoopbackIpAddr

An IP address in the loopback range.

MulticastAddr

A socket address whose IP address is multicast.

MulticastIpAddr

An IPv4 or IPv6 multicast address.

ParseAsciiDomainError

The provided input could not be parsed because it is not an ASCII syntactically-valid DNS Domain.

ParseAsciiHostError

An error which can be returned when parsing an ASCII Host.

ParseBenchmarkAddrError

The provided socket address is not reserved for benchmarking.

ParseBenchmarkIpAddrError

The provided IP address is not reserved for benchmarking.

ParseBroadcastAddrError

The provided socket address is not the IPv4 limited broadcast address.

ParseBroadcastIpAddrError

The provided IP address is not the IPv4 limited broadcast address.

ParseDocumentationAddrError

The provided socket address is not reserved for documentation.

ParseDocumentationIpAddrError

The provided IP address is not reserved for documentation.

ParseDomainError

The provided input could not be parsed because it is not a syntactically-valid DNS Domain.

ParseHostError

An error which can be returned when parsing a Host.

ParseLinkLocalAddrError

The provided socket address is not link-local.

ParseLinkLocalIpAddrError

The provided IP address is not link-local.

ParseLoopbackAddrError

The provided socket address is not a loopback address.

ParseLoopbackIpAddrError

The provided IP address is not a loopback address.

ParseMulticastAddrError

The provided socket address is not multicast.

ParseMulticastIpAddrError

The provided IP address is not multicast.

ParsePrivateAddrError

The provided socket address is not private-use or unique-local.

ParsePrivateIpAddrError

The provided IP address is not private-use or unique-local.

ParseSharedAddrError

The provided socket address is not in IPv4 shared address space.

ParseSharedIpAddrError

The provided IP address is not in IPv4 shared address space.

ParseUnspecifiedAddrError

The provided socket address is not the exact unspecified address.

ParseUnspecifiedIpAddrError

The provided IP address is not the exact unspecified address.

PrivateAddr

A socket address whose IP address is private-use or unique-local.

PrivateIpAddr

An RFC 1918 IPv4 private-use or RFC 4193 IPv6 unique-local address.

SharedAddr

A socket address whose IP address is in IPv4 shared address space.

SharedIpAddr

An IPv4 shared address space address.

TryUnwrapError

Error returned by the derived TryUnwrap implementation.

UnixAddrUnix

A Unix-domain socket pathname.

UnspecifiedAddr

A socket address whose IP address is the exact unspecified address.

UnspecifiedIpAddr

The exact IPv4 or IPv6 unspecified address.

VsockAddrLinux and vsock

A VM socket address.

Enums

Addr

Any address accepted by a runtime.

Host

The host name

IpcAddr

A non-IP communication address.

LocalAddr

An address in the local-address taxonomy.

ParseAsciiHostAddrError

An error which can be returned when parsing a HostAddr.

ParseHostAddrError

An error which can be returned when parsing a HostAddr.

Functions

verify_ascii_domain

Verifies that the input is a valid ASCII domain name.

verify_ascii_domain_allow_percent_encoding

Verifies that the input is a valid ASCII domain name. The input can be a percent-encoded domain name.

verify_domainalloc or std

Verifies that the input is a valid domain name.