session

package
v1.5.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 21, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package session provides per-session subprocess management for MCP servers.

Each upstream MCP session gets its own isolated subprocess connected via the go-sdk CommandTransport. The Manager tracks the mapping from session IDs to downstream ClientSessions and handles lifecycle (spawn, teardown, cleanup).

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrSessionExists   = errors.New("session: session already exists")
	ErrSessionNotFound = errors.New("session: session not found")
	ErrMaxSessions     = errors.New("session: maximum concurrent sessions reached")
)

Errors returned by session Manager operations.

Functions

This section is empty.

Types

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager manages per-session subprocess lifecycle for a single MCP server. Each upstream session gets its own subprocess, connected via CommandTransport.

func NewManager 

func NewManager(serverName string, cfg *config.ServerConfig, logger *slog.Logger) *Manager

NewManager creates a new session Manager for the given server.

func (*Manager) AdmissionStatus 

func (m *Manager) AdmissionStatus() (atCapacity bool, current int, max int)

AdmissionStatus returns current admission-control state. atCapacity is true only when MaxSessions is configured (>0) and reached.

func (*Manager) CloseAll 

func (m *Manager) CloseAll()

CloseAll terminates all sessions and their subprocesses.

func (*Manager) GetSession 

func (m *Manager) GetSession(sessionID string) *TrackedSession

GetSession returns the tracked session for the given session ID, or nil.

func (*Manager) RemoveSession 

func (m *Manager) RemoveSession(sessionID string) error

RemoveSession terminates the downstream subprocess and removes the session. It gracefully closes the ClientSession (which closes stdin, waits, then SIGTERM/SIGKILL).

func (*Manager) SessionCount 

func (m *Manager) SessionCount() int

SessionCount returns the number of active sessions.

func (*Manager) Sessions 

func (m *Manager) Sessions() []string

Sessions returns a snapshot of all active session IDs.

func (*Manager) SetOnSessionRemoved 

func (m *Manager) SetOnSessionRemoved(fn func(sessionID string))

SetOnSessionRemoved registers a callback that fires before any session's downstream connection is closed. This is called from all removal paths: RemoveSession, reaper, and CloseAll. The callback receives the session ID and runs outside any Manager lock, allowing the proxy layer to gate further dispatches before the SDK connection is torn down.

func (*Manager) SpawnSession 

func (m *Manager) SpawnSession(ctx context.Context, sessionID string, clientOpts ...*mcp.ClientOptions) (*mcp.ClientSession, error)

SpawnSession creates a new downstream subprocess for the given session ID. It connects via CommandTransport, performs the initialize handshake, and returns the ready-to-use ClientSession. If clientOpts is non-nil, it is used to configure the downstream Client (e.g., for notification handlers).

func (*Manager) StartReaper 

func (m *Manager) StartReaper(ctx context.Context, checkInterval time.Duration)

StartReaper starts a background goroutine that periodically checks for idle and TTL-expired sessions and removes them. The reaper stops when the context is cancelled.

func (*Manager) TouchSession 

func (m *Manager) TouchSession(sessionID string)

TouchSession updates the LastActivity timestamp for valid application activity on the given session.

type SharedSessionManager 

type SharedSessionManager struct {
	// contains filtered or unexported fields
}

SharedSessionManager maintains a single downstream subprocess shared across all upstream sessions for stateless MCP servers.

func NewSharedSessionManager 

func NewSharedSessionManager(serverName string, cfg *config.ServerConfig, logger *slog.Logger, idleTimeout time.Duration, m metrics.ServerMetricsReporter) *SharedSessionManager

NewSharedSessionManager creates a new shared session manager. idleTimeout controls the idle reap behavior: when refCount drops to 0, the downstream subprocess is torn down after this duration. 0 disables idle reaping.

func (*SharedSessionManager) AdmissionStatus 

func (sm *SharedSessionManager) AdmissionStatus() (atCapacity bool, current int, max int)

AdmissionStatus returns current admission-control state.

func (*SharedSessionManager) BeginRequest added in v1.5.5 

func (sm *SharedSessionManager) BeginRequest(sessionID string) func()

BeginRequest marks an application request as in flight until the returned release function runs. Idle reaping never removes such a session.

func (*SharedSessionManager) CloseAll 

func (sm *SharedSessionManager) CloseAll()

CloseAll terminates the shared downstream subprocess and clears all state.

func (*SharedSessionManager) Downstream 

func (sm *SharedSessionManager) Downstream() *mcp.ClientSession

Downstream returns the current downstream session (may be nil).

func (*SharedSessionManager) GetOrCreateSession 

func (sm *SharedSessionManager) GetOrCreateSession(ctx context.Context, sessionID string) (*mcp.ClientSession, error)

GetOrCreateSession returns the shared downstream session, lazily spawning it on first use. The sessionID is tracked for admission control and refcounting.

func (*SharedSessionManager) HasDownstream 

func (sm *SharedSessionManager) HasDownstream() bool

HasDownstream reports whether a downstream session is currently active.

func (*SharedSessionManager) RefCount 

func (sm *SharedSessionManager) RefCount() int

RefCount returns the current upstream refcount.

func (*SharedSessionManager) RemoveSession 

func (sm *SharedSessionManager) RemoveSession(sessionID string) error

RemoveSession removes the upstream session from tracking and decrements refcount. If refCount reaches 0 and idle reap is enabled, starts the idle reap timer.

func (*SharedSessionManager) SessionCount 

func (sm *SharedSessionManager) SessionCount() int

SessionCount returns the number of tracked upstream sessions.

func (*SharedSessionManager) SetOnSessionExpired added in v1.5.5 

func (sm *SharedSessionManager) SetOnSessionExpired(fn func(sessionID string))

SetOnSessionExpired registers the callback used when a shared upstream session exceeds session_timeout. The callback owns proxy-session cleanup.

func (*SharedSessionManager) SetReachabilityStore added in v1.5.0 

func (sm *SharedSessionManager) SetReachabilityStore(store *reachability.Store)

SetReachabilityStore configures the optional store used by health probes. A nil store disables reporting while leaving the probe behavior unchanged.

func (*SharedSessionManager) StartHealthProbe 

func (sm *SharedSessionManager) StartHealthProbe(ctx context.Context)

StartHealthProbe starts a background goroutine that periodically probes the shared downstream for liveness. If the probe fails, the downstream is respawned.

func (*SharedSessionManager) StartReaper added in v1.5.5 

func (sm *SharedSessionManager) StartReaper(ctx context.Context, checkInterval time.Duration)

StartReaper starts the shared upstream-session idle reaper.

func (*SharedSessionManager) Subscribe 

func (sm *SharedSessionManager) Subscribe(sessionID string, onRespawn func(*mcp.ClientSession))

Subscribe registers a callback to be invoked when the downstream is respawned.

func (*SharedSessionManager) TouchSession added in v1.5.5 

func (sm *SharedSessionManager) TouchSession(sessionID string)

TouchSession records valid application activity for one upstream session. Protocol pings, notifications, responses, and GET/SSE requests do not call this method.

func (*SharedSessionManager) Unsubscribe 

func (sm *SharedSessionManager) Unsubscribe(sessionID string)

Unsubscribe removes the respawn callback for the given session ID.

type TrackedSession 

type TrackedSession struct {
	SessionID    string
	Downstream   *mcp.ClientSession
	Client       *mcp.Client
	CreatedAt    time.Time // When the session was spawned
	LastActivity time.Time // Last time the session was actively used
}

TrackedSession holds the downstream client session and metadata for a single upstream MCP session.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.