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

{- | The Pilot role's front door. Every decision it acts on is planned before it starts, in
"Ecluse.Pilot.Plan" and the boot arm that spends the plan's refusal, so what is left here is
the effect each plan names.
-}
module Ecluse.Pilot (
    runPilot,
    runExportLoop,
    superviseExportCycles,

    -- * One-shot compilation
    PilotCompileOptions (..),
    UploadRequest (..),
    runPilotCompile,
    PilotUploadUnconfigured (..),
) where

import Conduit (MonadResource, runResourceT)
import Control.Monad.Catch (MonadMask)
import Katip (KatipContext, LogEnv, Severity (InfoS, WarningS), logFM, ls)
import Network.HTTP.Client (Manager)
import UnliftIO (MonadUnliftIO)
import UnliftIO.Async (mapConcurrently_)
import UnliftIO.Concurrent (threadDelay)
import UnliftIO.Exception (throwIO)

import Ecluse.Boot (BootEnv (..), probeServerConfig)
import Ecluse.Composition.Plan (BootPlan (bpS3Endpoint))
import Ecluse.Config (
    AdvisoriesSettings (advDataDir, advUrl),
    AdvisoryStoreUrl,
    AppConfig (cfgAdvisories, cfgEgress),
    Config (configApp, configMounts),
    EgressSettings (egrOperatorContact),
    advisoryStoreUrlText,
 )
import Ecluse.Config.AdvisoryStore (advisoryStoreCapability)
import Ecluse.Core.BuildIdentity (renderUserAgent)
import Ecluse.Core.Ecosystem (ecosystemName, parseEcosystem)
import Ecluse.Core.Osv.Compile (OsvCandidate, candidateDestination, newFeedManagerWithIdentity, promoteCandidate, withOsvCandidate)
import Ecluse.Core.Osv.Ecosystem (osvEcosystemFor, osvEcosystemNamed)
import Ecluse.Core.Osv.Publication (Rebaseline)
import Ecluse.Core.Supervision (
    BackoffSchedule (BackoffSchedule, bsBaseMicros, bsCapMicros),
    superviseLoop,
    transientPolicy,
 )
import Ecluse.Pilot.Plan (
    ExportLoopPlan (ExportIdle, ExportTo),
    ExportTarget (etEcosystem, etEpss),
    PilotCompileOptions (..),
    PilotUploadUnconfigured (..),
    UploadPlan (UploadSkipped, UploadTo),
    UploadRequest (..),
    compileEpssRequirement,
    configuredSources,
    exportCadenceMicros,
    idleCadenceMicros,
    quietTimeFor,
    shrinkPolicyOf,
    unmountedCompileWarning,
    uploadPlan,
    uploadTarget,
 )
import Ecluse.Runtime.Aws.Env (AwsEndpoint)
import Ecluse.Runtime.Aws.Fault (retypeAmazonkaEscapes)
import Ecluse.Runtime.Aws.S3 (buildS3Env)
import Ecluse.Runtime.Log (moduleContext)
import Ecluse.Runtime.Pilot.Export (publishCandidate)
import Ecluse.Runtime.Server (probeOnlyApplication, raceServerAgainstLoop, runWarp)
import Ecluse.Runtime.Telemetry (Telemetry, telemetryTracerProvider)
import Ecluse.Runtime.Telemetry.Instruments (Metrics, advisoryCompileMetricsPortOf, newMetrics)

-- | The Pilot worker mode. The export loop never returns, so the server's return on shutdown cancels it.
runPilot :: BootEnv -> ExportLoopPlan -> IO ()
runPilot :: BootEnv -> ExportLoopPlan -> IO ()
runPilot BootEnv
bootEnv ExportLoopPlan
exportPlan = do
    let cfg :: ServerConfig
cfg = AppConfig -> ServerConfig
probeServerConfig (Config -> AppConfig
configApp (BootEnv -> Config
beConfig BootEnv
bootEnv))
    LogEnv -> Text -> KatipContextT IO () -> IO ()
forall (m :: * -> *) a. LogEnv -> Text -> KatipContextT m a -> m a
moduleContext (BootEnv -> LogEnv
beLogEnv BootEnv
bootEnv) Text
"Ecluse.Pilot" (KatipContextT IO () -> IO ()) -> KatipContextT IO () -> IO ()
forall a b. (a -> b) -> a -> b
$ do
        Severity -> LogStr -> KatipContextT IO ()
