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

{- | Request shaping and response classification for artifact relays.
Response judgements precede the client response commit.
-}
module Ecluse.Core.Server.Pipeline.Tarball.Relay (
    -- * Serve mode
    ArtifactServe (..),

    -- * Shaping the upstream artifact request
    withMethod,
    withValidators,

    -- * Relaying the upstream response
    relayUpstreamResult,
    relayPublicResult,
    acceptArtifact,
    acceptPrivateArtifact,
    privateArtifactResponder,
    relayUnjudged,
    relayJudged,

    -- * Judging the public relay
    RelayVerdict (..),
    relayVerdict,
    observeRelayAnomaly,
) where

import Network.HTTP.Client qualified as HTTP
import Network.HTTP.Types (RequestHeaders, ResponseHeaders, Status, hContentType, methodHead, statusCode, statusIsSuccessful)

import Data.ByteString qualified as BS
import Ecluse.Core.Package (PackageName, renderPackageName)
import Ecluse.Core.Registry (isAuthorisationFailure)
import Ecluse.Core.Registry.Exchange.Types (ExchangeClient)
import Ecluse.Core.Registry.Public (PublicControl, ReadControl (Controlled))
import Ecluse.Core.Security (ProgressFloor)
import Ecluse.Core.Server.Conditional (isNotModified)
import Ecluse.Core.Server.Pipeline.Internal (pipelineModule)
import Ecluse.Core.Server.Stream (RelayResponder (..), UpstreamBody (NoBody, StreamBody), UpstreamResult, withUpstreamResult, withUpstreamResultUsing)
import Ecluse.Core.Telemetry.Metrics qualified as Metric
import Ecluse.Core.Telemetry.Record (MetricsPort (mpPublicRelayAnomaly))
import Ecluse.Core.Telemetry.Upstream (PublicReadKind)
import Ecluse.Core.Version (Version, renderVersion)
import Katip (KatipContext, Severity (WarningS), katipAddContext, logFM, ls, sl)

-- | The artifact method and whether a public admit enqueues a mirror job.
data ArtifactServe
    = -- | A @GET@: stream the artifact body through, enqueuing a mirror job on a public admit.
      ServeFull
    | -- | Probe with @HEAD@ without streaming bytes or enqueuing a mirror job.
      ServeHead

-- | Tag an upstream artifact request with the serve mode's method. 'ServeFull' keeps the @GET@.
withMethod :: ArtifactServe -> HTTP.Request -> HTTP.Request
withMethod :: ArtifactServe -> Request -> Request
withMethod = \case
    ArtifactServe
ServeFull -> Request -> Request
forall a. a -> a
id
    ArtifactServe
ServeHead -> \Request
req -> Request
req{HTTP.method = methodHead}

-- | Forward conditional validators so upstream can answer @304@.
withValidators :: RequestHeaders -> HTTP.Request -> HTTP.Request
withValidators :: RequestHeaders -> Request -> Request
withValidators RequestHeaders
validators Request
req =
    Request
req{HTTP.requestHeaders = validators <> HTTP.requestHeaders req}

-- | Relay in the serve mode, preserving an upstream rejection or transport failure.
relayUpstreamResult ::
    ArtifactServe ->
    ExchangeClient ->
    ProgressFloor ->
    HTTP.Request ->
    (Status -> Bool) ->
    (Status -> ResponseHeaders -> IO (Status, ResponseHeaders, verdict)) ->
    RelayResponder response ->
    IO (UpstreamResult (verdict, response))
relayUpstreamResult :: forall verdict response.
ArtifactServe
-> ExchangeClient
-> ProgressFloor
-> Request
-> (Status -> Bool)
-> (Status
    -> RequestHeaders -> IO (Status, RequestHeaders, verdict))
-> RelayResponder response
-> IO (UpstreamResult (verdict, response))
relayUpstreamResult ArtifactServe
mode ExchangeClient
client ProgressFloor
progress Request
request =
    ExchangeClient
-> ProgressFloor
-> Request
-> UpstreamBody
-> (Status -> Bool)
-> (Status
    -> RequestHeaders -> IO (Status, RequestHeaders, verdict))
-> RelayResponder response
-> IO (UpstreamResult (verdict, response))
forall verdict response.
ExchangeClient
-> ProgressFloor
-> Request
-> UpstreamBody
-> (Status -> Bool)
-> (Status
    -> RequestHeaders -> IO (Status, RequestHeaders, verdict))
