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

{- | Bounded overflow ahead of the metadata gates. Each request keeps its permit and arrival
order through retries. Gate signals and sweeper ticks wake requests without request timers.
-}
module Ecluse.Core.Server.Admission.Overflow (
    -- * A gate's line
    Line,
    newLine,
    signalLine,

    -- * The queue
    Overflow,
    newOverflow,
    newOverflowTuned,
    overflowWaiting,

    -- * Waiting for a place
    Attempt (..),
    attemptAfter,
    Waited (..),
    awaitPlace,
) where

import Control.Concurrent.STM (check, orElse)
import Data.Map.Strict qualified as Map
import GHC.Clock (getMonotonicTimeNSec)
import UnliftIO.Exception (finally, mask)

import Ecluse.Core.Deadline (Check, Deadlines, withDeadline, withDeadlineFlag)
import Ecluse.Core.Server.Admission.Types (Shed (..))
import Ecluse.Core.Telemetry.Record (MetricsPort (..))

-- | Requests one gate turned away, oldest first. Equality identifies the gate of a final refusal.
data Line = Line (TVar (Map Integer (TVar Bool))) (TVar Word64)
    deriving stock (Line -> Line -> Bool
(Line -> Line -> Bool) -> (Line -> Line -> Bool) -> Eq Line
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: Line -> Line -> Bool
== :: Line -> Line -> Bool
$c/= :: Line -> Line -> Bool
/= :: Line -> Line -> Bool
Eq)

-- | An empty gate line, with one periodic wake allowed per sweep.
newLine :: IO Line
newLine :: IO Line
newLine = TVar (Map Integer (TVar Bool)) -> TVar Word64 -> Line
Line (TVar (Map Integer (TVar Bool)) -> TVar Word64 -> Line)
-> IO (TVar (Map Integer (TVar Bool))) -> IO (TVar Word64 -> Line)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Map Integer (TVar Bool) -> IO (TVar (Map Integer (TVar Bool)))
forall (m :: * -> *) a. MonadIO m => a -> m (TVar a)
newTVarIO Map Integer (TVar Bool)
forall k a. Map k a
Map.empty IO (TVar Word64 -> Line) -> IO (TVar Word64) -> IO Line
forall a b. IO (a -> b) -> IO a -> IO b
forall (f :: * -> *) a b. Applicative f => f (a -> b) -> f a -> f b
<*> Word64 -> IO (TVar Word64)
forall (m :: * -> *) a. MonadIO m => a -> m (TVar a)
newTVarIO Word64
0

-- | Wake the oldest request on the line. A gate runs it in the transaction that frees a place.
signalLine :: Line -> STM ()
signalLine :: Line -> STM ()
signalLine (Line TVar (Map Integer (TVar Bool))
entries TVar Word64
_) =
    TVar (Map Integer (TVar Bool)) -> STM (Map Integer (TVar Bool))
forall a. TVar a -> STM a
readTVar TVar (Map Integer (TVar Bool))
entries STM (Map Integer (TVar Bool))
-> (Map Integer (TVar Bool) -> STM ()) -> STM ()
forall a b. STM a -> (a -> STM b) -> STM b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \Map Integer (TVar Bool)
queue -> case Map Integer (TVar Bool)
-> Maybe (TVar Bool, Map Integer (TVar Bool))
forall k a. Map k a -> Maybe (a, Map k a)
Map.minView Map Integer (TVar Bool)
queue of
        Maybe (TVar Bool, Map Integer (TVar Bool))
Nothing -> STM ()
forall (f :: * -> *). Applicative f => f ()
pass
        Just (TVar Bool
oldest, Map Integer (TVar Bool)
rest) -> TVar (Map Integer (TVar Bool)) -> Map Integer (TVar Bool) -> STM ()
forall a. TVar a -> a -> STM ()
writeTVar TVar (Map Integer (TVar Bool))
entries Map Integer (TVar Bool)
rest STM () -> STM () -> STM ()
forall a b. STM a -> STM b -> STM b
forall (m :: * -> *) a b. Monad m => m a -> m b -> m b
>> TVar Bool -> Bool -> STM ()
forall a. TVar a -> a -> STM ()
writeTVar TVar Bool
oldest Bool
True

-- | The queue in front of both gates: how many requests wait, how many may, and for how long.
data Overflow = Overflow
    { Overflow -> Deadlines
ovDeadlines :: Deadlines
    , Overflow -> TVar Int
ovWaiting :: TVar Int
    , Overflow -> TVar Int
ovReserved :: TVar Int
    , Overflow -> TVar Integer
ovNext :: TVar Integer
    , Overflow -> Int
ovCap :: Int
    , Overflow -> Int
ovWaitMicros :: Int
    }

