# Adbyss: Public Suffix
[](https://docs.rs/adbyss_psl/)
[](https://github.com/Blobfolio/adbyss/blob/master/adbyss_psl/CHANGELOG.md)
[](https://crates.io/crates/adbyss_psl)
[](https://github.com/Blobfolio/adbyss/actions)
[](https://deps.rs/repo/github/blobfolio/adbyss)
[](https://en.wikipedia.org/wiki/WTFPL)
[](https://github.com/Blobfolio/adbyss/issues)
This library contains a single public-facing struct — `adbyss_psl::Domain` — used for validating and normalizing Internet hostnames, like "www.domain.com".
It will:
* Validate, normalize, and Puny-encode internationalized/Unicode labels ([RFC 3492](https://datatracker.ietf.org/doc/html/rfc3492#ref-IDNA));
* Validate and normalize the [public suffix](https://publicsuffix.org/list/);
* Ensure conformance with [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123);
* And locate the boundaries of the subdomain (if any), root (required), and suffix (required);
## Examples
New instances of `Domain` can be initialized using either `Domain::new` or `TryFrom<&str>`.
```rust
use adbyss_psl::Domain;
// These are equivalent and fine:
assert!(Domain::new("www.MyDomain.com").is_some());
assert!(Domain::try_from("www.MyDomain.com").is_ok());
// The following is valid DNS, but invalid as an Internet hostname:
assert!(Domain::new("_acme-challenge.mydomain.com").is_none());
```
Valid Internet hostnames must be no longer than 253 characters, and contain both root and (valid) suffix components.
Their labels — the bits between the dots — must additionally:
* Be no longer than 63 characters;
* (Ultimately) contain only ASCII letters, digits, and `-`;
* Start and end with an alphanumeric character;
Unicode/internationalized labels are allowed, but must be Puny-encodable and not contain any conflicting bidirectionality constraints. `Domain` will encode such labels using [Punycode](https://en.wikipedia.org/wiki/Punycode) when it finds them, ensuring the resulting hostname will always be ASCII-only.
Post-parsing, `Domain` gives you access to each individual component, or the whole thing:
```rust
use adbyss_psl::Domain;
let dom = Domain::new("www.MyDomain.com").unwrap();
// Pull out the pieces if you're into that sort of thing.
assert_eq!(dom.host(), "www.mydomain.com");
assert_eq!(dom.subdomain(), Some("www"));
assert_eq!(dom.root(), "mydomain");
assert_eq!(dom.suffix(), "com");
assert_eq!(dom.tld(), "mydomain.com");
// If you just want the sanitized host back as an owned value, use
// `Domain::take` or `String::from`:
let owned = dom.take(); // "www.mydomain.com"
```
## Optional Crate Features
* `serde`: Enables serialization/deserialization support.