CLOUDFLAREAPI: Add per-record CNAME flattening support (#4020)

Add support for Cloudflare's per-record CNAME flattening feature using
CF_CNAME_FLATTEN_ON and CF_CNAME_FLATTEN_OFF modifiers, similar to the
existing CF_PROXY_ON/OFF pattern.

CNAME flattening resolves CNAME targets to their IP addresses at
Cloudflare's edge, which can improve performance and compatibility. This
feature requires a paid Cloudflare plan (Pro, Business, or Enterprise).

New record modifiers for CNAME records:
- CF_CNAME_FLATTEN_ON: Enable CNAME flattening for the record
- CF_CNAME_FLATTEN_OFF: Disable CNAME flattening (default)

Example usage:
```javascript
D("example.com", REG, DSP,
    CNAME("cdn", "cdn.provider.com.", CF_CNAME_FLATTEN_ON),
    CNAME("www", "www.example.com.", CF_CNAME_FLATTEN_OFF),
);
```

- Uses Cloudflare API's `settings.flatten_cname` field
- Stores state in record metadata as `cloudflare_cname_flatten`
- Only applies to CNAME record types
- Integrated with diff detection via genComparable()

- pkg/js/helpers.js: Add CF_CNAME_FLATTEN_ON/OFF constants
- commands/types/others.d.ts: Add TypeScript declarations for IDE
support
- providers/cloudflare/cloudflareProvider.go:
  - Add metaCNAMEFlatten constant
  - Add checkCNAMEFlattenVal() validation function
  - Update preprocessConfig() to validate CNAME flatten setting
  - Update nativeToRecord() to read settings.flatten_cname from API
  - Update genComparable() to include flatten state in diff comparison
- providers/cloudflare/rest.go:
  - Update createRecDiff2() to set Settings.FlattenCNAME
  - Update modifyRecord() to set Settings.FlattenCNAME
- commands/getZones.go:
  - Update TSV export to include cloudflare_cname_flatten metadata
  - Update JS/DJS export to include CF_CNAME_FLATTEN_ON modifier
- pkg/prettyzone/prettyzone.go:
  - Update zone file export to include CF_CNAME_FLATTEN_ON comment

Added gated integration tests that are disabled by default since CNAME
flattening requires a paid plan:
- integrationTest/helpers_test.go: Add -cfflatten flag (default false)
- integrationTest/helpers_integration_test.go: Add test helper functions
- integrationTest/integration_test.go: Add CF_CNAME_FLATTEN test groups

Run tests on paid zones with: go test -v -provider=CLOUDFLAREAPI
-cfflatten=true

Updated documentation/provider/cloudflareapi.md with:
- New CNAME flattening section with usage examples
- Warning about paid plan requirement
- Integration test flag documentation

Author: allixsenos

commands/getZones.go

@@ -311,19 +311,27 @@ func GetZone(args GetZoneArgs) error {
 
 		case "tsv":
 			for _, rec := range recs {
-				cfproxy := ""
+				cfmeta := ""
 				if cp, ok := rec.Metadata["cloudflare_proxy"]; ok {
 					if cp == "true" {
-						cfproxy = "\tcloudflare_proxy=true"
+						cfmeta += ",cloudflare_proxy=true"
 					}
 				}
+				if cf, ok := rec.Metadata["cloudflare_cname_flatten"]; ok {
+					if cf == "on" {
+						cfmeta += ",cloudflare_cname_flatten=on"
+					}
+				}
+				if cfmeta != "" {
+					cfmeta = "\t" + cfmeta[1:] // Remove leading comma, add tab
+				}
 
 				ty := rec.Type
 				if rec.Type == "UNKNOWN" {
 					ty = rec.UnknownTypeName
 				}
 				fmt.Fprintf(w, "%s\t%s\t%d\tIN\t%s\t%s%s\n",
-					rec.NameFQDN, rec.Name, rec.TTL, ty, rec.GetTargetCombinedFunc(nil), cfproxy)
+					rec.NameFQDN, rec.Name, rec.TTL, ty, rec.GetTargetCombinedFunc(nil), cfmeta)
 			}
 
 		default:
@@ -360,6 +368,13 @@ func formatDsl(rec *models.RecordConfig, defaultTTL uint32) string {
 		}
 	}
 
