livery.toolroom.bench._index¶
livery.toolroom.bench._index ¶
The published index: every record materialised into a store served as static files.
A client never replays a record. The build resolves every version of every tool and lands what it resolves to as content-addressed objects, one tree per tool:
tool the tool axis, the record's first line as canonical JSON
versions every version tracked, oldest first
<version>/observation who read the version; its help, extractor, absences
<version>/hosts/<host> the deployment resolved for that host
<version>/surface the version's verbs whole, each with its options
Adjacent versions share every unchanged blob by content address, and any version is addressable without replay. Refs are local, so beside the store the build writes one pointer document naming each tool's current tree and the digest of the record it was built from. Everything under a tree is immutable and cacheable for as long as anyone likes; only the pointer needs a short lifetime. The index holds no stubs: a consumer renders the stub of the version it locks from that version's surface, through the store.
The build replays to identical digests: two builds from genesis land
equal objects and equal pointers. A build into a directory holding an
earlier build reads that pointer and reuses every tool whose record
digest did not move, and a build whose records directory is unmoved
since the last, by the stat fingerprint the build keeps in build.json
beside the pointer, reads no record at all and answers from the
pointer, an optimisation and never authority, since --from-genesis
rebuilds every tool from the records alone.
Classes:
| Name | Description |
|---|---|
Built |
What one build did, as data. |
Functions:
| Name | Description |
|---|---|
record_digest |
The digest of the record file path as authored: its name and its bytes. |
open_index |
The index store at into, created on first use. |
read_pointer |
The pointer document at into, or |
load_records |
Every record under records, by name. |
build |
Materialise every record under records into the index at into. |
materialise |
Land record whole into store and return its tree's digest. |
Attributes:
| Name | Type | Description |
|---|---|---|
INDEX |
The namespace of the index store: |
|
POINTER |
The pointer document, beside the store's layout at the index root. |
|
SCHEMA |
The pointer document's shape. Bumped when a reader must know. |
|
BY |
Who moves the index refs: the build, named by its verb. |
INDEX
module-attribute
¶
The namespace of the index store: index/<tool> names the tool's tree; volatile.
POINTER
module-attribute
¶
The pointer document, beside the store's layout at the index root.
BY
module-attribute
¶
BY = Subject('call', 'toolroom.index.build')
Who moves the index refs: the build, named by its verb.
Built
dataclass
¶
Built(into: str, tools: dict[str, str], rebuilt: tuple[str, ...], reused: tuple[str, ...], dropped: tuple[str, ...])
What one build did, as data.
Attributes:
| Name | Type | Description |
|---|---|---|
into |
str
|
The index root, holding the store's layout and the pointer. |
tools |
dict[str, str]
|
Tool name to the digest of its current tree, every tool. |
rebuilt |
tuple[str, ...]
|
The tools materialised on this build. |
reused |
tuple[str, ...]
|
The tools whose earlier tree stood, their record unmoved. |
dropped |
tuple[str, ...]
|
The tools the earlier pointer named and no record has. |
record_digest ¶
The digest of the record file path as authored: its name and its bytes.
Hashed as written, never re-serialised: a record moved anywhere digests the same, one edited anywhere does not, and the cost is a read of the bytes rather than a parse and a canonical dump.
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_index.py
open_index ¶
The index store at into, created on first use.
Raises:
| Type | Description |
|---|---|
ManifestError
|
when into holds a store of another layout. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_index.py
read_pointer ¶
The pointer document at into, or None when there is none.
Raises:
| Type | Description |
|---|---|
ValueError
|
when the file is there and is not a pointer this build understands, naming the file. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_index.py
load_records ¶
Every record under records, by name.
Raises:
| Type | Description |
|---|---|
RecordError
|
for a record that does not validate, as the store refuses it. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_index.py
build ¶
Materialise every record under records into the index at into.
A tool whose record digest matches the pointer's, and whose tree the store still names, is reused; every other tool is materialised and its ref moved. A tool the pointer names and no record has is dropped. from_genesis ignores the pointer and materialises every tool.
Before any record is read, the build asks whether anything moved:
build.json beside the pointer holds a stat fingerprint of the
records directory from the last build, and when it stands and every
tree and ref the pointer names is present, the build answers from
the pointer alone.
Returns:
| Type | Description |
|---|---|
Built
|
What the build did. |
Raises:
| Type | Description |
|---|---|
RecordError
|
for a record that does not validate. |
ValueError
|
for a pointer that is not one. |
Source code in packages/toolroom-bench/src/livery/toolroom/bench/_index.py
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 | |
materialise ¶
Land record whole into store and return its tree's digest.