-- SPDX-FileCopyrightText: 2026 Alexandra de Wit
-- SPDX-License-Identifier: MIT

-- | Retention handles and their storage capability classification.
module Ecluse.Core.Server.Cache.Backend.Internal (
    RetentionBackend (..),
    RetentionOperations (..),
    BackendStorage (..),
    Recency (..),
    CacheOccupancy (..),
) where

-- | Backend-owned storage, independent of request coalescing and admission.
data RetentionBackend k v = RetentionBackend
    { forall k v. RetentionBackend k v -> BackendStorage
rbStorage :: BackendStorage
    , forall k v.
RetentionBackend k v
-> (CacheOccupancy -> IO ())
-> IO ()
-> Recency
-> k
-> IO (Maybe v)
rbLookup :: (CacheOccupancy -> IO ()) -> IO () -> Recency -> k -> IO (Maybe v)
    -- ^ Report occupancy changes and backend failure, then return a retained value.
    , forall k v.
RetentionBackend k v
-> (CacheOccupancy -> IO ()) -> IO () -> IO () -> k -> v -> IO ()
rbInsert :: (CacheOccupancy -> IO ()) -> IO () -> IO () -> k -> v -> IO ()
    -- ^ Report occupancy, capacity refusal, and backend failure respectively.
    }

{- | Typed storage operations. Recency is advisory and occupancy reporting is optional.
Adapters may report charged bytes and entry counts. These do not measure process or remote heap size.
-}
data RetentionOperations k v = RetentionOperations
    { forall k v.
RetentionOperations k v
-> (CacheOccupancy -> IO ()) -> Recency -> k -> IO (Maybe v)
roLookup :: (CacheOccupancy -> IO ()) -> Recency -> k -> IO (Maybe v)
    , forall k v.
RetentionOperations k v
-> (CacheOccupancy -> IO ()) -> IO () -> k -> v -> IO ()
roInsert :: (CacheOccupancy -> IO ()) -> IO () -> k -> v -> IO ()
    }

-- | Local storage cannot retain full metadata, regardless of its capacity.
data BackendStorage
    = LocalStorage
    | -- | External operation deadline, in microseconds, capped by the handle.
      ExternalStorage Int
    deriving stock (BackendStorage -> BackendStorage -> Bool
(BackendStorage -> BackendStorage -> Bool)
-> (BackendStorage -> BackendStorage -> Bool) -> Eq BackendStorage
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: BackendStorage -> BackendStorage -> Bool
== :: BackendStorage -> BackendStorage -> Bool
$c/= :: BackendStorage -> BackendStorage -> Bool
/= :: BackendStorage -> BackendStorage -> Bool
Eq, Int -> BackendStorage -> ShowS
[BackendStorage] -> ShowS
BackendStorage -> String
(Int -> BackendStorage -> ShowS)
-> (BackendStorage -> String)
-> ([BackendStorage] -> ShowS)
-> Show BackendStorage
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> BackendStorage -> ShowS
showsPrec :: Int -> BackendStorage -> ShowS
$cshow :: BackendStorage -> String
show :: BackendStorage -> String
$cshowList :: [BackendStorage] -> ShowS
showList :: [BackendStorage] -> ShowS
Show)

-- | Whether a probe contributes to eviction recency.
data Recency = PreserveRecency | RefreshRecency
    deriving stock (Recency -> Recency -> Bool
(Recency -> Recency -> Bool)
-> (Recency -> Recency -> Bool) -> Eq Recency
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: Recency -> Recency -> Bool
== :: Recency -> Recency -> Bool
$c/= :: Recency -> Recency -> Bool
/= :: Recency -> Recency -> Bool
Eq, Int -> Recency -> ShowS
[Recency] -> ShowS
Recency -> String
(Int -> Recency -> ShowS)
-> (Recency -> String) -> ([Recency] -> ShowS) -> Show Recency
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> Recency -> ShowS
showsPrec :: Int -> Recency -> ShowS
$cshow :: Recency -> String
show :: Recency -> String
$cshowList :: [Recency] -> ShowS
showList :: [Recency] -> ShowS
Show)

-- | Entry count and summed accounted bytes after a store mutation.
data CacheOccupancy = CacheOccupancy
    { CacheOccupancy -> Int
occEntries :: Int
    , CacheOccupancy -> Int
occBytes :: Int
    }
    deriving stock (CacheOccupancy -> CacheOccupancy -> Bool
(CacheOccupancy -> CacheOccupancy -> Bool)
-> (CacheOccupancy -> CacheOccupancy -> Bool) -> Eq CacheOccupancy
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: CacheOccupancy -> CacheOccupancy -> Bool
== :: CacheOccupancy -> CacheOccupancy -> Bool
$c/= :: CacheOccupancy -> CacheOccupancy -> Bool
/= :: CacheOccupancy -> CacheOccupancy -> Bool
Eq, Int -> CacheOccupancy -> ShowS
[CacheOccupancy] -> ShowS
CacheOccupancy -> String
(Int -> CacheOccupancy -> ShowS)
-> (CacheOccupancy -> String)
-> ([CacheOccupancy] -> ShowS)
-> Show CacheOccupancy
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> CacheOccupancy -> ShowS
showsPrec :: Int -> CacheOccupancy -> ShowS
$cshow :: CacheOccupancy -> String
show :: CacheOccupancy -> String
$cshowList :: [CacheOccupancy] -> ShowS
showList :: [CacheOccupancy] -> ShowS
Show)