immutable

func New ¶

func New(dataDir string) (*ImmutableDb, error)

New returns a new ImmutableDb using the specified data directory or an error

func NewFromRoot ¶ added in v0.70.0

func NewFromRoot(root *os.Root) (*ImmutableDb, error)

NewFromRoot returns a new ImmutableDb that reads every file through root rather than by resolving the data directory's pathname again.

Use this when the directory was vetted and the caller needs the reads to be about that directory rather than about whatever its name refers to later. The handle refers to the directory itself, so a tree substituted behind the name afterwards is not what gets read; New cannot offer that, because it only ever holds a name.

The caller keeps ownership of root and must hold it open for as long as the returned ImmutableDb is used. Closing it early makes subsequent reads fail rather than silently fall back to the pathname.

func NewFromRootVerified ¶ added in v0.70.0

func NewFromRootVerified(
	root *os.Root,
	digests map[string]string,
	maxChunk string,
) (*ImmutableDb, error)

NewFromRootVerified is NewFromRoot for a tree whose files are individually certified: every file is read once, checked against digests, and parsed from the bytes that were checked.

NewFromRoot binds the reads to a directory. This binds them to the bytes. The two are not the same guarantee, and the difference is the whole point here: a Mithril bootstrap hashes each downloaded file when it lands, and whatever consumes it opens it again later. Between those, a writer who shares the download directory can rename a file of their own over the verified one without ever leaving the directory the handle refers to, and the second open reads what they wrote.

Holding the descriptor open across both would answer the rename and nothing else. A descriptor names an inode, so writes made through the file it still refers to are visible to a reader that has merely rewound it — the check and the parse would be two readings of one mutable thing, and only the first would be the one that was compared against the digest. So there is only one reading: the entry is read into memory, the digest is computed over that buffer, and the parser walks the same buffer. Nothing that happens to the file afterwards is reachable from it.

This holds one entry in memory at a time, bounded by the certified size of the largest file, which is what the guarantee costs. The file is read twice — once streaming, to learn that size without trusting it, and once into the buffer — so it is the parser's read that is removed, not one of the two.

digests maps a name directly beneath the data directory ("00000.chunk") to its lowercase hex SHA-256. An empty or nil map is refused: it would verify nothing while looking as though it did.

maxChunk, when non-empty, hides every chunk named above it (use ChunkName). The pipelined bootstrap copy reads a tree its download pool is still filling, and chunks arrive out of order — so a chunk above the contiguous prefix may be present and half written. The bound keeps the reader inside the prefix whose archives have been verified rather than failing on one that is merely unfinished. A name rather than a count, because a count would mean the same thing as a position, and a position is not a chunk number.

The caller keeps ownership of root on the same terms as NewFromRoot.