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

{- | Artifact relays with bounded memory and upstream backpressure.
The connection stays open until the responder finishes. The progress floor
counts upstream waits, excluding time spent waiting for the client.
-}
module Ecluse.Core.Server.Stream (
    -- * A typed relay responder
    RelayResponder (..),

    -- * Relaying an upstream response through
    UpstreamBody (..),
    UpstreamResult (..),
    withUpstreamResult,
    withUpstreamResultUsing,
    UpstreamBodyFailed (..),

    -- * The pump
    pumpBody,
) where

import Data.ByteString qualified as BS
import Data.ByteString.Builder (Builder, byteString)
import Network.HTTP.Client (BodyReader, Request, brRead, responseClose, responseHeaders, responseStatus)
import Network.HTTP.Client qualified as HTTP
import Network.HTTP.Types (ResponseHeaders, Status)
import Network.Wai (StreamingBody)
import UnliftIO.Exception (finally, mask, throwIO, try, tryAny)

import Ecluse.Core.Fault (RetryAfter, TransportFault, renderTransportFault)
import Ecluse.Core.Fault.Http (classifyTransport)
import Ecluse.Core.Fault.RetryAfter (responseRetryAfter)
import Ecluse.Core.Registry (FetchFault (FetchCooldown))
import Ecluse.Core.Registry.Exchange.Types (ExchangeClient (ecDeadlines))
import Ecluse.Core.Registry.Progress (meteredReader, watchedRaising)
import Ecluse.Core.Registry.Public (ReadControl (Uncontrolled), withReadControl)
import Ecluse.Core.Registry.ResponseWait (openResponse)
import Ecluse.Core.Security (ProgressFloor)
import Ecluse.Core.Server.Conditional (isNotModified)

-- | Route-scoped responders that keep WAI response construction at the caller.
data RelayResponder response = RelayResponder
    { forall response.
RelayResponder response
-> Status -> ResponseHeaders -> StreamingBody -> IO response
relayStreamResponse :: Status -> ResponseHeaders -> StreamingBody -> IO response
    -- ^ Commit a status, headers, and bounded-memory streaming body.
    , forall response.
RelayResponder response -> Status -> ResponseHeaders -> IO response
relayEmptyResponse :: Status -> ResponseHeaders -> IO response
    -- ^ Commit the same response without a body (a @304@ or @HEAD@).
    }

-- | Whether a relay pumps the upstream body through, or answers bodiless.
data UpstreamBody
    = -- | Stream the body, except for a bodiless @304@.
      StreamBody
    | -- | Never read the upstream body, including for @HEAD@.
      NoBody
    deriving stock (UpstreamBody -> UpstreamBody -> Bool
(UpstreamBody -> UpstreamBody -> Bool)
-> (UpstreamBody -> UpstreamBody -> Bool) -> Eq UpstreamBody
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: UpstreamBody -> UpstreamBody -> Bool
== :: UpstreamBody -> UpstreamBody -> Bool
$c/= :: UpstreamBody -> UpstreamBody -> Bool
/= :: UpstreamBody -> UpstreamBody -> Bool
Eq, Int -> UpstreamBody -> ShowS
[UpstreamBody] -> ShowS
UpstreamBody -> String
(Int -> UpstreamBody -> ShowS)
-> (UpstreamBody -> String)
-> ([UpstreamBody] -> ShowS)
-> Show UpstreamBody
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> UpstreamBody -> ShowS
showsPrec :: Int -> UpstreamBody -> ShowS
$cshow :: UpstreamBody -> String
show :: UpstreamBody -> String
$cshowList :: [UpstreamBody] -> ShowS
showList :: [UpstreamBody] -> ShowS
Show)

