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

{- | Shared authentication, admission shedding, flight keys, and refusal handling.
Route handlers keep their own response formats while sharing these policy decisions.
-}
module Ecluse.Core.Server.Pipeline.Shared (
    -- * Edge authentication
    edgeTokenMatches,
    forwardedCredential,
    unauthorisedMessage,
    privateAuthorisationRefusal,

    -- * Admission shed
    withMetadataAdmission,
    withListingAdmission,
    shedStatus,
    shedMessage,
    hRetryAfter,
    shedRetryAfter,
    retryAfterHeaders,
    upstreamCooling,

    -- * Shared work
    flightOf,

    -- * First-party refusals
    firstPartyRule,

    -- * Integrity-floor rejections
    integrityMissing,
    integrityBelowFloor,
    trustedIntegrityMissing,
    trustedIntegrityBelowFloor,
) where

import Network.HTTP.Types (Header, HeaderName, ResponseHeaders, Status, status503)
import Network.Wai (Request, requestHeaders)
import UnliftIO (MonadUnliftIO, withRunInIO)

import Ecluse.Core.Credential (ClientCredential (credSecret), Secret)
import Ecluse.Core.Registry.Request (credentialRecover)
import Ecluse.Core.Server.Admission (serveAdmissionLine, serveAdmissionOverflow, withServeAdmission)
import Ecluse.Core.Server.Admission.Meter (MemoryTicket, meterLine, tryMemoryEntry)
import Ecluse.Core.Server.Admission.Overflow (Attempt (..), Waited (..), attemptAfter, awaitPlace)
import Ecluse.Core.Server.Admission.Types (FlightKey (FlightKey))
import Ecluse.Core.Server.Admission.Weighted (admissionWaitMicros)
import Ecluse.Core.Server.Cache.Types (CacheKey, cacheKeyIdentity, cacheKeyStore)
import Ecluse.Core.Server.Context (MountBinding (bindingCredential), ServeRuntime (srAdmission, srMemoryMeter, srMetrics))
import Ecluse.Core.Server.Response (
    HelpMessage,
    Refusal,
    RejectReason (BelowIntegrityFloor, MissingIntegrity),
    Rejection (Rejection),
    RetryAfter (RetryAfter),
    RuleName (RuleName),
    ServeDecision (Reject),
    Transience (WillResolve),
    mkRefusal,
    rejectUnavailable,
 )
import Ecluse.Core.Telemetry.Metrics qualified as Metric
import Ecluse.Core.Telemetry.Record (MetricsPort (mpMemoryAdmissionShed, mpServeDecision))

-- | Match the configured inbound secret without content-dependent early exit. An unconfigured edge is open.
edgeTokenMatches :: Maybe Secret -> Maybe ClientCredential -> Bool
edgeTokenMatches :: Maybe Secret -> Maybe ClientCredential -> Bool
edgeTokenMatches Maybe Secret
expected Maybe ClientCredential
forwarded = case Maybe Secret
expected of
    Maybe Secret
Nothing -> Bool
True
    Just Secret
want -> (ClientCredential -> Secret)
-> Maybe ClientCredential -> Maybe Secret
forall a b. (a -> b) -> Maybe a -> Maybe b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ClientCredential -> Secret
credSecret Maybe ClientCredential
forwarded Maybe Secret -> Maybe Secret -> Bool
forall a. Eq a => a -> a -> Bool
== Secret -> Maybe Secret
forall a. a -> Maybe a
Just Secret
want

-- | The client's credential, as the mount's credential mapping recovers it from the request headers.
forwardedCredential :: MountBinding -> Request -> Maybe ClientCredential
forwardedCredential :: MountBinding -> Request -> Maybe ClientCredential
forwardedCredential MountBinding
mount = CredentialMapping -> RequestHeaders -> Maybe ClientCredential
credentialRecover (MountBinding -> CredentialMapping
bindingCredential MountBinding
mount) (RequestHeaders -> Maybe ClientCredential)
-> (Request -> RequestHeaders) -> Request -> Maybe ClientCredential
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Request -> RequestHeaders
requestHeaders

-- | Report edge authentication failure without disclosing either token.
unauthorisedMessage :: Text
unauthorisedMessage :: Text
unauthorisedMessage = Text
"authentication required"

