pub struct RecordingState { /* private fields */ }Expand description
Manages recording lifecycle with file-based locking.
Uses fd-lock to ensure only one recording can be active at a time.
State is persisted to disk so it survives process restarts and can
detect stale locks from crashed processes.
§File Layout
{state_dir}/recording.lock- Lock file for mutual exclusion{state_dir}/recording.json- Active session metadata
Implementations§
Source§impl RecordingState
impl RecordingState
Sourcepub fn new(state_dir: &Path) -> Self
pub fn new(state_dir: &Path) -> Self
Create a new RecordingState using the given state directory.
Does not create the directory; caller should ensure it exists
(e.g., via Paths::ensure_dirs()).
Sourcepub fn start(&self, name: &str, session_path: PathBuf) -> Result<ActiveSession>
pub fn start(&self, name: &str, session_path: PathBuf) -> Result<ActiveSession>
Start a new recording session.
Acquires an exclusive file lock, writes session metadata, and
returns the ActiveSession. If another recording is in progress
(lock held by live process), returns RecError::RecordingInProgress.
If a stale lock is detected (process no longer alive), cleans it up
first and then starts.
§Arguments
name- Human-readable session namesession_path- Path where the session NDJSON file will be written
§Errors
Returns an error if the lock cannot be acquired or file I/O fails.
§Panics
Panics if the system clock is before the Unix epoch.
Sourcepub fn stop(&self) -> Result<ActiveSession>
pub fn stop(&self) -> Result<ActiveSession>
Stop the current recording session.
Reads the active session metadata, removes the state and lock files,
and returns the session info. Returns RecError::NoActiveRecording
if no recording is in progress.
§Errors
Returns an error if no recording is active or file removal fails.
Sourcepub fn is_recording(&self) -> bool
pub fn is_recording(&self) -> bool
Check if a recording is currently in progress.
Returns true if the state file exists and contains valid session data.
Sourcepub fn current(&self) -> Result<ActiveSession>
pub fn current(&self) -> Result<ActiveSession>
Get the current active session metadata.
Returns RecError::NoActiveRecording if no recording is active.
§Errors
Returns an error if no recording is active or the state file is corrupted.
Sourcepub fn cleanup_stale_lock(
&self,
store: Option<&SessionStore>,
) -> Result<Option<RecoveryInfo>>
pub fn cleanup_stale_lock( &self, store: Option<&SessionStore>, ) -> Result<Option<RecoveryInfo>>
Clean up stale lock from a crashed process, optionally recovering the session.
Reads the PID from the lock file and checks if that process is still
alive using libc::kill(pid, 0) on Unix. If the process is dead,
attempts recovery (if store is provided) and then removes lock/state files.
§Recovery behavior
When store is Some:
- Sessions with ≥1 command are renamed to
recovered-YYYY-MM-DD-HHMMSSand flagged withrecovered: Some(true). - Sessions with 0 commands are silently deleted.
- Recovery is best-effort: errors loading/saving are logged and cleanup proceeds.
When store is None:
- Existing behavior: just remove lock and state files.
§Safety
- We only clean up if the process is definitively dead
- PIDs can be reused, but the window is very small for a recording tool
- The lock file contains only a PID, so worst case we clean up an unrelated process’s “lock” (but they wouldn’t be using our lock file)
§Errors
Returns an error if file I/O operations fail unexpectedly.