session

type Config struct {
	// SiteID identifies which site/service this store handles.
	// Used for multi-site isolation (e.g., "academyos", "agentos", "dashforge").
	// When set, all sessions are tagged with this SiteID and Get operations
	// validate the session belongs to this site.
	// Required for ControlledStore when running multiple sites.
	SiteID string

	// MaxSessionSize is the maximum serialized session size in bytes.
	// Set to 0 for no limit.
	MaxSessionSize int

	// MaxSessionsPerUser limits concurrent sessions per user.
	// When exceeded, oldest sessions are deleted to make room.
	// Set to 0 for no limit.
	MaxSessionsPerUser int

	// DefaultTTL is the default session TTL if not specified.
	DefaultTTL time.Duration

	// CleanupInterval is how often to run automatic cleanup.
	// Set to 0 to disable automatic cleanup.
	CleanupInterval time.Duration

	// KeyPrefix is the prefix for session keys (for KVS backends).
	KeyPrefix string
}

type ControlOption func(*ControlledStore)

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

type Session struct {
	// ID is the unique session identifier.
	ID string `json:"id"`

	// UserID is the authenticated user's ID.
	UserID uuid.UUID `json:"user_id"`

	// SiteID identifies which site/service this session belongs to.
	// Used for multi-site isolation (e.g., "academyos", "agentos", "dashforge").
	// Set automatically by ControlledStore based on Config.SiteID.
	SiteID string `json:"site_id,omitempty"`

	// OrganizationID is the current organization context (optional).
	OrganizationID *uuid.UUID `json:"organization_id,omitempty"`

	// Data contains arbitrary session data.
	// This can include tokens, preferences, etc.
	Data map[string]any `json:"data,omitempty"`

	// CreatedAt is when the session was created.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is when the session was last updated.
	UpdatedAt time.Time `json:"updated_at"`

	// LastAccessedAt is when the session was last accessed.
	LastAccessedAt time.Time `json:"last_accessed_at"`

	// ExpiresAt is when the session expires.
	ExpiresAt time.Time `json:"expires_at"`

	// IPAddress is the IP address that created the session.
	IPAddress string `json:"ip_address,omitempty"`

	// UserAgent is the user agent that created the session.
	UserAgent string `json:"user_agent,omitempty"`
}

type SessionError struct {
	// Code is a machine-readable error code.
	Code string

	// Message is a human-readable error message.
	Message string

	// Details contains additional error context.
	Details map[string]any

	// Cause is the underlying error, if any.
	Cause error
}

type SessionLister interface {
	// ListByUserID returns all sessions for a user, sorted by CreatedAt ascending (oldest first).
	ListByUserID(ctx context.Context, userID string) ([]*Session, error)
}

type Store interface {
	// Create stores a new session.
	Create(ctx context.Context, session *Session) error

	// Get retrieves a session by ID.
	// Returns ErrNotFound if the session doesn't exist.
	// Returns ErrExpired if the session has expired.
	Get(ctx context.Context, id string) (*Session, error)

	// Update updates an existing session.
	// Returns ErrNotFound if the session doesn't exist.
	Update(ctx context.Context, session *Session) error

	// Delete removes a session by ID.
	Delete(ctx context.Context, id string) error

	// DeleteByUserID removes all sessions for a user.
	// Returns the number of sessions deleted.
	DeleteByUserID(ctx context.Context, userID string) (int, error)

	// Touch updates the LastAccessedAt timestamp.
	// This is used to track session activity without modifying other fields.
	Touch(ctx context.Context, id string) error

	// Close closes the store and releases any resources.
	Close() error
}

type ViolationEvent struct {
	Type ViolationType
	// SessionID is no longer set, because session IDs are bearer
	// credentials and must not reach logs or metrics.
	//
	// Deprecated: Use SessionRef.
	SessionID string
	// SessionRef is SessionRef(id) of the session involved, a
	// non-reversible reference safe to log.
	SessionRef string
	UserID     uuid.UUID
	SiteID     string // Site identifier for multi-site isolation
	Size       int    // Current size in bytes
	Limit      int    // Configured limit
	Message    string
}

type ViolationHandler func(ctx context.Context, event ViolationEvent)

type ViolationType string