NEW MACROS: DOMAIN_ELSEWHERE and DOMAIN_ELSEWHERE_AUTO (#1237)

* NEW MACROS: DOMAIN_ELSEWHERE and DOMAIN_ELSEWHERE_AUTO
* Finish docs

docs/_functions/global/DOMAIN_ELSEWHERE.md

@@ -0,0 +1,34 @@
+---
+name: DOMAIN_ELSEWHERE
+parameters:
+  - registrar
+  - list of nameserver names
+---
+
+`DOMAIN_ELSEWHERE()` is a helper macro that lets you easily indicate that
+a domain's zones are managed elsewhere. That is, it permits you easily delegate
+a domain to a hard-coded list of DNS servers.
+
+`DOMAIN_ELSEWHERE` is useful when you control a domain's registrar but not the
+DNS servers. For example, suppose you own a domain but the DNS servers are run
+by someone else, perhaps a SaaS product you've subscribed to or a DNS server
+that is run by your brother-in-law who doesn't trust you with the API keys that
+would let you maintain the domain using DNSControl. You need an easy way to
+point (delegate) the domain at a specific list of DNS servers.
+
+For example these two statements are equivalent:
+
+```
+DOMAIN_ELSEWHERE("example.com", REG_NAMEDOTCOM, ["ns1.foo.com", "ns2.foo.com"]);
+
+# ...is equivalent to...
+
+D("example.com", REG_NAMEDOTCOM,
+    NO_PURGE,
+    NAMESERVER("ns1.foo.com"),
+    NAMESERVER("ns2.foo.com")
+);
+```
+
+NOTE: The `NO_PURGE` is used out of abundance of caution but since no
+`DnsProvider()` statements exist, no updates would be performed.

docs/_functions/global/DOMAIN_ELSEWHERE_AUTO.md

@@ -0,0 +1,35 @@
+---
+name: DOMAIN_ELSEWHERE_AUTO
+parameters:
+  - registrar
+  - list of Dns Providers
+---
+
+`DOMAIN_ELSEWHERE_AUTO()` is similar to `DOMAIN_ELSEWHERE()` but instead of
+a hardcoded list of nameservers, a DnsProvider() is queried.
+
+`DOMAIN_ELSEWHERE_AUTO` is useful when you control a domain's registrar but the
+DNS zones are managed by another system. Luckily you have enough access to that
+other system that you can query it to determine the zone's nameservers.
+
+For example, suppose you own a domain but the DNS servers for it are in Azure.
+Further suppose that something in Azure maintains the zones (automatic or
+human). Azure picks the nameservers for the domains automatically, and that
+list may change occasionally.  `DOMAIN_ELSEWHERE_AUTO` allows you to easily
+query Azure to determine the domain's delegations so that you do not need to
+hard-code them in your dnsconfig.js file.
+
+For example these two statements are equivalent:
+
+```
+DOMAIN_ELSEWHERE_AUTO("example.com", REG_NAMEDOTCOM, DSP_AZURE);
+
+# ...is equivalent to...
+
+D("example.com", REG_NAMEDOTCOM,
+    NO_PURGE,
+    DnsProvider(DSP_AZURE)
+);
+```
+
+NOTE: The `NO_PURGE` is used to prevent DNSControl from changing the records.

docs/nameservers.md

@@ -130,6 +130,23 @@ D("example1.com", REG_NAMECOM,
   A("@", "10.2.3.4")
 );
 
+// ========== Fancy macros
+
+// There are some built-in macros that you might find useful.
+
+// DOMAIN_ELSEWHERE: This macro points the domain's delegation
+// (nameservers) to a list of DNS servers.
+DOMAIN_ELSEWHERE("example1.com", REG_NAMECOM, [
+    "dns1.example.net.",
+    "dns2.example.net.",
+    "dns3.example.net.",
+]);
+
+// DOMAIN_ELSEWHERE_AUTO: Similar to DOMAIN_ELSEWHERE but the list
+// of nameservers is queried from the API of a DNS provider.
+DOMAIN_ELSEWHERE_AUTO("example1.com", REG_NAMECOM, DNS_AWS);
+DOMAIN_ELSEWHERE_AUTO("example2.com", REG_NAMECOM, DNS_GOOGLE);
+
 {%endhighlight%}
 {% include endExample.html %}
 

pkg/js/helpers.js

@@ -1136,3 +1136,32 @@ function CLI_DEFAULTS(defaults) {
 function FETCH() {
     return fetch.apply(null, arguments).catch(PANIC);
 }
+
+// DOMAIN_ELSEWHERE is a helper macro that delegates a domain to a
+// static list of nameservers.  It updates the registrar (the parent)
+// with a list of nameservers.  This is used when we own the domain (we
+// control the registrar) but something else controls the DNS records
+// (often a third-party of Azure).
+// Usage: DOMAIN_ELSEWHERE("example.com", REG_NAMEDOTCOM, ["ns1.foo.com", "ns2.foo.com"]);
+function DOMAIN_ELSEWHERE(domain, registrar, nslist) {
+    D(domain, registrar, NO_PURGE);
+    // NB(tlim): NO_PURGE is added as a precaution since something else
+    // is maintaining the DNS records in that zone.  In theory this is
+    // not needed since this domain won't have a DSP defined.
+    for (i = 0; i < nslist.length; i++) {
+        D_EXTEND(domain, NAMESERVER(nslist[i]));
+    }
+}
+
+// DOMAIN_ELSEWHERE_AUTO is similar to DOMAIN_ELSEWHERE but the list of
+// nameservers is queried from a DNS Service Provider.
+// Usage: DOMAIN_ELSEWHERE_AUTO("example.com", REG_NAMEDOTCOM, DNS_FOO)
+function DOMAIN_ELSEWHERE_AUTO(domain, registrar, dsplist) {
+    D(domain, registrar, NO_PURGE);
+    // NB(tlim): NO_PURGE is required since something else
+    // is maintaining the DNS records in that zone, and we have access
+    // to updating it (but we don't want to use it.)
+    for (i = 2; i < arguments.length; i++) {
+        D_EXTEND(domain, DnsProvider(arguments[i]));
+    }
+}