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

{- | The core transport-fault vocabulary. A client-library adapter classifies its own
exceptions at its edge, so no consumer layer ever sees the library's exception type.
-}
module Ecluse.Core.Fault (
    -- * Transport faults
    TransportFault (..),
    transportFault,
    TransportCause (..),
    renderTransportCause,
    renderTransportFault,
    transportRetryable,

    -- * HTTP faults
    HttpFault (..),
    renderHttpFault,

    -- * Retry delays
    RetryAfter (..),

    -- * The shared detail budget
    boundedDetail,
) where

import Data.Text qualified as T

-- | One classified transport failure. Build it with 'transportFault' so the detail stays bounded.
data TransportFault = TransportFault
    { TransportFault -> TransportCause
tfCause :: TransportCause
    -- ^ The closed classification a consumer or an operator reads.
    , TransportFault -> Text
tfDetail :: Text
    -- ^ What the adapter knows beyond the cause, bounded to a log line. Diagnostic only: never parsed, and no decision branches on it.
    }
    deriving stock (TransportFault -> TransportFault -> Bool
(TransportFault -> TransportFault -> Bool)
-> (TransportFault -> TransportFault -> Bool) -> Eq TransportFault
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: TransportFault -> TransportFault -> Bool
== :: TransportFault -> TransportFault -> Bool
$c/= :: TransportFault -> TransportFault -> Bool
/= :: TransportFault -> TransportFault -> Bool
Eq, Int -> TransportFault -> ShowS
[TransportFault] -> ShowS
TransportFault -> String
(Int -> TransportFault -> ShowS)
-> (TransportFault -> String)
-> ([TransportFault] -> ShowS)
-> Show TransportFault
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> TransportFault -> ShowS
showsPrec :: Int -> TransportFault -> ShowS
$cshow :: TransportFault -> String
show :: TransportFault -> String
$cshowList :: [TransportFault] -> ShowS
showList :: [TransportFault] -> ShowS
Show)

-- | Build a 'TransportFault' with the detail truncated, so a pathological exception cannot bloat a log line or a held value.
transportFault :: TransportCause -> Text -> TransportFault
transportFault :: TransportCause -> Text -> TransportFault
transportFault TransportCause
cause Text
detail = TransportCause -> Text -> TransportFault
TransportFault TransportCause
cause (Text -> Text
boundedDetail Text
detail)

-- | Why the transport could not deliver. Coarse on purpose: each constructor reads differently to an operator, and the rest goes in 'tfDetail'.
data TransportCause
    = -- | The peer did not answer in time (a connect, response, or socket timeout).
      TransportTimeout
    | -- | The peer could not be reached at all: a refused connection, a failed lookup, or a peer that closed or reset before answering.
      TransportUnreachable
    | -- | The TLS layer refused the peer (a handshake or certificate failure).
      TransportTls
    | -- | Any other client-reported fault (a malformed response, an unparseable URL, an internal client error): the closed catch-all.
      TransportProtocol
    deriving stock (TransportCause -> TransportCause -> Bool
(TransportCause -> TransportCause -> Bool)
-> (TransportCause -> TransportCause -> Bool) -> Eq TransportCause
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: TransportCause -> TransportCause -> Bool
== :: TransportCause -> TransportCause -> Bool
$c/= :: TransportCause -> TransportCause -> Bool
/= :: TransportCause -> TransportCause -> Bool
Eq, Int -> TransportCause -> ShowS
[TransportCause] -> ShowS
TransportCause -> String
(Int -> TransportCause -> ShowS)
-> (TransportCause -> String)
-> ([TransportCause] -> ShowS)
-> Show TransportCause
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> TransportCause -> ShowS
showsPrec :: Int -> TransportCause -> ShowS
$cshow :: TransportCause -> String
show :: TransportCause -> String
$cshowList :: [TransportCause] -> ShowS
showList :: [TransportCause] -> ShowS
Show)

-- | What a transport cause says happened, for a line an operator reads.
renderTransportCause :: TransportCause -> Text
renderTransportCause :: TransportCause -> Text
renderTransportCause = \case
    TransportCause
TransportTimeout -> Text
"the peer did not answer in time"
    TransportCause
TransportUnreachable -> Text
"the peer could not be reached"
    TransportCause
TransportTls -> Text
"the TLS layer refused the peer"
    TransportCause
TransportProtocol -> Text
"the peer's answer could not be used"

-- | A transport fault for a log line: its detail, then its cause.
renderTransportFault :: TransportFault -> Text
renderTransportFault :: TransportFault -> Text
renderTransportFault TransportFault
fault = TransportFault -> Text
tfDetail TransportFault
fault Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
" (" Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> TransportCause -> Text
renderTransportCause (TransportFault -> TransportCause
tfCause TransportFault
fault) Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
")"

-- | Whether another attempt can help. A timeout and an unreachable peer clear on their own, and a TLS or protocol fault needs a fix.
transportRetryable :: TransportCause -> Bool
transportRetryable :: TransportCause -> Bool
transportRetryable = \case
    TransportCause
TransportTimeout -> Bool
True
    TransportCause
TransportUnreachable -> Bool
True
    TransportCause
TransportTls -> Bool
False
    TransportCause
