barrel_version (barrel_docdb v1.0.0)

View Source

Document versions: an HLC timestamp plus the id of the database that authored the write.

Versions replace rev-tree revisions ("Gen-Hash") as the identity of a document write. The HLC gives causally meaningful last-write-wins ordering; the author id breaks ties deterministically and identifies the writer. Authorship is per-database (each database carries a source id, see barrel_db_server), not per-node: two databases on one node share the HLC clock, so node-level authorship would totally order their writes and hide concurrency. The API _rev token is <hex(hlc)>@<author>: the hex is fixed width, so lexicographic token order equals causal order.

The winner among sibling versions is the maximum under compare/2, a commutative rule: any replica that sees the same version set picks the same winner.

Summary

Types

API form: <<"0000018abc...@f1e061a70714abcd">>

{WriteHlc, AuthorId}

Functions

Total order over versions: HLC first, author id as tie-break.

Decode a storage-encoded version.

Storage encoding: fixed-width HLC first, author id after, so the version parses from the front and sorts by HLC.

Parse an API token back to a version.

The greater of two versions (the deterministic winner rule).

A version at a given HLC authored by an explicit identity (the authoring database's source id).

API token: <hex(hlc)>@<author>. Author ids (lowercase hex) can never contain @.

Types

token/0

-type token() :: binary().

API form: <<"0000018abc...@f1e061a70714abcd">>

version/0

-type version() :: {barrel_hlc:timestamp(), binary()}.

{WriteHlc, AuthorId}

Functions

author(_)

-spec author(version()) -> binary().

compare(_, _)

-spec compare(version(), version()) -> lt | eq | gt.

Total order over versions: HLC first, author id as tie-break.

decode(_)

-spec decode(binary()) -> version().

Decode a storage-encoded version.

encode(_)

-spec encode(version()) -> binary().

Storage encoding: fixed-width HLC first, author id after, so the version parses from the front and sorts by HLC.

from_token(_)

-spec from_token(token()) -> version().

Parse an API token back to a version.

hlc(_)

-spec hlc(version()) -> barrel_hlc:timestamp().

max(A, B)

-spec max(version(), version()) -> version().

The greater of two versions (the deterministic winner rule).

new(Hlc, Author)

-spec new(barrel_hlc:timestamp(), binary()) -> version().

A version at a given HLC authored by an explicit identity (the authoring database's source id).

to_token(_)

-spec to_token(version()) -> token().

API token: <hex(hlc)>@<author>. Author ids (lowercase hex) can never contain @.