-- | A queue for the serve slots: eight places for each, and a 0.5 s wait. The deadlines must be swept.
newOverflow :: Deadlines -> Int -> IO Overflow
newOverflow :: Deadlines -> Int -> IO Overflow
newOverflow Deadlines
deadlines Int
slots = Deadlines -> Int -> Int -> IO Overflow
newOverflowTuned Deadlines
deadlines (Int
8 Int -> Int -> Int
forall a. Num a => a -> a -> a
* Int -> Int -> Int
forall a. Ord a => a -> a -> a
max Int
1 Int
slots) Int
500_000

-- | Set the cap and the microsecond wait explicitly. Both floor at zero.
newOverflowTuned :: Deadlines -> Int -> Int -> IO Overflow
newOverflowTuned :: Deadlines -> Int -> Int -> IO Overflow
newOverflowTuned Deadlines
deadlines Int
cap Int
waitMicros = do
    waiting <- Int -> IO (TVar Int)
forall (m :: * -> *) a. MonadIO m => a -> m (TVar a)
newTVarIO Int
0
    reserved <- newTVarIO 0
    next <- newTVarIO 0
    pure Overflow{ovDeadlines = deadlines, ovWaiting = waiting, ovReserved = reserved, ovNext = next, ovCap = max 0 cap, ovWaitMicros = max 0 waitMicros}

-- | Requests parked on the gate lines, excluding retries and admitted callbacks.
overflowWaiting :: Overflow -> IO Int
overflowWaiting :: Overflow -> IO Int
overflowWaiting = TVar Int -> IO Int
forall (m :: * -> *) a. MonadIO m => TVar a -> m a
readTVarIO (TVar Int -> IO Int)
-> (Overflow -> TVar Int) -> Overflow -> IO Int
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Overflow -> TVar Int
ovWaiting

-- | What one try at the gates came to.
data Attempt a
    = -- | It got a place, and its action ran.
      Entered a
    | -- | A gate's room was full, so the request waits on that gate's line.
      TurnedAway Line
    | -- | It took a room place, and the room's wait ran out first.
      Expired Line

-- | Read a gate's answer, where the line is that gate's.
attemptAfter :: Line -> Either Shed a -> Attempt a
attemptAfter :: forall a. Line -> Either Shed a -> Attempt a
attemptAfter Line
line = \case
    Right a
result -> a -> Attempt a
forall a. a -> Attempt a
Entered a
result
    Left Shed
RoomFull -> Line -> Attempt a
forall a. Line -> Attempt a
TurnedAway Line
line
    Left Shed
WaitExpired -> Line -> Attempt a
forall a. Line -> Attempt a
Expired Line
line

-- | How a queued request ended.
data Waited a
    = -- | It got a place after waiting, and its action ran.
      Placed a
    | -- | No place freed within the wait, or the room it reached ran out of time.
      WaitedOut Line
    | -- | The queue already held its cap, so the request never joined it.
      QueueFull Line

{- | Queue a request the gate behind the line turned away, and run @try@ each time it wakes, until it
gets a place or the wait runs out. Past the cap it answers 'QueueFull' at once.
-}
awaitPlace :: MetricsPort -> Overflow -> Line -> IO (Attempt a) -> IO (Waited a)
awaitPlace :: forall a.
MetricsPort -> Overflow -> Line -> IO (Attempt a) -> IO (Waited a)
awaitPlace MetricsPort
metrics Overflow
overflow Line
line IO (Attempt a)
try = ((forall a. IO a -> IO a) -> IO (Waited a)) -> IO (Waited a)
forall (m :: * -> *) b.
MonadUnliftIO m =>
((forall a. m a -> m a) -> m b) -> m b
mask (((forall a. IO a -> IO a) -> IO (Waited a)) -> IO (Waited a))
-> ((forall a. IO a -> IO a) -> IO (Waited a)) -> IO (Waited a)
forall a b. (a -> b) -> a -> b
$ \forall a. IO a -> IO a
restore -> do
    start <- IO Word64
