- Hyperclay Local
- Docs
- Serving documents
- Addresses and reserved routes
Addresses and reserved routes
How Hyperclay Local maps URLs on localhost to documents, static files, client-side routes, and reserved /_/ endpoints.
Every served folder in Hyperclay Local runs an HTTP server bound to 127.0.0.1 (localhost) on its assigned port: 4321 for your personal folder, and 5432, 6543, 7654, 8765, 9876 (or a random port between 49152 and 65535) for team folders. See Folders and ports.
URL mapping#
With the server running on a folder (shown below using port 4321):
| URL | Serves |
|---|---|
http://localhost:4321/ | On a top-level browser GET, redirects (302) to the workspace window entry URL (/enter?ticket=…, valid for 60 seconds, which sets a hyperclay-workspace-<port> session cookie). For HEAD requests, framed loads, or when the workspace cannot start, serves the directory listing of the folder root. |
http://localhost:4321/notes.html | The document notes.html |
http://localhost:4321/blog/ | Directory listing of blog/ |
http://localhost:4321/blog/post.html | The document blog/post.html |
http://localhost:4321/blog/post.html/any/route | Also blog/post.html; everything after the .html or .htmlclay extension is a client-side route |
http://localhost:4321/logo.png | Any static file, sent as-is |
http://localhost:4321/_/uploads/assets-notes/photo-2cf24d.png | An attachment stored inside uploads/ in the served folder |
Documents and static files#
- Documents: Files ending in
.htmland.htmlclayare served as malleable documents. Each served document carries adocumentetagattribute on its root<html>element with the ETag stamp of the served bytes (the file on disk is untouched, and the attribute is stripped on save). - Static assets: Every other file type is served as a static asset with
X-Content-Type-Options: nosniff. - SVG and uploaded web-page types:
.svgand.svgzfiles, as well as any web-page file type placed insideuploads/, are served withContent-Disposition: attachmentandX-Content-Type-Options: nosniff. An SVG or uploaded HTML file cannot execute inline with the origin’s authority. - Uploads route (
/_/uploads/): Serves only files inside the realuploads/folder of the served root. Every byte of a filename outside the unreserved set is percent-encoded, and symbolic links pointing outside the folder are refused.
Path validation and hidden files#
Requests are validated before they touch the filesystem:
- No backslashes (
\), no null bytes (\0), no absolute paths, and no.or..segments. - No path segment longer than
255characters. - Any path segment beginning with
.(including.hyperclay/,.hyperclay/versions/,.hyperclay/conflicts/, and.trash/) returns404. sites-versionsis a reserved first path segment and is never served over HTTP.
See Rejected requests for the complete list of request checks.
Reserved /_/ system routes#
All system endpoints live under the /_/ prefix:
/_/save(and legacy/save): Write a document to disk. See Saving and stale-write protection./_/meta: Inspect host capabilities and per-document metadata. See Metadata and uploads./_/uploadand/_/uploads/: Upload and serve document attachments. See Metadata and uploads./_/syncand/_/live-sync: Broadcast and subscribe to live tab updates. See Live updates between tabs./_/api: Read and write documents as JSON using CSS selector rules. See Data API./_/data-loss: Inspect or resolve data-clobber guard incidents. See Saving and stale-write protection./_/versions,/_/version, and/_/restore: List, inspect, and restore saved versions and recovered copies. See Version history routes./_/wire: Run helper programs and wire commands. See Programs and helpers.
Any unknown path under /_/ returns 404, so a request such as /_/foo.html never falls through to be served as a document.