Skip to content

v0.1.0

Choose a tag to compare

@github-actions github-actions released this 17 Nov 19:02
· 11 commits to main since this release
v0.1.0
728bb6f

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 with T; search_owned and
    get_exact_owned are gone, because a pair of owned methods covered two queries out
    of five and left the rest to the caller's own rkyv call.
  • TreeId with TreeId::from_name("...") (the first 16 bytes of its BLAKE3 hash).
    Journal::open, open_with and repair take impl Into<TreeId>, so a plain
    [u8; 16] still works and no example has to invent sixteen bytes.
  • Journal::to_snapshot(&opts) and Journal::to_bytes(&opts): the object a
    checkpoint would write, opened or as bytes, without touching the disk. This is how
    a journal user reaches children, cover and iter without a second copy of the
    query surface on the journal.
  • Writer::insert_many stops at the first refused prefix. Writer deliberately does
    not implement Extend, which cannot report that.
  • Snapshot::merge_last_wins and merge_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.
  • ipnet is 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 different ipnet
    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" from BadSectionKind, which is about the four-byte kind tag. Error is
    #[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"
    (::/0 covers 2^128 addresses, which does not fit in the count). Count prints
    (all, 0, the number) and Count::exact() gives the number when there is one.
  • #[derive(SnapValue)] from the new bgpkit-snap-derive crate (feature
    derive): #[snap(type_id = "...")] replaces the hand-written impl, and the
    id is checked where it is written rather than when an object is finished.
  • Journal::seq() and Journal::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 no state.json, so a reader of
    another type could open it and decode those bytes as its own.
  • Snapshot::lpm takes a prefix and Snapshot::search takes an address; both are
    documented as the same lookup, one with the host prefix built for you.
  • Journal::open(dir, tree) and open_with_payload(dir, tree, payload) replace the
    positional Option<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. Previously sync() 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.
  • checkpoint carries 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.
  • children returns 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 Deserialize refuses as an error, not as an
    absent prefix (which made len() disagree with iter().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 every io::Error, and rotation and sync keep errno on a failed
    flush.
  • state.json records 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::ConfigMismatch names that case.
  • repair refuses a directory that still has a readable state.json, because
    rewriting next_seq there hides the sequence gap open reports.
  • 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_bytes and Snapshot::from_bytes bounds-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 required flag as well as its id and kind.
  • SnapshotView::sections is &[SectionRef] with named fields instead of a tuple; the
    library returns Error where it used to expect.

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, TreeId stability and tree mismatch,
    to_snapshot/to_bytes without a file, and insert_many stopping.