-- | The fixed refusal shared by private metadata and artifact access failures.
privateAuthorisationRefusal :: Maybe HelpMessage -> Refusal
privateAuthorisationRefusal :: Maybe HelpMessage -> Refusal
privateAuthorisationRefusal Maybe HelpMessage
help = Maybe HelpMessage -> Text -> Refusal
mkRefusal Maybe HelpMessage
help Text
"the private upstream refused access, so public content cannot replace it"

-- | Acquire memory and CPU admission before metadata work. Answer after both release.
withMetadataAdmission :: (MonadUnliftIO m) => ServeRuntime -> (ResponseHeaders -> m received) -> (MemoryTicket -> m a) -> (a -> m received) -> m received
withMetadataAdmission :: forall (m :: * -> *) received a.
MonadUnliftIO m =>
ServeRuntime
-> (RequestHeaders -> m received)
-> (MemoryTicket -> m a)
-> (a -> m received)
-> m received
withMetadataAdmission ServeRuntime
runtime RequestHeaders -> m received
shed MemoryTicket -> m a
gated =
    ServeRuntime
-> (RequestHeaders -> m received)
-> (MemoryTicket -> m a)
-> (a -> m a)
-> (a -> m received)
-> m received
forall (m :: * -> *) received a b.
MonadUnliftIO m =>
ServeRuntime
-> (RequestHeaders -> m received)
-> (MemoryTicket -> m a)
-> (a -> m b)
-> (b -> m received)
-> m received
metadataAdmission ServeRuntime
runtime RequestHeaders -> m received
shed MemoryTicket -> m a
gated a -> m a
forall a. a -> m a
forall (f :: * -> *) a. Applicative f => a -> f a
pure

-- | Write after CPU admission releases, while the memory ticket still covers the response body.
withListingAdmission :: (MonadUnliftIO m) => ServeRuntime -> (ResponseHeaders -> m received) -> (MemoryTicket -> m response) -> (response -> m received) -> m received
withListingAdmission :: forall (m :: * -> *) received a.
MonadUnliftIO m =>
ServeRuntime
-> (RequestHeaders -> m received)
-> (MemoryTicket -> m a)
-> (a -> m received)
-> m received
withListingAdmission ServeRuntime
runtime RequestHeaders -> m received
shed MemoryTicket -> m response
gated response -> m received
write =
    ServeRuntime
-> (RequestHeaders -> m received)
-> (MemoryTicket -> m response)
-> (response -> m received)
-> (received -> m received)
-> m received
forall (m :: * -> *) received a b.
MonadUnliftIO m =>
ServeRuntime
-> (RequestHeaders -> m received)
-> (MemoryTicket -> m a)
-> (a -> m b)
-> (b -> m received)
-> m received
metadataAdmission ServeRuntime
runtime RequestHeaders -> m received
shed MemoryTicket -> m response
gated response -> m received
write received -> m received
forall a. a -> m a
forall (f :: * -> *) a. Applicative f => a -> f a
pure

metadataAdmission :: (MonadUnliftIO m) => ServeRuntime -> (ResponseHeaders -> m received) -> (MemoryTicket -> m a) -> (a -> m b) -> (b -> m received) -> m received
metadataAdmission :: forall (m :: * -> *) received a b.
MonadUnliftIO m =>
ServeRuntime
-> (RequestHeaders -> m received)
-> (MemoryTicket -> m a)
-> (a -> m b)
-> (b -> m received)
-> m received
metadataAdmission ServeRuntime
runtime RequestHeaders -> m received
shed MemoryTicket -> m a
gated a -> m b
held b -> m received
answer =
    m (Attempt b)
attempt m (Attempt b) -> (Attempt b -> m received) -> m received
forall a b. m a -> (a -> m b) -> m b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
        Entered b
result -> b -> m received
answer b
result
        Expired Line
line -> Line -> RequestHeaders -> m received
refuse Line
line [Header
shedRetryAfter]
        TurnedAway Line
line -> case ServeAdmission -> Maybe Overflow
serveAdmissionOverflow ServeAdmission
admission of
            Maybe Overflow
Nothing -> Line -> RequestHeaders -> m received
refuse Line
line [Header
shedRetryAfter]
            Just Overflow
overflow ->
                ((forall a. m a -> IO a) -> IO (Waited b)) -> m (Waited b)
