Canonical URLs in the Kireji Web Framework

Edited Dec 20, 2025 | Posted Nov 3, 2025 | ~1 minute read

In the Kireji Web Framework, a canonical URL is a short, human-readable URL that defines an override for the state of the ecosystem compared to the default landing hash (or the current state the client is in).

This allows Kireji's atypical routing system to feature the same behavior as a typical website: the ability to have simple, unversioned links like:

https://example.com/my-favorite-page

Because these URLs lack query parameters, they lack composition (multiple URLs can't be combined deterministically into a merged form). This means that they aren't as comprehensive as Kireji's own hash routing system. It also means that only one override to the state can be defined per canonical URL. This simplifies and constrains the translation behavior in Kireji.

URL Structure

Canonical URLs are composed of just two parts: an origin

https://example.com

and a pathname

/my-favorite-page

Kireji URLs, on the other hand, are composed of three parts: an origin, an ecosystem version number, and a state hash.

https://example.com/1.2.3/aurg3248gh23rg-234rfwrv_asdf

The challenge for canonical URLs is to design a translation service that turns canonical URLs into Kireji URLs.

Luckily, the origin is easy for the server to handle: its the same for both URLs and features the domain name being used to access the server. Adding the version number is also trivial: all canonical links point to the latest LTS version of the ecosystem which happens to be the current version of the server.

So, the main task for the translation service is really just converting a human-readable pathname into a stateful hash.

In Kireji, hashes are cross-origin and mean the same thing across all host names. For example:

https://aaaa.example.com/1.0.0/24rtgetb

is the same data as

https://bbbb.example.com/1.0.0/24rtgetb

just viewed from a different app. In contrast, canonical paths mean something different for each origin.

https://store.example.com/red-shirt

is not the same thing as

https://star-trek-characters.example.com/red-shirt

That needs to be taken into consideration for the translation logic.

URL-as-a-File Metaphor

The routing model for a Kireji ecosystem can be thought of as a file type spec, such that Kireji URLs can be thought of as highly compressed, lossless save files. These files have a simple structure: a small header provides the origin (indicating the application that is currently full-screened) and version number of the file spec. This is then followed by the file body: a block of data which achieves the information-theoretic lower bound for data compression according to the file spec.

This is analogous to how common file types such as GIF feature a small header with meta data followed by blocks of data representing the file.

Under this metaphor, canonical URLs are a bit strange - the equivalent of having a GIF spec that includes a handful of predefined GIFs which can be accessed by simply writing their name as plain text and giving the file a .gif extension. All GIF readers would then have to store a table containing all these premade GIFs according to their name.

This would be unusual behavior for a file type like GIF, but its expected behavior when fetching web URLs.

Use Cases for Canonical URLs

Critically, canonical links have two use cases in Kireji:

1. External Linking
   • This is their main purpose: providing familiar, marketing-friendly links like ad-click links and search engine results.
   • These need to be unversioned and human-readable. This makes them easy to type, understand and share.
   • The server needs to be able to translate these into versioned Kireji URLs so we know exactly what file they represent.
2. Internal Linking
   • Any anchor links inside Kireji web apps (including any sitemap) will get indexed by search engines and become external links, so we don't want to see this anywhere in the web app's source code:

     <a href="https://example.com/1.0.0/4gw5-g5wnzzw35h4g">Click here</a>

   • Besides, rendering versioned anchor links inside app HTML would be annoying and not straightforward - link elements would need to be tracked and their href attributes updated every time the ecosystem state changed. This would cause an explosion of URLs that would confuse search engine spiders.
   • Hovering over links helps desktop users gain additional context about where the link will go. This doesn't look like anything to the user:

     https://example.com/1.0.0/4gw5-g5wnzzw35h4g

     Whereas this is clear:

     https://example.com/contact-us

   • As is common in web apps, anchor tags require onclick handlers to interrupt internal link clicks in order to update parts of the page without navigating away. In Kireji, this is even more important to retain file data encoded in the URL hash.

Given the usefulness and requirements of canonical URLs both internally and externally, the canonical link translator has the opportunity to kill two birds with one stone:

1. It can enhance search engine optimization and the first arrival experience.
2. It creates a URL language that tells the client exactly what aspect of the current file a given anchor link is meant to change (making canonical URLs behave more like tools than destinations) without having to encode that behavior separately in the onclick handler.

Different versions of the ecosystem will still function correctly even if they support different canonical URLs but there are two complications introduced by versioning:

1. A canonical URL that was hard-coded into an old version may not be supported several versions later. Older versions of the ecosystem should thus avoid being indexed by search engines.
2. The fact that an unsupported canonical URL still works on an old versioned page may confuse some users. This could happen if, for example, the user notes a URL while hovering over a link and sees that it works when clicked but not when shared. This is a rare edge case however, and its a risk that we can accept right now.

Final Translation Methodology

After breaking down these use cases, the optimal implementation is one where canonical URLs represent a delta or tool which describes a change-of-state to the base state. When linking internally, that base state is the current versioned URL hash. When coming into the ecosystem from an external link, that base state is the default landing hash.

These delta operations must account for the need to both set and unset state parameters. For example, the empty pathname (e.g. https://example.com/) most likely represents a home page, which is probably the default landing state and so the delta shouldn't need to do anything. In contrast, linking to https://example.com/ from https://example.com/1.0.0/gr224-245g-435 may require hiding an article and then redrawing the home page. So, canonical URLs represent functional but idempotent tools.