session

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

type Broadcaster interface {
	// Subscribe registers a new subscriber and returns the subscription.
	// ctx cancellation closes the subscription automatically. The
	// sessionID is recorded for log attribution only — events are
	// fan-out broadcast to every subscriber regardless of sessionID.
	// (tools/list_changed today is a server-wide signal, so per-
	// session targeting is intentionally not implemented; if a future
	// notification needs per-session delivery, add an Event.SessionID
	// filter at Publish time and document the contract change here.)
	Subscribe(ctx context.Context, sessionID string) Subscription
	// Publish delivers ev to every active subscription. Best-effort:
	// returns nil even when individual subscribers are dropped due to
	// buffer overflow. The error path is reserved for unrecoverable
	// transport faults (e.g., the underlying postgres LISTEN connection
	// is closed) so callers can decide whether to retry or surface.
	Publish(ctx context.Context, ev Event) error
	// Close releases any background resources. After Close, Subscribe
	// returns a closed-immediate subscription and Publish returns
	// ErrBroadcasterClosed.
	Close() error
}

type Event struct {
	Method string         `json:"method"`
	Params map[string]any `json:"params,omitempty"`
}

type HandlerConfig struct {
	Store Store
	TTL   time.Duration
	// Broadcaster delivers server-pushed MCP notifications (e.g.
	// notifications/tools/list_changed) to the per-session SSE
	// long-poll stream. When nil, GET requests are forwarded to the
	// inner handler unchanged — useful for tests or for transport
	// modes that don't need server push.
	Broadcaster Broadcaster
}

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

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

type Session struct {
	// ID is the unique session identifier.
	ID string

	// UserID identifies the session owner. For authenticated sessions this is
	// a hash of the bearer token; for anonymous sessions it is empty.
	UserID string

	// CreatedAt is when the session was established.
	CreatedAt time.Time

	// LastActiveAt is the most recent activity timestamp.
	LastActiveAt time.Time

	// ExpiresAt is when the session expires if not touched.
	ExpiresAt time.Time

	// State holds extensible session data (e.g. enrichment dedup state).
	State map[string]any
}

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

	// Get retrieves a session by ID. Returns nil, nil if not found or expired.
	Get(ctx context.Context, id string) (*Session, error)

	// Touch updates LastActiveAt and extends ExpiresAt by the store's TTL.
	Touch(ctx context.Context, id string) error

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

	// List returns all non-expired sessions.
	List(ctx context.Context) ([]*Session, error)

	// UpdateState merges state into the session's State map.
	UpdateState(ctx context.Context, id string, state map[string]any) error

	// Cleanup removes expired sessions.
	Cleanup(ctx context.Context) error

	// Close stops background routines and releases resources.
	Close() error
}

type Subscription interface {
	// Events returns the channel events are delivered on. The channel is
	// closed by Close, after which receives yield zero values.
	Events() <-chan Event
	// Close releases the subscription. Safe to call more than once.
	Close()
}