/ 
Langertha-Raider-0.504
/ Langertha::Raider::Session

NAME

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

VERSION

version 0.504

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 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.

https://raudssus.de/