-> RelayResponder response
-> IO (UpstreamResult (verdict, response))
withUpstreamResult ExchangeClient
client ProgressFloor
progress Request
request (ArtifactServe -> UpstreamBody
upstreamBody ArtifactServe
mode)

-- | Relay a public artifact or companion after shared authority admission.
relayPublicResult :: PublicControl -> PublicReadKind -> ArtifactServe -> ExchangeClient -> ProgressFloor -> HTTP.Request -> (Status -> Bool) -> (Status -> ResponseHeaders -> IO (Status, ResponseHeaders, verdict)) -> RelayResponder response -> IO (UpstreamResult (verdict, response))
relayPublicResult :: forall verdict response.
PublicControl
-> PublicReadKind
-> ArtifactServe
-> ExchangeClient
-> ProgressFloor
-> Request
-> (Status -> Bool)
-> (Status
    -> RequestHeaders -> IO (Status, RequestHeaders, verdict))
-> RelayResponder response
-> IO (UpstreamResult (verdict, response))
relayPublicResult PublicControl
control PublicReadKind
kind ArtifactServe
mode ExchangeClient
client ProgressFloor
progress Request
request = ReadControl
-> ExchangeClient
-> ProgressFloor
-> Request
-> UpstreamBody
-> (Status -> Bool)
-> (Status
    -> RequestHeaders -> IO (Status, RequestHeaders, verdict))
-> RelayResponder response
-> IO (UpstreamResult (verdict, response))
forall verdict response.
ReadControl
-> ExchangeClient
-> ProgressFloor
-> Request
-> UpstreamBody
-> (Status -> Bool)
-> (Status
    -> RequestHeaders -> IO (Status, RequestHeaders, verdict))
-> RelayResponder response
-> IO (UpstreamResult (verdict, response))
withUpstreamResultUsing (PublicControl -> PublicReadKind -> ReadControl
Controlled PublicControl
control PublicReadKind
kind) ExchangeClient
client ProgressFloor
progress Request
request (ArtifactServe -> UpstreamBody
upstreamBody ArtifactServe
mode)

upstreamBody :: ArtifactServe -> UpstreamBody
upstreamBody :: ArtifactServe -> UpstreamBody
upstreamBody = \case
    ArtifactServe
ServeFull -> UpstreamBody
StreamBody
    ArtifactServe
ServeHead -> UpstreamBody
NoBody

-- | A successful artifact response, including a matching conditional validator.
acceptArtifact :: Status -> Bool
acceptArtifact :: Status -> Bool
acceptArtifact Status
s = Status -> Bool
statusIsSuccessful Status
s Bool -> Bool -> Bool
|| Status -> Bool
isNotModified Status
s

-- | Private authorisation failures commit a local refusal instead of allowing public fallback.
acceptPrivateArtifact :: Status -> Bool
acceptPrivateArtifact :: Status -> Bool
acceptPrivateArtifact Status
status = Status -> Bool
acceptArtifact Status
status Bool -> Bool -> Bool
|| Int -> Bool
isAuthorisationFailure (Status -> Int
statusCode Status
status)

-- | Replace private access refusals without invoking either upstream responder.
privateArtifactResponder :: (Status -> IO result) -> (response -> result) -> RelayResponder response -> RelayResponder result
privateArtifactResponder :: forall result response.
(Status -> IO result)
-> (response -> result)
-> RelayResponder response
-> RelayResponder result
privateArtifactResponder Status -> IO result
refuse response -> result
admitted RelayResponder response
responder =
    (Status -> RequestHeaders -> StreamingBody -> IO result)
-> (Status -> RequestHeaders -> IO result) -> RelayResponder result
forall response.
(Status -> RequestHeaders -> StreamingBody -> IO response)
-> (Status -> RequestHeaders -> IO response)
-> RelayResponder response
RelayResponder
        (\Status
status RequestHeaders
headers StreamingBody
body -> Status -> IO response -> IO result
answer Status
status (RelayResponder response
-> Status -> RequestHeaders -> StreamingBody -> IO response
forall response.
RelayResponder response
-> Status -> RequestHeaders -> StreamingBody -> IO response
relayStreamResponse RelayResponder response
responder Status
status RequestHeaders
headers StreamingBody
body))
        (\Status
status RequestHeaders
headers -> Status -> IO response -> IO result
answer Status
status (RelayResponder response -> Status -> RequestHeaders -> IO response
forall response.
RelayResponder response -> Status -> RequestHeaders -> IO response
relayEmptyResponse RelayResponder response
responder Status
status RequestHeaders
headers))
  where
    answer :: Status -> IO response -> IO result
