Package at.aimon.session.web.internal

Class BindingResolver

java.lang.Object
at.aimon.session.web.internal.BindingResolver
public final class BindingResolver extends Object
Resolves and validates the agentRef bound to a ConversationId.

Implements design §3.6: the binding is a sole-writer field on the conversation; only the manager writes it. Reads use a small in-memory cache backed by the ConversationRepository to avoid hitting persistent storage on every submit. The cache stores positive results only — a missing binding always re-checks the repository.

After successful first-turn binding, callers invoke recordBinding(ConversationId, String) so subsequent submits hit the cache directly.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BindingResolver(at.aimon.core.agent.conversation.ConversationRepository repository)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    invalidate(at.aimon.core.agent.conversation.ConversationId conversationId)
    Drop the cached binding for conversationId.
    void
    recordBinding(at.aimon.core.agent.conversation.ConversationId conversationId, String agentRef)
    Record the binding for conversationId after a successful first-turn lock acquisition.
    Optional<String>
    resolveAndValidate(at.aimon.core.agent.conversation.ConversationId conversationId, String requestedAgentRef)
    Validate that requestedAgentRef is compatible with the conversation's current binding.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • BindingResolver

      public BindingResolver(at.aimon.core.agent.conversation.ConversationRepository repository)

  • Method Details

    • resolveAndValidate

      public Optional<String> resolveAndValidate(at.aimon.core.agent.conversation.ConversationId conversationId, String requestedAgentRef)
      Validate that requestedAgentRef is compatible with the conversation's current binding.

      Three cases:

      • No binding exists yet (first turn) — returns empty Optional.
      • Binding exists and matches — returns Optional.of(existing).
      • Binding exists and differs — throws ConflictingAgentException.
      Parameters:
      conversationId - target conversation (must not be null)
      requestedAgentRef - the agent ref carried by the request (must not be null)
      Returns:
      the existing binding, or empty when this is the first turn

    • recordBinding

      public void recordBinding(at.aimon.core.agent.conversation.ConversationId conversationId, String agentRef)
      Record the binding for conversationId after a successful first-turn lock acquisition. Updates the persistent agentRef field and refreshes the in-memory cache.
      Parameters:
      conversationId - the conversation (must not be null)
      agentRef - the agent ref to bind (must not be null)

    • invalidate

      public void invalidate(at.aimon.core.agent.conversation.ConversationId conversationId)
      Drop the cached binding for conversationId. Called from WebAgentSessionManager.releaseConversation(ConversationId) and when a stale binding is suspected (e.g. after ConflictingAgentException).
      Parameters:
      conversationId - the conversation (must not be null)