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

-- | Process resources shared by serving and worker runtimes. The application owns their lifetime.
module Ecluse.Runtime.Env (
    -- * Composition root
    Env (..),
    newEnvWithAdmission,
    withEnvWithAdmission,

    -- * Runtime projections
    serveRuntimeOf,
    workerRuntimeOf,

    -- * Worker heartbeat (re-exported from "Ecluse.Core.Worker")
    WorkerHeartbeat,
    newWorkerHeartbeat,
    recordPoll,
    lastPoll,
) where

import Katip (LogEnv, Severity (InfoS, WarningS), katipAddContext, sl)
import Network.HTTP.Client (Manager)

import Ecluse.Core.Deadline (Deadlines)
import Ecluse.Core.Queue (MirrorQueue)
import Ecluse.Core.Registry.Backoff (CooldownEvent (..))
import Ecluse.Core.Registry.Exchange.Types (ExchangeClient (ExchangeClient))
import Ecluse.Core.Registry.Public (PublicControl, newPublicControl)
import Ecluse.Core.Security.Authority (HostPort (..))
import Ecluse.Core.Server.Admission (ServeAdmission)
import Ecluse.Core.Server.Admission.Meter (MemoryMeter)
import Ecluse.Core.Server.Cache (MetadataCache)
import Ecluse.Core.Server.Context (ServeRuntime (..))
import Ecluse.Core.Telemetry.Record (MetricsPort (mpUpstreamRequest))
import Ecluse.Core.Worker (WorkerHeartbeat, WorkerPolicies, WorkerRuntime (..), lastPoll, newWorkerHeartbeat, recordPoll)
import Ecluse.Runtime.Log (DdContext, logLine)
import Ecluse.Runtime.Telemetry (Telemetry)
import Ecluse.Runtime.Telemetry.Correlation (ddIdentityFromEnvironment, ddPayloadNow)
import Ecluse.Runtime.Telemetry.Instruments (Metrics, metricsPortOf, newMetrics, workerMetricsPortOf)
import Ecluse.Runtime.Telemetry.Tracing (dataPlaneTrace, tracingPortOf, workerTracingPortOf)

-- | The composition-root record from which the whole effectful shell is reached.
data Env = Env
    { Env -> ServeAdmission
envServeAdmission :: ServeAdmission
    -- ^ Share the metadata admission limit and waiting room across all mounts.
    , Env -> MemoryMeter
envMemoryMeter :: MemoryMeter
    -- ^ The process-wide memory budget every serving mount pays into.
    , Env -> MirrorQueue
envQueue :: MirrorQueue
    -- ^ Queue mirror work from serving requests.
    , Env -> ExchangeClient
envPublicClient :: ExchangeClient
    -- ^ Validate public TLS peers for metadata and artifact requests.
    , Env -> PublicControl
envPublicControl :: PublicControl
    -- ^ Shared cooldown and request observation for every public serve and worker read.
    , Env -> ExchangeClient
envPrivateClient :: ExchangeClient
    -- ^ Validate private TLS peers while retaining their credential handling.
    , Env -> Deadlines
envDeadlines :: Deadlines
    -- ^ The process's one sweeper, which both clients carry and every request's timeout runs on.
    , Env -> MetadataCache
envMetadataCache :: MetadataCache
    -- ^ Selected-version and assembled retention with transient full-read coalescing.
    , Env -> LogEnv
envLogEnv :: LogEnv
    -- ^ Use the configured output format and minimum severity for structured logs.
    , Env -> Telemetry
envTelemetry :: Telemetry
    -- ^ Emit spans and metrics when telemetry is enabled, otherwise do nothing.
    , Env -> Metrics
envMetrics :: Metrics
    -- ^ Process-wide metric instruments are inert when telemetry is disabled.
    , Env -> DdContext
envDdContext :: DdContext
    -- ^ Retain the resolved Datadog identity for per-line trace correlation.
    , Env -> WorkerHeartbeat
envWorkerHeartbeat :: WorkerHeartbeat
    -- ^ Track completed worker progress for liveness, separately from HTTP readiness.
    }