-- | A committed relay, or the reason no response was committed.
data UpstreamResult a
    = -- | The responder finished, including any body streaming.
      UpstreamRelayed a
    | -- | The upstream answered a status the caller did not accept, with any delay its @Retry-After@ asked for.
      UpstreamRejected Status (Maybe RetryAfter)
    | -- | The upstream connection failed before a response was available.
      UpstreamTransportFailure
    | -- | Public admission refused the exchange before opening a connection.
      UpstreamCooling RetryAfter
    deriving stock (UpstreamResult a -> UpstreamResult a -> Bool
(UpstreamResult a -> UpstreamResult a -> Bool)
-> (UpstreamResult a -> UpstreamResult a -> Bool)
-> Eq (UpstreamResult a)
forall a. Eq a => UpstreamResult a -> UpstreamResult a -> Bool
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: forall a. Eq a => UpstreamResult a -> UpstreamResult a -> Bool
== :: UpstreamResult a -> UpstreamResult a -> Bool
$c/= :: forall a. Eq a => UpstreamResult a -> UpstreamResult a -> Bool
/= :: UpstreamResult a -> UpstreamResult a -> Bool
Eq, Int -> UpstreamResult a -> ShowS
[UpstreamResult a] -> ShowS
UpstreamResult a -> String
(Int -> UpstreamResult a -> ShowS)
-> (UpstreamResult a -> String)
-> ([UpstreamResult a] -> ShowS)
-> Show (UpstreamResult a)
forall a. Show a => Int -> UpstreamResult a -> ShowS
forall a. Show a => [UpstreamResult a] -> ShowS
forall a. Show a => UpstreamResult a -> String
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: forall a. Show a => Int -> UpstreamResult a -> ShowS
showsPrec :: Int -> UpstreamResult a -> ShowS
$cshow :: forall a. Show a => UpstreamResult a -> String
show :: UpstreamResult a -> String
$cshowList :: forall a. Show a => [UpstreamResult a] -> ShowS
showList :: [UpstreamResult a] -> ShowS
Show)

-- | A body failure after response commitment requires closing the client connection. The fault never includes the upstream request.
newtype UpstreamBodyFailed = UpstreamBodyFailed TransportFault
    deriving stock (UpstreamBodyFailed -> UpstreamBodyFailed -> Bool
(UpstreamBodyFailed -> UpstreamBodyFailed -> Bool)
-> (UpstreamBodyFailed -> UpstreamBodyFailed -> Bool)
-> Eq UpstreamBodyFailed
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: UpstreamBodyFailed -> UpstreamBodyFailed -> Bool
== :: UpstreamBodyFailed -> UpstreamBodyFailed -> Bool
$c/= :: UpstreamBodyFailed -> UpstreamBodyFailed -> Bool
/= :: UpstreamBodyFailed -> UpstreamBodyFailed -> Bool
Eq, Int -> UpstreamBodyFailed -> ShowS
[UpstreamBodyFailed] -> ShowS
UpstreamBodyFailed -> String
(Int -> UpstreamBodyFailed -> ShowS)
-> (UpstreamBodyFailed -> String)
-> ([UpstreamBodyFailed] -> ShowS)
-> Show UpstreamBodyFailed
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> UpstreamBodyFailed -> ShowS
showsPrec :: Int -> UpstreamBodyFailed -> ShowS
$cshow :: UpstreamBodyFailed -> String
show :: UpstreamBodyFailed -> String
$cshowList :: [UpstreamBodyFailed] -> ShowS
showList :: [UpstreamBodyFailed] -> ShowS
Show)

instance Exception UpstreamBodyFailed where
    displayException :: UpstreamBodyFailed -> String
displayException (UpstreamBodyFailed TransportFault
fault) = Text -> String
forall a. ToString a => a -> String
toString (Text
"the upstream body failed after the response was committed: " Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> TransportFault -> Text
renderTransportFault TransportFault
fault)

-- | Relay accepted responses, preserving pre-commit misses and propagating failures after the commit.
withUpstreamResult ::
    ExchangeClient ->
    ProgressFloor ->
    Request ->
    UpstreamBody ->
    (Status -> Bool) ->
    (Status -> ResponseHeaders -> IO (Status, ResponseHeaders, verdict)) ->
    RelayResponder response ->
    IO (UpstreamResult (verdict, response))
withUpstreamResult :: forall verdict response.
ExchangeClient
-> ProgressFloor
-> Request
-> UpstreamBody
-> (Status -> Bool)
-> (Status
    -> ResponseHeaders -> IO (Status, ResponseHeaders, verdict))
-> RelayResponder response
-> IO (UpstreamResult (verdict, response))
withUpstreamResult = ReadControl
-> ExchangeClient
-> ProgressFloor
-> Request
-> UpstreamBody
-> (Status -> Bool)
-> (Status
    -> ResponseHeaders -> IO (Status, ResponseHeaders, verdict))