getMonotonicTimeNSec
    entry <- newTVarIO False
    joined <- atomically $ do
        reserved <- readTVar (ovReserved overflow)
        if reserved >= ovCap overflow
            then pure Nothing
            else do
                age <- readTVar (ovNext overflow)
                writeTVar (ovNext overflow) (age + 1)
                writeTVar (ovReserved overflow) (reserved + 1)
                modifyTVar' (ovWaiting overflow) (+ 1)
                insertLine line age entry
                pure (Just age)
    let remaining = (\Word64
now -> Overflow -> Int
ovWaitMicros Overflow
overflow Int -> Int -> Int
forall a. Num a => a -> a -> a
- Word64 -> Int
forall a b. (Integral a, Num b) => a -> b
fromIntegral ((Word64
now Word64 -> Word64 -> Word64
forall a. Num a => a -> a -> a
- Word64
start) Word64 -> Word64 -> Word64
forall a. Integral a => a -> a -> a
`div` Word64
1_000)) (Word64 -> Int) -> IO Word64 -> IO Int
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> IO Word64
getMonotonicTimeNSec
        shed Line
waitingOn = MetricsPort -> IO ()
mpOverflowShed MetricsPort
metrics IO () -> Waited a -> IO (Waited a)
forall (f :: * -> *) a b. Functor f => f a -> b -> f b
$> Line -> Waited a
forall a. Line -> Waited a
WaitedOut Line
waitingOn
        queued Integer
age Line
waitingOn TVar Bool
waiting = do
            micros <- IO Int
remaining
            woken <- waitInLine overflow waitingOn age waiting micros
            left <- remaining
            if not woken || left <= 0
                then do
                    when woken (atomically (signalLine waitingOn))
                    shed waitingOn
                else
                    restore try >>= \case
                        Entered a
result -> MetricsPort -> IO ()
mpOverflowAdmitted MetricsPort
metrics IO () -> Waited a -> IO (Waited a)
forall (f :: * -> *) a b. Functor f => f a -> b -> f b
$> a -> Waited a
forall a. a -> Waited a
Placed a
result
                        Expired Line
refusedAt -> MetricsPort -> IO ()
mpOverflowAdmitted MetricsPort
metrics IO () -> Waited a -> IO (Waited a)
forall (f :: * -> *) a b. Functor f => f a -> b -> f b
$> Line -> Waited a
forall a. Line -> Waited a
WaitedOut Line
refusedAt
                        TurnedAway Line
next -> do
                            leftAfterTry <- IO Int
remaining
                            if leftAfterTry <= 0
                                then shed next
                                else do
                                    fresh <- newTVarIO False
                                    atomically (modifyTVar' (ovWaiting overflow) (+ 1) >> insertLine next age fresh)
                                    queued age next fresh
    case joined of
        Maybe Integer
Nothing -> MetricsPort -> IO ()
mpOverflowFull MetricsPort
metrics IO () -> Waited a -> IO (Waited a)
forall (f :: * -> *) a b. Functor f => f a -> b -> f b
$> Line -> Waited a
forall a. Line -> Waited a
QueueFull Line
line
        Just Integer
age -> Integer -> Line -> TVar Bool -> IO (Waited a)
queued Integer
age Line
line TVar Bool
entry IO (Waited a) -> IO () -> IO (Waited a)
forall (m :: * -> *) a b. MonadUnliftIO m => m a -> m b -> m a
`finally` STM () -> IO ()
forall (m :: * -> *) a. MonadIO m => STM a -> m a
atomically (TVar Int -> (Int -> Int) -> STM ()
forall a. TVar a -> (a -> a) -> STM ()
modifyTVar' (Overflow -> TVar Int
ovReserved Overflow
overflow) (Int -> Int -> Int
forall a. Num a => a -> a -> a
subtract Int
1))

-- Line membership ends before retrying. The permit survives until the whole request exits.
waitInLine :: Overflow -> Line -> Integer -> TVar Bool -> Int -> IO Bool
waitInLine :: Overflow -> Line -> Integer -> TVar Bool -> Int -> IO Bool
waitInLine Overflow
overflow Line
line Integer
age TVar Bool
entry Int
micros =
    Deadlines -> Int -> (TVar Bool -> IO Bool) -> IO Bool
forall a. Deadlines -> Int -> (TVar Bool -> IO a) -> IO a
withDeadlineFlag (Overflow -> Deadlines
ovDeadlines Overflow
overflow) Int
micros TVar Bool -> IO Bool
wait
        IO Bool -> IO () -> IO Bool
forall (m :: * -> *) a b. MonadUnliftIO m => m a -> m b -> m a
`finally` STM () -> IO ()
forall (m :: * -> *) a. MonadIO m => STM a -> m a
atomically (Line -> Integer -> TVar Bool -> STM ()
leaveLine Line
line Integer
age TVar Bool
entry STM () -> STM () -> STM ()
forall a b. STM a -> STM b -> STM b
forall (m :: * -> *) a b. Monad m => m a -> m b -> m b
>> TVar Int -> (Int -> Int) -> STM ()
forall a. TVar a -> (a -> a) -> STM ()
modifyTVar' (Overflow -> TVar Int
ovWaiting Overflow
overflow) (Int -> Int -> Int
forall a. Num a => a -> a -> a
subtract Int
1))
  where
    wait :: TVar Bool -> IO Bool
