reckon_db_stream_path (reckon_db v5.0.0)

View Source

The single source of truth for the Khepri stream layout.

reckon-db stores events under a **structural aggregate-type subtree** (DESIGN_STREAM_NAMESPACE.md, Model C):

  USER:    [streams, <<"ride">>, <<"abc…hex">>, PaddedVersion] -> #event{}
  SYSTEM:  [streams, <<"$link">>, <<"name">>,    PaddedVersion] -> #event{}
  DCB:     [streams, <<"_dcb">>,  SeqKey]                        -> #event{}

The aggregate **type** (the user-id prefix, or the $-namespace for system streams) is a real Khepri path level rather than a leading substring of an opaque id. This makes type-scoped operations (list_streams, replay, links) navigate a subtree instead of scanning the whole store.

This module is the ONLY place that knows the 4-level shape. Every other module builds stream paths through these functions, so the layout lives in exactly one file. The opaque round-trip — a stream id written under event_path/2 must reconstruct byte-identical via stream_id_from_path/1 — is the load-bearing correctness property and is exercised directly by reckon_db_stream_path_tests.

The DCB pseudo-stream (_dcb) keeps its existing 2-level [streams, _dcb, SeqKey] shape (a flat seq-keyed log, not an aggregate); its paths are built by reckon_db_dcb_paths, but the readers here (stream_id_from_path/1) tolerate it because global reads span both depths.

Summary

Functions

Pattern matching every regular (user/system) event leaf across the store: [streams, *, *, leaf-with-data]. This is the 4-level regular shape ONLY — the 2-level DCB log is at a different depth and must be queried separately (see reckon_db_streams global readers).

Khepri path of a single event: [streams, Type, Id, PaddedVersion].

Reconstruct the opaque stream id from a Khepri path. The inverse of event_path/2 / stream_path/1. Tolerates the 2-level DCB node (returns the reserved _dcb id) so global readers spanning both depths can label every result.

Khepri path of the aggregate node (all versions live beneath it): [streams, Type, Id]. Used by exists/delete and version counting.

The aggregate-type node for a stream id (<<"ride">>, <<"$link">>). Raises for ids that don't decompose.

Pattern matching every aggregate-id node of one type: [streams, Type, *]. Used by links to navigate a type subtree (order-*) instead of scanning the whole store.

Pattern matching every version node of one stream: [streams, Type, Id, *]. Used by get_version (count).

Functions

all_events_pattern()

-spec all_events_pattern() -> khepri_path:native_pattern().

Pattern matching every regular (user/system) event leaf across the store: [streams, *, *, leaf-with-data]. This is the 4-level regular shape ONLY — the 2-level DCB log is at a different depth and must be queried separately (see reckon_db_streams global readers).

event_path(StreamId, PaddedVersion)

-spec event_path(binary(), binary()) -> khepri_path:native_path().

Khepri path of a single event: [streams, Type, Id, PaddedVersion].

Raises {invalid_stream_id, StreamId} for ids that don't decompose (including the DCB pseudo-stream, whose paths are built elsewhere).

stream_id_from_path(_)

-spec stream_id_from_path(khepri_path:native_path()) -> binary().

Reconstruct the opaque stream id from a Khepri path. The inverse of event_path/2 / stream_path/1. Tolerates the 2-level DCB node (returns the reserved _dcb id) so global readers spanning both depths can label every result.

stream_path(StreamId)

-spec stream_path(binary()) -> khepri_path:native_path().

Khepri path of the aggregate node (all versions live beneath it): [streams, Type, Id]. Used by exists/delete and version counting.

type_of(StreamId)

-spec type_of(binary()) -> binary().

The aggregate-type node for a stream id (<<"ride">>, <<"$link">>). Raises for ids that don't decompose.

type_streams_pattern(Type)

-spec type_streams_pattern(binary()) -> khepri_path:native_pattern().

Pattern matching every aggregate-id node of one type: [streams, Type, *]. Used by links to navigate a type subtree (order-*) instead of scanning the whole store.

versions_pattern(StreamId)

-spec versions_pattern(binary()) -> khepri_path:native_pattern().

Pattern matching every version node of one stream: [streams, Type, Id, *]. Used by get_version (count).