Module hats 

Hats (kernel spec §5; umbrella §8): the isolation boundary a session belongs to. A hat is {id, name, colour}; every host has a default hat, and per-host path rules (prefix → hat) pick another for the paths under them. The registry keeps them beside the hosts, on the same connection (Hosts), so a host and its default hat always change together. Every query names the database’s owner (kernel spec §1).

Resolution (kernel spec §5.2) is a pure function of a host’s rules, its default hat and a canonical path (resolve): rules match by path segment, the longest prefix wins, and no match means the host’s default hat. Canonicalisation itself happens on the host, where the filesystem is; here a path is only ever checked to be in canonical form (is_canonical), never trusted to be.

Structs

HatRecord

One hat, as GET /api/hats lists it.

NewRule

A rule to store, its prefix already in canonical form.

PathRule

One stored path rule of a host (kernel spec §5.1).

Resolution

Which hat a path resolves to on a host, and the rule that decided it (None: no rule matched, so the host’s default hat).

Enums

HatChange

The outcome of Hosts::create_hat and Hosts::update_hat.

HostChange

The outcome of Hosts::update_host.

PurgeStart

The outcome of Hosts::begin_purge.

RulesChange

The outcome of Hosts::replace_path_rules.

SessionHat

The hat a session’s canonical cwd gets (Hosts::session_hat).

Constants

DEFAULT_COLOUR

The colour a hat gets when none is given: slate, neither a warning nor a brand.

MAX_PATH

The longest path accepted, in bytes: Linux’s PATH_MAX.

MAX_RULES

The most path rules one host has (plan 5a decision 6).

Functions

covers

Whether the rule prefix covers path: it is the path, or a parent of it by whole segments (/p/acme covers /p/acme/x, never /p/acme-infra). Both are canonical.

hat_name_problem

Why name cannot name a hat, if it cannot: the rule for host names (1 to 64 printable characters once trimmed, no invisible format characters).

is_canonical

Whether path is already in the form normalize_lexically gives. A path from a host is checked with this before it is matched against any rule: the host is authenticated, but its answer is still its own words.

near_miss

A rule that does not cover path byte for byte but would if case were ignored, that would then win over decided (a longer prefix than its rule’s, or any prefix when no rule decided), and that names another hat (the review’s P4). A case-insensitive volume is where that happens: the rule’s prefix holds another case than the directory has now, because it was saved before the directory existed, or the directory was renamed since (the review’s B2, which is why verified rules count too). Its sessions would fall silently to another hat (plan 5c decision 3).

normalize_lexically

path in canonical form by its text alone (kernel spec §5.2’s unverified rule): absolute, empty and . segments dropped, no trailing slash. Refuses a relative path, a .. segment (the review’s O1: by its text alone it can disagree with the filesystem when a parent is a symlink), a NUL or other control character, and a path longer than MAX_PATH. Symlinks are not resolved: only the host can do that.

parse_colour

A hat’s colour as given, if it is #rrggbb: returned lowercase. The frontend applies it as a CSS custom property, so nothing else may pass.

resolve

The hat path (canonical) resolves to among a host’s rules, with default_hat when no rule covers it (kernel spec §5.2): the longest covering prefix wins. Two rules never share a prefix on one host.

session_hat_in

Resolve placement in the caller’s mutation transaction. Delegated allocation and dispatch use this rather than retaining a preflight path-rule decision.