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

{- | Registry capabilities used by the ecosystem-neutral pipeline.
Adapters own wire formats and share exact source-entry selection for served metadata.
-}
module Ecluse.Core.Registry.Adapter.Capability (
    -- * Metadata
    AdapterMetadata (..),

    -- * Artifact requests
    AdapterArtifact (..),
    PrivateArtifactAddressing (..),

    -- * Publish
    AdapterPublish (..),
    PublishRequestBody (..),
    PublishExtras (..),
    MirrorRequirements (..),
    WorkerMetadataRead (..),
    MirrorStateRequirement (..),
    durableMirrorDocuments,
    companionsAgree,
    UploadEndpointRequirement (..),
    UploadIdentityRequirement (..),

    -- * Names
    ProjectName,

    -- * Store maintenance
    AdapterMaintenance (..),
    StoreListing (..),
    VersionDelete (..),
) where

import Data.JsonStream.Lexer (Cursor)
import Network.HTTP.Client (Request)
import Network.HTTP.Types.Header (RequestHeaders)

import Ecluse.Core.Credential (ClientCredential, Secret)
import Ecluse.Core.Mirror.Documents (MirrorDocuments)
import Ecluse.Core.Mirror.State.Format (MirrorStateFormat (msfCompanions))
import Ecluse.Core.Package (PackageName)
import Ecluse.Core.Package.Merge (MergePlan, SourceId)
import Ecluse.Core.Registry (
    CompanionRequirement (NativeCompanions),
    FetchFault,
    PublishBodyFault,
    PublishRelayResponse,
    RegistryResponse,
    UrlFormationError,
 )
import Ecluse.Core.Registry.CachedDocument (CachedDoc)
import Ecluse.Core.Registry.Json.Walk (Step)
import Ecluse.Core.Registry.Maintenance (StoreRefusal)
import Ecluse.Core.Registry.Maintenance.NameSpace (NameAlphabet)
import Ecluse.Core.Registry.Metadata.Fetch.Preparation (PrepareRead)
import Ecluse.Core.Registry.Origin (OriginClient)
import Ecluse.Core.Registry.Publish (PublishCodec (pcMirrorCompanion))
import Ecluse.Core.Registry.Request (CredentialMapping, ServicePresentation, nativePresentation)
import Ecluse.Core.Registry.ServedDocument (RenderRefused)
import Ecluse.Core.Security (Limits)
import Ecluse.Core.Server.Admission.Types (ChargeFactors)
import Ecluse.Core.Snapshot (Snapshot)
import Ecluse.Core.Version (Version)

-- | Canonicalise a raw name under one ecosystem's grammar: the one parser every caller reaches a 'PackageName' through.
type ProjectName = Text -> Maybe PackageName

-- | The ecosystem's metadata read, served-document assembly, and encoding ('Ecluse.Core.Server.Context.pdMetadata').
data AdapterMetadata = AdapterMetadata
    { AdapterMetadata -> PrepareRead
metadataRead :: PrepareRead
    -- ^ Prepare under the selected origin before reading its metadata.
    , AdapterMetadata
-> Text
-> Map SourceId (Snapshot CachedDoc)
-> MergePlan
-> Maybe CachedDoc
-> CachedDoc
metadataAssemble :: Text -> Map SourceId (Snapshot CachedDoc) -> MergePlan -> Maybe CachedDoc -> CachedDoc
    -- ^ Select exact admitted entries from the supplied snapshots before rendering their wire shape.
    , AdapterMetadata -> CachedDoc -> Either RenderRefused LByteString
metadataSerialise :: CachedDoc -> Either RenderRefused LByteString
    -- ^ Encode an assembled served document ('CachedDoc') to its wire bytes, or refuse a damaged render.
    , AdapterMetadata -> ChargeFactors
metadataChargeFactors :: ChargeFactors
    -- ^ What this ecosystem's full reads and listings charge the memory budget per source byte.
    }

