Request routing

Overview

A request to a deployed host passes through these steps in order. A step either lets the request through or answers it, and the first step that answers ends the request. Step 1 only rewrites the URL, and step 15 adjusts whatever answered. Steps 1 to 4 and 15 belong to the platform around your deployment, and steps 5 to 14 to the edge router that serves it.

Routes are directories

For the route strings you enter in the playground, see Routes. This section explains how incoming URLs select those deployments.

The router builds the route from the host and the part of the path before the first :. It removes the last path segment and any trailing slashes. That exact route is read and nothing else: parent routes are never searched. For name.rt.ht the host part is just name, and for a custom domain it is the whole hostname.

So https://name.rt.ht/docs/sub/ answers 404, "Code does not exist.", unless name/docs/sub is itself deployed, even when name/docs has a worker. Path routes are independent deployments, each with its own files, worker, versions and screenshots. They share one browser origin, though: all the path routes of a host share its cookies, storage, service worker scopes and sign-in session. Domains and subdomains explains hosts and paths.

Canonical URLs

Before a request is routed, the platform rewrites some URLs into one canonical form. All of these are 307 redirects:

• A path with no trailing slash that contains no ., * or : gets a slash, for any method, and keeps its query: /docs becomes /docs/.
• When the URL has a ? and the request is a document navigation, /docs? becomes /docs/?. This keeps the bare ? that opens the source.
• A path that ends in a single : gets a slash before it: /docs: becomes /docs/:.
• A path that ends in /* loses the slash: /docs/* becomes /docs*.

Because of the first rule, https://name.rt.ht/api/users is redirected to /api/users/, which is the route name/api/users, not an API of the route name. Reach a worker with a worker path instead, /:api/users. Write the URLs of directories with a trailing slash. File names stay case-sensitive: /NAV.JS does not find nav.js.

Worker paths

The first : in a path splits it. The text before it chooses the route, as above. The text after it becomes the worker's pathname, and the query string is kept.

• Apart from the router's own :: suffixes, a : path goes to the worker before the deployment is read, and it is not checked against edge:user. A worker that must know who is calling checks request.rt.user itself.
• On a path route always write the slash: /docs/:x. A path such as /docs:x without it belongs to the parent route.
• Pages can use the relative form, :hello, which resolves against the page's directory, so on /docs/ it means /docs/:hello.
• A request that reaches the worker without a :, as a fallback, keeps its original pathname, with the route's prefix. A worker on the route name/docs sees /docs/x.json for a fallback and /x for /docs/:x.

The playground output splits : paths the same way, so the same code works in both places. See The /: suffix.

Try a worker path

The iframe asks the worker for :hello. The worker answers with the pathname it sees and its route. In the playground the route is the output host. Deployed to name/docs, the same code answers {"path":"/hello","route":"name/docs"}.

<iframe src=:hello></iframe>
<script type=worker edge>
  export default { fetch: r => Response.json({ path: new URL(r.url).pathname, route: r.rt.route }) }
</script>

Platform suffixes come first

Suffixes such as ::si for sign-in are answered by the platform, before the router and before your deployment is read. They apply to every URL of every platform host, deployed or not, and your code cannot override them. Most of them are matched as a piece of the path, wherever it is, and not only at the end. A path such as /:api::save contains ::s, so the sign-in handler answers it and it never reaches your worker.

Keep :: out of file names, route paths and worker paths. Reserved paths lists the patterns, and URL suffixes describes each suffix.

Source, versions and the index

• ?? is answered before the deployment is read, so it works for any route, even one that was never deployed. It redirects to the version viewer. See The ?? suffix.
• * lists the deployments you own or edit under a host or path. A visitor who is not signed in is sent to sign in first. See The * suffix.
• ? opens the deployed source in RTCode.io. It is answered after the deployment is read and before the edge:user check, so the source view follows its own access rules. See The ? suffix and Restricting access.

The playground output has none of these. They belong to the router.

Access checks

After the source view, the edge:user check decides who may view the deployment. It protects the root document, exported files and fallback calls to the worker, but not : worker paths. A visitor who fails it gets the 401 or 403 page from Error pages and status codes.

Files, page and worker

An exported file answers when the last segment of the path equals its name. Matching is case-sensitive and ignores the query, so /nav.js?v=2 serves nav.js. Files answer for every method, and an export wins over the worker, so a worker never sees a request for a path that matches an export.

The root document answers GET only. Everything else that has no answer goes to the worker, with the original URL, when one of these holds:

• The page is empty after processing.
• The path is not the route root, such as a dotted name that no export matches.
• The method is not GET.

Without a worker, the answer is 404, "File does not exist." That makes an API-only route possible: leave the page empty and let the worker answer GET of the root.

Routing in the playground

In the playground, your page is the document of an output origin, and a service worker answers its requests. In short, it answers ::su first, then an exported file whose last segment contains a dot (your own files, then those of sibling routes), then the worker for every other request except GET /. GET / always returns your page, and anything left goes to the network. Hosts that you list in io:host reach the worker too. The playground has no router, so the platform steps above do not exist there.

Because every non-root path reaches the worker in the playground, test clean paths on a deployment before you rely on them. Playground and edge differences lists the other differences.

Guarantees and limits

• Every directory is its own deployment. There is no fallback to a shorter route.
• Reads are eventually consistent after a deploy. See Freshness after a deploy.
• The root document answers GET only. A HEAD request goes to the worker, or answers "File does not exist." Use GET for health checks.
• At the edge, a worker's fetch() needs absolute URLs. A relative URL does not resolve there. Use an absolute URL, or a worker:fs asset for your own files.
• Platform suffixes and reserved names cannot be overridden by your code.

Related concepts

Anatomy of a deployment

What a route holds: the page, files, worker, metadata, version and screenshot.

Playground and edge differences

Everything that behaves differently in the playground and on RTEdge.net, in one table.

Security and access model

Sites, sessions and permits: who can view a page, and who can open its source.

Architecture

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

See also

• Routes
• URL suffixes
• Reserved paths
• Error pages and status codes
• Response headers
• Domains and subdomains
• The edge worker runtime
• The fetch() handler