Kitten

Reference sections

Kitten automatically normalises URLs that do not have a trailing slash when they should to add one.

It does so using a permanent 308 redirect that preserves the method of the request.

This means, for example, that a request to https://my.site/hello will be forwarded to https://my.site/hello/.

This is both to help implement canonical paths for your sites/apps and to avoid the unexpected situation of a relative include failing from your page if a slash is not provided in the path. (e.g., if you have an index.js file and an index.html file in a folder called hello and you include the JavaScript file using <script src='./index.js'></script>, that will succeed if the page is hit as /hello/ but fail if it is hit as /hello.)

Kitten tries to be as minimally invasive into your site or app’s own namespace as possible. That said, there are certain routes that it does reserve. Some of these are part of the Small Web protocol and others are Kitten-specific.

Paths under /💕/ and /🐱/ belong to Kitten, and so do paths below /uploads/, where Kitten serves uploads. A route file in your app, or a route that main.script.js adds through the router object, at one of those paths stops Kitten at start-up with a line that mentions the file (or the router call) and the URL. (/uploads/ itself is yours. A [slug] or [any] route at the root of your app also matches those paths, and Kitten doesn’t refuse it, as its own routes come first.)

Kitten-specific routes are kept in the 🐱 namespace so as not to pollute your app/site’s own URI space.

These include routes for default functionality that Kitten provides like the settings interface:

The protocol is currently under development and evolving rapidly.

The following routes are reserved as part of the Small Web protocol, which is namespaced by the Small Web emoji/logo (💕).

They are used to implement public-key authentication and manage the communication between Small Web instances and the Catalyst instances that host them:

Kitten’s sign-in and sign-out routes are also in this namespace:

Kitten currently does not implement the full Small Web protocol. (The Small Web protocol is, itself, a work in progress.) It is currently up to apps to implement aspects of it in ways that make sense for them.

For example, Place is in the process of implementing the following routes:

In time we’ll see whether or not it makes sense to pull in more base Small Web protocol implementations into Kitten proper.

Before it handles sessions and sign-in, Kitten checks two tables in its internal database on each request. Both tables are plain objects. Set a property to add a redirect, and delete it to remove one.

The kitten._db.settings.domainRedirects table maps a Host header value to a URL prefix. Kitten redirects a request whose Host header is a key to the value followed by the request’s path and query, with a 307 redirect. The value must not end with a slash.

When it starts, Kitten requests one TLS certificate for the app’s domain and all keys together, so a new domain redirect takes effect after a restart. If DNS for a key does not point at the server, the certificate is refused and the restart fails. Deleting a domain redirect takes effect on the next request.

kitten._db.settings.domainRedirects['old.example'] = 'https://new.example'

With this redirect, Kitten redirects https://old.example/notes/?page=2 to https://new.example/notes/?page=2.

Kitten checks domain redirects before URL normalisation, so the path reaches the new domain unchanged: https://old.example/notes redirects to https://new.example/notes.

Look over there! is a Kitten app that manages domain redirects, with HTTPS for each redirected domain.

The kitten._db.settings.localRedirects table maps a request path to a location. The key is the path as the browser requests it: percent-encoded and without the query. URL normalisation runs first, so the key ends with a slash unless its last segment contains a dot (/blog/2024/hello/, /about.html).

The value is any location that the response.redirect() method accepts. Kitten encodes each % in it that does not start an escape as %25. Kitten redirects the request with a 307 redirect.

kitten._db.settings.localRedirects['/blog/2024/hello/'] = '/notes/hello/'

A local redirect preserves links when the structure of a site changes.

Kitten has built-in support for the Evergreen Web (404 to 307) technique.

To implement 404 to 307 redirection for your Small Web place in Kitten, simply set domain you want to forward to in your Small Web Settings page which you can reach in your browser at /🐱/settings/.

Let’s say you are deploying your new Small Web place at your own domain (e.g., https://ar.al) but you already have a personal web site or a blog there. You will already have content that other people might have linked to and/or rely on. It would be a shame for all those links to break when you deploy your new site.

The Evergreen Web (404 to 307) technique is very simple:

On your new site, issue a 307 redirect for any paths that result in a 404 (not found) error to the previous version of your site. That way, if the path existed in the previous version of your site, it will be found there and, if it did not, it will result in a 404 error there.

Of course, you’re not limited to one level of indirection. If the previous version of your site replaced an even earlier version, there’s no reason why you cannot add a 404 to 307 rule there also and have a chain of redirects going all the way back to the earliest version of your site.

One of the great advantages of this technique is that you can just leave older versions of your site running (perhaps at different subdomains) and they can all continue to exist using whatever technologies they were using at the time. (You don’t have to take static exports, etc., of the data.)

By using 404 to 307, you will contribute to an evergreen web by not breaking URLs.

To see it in action, run the evergreen-web example.

For more information, see 4042307.org.

Similar to the Evergreen Web technique, but useful when your old site was static (or if you output a static version of your old site).

Kitten looks for three special folders:

If they exist, it serves their contents as static files from the root of the site.

These routes are added after all other routes.

So if a route cannot be found in the current version of your site, Kitten will search for it in the above archives, in the order shown above.

Like this? Fund us!

Small Technology Foundation is a tiny, independent not-for-profit.

We exist in part thanks to patronage by people like you. If you share our vision and want to support our work, please become a patron or donate to us today and help us continue to exist.