forall b. ((forall a. m a -> IO a) -> IO b) -> m b
forall (m :: * -> *) b.
MonadUnliftIO m =>
((forall a. m a -> IO a) -> IO b) -> m b
withRunInIO (\forall a. m a -> IO a
run -> MetricsPort -> Overflow -> Line -> IO (Attempt b) -> IO (Waited b)
forall a.
MetricsPort -> Overflow -> Line -> IO (Attempt a) -> IO (Waited a)
awaitPlace MetricsPort
metrics Overflow
overflow Line
line (m (Attempt b) -> IO (Attempt b)
forall a. m a -> IO a
run m (Attempt b)
attempt)) m (Waited b) -> (Waited b -> m received) -> m received
forall a b. m a -> (a -> m b) -> m b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
                    Placed b
result -> b -> m received
answer b
result
                    WaitedOut Line
refusedAt -> Line -> RequestHeaders -> m received
refuse Line
refusedAt [Header
shedRetryAfter]
                    QueueFull Line
refusedAt -> Line -> RequestHeaders -> m received
refuse Line
refusedAt [Header
shedRetryAfter]
  where
    metrics :: MetricsPort
metrics = ServeRuntime -> MetricsPort
srMetrics ServeRuntime
runtime
    admission :: ServeAdmission
admission = ServeRuntime -> ServeAdmission
srAdmission ServeRuntime
runtime
    meter :: MemoryMeter
meter = ServeRuntime -> MemoryMeter
srMemoryMeter ServeRuntime
runtime
    refuse :: Line -> RequestHeaders -> m received
refuse Line
line RequestHeaders
headers = do
        IO () -> m ()
forall a. IO a -> m a
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO () -> m ()) -> IO () -> m ()
forall a b. (a -> b) -> a -> b
$ do
            Bool -> IO () -> IO ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
when (Line
line Line -> Line -> Bool
forall a. Eq a => a -> a -> Bool
== MemoryMeter -> Line
meterLine MemoryMeter
meter) (MetricsPort -> IO ()
mpMemoryAdmissionShed MetricsPort
metrics)
            MetricsPort -> Decision -> IO ()
mpServeDecision MetricsPort
metrics Decision
Metric.Unavailable
        RequestHeaders -> m received
shed RequestHeaders
headers
    attempt :: m (Attempt b)
attempt =
        (Shed -> Attempt b)
-> (Either Shed b -> Attempt b)
-> Either Shed (Either Shed b)
-> Attempt b
forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either (Line -> Either Shed b -> Attempt b
forall a. Line -> Either Shed a -> Attempt a
attemptAfter (MemoryMeter -> Line
meterLine MemoryMeter
meter) (Either Shed b -> Attempt b)
-> (Shed -> Either Shed b) -> Shed -> Attempt b
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Shed -> Either Shed b
forall a b. a -> Either a b
Left) (Line -> Either Shed b -> Attempt b
forall a. Line -> Either Shed a -> Attempt a
attemptAfter (ServeAdmission -> Line
serveAdmissionLine ServeAdmission
admission))
            (Either Shed (Either Shed b) -> Attempt b)
-> m (Either Shed (Either Shed b)) -> m (Attempt b)
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> MetricsPort
-> MemoryMeter
-> (MemoryTicket -> m (Either Shed b))
-> m (Either Shed (Either Shed b))
forall (m :: * -> *) a.
MonadUnliftIO m =>
MetricsPort
-> MemoryMeter -> (MemoryTicket -> m a) -> m (Either Shed a)
tryMemoryEntry MetricsPort
metrics MemoryMeter
meter (\MemoryTicket
ticket -> MetricsPort -> ServeAdmission -> m a -> m (Either Shed a)
forall (m :: * -> *) a.
MonadUnliftIO m =>
MetricsPort -> ServeAdmission -> m a -> m (Either Shed a)
withServeAdmission MetricsPort
metrics ServeAdmission
admission (MemoryTicket -> m a
gated MemoryTicket
ticket) m (Either Shed a)
-> (Either Shed a -> m (Either Shed b)) -> m (Either Shed b)
forall a b. m a -> (a -> m b) -> m b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= (a -> m b) -> Either Shed a -> m (Either Shed b)
forall (t :: * -> *) (f :: * -> *) a b.
(Traversable t, Applicative f) =>
(a -> f b) -> t a -> f (t b)
forall (f :: * -> *) a b.
Applicative f =>
(a -> f b) -> Either Shed a -> f (Either Shed b)
traverse a -> m b
held)