forall (m :: * -> *).
(Applicative m, KatipContext m) =>
Severity -> LogStr -> m ()
logFM Severity
InfoS LogStr
"Pilot mode starting up"
        KatipContextT IO () -> KatipContextT IO () -> KatipContextT IO ()
forall (m :: * -> *). MonadUnliftIO m => m () -> m () -> m ()
raceServerAgainstLoop
            (IO () -> KatipContextT IO ()
forall a. IO a -> KatipContextT IO a
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (IO () -> KatipContextT IO ()) -> IO () -> KatipContextT IO ()
forall a b. (a -> b) -> a -> b
$ LogEnv
-> Text
-> ServerConfig
-> (ServerConfig -> IO Application)
-> IO ()
runWarp (BootEnv -> LogEnv
beLogEnv BootEnv
bootEnv) Text
"Pilot health probes" ServerConfig
cfg (Deadlines -> ServerConfig -> IO Application
probeOnlyApplication (BootEnv -> Deadlines
beDeadlines BootEnv
bootEnv)))
            (Telemetry
-> Maybe AwsEndpoint
-> Config
-> ExportLoopPlan
-> KatipContextT IO ()
forall (m :: * -> *).
(MonadMask m, MonadUnliftIO m, KatipContext m) =>
Telemetry -> Maybe AwsEndpoint -> Config -> ExportLoopPlan -> m ()
runExportLoop (BootEnv -> Telemetry
beTelemetry BootEnv
bootEnv) (BootPlan -> Maybe AwsEndpoint
bpS3Endpoint (BootEnv -> BootPlan
beBootPlan BootEnv
bootEnv)) (BootEnv -> Config
beConfig BootEnv
bootEnv) ExportLoopPlan
exportPlan)

-- | Run the loop the boot planned, never returning. Every fault inside a cycle is transient: a cycle has no wiring to fail on.
runExportLoop :: (MonadMask m, MonadUnliftIO m, KatipContext m) => Telemetry -> Maybe AwsEndpoint -> Config -> ExportLoopPlan -> m ()
runExportLoop :: forall (m :: * -> *).
(MonadMask m, MonadUnliftIO m, KatipContext m) =>
Telemetry -> Maybe AwsEndpoint -> Config -> ExportLoopPlan -> m ()
runExportLoop Telemetry
telemetry Maybe AwsEndpoint
s3Endpoint Config
config = \case
    ExportLoopPlan
ExportIdle -> do
        Severity -> LogStr -> m ()
forall (m :: * -> *).
(Applicative m, KatipContext m) =>
Severity -> LogStr -> m ()
logFM Severity
InfoS LogStr
"No advisory store configured for OSV database export; export loop disabled."
        m () -> m ()
forall (f :: * -> *) a b. Applicative f => f a -> f b
forever (Int -> m ()
forall (m :: * -> *). MonadIO m => Int -> m ()
threadDelay Int
idleCadenceMicros)
    ExportTo AdvisoryStoreUrl
store NonEmpty ExportTarget
targets -> do
        Severity -> LogStr -> m ()
forall (m :: * -> *).
(Applicative m, KatipContext m) =>
Severity -> LogStr -> m ()
logFM Severity
InfoS (Text -> LogStr
forall a. StringConv a Text => a -> LogStr
ls (Text
"Export loop starting up. Target store: " Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> AdvisoryStoreUrl -> Text
advisoryStoreUrlText AdvisoryStoreUrl
store))
        -- One instrument set for the whole loop. Rebuilding it per cycle would register
        -- the catalogue again and split each signal across two streams.
        metrics <- IO Metrics -> m Metrics
forall a. IO a -> m a
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (Telemetry -> IO Metrics
newMetrics Telemetry
telemetry)
        feeds <- liftIO (newFeedManagerWithIdentity (renderUserAgent (egrOperatorContact (cfgEgress (configApp config)))))
        superviseExportCycles schedule targets $ \ExportTarget
target -> do
            ResourceT m () -> m ()
forall (m :: * -> *) a. MonadUnliftIO m => ResourceT m a -> m a
runResourceT (Metrics
-> Manager
-> ExportTarget
-> Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> AdvisoryStoreUrl
-> ResourceT m ()
forall (m :: * -> *).
(MonadResource m, MonadMask m, MonadUnliftIO m, KatipContext m) =>
Metrics
-> Manager
-> ExportTarget
-> Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> AdvisoryStoreUrl
-> m ()
exportEcosystem Metrics
metrics Manager
feeds ExportTarget
target Telemetry
telemetry Maybe AwsEndpoint
s3Endpoint AdvisoriesSettings
advisories AdvisoryStoreUrl
store)
            Int -> m ()
