cadrumo.adapters.persistence.storage.master_key.idle_timeout module

Idle-timeout evaluation for BucketSession.

Every CLI invocation runs evaluate_idle(session, now) before granting access to the session. The window it evaluates was fixed when the session was opened, from cadrumo_bucket_default_idle_lock_minutes; the default is 15 minutes. There is no per-bucket override to read: the plaintext bucket manifest that once declared one is retired, and nothing replaced it.

The evaluator is a pure function over the session’s idle deadline and the supplied now; it never mutates the session. Mutation happens through session.touch(now) which the caller invokes on a successful authentication so the deadline rolls forward by the configured window.

Returning a typed IdleEvaluation record (rather than a bare boolean) lets the CLI render an actionable “remaining N seconds” hint without re-deriving the math at the verb layer.

class IdleEvaluation(**data)[source]

Bases: BaseModel

Typed outcome of an idle-window evaluation.

Parameters:

data (Any)

expired: bool
remaining_seconds: NonNegativeInt
evaluate_idle(*, session, now, configured_minutes=15)[source]

Evaluate the session’s idle window without mutating it.

Parameters:

  • session (BucketSession) – The session whose idle deadline to evaluate.

  • now (datetime) – UTC timestamp at which the evaluation runs.

  • configured_minutes (int) – Idle-lock window in minutes, defaulting to DEFAULT_IDLE_LOCK_MINUTES (15). Validated as a strict positive integer and otherwise unused: the deadlines this function compares were computed when the session opened, so the value bounds nothing here. The live caller passes none.

Return type:

IdleEvaluation

Returns:

An IdleEvaluation record carrying expired and the floor-truncated remaining_seconds until the earlier of the idle deadline and the absolute session cap (zero when either has elapsed).

Raises:

StorageValidationError – When configured_minutes is not a strict positive integer.