-- | Private artifact locations come from a conventional path or authoritative index metadata.
data PrivateArtifactAddressing
    = ConventionalArtifactPath
    | IndexedArtifactLocation
    | -- | Requires metadata admission before discovery or index workspace allocation.
      AdmittedIndexedArtifactLocation
    deriving stock (PrivateArtifactAddressing -> PrivateArtifactAddressing -> Bool
(PrivateArtifactAddressing -> PrivateArtifactAddressing -> Bool)
-> (PrivateArtifactAddressing -> PrivateArtifactAddressing -> Bool)
-> Eq PrivateArtifactAddressing
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: PrivateArtifactAddressing -> PrivateArtifactAddressing -> Bool
== :: PrivateArtifactAddressing -> PrivateArtifactAddressing -> Bool
$c/= :: PrivateArtifactAddressing -> PrivateArtifactAddressing -> Bool
/= :: PrivateArtifactAddressing -> PrivateArtifactAddressing -> Bool
Eq, SourceId -> PrivateArtifactAddressing -> ShowS
[PrivateArtifactAddressing] -> ShowS
PrivateArtifactAddressing -> String
(SourceId -> PrivateArtifactAddressing -> ShowS)
-> (PrivateArtifactAddressing -> String)
-> ([PrivateArtifactAddressing] -> ShowS)
-> Show PrivateArtifactAddressing
forall a.
(SourceId -> a -> ShowS)
-> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: SourceId -> PrivateArtifactAddressing -> ShowS
showsPrec :: SourceId -> PrivateArtifactAddressing -> ShowS
$cshow :: PrivateArtifactAddressing -> String
show :: PrivateArtifactAddressing -> String
$cshowList :: [PrivateArtifactAddressing] -> ShowS
showList :: [PrivateArtifactAddressing] -> ShowS
Show)

-- | Artifact request formation by filename or authoritative URL, shared by serve and worker ('Ecluse.Core.Server.Context.pdArtifact').
data AdapterArtifact = AdapterArtifact
    { AdapterArtifact
-> OriginClient
-> PackageName
-> Text
-> Either UrlFormationError Request
artifactByFile :: OriginClient -> PackageName -> Text -> Either UrlFormationError Request
    -- ^ Address a trusted origin by the conventional filename path under its base URL.
    , AdapterArtifact
-> Maybe ClientCredential
-> Text
-> Either UrlFormationError Request
artifactByUrl :: Maybe ClientCredential -> Text -> Either UrlFormationError Request
    -- ^ Build the request at the authoritative upstream URL. It names no origin, because the mirror worker has none.
    , AdapterArtifact -> [Text]
artifactHosts :: [Text]
    -- ^ Hosts the same-host tarball gate admits unnamed. Empty for npm, whose artifacts ride the registry host.
    , AdapterArtifact -> PrivateArtifactAddressing
artifactPrivateAddressing :: PrivateArtifactAddressing
    -- ^ How private requests find their artifact location, independent of the admitted public hosts.
    }

-- | Original request bytes and their declared media type, retained under byte admission.
data PublishRequestBody = PublishRequestBody
    { PublishRequestBody -> ByteString
publishBodyBytes :: ByteString
    , PublishRequestBody -> Maybe ByteString
publishBodyContentType :: Maybe ByteString
    , PublishRequestBody -> PublishExtras
publishBodyExtras :: PublishExtras
    }

-- | Checked native publication headers. Secrets never enter durable mirror state.
data PublishExtras
    = NoPublishExtras
    | -- | A one-time password the caller presented for this publication.
      PublishOneTimePassword Secret
    deriving stock (PublishExtras -> PublishExtras -> Bool
(PublishExtras -> PublishExtras -> Bool)
-> (PublishExtras -> PublishExtras -> Bool) -> Eq PublishExtras
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: PublishExtras -> PublishExtras -> Bool
== :: PublishExtras -> PublishExtras -> Bool
$c/= :: PublishExtras -> PublishExtras -> Bool
/= :: PublishExtras -> PublishExtras -> Bool
Eq, SourceId -> PublishExtras -> ShowS
[PublishExtras] -> ShowS
PublishExtras -> String
(SourceId -> PublishExtras -> ShowS)
-> (PublishExtras -> String)
-> ([PublishExtras] -> ShowS)
-> Show PublishExtras
forall a.
(SourceId -> a -> ShowS)
-> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: SourceId -> PublishExtras -> ShowS
showsPrec :: SourceId -> PublishExtras -> ShowS
$cshow :: PublishExtras -> String
show :: PublishExtras -> String
$cshowList :: [PublishExtras] -> ShowS
showList :: [PublishExtras] -> ShowS
Show)

-- | Worker reads use cached facts, charged chunks, or native workspace reservations.
data WorkerMetadataRead
    = CachedWorkerRead
    | ChargedWorkerRead PrepareRead
    | NativeChargedWorkerRead PrepareRead

-- | Completion uses native inventory or requires durable version state.
data MirrorStateRequirement
    = NativeVersionState
    | -- | Completion and outage reads restore retained source documents through these operations.
      DurableVersionState MirrorDocuments

-- | The durable format's document operations, absent where native inventory proves completion.
durableMirrorDocuments :: MirrorStateRequirement -> Maybe MirrorDocuments
durableMirrorDocuments :: MirrorStateRequirement -> Maybe MirrorDocuments
durableMirrorDocuments = \case
    MirrorStateRequirement
