-- SPDX-FileCopyrightText: 2026 Alexandra de Wit
--
-- SPDX-License-Identifier: MIT
{-# LANGUAGE TupleSections #-}

{- | One provider owns metadata retention. Local single-flight shares active requests.
Public metadata and content-addressed responses follow the sharing policy in the web-layer architecture.
-}
module Ecluse.Core.Server.Cache (
    -- * Configuration
    CacheConfig (..),
    StoreBudget (..),

    -- * The cache handle
    MetadataCache,
    newMetadataCacheWithProvider,

    -- * Cache entries
    Source (..),
    CacheEntry (..),

    -- * Resolution
    resolveMetadata,
    resolveDirectory,

    -- * Single-version resolution
    resolveVersion,
    prepareVersion,

    -- * Assembled-representation resolution
    resolveAssembled,
) where

import Data.ByteString.Short qualified as SBS

import Ecluse.Core.Package (PackageName)
import Ecluse.Core.Registry.Metadata (MetadataError, VersionRead)
import Ecluse.Core.Registry.RubyGems.Directory (GemDirectory)
import Ecluse.Core.Server.Cache.Provider (CacheProvider, providerAssembled, providerDirectory, providerFull, providerVersion)
import Ecluse.Core.Server.Cache.Store (
    CacheOccupancy (..),
    PreparedStore,
    SingleFlight,
    executePrepared,
    newSingleFlightWithBackend,
    prepareStore,
    resolveSingleFlight,
 )
import Ecluse.Core.Server.Cache.Types
import Ecluse.Core.Telemetry.Metrics qualified as Metric
import Ecluse.Core.Telemetry.Record (MetricsPort (..))
import Ecluse.Core.Version (Version)

-- | One provider supplies every retention capability beside process-local request coalescing.
data MetadataCache = MetadataCache
    { MetadataCache
-> SingleFlight MetadataError CacheKey (GemDirectory, Int)
mcDirectory :: SingleFlight MetadataError CacheKey (GemDirectory, Int)
    , MetadataCache -> SingleFlight MetadataError CacheKey CacheEntry
mcFull :: SingleFlight MetadataError CacheKey CacheEntry
    -- ^ Full fetches partition by source, ecosystem, and package without local retention.
    , MetadataCache -> SingleFlight MetadataError CacheKey VersionRead
mcVersion :: SingleFlight MetadataError CacheKey VersionRead
    , MetadataCache -> SingleFlight Void CacheKey ByteString
mcAssembled :: SingleFlight Void CacheKey ByteString
    }

-- | Create only transient flight state. The selected provider owns every retained representation.
newMetadataCacheWithProvider :: CacheProvider -> IO MetadataCache
newMetadataCacheWithProvider :: CacheProvider -> IO MetadataCache
newMetadataCacheWithProvider CacheProvider
provider =
    SingleFlight MetadataError CacheKey (GemDirectory, Int)
-> SingleFlight MetadataError CacheKey CacheEntry
-> SingleFlight MetadataError CacheKey VersionRead
-> SingleFlight Void CacheKey ByteString
-> MetadataCache
MetadataCache
        (SingleFlight MetadataError CacheKey (GemDirectory, Int)
 -> SingleFlight MetadataError CacheKey CacheEntry
 -> SingleFlight MetadataError CacheKey VersionRead
 -> SingleFlight Void CacheKey ByteString
 -> MetadataCache)
-> IO (SingleFlight MetadataError CacheKey (GemDirectory, Int))
-> IO
     (SingleFlight MetadataError CacheKey CacheEntry
      -> SingleFlight MetadataError CacheKey VersionRead
      -> SingleFlight Void CacheKey ByteString
      -> MetadataCache)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Maybe (RetentionBackend CacheKey (GemDirectory, Int))
-> IO (SingleFlight MetadataError CacheKey (GemDirectory, Int))
forall k v e.
Maybe (RetentionBackend k v) -> IO (SingleFlight e k v)
newSingleFlightWithBackend (CacheProvider
-> Maybe (RetentionBackend CacheKey (GemDirectory, Int))
providerDirectory CacheProvider
provider)
        IO
  (SingleFlight MetadataError CacheKey CacheEntry
   -> SingleFlight MetadataError CacheKey VersionRead
   -> SingleFlight Void CacheKey ByteString
   -> MetadataCache)
-> IO (SingleFlight MetadataError CacheKey CacheEntry)
-> IO
     (SingleFlight MetadataError CacheKey VersionRead
      -> SingleFlight Void CacheKey ByteString -> MetadataCache)
forall a b. IO (a -> b) -> IO a -> IO b
forall (f :: * -> *) a b. Applicative f => f (a -> b) -> f a -> f b
<*> Maybe (RetentionBackend CacheKey CacheEntry)
-> IO (SingleFlight MetadataError CacheKey CacheEntry)
forall k v e.
Maybe (RetentionBackend k v) -> IO (SingleFlight e k v)
newSingleFlightWithBackend (CacheProvider -> Maybe (RetentionBackend CacheKey CacheEntry)
providerFull CacheProvider
provider)
        IO
  (SingleFlight MetadataError CacheKey VersionRead
   -> SingleFlight Void CacheKey ByteString -> MetadataCache)
-> IO (SingleFlight MetadataError CacheKey VersionRead)
-> IO (SingleFlight Void CacheKey ByteString -> MetadataCache)
forall a b. IO (a -> b) -> IO a -> IO b
forall (f :: * -> *) a b. Applicative f => f (a -> b) -> f a -> f b
<*> Maybe (RetentionBackend CacheKey VersionRead)
-> IO (SingleFlight MetadataError CacheKey VersionRead)
forall k v e.
Maybe (RetentionBackend k v) -> IO (SingleFlight e k v)
newSingleFlightWithBackend (CacheProvider -> Maybe (RetentionBackend CacheKey VersionRead)
providerVersion CacheProvider
provider)
        IO (SingleFlight Void CacheKey ByteString -> MetadataCache)
-> IO (SingleFlight Void CacheKey ByteString) -> IO MetadataCache
forall a b. IO (a -> b) -> IO a -> IO b
forall (f :: * -> *) a b. Applicative f => f (a -> b) -> f a -> f b
<*> Maybe (RetentionBackend CacheKey ByteString)
-> IO (SingleFlight Void CacheKey ByteString)
forall k v e.
Maybe (RetentionBackend k v) -> IO (SingleFlight e k v)
newSingleFlightWithBackend (CacheProvider -> Maybe (RetentionBackend CacheKey ByteString)
providerAssembled CacheProvider
provider)

-- | Coalesce public metadata fetches. Failures reach all waiters and retain nothing.
resolveMetadata :: MetricsPort -> MetadataCache -> Source -> PackageName -> IO (Either MetadataError CacheEntry) -> IO (Either MetadataError CacheEntry)
resolveMetadata :: MetricsPort
-> MetadataCache
-> Source
-> PackageName
-> IO (Either MetadataError CacheEntry)
-> IO (Either MetadataError CacheEntry)
resolveMetadata MetricsPort
metrics MetadataCache
cache Source
source PackageName
name =
    (CacheResult -> IO ())
-> (CacheOccupancy -> IO ())
-> IO ()
-> SingleFlight MetadataError CacheKey CacheEntry
-> CacheKey
-> IO (Either MetadataError CacheEntry)
-> IO (Either MetadataError CacheEntry)
forall k e v.
Ord k =>
(CacheResult -> IO ())
-> (CacheOccupancy -> IO ())
-> IO ()
-> SingleFlight e k v
-> k
-> IO (Either e v)
-> IO (Either e v)
resolveSingleFlight
        (MetricsPort -> CacheResult -> IO ()
mpCacheRequest MetricsPort
metrics)
        (MetricsPort -> CacheOccupancy -> IO ()
recordFullOccupancy MetricsPort
metrics)
        (MetricsPort -> CacheStore -> IO ()
mpCacheRefused MetricsPort
metrics CacheStore
Metric.FullStore)
        (MetadataCache -> SingleFlight MetadataError CacheKey CacheEntry
mcFull MetadataCache
cache)
        (Source -> PackageName -> CacheKey
fullKey Source
source PackageName
name)

-- | Cache a selectively decoded release or its absence. Oversized releases remain uncached.
resolveVersion :: MetricsPort -> MetadataCache -> Source -> PackageName -> Version -> IO (Either MetadataError VersionRead) -> IO (Either MetadataError VersionRead)
resolveVersion :: MetricsPort
-> MetadataCache
-> Source
-> PackageName
-> Version
-> IO (Either MetadataError VersionRead)
-> IO (Either MetadataError VersionRead)
resolveVersion MetricsPort
metrics MetadataCache
cache Source
source PackageName
name Version
version IO (Either MetadataError VersionRead)
fetch =
    MetricsPort
-> MetadataCache
-> Source
-> PackageName
-> Version
-> IO (Either MetadataError VersionRead)
-> IO (PreparedStore MetadataError VersionRead)
prepareVersion MetricsPort
metrics MetadataCache
cache Source
source PackageName
name Version
version IO (Either MetadataError VersionRead)
fetch IO (PreparedStore MetadataError VersionRead)
-> (PreparedStore MetadataError VersionRead
    -> IO (Either MetadataError VersionRead))
-> IO (Either MetadataError VersionRead)
forall a b. IO a -> (a -> IO b) -> IO b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= PreparedStore MetadataError VersionRead
-> IO (Either MetadataError VersionRead)
forall e v. PreparedStore e v -> IO (Either e v)
executePrepared

-- | Pin a selected local value, including absence, before any remote work.
prepareVersion :: MetricsPort -> MetadataCache -> Source -> PackageName -> Version -> IO (Either MetadataError VersionRead) -> IO (PreparedStore MetadataError VersionRead)
prepareVersion :: MetricsPort
-> MetadataCache
-> Source
-> PackageName
-> Version
-> IO (Either MetadataError VersionRead)
-> IO (PreparedStore MetadataError VersionRead)
prepareVersion MetricsPort
metrics MetadataCache
cache Source
source PackageName
name Version
version =
    (CacheResult -> IO ())
-> (CacheOccupancy -> IO ())
-> IO ()
-> SingleFlight MetadataError CacheKey VersionRead
-> CacheKey
-> IO (Either MetadataError VersionRead)
-> IO (PreparedStore MetadataError VersionRead)
forall k e v.
Ord k =>
(CacheResult -> IO ())
-> (CacheOccupancy -> IO ())
-> IO ()
-> SingleFlight e k v
-> k
-> IO (Either e v)
-> IO (PreparedStore e v)
prepareStore
        (MetricsPort -> CacheResult -> IO ()
mpVersionCacheRequest MetricsPort
metrics)
        (MetricsPort -> Int -> IO ()
mpVersionCacheResidentBytes MetricsPort
metrics (Int -> IO ())
-> (CacheOccupancy -> Int) -> CacheOccupancy -> IO ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. CacheOccupancy -> Int
occBytes)
        (MetricsPort -> CacheStore -> IO ()
mpCacheRefused MetricsPort
metrics CacheStore
Metric.VersionStore)
        (MetadataCache -> SingleFlight MetadataError CacheKey VersionRead
mcVersion MetadataCache
cache)
        (Source -> PackageName -> Version -> CacheKey
versionKey Source
source PackageName
name Version
version)

-- | Memoise a response under a key that binds it to this request's authorised inputs.
resolveAssembled :: MetricsPort -> MetadataCache -> CacheKey -> IO ByteString -> IO ByteString
resolveAssembled :: MetricsPort
-> MetadataCache -> CacheKey -> IO ByteString -> IO ByteString
resolveAssembled MetricsPort
metrics MetadataCache
cache CacheKey
key IO ByteString
render =
    (Void -> ByteString)
-> (ByteString -> ByteString)
-> Either Void ByteString
-> ByteString
forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either Void -> ByteString
forall a. Void -> a
absurd ByteString -> ByteString
forall a. a -> a
id
        (Either Void ByteString -> ByteString)
-> IO (Either Void ByteString) -> IO ByteString
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> (CacheResult -> IO ())
-> (CacheOccupancy -> IO ())
-> IO ()
-> SingleFlight Void CacheKey ByteString
-> CacheKey
-> IO (Either Void ByteString)
-> IO (Either Void ByteString)
forall k e v.
Ord k =>
(CacheResult -> IO ())
-> (CacheOccupancy -> IO ())
-> IO ()
-> SingleFlight e k v
-> k
-> IO (Either e v)
-> IO (Either e v)
resolveSingleFlight
            (MetricsPort -> CacheResult -> IO ()
mpAssembledCacheRequest MetricsPort
metrics)
            (MetricsPort -> Int -> IO ()
mpAssembledCacheResidentBytes MetricsPort
metrics (Int -> IO ())
-> (CacheOccupancy -> Int) -> CacheOccupancy -> IO ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. CacheOccupancy -> Int
occBytes)
            (MetricsPort -> CacheStore -> IO ()
mpCacheRefused MetricsPort
metrics CacheStore
Metric.AssembledStore)
            (MetadataCache -> SingleFlight Void CacheKey ByteString
mcAssembled MetadataCache
cache)
            CacheKey
key
            (ByteString -> Either Void ByteString
forall a b. b -> Either a b
Right (ByteString -> Either Void ByteString)
-> IO ByteString -> IO (Either Void ByteString)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> IO ByteString
render)

recordFullOccupancy :: MetricsPort -> CacheOccupancy -> IO ()
recordFullOccupancy :: MetricsPort -> CacheOccupancy -> IO ()
recordFullOccupancy MetricsPort
metrics CacheOccupancy
occ = do
    MetricsPort -> Int -> IO ()
mpCacheEntries MetricsPort
metrics (CacheOccupancy -> Int
occEntries CacheOccupancy
occ)
    MetricsPort -> Int -> IO ()
mpCacheResidentBytes MetricsPort
metrics (CacheOccupancy -> Int
occBytes CacheOccupancy
occ)

-- | Refresh one public directory per origin and share active acquisitions.
resolveDirectory :: MetricsPort -> MetadataCache -> CacheKey -> IO (Either MetadataError GemDirectory) -> IO (Either MetadataError GemDirectory)
resolveDirectory :: MetricsPort
-> MetadataCache
-> CacheKey
-> IO (Either MetadataError GemDirectory)
-> IO (Either MetadataError GemDirectory)
resolveDirectory MetricsPort
metrics MetadataCache
cache CacheKey
key IO (Either MetadataError GemDirectory)
fetch =
    ((GemDirectory, Int) -> GemDirectory)
-> Either MetadataError (GemDirectory, Int)
-> Either MetadataError GemDirectory
forall a b.
(a -> b) -> Either MetadataError a -> Either MetadataError b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (GemDirectory, Int) -> GemDirectory
forall a b. (a, b) -> a
fst
        (Either MetadataError (GemDirectory, Int)
 -> Either MetadataError GemDirectory)
-> IO (Either MetadataError (GemDirectory, Int))
-> IO (Either MetadataError GemDirectory)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> (CacheResult -> IO ())
-> (CacheOccupancy -> IO ())
-> IO ()
-> SingleFlight MetadataError CacheKey (GemDirectory, Int)
-> CacheKey
-> IO (Either MetadataError (GemDirectory, Int))
-> IO (Either MetadataError (GemDirectory, Int))
forall k e v.
Ord k =>
(CacheResult -> IO ())
-> (CacheOccupancy -> IO ())
-> IO ()
-> SingleFlight e k v
-> k
-> IO (Either e v)
-> IO (Either e v)
resolveSingleFlight
            (MetricsPort -> CacheResult -> IO ()
mpDirectoryCacheRequest MetricsPort
metrics)
            (MetricsPort -> Int -> IO ()
mpDirectoryCacheResidentBytes MetricsPort
metrics (Int -> IO ())
-> (CacheOccupancy -> Int) -> CacheOccupancy -> IO ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. CacheOccupancy -> Int
occBytes)
            (MetricsPort -> CacheStore -> IO ()
mpCacheRefused MetricsPort
metrics CacheStore
Metric.DirectoryStore)
            (MetadataCache
-> SingleFlight MetadataError CacheKey (GemDirectory, Int)
mcDirectory MetadataCache
cache)
            CacheKey
key
            ((Either MetadataError GemDirectory
 -> Either MetadataError (GemDirectory, Int))
-> IO (Either MetadataError GemDirectory)
-> IO (Either MetadataError (GemDirectory, Int))
forall a b. (a -> b) -> IO a -> IO b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ((GemDirectory -> (GemDirectory, Int))
-> Either MetadataError GemDirectory
-> Either MetadataError (GemDirectory, Int)
forall a b.
(a -> b) -> Either MetadataError a -> Either MetadataError b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (,ShortByteString -> Int
SBS.length (CacheKey -> ShortByteString
cacheKeyIdentity CacheKey
key) Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Int
256)) IO (Either MetadataError GemDirectory)
fetch)