forall (m :: * -> *). MonadIO m => Int -> m ()
threadDelay Int
cadence
  where
    advisories :: AdvisoriesSettings
advisories = AppConfig -> AdvisoriesSettings
cfgAdvisories (Config -> AppConfig
configApp Config
config)
    cadence :: Int
cadence = AdvisoriesSettings -> Int
exportCadenceMicros AdvisoriesSettings
advisories
    schedule :: BackoffSchedule
schedule = BackoffSchedule{bsBaseMicros :: Int
bsBaseMicros = Int
cadence, bsCapMicros :: Int
bsCapMicros = Int
cadence}

-- | One supervised cycle loop per ecosystem, side by side, each with its own backoff, so one failing feed holds back no other.
superviseExportCycles :: (MonadUnliftIO m, KatipContext m) => BackoffSchedule -> NonEmpty ExportTarget -> (ExportTarget -> m ()) -> m ()
superviseExportCycles :: forall (m :: * -> *).
(MonadUnliftIO m, KatipContext m) =>
BackoffSchedule
-> NonEmpty ExportTarget -> (ExportTarget -> m ()) -> m ()
superviseExportCycles BackoffSchedule
schedule NonEmpty ExportTarget
targets ExportTarget -> m ()
runCycle =
    -- amazonka hands a failed credential refresh to the cycle thread that discovered the credentials.
    (ExportTarget -> m Void) -> NonEmpty ExportTarget -> m ()
forall (m :: * -> *) (f :: * -> *) a b.
(MonadUnliftIO m, Foldable f) =>
(a -> m b) -> f a -> m ()
mapConcurrently_ (\ExportTarget
target -> SupervisionPolicy -> m () -> m Void
forall (m :: * -> *).
(MonadUnliftIO m, KatipContext m) =>
SupervisionPolicy -> m () -> m Void
superviseLoop (ExportTarget -> SupervisionPolicy
policyFor ExportTarget
target) (m () -> m ()
forall (m :: * -> *) a. MonadUnliftIO m => m a -> m a
retypeAmazonkaEscapes (ExportTarget -> m ()
runCycle ExportTarget
target))) NonEmpty ExportTarget
targets
  where
    policyFor :: ExportTarget -> SupervisionPolicy
policyFor ExportTarget
target = Text -> BackoffSchedule -> SupervisionPolicy
transientPolicy (Text
"pilot-export-" Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Ecosystem -> Text
ecosystemName (ExportTarget -> Ecosystem
etEcosystem ExportTarget
target)) BackoffSchedule
schedule

-- One full cycle for one ecosystem: compile its OSV artifact, publish it, then keep it locally.
exportEcosystem :: (MonadResource m, MonadMask m, MonadUnliftIO m, KatipContext m) => Metrics -> Manager -> ExportTarget -> Telemetry -> Maybe AwsEndpoint -> AdvisoriesSettings -> AdvisoryStoreUrl -> m ()
exportEcosystem :: forall (m :: * -> *).
(MonadResource m, MonadMask m, MonadUnliftIO m, KatipContext m) =>
Metrics
-> Manager
-> ExportTarget
-> Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> AdvisoryStoreUrl
-> m ()
exportEcosystem Metrics
metrics Manager
feeds ExportTarget
target Telemetry
telemetry Maybe AwsEndpoint
s3Endpoint AdvisoriesSettings
advisories AdvisoryStoreUrl
store = do
    Severity -> LogStr -> m ()
forall (m :: * -> *).
(Applicative m, KatipContext m) =>
Severity -> LogStr -> m ()
logFM Severity
InfoS (Text -> LogStr
forall a. StringConv a Text => a -> LogStr
ls (Text
"Starting " Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Ecosystem -> Text
ecosystemName Ecosystem
eco Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
" OSV database compilation"))
    AdvisoryCompileMetricsPort
-> Maybe TracerProvider
-> Manager
-> String
-> OsvEcosystem
-> EpssRequirement
-> CompileSources
-> QuietTime
-> (OsvCandidate -> m ())
-> m ()
forall (m :: * -> *) a.
(MonadResource m, MonadMask m, MonadUnliftIO m, KatipContext m) =>
AdvisoryCompileMetricsPort
-> Maybe TracerProvider
-> Manager
-> String
-> OsvEcosystem
-> EpssRequirement
-> CompileSources
-> QuietTime
-> (OsvCandidate -> m a)
-> m a
withOsvCandidate
        (Metrics -> Maybe Ecosystem -> AdvisoryCompileMetricsPort
advisoryCompileMetricsPortOf Metrics
metrics (Ecosystem -> Maybe Ecosystem
forall a. a -> Maybe a
Just Ecosystem
eco))
        (Telemetry -> Maybe TracerProvider
telemetryTracerProvider Telemetry
telemetry)
        Manager
