custom domains documentation

content/workers/platform/routing/_index.md

+---
+pcx-content-type: concept
+title: Routing
+---
+
+# Routing
+
+## Background
+
+Routing lets customers connect a Worker to the Internet, allowing it to receive HTTP requests on their Cloudflare zones. There are two ways to route to a Worker: [Custom Domains](/workers/platform/routing/custom-domains) and [Routes](/workers/platform/routing/routes).
+
+## Custom Domains
+[Custom Domains](/workers/platform/routing/custom-domains) allow our customers to connect a Worker to a hostname. Cloudflare will create DNS records and issue necessary certificates on behalf of our customers. The DNS records will point directly to the Worker and must be proxied.
+
+[Custom Domains](/workers/platform/routing/custom-domains) are the best option if you'd like to connect your Worker to the Internet, and you don't have a default application server that you want to always communicate with. If you do have external dependencies, you can create a `Request` object with the target URI, and call `fetch()`.
+
+## Routes
+[Routes](/workers/platform/routing/routes) are a good option if you have a designated application server you always need to communicate with. Calling `fetch()` on the incoming `Request` object will trigger a subrequest to your application server, as defined in the DNS tab of your Cloudflare zone.
+
+[Routes](/workers/platform/routing/routes) can stack on top of [Custom Domains](/workers/platform/routing/custom-domains), if configured on the appropriate URL. If you'd like to run a logging Worker in front of your application, you can create a Custom Domain on your application Worker, and create a Route for your logging Worker. Calling `fetch()` will invoke the application Worker on your Custom Domain.
+
+## What's Best for Me?
+
+Generally, [Routes](/workers/platform/routing/routes) are good for use cases where the Worker acts like a 'proxy', making small modifications to the Request, Response, or logging data in between the user and the server. [Custom Domains](/workers/platform/routing/custom-domains) are great for more in-depth use cases, where your application lives on the Cloudflare network and may optionally communicate with external dependencies.

content/workers/platform/routing/custom-domains.md

+---
+pcx-content-type: concept
+title: Routes
+---
+
+# Custom Domains
+
+## About
+Custom Domains allow our customers to connect a Worker to a hostname, without having to fuss with DNS or certificate management. Cloudflare will create DNS records and issue necessary certificates on behalf of our customers. The DNS records will point directly to the Worker and will be proxied.
+
+## Building a Custom Domain
+In order to create a Custom Domain, you must have:
+* An active Cloudflare zone on your target domain
+* A Worker to invoke
+
+The interface provides active feedback on valid and invalid entries. Valid entries are hostnames on an active Cloudflare zone. If you attempt to create a Custom Domain on a hostname with an existing DNS record, Cloudflare will confirm that you'd like to replace the existing record.
+
+## Fetch
+Custom Domains are considered the 'origin' as far as your request is concerned. That means calling `fetch()` on the initial request is, in most cases, an antipattern. Instead, create new `Request` objects to reference any external dependencies, or use Cloudflare's built in primitives via bindings.
+
+Another side effect of the tight integration with Cloudflare DNS is that you can use your Custom Domains like you would any external dependency. Your Workers can `fetch()` Custom Domains and invoke their associated Worker, even if they're on the same Cloudflare zone. The newly invoked Worker is treated like a new top-level request, and will execute in a separate thread.
+
+## Ordering
+Custom Domains follow standard DNS ordering and matching logic. Custom Domains do not support wildcard records; as such an incoming request must match the hostname your Custom Domain is registered to. Other parts of the URI are ignored when executing this matching logic. For example, if you create a Custom Domain on `api.example.com`, a request to either `api.example.com/login` or `api.example.com/user` would invoke the same Worker.
+
+## Interaction with Routes
+Custom Domains are evaluated before Route rules, but take lower precedence. [Routes](/workers/platform/routing/routes) defined on your Custom Domain will run first, but can optionally call the Worker registered on your Custom Domain. In our example above, a Custom Domain for `api.example.com` can point to our Worker `api`. A Route added to `api.example.com/auth` can point to our Worker `auth`. Using `fetch(request)` within the Worker `auth` will invoke the Worker `api`, as if it was a normal application server. This means you can stack your Workers on top of each other, creating layers of 'proxy' Workers and 'application' Workers.
+
+## Migrating from Routes
+If you're currently invoking a Worker using a [Route](/workers/platform/routing/routes) with `/*`, and your DNS points to `100::` or similar,it's generally recommended that a Custom Domain is a suitable replacement. For example, to migrate the Route `app.example.com/*`, simply create a Custom Domain on `app.example.com`, replacing the existing record. You can then delete the route `app.example.com/*` in your Worker > Triggers > Routes table.
+
+If that Worker acts exclusively as a 'proxy' – meaning it will need to call `fetch(request)` on the incoming connection's HTTP request to connect to an application server defined in DNS – the Custom Domain may not be the best solution.
\ No newline at end of file