-> RelayResponder response
-> IO (UpstreamResult (verdict, response))
forall verdict response.
ReadControl
-> ExchangeClient
-> ProgressFloor
-> Request
-> UpstreamBody
-> (Status -> Bool)
-> (Status
    -> ResponseHeaders -> IO (Status, ResponseHeaders, verdict))
-> RelayResponder response
-> IO (UpstreamResult (verdict, response))
withUpstreamResultUsing ReadControl
Uncontrolled

-- | Apply public admission and observation while retaining response ownership through the responder.
withUpstreamResultUsing :: ReadControl -> ExchangeClient -> ProgressFloor -> Request -> UpstreamBody -> (Status -> Bool) -> (Status -> ResponseHeaders -> IO (Status, ResponseHeaders, verdict)) -> RelayResponder response -> IO (UpstreamResult (verdict, response))
withUpstreamResultUsing :: forall verdict response.
ReadControl
-> ExchangeClient
-> ProgressFloor
-> Request
-> UpstreamBody
-> (Status -> Bool)
-> (Status
    -> ResponseHeaders -> IO (Status, ResponseHeaders, verdict))
-> RelayResponder response
-> IO (UpstreamResult (verdict, response))
withUpstreamResultUsing ReadControl
control ExchangeClient
client ProgressFloor
progress Request
request UpstreamBody
body Status -> Bool
accept Status -> ResponseHeaders -> IO (Status, ResponseHeaders, verdict)
relay RelayResponder response
respond = do
    opened <- Bool -> IO (IORef Bool)
forall (m :: * -> *) a. MonadIO m => a -> m (IORef a)
newIORef Bool
False
    result <- tryAny $ withReadControl control request $ \Request
observed Status -> ResponseHeaders -> IO (Maybe RetryAfter)
recordHeaders ->
        ((forall a. IO a -> IO a)
 -> IO (UpstreamResult (verdict, response)))
-> IO (UpstreamResult (verdict, response))
forall (m :: * -> *) b.
MonadUnliftIO m =>
((forall a. m a -> m a) -> m b) -> m b
mask (((forall a. IO a -> IO a)
  -> IO (UpstreamResult (verdict, response)))
 -> IO (UpstreamResult (verdict, response)))
-> ((forall a. IO a -> IO a)
    -> IO (UpstreamResult (verdict, response)))
-> IO (UpstreamResult (verdict, response))
forall a b. (a -> b) -> a -> b
$ \forall a. IO a -> IO a
restore -> do
            upstream <- ExchangeClient -> Request -> IO (Response BodyReader)
openResponse ExchangeClient
client Request
observed
            writeIORef opened True
            restore (recordHeaders (responseStatus upstream) (responseHeaders upstream) >> answer upstream) `finally` responseClose upstream
    case result of
        Left SomeException
fault -> IORef Bool -> IO Bool
forall (m :: * -> *) a. MonadIO m => IORef a -> m a
readIORef IORef Bool
opened IO Bool
-> (Bool -> IO (UpstreamResult (verdict, response)))
-> IO (UpstreamResult (verdict, response))
forall a b. IO a -> (a -> IO b) -> IO b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \Bool
hasResponse -> if Bool
hasResponse then SomeException -> IO (UpstreamResult (verdict, response))
forall (m :: * -> *) e a. (MonadIO m, Exception e) => e -> m a
throwIO SomeException
fault else UpstreamResult (verdict, response)
-> IO (UpstreamResult (verdict, response))
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure UpstreamResult (verdict, response)
forall a. UpstreamResult a
UpstreamTransportFailure
        Right (Left (FetchCooldown RetryAfter
retry)) -> UpstreamResult (verdict, response)
-> IO (UpstreamResult (verdict, response))
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (RetryAfter -> UpstreamResult (verdict, response)
forall a. RetryAfter -> UpstreamResult a
UpstreamCooling RetryAfter
retry)
        Right (Left FetchFault
_) -> UpstreamResult (verdict, response)
-> IO (UpstreamResult (verdict, response))
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure UpstreamResult (verdict, response)
forall a. UpstreamResult a
UpstreamTransportFailure
        Right (Right UpstreamResult (verdict, response)
received) -> UpstreamResult (verdict, response)
-> IO (UpstreamResult (verdict, response))
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure UpstreamResult (verdict, response)
received
  where
    answer :: Response BodyReader -> IO (UpstreamResult (verdict, response))
