CLOUDFLARE: Correct redirect function documentation (#696)

* expand on how Page Rules are handled

* Correct Cloudflare redirect function documentation

* add warning per discussion on #696

docs/_functions/domain/CF_REDIRECT.md

@@ -5,12 +5,30 @@ parameters:
   - modifiers...
 ---
 
-`CF_REDIRECT` is the same as `CF_TEMP_REDIRECT` but generates a
+`CF_REDIRECT` uses Cloudflare-specific features ("Forwarding URL" Page Rules) to
-http 301 redirect (permanent redirect) instead of a temporary
+generate a HTTP 301 permanent redirect.
-redirect.
 
-These redirects are cached by browsers forever, usually ignoring
+If _any_ `CF_REDIRECT` or `CF_TEMP_REDIRECT` functions are used then
-any TTLs or other cache invalidation techniques.   It should be
+`dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain.
-used with great care.  We suggest using a `CF_TEMP_REDIRECT`
+Page Rule types other than "Forwarding URL” will be left alone.
-initially, then changing to a `CF_REDIRECT` only after sufficient
+
-time has elapsed to prove this is what you really want.
+WARNING: Cloudflare does not currently fully document the Page Rules API and
+this interface is not extensively tested. Take precautions such as making
+backups and manually verifying `dnscontrol preview` output before running
+`dnscontrol push`. This is especially true when mixing Page Rules that are
+managed by DNSControl and those that aren't.
+
+HTTP 301 redirects are cached by browsers forever, usually ignoring any TTLs or
+other cache invalidation techniques. It should be used with great care. We
+suggest using a `CF_TEMP_REDIRECT` initially, then changing to a `CF_REDIRECT`
+only after sufficient time has elapsed to prove this is what you really want.
+
+This example redirects the bare (aka apex, or naked) domain to www:
+
+{% include startExample.html %}
+{% highlight js %}
+D("foo.com", .... ,
+  CF_REDIRECT("mydomain.com/*", "https://www.mydomain.com/$1"),
+);
+{%endhighlight%}
+{% include endExample.html %}

docs/_functions/domain/CF_TEMP_REDIRECT.md

@@ -5,13 +5,18 @@ parameters:
   - modifiers...
 ---
 
-`CF_REDIRECT` uses Cloudflare-specific features ("page rules") to
+`CF_TEMP_REDIRECT` uses Cloudflare-specific features ("Forwarding URL" Page
-generate an HTTP 301 redirect.
+Rules) to generate a HTTP 302 temporary redirect.
 
-WARNING: If the domain has other pagerules in place, they may be
+If _any_ `CF_REDIRECT` or `CF_TEMP_REDIRECT` functions are used then
-deleted. At this time this feature is best used on bare domains
+`dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain.
-that need to redirect to another domain, perhaps with wildcard
+Page Rule types other than "Forwarding URL” will be left alone.
-substitutions.
+
+WARNING: Cloudflare does not currently fully document the Page Rules API and
+this interface is not extensively tested. Take precautions such as making
+backups and manually verifying `dnscontrol preview` output before running
+`dnscontrol push`. This is especially true when mixing Page Rules that are
+managed by DNSControl and those that aren't.
 
 {% include startExample.html %}
 {% highlight js %}

docs/_providers/cloudflare.md

@@ -21,7 +21,7 @@ In the credentials file you must provide a [Cloudflare API token](https://dash.c
 }
 {% endhighlight %}
 
-Make sure the token has at least the right read zones and edit DNS records (i.e. `Zone → Zone → Read` and `Zone → DNS → Edit`);
+Make sure the token has at least the right read zones and edit DNS records (i.e. `Zone → Zone → Read` and `Zone → DNS → Edit`; to modify Page Rules additionally requires `Zone → Page Rules → Edit`);
 checkout [Cloudflare's documentation](https://support.cloudflare.com/hc/en-us/articles/200167836-Managing-API-Tokens-and-Keys) for instructions on how to generate and configure permissions on API tokens.
 
 
@@ -142,7 +142,7 @@ will *not* automatically add it. You'll need to do that via the
 control panel manually or via the `dnscontrol create-domains` command.
 
 ## Redirects
-The Cloudflare provider can manage Page-Rule based redirects for your domains. Simply use the `CF_REDIRECT` and `CF_TEMP_REDIRECT` functions to make redirects:
+The Cloudflare provider can manage "Forwarding URL" Page Rules (redirects) for your domains. Simply use the `CF_REDIRECT` and `CF_TEMP_REDIRECT` functions to make redirects:
 
 {% highlight js %}
 
@@ -169,3 +169,4 @@ Notice a few details:
 1. We need an A record with cloudflare proxy on, or the page rule will never run.
 2. The IP address in those A records may be mostly irrelevant, as cloudflare should handle all requests (assuming some page rule matches).
 3. Ordering matters for priority. CF_REDIRECT records will be added in the order they appear in your js. So put catch-alls at the bottom.
+4. if _any_ `CF_REDIRECT` or `CF_TEMP_REDIRECT` functions are used then `dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain. Page Rule types other than "Forwarding URL” will be left alone.