wait TVar Bool
due = Deadlines -> Check -> IO Bool -> IO Bool
forall a. Deadlines -> Check -> IO a -> IO a
withDeadline (Overflow -> Deadlines
ovDeadlines Overflow
overflow) (Line -> Integer -> Check
wakeIfOldest Line
line Integer
age) (IO Bool -> IO Bool) -> IO Bool -> IO Bool
forall a b. (a -> b) -> a -> b
$ do
        woken <- STM Bool -> IO Bool
forall (m :: * -> *) a. MonadIO m => STM a -> m a
atomically (TVar Bool -> TVar Bool -> STM Bool
wokenOrDue TVar Bool
entry TVar Bool
due)
        when woken (atomically (writeTVar entry False))
        pure woken

wokenOrDue :: TVar Bool -> TVar Bool -> STM Bool
wokenOrDue :: TVar Bool -> TVar Bool -> STM Bool
wokenOrDue TVar Bool
entry TVar Bool
due = ((TVar Bool -> STM Bool
forall a. TVar a -> STM a
readTVar TVar Bool
due STM Bool -> (Bool -> STM ()) -> STM ()
forall a b. STM a -> (a -> STM b) -> STM b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= Bool -> STM ()
check) STM () -> Bool -> STM Bool
forall (f :: * -> *) a b. Functor f => f a -> b -> f b
$> Bool
False) STM Bool -> STM Bool -> STM Bool
forall a. STM a -> STM a -> STM a
`orElse` ((TVar Bool -> STM Bool
forall a. TVar a -> STM a
readTVar TVar Bool
entry STM Bool -> (Bool -> STM ()) -> STM ()
forall a b. STM a -> (a -> STM b) -> STM b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= Bool -> STM ()
check) STM () -> Bool -> STM Bool
forall (f :: * -> *) a b. Functor f => f a -> b -> f b
$> Bool
True)

insertLine :: Line -> Integer -> TVar Bool -> STM ()
insertLine :: Line -> Integer -> TVar Bool -> STM ()
insertLine (Line TVar (Map Integer (TVar Bool))
entries TVar Word64
_) Integer
age TVar Bool
entry = TVar (Map Integer (TVar Bool))
-> (Map Integer (TVar Bool) -> Map Integer (TVar Bool)) -> STM ()
forall a. TVar a -> (a -> a) -> STM ()
modifyTVar' TVar (Map Integer (TVar Bool))
entries (Integer
-> TVar Bool -> Map Integer (TVar Bool) -> Map Integer (TVar Bool)
forall k a. Ord k => k -> a -> Map k a -> Map k a
Map.insert Integer
age TVar Bool
entry)

-- A late wake passes on when cancellation or expiry removes its recipient.
leaveLine :: Line -> Integer -> TVar Bool -> STM ()
leaveLine :: Line -> Integer -> TVar Bool -> STM ()
leaveLine line :: Line
line@(Line TVar (Map Integer (TVar Bool))
entries TVar Word64
_) Integer
age TVar Bool
entry = do
    woken <- TVar Bool -> STM Bool
forall a. TVar a -> STM a
readTVar TVar Bool
entry
    modifyTVar' entries (Map.delete age)
    when woken (signalLine line)

wakeIfOldest :: Line -> Integer -> Check
wakeIfOldest :: Line -> Integer -> Check
wakeIfOldest line :: Line
line@(Line TVar (Map Integer (TVar Bool))
entries TVar Word64
lastSweep) Integer
age Word64
now = do
    STM () -> IO ()
forall (m :: * -> *) a. MonadIO m => STM a -> m a
atomically (STM () -> IO ()) -> STM () -> IO ()
forall a b. (a -> b) -> a -> b
$ do
        queue <- TVar (Map Integer (TVar Bool)) -> STM (Map Integer (TVar Bool))
forall a. TVar a -> STM a
readTVar TVar (Map Integer (TVar Bool))
entries
        previous <- readTVar lastSweep
        when (previous /= now && fmap fst (Map.lookupMin queue) == Just age) $ do
            writeTVar lastSweep now
            signalLine line
    Maybe SomeException -> IO (Maybe SomeException)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure Maybe SomeException
forall a. Maybe a
Nothing