NativeVersionState -> Maybe MirrorDocuments
forall a. Maybe a
Nothing
    DurableVersionState MirrorDocuments
documents -> MirrorDocuments -> Maybe MirrorDocuments
forall a. a -> Maybe a
Just MirrorDocuments
documents

-- | Whether the protocol writes at its read root or at a separate endpoint.
data UploadEndpointRequirement
    = ReadRootUpload
    | ExplicitUploadEndpoint
    deriving stock (UploadEndpointRequirement -> UploadEndpointRequirement -> Bool
(UploadEndpointRequirement -> UploadEndpointRequirement -> Bool)
-> (UploadEndpointRequirement -> UploadEndpointRequirement -> Bool)
-> Eq UploadEndpointRequirement
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: UploadEndpointRequirement -> UploadEndpointRequirement -> Bool
== :: UploadEndpointRequirement -> UploadEndpointRequirement -> Bool
$c/= :: UploadEndpointRequirement -> UploadEndpointRequirement -> Bool
/= :: UploadEndpointRequirement -> UploadEndpointRequirement -> Bool
Eq, SourceId -> UploadEndpointRequirement -> ShowS
[UploadEndpointRequirement] -> ShowS
UploadEndpointRequirement -> String
(SourceId -> UploadEndpointRequirement -> ShowS)
-> (UploadEndpointRequirement -> String)
-> ([UploadEndpointRequirement] -> ShowS)
-> Show UploadEndpointRequirement
forall a.
(SourceId -> a -> ShowS)
-> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: SourceId -> UploadEndpointRequirement -> ShowS
showsPrec :: SourceId -> UploadEndpointRequirement -> ShowS
$cshow :: UploadEndpointRequirement -> String
show :: UploadEndpointRequirement -> String
$cshowList :: [UploadEndpointRequirement] -> ShowS
showList :: [UploadEndpointRequirement] -> ShowS
Show)

-- | Named protocols require a username when using a static token.
data UploadIdentityRequirement
    = TokenIdentity
    | NamedIdentity
    deriving stock (UploadIdentityRequirement -> UploadIdentityRequirement -> Bool
(UploadIdentityRequirement -> UploadIdentityRequirement -> Bool)
-> (UploadIdentityRequirement -> UploadIdentityRequirement -> Bool)
-> Eq UploadIdentityRequirement
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: UploadIdentityRequirement -> UploadIdentityRequirement -> Bool
== :: UploadIdentityRequirement -> UploadIdentityRequirement -> Bool
$c/= :: UploadIdentityRequirement -> UploadIdentityRequirement -> Bool
/= :: UploadIdentityRequirement -> UploadIdentityRequirement -> Bool
Eq, SourceId -> UploadIdentityRequirement -> ShowS
[UploadIdentityRequirement] -> ShowS
UploadIdentityRequirement -> String
(SourceId -> UploadIdentityRequirement -> ShowS)
-> (UploadIdentityRequirement -> String)
-> ([UploadIdentityRequirement] -> ShowS)
-> Show UploadIdentityRequirement
forall a.
(SourceId -> a -> ShowS)
-> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: SourceId -> UploadIdentityRequirement -> ShowS
showsPrec :: SourceId -> UploadIdentityRequirement -> ShowS
$cshow :: UploadIdentityRequirement -> String
show :: UploadIdentityRequirement -> String
$cshowList :: [UploadIdentityRequirement] -> ShowS
showList :: [UploadIdentityRequirement] -> ShowS
Show)

-- | Static mirror obligations, separate from runtime completion observations.
data MirrorRequirements = MirrorRequirements
    { MirrorRequirements -> WorkerMetadataRead
mirrorWorkerRead :: WorkerMetadataRead
    -- ^ Cache and charging policy for worker metadata.
    , MirrorRequirements -> MirrorStateFormat
mirrorStateFormat :: MirrorStateFormat
    -- ^ How mirror state records, weighs and rechecks the format's read data.
    , MirrorRequirements -> MirrorStateRequirement
mirrorStateRequirement :: MirrorStateRequirement
    -- ^ State the configured mirror requires at boot.
    }