-- | Assemble process handles without opening a socket. Both clients carry the one sweeper and the one client-span tracing. Callers own the supplied resources.
newEnvWithAdmission :: ServeAdmission -> MemoryMeter -> MirrorQueue -> Manager -> Manager -> Deadlines -> MetadataCache -> LogEnv -> Telemetry -> WorkerHeartbeat -> IO Env
newEnvWithAdmission :: ServeAdmission
-> MemoryMeter
-> MirrorQueue
-> Manager
-> Manager
-> Deadlines
-> MetadataCache
-> LogEnv
-> Telemetry
-> WorkerHeartbeat
-> IO Env
newEnvWithAdmission ServeAdmission
admission MemoryMeter
meter MirrorQueue
queue Manager
manager Manager
privateManager Deadlines
deadlines MetadataCache
metadataCache LogEnv
logEnv Telemetry
telemetry WorkerHeartbeat
heartbeat = do
    metrics <- Telemetry -> IO Metrics
newMetrics Telemetry
telemetry
    tracing <- dataPlaneTrace telemetry
    publicControl <- newPublicControl (mpUpstreamRequest (metricsPortOf metrics)) (reportCooldown logEnv)
    -- The dd log identity comes from the (already-normalised) OTEL_* environment, the
    -- same precedence table the exporter uses, so logs and traces share one identity.
    ddContext <- ddIdentityFromEnvironment
    pure
        Env
            { envServeAdmission = admission
            , envMemoryMeter = meter
            , envQueue = queue
            , envPublicClient = ExchangeClient manager deadlines tracing
            , envPublicControl = publicControl
            , envPrivateClient = ExchangeClient privateManager deadlines tracing
            , envDeadlines = deadlines
            , envMetadataCache = metadataCache
            , envLogEnv = logEnv
            , envTelemetry = telemetry
            , envMetrics = metrics
            , envDdContext = ddContext
            , envWorkerHeartbeat = heartbeat
            }

-- | Run an action with borrowed process resources that require no additional release.
withEnvWithAdmission ::
    (MonadIO m) =>
    ServeAdmission ->
    MemoryMeter ->
    MirrorQueue ->
    Manager ->
    Manager ->
    Deadlines ->
    MetadataCache ->
    LogEnv ->
    Telemetry ->
    WorkerHeartbeat ->
    (Env -> m a) ->
    m a
withEnvWithAdmission :: forall (m :: * -> *) a.
MonadIO m =>
ServeAdmission
-> MemoryMeter
-> MirrorQueue
-> Manager
-> Manager
-> Deadlines
-> MetadataCache
-> LogEnv
-> Telemetry
-> WorkerHeartbeat
-> (Env -> m a)
-> m a
withEnvWithAdmission ServeAdmission
admission MemoryMeter
meter MirrorQueue
queue Manager
manager Manager
privateManager Deadlines
deadlines MetadataCache
metadataCache LogEnv
logEnv Telemetry
telemetry WorkerHeartbeat
heartbeat Env -> m a
action = do
    env <- IO Env -> m Env
forall a. IO a -> m a
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (ServeAdmission
-> MemoryMeter
-> MirrorQueue
-> Manager
-> Manager
-> Deadlines
-> MetadataCache
-> LogEnv
-> Telemetry
-> WorkerHeartbeat
-> IO Env
newEnvWithAdmission ServeAdmission
admission MemoryMeter
meter MirrorQueue
queue Manager
manager Manager
privateManager Deadlines
deadlines MetadataCache
metadataCache LogEnv
logEnv Telemetry
telemetry WorkerHeartbeat
heartbeat)
    action env

-- | Project serving capabilities without exposing the application environment to the core.
serveRuntimeOf :: Env -> ServeRuntime
serveRuntimeOf :: Env -> ServeRuntime
serveRuntimeOf Env
env =
    ServeRuntime
        { srAdmission :: ServeAdmission
srAdmission = Env -> ServeAdmission
envServeAdmission Env
env
        , srMemoryMeter :: MemoryMeter
srMemoryMeter = Env -> MemoryMeter
envMemoryMeter Env
env
        , srPublicClient :: ExchangeClient
srPublicClient = Env -> ExchangeClient
envPublicClient Env
env
        , srPublicControl :: PublicControl
srPublicControl = Env -> PublicControl
envPublicControl Env
env
        , srPrivateClient :: ExchangeClient
srPrivateClient = Env -> ExchangeClient
envPrivateClient Env
env
        , srMetadataCache :: MetadataCache
srMetadataCache = Env -> MetadataCache
envMetadataCache Env
env
        , srQueue :: MirrorQueue
srQueue = Env -> MirrorQueue
envQueue Env
env
        , srMetrics :: MetricsPort
srMetrics = Metrics -> MetricsPort
metricsPortOf (Env -> Metrics
envMetrics Env
env)
        , srTracing :: TracingPort
srTracing = Telemetry -> TracingPort
tracingPortOf (Env -> Telemetry
envTelemetry Env
env)
        }

