/ 
Langertha-Raider-0.503
/ Langertha::Raider::Session

NAME

Langertha::Raider::Session - Internal writer of one session journal, holding its lock

VERSION

version 0.503

SYNOPSIS

# Internal to Langertha-Raider -- no API promise.
# Made by Langertha::Raider::SessionStore->create / ->open.
my $run = $session->next_run;                       # 'r3' after two runs
$session->append('message', run => $run, role => 'user', content => 'hi');
say $session->id, ' ', $session->path;
$session->release;                                  # or let it go out of scope

DESCRIPTION

Internal module. Its interface may change without notice.

The one writer of a session journal (ADR 0015). Constructing it takes an exclusive, non-blocking flock on <id>.lock next to the journal and fails at once with session ID is in use when another writer -- in this process or another -- holds it. The lock is held until "release" or until the object is destroyed.

On opening, the journal is read once ("journal"): numbering continues after its last seq and its last run, and when the last line was cut off (a crash mid-write) the next append starts on a fresh line.

id

The session id. Required.

path

The journal file, a Path::Tiny. Required; it must exist.

clock

Code reference returning epoch seconds for the time of an event. Defaults to "time" in Time::HiRes.

journal

The Langertha::Raider::Session::Journal as it was when the session was opened (read under the lock) -- what a resume replays.

lock_path

<id>.lock next to the journal.

is_open

True until "release".

next_run

my $run = $session->next_run;   # 'r1', 'r2', ...

The id of the next run of this session, counting on from the runs already in the journal.

append

my $event = $session->append('tool.call', run => 'r1', call => 'c1', name => 'bash', ...);

Writes one event as one line and flushes it: the fields plus v (1), seq, time and type. Returns the event. Croaks cannot write FILE: ... when the line cannot be written; the next event then starts on a fresh line, so a partly written one damages only itself.

release

Closes the journal and gives up the lock. Appending afterwards croaks.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-raider/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.