Anatomy of a deployment

Overview

From source to deployment

A deploy sends the whole playground state to RTEdge.net: your HTML, the title, the routes, the editors and the view settings. For every route in the Routes field, RTEdge.net compiles that same state and publishes it. The stored state is exactly what route/? reopens later.

The compile step, in short:

1. It reads your HTML and collects the worker:fs assets and the <script type=worker edge> elements.
2. It works out who may view the deployment and who may open its source, from edge:user, io:user and io:guest.
3. It removes every <script type=worker> from the page. Each one becomes blank lines, so later line numbers do not shift.
4. It merges the edge scripts, bundles their static imports, prepares WebAssembly and uploads the worker.
5. It extracts the o:= exports, applies edge:remove and edge:redact, and strips the RTCode attributes from the page and the exports.

Deploying to several routes compiles the state once for each route, and each route is charged in full. See Limits and quotas. Ownership and quota checks run for all routes before anything is written, and then every route is published on its own, so one route can fail while the others succeed.

The root document

Exported files

An element with o:=name becomes the file route/name for every route you deploy to.

• Files answer for any method. The name is matched against the last path segment, case-sensitively, and the query is ignored.
• A name contains a . and no /. Leading-dot names such as .css and .js are valid. Reserved paths lists the names that cannot be reached.
• The content type comes from h:content-type, then o:type, then the extension, then the type of a data: URL. Response headers has the details.
• An h:name=value attribute becomes a response header of that file.
• HTML pages exported from templates get a doctype when a browser navigates to them, but no generated social tags.
• Elements with the same export name are joined with newlines, and the headers and type of the first one apply. Never reuse the name of a binary file.
• <img o:=name.ext src=data:…> exports the decoded bytes as a binary file.
• A <template> can be exported itself. The o:= elements inside it are exported on RTEdge.net, but the playground does not look inside templates, so keep shared files outside them.

<title>Demo</title>
<style o:=.css h:cache-control="public, max-age=300">
  body { font: 1rem/1.5 system-ui; color-scheme: light dark }
</style>
<template o:=About.html edge:redact>
  <meta charset=utf-8><link rel=stylesheet href=.css>
  <h1>About</h1>
</template>
<iframe src=About.html edge:remove></iframe>
<a href=About.html>About</a>

The edge worker

• A route has at most one edge worker. All <script type=worker edge> elements are merged in document order, and the attributes of the first one apply. A worker script without edge runs only in the playground and is not deployed.
• Every <script type=worker>, with or without edge, is removed from the served page. The source view still shows it.
• The worker is uploaded as its own isolated Cloudflare Workers for Platforms script. It answers route/:… and the fallbacks described in Request routing. Its env holds KV and FS.
• Redeploying a route without an edge worker deletes the route's worker and frees its slot.
• A worker keeps the runtime settings of its last deploy. Its compatibility date is the day of that deploy, in UTC, and the wrapper around your code is the one that was current then. Redeploy to pick up newer ones.

See The edge worker runtime.

Metadata and the digest

RTEdge.net keeps a small record for each route: the owner, which is the first account that deployed it, the editors, the deploy time with a digest, the last saver, and whether the route has a worker. The saver is the editor who deployed last. It disappears when the owner deploys again.

The digest changes on every deploy, even when the content is identical, so it detects change rather than describing content. Pages and files send the deploy time as their deploy response header, and route/::meta returns the digest hash. Experimental See The ::meta suffix.

<script type=module>
  const digest = () => fetch('::meta', { cache: 'no-store' }).then(r => r.json()).then(j => j?.digest?.hash, () => null)
  const last = await digest()
  last && setInterval(() => digest().then(now => now && now !== last && location.reload()), 30_000)
</script>

The version

Each deploy is also recorded as a version of the route: the stored playground state, your source, the document that was served, the exported files and the worker code. A few seconds after the deploy the version shows up in the version viewer, because it is written in the background. Worker modules and WebAssembly files that were fetched at deploy time are not kept, only their names. Deleting a deployment records a deletion, and keeps the older versions. Versions and Smart Undo shows how to browse, compare and restore them.

The screenshot

Every deploy queues a screenshot of route/. It is taken at a 1200 by 630 CSS pixel viewport, at twice the scale, so it is a 2400 by 1260 PNG, once the page's network requests have settled. Areas the page does not paint are transparent. The image is kept with the version history, and it is the default og:image of the page. Only the root document gets one. Social previews and screenshots has the details.

Freshness after a deploy

Every request reads the deployment from globally replicated storage, which is eventually consistent. Other locations can show the previous version for a short while after a deploy or a delete. Cloudflare documents up to about 60 seconds for this kind of storage.

For 90 seconds after the owner's latest deploy or delete, two kinds of request read the owner's fresh copy instead: requests that carry Cache-Control: no-cache or max-age=0, which is what a browser reload sends, and document navigations whose referrer is https://rtcode.io/, such as the links in the deploy toasts. The Edge: Open command opens routes without a referrer, so its first load can still show the previous version. Reload to see the new one.

Pages are sent with cache-control: no-store. Exported files have no cache-control unless you set one with h:cache-control. A signed-in deployer who reloads a route that was just deployed for the first time sees it at once, while other visitors can see "Code does not exist." until it has propagated.

Guarantees and limits

• Deleting a deployment removes its worker and stored files, and frees its size and its worker slot from your quota. It keeps the version history, the past screenshots and your domain claim. The URL then answers 404, "Code does not exist."
• Removing a route from the Routes field does not delete what was deployed there. Delete the deployment while the route is still listed.
• Every route is published on its own, so check each route after a deploy.
• A deployment keeps the behaviour of the platform at the time of its deploy. Redeploy a route to apply the current rules.

Related concepts

Request routing

How a URL finds its route, and which part of the deployment answers it.

Security and access model

Who can view a deployment and who can open its source.

Playground and edge differences

What changes between the live preview and the deployment.

Architecture

How the editor, the output and the edge fit together.

See also

• Deploying to RTEdge.net
• Versions and Smart Undo
• Social previews and screenshots
• Exporting files with o:
• Response headers
• Limits and quotas
• Keeping secrets out of deployments