answer Response BodyReader
upstream
        | Bool -> Bool
not (Status -> Bool
accept Status
upstreamStatus) = Status -> Maybe RetryAfter -> UpstreamResult (verdict, response)
forall a. Status -> Maybe RetryAfter -> UpstreamResult a
UpstreamRejected Status
upstreamStatus (Maybe RetryAfter -> UpstreamResult (verdict, response))
-> IO (Maybe RetryAfter) -> IO (UpstreamResult (verdict, response))
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> ResponseHeaders -> IO (Maybe RetryAfter)
responseRetryAfter (Response BodyReader -> ResponseHeaders
forall body. Response body -> ResponseHeaders
responseHeaders Response BodyReader
upstream)
        | Bool
otherwise = do
            (status, headers, verdict) <- Status -> ResponseHeaders -> IO (Status, ResponseHeaders, verdict)
relay Status
upstreamStatus (Response BodyReader -> ResponseHeaders
forall body. Response body -> ResponseHeaders
responseHeaders Response BodyReader
upstream)
            received <-
                if bodiless
                    then relayEmptyResponse respond status headers
                    else relayStreamResponse respond status headers pump
            pure (UpstreamRelayed (verdict, received))
      where
        upstreamStatus :: Status
upstreamStatus = Response BodyReader -> Status
forall body. Response body -> Status
responseStatus Response BodyReader
upstream
        bodiless :: Bool
bodiless = UpstreamBody
body UpstreamBody -> UpstreamBody -> Bool
forall a. Eq a => a -> a -> Bool
== UpstreamBody
NoBody Bool -> Bool -> Bool
|| Status -> Bool
isNotModified Status
upstreamStatus
        -- A body read fails with the upstream request inside, so the fault is typed before it leaves.
        pump :: StreamingBody
pump Builder -> IO ()
write IO ()
flush =
            IO () -> IO (Either HttpException ())
forall (m :: * -> *) e a.
(MonadUnliftIO m, Exception e) =>
m a -> m (Either e a)
try (Deadlines -> ProgressFloor -> (Watch -> IO ()) -> IO ()
forall a. Deadlines -> ProgressFloor -> (Watch -> IO a) -> IO a
watchedRaising (ExchangeClient -> Deadlines
ecDeadlines ExchangeClient
client) ProgressFloor
progress (\Watch
watch -> BodyReader -> StreamingBody
pumpBody (Watch -> BodyReader -> BodyReader
meteredReader Watch
watch (BodyReader -> BodyReader
brRead (Response BodyReader -> BodyReader
forall body. Response body -> body
HTTP.responseBody Response BodyReader
upstream))) Builder -> IO ()
write IO ()
flush))
                IO (Either HttpException ())
-> (Either HttpException () -> IO ()) -> IO ()
forall a b. IO a -> (a -> IO b) -> IO b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= (HttpException -> IO ())
-> (() -> IO ()) -> Either HttpException () -> IO ()
forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either (UpstreamBodyFailed -> IO ()
forall (m :: * -> *) e a. (MonadIO m, Exception e) => e -> m a
throwIO (UpstreamBodyFailed -> IO ())
-> (HttpException -> UpstreamBodyFailed) -> HttpException -> IO ()
forall b c a. (b -> c) -> (a -> b) -> a -> c
. TransportFault -> UpstreamBodyFailed
UpstreamBodyFailed (TransportFault -> UpstreamBodyFailed)
-> (HttpException -> TransportFault)
-> HttpException
-> UpstreamBodyFailed
forall b c a. (b -> c) -> (a -> b) -> a -> c
. HttpException -> TransportFault
classifyTransport) () -> IO ()
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure

-- | Pump chunks with one opening flush. An empty chunk marks the end of the body.
pumpBody :: BodyReader -> (Builder -> IO ()) -> IO () -> IO ()
pumpBody :: BodyReader -> StreamingBody
pumpBody BodyReader
readChunk Builder -> IO ()
write IO ()
flush = do
    opening <- BodyReader
readChunk
    unless (BS.null opening) $ do
        write (byteString opening)
        flush
        rest
  where
    rest :: IO ()
    rest :: IO ()
rest = do
        chunk <- BodyReader
readChunk
        unless (BS.null chunk) $ do
            write (byteString chunk)
            rest