session

package
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2025 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package session provides a session manager with TTL cleanup.

Package session provides session management with pluggable storage backends.

Index

Constants

View Source 
const (
	// DefaultSessionTTL is the default time-to-live for sessions (2 hours)
	DefaultSessionTTL = 2 * time.Hour
)

Variables

View Source 
var (
	// ErrSessionDisconnected is returned when trying to send to a disconnected session
	ErrSessionDisconnected = errors.New("session is disconnected")

	// ErrMessageChannelFull is returned when the message channel is full
	ErrMessageChannelFull = errors.New("message channel is full")

	// ErrSessionNotFound is returned when a session cannot be found
	ErrSessionNotFound = errors.New("session not found")

	// ErrSessionAlreadyExists is returned when trying to create a session with an existing ID
	ErrSessionAlreadyExists = errors.New("session already exists")

	// ErrInvalidSessionType is returned when an invalid session type is provided
	ErrInvalidSessionType = errors.New("invalid session type")
)

Common session errors

Functions

This section is empty.

Types

type Factory 

type Factory func(id string) Session

Factory defines a function type for creating new sessions. It now returns the Session interface to support different session types.

type LegacyFactory added in v0.2.17 

type LegacyFactory func(id string) *ProxySession

LegacyFactory is the old factory type for backward compatibility

type LocalStorage added in v0.3.8 

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

LocalStorage implements the Storage interface using an in-memory sync.Map. This is the default storage backend for single-instance deployments.

func NewLocalStorage added in v0.3.8 

func NewLocalStorage() *LocalStorage

NewLocalStorage creates a new local in-memory storage backend.

func (*LocalStorage) Close added in v0.3.8 

func (s *LocalStorage) Close() error

Close clears all sessions from local storage.

func (*LocalStorage) Count added in v0.3.8 

func (s *LocalStorage) Count() int

Count returns the number of sessions in storage. This is a helper method not part of the Storage interface.

func (*LocalStorage) Delete added in v0.3.8 

func (s *LocalStorage) Delete(_ context.Context, id string) error

Delete removes a session from local storage.

func (*LocalStorage) DeleteExpired added in v0.3.8 

func (s *LocalStorage) DeleteExpired(ctx context.Context, before time.Time) error

DeleteExpired removes all sessions that haven't been updated since the given time.

func (*LocalStorage) Load added in v0.3.8 

func (s *LocalStorage) Load(_ context.Context, id string) (Session, error)

Load retrieves a session from local storage.

func (*LocalStorage) Range added in v0.3.8 

func (s *LocalStorage) Range(f func(key, value interface{}) bool)

Range iterates over all sessions in storage. This is a helper method not part of the Storage interface.

func (*LocalStorage) Store added in v0.3.8 

func (s *LocalStorage) Store(_ context.Context, session Session) error

Store saves a session to the local storage. For local storage, we store the session object directly without serialization.

type Manager 

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

Manager holds sessions with TTL cleanup.

func NewManager 

func NewManager(ttl time.Duration, factory interface{}) *Manager

NewManager creates a session manager with TTL and starts cleanup worker. It accepts either the new Factory or the legacy factory for backward compatibility.

func NewManagerWithStorage added in v0.3.8 

func NewManagerWithStorage(ttl time.Duration, factory Factory, storage Storage) *Manager

NewManagerWithStorage creates a session manager with a custom storage backend.

func NewTypedManager added in v0.2.17 

func NewTypedManager(ttl time.Duration, sessionType SessionType) *Manager

NewTypedManager creates a session manager for a specific session type.

func (*Manager) AddSession added in v0.2.17 

func (m *Manager) AddSession(session Session) error

AddSession adds an existing session to the manager. This is useful when you need to create a session with specific properties.

func (*Manager) AddWithID 

func (m *Manager) AddWithID(id string) error

AddWithID creates (and adds) a new session with the provided ID. Returns error if ID is empty or already exists.

func (*Manager) Count added in v0.2.17 

func (m *Manager) Count() int

Count returns the number of active sessions.

Note: This method only works with LocalStorage backend and returns 0 for other storage backends. Count is not part of the Storage interface because it's not feasible for distributed storage backends like Redis where counting all keys can be prohibitively expensive.

