Technical Manual sections
Reference › Technical Manual › Kitten’s operating model
These are the rules that shape and drive Kitten’s development.
What separates a Small Web site from a Big Web site is who owns and controls it.
Kitten is a tool for building Small Web sites and apps, which are owned and controlled by individuals. Our greatest advantage is simplicity. Specifically, it’s the complexity we avoid by limiting Small Web servers to a single app with a single owner.
This fundamental design decision removes a whole class of complexity: we don’t have “users” or “accounts”, we have “the owner”. We don’t have to worry about roles, etc., during authentication and authorisation, etc.
A Kitten server, therefore, serves one app for the one person who owns it.
During development and on your local machine, you can run as many servers as you like. The test suites, for example, run several instances of one app at the same time, each at its own port, using the Kitten helper in tests/helpers/Kitten.ts.
Similarly, when testing peer-to-peer Small Web apps, you can run multiple instances locally using the place1.localhost, place2.localhost, etc., aliases.
We follow web standards and good practices (semantic HTML, accessible code, etc.)
We don’t implement what the browser or the operating system already provides. (For example, Kitten has no idle timeout, because an unattended device is the screen lock’s job.)
We value simplicity and we’re always on the look out for how we can make Kitten simpler, more elegant, and easier to use.
While you can build traditional, centralised web apps with Kitten (or just have it serve your static web site from 1993), Kitten is designed for the Small Web. That is to say, the personal, peer-to-peer web.
When designing Kitten features and Kitten apps, we keep the following principles in mind:
A person’s data is their own and always stays on their server.
Communication between peers involves the sending of messages in a topologically decentralised network of always on nodes with static, well-known addresses, not on replicating data.
The originator of a piece of data can always delete it or deny access to it at any time.
This is why Auto Encrypt Localhost exists, for example (so we can use TLS in development).
Development and production differ only where they must. Kitten runs in production when the PRODUCTION environment variable is true, as it is in the systemd unit written by the kitten deploy command.
In production, Kitten:
runs the Kitten bundle directly under systemd, without the process manager,
doesn’t restart when a file in the project changes (see File changes),
compiles TypeScript without inline source maps,
serves the minified versions of the client-side libraries that have one (
kitten.libraries),leaves out the hot reload script (from pages, static HTML files, and error pages) and the HTML validator,
doesn’t log development warnings (
warnOnceInDevelopment()),shows error pages without stack traces or source code,
adds the HTTP Strict Transport Security (HSTS) header,
opens the app’s git working copy and starts automatic updates, and
restarts once a day (see step 11 of Initialisation (asynchronous)), so JSDB compacts the tables.
In development, a change to any file in the project (except those in node_modules/ and in hidden files and folders other than .well-known/) exits the worker with the restart request code (systemExitCodes.restartRequest, which is 99), and the Kitten Process Manager forks a new worker (see File changes). An uncaught exception exits with the same code.
In production, systemd restarts Kitten after any non-clean exit (see Errors and restarts).
Slow tests are tests people don’t run. We measure and track wall clock time of tests to ensure that we run them often.
When Kitten catches an error on an author’s behalf, it must print a message that explains the issue to the author in plain language and provides information they can act on. If there are known/possible fixes, mention them.
All Kitten data is stored under kitten.paths.KITTEN_DATA_HOME, and each app’s data is in its own subfolder of kitten.paths.KITTEN_DATA_DIRECTORY (kitten.paths.APP_DATA_DIRECTORY), the name of which is the app’s project identifier (see Serve and, for random ports, Domains and domain aliases). We never store Kitten or app data outside of those folders.
We keep the reference, tutorials, and this technical manual up to date as we continue to develop Kitten.