ReferenceAsk
Remy Reference/Architecture/Architecture/Edge and Custom Domains
26Architecture

Edge and Custom Domains

The Cloudflare Workers that make up the edge, the small hostname-to-parameters routing contract they implement, how a customer's own domain is carried with an automatic certificate, and what the edge caches.

Every browser request to a deployed app, the editor, the console, a file, an image or a video arrives at Cloudflare first. Eight Workers make up the platform's edge, each owning a hostname pattern; two more serve the frontends. Cloudflare for SaaS carries customers' own domains with certificates issued automatically. This chapter covers the Workers, the routing contract they implement, custom domains, and what the edge caches.


#The Workers

WorkerHostnamesWhat it does
Subdomain proxyThe platform's wildcard app domain, the legacy app apex, the Cloudflare for SaaS fallback and CNAME targetsResolves the app from the subdomain label or the custom hostname and reverse-proxies to the platform
Sandbox preview proxyThe sandbox preview domainFronts dev-box previews and hot reload, forwarding to the sandbox-proxy role
Git and static rewriteThe git host, release-addressed static hosts, and the npm registry hostRoutes git traffic to the git role with per-app stickiness, static assets to the release-addressed origin, and the npm registry host read-only to the npm registry, caching only its tarballs
API host rewriteThe public API hostnameProxies to the API origin with CORS and edge caching for cacheable reads
WebSocket host rewriteA legacy socket aliasProxies WebSocket upgrades to the socket origin
Files CDNThe files CDN hostsServes public files from the public buckets with content-type inference and audio waveform rendering
Image CDNThe image CDN hostsServes images from the regional public buckets with edge transformation from query parameters
Video CDNThe video CDN hostsServes video with range support, frame thumbnails and metadata

The Workers are one package with their own build, tests and deploy scripts. Each deploys to the zones it owns, from the release pipeline: a Worker ships on the release that changed it.


#The Routing Contract

The platform is edge-agnostic. It reads the app's identity and the request path from query parameters and never from the Host header. The Worker's job is to map a hostname to those parameters:

IncomingForwarded to the platform
<sub>.<apex>/*The subdomain serve endpoint, with the subdomain and path as query parameters
<sub>.<apex>/<internal prefix>/*The subdomain proxy endpoint, with the subdomain and path as query parameters
<customer-domain>/*The custom-host serve endpoint, with the host and path as query parameters
<customer-domain>/<internal prefix>/*The custom-host proxy endpoint, with the host and path as query parameters

A page load is a serve request; anything the app's frontend calls under the internal prefix is a proxy request, and the platform's segment switch dispatches from there. The app-facing query string rides along. HTTPS is forced unconditionally before any other handling, and the redirect target is built from the client-facing host so a custom domain redirects to itself.

Because the contract is this small, any reverse proxy can implement the mapping. The Workers do more than the mapping, though, and that part is product behavior rather than routing:

  • image transformation on an app's own host;
  • the file, image and video CDN hosts;
  • marking session HTML as uncacheable;
  • the custom-host surface;
  • the redirect that keeps SVG off an app's origin;
  • following a stored file an app method answered with. The API answers with a 302 to a short-lived signed URL, marked with a header that only the API sets. The Worker fetches the URL itself, forwarding only the client's range and validator headers, and streams the bytes back at the request's own URL. The client follows no redirect (git refuses one after its first request) and the bytes never pass through a pod. A proxy that doesn't follow passes the 302 on, which still serves the file to any client that follows redirects. An app may not set headers in the platform's reserved prefix, so it cannot forge the mark.

So the direction off Cloudflare is the same Workers on workerd, the open-source Workers runtime, behind a TLS proxy: Caddy on a laptop or a server, an ALB or CloudFront in a dedicated account. Image transformation goes to imgproxy. The Workers read their origin and apexes from bindings, so the same code runs on both runtimes, and so does the frontend's: its Worker writes the API's origin and the platform assets' base, both bindings, into every page it serves. A laptop already runs the app Worker this way, behind Caddy. The file, image and video Workers follow. See Portability.


#Custom Domains

A workspace attaches its own domain to an app, up to ten per app. The platform registers it as a Cloudflare for SaaS custom hostname, and the customer points it at the platform: a CNAME for a subdomain, or A and AAAA records for an apex, since DNS allows no CNAME at the root of a zone. Cloudflare validates the certificate over HTTP once the name routes to it, and issues and renews it.

Routing alone proves control only when the name started routing to the platform because of this claim. A name that already pointed here, or that another app held before, must also publish a TXT record Cloudflare issues for the claim before it serves. The platform's own domains can't be claimed. Traffic for the custom hostname terminates at Cloudflare and is forwarded to the Worker's fallback origin with the original hostname preserved, so the Worker routes it like any other app.

A domain and its www alias are managed as a pair. API calls on either are routed to the app directly; page navigation canonicalizes to the primary so there is one address for search engines and one for cookies. Custom hosts always serve the live release; previews live only on the platform apex.

Domains bought through Remy. A workspace can also buy a domain without leaving Remy. The platform resells registrations through Name.com, an ICANN-accredited registrar, at the registrar's price. The workspace's contact is the registrant, so the workspace and not the platform is the domain's legal owner, and ICANN's verification and notices go to it. Name.com also hosts the domain's DNS, under the platform's reseller account.

When one of the workspace's apps connects the domain, as its web address or for sending or receiving mail, the platform writes the records that connection needs, the same ones it would otherwise ask the owner to paste, and removes them when the connection ends. The owner's own records sit beside them, and the platform never writes one that duplicates or contradicts theirs.

A daily sweep renews each domain about a month before it expires while auto-renew is on, with Name.com's own auto-renew a week out as the backstop, and each renewal is charged once. Once the registry's 60-day lock on a new registration has passed, the owner can transfer the domain to another registrar.


#What the Edge Caches

The caching split is a property of the response, and the Worker honors it:

  • Session HTML is never cached. Every page load reaches the platform and gets the session injected.
  • Content-addressed assets from a release's build are cached at the edge for a long time; a new release has new addresses.
  • An app's own files on its own host (a build that names its assets by root path, a favicon, a robots file) are cached at the edge under the app's tag and purged when a release goes live. A file the build tool named for its content is also kept by the browser for good. Every other file there is revalidated by the browser, which the edge answers. A branch preview's files are cached nowhere, since the preview gate runs at the platform on every path.
  • Public files are cached at the edge under the object's CDN URL after transformation; the platform's redirect that locates them is cached briefly.
  • Private files and per-user transforms are never cached.
  • Public API reads are edge-cached when the origin says so, with browser caching forced to revalidate so a client never sees a stale read after its own write.

The platform purges by tag when a payload it builds changes: after every deploy for the compile-time payloads, when a site setting or a model's state changes, and for an app's own hosts when a release goes live or the app stops or is deleted. A public file carries no tag, since the edge fetches it straight from storage, so it is purged by prefix, from a durable queue, when it is overwritten or deleted. Prerendered pages are served with a max-age of zero, so the edge holds none to purge.


#The Frontends

The Remy editor and console are static builds deployed as Cloudflare Workers, with their assets on the same edge, and they call the platform's API and WebSocket hosts directly.

What This Gives an App
A global edge in front of every request, with TLS terminated close to the user.
Its own domain with a certificate it never manages.
A domain bought in Remy that goes live for the web and for mail with no DNS to configure.
Assets and public files served from cache; personalized pages always fresh.
An origin that can sit behind a different edge without changing.