service.go

Overview

The service.go file in the session package defines the primary interface and data structures for managing user interaction sessions within the system. It establishes the contract for session storage services, including creation, retrieval, listing, deletion, and event appending functionality. The file also provides a factory method for an in-memory implementation of the session service, and defines request and response types used in the service API.

This file is foundational within the Session Management topic, as it specifies the core abstractions and communication patterns for working with sessions and events, enabling pluggable backend implementations and consistent session lifecycle management.

Key Elements

Service Interface

type Service interface {
	Create(context.Context, *CreateRequest) (*CreateResponse, error)
	Get(context.Context, *GetRequest) (*GetResponse, error)
	List(context.Context, *ListRequest) (*ListResponse, error)
	Delete(context.Context, *DeleteRequest) error
	AppendEvent(context.Context, Session, *Event) error
}

• Purpose: Represents the contract for session storage services.

• Methods:

  • Create: Creates a new session.

  • Get: Retrieves an existing session with optional event filtering.

  • List: Lists sessions for a user/application.

  • Delete: Deletes a specified session.

  • AppendEvent: Appends an event to a session while filtering out temporary state keys.

• Parameters:

  • context.Context: Carries deadlines, cancellation signals, and other request-scoped values.

  • Request structs (CreateRequest, GetRequest, etc.) encapsulate input parameters.

  • Session: Represents the session entity to which events are appended.

  • *Event: The event data to append.

• Return Values:

  • Responses wrapping session data or error information.

This interface abstracts session management operations and facilitates interchangeable backend implementations, such as in-memory or database-backed services.

InMemoryService Function

func InMemoryService() Service

• Purpose: Provides an in-memory, thread-safe implementation of the Service interface.

• Usage: Useful for testing, prototyping, or ephemeral session storage scenarios where persistence across process restarts is not required.

• Implementation Details:

  • Initializes internal maps to hold application-wide and user-specific state.

  • Returns a Service instance that manages sessions fully in memory.

Request and Response Types

These structures define the input parameters and output data for session operations.

CreateRequest

type CreateRequest struct {
	AppName   string
	UserID    string
	SessionID string // Optional; autogenerated if empty
	State     map[string]any
}

• Fields:

  • AppName: Application identifier.

  • UserID: Identifier for the user owning the session.

  • SessionID: Optional client-provided session identifier.

  • State: Initial session state map.

• Usage: Used to request creation of a new session with optional pre-set state.

CreateResponse

type CreateResponse struct {
	Session Session
}

• Contains: The newly created session instance.

GetRequest

type GetRequest struct {
	AppName         string
	UserID          string
	SessionID       string
	NumRecentEvents int       // Optional filter: max number of recent events
	After           time.Time // Optional filter: events after this timestamp
}

• Functionality: Retrieves a session and optionally filters events by recency or timestamp threshold.

GetResponse

type GetResponse struct {
	Session Session
}

• Contains: The session data with events matching the filters.

ListRequest

type ListRequest struct {
	AppName string
	UserID  string
}

• Purpose: Lists all sessions for a given user and application.

ListResponse

type ListResponse struct {
	Sessions []Session
}

• Contains: Slice of sessions, each representing a user interaction context.

DeleteRequest

type DeleteRequest struct {
	AppName   string
	UserID    string
	SessionID string
}

• Purpose: Identifies the session to delete.

Important Implementation Details

• The Service interface abstracts session storage, allowing different implementations to manage sessions transparently.

• The in-memory implementation returned by InMemoryService uses concurrent-safe maps to store:

  • appState: Application-scoped state shared across users and sessions.

  • userState: User-scoped state per application.

• The AppendEvent method in the interface is responsible for:

  • Adding events to a session.

  • Cleaning temporary state keys (prefixed with temp:) from event state deltas before persistence.

  • Updating the appropriate state scopes (application, user, session) accordingly.

• The request and response types promote a clear, typed API for session operations.

Interaction With Other System Components

• The session service is a core component of the Session Management subsystem, interacting with:

  • Session state and event persistence layers (e.g., in-memory or database backends).

  • Agents and workflows that require context and history for multi-turn interactions, as managed in Agent Execution Runner.

  • Artifact management indirectly through session state and event metadata referencing artifacts (Artifact Management).

• The interface design supports pluggable backends enabling flexible deployment and testing strategies.

Visual Diagram

classDiagram
class Service {
+Create(ctx, req)
+Get(ctx, req)
+List(ctx, req)
+Delete(ctx, req)
+AppendEvent(ctx, session, event)
}
class InMemoryService {
-appState
-userState
+Create(ctx, req)
+Get(ctx, req)
+List(ctx, req)
+Delete(ctx, req)
+AppendEvent(ctx, session, event)
}
Service <|.. InMemoryService
class CreateRequest {
+AppName
+UserID
+SessionID
+State
}
class CreateResponse {
+Session
}
class GetRequest {
+AppName
+UserID
+SessionID
+NumRecentEvents
+After
}
class GetResponse {
+Session
}
class ListRequest {
+AppName
+UserID
}
class ListResponse {
+Sessions
}
class DeleteRequest {
+AppName
+UserID
+SessionID
}

This diagram illustrates:

• The Service interface with its key methods.

• The InMemoryService struct implementing Service, holding internal state maps.

• The request and response data structures used in session operations.

For further details on the implementation of the in-memory and database-backed services, and session state management algorithms including event filtering and state scoping, see the related subtopics in Session Management.