IPv6-dns-server AGENTS.md

Provider Integration Notes

These notes capture the patterns and conventions used in this repo so new providers can be added consistently.

Where provider logic lives

• providers/*.js contains provider detection and IPv6 generation helpers.
• app.js wires providers into AAAA and A record flows via data-driven registries.
• tests/*.js contains simple Node assertions for provider utilities.

Architecture

Provider detection in app.js uses three registry arrays:

• AAAA_PROVIDERS — 27 entries, each with detect(ctx) and resolve(ctx, result, cb). The processAAAAProviders(ctx) loop iterates these and stops at the first match. This eliminates missing-return bugs by design.
• A_IP_PROVIDERS — 13 entries for IP-range detection in A-record responses. Each has check(ip) and a tag (string or function).
• A_HOSTNAME_PROVIDERS — 11 entries for hostname-based detection in A-record responses. Each has check(hostname) and a tag.

The add_aaaa switch statement sets flags on a detected object. Provider registry entries check these flags first (ctx.detected.<name>) before running auto-detection.

Adding a new provider

AAAA provider (synthesizes AAAA from CNAME/A)

1. Add require('./providers/<name>') at the top of app.js.
2. Add a case '<name>' in the switch (lines ~475-565) to set detected.<name> = true.
3. Add an entry to AAAA_PROVIDERS:

   { name: '<name>',
     detect: (ctx) => ctx.detected.<name> || provider.check_for_<name>_hostname(ctx.last_hostname),
     resolve: (ctx, r, cb) => asyncDNSAndRespond(ctx, provider.get<v6>address) },
   

   Use the appropriate resolve helper: resolve6AndRespond, asyncDNSAndRespond, staticV6AndRespond, or resolve4AndMapV6.

A-record IP provider (detects CDN from A record IP)

Add to A_IP_PROVIDERS:

{ check: (ip) => provider.check_for_<name>_ip(ip), tag: '<name>' },

A-record hostname provider (detects CDN from hostname pattern)

Add to A_HOSTNAME_PROVIDERS:

{ check: (h) => provider.check_for_<name>_hostname(h), tag: '<name>' },