-- | Use 503 to report server admission capacity, without implying a client rate limit.
shedStatus :: Status
shedStatus :: Status
shedStatus = Status
status503

-- | The body every read-path shed answers with, so the three handlers say one thing.
shedMessage :: Text
shedMessage :: Text
shedMessage = Text
"server is busy; retry later"

hRetryAfter :: HeaderName
hRetryAfter :: HeaderName
hRetryAfter = HeaderName
"Retry-After"

-- | The shed retry delay, rounded down to whole seconds from 'admissionWaitMicros'.
shedRetryAfter :: Header
shedRetryAfter :: Header
shedRetryAfter = (HeaderName
hRetryAfter, Int -> ByteString
forall b a. (Show a, IsString b) => a -> b
show (Int
admissionWaitMicros Int -> Int -> Int
forall a. Integral a => a -> a -> a
`div` Int
1_000_000))

-- | Emit Retry-After only when a decision supplies a delay.
retryAfterHeaders :: Maybe RetryAfter -> ResponseHeaders
retryAfterHeaders :: Maybe RetryAfter -> RequestHeaders
retryAfterHeaders = RequestHeaders
-> (RetryAfter -> RequestHeaders)
-> Maybe RetryAfter
-> RequestHeaders
forall b a. b -> (a -> b) -> Maybe a -> b
maybe [] (\(RetryAfter Int
secs) -> [(HeaderName
hRetryAfter, Int -> ByteString
forall b a. (Show a, IsString b) => a -> b
show Int
secs)])

-- | A public authority that supplies a positive retry delay.
upstreamCooling :: RetryAfter -> ServeDecision
upstreamCooling :: RetryAfter -> ServeDecision
upstreamCooling RetryAfter
retry = Transience -> Text -> ServeDecision
rejectUnavailable (Maybe RetryAfter -> Transience
WillResolve (RetryAfter -> Maybe RetryAfter
forall a. a -> Maybe a
Just RetryAfter
retry)) Text
"the public upstream is cooling down"

-- | The flight that the shared fetch or render behind a cache key runs under: the key's store and identity.
flightOf :: CacheKey -> FlightKey
flightOf :: CacheKey -> FlightKey
flightOf CacheKey
key = CacheStore -> ShortByteString -> FlightKey
FlightKey (CacheKey -> CacheStore
cacheKeyStore CacheKey
key) (CacheKey -> ShortByteString
cacheKeyIdentity CacheKey
key)

-- | Use one rule label for first-party refusals across read paths.
firstPartyRule :: RuleName
firstPartyRule :: RuleName
firstPartyRule = Text -> RuleName
RuleName Text
"first-party"

-- | A public version with no integrity digest.
integrityMissing :: ServeDecision
integrityMissing :: ServeDecision
integrityMissing =
    Rejection -> ServeDecision
Reject (RejectReason -> Text -> Rejection
Rejection RejectReason
MissingIntegrity Text
"this version carries no integrity digest and cannot be served from a public upstream")

-- | A public version whose digest is weaker than the configured minimum.
integrityBelowFloor :: ServeDecision
integrityBelowFloor :: ServeDecision
integrityBelowFloor =
    Rejection -> ServeDecision
Reject (RejectReason -> Text -> Rejection
Rejection RejectReason
BelowIntegrityFloor Text
"this version's integrity digest is weaker than the configured minimum and cannot be served from a public upstream")

-- | A private version with no integrity digest.
trustedIntegrityMissing :: ServeDecision
trustedIntegrityMissing :: ServeDecision
trustedIntegrityMissing =
    Rejection -> ServeDecision
Reject (RejectReason -> Text -> Rejection
Rejection RejectReason
MissingIntegrity Text
"this private version carries no integrity digest and was not served")

-- | A private version whose digest is weaker than the configured trusted minimum.
trustedIntegrityBelowFloor :: ServeDecision
trustedIntegrityBelowFloor :: ServeDecision
trustedIntegrityBelowFloor =
    Rejection -> ServeDecision
Reject (RejectReason -> Text -> Rejection
Rejection RejectReason
BelowIntegrityFloor Text
"this private version's integrity digest is weaker than the configured trusted minimum and was not served")