#MoonSuffix

• What is its public suffix?
• What is the registrable domain (often called eTLD+1)?

#Why this project exists

#Review in one minute

moon run examples/review

lookup api.shop.example.co.uk: suffix=co.uk, registrable=example.co.uk
PSL update: +PRIVATE glideos.app
api.glideos.app: registrable glideos.app -> api.glideos.app
Cookie Domain=.glideos.app: glideos.app accepted -> cookie Domain attribute 'glideos.app' is a public suffix
changed hosts=1, changed Cookie scopes=1

#Quick start

let rules =
  #|com
  #|co.uk
  #|*.ck
  #|!www.ck

let suffixes = @moonsuffix.SuffixList::parse(rules).unwrap()
let result = suffixes.lookup("api.shop.example.co.uk").unwrap()

println(result.public_suffix())       // co.uk
println(result.registrable_domain())  // Some(example.co.uk)
println(result.matched_rule())        // co.uk

let result = suffixes.lookup_with_options(
  "api.example.com",
  @moonsuffix.LookupOptions::strict_icann(),
).unwrap()

moon run cmd/main

let list = @suffix_idna.parse_psl("公司.cn\ncom\n").unwrap()
let result = @suffix_idna.lookup(list, "商店.公司.cn").unwrap()
println(result.public_suffix()) // xn--55qx5d.cn
println(result.registrable_domain().unwrap()) // xn--czrs0t.xn--55qx5d.cn

let report = @suffix_idna.lookup_batch(
  list,
  ["商店.公司.cn", "商店..公司.cn", "xn--czrs0t.xn--55qx5d.cn"],
)
println(report.to_csv())

let scope = @suffix_idna.resolve_cookie_scope(
  list, "api.商店.公司.cn", Some(".商店.公司.cn"),
).unwrap()
println(scope.domain()) // xn--czrs0t.xn--55qx5d.cn
println(@suffix_idna.cookie_scope_matches_host(scope, "别的.商店.公司.cn")) // Ok(true)

let first = suffixes.schemeful_site("https", "shop.example.com").unwrap()
let second = suffixes.schemeful_site("https", "api.example.com").unwrap()
let third = suffixes.schemeful_site("http", "api.example.com").unwrap()
println(first.same_site(second)) // true
println(first.same_site(third))  // false

let scopes = suffixes.shareable_cookie_scopes("api.shop.example.com").unwrap()
for scope in scopes {
  println(scope.domain())
}

#Build a PSL snapshot

moon run --target native cmd/snapshot \
  examples/audit/old.psl \
  old.snapshot \
  --revision example-v1

moon run --target native cmd/snapshot \
  examples/idna/rules.psl unicode.snapshot \
  --revision unicode-example-v1 --idna

moon run --target native cmd/lookup \
  unicode.snapshot 商店.公司.cn --idna --strict-icann

#Check PSL conformance cases

moon run --target native cmd/conformance \
  examples/conformance/rules.psl examples/conformance/cases.txt

#Measure a real PSL workload

moon run --target native cmd/bench \
  public_suffix_list.dat examples/bench/hosts.txt --idna

#Embed a pinned PSL in a MoonBit application

moon run --target native cmd/embed \
  public_suffix_list.dat embedded_psl.mbt \
  --revision <upstream-commit-sha> --idna

#Audit a PSL update

moon run --target native cmd/audit \
  examples/audit/old.psl \
  examples/audit/new.psl \
  examples/audit/hosts.txt \
  --from example-v1 \
  --to example-v2 \
  --strict-icann

moon run --target native cmd/audit \
  old.snapshot new.snapshot examples/audit/hosts.txt \
  --bundles --strict-icann --fail-on-impact

moon run --target native cmd/audit \
  examples/audit/old.psl examples/audit/new.psl \
  examples/audit/stable-hosts.txt \
  --from example-v1 --to example-v2 --strict-icann \
  --cookie-inventory examples/audit/cookies.tsv --fail-on-impact

moon run --target native cmd/audit \
  examples/audit/old-unicode.psl examples/audit/new-unicode.psl \
  examples/audit/unicode-hosts.txt \
  --from old --to new --idna --strict-icann \
  --cookie-inventory examples/audit/unicode-cookies.tsv --fail-on-impact

#Audit a lookup-policy migration

moon run --target native cmd/snapshot \
  examples/audit/old.psl old.snapshot --revision example-v1
moon run --target native cmd/policy-audit \
  old.snapshot examples/audit/hosts.txt --fail-on-impact

#Classify a hostname inventory

moon run --target native cmd/snapshot \
  examples/audit/old.psl classify.snapshot --revision example-v1
moon run --target native cmd/classify \
  classify.snapshot examples/classify/hosts.txt --strict-icann

moon run --target native cmd/snapshot \
  examples/idna/rules.psl unicode.snapshot \
  --revision unicode-example-v1 --idna
moon run --target native cmd/classify \
  unicode.snapshot examples/classify/unicode-hosts.txt \
  --idna --strict-icann

#Check rule coverage in a hostname sample

let coverage = suffixes.analyze_rule_coverage(
  ["api.example.com", "www.www.ck", "service.internal"],
  @moonsuffix.LookupOptions::browser_default(),
)
println(coverage.observed_rule_count())
println(coverage.to_csv())

#Current API

