cache

type Cache interface {

	// IncrSeq atomically increments and returns the sequence number for a given scope.
	IncrSeq(ctx context.Context, scope, scopeID string) (uint64, error)

	// IncrMsgID atomically increments and returns the message ID for a conversation.
	IncrMsgID(ctx context.Context, conversationID string) (uint64, error)

	// IncrSeqAndMsgID atomically increments both seq and msgID in a single call.
	IncrSeqAndMsgID(ctx context.Context, scope, scopeID, conversationID string) (seq uint64, msgID uint64, err error)

	// GetCurrentSeq returns the current sequence number for a given scope without incrementing.
	GetCurrentSeq(ctx context.Context, scope, scopeID string) (uint64, error)

	// SetSeq sets the sequence counter for a scope to the given value.
	// Used during startup to sync Redis seq with DB max(seq).
	// Only updates if val > current seq (never goes backwards).
	SetSeq(ctx context.Context, scope, scopeID string, val uint64) error

	// Publish sends data to the specified channel.
	Publish(ctx context.Context, channel string, data []byte) error

	// Subscribe returns a channel that receives messages from the specified channel.
	// The returned func() is the unsubscribe function — calling it closes the channel
	// and releases resources. There is no standalone Unsubscribe method.
	Subscribe(ctx context.Context, channel string) (<-chan []byte, func(), error)

	// SetConversationState stores the state of a conversation.
	SetConversationState(ctx context.Context, conversationID string, state string) error

	// GetConversationState retrieves the state of a conversation.
	GetConversationState(ctx context.Context, conversationID string) (string, error)

	// IncrConnCount atomically increments the connection count for a user and sets TTL.
	// Returns the new count after increment.
	IncrConnCount(ctx context.Context, userID string) (int64, error)

	// DecrConnCount atomically decrements the connection count for a user.
	// Clamps at 0 (no negative counts). Returns the new count after decrement.
	DecrConnCount(ctx context.Context, userID string) (int64, error)

	// GetConnCount returns the current connection count for a user.
	// Returns 0 if no connections exist.
	GetConnCount(ctx context.Context, userID string) (int64, error)

	// RenewConnCount extends the TTL for a user's connection count without changing the count.
	// Used for batch TTL renewal to prevent expiry of active users.
	RenewConnCount(ctx context.Context, userID string) error

	// IsHealthy returns true if the cache backend is reachable.
	IsHealthy(ctx context.Context) bool

	// Close releases all resources (connections, goroutines).
	Close() error
}