Skip to content

session_cache

session_cache

The volatile unlock cache — one tier, two backings.

The cache tier of the passphrase chain holds the vault passphrase for the login session. The cache has no timeout; vault lock clears it; a reboot removes it. Which backing holds it follows where this host runs the supervisor, the reader that has to find it (supervisor_placement): a user-unit supervisor reads the operator's kernel keyring (kernel_keyring), so that is the backing; a supervisor inside the container runtime's namespace sees an empty keyring there, so the tier is a tmpfs session file (session_file), a path being a path in any namespace. The file also stands in where the kernel facility itself is unusable. The status surfaces name the backing and the reason, so a degradation is never silent.

Callers use this module, not a backing, for every cache operation. forget clears both backings: facility availability can change between boots, and vault lock must not leave a live cache in the backing this boot does not prefer.

__all__ = ['backing_detail', 'forget', 'is_cached', 'load', 'store', 'unavailable_reason'] module-attribute

store(passphrase, db_path)

Cache passphrase for db_path in the session's preferred backing.

Source code in src/terok_sandbox/vault/store/session_cache.py 
38
39
40
def store(passphrase: str, db_path: str | os.PathLike[str]) -> bool:
    """Cache *passphrase* for *db_path* in the session's preferred backing."""
    return _backend().store(passphrase, db_path)

load(db_path)

Return the cached passphrase for db_path, or None on any miss.

Source code in src/terok_sandbox/vault/store/session_cache.py 
43
44
45
def load(db_path: str | os.PathLike[str]) -> str | None:
    """Return the cached passphrase for *db_path*, or ``None`` on any miss."""
    return _backend().load(db_path)

forget(db_path)

Clear the cache for db_path from both backings.

Returns:

Type Description
bool

True when no backing can still hold the cache, False when either
bool

removal failed and a live cache may remain.
Source code in src/terok_sandbox/vault/store/session_cache.py 
48
49
50
51
52
53
54
55
56
57
def forget(db_path: str | os.PathLike[str]) -> bool:
    """Clear the cache for *db_path* from both backings.

    Returns:
        True when no backing can still hold the cache, False when either
        removal failed and a live cache may remain.
    """
    kernel_cleared = _kernel_keyring.forget(db_path)
    file_cleared = _session_file.forget(db_path)
    return kernel_cleared and file_cleared

is_cached(db_path)

Return True when the preferred backing holds a cache for db_path.

Source code in src/terok_sandbox/vault/store/session_cache.py 
60
61
62
def is_cached(db_path: str | os.PathLike[str]) -> bool:
    """Return ``True`` when the preferred backing holds a cache for *db_path*."""
    return _backend().is_cached(db_path)

unavailable_reason()

Explain why no backing can hold the cache here, or None when one can.

A file backing that fails names why the keyring was not the choice first, so the operator reads both facts in one line.

Source code in src/terok_sandbox/vault/store/session_cache.py 
65
66
67
68
69
70
71
72
73
74
75
def unavailable_reason() -> str | None:
    """Explain why no backing can hold the cache here, or ``None`` when one can.

    A file backing that fails names why the keyring was not the choice
    first, so the operator reads both facts in one line.
    """
    backend = _backend()
    reason = backend.unavailable_reason()
    if reason is None or backend is _kernel_keyring:
        return reason
    return f"{_file_reason()}; {reason}"

backing_detail(*, cached)

Human detail for the cache tier in the vault status chain.

Separates the states an operator acts on differently: which backing serves this session and why, whether it holds a passphrase, and why the tier cannot run at all.

Source code in src/terok_sandbox/vault/store/session_cache.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
def backing_detail(*, cached: bool) -> str:
    """Human detail for the cache tier in the ``vault status`` chain.

    Separates the states an operator acts on differently: which backing
    serves this session and why, whether it holds a passphrase, and why
    the tier cannot run at all.
    """
    if (reason := unavailable_reason()) is not None:
        return f"unusable here: {reason}"
    if _backend() is _kernel_keyring:
        return "cached in the user keyring" if cached else "no passphrase cached"
    where = f"session file ({_file_reason()})"
    return f"cached in a {where}" if cached else f"no passphrase cached — {where}"