@mytld/engine 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,17 @@
1
+ import { type Engine, type EngineOptions } from "./options.js";
2
+ /**
3
+ * Creates a lookup engine. Every engine owns its own resolvers, throttles and caches,
4
+ * so create one per process and reuse it.
5
+ *
6
+ * Pipeline per domain (all domains run concurrently):
7
+ *
8
+ * 1. **Cache:** in-process L1, then one `mget()` on the store for the whole batch.
9
+ * 2. **DNS:** an NS query (~10–40 ms). If the name is delegated, it's **taken**. Done.
10
+ * 3. **Registry:** RDAP (IANA bootstrap + overrides), WHOIS as fallback.
11
+ *
12
+ * Step 3 runs for every name without a delegation, because a missing DNS record doesn't
13
+ * mean free: on-hold, parked and reserved names have none. So "available" is only ever
14
+ * reported after a registry confirmed it. Without a registry answer the result is
15
+ * "unknown", with `noDns: true` when DNS had nothing either.
16
+ */
17
+ export declare function createEngine(options?: EngineOptions): Engine;
@@ -0,0 +1,147 @@
1
+ import { ResultCache } from "../cache/result-cache.js";
2
+ import { safeStore } from "../cache/safe-store.js";
3
+ import { memoryStore } from "../cache/store.js";
4
+ import { isValidDomain, tldOf } from "../core/domain.js";
5
+ import { createDns } from "../lookup/dns.js";
6
+ import { createRdap, DEFAULT_RDAP_OVERRIDES } from "../lookup/rdap.js";
7
+ import { createWhois, DEFAULT_WHOIS_SERVERS } from "../lookup/whois.js";
8
+ import { callbackToAsyncIterable } from "../util/async-iterable.js";
9
+ import { DEFAULTS } from "./options.js";
10
+ /**
11
+ * Creates a lookup engine. Every engine owns its own resolvers, throttles and caches,
12
+ * so create one per process and reuse it.
13
+ *
14
+ * Pipeline per domain (all domains run concurrently):
15
+ *
16
+ * 1. **Cache:** in-process L1, then one `mget()` on the store for the whole batch.
17
+ * 2. **DNS:** an NS query (~10–40 ms). If the name is delegated, it's **taken**. Done.
18
+ * 3. **Registry:** RDAP (IANA bootstrap + overrides), WHOIS as fallback.
19
+ *
20
+ * Step 3 runs for every name without a delegation, because a missing DNS record doesn't
21
+ * mean free: on-hold, parked and reserved names have none. So "available" is only ever
22
+ * reported after a registry confirmed it. Without a registry answer the result is
23
+ * "unknown", with `noDns: true` when DNS had nothing either.
24
+ */
25
+ export function createEngine(options = {}) {
26
+ /* ── building blocks ── */
27
+ const store = safeStore(options.store ?? memoryStore(), options.keyPrefix ?? "");
28
+ const cache = new ResultCache(store, {
29
+ taken: options.ttl?.taken ?? DEFAULTS.ttlTaken,
30
+ available: options.ttl?.available ?? DEFAULTS.ttlAvailable,
31
+ });
32
+ const checkNs = createDns({
33
+ servers: options.dnsServers ?? [...DEFAULTS.dnsServers],
34
+ concurrency: options.dnsConcurrency ?? DEFAULTS.dnsConcurrency,
35
+ timeoutMs: options.dnsTimeoutMs ?? DEFAULTS.dnsTimeoutMs,
36
+ });
37
+ const rdap = createRdap({
38
+ store,
39
+ fetch: options.fetch ?? globalThis.fetch,
40
+ perHost: options.rdapPerHost ?? DEFAULTS.rdapPerHost,
41
+ maxRps: options.rdapRps ?? DEFAULTS.rdapRps,
42
+ timeoutMs: options.rdapTimeoutMs ?? DEFAULTS.rdapTimeoutMs,
43
+ overrides: { ...DEFAULT_RDAP_OVERRIDES, ...options.rdapOverrides },
44
+ bootstrapUrl: DEFAULTS.bootstrapUrl,
45
+ headers: options.userAgent ? { "user-agent": options.userAgent } : {},
46
+ });
47
+ const whois = createWhois({
48
+ store,
49
+ perHost: options.whoisPerHost ?? DEFAULTS.whoisPerHost,
50
+ timeoutMs: options.whoisTimeoutMs ?? DEFAULTS.whoisTimeoutMs,
51
+ servers: { ...DEFAULT_WHOIS_SERVERS, ...options.whoisServers },
52
+ });
53
+ /* ── registry check, shared between concurrent callers for the same domain ── */
54
+ const pendingVerdicts = new Map();
55
+ async function askRegistry(domain, signal) {
56
+ const tld = tldOf(domain);
57
+ const base = await rdap.baseUrl(tld);
58
+ if (base) {
59
+ const answer = await rdap.check(base, domain, signal);
60
+ if (answer !== "unknown") {
61
+ return { status: answer, source: "rdap" };
62
+ }
63
+ }
64
+ if (signal?.aborted) {
65
+ return { status: "unknown", source: "rdap" };
66
+ }
67
+ return { status: await whois.check(tld, domain), source: "whois" };
68
+ }
69
+ function askRegistryOnce(domain, signal) {
70
+ const pending = pendingVerdicts.get(domain);
71
+ if (pending) {
72
+ return pending;
73
+ }
74
+ const verdict = askRegistry(domain, signal).finally(() => pendingVerdicts.delete(domain));
75
+ pendingVerdicts.set(domain, verdict);
76
+ return verdict;
77
+ }
78
+ /* ── one uncached lookup: DNS, then the registry ── */
79
+ async function lookup(domain, signal) {
80
+ const dns = await checkNs(domain);
81
+ if (signal?.aborted) {
82
+ return null;
83
+ }
84
+ if (dns === "registered") {
85
+ return { domain, status: "taken", verified: true, source: "dns" };
86
+ }
87
+ const verdict = await askRegistryOnce(domain, signal);
88
+ if (signal?.aborted) {
89
+ return null;
90
+ }
91
+ if (verdict.status !== "unknown") {
92
+ return { domain, status: verdict.status, verified: true, source: verdict.source };
93
+ }
94
+ return { domain, status: "unknown", verified: false, source: verdict.source, noDns: dns === "nxdomain" };
95
+ }
96
+ /* ── public API ── */
97
+ async function checkMany(domains, onResult, { signal } = {}) {
98
+ const unique = normalize(domains);
99
+ const cached = await cache.getMany(unique);
100
+ const lookups = [];
101
+ for (const domain of unique) {
102
+ const hit = cached.get(domain);
103
+ if (hit) {
104
+ onResult({ domain, status: hit.status, verified: true, source: "cache" });
105
+ continue;
106
+ }
107
+ const work = lookup(domain, signal)
108
+ .then((result) => {
109
+ if (!result || signal?.aborted) {
110
+ return;
111
+ }
112
+ cache.remember(result);
113
+ onResult(result);
114
+ })
115
+ .catch(() => { }); // a single failed lookup must not reject the batch
116
+ lookups.push(work);
117
+ }
118
+ await Promise.all(lookups);
119
+ }
120
+ async function check(domain, opts = {}) {
121
+ let result;
122
+ await checkMany([domain], (r) => (result = r), opts);
123
+ if (!result) {
124
+ throw new Error(opts.signal?.aborted ? "aborted" : "lookup failed");
125
+ }
126
+ return result;
127
+ }
128
+ function stream(domains, opts = {}) {
129
+ return callbackToAsyncIterable((push) => checkMany(domains, push, opts));
130
+ }
131
+ return {
132
+ check,
133
+ checkMany,
134
+ stream,
135
+ warmup: rdap.warmup,
136
+ rdapBase: rdap.baseUrl,
137
+ };
138
+ }
139
+ /** Lower-cases, trims and de-duplicates; rejects anything that isn't "label.tld". */
140
+ function normalize(domains) {
141
+ const unique = [...new Set(domains.map((d) => d.trim().toLowerCase()))];
142
+ const invalid = unique.filter((d) => !isValidDomain(d));
143
+ if (invalid.length) {
144
+ throw new TypeError(`@mytld/engine: invalid domain(s): ${invalid.slice(0, 5).join(", ")}`);
145
+ }
146
+ return unique;
147
+ }
@@ -0,0 +1,65 @@
1
+ import type { CacheStore } from "../cache/store.js";
2
+ import type { DomainResult } from "../core/domain.js";
3
+ export interface EngineOptions {
4
+ /** Shared cache (results, IANA bootstrap, WHOIS servers, registry cooldowns). Default: in-memory. */
5
+ store?: CacheStore;
6
+ /** Prefix for every store key. Default: "". */
7
+ keyPrefix?: string;
8
+ /** Upstream DNS resolvers (IPs). Default: Cloudflare + Google. A local Unbound is ideal in production. */
9
+ dnsServers?: string[];
10
+ /** Max in-flight DNS queries. Default 256. */
11
+ dnsConcurrency?: number;
12
+ /** Per-query DNS timeout. Default 1200 ms. */
13
+ dnsTimeoutMs?: number;
14
+ /** Max concurrent requests per RDAP host. Default 6. */
15
+ rdapPerHost?: number;
16
+ /** Starting (and maximum) requests per second per RDAP host. Adapts down on 429. Default 8. */
17
+ rdapRps?: number;
18
+ /** RDAP request timeout. Default 4000 ms. */
19
+ rdapTimeoutMs?: number;
20
+ /** Extra / replacement RDAP base URLs by TLD (merged over the built-in overrides). */
21
+ rdapOverrides?: Record<string, string>;
22
+ /** Max concurrent connections per WHOIS server. Default 3. */
23
+ whoisPerHost?: number;
24
+ /** WHOIS socket timeout. Default 4000 ms. */
25
+ whoisTimeoutMs?: number;
26
+ /** Extra / replacement WHOIS servers by TLD (merged over the built-ins). */
27
+ whoisServers?: Record<string, string>;
28
+ /** Cache lifetimes in seconds for verified answers. */
29
+ ttl?: {
30
+ taken?: number;
31
+ available?: number;
32
+ };
33
+ /** Custom fetch (proxies, instrumentation). Default: global fetch. */
34
+ fetch?: typeof fetch;
35
+ /** Sent with HTTP requests to registries. */
36
+ userAgent?: string;
37
+ }
38
+ export interface CheckOptions {
39
+ signal?: AbortSignal;
40
+ }
41
+ export interface Engine {
42
+ /** Checks one domain and resolves with the final answer. */
43
+ check(domain: string, opts?: CheckOptions): Promise<DomainResult>;
44
+ /** Checks many domains concurrently; `onResult` fires as each answer is known. */
45
+ checkMany(domains: string[], onResult: (result: DomainResult) => void, opts?: CheckOptions): Promise<void>;
46
+ /** Same as checkMany, as an async iterator (results in completion order). */
47
+ stream(domains: string[], opts?: CheckOptions): AsyncIterable<DomainResult>;
48
+ /** Pre-loads the IANA RDAP bootstrap so the first lookup doesn't pay for it. */
49
+ warmup(): Promise<void>;
50
+ /** RDAP base URL for a TLD, or null if the registry has none. */
51
+ rdapBase(tld: string): Promise<string | null>;
52
+ }
53
+ export declare const DEFAULTS: {
54
+ readonly dnsServers: readonly ["1.1.1.1", "8.8.8.8", "1.0.0.1", "8.8.4.4"];
55
+ readonly dnsConcurrency: 256;
56
+ readonly dnsTimeoutMs: 1200;
57
+ readonly rdapPerHost: 6;
58
+ readonly rdapRps: 8;
59
+ readonly rdapTimeoutMs: 4000;
60
+ readonly bootstrapUrl: "https://data.iana.org/rdap/dns.json";
61
+ readonly whoisPerHost: 3;
62
+ readonly whoisTimeoutMs: 4000;
63
+ readonly ttlTaken: number;
64
+ readonly ttlAvailable: 600;
65
+ };
@@ -0,0 +1,13 @@
1
+ export const DEFAULTS = {
2
+ dnsServers: ["1.1.1.1", "8.8.8.8", "1.0.0.1", "8.8.4.4"],
3
+ dnsConcurrency: 256,
4
+ dnsTimeoutMs: 1200,
5
+ rdapPerHost: 6,
6
+ rdapRps: 8,
7
+ rdapTimeoutMs: 4000,
8
+ bootstrapUrl: "https://data.iana.org/rdap/dns.json",
9
+ whoisPerHost: 3,
10
+ whoisTimeoutMs: 4000,
11
+ ttlTaken: 6 * 3600,
12
+ ttlAvailable: 600,
13
+ };
@@ -0,0 +1,16 @@
1
+ /**
2
+ * @mytld/engine: fast, honest domain availability checks for Node.js.
3
+ *
4
+ * DNS (c-ares, hundreds in parallel) → RDAP → WHOIS
5
+ * "available" is only reported after a registry confirmed it.
6
+ *
7
+ * This is the Node-only entry. For browser-safe helpers import
8
+ * "@mytld/engine/domain" or "@mytld/engine/tlds".
9
+ */
10
+ export { createEngine } from "./engine/create-engine.js";
11
+ export type { CheckOptions, Engine, EngineOptions } from "./engine/options.js";
12
+ export { memoryStore, redisStore } from "./cache/store.js";
13
+ export type { CacheStore, RedisLike } from "./cache/store.js";
14
+ export { parseWhois } from "./lookup/whois-parser.js";
15
+ export * from "./core/domain.js";
16
+ export * from "./core/tlds.js";
package/dist/index.js ADDED
@@ -0,0 +1,14 @@
1
+ /**
2
+ * @mytld/engine: fast, honest domain availability checks for Node.js.
3
+ *
4
+ * DNS (c-ares, hundreds in parallel) → RDAP → WHOIS
5
+ * "available" is only reported after a registry confirmed it.
6
+ *
7
+ * This is the Node-only entry. For browser-safe helpers import
8
+ * "@mytld/engine/domain" or "@mytld/engine/tlds".
9
+ */
10
+ export { createEngine } from "./engine/create-engine.js";
11
+ export { memoryStore, redisStore } from "./cache/store.js";
12
+ export { parseWhois } from "./lookup/whois-parser.js";
13
+ export * from "./core/domain.js";
14
+ export * from "./core/tlds.js";
@@ -0,0 +1,21 @@
1
+ /**
2
+ * - `registered`: the TLD zone delegates the name (NS records exist). Final answer: taken.
3
+ * - `nxdomain`: no such name in DNS. This does NOT mean free (see create-engine.ts).
4
+ * - `unknown`: no usable answer (timeout, SERVFAIL, NODATA).
5
+ */
6
+ export type DnsSignal = "registered" | "nxdomain" | "unknown";
7
+ export interface DnsOptions {
8
+ servers: string[];
9
+ concurrency: number;
10
+ timeoutMs: number;
11
+ }
12
+ /**
13
+ * Creates an NS-record checker.
14
+ *
15
+ * Uses `dns.promises.Resolver` (c-ares) instead of `dns.lookup()`. lookup() runs
16
+ * getaddrinfo on libuv's threadpool (4 threads by default), so hundreds of queries
17
+ * would wait in line. c-ares sends them all concurrently from the event loop.
18
+ *
19
+ * Queries are spread round-robin across the configured resolvers.
20
+ */
21
+ export declare function createDns({ servers, concurrency, timeoutMs }: DnsOptions): (domain: string) => Promise<DnsSignal>;
@@ -0,0 +1,57 @@
1
+ import { Resolver } from "node:dns/promises";
2
+ import { Semaphore } from "../throttle/semaphore.js";
3
+ /** Errors that say "this resolver didn't answer", not "the name doesn't exist". */
4
+ const TRANSIENT_ERRORS = new Set(["ETIMEOUT", "ECONNREFUSED", "ESERVFAIL"]);
5
+ /**
6
+ * Creates an NS-record checker.
7
+ *
8
+ * Uses `dns.promises.Resolver` (c-ares) instead of `dns.lookup()`. lookup() runs
9
+ * getaddrinfo on libuv's threadpool (4 threads by default), so hundreds of queries
10
+ * would wait in line. c-ares sends them all concurrently from the event loop.
11
+ *
12
+ * Queries are spread round-robin across the configured resolvers.
13
+ */
14
+ export function createDns({ servers, concurrency, timeoutMs }) {
15
+ if (!servers.length) {
16
+ throw new Error("@mytld/engine: at least one DNS server is required");
17
+ }
18
+ const resolvers = servers.map((server) => {
19
+ const resolver = new Resolver({ timeout: timeoutMs, tries: 1 });
20
+ resolver.setServers([server]);
21
+ return resolver;
22
+ });
23
+ const gate = new Semaphore(concurrency);
24
+ let nextResolver = 0;
25
+ return function checkNs(domain) {
26
+ return gate.run(async () => {
27
+ const index = nextResolver++;
28
+ const first = await queryNs(resolvers[index % resolvers.length], domain);
29
+ if (first !== "transient-error" || resolvers.length === 1) {
30
+ return orUnknown(first);
31
+ }
32
+ // Public resolvers occasionally drop bursts: retry once on a different upstream.
33
+ const second = await queryNs(resolvers[(index + 1) % resolvers.length], domain);
34
+ return orUnknown(second);
35
+ });
36
+ };
37
+ }
38
+ async function queryNs(resolver, domain) {
39
+ try {
40
+ const records = await resolver.resolveNs(domain);
41
+ return records.length ? "registered" : "unknown";
42
+ }
43
+ catch (err) {
44
+ const code = err.code ?? "";
45
+ if (code === "ENOTFOUND") {
46
+ return "nxdomain";
47
+ }
48
+ if (TRANSIENT_ERRORS.has(code)) {
49
+ return "transient-error";
50
+ }
51
+ // e.g. ENODATA: the name exists without NS records. Let the registry decide.
52
+ return "unknown";
53
+ }
54
+ }
55
+ function orUnknown(result) {
56
+ return result === "transient-error" ? "unknown" : result;
57
+ }
@@ -0,0 +1,18 @@
1
+ import type { SafeStore } from "../cache/safe-store.js";
2
+ /** TLD → RDAP base URL, always with a trailing slash. */
3
+ export type Bootstrap = Record<string, string>;
4
+ export interface BootstrapLoaderOptions {
5
+ store: SafeStore;
6
+ fetch: typeof fetch;
7
+ url: string;
8
+ headers: Record<string, string>;
9
+ }
10
+ /**
11
+ * Loads the IANA RDAP bootstrap (dns.json) at most once per day, through the shared store.
12
+ *
13
+ * Concurrent callers share one in-flight request. While a stale copy is being
14
+ * refreshed, the stale copy keeps being served.
15
+ */
16
+ export declare function createBootstrapLoader({ store, fetch, url, headers }: BootstrapLoaderOptions): {
17
+ get: () => Promise<Bootstrap>;
18
+ };
@@ -0,0 +1,56 @@
1
+ const CACHE_KEY = "rdap:bootstrap:v1";
2
+ const TTL_SEC = 24 * 3600;
3
+ const FETCH_TIMEOUT_MS = 5000;
4
+ /**
5
+ * Loads the IANA RDAP bootstrap (dns.json) at most once per day, through the shared store.
6
+ *
7
+ * Concurrent callers share one in-flight request. While a stale copy is being
8
+ * refreshed, the stale copy keeps being served.
9
+ */
10
+ export function createBootstrapLoader({ store, fetch, url, headers }) {
11
+ let cached = null;
12
+ let loadedAt = 0;
13
+ let inflight = null;
14
+ async function fetchFromIana() {
15
+ const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), headers });
16
+ if (!res.ok) {
17
+ throw new Error(`IANA bootstrap ${res.status}`);
18
+ }
19
+ const file = (await res.json());
20
+ return indexByTld(file);
21
+ }
22
+ function isFresh() {
23
+ return cached !== null && Date.now() - loadedAt < TTL_SEC * 1000;
24
+ }
25
+ function get() {
26
+ if (isFresh()) {
27
+ return Promise.resolve(cached);
28
+ }
29
+ inflight ??= store
30
+ .json(CACHE_KEY, TTL_SEC, fetchFromIana)
31
+ .then((loaded) => {
32
+ cached = loaded;
33
+ loadedAt = Date.now();
34
+ return loaded;
35
+ })
36
+ .finally(() => {
37
+ inflight = null;
38
+ });
39
+ return cached ? Promise.resolve(cached) : inflight;
40
+ }
41
+ return { get };
42
+ }
43
+ function indexByTld(file) {
44
+ const byTld = {};
45
+ for (const [tlds, urls] of file.services) {
46
+ const url = urls.find((u) => u.startsWith("https://")) ?? urls[0];
47
+ if (!url) {
48
+ continue;
49
+ }
50
+ const base = url.endsWith("/") ? url : `${url}/`;
51
+ for (const tld of tlds) {
52
+ byTld[tld.toLowerCase()] = base;
53
+ }
54
+ }
55
+ return byTld;
56
+ }
@@ -0,0 +1,22 @@
1
+ import type { SafeStore } from "../cache/safe-store.js";
2
+ export type RdapAnswer = "available" | "taken" | "unknown";
3
+ export interface RdapOptions {
4
+ store: SafeStore;
5
+ fetch: typeof fetch;
6
+ /** Max concurrent requests per RDAP host. */
7
+ perHost: number;
8
+ /** Starting (and maximum) requests per second per host. */
9
+ maxRps: number;
10
+ timeoutMs: number;
11
+ /** TLD → RDAP base URL, checked before the IANA bootstrap. */
12
+ overrides: Record<string, string>;
13
+ bootstrapUrl: string;
14
+ headers: Record<string, string>;
15
+ }
16
+ /** Registries with working RDAP that are missing from the IANA bootstrap. */
17
+ export declare const DEFAULT_RDAP_OVERRIDES: Record<string, string>;
18
+ export declare function createRdap(options: RdapOptions): {
19
+ baseUrl: (tld: string) => Promise<string | null>;
20
+ check: (base: string, domain: string, signal?: AbortSignal) => Promise<RdapAnswer>;
21
+ warmup: () => Promise<void>;
22
+ };
@@ -0,0 +1,107 @@
1
+ import { HostThrottle } from "../throttle/host-throttle.js";
2
+ import { keyedSemaphore } from "../throttle/semaphore.js";
3
+ import { createBootstrapLoader } from "./rdap-bootstrap.js";
4
+ /** Registries with working RDAP that are missing from the IANA bootstrap. */
5
+ export const DEFAULT_RDAP_OVERRIDES = {
6
+ de: "https://rdap.denic.de/",
7
+ ch: "https://rdap.nic.ch/",
8
+ li: "https://rdap.nic.ch/",
9
+ };
10
+ /** A 429 with a Retry-After longer than this puts the whole host into cooldown. */
11
+ const COOLDOWN_THRESHOLD_SEC = 3;
12
+ export function createRdap(options) {
13
+ const bootstrap = createBootstrapLoader({
14
+ store: options.store,
15
+ fetch: options.fetch,
16
+ url: options.bootstrapUrl,
17
+ headers: options.headers,
18
+ });
19
+ const throttle = new HostThrottle(options.store, options.maxRps);
20
+ const hostSlots = keyedSemaphore(options.perHost);
21
+ /** RDAP base URL for a TLD, or null if the registry has no RDAP service. */
22
+ async function baseUrl(tld) {
23
+ if (options.overrides[tld]) {
24
+ return options.overrides[tld];
25
+ }
26
+ try {
27
+ const byTld = await bootstrap.get();
28
+ return byTld[tld] ?? null;
29
+ }
30
+ catch {
31
+ return null;
32
+ }
33
+ }
34
+ /** Asks the registry about `domain`. A short rate limit gets exactly one retry. */
35
+ async function check(base, domain, signal) {
36
+ const host = new URL(base).host;
37
+ const url = `${base}domain/${domain}`;
38
+ const first = await attempt(host, url, signal);
39
+ if (first !== "retry") {
40
+ return first;
41
+ }
42
+ const second = await attempt(host, url, signal);
43
+ return second === "retry" ? "unknown" : second;
44
+ }
45
+ async function attempt(host, url, signal) {
46
+ if (await throttle.isCoolingDown(host)) {
47
+ return "unknown";
48
+ }
49
+ const delayMs = throttle.reserveSlot(host);
50
+ if (delayMs === null) {
51
+ return "unknown"; // queue too long: let WHOIS answer instead
52
+ }
53
+ if (delayMs > 0) {
54
+ await sleep(delayMs);
55
+ }
56
+ return hostSlots(host).run(async () => {
57
+ // Re-check: a sibling request may have triggered a cooldown while we waited.
58
+ if (signal?.aborted || throttle.isCoolingDownLocally(host)) {
59
+ return "unknown";
60
+ }
61
+ try {
62
+ const res = await options.fetch(url, {
63
+ headers: { accept: "application/rdap+json", ...options.headers },
64
+ redirect: "follow",
65
+ signal: withTimeout(signal, options.timeoutMs),
66
+ });
67
+ // We only need the status. Releasing the body keeps the socket reusable.
68
+ res.body?.cancel().catch(() => { });
69
+ return interpretResponse(host, res);
70
+ }
71
+ catch {
72
+ return "unknown";
73
+ }
74
+ });
75
+ }
76
+ function interpretResponse(host, res) {
77
+ if (res.status === 404) {
78
+ throttle.recordSuccess(host);
79
+ return "available";
80
+ }
81
+ if (res.ok) {
82
+ throttle.recordSuccess(host);
83
+ return "taken";
84
+ }
85
+ if (res.status === 429) {
86
+ throttle.recordRateLimited(host);
87
+ const retryAfterSec = Number(res.headers.get("retry-after"));
88
+ if (retryAfterSec > COOLDOWN_THRESHOLD_SEC) {
89
+ throttle.coolDown(host, retryAfterSec);
90
+ return "unknown";
91
+ }
92
+ return "retry";
93
+ }
94
+ return "unknown"; // 400 (query not supported), 5xx
95
+ }
96
+ async function warmup() {
97
+ await bootstrap.get();
98
+ }
99
+ return { baseUrl, check, warmup };
100
+ }
101
+ function withTimeout(signal, ms) {
102
+ const timeout = AbortSignal.timeout(ms);
103
+ return signal ? AbortSignal.any([signal, timeout]) : timeout;
104
+ }
105
+ function sleep(ms) {
106
+ return new Promise((resolve) => setTimeout(resolve, ms));
107
+ }
@@ -0,0 +1,9 @@
1
+ export type WhoisAnswer = "available" | "taken" | "unknown";
2
+ /**
3
+ * Classifies a raw WHOIS reply.
4
+ *
5
+ * "taken" requires positive evidence: an unparseable reply is "unknown", never a guess.
6
+ */
7
+ export declare function parseWhois(reply: string): WhoisAnswer;
8
+ /** Some registries need a special query syntax. */
9
+ export declare function formatQuery(tld: string, domain: string): string;
@@ -0,0 +1,64 @@
1
+ /*
2
+ * WHOIS has no standard format. These patterns cover the registries we query.
3
+ */
4
+ const NOT_FOUND = new RegExp([
5
+ "no match",
6
+ "not[ _]found",
7
+ "no data (was )?found",
8
+ "no entries found",
9
+ "nothing found",
10
+ "status:\\s*(free|available)",
11
+ "no object found",
12
+ "is free",
13
+ "not registered",
14
+ "not been registered",
15
+ "no such domain",
16
+ "we do not have an entry",
17
+ "no information available",
18
+ "object does not exist",
19
+ "available for registration",
20
+ "does not exist",
21
+ ].join("|"), "i");
22
+ const RATE_LIMITED = new RegExp(["exceeded", "too many", "quota", "try again later", "access denied", "blacklisted", "not permitted", "not allowed"].join("|"), "i");
23
+ const REGISTERED = new RegExp([
24
+ "domain name:",
25
+ "registrar:",
26
+ "registrar\\b",
27
+ "creation date",
28
+ "created:",
29
+ "registered:",
30
+ "registration date",
31
+ "status:\\s*(active|connect|registered|ok)",
32
+ "nserver:",
33
+ "name servers?:",
34
+ "holder:",
35
+ "registrant",
36
+ ].join("|"), "i");
37
+ /**
38
+ * Classifies a raw WHOIS reply.
39
+ *
40
+ * "taken" requires positive evidence: an unparseable reply is "unknown", never a guess.
41
+ */
42
+ export function parseWhois(reply) {
43
+ if (!reply.trim()) {
44
+ return "unknown";
45
+ }
46
+ if (NOT_FOUND.test(reply)) {
47
+ return "available";
48
+ }
49
+ if (RATE_LIMITED.test(reply)) {
50
+ return "unknown";
51
+ }
52
+ return REGISTERED.test(reply) ? "taken" : "unknown";
53
+ }
54
+ /** Some registries need a special query syntax. */
55
+ export function formatQuery(tld, domain) {
56
+ switch (tld) {
57
+ case "de":
58
+ return `-T dn,ace ${domain}`; // DENIC: domain info, ASCII/punycode
59
+ case "jp":
60
+ return `${domain}/e`; // JPRS: English output
61
+ default:
62
+ return domain;
63
+ }
64
+ }
@@ -0,0 +1,17 @@
1
+ import type { SafeStore } from "../cache/safe-store.js";
2
+ import { type WhoisAnswer } from "./whois-parser.js";
3
+ export type { WhoisAnswer } from "./whois-parser.js";
4
+ export interface WhoisOptions {
5
+ store: SafeStore;
6
+ /** Max concurrent connections per WHOIS server. */
7
+ perHost: number;
8
+ timeoutMs: number;
9
+ /** TLD → WHOIS server, checked before discovery via whois.iana.org. */
10
+ servers: Record<string, string>;
11
+ }
12
+ /** Well-known servers. Everything else is discovered via whois.iana.org. */
13
+ export declare const DEFAULT_WHOIS_SERVERS: Record<string, string>;
14
+ export declare function createWhois(options: WhoisOptions): {
15
+ check: (tld: string, domain: string) => Promise<WhoisAnswer>;
16
+ serverFor: (tld: string) => Promise<string | null>;
17
+ };