For distributed storage, consider maintaining a counter or using approximate count mechanisms provided by the storage backend.

func (*Manager) Delete 

func (m *Manager) Delete(id string) error

Delete removes a session by ID. Returns an error if the deletion fails.

func (*Manager) Get 

func (m *Manager) Get(id string) (Session, bool)

Get retrieves a session by ID. Returns (session, true) if found, and also updates its UpdatedAt timestamp.

func (*Manager) Range added in v0.2.17 

func (m *Manager) Range(f func(key, value interface{}) bool)

Range calls f sequentially for each key and value present in the map. If f returns false, range stops the iteration.

Note: This method only works with LocalStorage backend. It will silently do nothing with other storage backends. Range is not part of the Storage interface because it's not feasible for distributed storage backends like Redis where iterating all keys can be prohibitively expensive or impractical.

For distributed storage, consider using more targeted queries or maintaining a separate index of session IDs.

func (*Manager) Stop 

func (m *Manager) Stop() error

Stop stops the cleanup worker and closes the storage backend. Returns an error if closing the storage backend fails.

type ProxySession 

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

ProxySession implements the Session interface for proxy sessions. It now includes support for session types, metadata, and custom data.

func NewProxySession 

func NewProxySession(id string) *ProxySession

NewProxySession creates a new ProxySession with the given ID. It defaults to SessionTypeMCP for backward compatibility.

func NewTypedProxySession added in v0.2.17 

func NewTypedProxySession(id string, sessType SessionType) *ProxySession

NewTypedProxySession creates a new ProxySession with the given ID and type.

func (*ProxySession) CreatedAt 

func (s *ProxySession) CreatedAt() time.Time

CreatedAt returns the creation time of the session.

func (*ProxySession) DeleteMetadata added in v0.2.17 

func (s *ProxySession) DeleteMetadata(key string)

DeleteMetadata removes a metadata key.

func (*ProxySession) GetData added in v0.2.17 

func (s *ProxySession) GetData() interface{}

GetData returns the session-specific data.

func (*ProxySession) GetMetadata added in v0.2.17 

func (s *ProxySession) GetMetadata() map[string]string

GetMetadata returns all metadata as a map.

func (*ProxySession) GetMetadataValue added in v0.2.17 

func (s *ProxySession) GetMetadataValue(key string) (string, bool)

GetMetadataValue gets a specific metadata value.

func (*ProxySession) ID 

func (s *ProxySession) ID() string

ID returns the session ID.

func (*ProxySession) SetData added in v0.2.17 

func (s *ProxySession) SetData(data interface{})

SetData sets the session-specific data.

func (*ProxySession) SetMetadata added in v0.2.17 

func (s *ProxySession) SetMetadata(key, value string)

SetMetadata sets a metadata key-value pair.

func (*ProxySession) Touch 

func (s *ProxySession) Touch()

Touch updates the session's last updated time to the current time.

func (*ProxySession) Type added in v0.2.17 

func (s *ProxySession) Type() SessionType

Type returns the session type.

func (*ProxySession) UpdatedAt 

func (s *ProxySession) UpdatedAt() time.Time

UpdatedAt returns the last updated time of the session.

type SSESession added in v0.2.17 

type SSESession struct {
	*ProxySession

	// SSE-specific fields
	MessageCh   chan string
	ClientInfo  *ssecommon.SSEClient
	IsConnected bool
}

SSESession represents an SSE (Server-Sent Events) session. It embeds ProxySession and adds SSE-specific functionality.

func NewSSESession added in v0.2.17 

func NewSSESession(id string) *SSESession

NewSSESession creates a new SSE session with the given ID.

func NewSSESessionWithClient added in v0.2.17 

func NewSSESessionWithClient(id string, client *ssecommon.SSEClient) *SSESession

NewSSESessionWithClient creates a new SSE session with the given ID and client info.

func (*SSESession) Disconnect added in v0.2.17 

func (s *SSESession) Disconnect()

Disconnect marks the session as disconnected and closes the message channel.

func (*SSESession) GetClientInfo added in v0.2.17 

