NEW FEATURE: Add RFC4183 support to REV() (#2879)

Co-authored-by: Thomas Misilo <[email protected]>
Co-authored-by: Jeffrey Cafferata <[email protected]>

.goreleaser.yml

@@ -159,8 +159,9 @@ release:
     ## Deprecation warnings
 
     > [!WARNING]
+    > - **REV() will switch from RFC2317 to RFC4183 in v5.0.**  This is a breaking change. Warnings are output if your configuration is affected. No date has been announced for v5.0. See https://docs.dnscontrol.org/language-reference/top-level-functions/revcompat
     > - **MSDNS maintainer needed!** Without a new volunteer, this DNS provider will lose support after April 2025. See https://github.com/StackExchange/dnscontrol/issues/2878
-    > - **Call for new volunteer maintainers for NAMEDOTCOM and SOFTLAYER.** These providers have no maintainer. Maintainers respond to PRs and fix bugs in a timely manner, and try to stay on top of protocol changes.
+    > - **NAMEDOTCOM and SOFTLAYER need maintainers!** These providers have no maintainer. Maintainers respond to PRs and fix bugs in a timely manner, and try to stay on top of protocol changes.
     > - **get-certs/ACME support is frozen and will be removed without notice between now and July 2025.** It has been unsupported since December 2022.  If you don't use this feature, do not start. If you do use this feature, migrate ASAP.  See discussion in [issues/1400](https://github.com/StackExchange/dnscontrol/issues/1400)
 
     ## Install

README.md

@@ -160,8 +160,9 @@ See [dnscontrol-action](https://github.com/koenrh/dnscontrol-action) or [gacts/i
 
 ## Deprecation warnings (updated 2024-03-25)
 
+- **REV() will switch from RFC2317 to RFC4183 in v5.0.**  This is a breaking change. Warnings are output if your configuration is affected. No date has been announced for v5.0. See https://docs.dnscontrol.org/language-reference/top-level-functions/revcompat
 - **MSDNS maintainer needed!** Without a new volunteer, this DNS provider will lose support after April 2025. See https://github.com/StackExchange/dnscontrol/issues/2878
-- **Call for new volunteer maintainers for NAMEDOTCOM and SOFTLAYER.** These providers have no maintainer. Maintainers respond to PRs and fix bugs in a timely manner, and try to stay on top of protocol changes.
+- **NAMEDOTCOM and SOFTLAYER need maintainers!** These providers have no maintainer. Maintainers respond to PRs and fix bugs in a timely manner, and try to stay on top of protocol changes.
 - **get-certs/ACME support is frozen and will be removed without notice between now and July 2025.** It has been unsupported since December 2022.  If you don't use this feature, do not start. If you do use this feature, migrate ASAP.  See discussion in [issues/1400](https://github.com/StackExchange/dnscontrol/issues/1400)
 
 ## More info at our website

commands/ppreviewPush.go

@@ -15,6 +15,7 @@ import (
 	"github.com/StackExchange/dnscontrol/v4/pkg/normalize"
 	"github.com/StackExchange/dnscontrol/v4/pkg/notifications"
 	"github.com/StackExchange/dnscontrol/v4/pkg/printer"
+	"github.com/StackExchange/dnscontrol/v4/pkg/rfc4183"
 	"github.com/StackExchange/dnscontrol/v4/pkg/zonerecs"
 	"github.com/StackExchange/dnscontrol/v4/providers"
 	"github.com/urfave/cli/v2"
@@ -257,6 +258,7 @@ func prun(args PPreviewArgs, push bool, interactive bool, out printer.CLI, repor
 	if os.Getenv("TEAMCITY_VERSION") != "" {
 		fmt.Fprintf(os.Stderr, "##teamcity[buildStatus status='SUCCESS' text='%d corrections']", totalCorrections)
 	}
+	rfc4183.PrintWarning()
 	notifier.Done()
 	out.Printf("Done. %d corrections.\n", totalCorrections)
 	err = writeReport(report, reportItems)

commands/previewPush.go

@@ -16,6 +16,7 @@ import (
 	"github.com/StackExchange/dnscontrol/v4/pkg/normalize"
 	"github.com/StackExchange/dnscontrol/v4/pkg/notifications"
 	"github.com/StackExchange/dnscontrol/v4/pkg/printer"
+	"github.com/StackExchange/dnscontrol/v4/pkg/rfc4183"
 	"github.com/StackExchange/dnscontrol/v4/pkg/zonerecs"
 	"github.com/StackExchange/dnscontrol/v4/providers"
 	"github.com/urfave/cli/v2"
@@ -293,6 +294,7 @@ func run(args PreviewArgs, push bool, interactive bool, out printer.CLI, report
 	if os.Getenv("TEAMCITY_VERSION") != "" {
 		fmt.Fprintf(os.Stderr, "##teamcity[buildStatus status='SUCCESS' text='%d corrections']", totalCorrections)
 	}
+	rfc4183.PrintWarning()
 	notifier.Done()
 	out.Printf("Done. %d corrections.\n", totalCorrections)
 	if anyErrors {

commands/printIR.go

@@ -10,6 +10,7 @@ import (
 	"github.com/StackExchange/dnscontrol/v4/models"
 	"github.com/StackExchange/dnscontrol/v4/pkg/js"
 	"github.com/StackExchange/dnscontrol/v4/pkg/normalize"
+	"github.com/StackExchange/dnscontrol/v4/pkg/rfc4183"
 	"github.com/urfave/cli/v2"
 )
 
@@ -58,6 +59,7 @@ var _ = cmd(catDebug, func() *cli.Command {
 			log.SetOutput(os.Stdout)
 
 			err := exit(PrintIR(pargs))
+			rfc4183.PrintWarning()
 			if err == nil {
 				fmt.Fprintf(os.Stdout, "No errors.\n")
 			}

commands/types/dnscontrol.d.ts

@@ -2214,7 +2214,7 @@ declare function PANIC(message: string): never;
  *
  * Target should be a string representing the FQDN of a host.  Like all FQDNs in DNSControl, it must end with a `.`.
  *
- * **Magic Mode:**
+ * # Magic Mode
  *
  * PTR records are complex and typos are common. Therefore DNSControl
  * enables features to save labor and
@@ -2282,9 +2282,33 @@ declare function PANIC(message: string): never;
  * );
  * ```
  *
- * In the future we plan on adding a flag to [`A()`](A.md) which will insert
- * the correct PTR() record if the appropriate `.arpa` domain has been
- * defined.
+ * # Automatic forward and reverse lookups
+ *
+ * DNSControl does not automatically generate forward and reverse lookups. However
+ * it is possible to write a macro that does this by using the
+ * [`D_EXTEND()`](../global/D_EXTEND.md)
+ * function to insert `A` and `PTR` records into previously-defined domains.
+ *
+ * ```javascript
+ * function FORWARD_AND_REVERSE(ipaddr, fqdn) {
+ *     D_EXTEND(dom,
+ *         A(fqdn, ipaddr)
+ *     );
+ *     D_EXTEND(REV(ipaddr),
+ *         PTR(ipaddr, fqdn)
+ *     );
+ * }
+ *
+ * D("example.com", REGISTRAR, DnsProvider(DSP_NONE),
+ *     ...,
+ *     END);
+ * D(REV("10.20.30.0/24"), REGISTRAR, DnsProvider(DSP_NONE),
+ *     ...,
+ *     END);
+ *
+ * FORWARD_AND_REVERSE("10.20.30.77", "foo.example.com.");
+ * FORWARD_AND_REVERSE("10.20.30.99", "bar.example.com.");
+ * ```
  *
  * @see https://docs.dnscontrol.org/language-reference/domain-modifiers/ptr
  */
@@ -2395,53 +2419,115 @@ declare function R53_ZONE(zone_id: string): DomainModifier & RecordModifier;
  * `REV` returns the reverse lookup domain for an IP network. For
  * example `REV("1.2.3.0/24")` returns `3.2.1.in-addr.arpa.` and
  * `REV("2001:db8:302::/48")` returns `2.0.3.0.8.b.d.0.1.0.0.2.ip6.arpa.`.
- * This is used in [`D()`](D.md) functions to create reverse DNS lookup zones.
  *
- * This is a convenience function. You could specify `D("3.2.1.in-addr.arpa",
- * ...` if you like to do things manually but why would you risk making
- * typos?
+ * `REV()` is commonly used with the [`D()`](D.md) functions to create reverse DNS lookup zones.
  *
- * `REV` complies with RFC2317, "Classless in-addr.arpa delegation"
- * for netmasks of size /25 through /31.
- * While the RFC permits any format, we abide by the recommended format:
- * `FIRST/MASK.C.B.A.in-addr.arpa` where `FIRST` is the first IP address
- * of the zone, `MASK` is the netmask of the zone (25-31 inclusive),
- * and A, B, C are the first 3 octets of the IP address. For example
- * `172.20.18.130/27` is located in a zone named
- * `128/27.18.20.172.in-addr.arpa`
+ * These two are equivalent:
+ *
+ * ```javascript
+ * D("3.2.1.in-addr.arpa", ...
+ * ```
+ *
+ * ```javascript
+ * D(REV("1.2.3.0/24", ...
+ * ```
+ *
+ * The latter is easier to type and less error-prone.
  *
- * If the address does not include a "/" then `REV` assumes /32 for IPv4 addresses
+ * If the address does not include a "/" then `REV()` assumes /32 for IPv4 addresses
  * and /128 for IPv6 addresses.
  *
- * Note that the lower bits (the ones outside the netmask) must be zeros. They are not
- * zeroed out automatically. Thus, `REV("1.2.3.4/24")` is an error.  This is done
- * to catch typos.
+ * # RFC compliance
+ *
+ * `REV()` implements both RFC 2317 and the newer RFC 4183. The `REVCOMPAT()`
+ * function selects which mode is used. If `REVCOMPAT()` is not called, a default
+ * is selected for you.  The default will change to RFC 4183 in DNSControl v5.0.
+ *
+ * See [`REVCOMPAT()`](REVCOMPAT.md) for details.
+ *
+ * # Host bits
+ *
+ * v4.x:
+ * The host bits (the ones outside the netmask) must be zeros. They are not zeroed
+ * out automatically. Thus, `REV("1.2.3.4/24")` is an error.
+ *
+ * v5.0 and later:
+ * The host bits (the ones outside the netmask) are ignored.  Thus
+ * `REV("1.2.3.4/24")` and `REV("1.2.3.0/24")` are equivalent.
+ *
+ * # Examples
+ *
+ * Here's an example reverse lookup domain:
  *
  * ```javascript
  * D(REV("1.2.3.0/24"), REGISTRAR, DnsProvider(BIND),
  *   PTR("1", "foo.example.com."),
  *   PTR("2", "bar.example.com."),
  *   PTR("3", "baz.example.com."),
- *   // These take advantage of DNSControl's ability to generate the right name:
+ *   // If the first parameter is an IP address, DNSControl automatically calls REV() for you.
  *   PTR("1.2.3.10", "ten.example.com."),
  * );
  *
  * D(REV("2001:db8:302::/48"), REGISTRAR, DnsProvider(BIND),
  *   PTR("1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0", "foo.example.com."),  // 2001:db8:302::1
- *   // These take advantage of DNSControl's ability to generate the right name:
+ *   // If the first parameter is an IP address, DNSControl automatically calls REV() for you.
  *   PTR("2001:db8:302::2", "two.example.com."),                          // 2.0.0...
  *   PTR("2001:db8:302::3", "three.example.com."),                        // 3.0.0...
  * );
  * ```
  *
- * In the future we plan on adding a flag to [`A()`](../domain/A.md)which will insert
- * the correct PTR() record in the appropriate `D(REV())` domain (i.e. `.arpa` domain) has been
- * defined.
+ * # Automatic forward and reverse record generation
+ *
+ * DNSControl does not automatically generate forward and reverse lookups. However
+ * it is possible to write a macro that does this.  See
+ * [`PTR()`](../domain/PTR.md)   for an example.
  *
  * @see https://docs.dnscontrol.org/language-reference/top-level-functions/rev
  */
 declare function REV(address: string): string;
 
+/**
+ * `REVCOMPAT()` controls which RFC the [`REV()`](REV.md) function adheres to.
+ *
+ * Include one of these two commands near the top `dnsconfig.js` (at the global level):
+ *
+ * ```javascript
+ * REVCOMPAT("rfc2317");  // RFC 2117: Compatible with old files.
+ * REVCOMPAT("rfc4183");  // RFC 4183: Adopt the newer standard.
+ * ```
+ *
+ * `REVCOMPAT()` is global for all of `dnsconfig.js`. It must appear before any
+ * use of `REV()`; If not, behavior is undefined.
+ *
+ * # RFC 4183 vs RFC 2317
+ *
+ * RFC 2317 and RFC 4183 are two different ways to implement reverse lookups for
+ * CIDR blocks that are not on 8-bit boundaries (/24, /16, /8).
+ *
+ * Originally DNSControl implemented the older standard, which only specifies what
+ * to do for /8, /16, /24 - /32.  Using `REV()` for /9-17 and /17-23 CIDRs was an
+ * error.
+ *
+ * v4 defaults to RFC 2317.  In v5.0 the default will change to RFC 4183.
+ * `REVCOMPAT()` is provided for those that wish to retain the old behavior.
+ *
+ * For more information, see [Opinion #9](../../opinions.md#opinion-9-rfc-4183-is-better-than-rfc-2317).
+ *
+ * # Transition plan
+ *
+ * What's the default behavior if `REVCOMPAT()` is not used?
+ *
+ * | Version | /9 to /15 and /17 to /23 | /25 to 32 | Warnings                   |
+ * |---------|--------------------------|-----------|----------------------------|
+ * | v4      | RFC 4183                 | RFC 2317  | Only if /25 - /32 are used |
+ * | v5      | RFC 4183                 | RFC 4183  | none                       |
+ *
+ * No warnings are generated if the `REVCOMPAT()` function is used.
+ *
+ * @see https://docs.dnscontrol.org/language-reference/top-level-functions/revcompat
+ */
+declare function REVCOMPAT(rfc: string): string;
+
 /**
  * `SOA` adds an `SOA` record to a domain. The name should be `@`.  ns and mbox are strings. The other fields are unsigned 32-bit ints.
  *

documentation/SUMMARY.md

@@ -24,6 +24,7 @@
   * [NewRegistrar](functions/global/NewRegistrar.md)
   * [PANIC](functions/global/PANIC.md)
   * [REV](functions/global/REV.md)
+  * [REVCOMPAT](functions/global/REVCOMPAT.md)
   * [getConfiguredDomains](functions/global/getConfiguredDomains.md)
   * [require](functions/global/require.md)
   * [require_glob](functions/global/require_glob.md)

documentation/functions/domain/PTR.md

@@ -17,7 +17,7 @@ saving the user from having to reverse the IP address manually.
 
 Target should be a string representing the FQDN of a host.  Like all FQDNs in DNSControl, it must end with a `.`.
 
-**Magic Mode:**
+# Magic Mode
 
 PTR records are complex and typos are common. Therefore DNSControl
 enables features to save labor and
@@ -91,6 +91,32 @@ D(REV("2001:db8:302::/48"), REGISTRAR, DnsProvider(BIND),
 ```
 {% endcode %}
 
-In the future we plan on adding a flag to [`A()`](A.md) which will insert
-the correct PTR() record if the appropriate `.arpa` domain has been
-defined.
+# Automatic forward and reverse lookups
+
+DNSControl does not automatically generate forward and reverse lookups. However
+it is possible to write a macro that does this by using the 
+[`D_EXTEND()`](../global/D_EXTEND.md)
+function to insert `A` and `PTR` records into previously-defined domains.
+
+{% code title="dnsconfig.js" %}
+```javascript
+function FORWARD_AND_REVERSE(ipaddr, fqdn) {
+    D_EXTEND(dom,
+        A(fqdn, ipaddr)
+    );
+    D_EXTEND(REV(ipaddr),
+        PTR(ipaddr, fqdn)
+    );
+}
+
+D("example.com", REGISTRAR, DnsProvider(DSP_NONE),
+    ...,
+    END);
+D(REV("10.20.30.0/24"), REGISTRAR, DnsProvider(DSP_NONE),
+    ...,
+    END);
+
+FORWARD_AND_REVERSE("10.20.30.77", "foo.example.com.");
+FORWARD_AND_REVERSE("10.20.30.99", "bar.example.com.");
+```
+{% endcode %}