Kitten

Technical Manual sections

In production, Kitten updates itself and the app it serves in one transaction: either both move to their new versions and the new server’s home page is healthy, or both go back to where they were. (Without a deployed app, the kitten update command updates only Kitten.)

These are the parts:

A check runs like this:

  1. If an update is pending (updates/pending exists), the check ends as busy. Otherwise, it fetches the head of the tracked branch and asks for the newest release of each API version involved (the running Kitten’s, the installed commit’s, and the head’s).

  2. The chooseUpdateTarget() function (src/lib/updateTarget.ts) chooses a target: a Kitten release and an app commit. It prefers the head with the newest Kitten for the head’s API version, then the installed commit with a newer Kitten, and then the head with the running Kitten. It never chooses a head that declares an older API version than the running Kitten’s, and it skips every target that failed before (updates/failed/). A head that declares no API version is only a candidate in a requested check, which treats it as declaring the running Kitten’s API version.

  3. The apply() function (src/lib/applyUpdate.ts) checks that there is enough free space (requiredBytes() in src/lib/updateSpace.ts) and stages the Kitten release if Kitten changes. It refuses an app that has local work the checkout would overwrite, or that is on another file system than the data home. It installs the app’s changed dependencies in updates/staged-dependencies/ and records the status code of the home page as the baseline. Then it writes the pending record (updates/pending, in the staged state, with a startDeadlineSeconds of five times the last start’s duration and at least 60 seconds), activates the new Kitten, and asks for a restart.

  4. In production, when updates/pending exists, the launcher runs the update guard (src/entry/update-guard.ts, src/lib/updateGuard.ts) before it starts Kitten. If the history already contains the update as confirmed, the guard deletes the pending record and exits with 0. If a staged record is for another version, the guard points the symbolic links at that version and exits with 3. (If the links already point there, the guard exits with 1 and reports the launcher to run. If the folder of that version or of its runtime doesn’t exist, the guard deletes the pending record and exits with 0.) Otherwise, the guard switches over (switchTo() in src/lib/updateTransaction.ts): it snapshots db/ and _db/ in updates/snapshots/, checks out the app commit, moves the staged dependencies into place, and sets the record to started with one attempt.

  5. Once it is listening, the Kitten Server requests its own home page. If the status is healthy (isHealthy() in src/lib/updateConfirmation.ts: a response with a status under 500, or any result if the home page had no response or a status of 500 or more before the update), the confirm() function removes the change logs that the 2026-11-07 release recorded in updates/history.jsonl (removeRecordedChangeLogs()), adds the update to it, deletes the pending record, and deletes the staged dependencies and the snapshots of other updates. After an update that changed Kitten, it also prunes every version and runtime other than the new and the previous ones. (After an app-only update, it preserves every version and runtime.) Otherwise, the server exits with the restart request code. A worker thread (startDeadline()) ends the process with SIGKILL if the server hasn’t confirmed the update within the record’s startDeadlineSeconds.

  6. Each start that finds a started record with fewer than MAX_FAILED_STARTS (2) attempts adds one attempt and starts the new version again. A start that finds two attempts, or a record for another version, rolls the update back (rollBack()): it checks out the previous commit, removes the files the update added, restores node_modules, moves the app’s databases to updates/failed-data/<id>/ and restores the snapshot, points the symbolic links back, records the target as failed, adds the rollback to the history, and deletes the pending record. If a step of the rollback fails, Kitten keeps the record, and the next start tries again.

State Diagram: The states of an update

The automatic updates use these files and folders in updates/ in the data home:

The unit tests cannot exercise an update on a real server. The automatic updates rehearsal does. Run its reset and scenarios 1, 2, 14, 6, 7, and 12 (npm run rehearsal -- 1 2 14 6 7 12) before a release that changes install, build-templates/kitten, update-guard.js, KittenPackage.ts, or AutomaticUpdates.ts, and its reset and all fifteen (npm run rehearsal) before a release that changes the update transaction or starts a new Kitten API version.

Source code:

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.