+	cfflatten := ""
+	if cf, ok := rec.Metadata["cloudflare_cname_flatten"]; ok {
+		if cf == "on" {
+			cfflatten = ", CF_CNAME_FLATTEN_ON"
+		}
+	}
+
 	switch rec.Type { // #rtype_variations
 	case "CAA":
 		return makeCaa(rec, ttlop)
@@ -412,7 +427,7 @@ func formatDsl(rec *models.RecordConfig, defaultTTL uint32) string {
 		target = `"` + target + `"`
 	}
 
-	return fmt.Sprintf(`%s("%s", %s%s%s)`, rec.Type, rec.Name, target, cfproxy, ttlop)
+	return fmt.Sprintf(`%s("%s", %s%s%s%s)`, rec.Type, rec.Name, target, cfproxy, cfflatten, ttlop)
 }
 
 func makeCaa(rec *models.RecordConfig, ttlop string) string {

commands/types/dnscontrol.d.ts

@@ -138,6 +138,10 @@ declare const CF_PROXY_OFF: RecordModifier;
 declare const CF_PROXY_ON: RecordModifier;
 /** Proxy+Railgun enabled. */
 declare const CF_PROXY_FULL: RecordModifier;
+/** Per-record CNAME flattening disabled (default) */
+declare const CF_CNAME_FLATTEN_OFF: RecordModifier;
+/** Per-record CNAME flattening enabled (requires Cloudflare paid plan) */
+declare const CF_CNAME_FLATTEN_ON: RecordModifier;
 
 /** Proxy default off for entire domain (the default) */
 declare const CF_PROXY_DEFAULT_OFF: DomainModifier;

commands/types/others.d.ts

@@ -27,6 +27,10 @@ declare const CF_PROXY_OFF: RecordModifier;
 declare const CF_PROXY_ON: RecordModifier;
 /** Proxy+Railgun enabled. */
 declare const CF_PROXY_FULL: RecordModifier;
+/** Per-record CNAME flattening disabled (default) */
+declare const CF_CNAME_FLATTEN_OFF: RecordModifier;
+/** Per-record CNAME flattening enabled (requires Cloudflare paid plan) */
+declare const CF_CNAME_FLATTEN_ON: RecordModifier;
 
 /** Proxy default off for entire domain (the default) */
 declare const CF_PROXY_DEFAULT_OFF: DomainModifier;

documentation/provider/cloudflareapi.md

@@ -103,6 +103,7 @@ This provider accepts some optional metadata:
 
 Record level metadata available:
    * `cloudflare_proxy` ("on", "off", or "full")
+   * `cloudflare_cname_flatten` ("on" or "off") - Per-record CNAME flattening (paid plans only)
 
 Domain level metadata available:
    * `cloudflare_proxy_default` ("on", "off", or "full")
@@ -141,6 +142,8 @@ the following aliases are *pre-defined*:
 var CF_PROXY_OFF = {"cloudflare_proxy": "off"};     // Proxy disabled.
 var CF_PROXY_ON = {"cloudflare_proxy": "on"};       // Proxy enabled.
 var CF_PROXY_FULL = {"cloudflare_proxy": "full"};   // Proxy+Railgun enabled.
+var CF_CNAME_FLATTEN_OFF = {"cloudflare_cname_flatten": "off"};  // CNAME flattening disabled (default).
+var CF_CNAME_FLATTEN_ON = {"cloudflare_cname_flatten": "on"};    // CNAME flattening enabled (paid plans only).
 // Per-domain meta settings:
 // Proxy default off for entire domain (the default):
 var CF_PROXY_DEFAULT_OFF = {"cloudflare_proxy_default": "off"};
@@ -201,6 +204,33 @@ D("example2.tld", REG_NONE, DnsProvider(DSP_CLOUDFLARE),
 If a domain does not exist in your Cloudflare account, DNSControl
 will automatically add it when `dnscontrol push` is executed.
 
+## CNAME flattening
+
+Cloudflare supports [CNAME flattening](https://developers.cloudflare.com/dns/cname-flattening/), which resolves CNAME targets to their IP addresses at the edge. This can be enabled zone-wide (for zones on paid Cloudflare plans) or per-record.
+
+DNSControl supports per-record CNAME flattening using the `CF_CNAME_FLATTEN_ON` modifier:
+
+{% code title="dnsconfig.js" %}
+```javascript
+var REG_NONE = NewRegistrar("none");
+var DSP_CLOUDFLARE = NewDnsProvider("cloudflare");
+
+D("example.com", REG_NONE, DnsProvider(DSP_CLOUDFLARE),
+    // Enable CNAME flattening for this record
+    CNAME("cdn", "cdn.provider.com.", CF_CNAME_FLATTEN_ON),
+
+    // CNAME flattening disabled (default behavior)
+    CNAME("www", "www.example.com."),
+    CNAME("api", "api.example.com.", CF_CNAME_FLATTEN_OFF),
+);
+```
+{% endcode %}
+
+{% hint style="warning" %}
+**Paid plans only:** Per-record CNAME flattening requires a Cloudflare paid subscription (Pro, Business, or Enterprise). Free plans do not support this feature. If you attempt to enable CNAME flattening on a free zone, the Cloudflare API will return an error.
+{% endhint %}
+
+For more information, see [Cloudflare's CNAME flattening documentation](https://developers.cloudflare.com/dns/cname-flattening/).
 
 ## Old-style vs new-style redirects
 
@@ -421,6 +451,18 @@ go test -v -verbose -profile CLOUDFLAREAPI -cfworkers=false
 
 When `-cfworkers=false` is set, tests related to Workers are skipped.  The Account ID is not required.
 
+### CNAME flattening tests
+
+Tests for per-record CNAME flattening (`CF_CNAME_FLATTEN_ON`/`CF_CNAME_FLATTEN_OFF`) are disabled by default
+because they require a paid Cloudflare plan. To enable these tests, use the `-cfflatten=true` flag:
+
+```shell
+cd integrationTest
+go test -v -verbose -profile CLOUDFLAREAPI -cfflatten=true
+```
+
+If you run with `-cfflatten=true` on a free zone, the tests will fail with an error from the Cloudflare API.
+
 ## Cloudflare special TTLs
 
 Cloudflare plays tricks with TTLs.  Cloudflare uses "1" to mean "auto-ttl";

integrationTest/helpers_integration_test.go

@@ -41,6 +41,16 @@ func CfProxyOn() *TestCase  { return tc("proxyon", cfProxyA("prxy", "174.136.107
 func CfCProxyOff() *TestCase { return tc("cproxyoff", cfProxyCNAME("cproxy", "example.com.", "off")) }
 func CfCProxyOn() *TestCase  { return tc("cproxyon", cfProxyCNAME("cproxy", "example.com.", "on")) }
 
+// Helper constants/funcs for the CLOUDFLARE CNAME flattening testing:
+
+// CNAME flattening off/on (requires paid plan)
+func CfFlattenOff() *TestCase {
+	return tc("flattenoff", cfFlattenCNAME("cflatten", "example.com.", "off"))
+}
+func CfFlattenOn() *TestCase {
+	return tc("flattenon", cfFlattenCNAME("cflatten", "example.com.", "on"))
+}
+
 func getDomainConfigWithNameservers(t *testing.T, prv providers.DNSServiceProvider, domainName string) *models.DomainConfig {
 	dc := &models.DomainConfig{
 		Name: domainName,
@@ -340,6 +350,13 @@ func cfProxyCNAME(name, target, status string) *models.RecordConfig {
 	return r
 }
 
+func cfFlattenCNAME(name, target, status string) *models.RecordConfig {
+	r := cname(name, target)
+	r.Metadata = make(map[string]string)
+	r.Metadata["cloudflare_cname_flatten"] = status
+	return r
+}
+
 func cfSingleRedirectEnabled() bool {
 	return (*enableCFRedirectMode)
 }

integrationTest/helpers_test.go

@@ -19,6 +19,7 @@ var (
 	profileFlag          = flag.String("profile", "", "Entry in profiles.json to use (if empty, copied from -provider)")
 	enableCFWorkers      = flag.Bool("cfworkers", true, "enable CF worker tests (default true)")
 	enableCFRedirectMode = flag.Bool("cfredirect", false, "enable CF SingleRedirect tests (default false)")
+	enableCFFlatten      = flag.Bool("cfflatten", false, "enable CF CNAME flattening tests (requires paid plan, default false)")
 )
 
 func init() {

integrationTest/integration_test.go

@@ -1227,6 +1227,27 @@ func makeTests() []*TestGroup {
 			CfCProxyOn(), CfCProxyOff(),
 		),
 
+		// CLOUDFLAREAPI: CNAME FLATTENING (requires paid plan)
+
+		testgroup("CF_CNAME_FLATTEN create",
+			only("CLOUDFLAREAPI"),
+			alltrue(*enableCFFlatten),
+			CfFlattenOff(), tcEmptyZone(),
+			CfFlattenOn(), tcEmptyZone(),
+		),
+
+		testgroup("CF_CNAME_FLATTEN off to on",
+			only("CLOUDFLAREAPI"),
+			alltrue(*enableCFFlatten),
+			CfFlattenOff(), CfFlattenOn(),
+		),
+
+		testgroup("CF_CNAME_FLATTEN on to off",
+			only("CLOUDFLAREAPI"),
+			alltrue(*enableCFFlatten),
+			CfFlattenOn(), CfFlattenOff(),
+		),
+
 		testgroup("CF_WORKER_ROUTE",
 			only("CLOUDFLAREAPI"),
 			alltrue(*enableCFWorkers),

pkg/js/helpers.js

@@ -1452,6 +1452,8 @@ function num2dot(num) {
 var CF_PROXY_OFF = { cloudflare_proxy: 'off' }; // Proxy disabled.
 var CF_PROXY_ON = { cloudflare_proxy: 'on' }; // Proxy enabled.
 var CF_PROXY_FULL = { cloudflare_proxy: 'full' }; // Proxy+Railgun enabled.
+var CF_CNAME_FLATTEN_OFF = { cloudflare_cname_flatten: 'off' }; // CNAME flattening disabled (default).
+var CF_CNAME_FLATTEN_ON = { cloudflare_cname_flatten: 'on' }; // CNAME flattening enabled (paid plans only).
 // Per-domain meta settings:
 // Proxy default off for entire domain (the default):
 var CF_PROXY_DEFAULT_OFF = { cloudflare_proxy_default: 'off' };

pkg/prettyzone/prettyzone.go

@@ -137,9 +137,17 @@ func (z *ZoneGenData) generateZoneFileHelper(w io.Writer) error {
 		comment := ""
 		if cp, ok := rr.Metadata["cloudflare_proxy"]; ok {
 			if cp == "true" {
-				comment = " ; CF_PROXY_ON"
+				comment += " CF_PROXY_ON"
 			}
 		}
+		if cf, ok := rr.Metadata["cloudflare_cname_flatten"]; ok {
+			if cf == "on" {
+				comment += " CF_CNAME_FLATTEN_ON"
+			}
+		}
+		if comment != "" {
+			comment = " ;" + comment
+		}
 
 		fmt.Fprintf(w, "%s%s%s\n",
 			prefix, FormatLine([]int{10, 5, 2, 5, 0}, []string{name, ttl, "IN", typeStr, target}), comment)

providers/cloudflare/cloudflareProvider.go

@@ -257,6 +257,7 @@ func (c *cloudflareProvider) GetZoneRecordsCorrections(dc *models.DomainConfig,
 }
 
 func genComparable(rec *models.RecordConfig) string {
+	var parts []string
 	if rec.Type == "A" || rec.Type == "AAAA" || rec.Type == "CNAME" {
 		proxy := rec.Metadata[metaProxy]
 		if proxy != "" {
@@ -266,10 +267,18 @@ func genComparable(rec *models.RecordConfig) string {
 			if proxy == "off" {
 				proxy = "false"
 			}
-			return "proxy=" + proxy
+			parts = append(parts, "proxy="+proxy)
 		}
 	}
-	return ""
+	if rec.Type == "CNAME" {
+		flatten := rec.Metadata[metaCNAMEFlatten]
+		if flatten == "on" {
+			parts = append(parts, "flatten=true")
+		} else {
+			parts = append(parts, "flatten=false")
+		}
+	}
+	return strings.Join(parts, ",")
 }
 
 func (c *cloudflareProvider) mkCreateCorrection(newrec *models.RecordConfig, domainID, msg string) []*models.Correction {
@@ -408,6 +417,7 @@ const (
 	metaProxyDefault = metaProxy + "_default"
 	metaOriginalIP   = "original_ip" // TODO(tlim): Unclear what this means.
 	metaUniversalSSL = "cloudflare_universalssl"
+	metaCNAMEFlatten = "cloudflare_cname_flatten"
 )
 
 func checkProxyVal(v string) (string, error) {
@@ -418,6 +428,14 @@ func checkProxyVal(v string) (string, error) {
 	return v, nil
 }
 
+func checkCNAMEFlattenVal(v string) (string, error) {
+	v = strings.ToLower(v)
+	if v != "on" && v != "off" {
+		return "", fmt.Errorf("bad metadata value for cloudflare_cname_flatten: '%s'. Use on/off", v)
+	}
+	return v, nil
+}
+
 func (c *cloudflareProvider) preprocessConfig(dc *models.DomainConfig) error {
 
 	for _, rec := range dc.Records {
@@ -483,6 +501,18 @@ func (c *cloudflareProvider) preprocessConfig(dc *models.DomainConfig) error {
 			}
 		}
 
+		// Validate CNAME flattening metadata (only valid on CNAME records)
+		if val := rec.Metadata[metaCNAMEFlatten]; val != "" {
+			if rec.Type != "CNAME" {
+				return fmt.Errorf("cloudflare_cname_flatten set on %v record: %#v (only valid on CNAME records)", rec.Type, rec.GetLabel())
+			}
+			val, err := checkCNAMEFlattenVal(val)
+			if err != nil {
+				return err
+			}
+			rec.Metadata[metaCNAMEFlatten] = val
+		}
+
 		if rec.Type == "CLOUDFLAREAPI_SINGLE_REDIRECT" {
 			// SINGLEREDIRECT record types. Verify they are enabled.
 			if !c.manageSingleRedirects {
@@ -784,6 +814,15 @@ func (c *cloudflareProvider) nativeToRecord(domain string, cr cloudflare.DNSReco
 		}
 	}
 
+	// Check for CNAME flattening setting
+	if cr.Type == "CNAME" {
+		if cr.Settings.FlattenCNAME != nil && *cr.Settings.FlattenCNAME {
+			rc.Metadata[metaCNAMEFlatten] = "on"
+		} else {
+			rc.Metadata[metaCNAMEFlatten] = "off"
+		}
+	}
+
 	switch rType := cr.Type; rType { // #rtype_variations
 	case "MX":
 		if err := rc.SetTargetMX(*cr.Priority, cr.Content); err != nil {