feeds
        (AdvisoriesSettings -> String
advDataDir AdvisoriesSettings
advisories)
        OsvEcosystem
osvEco
        (ExportTarget -> EpssRequirement
etEpss ExportTarget
target)
        (AdvisoriesSettings -> OsvEcosystem -> CompileSources
configuredSources AdvisoriesSettings
advisories OsvEcosystem
osvEco)
        (AdvisoriesSettings -> Maybe Ecosystem -> QuietTime
quietTimeFor AdvisoriesSettings
advisories (Ecosystem -> Maybe Ecosystem
forall a. a -> Maybe a
Just Ecosystem
eco))
        (\OsvCandidate
candidate -> Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> AdvisoryStoreUrl
-> Maybe Rebaseline
-> OsvCandidate
-> m ()
forall (m :: * -> *).
(MonadUnliftIO m, KatipContext m) =>
Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> AdvisoryStoreUrl
-> Maybe Rebaseline
-> OsvCandidate
-> m ()
publishToStore Telemetry
telemetry Maybe AwsEndpoint
s3Endpoint AdvisoriesSettings
advisories AdvisoryStoreUrl
store Maybe Rebaseline
forall a. Maybe a
Nothing OsvCandidate
candidate m () -> m () -> m ()
forall a b. m a -> m b -> m b
forall (m :: * -> *) a b. Monad m => m a -> m b -> m b
>> m String -> m ()
forall (f :: * -> *) a. Functor f => f a -> f ()
void (OsvCandidate -> m String
forall (m :: * -> *). MonadIO m => OsvCandidate -> m String
promoteCandidate OsvCandidate
candidate))
  where
    eco :: Ecosystem
eco = ExportTarget -> Ecosystem
etEcosystem ExportTarget
target
    osvEco :: OsvEcosystem
osvEco = Ecosystem -> OsvEcosystem
osvEcosystemFor Ecosystem
eco

-- Publish to the key 'uploadTarget' derives, where the sync reads. A stop throws, so the loop's
-- supervision retries it on the cadence and a one-shot run exits non-zero.
publishToStore :: (MonadUnliftIO m, KatipContext m) => Telemetry -> Maybe AwsEndpoint -> AdvisoriesSettings -> AdvisoryStoreUrl -> Maybe Rebaseline -> OsvCandidate -> m ()
publishToStore :: forall (m :: * -> *).
(MonadUnliftIO m, KatipContext m) =>
Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> AdvisoryStoreUrl
-> Maybe Rebaseline
-> OsvCandidate
-> m ()
publishToStore Telemetry
telemetry Maybe AwsEndpoint
s3Endpoint AdvisoriesSettings
advisories AdvisoryStoreUrl
store Maybe Rebaseline
rebaseline OsvCandidate
candidate = do
    env <- IO Env -> m Env
forall a. IO a -> m a
forall (m :: * -> *) a. MonadIO m => IO a -> m a
liftIO (Maybe AwsEndpoint -> IO Env
buildS3Env Maybe AwsEndpoint
s3Endpoint)
    let (bucket, key) = uploadTarget store (candidateDestination candidate)
    publishCandidate (telemetryTracerProvider telemetry) env (shrinkPolicyOf advisories) (advisoryStoreCapability store) rebaseline bucket key candidate
        >>= either throwIO (const pass)

-- Act on a planned upload. A skipped one is the caller's success path, not an error.
runUploadPlan :: (MonadUnliftIO m, KatipContext m) => Telemetry -> Maybe AwsEndpoint -> AdvisoriesSettings -> UploadPlan -> OsvCandidate -> m ()
runUploadPlan :: forall (m :: * -> *).
(MonadUnliftIO m, KatipContext m) =>
Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> UploadPlan
-> OsvCandidate
-> m ()
runUploadPlan Telemetry
telemetry Maybe AwsEndpoint
s3Endpoint AdvisoriesSettings
advisories UploadPlan
plan OsvCandidate
candidate = case UploadPlan
plan of
    UploadPlan