content/workers/platform/routes.md → content/workers/platform/routing/routes.md

@@ -7,15 +7,15 @@ title: Routes
 
 ## Background
 
-Routes allow users to map a URL pattern to a Worker script to enable Workers to run on custom domains.
+Routes allow users to map a URL pattern to a Worker script to enable Workers to run in front of [Custom Domains](/workers/platform/routing/custom-domains) or their own application servers.
 
-## Custom routes
+## Customizing routes
 
 For zones proxied on Cloudflare, route patterns decide what (if any) script is matched based on the URL of that request. Requests are routed through a Workers script when the URL matches a route pattern assigned to that script.
 
 {{<Aside type="warning">}}
 
-For any Worker script that you want to run on a custom domain, that custom domain must be proxied through Cloudflare prior to adding the route.
+For any Worker script that you want to run on your domain, that domain must be proxied through Cloudflare prior to adding the route.
 
 {{</Aside>}}
 
@@ -33,13 +33,11 @@ The Routes REST API documentation can be found [in the Workers API docs](https:/
 
 If your route is configured to a hostname, you will need to add a DNS record to Cloudflare to ensure that the hostname can be resolved externally. If your Worker acts as your origin (that is, the request terminates in a Worker), you must add a DNS record.
 
-You may enter a placeholder AAAA record pointing to [100::](https://datatracker.ietf.org/doc/html/rfc6666), which must be proxied through Cloudflare (orange-cloud in the DNS settings). This value specifically is the reserved IPv6 discard prefix but is not the only value allowed. For example, you may also use an A record pointed to 192.0.2.1 or a CNAME pointed to any resolvable target.
-
 * _A zone that you have registered with some registrar (not workers.dev) and setup Cloudflare to serve as [a reverse proxy](https://www.cloudflare.com/learning/cdn/glossary/reverse-proxy/)._
 
 ## Routes with *.workers.dev
 
-Cloudflare Workers accounts come with a `*.workers.dev` subdomain that is configurable in the Cloudflare dashboard. Your `*.workers.dev` subdomain allows you to deploy Workers scripts [without attaching a custom domain as a Cloudflare zone](https://blog.cloudflare.com/announcing-workers-dev/).
+Cloudflare Workers accounts come with a `*.workers.dev` subdomain that is configurable in the Cloudflare dashboard. Your `*.workers.dev` subdomain allows you to deploy Workers scripts [without attaching your domain as a Cloudflare zone](https://blog.cloudflare.com/announcing-workers-dev/).
 
 To claim a `*.workers.dev` subdomain, such as `my-subdomain.workers.dev`, go to **Account Home** > **Workers** > **Overview** > **Your subdomain**. The `name` field in your Worker configuration is used as the secondary subdomain for the deployed script, (for example, `my-worker.my-subdomain.workers.dev.`).
 
@@ -125,4 +123,8 @@ There is a well-known bug associated with path matching concerning wildcards (`*
 
 All subdomains must have a [DNS record](https://support.cloudflare.com/hc/en-us/articles/360019093151#h_60566325041543261564371) to be proxied on Cloudflare and used to invoke a Worker. For example, if you want to put a worker on `myname.example.com`, and you have added `example.com` to Cloudflare but have not added any DNS records for `myname.example.com`, any request to `myname.example.com` will result in the error `ERR_NAME_NOT_RESOLVED`.
 
-To support this, you should use the Cloudflare dashboard to add an `AAAA` record for `myname` to `example.com`, pointing to `100::` (the [reserved IPv6 discard prefix](https://tools.ietf.org/html/rfc6666)).
+{{<Aside type="warning">}}
+
+If you've previously used the Cloudflare dashboard to add an `AAAA` record for `myname` to `example.com`, pointing to `100::` (the [reserved IPv6 discard prefix](https://tools.ietf.org/html/rfc6666)), Cloudflare recommends creating a [Custom Domain](/workers/platform/routing/custom-domains) pointing to your Worker instead.
+
+{{</Aside>}}
\ No newline at end of file