-- | Native relay, identity validation, and mirror publication for one ecosystem.
data AdapterPublish = AdapterPublish
    { AdapterPublish -> CredentialMapping
publishCredential :: CredentialMapping
    -- ^ Recover publication credentials independently from read credentials.
    , AdapterPublish
-> RequestHeaders -> Either PublishBodyFault PublishExtras
publishRequestExtras :: RequestHeaders -> Either PublishBodyFault PublishExtras
    -- ^ Admit only native publication headers before buffering the body.
    , AdapterPublish
-> ServicePresentation
-> OriginClient
-> PackageName
-> PublishRequestBody
-> IO (Either FetchFault PublishRelayResponse)
publishRelay :: ServicePresentation -> OriginClient -> PackageName -> PublishRequestBody -> IO (Either FetchFault PublishRelayResponse)
    -- ^ Relay a client's publish document to the target named as the origin, under the target store's presentation, and return its answer.
    , AdapterPublish
-> Limits
-> (SourceId -> IO ())
-> Text
-> PublishRequestBody
-> IO (Either PublishBodyFault [Text])
publishUploadClaims :: Limits -> (Int -> IO ()) -> Text -> PublishRequestBody -> IO (Either PublishBodyFault [Text])
    -- ^ Check claims before target IO against the mount's own base URL. Charge extra workspace as an absolute total.
    , AdapterPublish -> ServicePresentation -> PublishCodec
publishCodec :: ServicePresentation -> PublishCodec
    -- ^ The mirror write's document, requests, probe, and status semantics under the target store's presentation. The transport owns the manager, mint, and fault classification.
    , AdapterPublish -> MirrorRequirements
publishMirrorRequirements :: MirrorRequirements
    -- ^ The worker read and boot obligations for configured mirrors.
    , AdapterPublish -> UploadEndpointRequirement
publishUploadEndpoint :: UploadEndpointRequirement
    -- ^ Where mirror and client uploads go: derived from the read root, or a separate endpoint.
    , AdapterPublish -> UploadIdentityRequirement
publishIdentity :: UploadIdentityRequirement
    -- ^ Static credential requirements for mirror and client uploads.
    }

-- | Whether the mirror codec prepares native companions exactly where the state format requires them.
companionsAgree :: AdapterPublish -> Bool
companionsAgree :: AdapterPublish -> Bool
companionsAgree AdapterPublish
publish = Maybe MirrorCompanion -> Bool
forall a. Maybe a -> Bool
isJust (PublishCodec -> Maybe MirrorCompanion
pcMirrorCompanion (AdapterPublish -> ServicePresentation -> PublishCodec
publishCodec AdapterPublish
publish ServicePresentation
nativePresentation)) Bool -> Bool -> Bool
forall a. Eq a => a -> a -> Bool
== (CompanionRequirement
required CompanionRequirement -> CompanionRequirement -> Bool
forall a. Eq a => a -> a -> Bool
== CompanionRequirement
NativeCompanions)
  where
    required :: CompanionRequirement
required = MirrorStateFormat -> CompanionRequirement
msfCompanions (MirrorRequirements -> MirrorStateFormat
mirrorStateFormat (AdapterPublish -> MirrorRequirements
publishMirrorRequirements AdapterPublish
publish))

-- | Store maintenance verbs for "Ecluse.Core.Registry.Maintenance.Protocol". A missing verb makes the Dredger refuse.
data AdapterMaintenance = AdapterMaintenance
    { AdapterMaintenance -> Maybe StoreListing
maintenanceListing :: Maybe StoreListing
    -- ^ How the protocol enumerates a store's packages, where it can.
    , AdapterMaintenance -> Maybe VersionDelete
maintenanceVersionDelete :: Maybe VersionDelete
    -- ^ How the protocol deletes one version, where it can.
    , AdapterMaintenance -> NameAlphabet
maintenanceAlphabet :: NameAlphabet
    -- ^ The characters a name may begin with: the buckets a full walk covers one at a time.
    }

-- | The protocol's own listing of a store. A public registry may refuse it, and the caller reports a non-@200@.
data StoreListing = StoreListing
    { StoreListing -> OriginClient -> Either UrlFormationError Request
listingRequest :: OriginClient -> Either UrlFormationError Request
    -- ^ Form the listing read against the store.
    , StoreListing -> Cursor -> Step [PackageName]
listingWalk :: Cursor -> Step [PackageName]
    -- ^ Stream names while skipping unrelated per-package metadata.
    }

-- | One version's delete requests and their own document read, since an install-optimised read may omit the revision.
data VersionDelete = VersionDelete
    { VersionDelete
-> OriginClient -> PackageName -> Either UrlFormationError Request
deleteDocumentRequest :: OriginClient -> PackageName -> Either UrlFormationError Request
    -- ^ Form the read of the document the delete requests are built from.
    , VersionDelete
-> OriginClient
-> PackageName
-> Version
-> RegistryResponse
-> Either StoreRefusal (NonEmpty Request)
deleteRequests ::
        OriginClient ->
        PackageName ->
        Version ->
        RegistryResponse ->
        Either StoreRefusal (NonEmpty Request)
    -- ^ The ordered requests that remove one version, all of them needed, or why the document admits none.
    }