answer Status
status IO response
response
        | Int -> Bool
isAuthorisationFailure (Status -> Int
statusCode Status
status) = Status -> IO result
refuse Status
status
        | Bool
otherwise = response -> result
admitted (response -> result) -> IO response -> IO result
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> IO response
response

-- | Forward private headers without the public leg's anomaly scan.
relayUnjudged :: Status -> ResponseHeaders -> IO (Status, ResponseHeaders, ())
relayUnjudged :: Status -> RequestHeaders -> IO (Status, RequestHeaders, ())
relayUnjudged Status
status RequestHeaders
headers = (Status, RequestHeaders, ()) -> IO (Status, RequestHeaders, ())
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Status
status, RequestHeaders -> RequestHeaders
forwardedHeaders RequestHeaders
headers, ())

-- | Judge public headers before committing the response.
relayJudged :: Status -> ResponseHeaders -> IO (Status, ResponseHeaders, RelayVerdict)
relayJudged :: Status
-> RequestHeaders -> IO (Status, RequestHeaders, RelayVerdict)
relayJudged Status
status RequestHeaders
headers = (Status, RequestHeaders, RelayVerdict)
-> IO (Status, RequestHeaders, RelayVerdict)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Status
status, RequestHeaders -> RequestHeaders
forwardedHeaders RequestHeaders
headers, Status -> RequestHeaders -> RelayVerdict
relayVerdict Status
status RequestHeaders
headers)

forwardedHeaders :: ResponseHeaders -> ResponseHeaders
forwardedHeaders :: RequestHeaders -> RequestHeaders
forwardedHeaders = (Header -> Bool) -> RequestHeaders -> RequestHeaders
forall a. (a -> Bool) -> [a] -> [a]
filter (Bool -> Bool
not (Bool -> Bool) -> (Header -> Bool) -> Header -> Bool
forall b c a. (b -> c) -> (a -> b) -> a -> c
. HeaderName -> Bool
forall {a}. (Eq a, IsString a) => a -> Bool
isHopByHop (HeaderName -> Bool) -> (Header -> HeaderName) -> Header -> Bool
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Header -> HeaderName
forall a b. (a, b) -> a
fst)
  where
    isHopByHop :: a -> Bool
isHopByHop a
name = a
name a -> a -> Bool
forall a. Eq a => a -> a -> Bool
== a
"Transfer-Encoding" Bool -> Bool -> Bool
|| a
name a -> a -> Bool
forall a. Eq a => a -> a -> Bool
== a
"Connection"

-- | What the public leg relayed, judged at relay time from the status and headers alone.
data RelayVerdict
    = -- | A success whose headers look like the admitted artifact. A relayed @304@ counts.
      RelayedArtifact
    | -- | A success that does not look like an artifact. Carries a bounded reason.
      RelayedOddShape Text
    | -- | A non-success passed through verbatim. Carries the status.
      RelayedNonSuccess Status
    deriving stock (RelayVerdict -> RelayVerdict -> Bool
(RelayVerdict -> RelayVerdict -> Bool)
-> (RelayVerdict -> RelayVerdict -> Bool) -> Eq RelayVerdict
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: RelayVerdict -> RelayVerdict -> Bool
== :: RelayVerdict -> RelayVerdict -> Bool
$c/= :: RelayVerdict -> RelayVerdict -> Bool
/= :: RelayVerdict -> RelayVerdict -> Bool
Eq, Int -> RelayVerdict -> ShowS
[RelayVerdict] -> ShowS
RelayVerdict -> String
(Int -> RelayVerdict -> ShowS)
-> (RelayVerdict -> String)
-> ([RelayVerdict] -> ShowS)
-> Show RelayVerdict
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> RelayVerdict -> ShowS
showsPrec :: Int -> RelayVerdict -> ShowS
$cshow :: RelayVerdict -> String
show :: RelayVerdict -> String
$cshowList :: [RelayVerdict] -> ShowS
showList :: [RelayVerdict] -> ShowS
Show)

-- | Judge one public relay from its status and headers alone.
relayVerdict :: Status -> ResponseHeaders -> RelayVerdict
relayVerdict :: Status -> RequestHeaders -> RelayVerdict
relayVerdict Status
status RequestHeaders
headers
    | Status -> Bool
