mutablesession.go

Overview

This file defines the MutableSession type, a core implementation of the session.Session interface within the system. It acts as a wrapper around an existing immutable session.Session instance, providing the ability to mutate session state when supported. The primary purpose of MutableSession is to allow controlled modifications to the session state while delegating immutable session attributes and event handling to the underlying stored session.

The design facilitates session state management where mutability is conditional on the underlying session's state implementation, enabling safe mutation operations and error handling when unsupported. This is critical for managing user-agent interaction sessions, as described in the broader Session Management topic.

Types and Functions

MutableSession struct

type MutableSession struct {
	service       session.Service
	storedSession session.Session
}

• Fields:

  • service: The session.Service managing this session. This field links the mutable session to its service backend, responsible for session lifecycle and persistence.

  • storedSession: The underlying session.Session instance that this mutable session wraps. This stored session provides the immutable session properties and the actual state storage.

NewMutableSession

func NewMutableSession(service session.Service, storedSession session.Session) *MutableSession

• Purpose: Constructor function to create a new MutableSession instance.

• Parameters:

  • service: The session service managing this session.

  • storedSession: The immutable or underlying session instance to wrap.

• Returns: Pointer to a new MutableSession.

• Usage:

  mutableSess := NewMutableSession(myService, existingSession)
  

• Details: This function initializes a MutableSession by associating it with a service and an existing session, enabling state mutation operations through the wrapper.

Methods on MutableSession

State

func (s *MutableSession) State() session.State

• Returns the current state interface of the mutable session.

• Delegates directly to the MutableSession itself, which implements session.State.

• Facilitates access to state methods like Get, Set, and All.

AppName

func (s *MutableSession) AppName() string

• Returns the application name associated with the stored session.

• Delegates to the underlying storedSession.AppName() method.

UserID

func (s *MutableSession) UserID() string

• Returns the user ID linked to the stored session.

• Delegates to storedSession.UserID().

ID

func (s *MutableSession) ID() string

• Returns the unique session ID.

• Delegates to storedSession.ID().

Events

func (s *MutableSession) Events() session.Events

• Returns the event history associated with the session.

• Delegates to storedSession.Events().

LastUpdateTime

func (s *MutableSession) LastUpdateTime() time.Time

• Returns the timestamp of the last update to the session.

• Delegates to storedSession.LastUpdateTime().

Session State Operations

Get

func (s *MutableSession) Get(key string) (any, error)

• Retrieves a value from the session state by key.

• Internally calls Get on the current state of storedSession.

• Parameters:

  • key: The string identifier for the state value.

• Returns:

  • The value associated with key if present.

  • An error if retrieval fails.

• Error Handling:

  • If the underlying state returns an error, it is wrapped with contextual information for easier debugging.

• Example:

  val, err := mutableSess.Get("last_query")
  if err != nil {
      // handle error
  }
  

All

func (s *MutableSession) All() iter.Seq2[string, any]

• Returns a sequence (iter.Seq2[string, any]) of all key-value pairs in the session state.

• Delegates to the underlying stored session's state.

• Useful for iterating over the entire session state.

Set

func (s *MutableSession) Set(key string, value any) error

• Sets or updates a value in the mutable session state.

• Parameters:

  • key: The string key for the state entry.

  • value: The value to associate with the key.

• Returns: An error if the state is not mutable or the set operation fails.

• Behavior:

  • Asserts that the underlying session state implements the MutableState interface.

  • If not mutable, returns an error indicating immutability.

  • Otherwise, calls the Set method on the underlying mutable state.

  • Wraps any error returned from Set with context.

• Example:

  err := mutableSess.Set("user_preference", "dark_mode")
  if err != nil {
      // handle error
  }
  

Important Implementation Details

• Delegation Pattern: The MutableSession relies heavily on delegation to the underlying storedSession for most immutable session properties and event access. This ensures consistency and reuse of existing session implementations.

• Conditional Mutability: The mutability depends entirely on whether the underlying session state's type implements MutableState. This type assertion enforces safety and explicit error reporting if the session state cannot be mutated.

• Error Wrapping: All errors from underlying calls are wrapped with detailed context messages, aiding debugging and tracing of session state operations.

• Integration with session.Service: The reference to the session.Service hints at possible session lifecycle management or persistence operations handled elsewhere. While this file doesn't mutate the service, it establishes a link for potential future interactions.

Interactions with Other Components

• session.Session Interface: MutableSession implements this interface, providing mutable capabilities on top of an existing session.

• session.Service: Used during construction, likely representing the session management backend defined in Session Management.

• MutableState Interface: Represents the mutable state contract that underlying session states must implement to support state setting. The interface is crucial for differentiating mutable and immutable states.

• iter.Seq2: Used as the return type for the All method, it provides a generic sequence interface for iterating key-value pairs in session state.

• time.Time: Used for tracking session update timestamps.

• session.Events: Provides access to session event history, enabling audit trail or event-driven logic.

This file serves as a bridge to enable mutable session manipulations while preserving the original session interface and state management contracts, facilitating flexible session handling workflows, as elaborated in the broader Session Management topic.

Diagram: MutableSession Structure and Method Delegation

classDiagram
class MutableSession {
- service: session.Service
- storedSession: session.Session
+ State()
+ AppName()
+ UserID()
+ ID()
+ Events()
+ LastUpdateTime()
+ Get()
+ All()
+ Set()
}
MutableSession --> session.Session : storedSession
MutableSession --> session.Service : service
MutableSession ..> MutableState : type assertion in Set()

• The diagram highlights the MutableSession struct's key fields and public methods.

• Arrows indicate delegation to storedSession and association with the service.

• The dotted arrow represents the runtime type assertion to MutableState for mutability checks.

This documentation focuses on the detailed functionality and design of the MutableSession implementation, which is a vital part of session state management in the system. For further details on session lifecycle, state interfaces, and event processing, refer to the Session Management topic.