-- | Project worker capabilities with policies derived from the served mounts.
workerRuntimeOf :: WorkerPolicies -> Env -> WorkerRuntime
workerRuntimeOf :: WorkerPolicies -> Env -> WorkerRuntime
workerRuntimeOf WorkerPolicies
policies Env
env =
    WorkerRuntime
        { wrQueue :: MirrorQueue
wrQueue = Env -> MirrorQueue
envQueue Env
env
        , wrClient :: ExchangeClient
wrClient = Env -> ExchangeClient
envPublicClient Env
env
        , wrPublicControl :: PublicControl
wrPublicControl = Env -> PublicControl
envPublicControl Env
env
        , wrHeartbeat :: WorkerHeartbeat
wrHeartbeat = Env -> WorkerHeartbeat
envWorkerHeartbeat Env
env
        , wrMetrics :: WorkerMetricsPort
wrMetrics = Metrics -> WorkerMetricsPort
workerMetricsPortOf (Env -> Metrics
envMetrics Env
env)
        , wrTracing :: WorkerTracingPort
wrTracing = Telemetry -> WorkerTracingPort
workerTracingPortOf (Env -> Telemetry
envTelemetry Env
env)
        , wrInjectTraceContext :: forall (m :: * -> *) a. (KatipContext m, MonadIO m) => m a -> m a
wrInjectTraceContext = \m a
action -> do
            dd <- IO SimpleLogPayload -> m SimpleLogPayload
forall a. IO a -> m a
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO SimpleLogPayload -> m SimpleLogPayload)
-> IO SimpleLogPayload -> m SimpleLogPayload
forall a b. (a -> b) -> a -> b
$ DdContext -> IO SimpleLogPayload
forall (m :: * -> *). MonadIO m => DdContext -> m SimpleLogPayload
ddPayloadNow (Env -> DdContext
envDdContext Env
env)
            katipAddContext dd action
        , wrPolicies :: WorkerPolicies
wrPolicies = WorkerPolicies
policies
        }

reportCooldown :: LogEnv -> HostPort -> CooldownEvent -> IO ()
reportCooldown :: LogEnv -> HostPort -> CooldownEvent -> IO ()
reportCooldown LogEnv
logEnv HostPort
authority CooldownEvent
event = LogEnv -> SimpleLogPayload -> Severity -> Text -> IO ()
logLine LogEnv
logEnv SimpleLogPayload
payload Severity
severity Text
message
  where
    payload :: SimpleLogPayload
payload = Text -> Text -> SimpleLogPayload
forall a. ToJSON a => Text -> a -> SimpleLogPayload
sl Text
"module" (Text
"Ecluse.Runtime.Env" :: Text) SimpleLogPayload -> SimpleLogPayload -> SimpleLogPayload
forall a. Semigroup a => a -> a -> a
<> Text -> Text -> SimpleLogPayload
forall a. ToJSON a => Text -> a -> SimpleLogPayload
sl Text
"upstream_host" (HostPort -> Text
hpHost HostPort
authority) SimpleLogPayload -> SimpleLogPayload -> SimpleLogPayload
forall a. Semigroup a => a -> a -> a
<> Text -> Word16 -> SimpleLogPayload
forall a. ToJSON a => Text -> a -> SimpleLogPayload
sl Text
"upstream_port" (HostPort -> Word16
hpPort HostPort
authority)
    (Severity
severity, Text
message) = case CooldownEvent
event of
        CooldownEvent
CoolingDown -> (Severity
WarningS, Text
"public upstream entered cooldown")
        CooldownEvent
Recovered -> (Severity
InfoS, Text
"public upstream left cooldown")