barrel_session (barrel_spaces v1.0.0)
View SourceSessions: an agent's working context inside a space, folded down from barrel_memory's mechanisms. A session is a regular document (session:Sid) in the space database carrying data, summary, and pinned context; its messages are separate documents (session:Sid:msg:PaddedTs-Rand) whose ids sort chronologically, so history reads are ordered prefix folds.
TTL is sliding: every mutation rewrites the session doc with expires_at = now + ttl. Expiry is the space database's doc-TTL machinery: reads go blind to an idle session immediately (lazy expiry) and the space's TTL sweeper tombstones it; the janitor (barrel_spaces_janitor) then collects the orphaned message docs. add_message writes the message and slides the session in two writes (not atomic; a crash between them loses only the slide).
Summary
Functions
Append a message: #{role := binary(), content := term(), metadata => map()}. Slides the session's TTL.
Create a session with default options.
Create a session. Opts: agent (binary), ttl (seconds, default the space's session_ttl or 3600), data, metadata.
Delete a session and all of its messages.
The session document (expired sessions read as not found).
One key from the session's data map.
The session's messages in chronological order.
Messages with options: limit (from the chosen end), order (asc | desc, default asc), since/before (unix ms bounds on the message timestamp).
Live sessions of a space.
Live sessions, optionally filtered by agent.
The pinned items, highest priority first.
Pin context that must survive truncation: #{content := term(), priority => 0..10 (0 highest, default 5)}. Returns the pin's id.
Set one key in the session's data map.
Set the session's summary checkpoint.
Slide the session's TTL without changing it.
Remove a pinned item by id.
Functions
-spec add_message(barrel_spaces:space(), binary(), map()) -> {ok, binary()} | {error, term()}.
Append a message: #{role := binary(), content := term(), metadata => map()}. Slides the session's TTL.
-spec create(barrel_spaces:space()) -> {ok, binary()} | {error, term()}.
Create a session with default options.
-spec create(barrel_spaces:space(), map()) -> {ok, binary()} | {error, term()}.
Create a session. Opts: agent (binary), ttl (seconds, default the space's session_ttl or 3600), data, metadata.
-spec delete(barrel_spaces:space(), binary()) -> ok.
Delete a session and all of its messages.
-spec get(barrel_spaces:space(), binary()) -> {ok, map()} | {error, not_found}.
The session document (expired sessions read as not found).
-spec get_data(barrel_spaces:space(), binary(), binary()) -> {ok, term()} | {error, not_found}.
One key from the session's data map.
-spec get_messages(barrel_spaces:space(), binary()) -> {ok, [map()]}.
The session's messages in chronological order.
-spec get_messages(barrel_spaces:space(), binary(), map()) -> {ok, [map()]}.
Messages with options: limit (from the chosen end), order (asc | desc, default asc), since/before (unix ms bounds on the message timestamp).
-spec list(barrel_spaces:space()) -> {ok, [map()]}.
Live sessions of a space.
-spec list(barrel_spaces:space(), map()) -> {ok, [map()]}.
Live sessions, optionally filtered by agent.
-spec list_pinned(barrel_spaces:space(), binary()) -> {ok, [map()]} | {error, not_found}.
The pinned items, highest priority first.
-spec pin_context(barrel_spaces:space(), binary(), map()) -> {ok, binary()} | {error, term()}.
Pin context that must survive truncation: #{content := term(), priority => 0..10 (0 highest, default 5)}. Returns the pin's id.
-spec set_data(barrel_spaces:space(), binary(), binary(), term()) -> {ok, non_neg_integer()} | {error, term()}.
Set one key in the session's data map.
-spec set_summary(barrel_spaces:space(), binary(), binary()) -> {ok, non_neg_integer()} | {error, term()}.
Set the session's summary checkpoint.
-spec touch(barrel_spaces:space(), binary()) -> {ok, non_neg_integer()} | {error, term()}.
Slide the session's TTL without changing it.
-spec unpin_context(barrel_spaces:space(), binary(), binary()) -> {ok, non_neg_integer()} | {error, term()}.
Remove a pinned item by id.