UploadSkipped -> m ()
forall (f :: * -> *). Applicative f => f ()
pass
    UploadTo AdvisoryStoreUrl
store Maybe Rebaseline
rebaseline -> Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> AdvisoryStoreUrl
-> Maybe Rebaseline
-> OsvCandidate
-> m ()
forall (m :: * -> *).
(MonadUnliftIO m, KatipContext m) =>
Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> AdvisoryStoreUrl
-> Maybe Rebaseline
-> OsvCandidate
-> m ()
publishToStore Telemetry
telemetry Maybe AwsEndpoint
s3Endpoint AdvisoriesSettings
advisories AdvisoryStoreUrl
store Maybe Rebaseline
rebaseline OsvCandidate
candidate

-- | Compile once, optionally publish, and return the path. A compile failure or a publication refusal throws, so the command exits non-zero.
runPilotCompile :: LogEnv -> Telemetry -> Maybe AwsEndpoint -> Config -> PilotCompileOptions -> IO FilePath
runPilotCompile :: LogEnv
-> Telemetry
-> Maybe AwsEndpoint
-> Config
-> PilotCompileOptions
-> IO String
runPilotCompile LogEnv
logEnv Telemetry
telemetry Maybe AwsEndpoint
s3Endpoint Config
config PilotCompileOptions
opts = do
    metrics <- Telemetry -> IO Metrics
newMetrics Telemetry
telemetry
    feeds <- newFeedManagerWithIdentity (renderUserAgent (egrOperatorContact (cfgEgress (configApp config))))
    -- The metric label domain is the closed 'Ecosystem' enum. A one-shot compile of a name
    -- outside it still writes its artifact, and records no series.
    let compileMetrics = Metrics -> Maybe Ecosystem -> AdvisoryCompileMetricsPort
advisoryCompileMetricsPortOf Metrics
metrics (Text -> Maybe Ecosystem
parseEcosystem (PilotCompileOptions -> Text
pcoEcosystem PilotCompileOptions
opts))
    moduleContext logEnv "Ecluse.Pilot" $
        runResourceT $ do
            -- Raised before the compile, so an upload the wiring cannot satisfy fails
            -- without first compiling the artifact it could never publish.
            plan <- either throwIO pure planned
            traverse_ (logFM WarningS . ls) (unmountedCompileWarning (configMounts config) opts)
            withOsvCandidate
                compileMetrics
                (telemetryTracerProvider telemetry)
                feeds
                (pcoOutDir opts)
                osvEco
                (compileEpssRequirement advisories (configMounts config) opts)
                (configuredSources advisories osvEco)
                (quietTimeFor advisories (parseEcosystem (pcoEcosystem opts)))
                (\OsvCandidate
candidate -> Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> UploadPlan
-> OsvCandidate
-> ResourceT (KatipContextT IO) ()
forall (m :: * -> *).
(MonadUnliftIO m, KatipContext m) =>
Telemetry
-> Maybe AwsEndpoint
-> AdvisoriesSettings
-> UploadPlan
-> OsvCandidate
-> m ()
runUploadPlan Telemetry
telemetry Maybe AwsEndpoint
s3Endpoint AdvisoriesSettings
advisories UploadPlan
plan OsvCandidate
candidate ResourceT (KatipContextT IO) ()
-> ResourceT (KatipContextT IO) String
-> ResourceT (KatipContextT IO) String
forall a b.
ResourceT (KatipContextT IO) a
-> ResourceT (KatipContextT IO) b -> ResourceT (KatipContextT IO) b
forall (m :: * -> *) a b. Monad m => m a -> m b -> m b
>> OsvCandidate -> ResourceT (KatipContextT IO) String
forall (m :: * -> *). MonadIO m => OsvCandidate -> m String
promoteCandidate OsvCandidate
candidate)
  where
    advisories :: AdvisoriesSettings
advisories = AppConfig -> AdvisoriesSettings
cfgAdvisories (Config -> AppConfig
configApp Config
config)
    osvEco :: OsvEcosystem
osvEco = Text -> OsvEcosystem
osvEcosystemNamed (PilotCompileOptions -> Text
pcoEcosystem PilotCompileOptions
opts)
    planned :: Either PilotUploadUnconfigured UploadPlan
planned = PilotCompileOptions
-> Maybe AdvisoryStoreUrl
-> Either PilotUploadUnconfigured UploadPlan
uploadPlan PilotCompileOptions
opts (AdvisoriesSettings -> Maybe AdvisoryStoreUrl
advUrl AdvisoriesSettings
advisories)