TransportProtocol -> Bool
False

-- | A failed HTTP exchange without its request or its response, either of which can carry a credential.
data HttpFault
    = -- | The peer answered with this non-2xx status.
      HttpStatus Int
    | -- | The transport delivered no usable answer.
      HttpTransport TransportFault
    deriving stock (HttpFault -> HttpFault -> Bool
(HttpFault -> HttpFault -> Bool)
-> (HttpFault -> HttpFault -> Bool) -> Eq HttpFault
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: HttpFault -> HttpFault -> Bool
== :: HttpFault -> HttpFault -> Bool
$c/= :: HttpFault -> HttpFault -> Bool
/= :: HttpFault -> HttpFault -> Bool
Eq, Int -> HttpFault -> ShowS
[HttpFault] -> ShowS
HttpFault -> String
(Int -> HttpFault -> ShowS)
-> (HttpFault -> String)
-> ([HttpFault] -> ShowS)
-> Show HttpFault
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> HttpFault -> ShowS
showsPrec :: Int -> HttpFault -> ShowS
$cshow :: HttpFault -> String
show :: HttpFault -> String
$cshowList :: [HttpFault] -> ShowS
showList :: [HttpFault] -> ShowS
Show)

-- | A fault for a log line. A status follows its source's @host:port@, and a transport fault reads from its detail, which names the endpoint.
renderHttpFault :: Text -> HttpFault -> Text
renderHttpFault :: Text -> HttpFault -> Text
renderHttpFault Text
source = \case
    HttpStatus Int
code -> Text
source Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
": HTTP " Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Int -> Text
forall b a. (Show a, IsString b) => a -> b
show Int
code
    HttpTransport TransportFault
fault -> TransportFault -> Text
renderTransportFault TransportFault
fault

-- | A @Retry-After@ delay in whole seconds, never confused with another integer on its way to a header or a sweep's wait.
newtype RetryAfter = RetryAfter Int
    deriving stock (RetryAfter -> RetryAfter -> Bool
(RetryAfter -> RetryAfter -> Bool)
-> (RetryAfter -> RetryAfter -> Bool) -> Eq RetryAfter
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: RetryAfter -> RetryAfter -> Bool
== :: RetryAfter -> RetryAfter -> Bool
$c/= :: RetryAfter -> RetryAfter -> Bool
/= :: RetryAfter -> RetryAfter -> Bool
Eq, Eq RetryAfter
Eq RetryAfter =>
(RetryAfter -> RetryAfter -> Ordering)
-> (RetryAfter -> RetryAfter -> Bool)
-> (RetryAfter -> RetryAfter -> Bool)
-> (RetryAfter -> RetryAfter -> Bool)
-> (RetryAfter -> RetryAfter -> Bool)
-> (RetryAfter -> RetryAfter -> RetryAfter)
-> (RetryAfter -> RetryAfter -> RetryAfter)
-> Ord RetryAfter
RetryAfter -> RetryAfter -> Bool
RetryAfter -> RetryAfter -> Ordering
RetryAfter -> RetryAfter -> RetryAfter
forall a.
Eq a =>
(a -> a -> Ordering)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> Bool)
-> (a -> a -> a)
-> (a -> a -> a)
-> Ord a
$ccompare :: RetryAfter -> RetryAfter -> Ordering
compare :: RetryAfter -> RetryAfter -> Ordering
$c< :: RetryAfter -> RetryAfter -> Bool
< :: RetryAfter -> RetryAfter -> Bool
$c<= :: RetryAfter -> RetryAfter -> Bool
<= :: RetryAfter -> RetryAfter -> Bool
$c> :: RetryAfter -> RetryAfter -> Bool
> :: RetryAfter -> RetryAfter -> Bool
$c>= :: RetryAfter -> RetryAfter -> Bool
>= :: RetryAfter -> RetryAfter -> Bool
$cmax :: RetryAfter -> RetryAfter -> RetryAfter
max :: RetryAfter -> RetryAfter -> RetryAfter
$cmin :: RetryAfter -> RetryAfter -> RetryAfter
min :: RetryAfter -> RetryAfter -> RetryAfter
Ord, Int -> RetryAfter -> ShowS
[RetryAfter] -> ShowS
RetryAfter -> String
(Int -> RetryAfter -> ShowS)
-> (RetryAfter -> String)
-> ([RetryAfter] -> ShowS)
-> Show RetryAfter
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> RetryAfter -> ShowS
showsPrec :: Int -> RetryAfter -> ShowS
$cshow :: RetryAfter -> String
show :: RetryAfter -> String
$cshowList :: [RetryAfter] -> ShowS
showList :: [RetryAfter] -> ShowS
Show)

-- | Truncate a rendered detail to the log-line budget every fault vocabulary shares.
boundedDetail :: Text -> Text
boundedDetail :: Text -> Text
boundedDetail = Text -> Text
T.copy (Text -> Text) -> (Text -> Text) -> Text -> Text
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Int -> Text -> Text
T.take Int
maxDetailChars

-- The rendered-detail budget: generous enough for any realistic client-library
-- message, small enough that a held fault value stays log-line sized.
maxDetailChars :: Int
maxDetailChars :: Int
maxDetailChars = Int
512