Repository navigation
v0.1.0
The first version under the pre-stable numbering. The crate moved from 1.0.0-rc.4 to
0.1.0 on purpose: no service has leaned on this interface for long enough to freeze
it, and a 1.0 that has to break is worse than a 0.1 that is allowed to. The wire layout
is unchanged (v4) and is documented as the contract; the Rust API is not.
This is also the release that makes the surface small enough to describe without a
table of near-duplicates, and the one that makes the journal's durability claim true.
API
snap.owned()answers every value-returning query withT;search_ownedand
get_exact_ownedare gone, because a pair of owned methods covered two queries out
of five and left the rest to the caller's ownrkyvcall.TreeIdwithTreeId::from_name("...")(the first 16 bytes of its BLAKE3 hash).
Journal::open,open_withandrepairtakeimpl Into<TreeId>, so a plain
[u8; 16]still works and no example has to invent sixteen bytes.Journal::to_snapshot(&opts)andJournal::to_bytes(&opts): the object a
checkpoint would write, opened or as bytes, without touching the disk. This is how
a journal user reacheschildren,coveranditerwithout a second copy of the
query surface on the journal.Writer::insert_manystops at the first refused prefix.Writerdeliberately does
not implementExtend, which cannot report that.Snapshot::merge_last_winsandmerge_with: fold several objects into one, the
daily-merge step. The merge drops stream coordinates because several streams are not
one stream, and takes the union of the input windows when every input declares one.ipnetis re-exported. Unlike the archive re-export this one is complete, because no
macro expands::ipnet::paths, so a caller cannot end up on a differentipnet
version than the signatures use.- five queries removed because they were compositions of the others:
lpm_prefix,
spm_prefix,get_key_value,cover_keys,cover_values. Error::BadArchive(u16)separates "this section's body is not an archive of your
type" fromBadSectionKind, which is about the four-byte kind tag.Erroris
#[non_exhaustive], so a new refusal does not break a caller's match.AddressCounts/Count { NoEntries, All, Exact(u128) }: the old pair of options
could not tell "no entries in this family" from "this family is covered end to end"
(::/0covers 2^128 addresses, which does not fit in the count).Countprints
(all,0, the number) andCount::exact()gives the number when there is one.#[derive(SnapValue)]from the newbgpkit-snap-derivecrate (feature
derive):#[snap(type_id = "...")]replaces the hand-writtenimpl, and the
id is checked where it is written rather than when an object is finished.Journal::seq()andJournal::generation(): the sequence the next record will
carry and the stream incarnation, so a caller shipping records elsewhere can say
how far the journal has got and which stream wrote it.- a journal's value type is now pinned by its first record, not by its first sync: a
directory whose records were never synced had nostate.json, so a reader of
another type could open it and decode those bytes as its own. Snapshot::lpmtakes a prefix andSnapshot::searchtakes an address; both are
documented as the same lookup, one with the host prefix built for you.Journal::open(dir, tree)andopen_with_payload(dir, tree, payload)replace the
positionalOption<PayloadSection>;checkpoint_with(&opts, &validator)runs a
profile's own check before the object is committed;Snapshot::view()is public so
a validator can be run over an object a caller already holds.- every write path takes the value by value (
Journal::insert(prefix, value)), like
Writer::insert, instead of borrowing one the journal copies anyway.
Journal
- rotation flushes and fsyncs the outgoing segment before dropping it, and keeps the
segment if that fails. Previouslysync()returned Ok while the records in a
rotated segment had never reached stable storage. - the torn-tail cut runs before rotation, so a recovery offset recorded against the
old segment is not applied to the new one. checkpointcarries the journal's own sections only, because a checkpoint has to be
an object the journal can reopen; recovery refuses a checkpoint written under a
different payload configuration instead of opening it and losing the arena. Pruning
is best effort and never fails a committed checkpoint.childrenreturns stored keys: a query prefix with host bits answers for its
network address instead of returning a key the object does not contain.- the owned view reports a value whose
Deserializerefuses as an error, not as an
absent prefix (which madelen()disagree withiter().count()). - a zero generation is refused at open; it used to be accepted and then fail every
checkpoint. - a checkpoint that cannot be read reports the file system's error rather than
"missing" for everyio::Error, and rotation andsynckeep errno on a failed
flush. state.jsonrecords the value type and payload configuration, so reopening a
directory with another type or another payload id is refused instead of
reinterpreting the same bytes;Error::ConfigMismatchnames that case.repairrefuses a directory that still has a readablestate.json, because
rewritingnext_seqthere hides the sequence gapopenreports.- every checkpoint writes a new file name (
snapshot-<seq>-<n>.snap), so a checkpoint
with no new records cannot replace an object that is already committed. - the padding walk in
verify_bytesandSnapshot::from_bytesbounds-checks, so a
crafted object is refused instead of panicking. - a checkpoint decodes every value before it commits, because recovery decodes them on
open; an object holding an undecodable value would be unopenable for good. - recovery compares a payload section's
requiredflag as well as its id and kind. SnapshotView::sectionsis&[SectionRef]with named fields instead of a tuple; the
library returnsErrorwhere it used toexpect.
Verification
- tests: reopen after a checkpoint with a sidecar, a required sidecar refused, host
bits refused on the blob and withdraw paths, a journal crossing the 64 MiB segment
boundary reopening with both records,TreeIdstability and tree mismatch,
to_snapshot/to_byteswithout a file, andinsert_manystopping.