Package at.aimon.session.web.internal

Class LeaseRenewer

java.lang.Object

at.aimon.session.web.internal.LeaseRenewer

public final class LeaseRenewer
extends Object

Periodically extends a ConversationLock.LockHandle's lease (design §7.4) on a manager-owned ScheduledExecutorService.

The renewer is intentionally separate from the turn-execution thread: when a turn blocks on an LLM call or a tool, the lease must still be renewed by an unrelated scheduler tick or the lock will silently expire and another node may race ahead. The recommended interval is lease/3.

When ConversationLock.extend(LockHandle, Duration) returns false — the fencing token no longer matches because the lease already expired — the onExtendFailed hook is invoked exactly once. The hook is the manager's signal to interrupt the turn with InterruptReason.LEASE_LOST. Subsequent ticks become no-ops because the lostLease flag latches.

If an idempotency entry is associated with this turn, the optional IdempotencyStore.touch(String, String) call piggybacks the secondary-TTL refresh on each successful extend so the holder-loss sweeper does not pick the entry as stale while the holder is alive (design §9.2 stale cleanup).

Constructor Summary

Constructors

Constructor	Description
LeaseRenewer(ConversationLock lock, ScheduledExecutorService scheduler, Duration interval, Duration lease)
LeaseRenewer(ConversationLock lock, ScheduledExecutorService scheduler, Duration interval, Duration lease, SessionMetrics metrics)

Method Summary

Modifier and Type	Method	Description
ScheduledFuture<?>	start(ConversationLock.LockHandle handle, IdempotencyStore store, String idempotencyKey, Runnable onExtendFailed)	Variant of start(LockHandle, Runnable) that also touches an idempotency entry on each successful extend.
ScheduledFuture<?>	start(ConversationLock.LockHandle handle, Runnable onExtendFailed)	Schedule periodic extend calls for handle.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

LeaseRenewer

public LeaseRenewer(ConversationLock lock,
 ScheduledExecutorService scheduler,
 Duration interval,
 Duration lease)

LeaseRenewer

public LeaseRenewer(ConversationLock lock,
 ScheduledExecutorService scheduler,
 Duration interval,
 Duration lease,
 SessionMetrics metrics)

Method Details

start

public ScheduledFuture<?> start(ConversationLock.LockHandle handle,
 Runnable onExtendFailed)

Schedule periodic extend calls for handle. Cancel the returned future at turn end.

Parameters:

handle - the held lock (must not be null)

onExtendFailed - invoked at most once when extend returns false; typically tells the manager to interrupt the turn (must not be null)

Returns:

the ScheduledFuture the manager cancels at turn end (never null)

start

public ScheduledFuture<?> start(ConversationLock.LockHandle handle,
 IdempotencyStore store,
 String idempotencyKey,
 Runnable onExtendFailed)

Variant of start(LockHandle, Runnable) that also touches an idempotency entry on each successful extend.

Parameters:

handle - the held lock (must not be null)

store - the idempotency store, or null to disable touch

idempotencyKey - the key to touch, or null to disable touch

onExtendFailed - invoked at most once when extend returns false (must not be null)

Returns:

the scheduled task handle (never null)