orionis.session.stores.file.FileSessionStore

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class FileSessionStore(ISessionStore): (source)

Constructor: FileSessionStore(directory)

View In Hierarchy

Session store that persists each session as a JSON file on disk.

One JSON file per session, named {session_id}.json, stored inside directory. The directory is created on instantiation when it does not already exist.

Expired sessions are evicted lazily during read, keeping hot-path operations at O(1) complexity. Bulk removal of stale files can be triggered explicitly via gc.

File layout

{
    "id": "...",
    "expires_at": "2026-07-10T12:00:00+00:00",
    "data": { ... }
}

Parameters
directory	Path to the directory where session files are stored.

Static Method	`_tempPath`	Build a unique staging path for an atomic write.
Method	`__init__`	Initialise the store and ensure the storage directory exists.
Method	`_deleteFile`	Unlink path, silently ignoring a missing-file error.
Method	`_deserialize`	Decode raw JSON bytes into a `SessionRecord`.
Method	`_gcSweep`	Scan the store directory and remove stale or corrupt files.
Method	`_lock`	Select a bounded, stable cross-process lock for a session file.
Method	`_path`	Return the absolute path to the JSON file for session_id.
Method	`_readFile`	Read path as raw bytes, returning `None` if absent.
Method	`_readRecord`	Load, decode and validate the record stored at path.
Method	`_replace`	Publish tmp as path, retrying a transient sharing violation.
Method	`_serialize`	Encode record to compact JSON bytes via `msgspec`.
Method	`_updateRecord`	Replace an existing live session under its cross-process lock.
Method	`_writeFile`	Atomically write content to path.
Method	`_writeRecord`	Serialise record and store it atomically at path.
Async Method	`delete`	Remove the session file for session_id (no-op when absent).
Async Method	`gc`	Remove all expired, corrupt, or incomplete session files.
Async Method	`read`	Load and return the live record for session_id, or `None`.
Async Method	`update`	Update only a live session without recreating a deleted file.
Async Method	`write`	Serialise and persist record to disk atomically.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_directory`	Undocumented
Instance Variable	`_locks`	Undocumented
Instance Variable	`_rename_lock`	Undocumented

@staticmethod

def _tempPath(path: Path) -> Path: (source) ¶

Build a unique staging path for an atomic write.

Parameters
path:`Path`	Final destination file.

Returns
`Path`	Sibling path carrying a random infix, so concurrent writers of the same session never share a staging file, and still ending in `.tmp` so the sweep keeps telling both apart.

def __init__(self, directory: Path): (source) ¶

Initialise the store and ensure the storage directory exists.

Parameters
directory:`Path`	Filesystem path to the session storage directory.

Returns
`None`	Undocumented

def _deleteFile(self, path: Path) -> bool: (source) ¶

Unlink path, silently ignoring a missing-file error.

Parameters
path:`Path`	Session file to remove.

Returns
`bool`	True when this call removed the session file.

def _deserialize(self, raw: bytes) -> SessionRecord | None: (source) ¶

Decode raw JSON bytes into a SessionRecord.

Type validation is delegated entirely to msgspec; any structural mismatch or missing field is treated as corruption.

Parameters
raw:`bytes`	Raw JSON bytes previously written by `_serialize`.

Returns
`SessionRecord \| None`	Deserialised record, or `None` on any decode error.

def _gcSweep(self): (source) ¶

Scan the store directory and remove stale or corrupt files.

Uses os.scandir for reduced object allocation and filesystem cache reuse. A session file is removed when it is expired, contains invalid JSON, is structurally incomplete, or cannot be read due to an I/O error. Staging files left behind by an interrupted write are reclaimed once they are old enough that no writer can still be filling them.

Returns
`None`	Undocumented

def _lock(self, path: Path) -> BaseFileLock: (source) ¶

Select a bounded, stable cross-process lock for a session file.

Parameters
path:`Path`	Session file protected by the lock.

Returns
`BaseFileLock`	Platform lock serializing validation, replacement and deletion.

def _path(self, session_id: str) -> Path: (source) ¶

Return the absolute path to the JSON file for session_id.

Parameters
session_id:`str`	Unique session identifier.

Returns
`Path`	Full path to `{session_id}.json` inside the store directory.

Raises
`SessionStorageException`	If an identifier contains path syntax or exceeds its limit.

def _readFile(self, path: Path) -> bytes | None: (source) ¶

Read path as raw bytes, returning None if absent.

Parameters
path:`Path`	File to read.

Returns
`bytes \| None`	File contents, or `None` when the file does not exist.

def _readRecord(self, path: Path) -> SessionRecord | None: (source) ¶

Load, decode and validate the record stored at path.

Runs entirely on a worker thread: file I/O, JSON decoding and the eviction of an expired or corrupt file happen in a single hop.

Parameters
path:`Path`	Session file to load.

Returns
`SessionRecord \| None`	The live record, or `None` when absent, expired or corrupt.

def _replace(self, tmp: Path, path: Path): (source) ¶

Publish tmp as path, retrying a transient sharing violation.

The rename is serialised per store instance, and retried when the operating system refuses it because another process is swapping the same destination. POSIX never reaches the retry branch.

Parameters
tmp:`Path`	Staging file holding the serialised payload.
path:`Path`	Destination session file.

Returns
`None`	Undocumented

Raises
`OSError`	If the rename keeps failing after the last attempt.

def _serialize(self, record: SessionRecord) -> bytes: (source) ¶

Encode record to compact JSON bytes via msgspec.

Parameters
record:`SessionRecord`	Record to serialise.

Returns
`bytes`	UTF-8 encoded JSON payload.

def _updateRecord(self, path: Path, record: SessionRecord) -> bool: (source) ¶

Replace an existing live session under its cross-process lock.

Parameters
path:`Path`	Existing session file.
record:`SessionRecord`	Replacement record.

Returns
`bool`	False when another worker deleted or expired the record.

def _writeFile(self, path: Path, content: bytes): (source) ¶

Atomically write content to path.

Writes to a unique .tmp sibling first, then renames over the destination to prevent partial reads from concurrent processes. A failed write removes its own staging file before propagating.

Parameters
path:`Path`	Destination file path.
content:`bytes`	Serialised session payload.

Returns
`None`	Undocumented

Raises
`OSError`	If the payload cannot be staged or renamed into place.

def _writeRecord(self, path: Path, record: SessionRecord): (source) ¶

Serialise record and store it atomically at path.

Parameters
path:`Path`	Destination session file.
record:`SessionRecord`	The record to persist.

Returns
`None`	Undocumented

async def delete(self, session_id: str) -> bool: (source) ¶

overrides orionis.session.contracts.ISessionStore.delete

Remove the session file for session_id (no-op when absent).

Parameters
session_id:`str`	Unique session identifier to remove.

Returns
`bool`	True only when a session file was deleted.

async def gc(self): (source) ¶

overrides orionis.session.contracts.ISessionStore.gc

Remove all expired, corrupt, or incomplete session files.

The directory scan runs on a thread-pool worker so it never blocks the event loop. This method must be called explicitly; it is never triggered automatically by read, write, or delete.

Returns
`None`	Undocumented

async def read(self, session_id: str) -> SessionRecord | None: (source) ¶

overrides orionis.session.contracts.ISessionStore.read

Load and return the live record for session_id, or None.

Expired or corrupt records are evicted lazily: the file is deleted and None is returned without triggering a GC cycle.

Parameters
session_id:`str`	Unique session identifier to look up.

Returns
`SessionRecord \| None`	The live record, or `None` when absent, expired, or corrupt.

async def update(self, record: SessionRecord) -> bool: (source) ¶

overrides orionis.session.contracts.ISessionStore.update

Update only a live session without recreating a deleted file.

Parameters
record:`SessionRecord`	Replacement record.

Returns
`bool`	Whether the session still existed and was updated.

async def write(self, record: SessionRecord): (source) ¶

overrides orionis.session.contracts.ISessionStore.write

Serialise and persist record to disk atomically.

Parameters
record:`SessionRecord`	The record to store.

Returns
`None`	Undocumented

__slots__: tuple[str, ...] = (source) ¶

overrides orionis.session.contracts.ISessionStore.__slots__

Undocumented

_directory = (source) ¶

Undocumented

_locks = (source) ¶

Undocumented

_rename_lock = (source) ¶

Undocumented