• SuffixList::parse compiles PSL text into a reverse-label trie.
• lookup returns the case-normalized domain, public suffix, optional registrable domain, prevailing rule, rule kind, and source section. It keeps browser-style behavior by considering both ICANN and PRIVATE rules and falling back to *.
• lookup_with_options supports ICANN-only or all-section matching and either an implicit wildcard or an error for unknown suffixes.
• trace_lookup_with_options exposes every matching rule candidate, its source section, policy eligibility, and whether it won. A valid but unlisted host retains the strict-policy error alongside the trace.
• to_psl_text exports a deterministic, parseable representation for pinned snapshots, hashing, and reproducible builds.
• snapshot binds canonical PSL text to an opaque source revision, a SHA-256 digest, its rule count, and a deterministic line-oriented manifest.
• Snapshot::restore verifies stored canonical PSL text against every manifest field before reconstructing a trusted snapshot.
• Snapshot::bundle_text and restore_bundle_text store the manifest and canonical rules in one strictly verified text artifact.
• cmd/snapshot builds a single-file snapshot from a local PSL source and an explicit revision without overwriting existing output. Its --idna mode normalizes Unicode rules to A-labels first.
• cmd/lookup verifies a stored snapshot before classifying one hostname, with optional IDNA and strict ICANN lookup policies.
• Snapshot::diff produces deterministic additions, removals, and unambiguous ICANN/PRIVATE section moves between two snapshots.
• Snapshot::analyze_impact evaluates a hostname inventory against old and new snapshots, classifies only changed outcomes, and exports deterministic CSV.
• analyze_policy_impact compares two lookup policies over one hostname inventory, exposing domains affected by a stricter deployment policy.
• analyze_rule_coverage counts selected explicit rules by section and distinguishes implicit, unlisted, and invalid inputs in a deterministic CSV.
• lookup_batch and lookup_batch_with_options preserve input order and retain invalid hostnames as row-level errors; BatchReport::to_csv exports every row.
• site_key and same_registrable_site expose canonical registrable-hostname boundaries for Cookie policy and hostname-level same-site integration.
• schemeful_site creates an HTTP(S) site identity from an ASCII hostname and compares both scheme and registrable domain, including PRIVATE PSL rules.
• resolve_cookie_scope converts an optional Cookie Domain attribute into its canonical stored domain and host-only flag, rejecting public-suffix scope escalation, unrelated domains, and malformed non-ASCII server values.
• shareable_cookie_scopes enumerates valid Domain Cookie scopes from the request host down to its registrable boundary under the selected PSL policy.
• CookieScope::matches_host checks whether that stored domain scope covers a later request hostname, distinguishing host-only and Domain cookies.
• Snapshot::analyze_cookie_scope_impact tests an ordered inventory of request hosts and Cookie Domain attributes against old and candidate PSL snapshots, reporting changed acceptance or stored scopes as deterministic CSV.
• CookieScopeInput::validate_syntax checks ASCII request-host and Domain syntax independently of PSL policy, for fail-closed inventory ingestion.
• cmd/audit joins snapshots, semantic rule diffs, and hostname impact analysis into a native, local-file workflow with deterministic text and CSV output. It can verify stored bundles and audit an optional Cookie inventory; --fail-on-impact can block a candidate update in CI.
• cmd/policy-audit compares browser-default and strict ICANN lookup against one verified snapshot and can gate a policy migration in CI.
• cmd/classify turns a hostname inventory into ordered batch-lookup CSV, preserving row-level errors and optionally failing a CI input-quality gate.
• idna converts Unicode PSL rules and hostnames with UTS #46 before querying the core; returned domain strings are A-labels. Its batch API preserves Unicode inputs and IDNA errors as ordered rows with deterministic CSV. It also resolves Unicode Cookie scopes and matches later Unicode request hosts.
• verify_psl_test_file runs upstream-style checkPublicSuffix cases, retains ordered mismatch diagnostics, and exports failures as deterministic CSV.
• public_suffix, registrable_domain, and is_public_suffix provide focused convenience queries.
• Rules may be exact (co.uk), wildcard (*.ck), or exception (!www.ck).
• Unknown suffixes use the PSL algorithm's implicit * rule.
• A single trailing root dot is preserved in returned domain strings.

#Deliberate v0.1 boundaries

• No PSL snapshot is bundled. Applications inject a pinned or freshly fetched list, so data freshness and MPL-2.0 obligations remain explicit.
• Snapshot revision labels are supplied by the caller. SHA-256 detects canonical content changes but does not authenticate the source or fetch upstream data.
• The core lowercases rules and hostnames but does not perform IDNA conversion. Use the separate idna adapter for Unicode input; its results are ASCII A-labels and do not preserve the original display spelling.
• Callers must extract a hostname before lookup; URLs and IP literals are outside this API's input contract.

#Roadmap

1. Continue measuring performance on representative application inventories and track regressions across toolchain updates.

#Validation

moon fmt
moon info
moon check --target wasm --deny-warn
moon test --target wasm --deny-warn
moon test --target wasm-gc --deny-warn
moon test --target js --deny-warn
moon run cmd/main
moon run examples/idna
moon check cmd/audit --target native --deny-warn
moon test cmd/audit --target native --deny-warn
moon check cmd/snapshot --target native --deny-warn
moon test cmd/snapshot --target native --deny-warn
moon check cmd/lookup --target native --deny-warn
moon test cmd/lookup --target native --deny-warn
moon check cmd/conformance --target native --deny-warn
moon test cmd/conformance --target native --deny-warn
moon check cmd/policy-audit --target native --deny-warn
moon test cmd/policy-audit --target native --deny-warn
moon check cmd/classify --target native --deny-warn
moon test cmd/classify --target native --deny-warn
moon check cmd/bench --target native --deny-warn
moon test cmd/bench --target native --deny-warn
moon check cmd/embed --target native --deny-warn
moon test cmd/embed --target native --deny-warn

#License