isNotModified Status
status = RelayVerdict
RelayedArtifact
    | Bool -> Bool
not (Status -> Bool
statusIsSuccessful Status
status) = Status -> RelayVerdict
RelayedNonSuccess Status
status
    | Just ByteString
contentType <- Header -> ByteString
forall a b. (a, b) -> b
snd (Header -> ByteString) -> Maybe Header -> Maybe ByteString
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> (Header -> Bool) -> RequestHeaders -> Maybe Header
forall (t :: * -> *) a. Foldable t => (a -> Bool) -> t a -> Maybe a
find ((HeaderName -> HeaderName -> Bool
forall a. Eq a => a -> a -> Bool
== HeaderName
hContentType) (HeaderName -> Bool) -> (Header -> HeaderName) -> Header -> Bool
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Header -> HeaderName
forall a b. (a, b) -> a
fst) RequestHeaders
headers
    , ByteString -> Bool
textualContentType ByteString
contentType =
        Text -> RelayVerdict
RelayedOddShape (Text
"a success carrying a non-artifact content type: " Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> ByteString -> Text
forall a b. ConvertUtf8 a b => b -> a
decodeUtf8 ByteString
contentType)
    | Bool
otherwise = RelayVerdict
RelayedArtifact
  where
    textualContentType :: ByteString -> Bool
textualContentType ByteString
raw =
        ByteString
"text/" ByteString -> ByteString -> Bool
`BS.isPrefixOf` ByteString
raw Bool -> Bool -> Bool
|| ByteString
"application/json" ByteString -> ByteString -> Bool
`BS.isPrefixOf` ByteString
raw

-- | Count bounded anomaly classes and log their unbounded detail.
observeRelayAnomaly :: forall m. (KatipContext m) => MetricsPort -> PackageName -> Version -> RelayVerdict -> m ()
observeRelayAnomaly :: forall (m :: * -> *).
KatipContext m =>
MetricsPort -> PackageName -> Version -> RelayVerdict -> m ()
observeRelayAnomaly MetricsPort
metrics PackageName
name Version
version = \case
    RelayVerdict
RelayedArtifact -> m ()
forall (f :: * -> *). Applicative f => f ()
pass
    RelayedOddShape Text
reason -> RelayAnomaly -> Text -> m ()
record RelayAnomaly
Metric.RelayOddShape (Text
"the public upstream answered a success that does not look like the admitted artifact: " Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
reason)
    RelayedNonSuccess Status
status -> RelayAnomaly -> Text -> m ()
record RelayAnomaly
Metric.RelayNonSuccess (Text
"the public upstream answered a non-success: HTTP " Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Int -> Text
forall b a. (Show a, IsString b) => a -> b
show (Status -> Int
statusCode Status
status))
  where
    record :: Metric.RelayAnomaly -> Text -> m ()
    record :: RelayAnomaly -> Text -> m ()
record RelayAnomaly
cls Text
message = do
        IO () -> m ()
forall a. IO a -> m a
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (MetricsPort -> RelayAnomaly -> IO ()
mpPublicRelayAnomaly MetricsPort
metrics RelayAnomaly
cls)
        SimpleLogPayload -> m () -> m ()
forall i (m :: * -> *) a.
(LogItem i, KatipContext m) =>
i -> m a -> m a
katipAddContext SimpleLogPayload
payload (Severity -> LogStr -> m ()
forall (m :: * -> *).
(Applicative m, KatipContext m) =>
Severity -> LogStr -> m ()
logFM Severity
WarningS (Text -> LogStr
forall a. StringConv a Text => a -> LogStr
ls Text
message))
    payload :: SimpleLogPayload
payload =
        Text -> Text -> SimpleLogPayload
forall a. ToJSON a => Text -> a -> SimpleLogPayload
sl Text
"module" Text
pipelineModule
            SimpleLogPayload -> SimpleLogPayload -> SimpleLogPayload
forall a. Semigroup a => a -> a -> a
<> Text -> Text -> SimpleLogPayload
forall a. ToJSON a => Text -> a -> SimpleLogPayload
sl Text
"package" (PackageName -> Text
renderPackageName PackageName
name)
            SimpleLogPayload -> SimpleLogPayload -> SimpleLogPayload
forall a. Semigroup a => a -> a -> a
<> Text -> Text -> SimpleLogPayload
forall a. ToJSON a => Text -> a -> SimpleLogPayload
sl Text
"version" (Version -> Text
renderVersion Version
version)