net.hostname-validate

export function validateHostname(text: string): HostnameValidation

/** Whether the text is a usable host name, and its normal form. */
export interface HostnameValidation {
  readonly valid: boolean;
  /** lower-case, trailing dot removed */
  readonly hostname: string | null;
  /** why it is not valid */
  readonly reason: string | null;
  /** how many dot-separated labels the text has */
  readonly labels: number;
}

import { validateHostname } from "#fune/net.hostname-validate@^1";

import { type HostnameValidation } from "./net_hostname_validate_types.ts";

const ALLOWED = /^[A-Za-z0-9.-]*$/;
const DIGITS = /^[0-9]+$/;

/**
 * Check a host name against the RFC 1123 / RFC 952 rules and normalise it:
 * lower-case, one trailing dot (a fully qualified name) removed.
 *
 * Checks run in a fixed order and the first failure is the reason: empty,
 * characters, total length, then each label in turn, then the top-level label.
 */
export function validateHostname(text: string): HostnameValidation {
  if (typeof text !== "string") return { valid: false, hostname: null, reason: "not text", labels: 0 };
  const name = text.endsWith(".") ? text.slice(0, -1) : text;
  const labels = name.length === 0 ? [] : name.split(".");
  const fail = (reason: string): HostnameValidation => ({ valid: false, hostname: null, reason, labels: labels.length });

  if (name.length === 0) return fail("empty");
  // Characters first: once the text is known to be ASCII, every language
  // counts its length the same way.
  if (!ALLOWED.test(name)) return fail("character other than a letter, digit, hyphen or dot");
  if (name.length > 253) return fail("longer than 253 characters");
  for (const label of labels) {
    if (label.length === 0) return fail("empty label");
    if (label.length > 63) return fail("label longer than 63 characters");
    if (label.startsWith("-") || label.endsWith("-")) return fail("label starts or ends with a hyphen");
  }
  // RFC 3696 section 2: a top-level domain is never all-numeric, which keeps
  // 1.2.3.4 an address rather than a name.
  if (DIGITS.test(labels[labels.length - 1])) return fail("top-level label is all numeric");
  return { valid: true, hostname: name.toLowerCase(), reason: null, labels: labels.length };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add net.hostname-validate

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./net.hostname-validate-1.0.0-typescript.fune, or fetch it from a terminal with fune pull net.hostname-validate@1.0.0:typescript.

The whole function, every language, is one file too: net.hostname-validate-1.0.0.fune, 16,975 bytes, sha256 9576a43bfb084e52ba629fd752e619e549894cae29d493d149f1b1ff4f682255. It installs into a project of any language.

// fune: before net.hostname-validate

// fune: after net.hostname-validate

// fune: step net.hostname-validate after <n|label>

More from the author

The first rule that fails is the reason.

1. Not empty (`""` and `"."` are `empty`). 2. Only ASCII letters, digits, hyphens and dots. No underscores (allowed in some DNS record names such as `_sip._tcp`, never in a host name), no spaces, no trailing newline, nothing non-ASCII: an internationalised name must be converted to its `xn--` punycode form first. 3. At most 253 characters, not counting the trailing dot (RFC 1035 section 2.3.4 allows 255 octets on the wire, which is 253 characters of text). 4. Every label is 1 to 63 characters (RFC 1035 2.3.4) and does not start or end with a hyphen (RFC 952). A label may start with a digit: RFC 1123 section 2.1 relaxed RFC 952 on that point, so `3com.example` is fine. 5. The last label is not all digits (RFC 3696 section 2). This keeps `192.168.1.1` an address, not a name, so a caller can try the IP parsers first and fall back to this without ambiguity.

## Not checked

Whether the name resolves, whether its top-level domain exists, and the rules for other DNS record names (underscores, wildcards). `labels` is counted even when the name is invalid, from the text with one trailing dot removed.

Sources: RFC 952 (DoD Internet Host Table Specification), RFC 1123 section 2.1 (Requirements for Internet Hosts), RFC 1035 section 2.3.4 (size limits), RFC 3696 section 2 (Application Techniques for Checking and Transformation of Names).

Files