nodestep.state.integrations.filesystem¶

FilesystemStateStore, which keeps each thread's history in a JSON Lines file.

FilesystemStateStore¶

FilesystemStateStore(path)

State store that appends history to a JSON Lines file.

Subclass of InMemoryStateStore.

Processes can share the file. See State stores for its header record, its lock and the repair of an interrupted write.

Parameters
`path`	`str \| Path`	Store file; missing parent directories are created.

Raises
`StateStoreError`	If the runtime has no file lock, `path` is a directory, the file is not a state store of this version, or a complete record is corrupt.

Attributes
`repaired_bytes`	`int`	Bytes truncated by the last repair, or `0` if nothing was repaired.

Methods

`async append_event(event)`¶

Store an event as given.

async append_event(event) -> HistoryEvent

Parameters
`event`	`HistoryEvent`

Returns
`HistoryEvent`	The same event.

Raises
`StateStoreError`	If a record another writer appended to the file is corrupt.

`async append_next_event(event)`¶

Store an event with the next sequence number of its thread.

async append_next_event(event) -> HistoryEvent

Parameters
`event`	`HistoryEvent`	Event whose `sequence` is replaced.

Returns
`HistoryEvent`	The stored event with its sequence number.

Raises
`StateStoreError`	If a record another writer appended to the file is corrupt.

`async save_checkpoint(checkpoint)`¶

Store a state snapshot.

async save_checkpoint(checkpoint) -> CheckpointRecord

Parameters
`checkpoint`	`CheckpointRecord`

Returns
`CheckpointRecord`	The same checkpoint.

Raises
`StateStoreError`	If a record another writer appended to the file is corrupt.

`async fork(thread_id, ...)`¶

Record a new branch starting at an event.

async fork(thread_id, *, from_, branch_id='main', name=None) -> BranchRecord

Parameters
`thread_id`	`str`
`from_`	`str`	Event id to branch from.
`branch_id`	`str`	Branch to fork; `"main"` by default.
`name`	`str \| None`	Id of the new branch; a random id when omitted.

Raises
`StateStoreError`	If the thread already has a branch with that id, including `"main"`, or a record another writer appended is corrupt.

`async list_branches(thread_id)`¶

Return the branches forked from a thread, oldest first.

async list_branches(thread_id) -> list[BranchRecord]

Parameters
`thread_id`	`str`

Returns
`list[BranchRecord]`	Every recorded fork of the thread; `"main"` is not listed.

Raises
`StateStoreError`	If a record another writer appended to the file is corrupt.

`async get_history(thread_id, branch_id)`¶

Return the events and checkpoints of a thread branch.

async get_history(thread_id, branch_id='main') -> History

Parameters
`thread_id`	`str`
`branch_id`	`str`	Branch to read; `"main"` by default.

Returns
`History`	Empty lists for a thread or branch the store does not know.

Raises
`StateStoreError`	If a record another writer appended to the file is corrupt.

`async latest_checkpoint(thread_id, branch_id, at)`¶

Return the latest checkpoint, optionally at or before an event.

async latest_checkpoint(thread_id, branch_id='main', at=None) -> CheckpointRecord | None

Parameters
`thread_id`	`str`
`branch_id`	`str`	Branch to read; `"main"` by default.
`at`	`str \| None`	Event id; only checkpoints up to that event count.

Returns
`CheckpointRecord or None`	`None` when the branch has no such checkpoint.

Raises
`StateUpdateError`	If `at` is not an event of the branch.
`StateStoreError`	If a record another writer appended to the file is corrupt.

nodestep.state.integrations.filesystem¶

FilesystemStateStore¶

async append_event(event)¶

async append_next_event(event)¶

async save_checkpoint(checkpoint)¶

async fork(thread_id, ...)¶

async list_branches(thread_id)¶

async get_history(thread_id, branch_id)¶

async latest_checkpoint(thread_id, branch_id, at)¶