func (s *SSESession) GetClientInfo() *ssecommon.SSEClient

GetClientInfo returns the SSE client information.

func (*SSESession) GetConnectionStatus added in v0.2.17 

func (s *SSESession) GetConnectionStatus() bool

GetConnectionStatus returns whether the SSE session is connected.

func (*SSESession) GetCreatedAt added in v0.2.17 

func (s *SSESession) GetCreatedAt() time.Time

GetCreatedAt returns when the SSE session was created. This is useful for tracking connection duration.

func (*SSESession) SendMessage added in v0.2.17 

func (s *SSESession) SendMessage(msg string) error

SendMessage sends a message to the SSE client if connected.

func (*SSESession) SetClientInfo added in v0.2.17 

func (s *SSESession) SetClientInfo(client *ssecommon.SSEClient)

SetClientInfo sets the SSE client information.

type Session 

type Session interface {
	ID() string
	Type() SessionType
	CreatedAt() time.Time
	UpdatedAt() time.Time
	Touch()

	// Data and metadata methods
	GetData() interface{}
	SetData(data interface{})
	GetMetadata() map[string]string
	SetMetadata(key, value string)
}

Session interface defines the contract for all session types

func NewStreamableSession added in v0.2.17 

func NewStreamableSession(id string) Session

NewStreamableSession constructs a new streamable session with buffered channels

type SessionType added in v0.2.17 

type SessionType string

SessionType represents the type of session 

const (
	// SessionTypeMCP represents a standard MCP session
	SessionTypeMCP SessionType = "mcp"
	// SessionTypeSSE represents an SSE (Server-Sent Events) session
	SessionTypeSSE SessionType = "sse"
	// SessionTypeStreamable represents a streamable HTTP session
	SessionTypeStreamable SessionType = "streamable"
)

type Storage added in v0.3.8 

type Storage interface {
	// Store creates or updates a session in the storage backend.
	// If the session already exists, it will be overwritten.
	Store(ctx context.Context, session Session) error

	// Load retrieves a session by ID from the storage backend.
	// Returns ErrSessionNotFound if the session doesn't exist.
	// Note: This does not automatically touch the session. Callers should
	// explicitly call Touch() on the returned session if they want to update its timestamp.
	Load(ctx context.Context, id string) (Session, error)

	// Delete removes a session from the storage backend.
	// It is not an error if the session doesn't exist.
	Delete(ctx context.Context, id string) error

	// DeleteExpired removes all sessions that haven't been updated since the given time.
	// This is used by the cleanup routine to remove stale sessions.
	DeleteExpired(ctx context.Context, before time.Time) error

	// Close performs cleanup of the storage backend.
	// For local storage, this clears all sessions. For remote storage, it closes connections.
	Close() error
}

Storage defines the minimal interface for session storage backends. This interface is designed to be simple and efficient, supporting both local in-memory storage and distributed storage backends like Redis/Valkey.

type StreamableSession added in v0.2.17 

type StreamableSession struct {
	*ProxySession
	MessageCh  chan jsonrpc2.Message
	ResponseCh chan jsonrpc2.Message
	// contains filtered or unexported fields
}

StreamableSession represents a Streamable HTTP session

func (*StreamableSession) Disconnect added in v0.2.17 

func (s *StreamableSession) Disconnect()

Disconnect closes channels and marks session as disconnected

func (*StreamableSession) GetData added in v0.2.17 

func (s *StreamableSession) GetData() interface{}

GetData exposes buffer stats for observability/debugging

func (*StreamableSession) SendMessage added in v0.2.17 

func (s *StreamableSession) SendMessage(msg jsonrpc2.Message) error

SendMessage pushes message to MessageCh

func (*StreamableSession) SendResponse added in v0.2.17 

func (s *StreamableSession) SendResponse(msg jsonrpc2.Message) error

SendResponse pushes message to ResponseCh

func (*StreamableSession) SetData added in v0.2.17 

func (*StreamableSession) SetData(interface{})

SetData is a no-op for StreamableSession; channel stats are exposed via GetData.

func (*StreamableSession) Type added in v0.2.17 

func (*StreamableSession) Type() SessionType

Type identifies this as a streamable 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.