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

-- | Prepare metadata reads only after the caller selects an origin and its credentials.
module Ecluse.Core.Registry.Metadata.Fetch.Preparation (
    PrepareRead (PrepareRead),
    staticRead,
    prepareRead,
    presentedRead,
    bindToOrigin,
    canChargeFullReadWorkspace,
    prepareManifest,
    prepareVersion,
) where

import Ecluse.Core.Package (PackageName)
import Ecluse.Core.Registry (UrlFormationError)
import Ecluse.Core.Registry.Metadata (MetadataError (MetadataUndecodable), VersionRead)
import Ecluse.Core.Registry.Metadata.Fetch (fetchManifest, fetchVersion)
import Ecluse.Core.Registry.Metadata.Fetch.Types (EcosystemRead (..), ManifestFetch)
import Ecluse.Core.Registry.Origin (OriginClient)
import Ecluse.Core.Registry.Request (CredentialMapping, baseRequestUrl, presentedRequest)
import Ecluse.Core.Security.Egress (registryUrlText)
import Ecluse.Core.Telemetry.Span (TracingPort)
import Ecluse.Core.Version (Version)

-- | Origin-bound factories may capture operation callbacks. Static factories receive no origin.
data PrepareRead
    = StaticRead ~EcosystemRead
    | PrepareRead (OriginClient -> IO (Either MetadataError EcosystemRead))

-- | Reuse a reader that cannot bind callbacks from the selected origin.
staticRead :: EcosystemRead -> PrepareRead
staticRead :: EcosystemRead -> PrepareRead
staticRead = EcosystemRead -> PrepareRead
StaticRead

-- | Prepare a reader under the caller-selected origin's authority and limits.
prepareRead :: PrepareRead -> OriginClient -> IO (Either MetadataError EcosystemRead)
prepareRead :: PrepareRead
-> OriginClient -> IO (Either MetadataError EcosystemRead)
prepareRead = \case
    StaticRead EcosystemRead
nativeRead -> \OriginClient
_ -> Either MetadataError EcosystemRead
-> IO (Either MetadataError EcosystemRead)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (EcosystemRead -> Either MetadataError EcosystemRead
forall a b. b -> Either a b
Right EcosystemRead
nativeRead)
    PrepareRead OriginClient -> IO (Either MetadataError EcosystemRead)
prepare -> OriginClient -> IO (Either MetadataError EcosystemRead)
prepare

{- | Present the reader's credential under @mapping@ through 'presentedRequest'. A static reader
stays static, and the reader's own request checks still run.
-}
presentedRead :: CredentialMapping -> PrepareRead -> PrepareRead
presentedRead :: CredentialMapping -> PrepareRead -> PrepareRead
presentedRead CredentialMapping
mapping = \case
    StaticRead EcosystemRead
nativeRead -> EcosystemRead -> PrepareRead
StaticRead (EcosystemRead -> EcosystemRead
present EcosystemRead
nativeRead)
    PrepareRead OriginClient -> IO (Either MetadataError EcosystemRead)
prepare -> (OriginClient -> IO (Either MetadataError EcosystemRead))
-> PrepareRead
PrepareRead ((Either MetadataError EcosystemRead
 -> Either MetadataError EcosystemRead)
-> IO (Either MetadataError EcosystemRead)
-> IO (Either MetadataError EcosystemRead)
forall a b. (a -> b) -> IO a -> IO b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ((EcosystemRead -> EcosystemRead)
-> Either MetadataError EcosystemRead
-> Either MetadataError EcosystemRead
forall a b.
(a -> b) -> Either MetadataError a -> Either MetadataError b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap EcosystemRead -> EcosystemRead
present) (IO (Either MetadataError EcosystemRead)
 -> IO (Either MetadataError EcosystemRead))
-> (OriginClient -> IO (Either MetadataError EcosystemRead))
-> OriginClient
-> IO (Either MetadataError EcosystemRead)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. OriginClient -> IO (Either MetadataError EcosystemRead)
prepare)
  where
    present :: EcosystemRead -> EcosystemRead
present EcosystemRead
nativeRead = EcosystemRead
nativeRead{erRequest = \BaseRequest
base Maybe ClientCredential
credential PackageName
name -> CredentialMapping
-> Maybe ClientCredential
-> (Maybe ClientCredential -> Either UrlFormationError Request)
-> Either UrlFormationError Request
forall e.
CredentialMapping
-> Maybe ClientCredential
-> (Maybe ClientCredential -> Either e Request)
-> Either e Request
presentedRequest CredentialMapping
mapping Maybe ClientCredential
credential (\Maybe ClientCredential
anonymous -> EcosystemRead
-> BaseRequest
-> Maybe ClientCredential
-> PackageName
-> Either UrlFormationError Request
erRequest EcosystemRead
nativeRead BaseRequest
base Maybe ClientCredential
anonymous PackageName
name)}

{- | Hold a prepared reader to the origin at @root@: a request under another base is refused with
@refusal@, and a finish located against another base is undecodable.
-}
bindToOrigin :: UrlFormationError -> Text -> EcosystemRead -> EcosystemRead
bindToOrigin :: UrlFormationError -> Text -> EcosystemRead -> EcosystemRead
bindToOrigin UrlFormationError
refusal Text
root EcosystemRead{BaseRequest
-> Maybe ClientCredential
-> PackageName
-> Either UrlFormationError Request
erRequest :: EcosystemRead
-> BaseRequest
-> Maybe ClientCredential
-> PackageName
-> Either UrlFormationError Request
erRequest :: BaseRequest
-> Maybe ClientCredential
-> PackageName
-> Either UrlFormationError Request
erRequest, [Text]
erUniqueFields :: [Text]
erUniqueFields :: EcosystemRead -> [Text]
erUniqueFields, Limits -> PackageName -> Text -> DocumentWalk full
erWalkFull :: Limits -> PackageName -> Text -> DocumentWalk full
erWalkFull :: ()
erWalkFull, Limits
-> PackageName
-> Text
-> StreamResult full
-> Either MetadataError (PackageInfo, CachedDoc)
erFinishFull :: Limits
-> PackageName
-> Text
-> StreamResult full
-> Either MetadataError (PackageInfo, CachedDoc)
erFinishFull :: ()
erFinishFull, full -> RetainedEntries
erRetainedEntries :: full -> RetainedEntries
erRetainedEntries :: ()
erRetainedEntries, Limits -> PackageName -> Version -> DocumentWalk selected
erWalkSelected :: Limits -> PackageName -> Version -> DocumentWalk selected
erWalkSelected :: ()
erWalkSelected, Limits
-> PackageName
-> Text
-> Version
-> StreamResult selected
-> Either MetadataError VersionRead
erFinishSelected :: Limits
-> PackageName
-> Text
-> Version
-> StreamResult selected
-> Either MetadataError VersionRead
erFinishSelected :: ()
erFinishSelected} =
    EcosystemRead
        { erRequest :: BaseRequest
-> Maybe ClientCredential
-> PackageName
-> Either UrlFormationError Request
erRequest = \BaseRequest
base Maybe ClientCredential
credential PackageName
name -> do
            Bool -> Either UrlFormationError () -> Either UrlFormationError ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
unless (RegistryUrl -> Text
registryUrlText (BaseRequest -> RegistryUrl
baseRequestUrl BaseRequest
base) Text -> Text -> Bool
forall a. Eq a => a -> a -> Bool
== Text
root) (UrlFormationError -> Either UrlFormationError ()
forall a b. a -> Either a b
Left UrlFormationError
refusal)
            BaseRequest
-> Maybe ClientCredential
-> PackageName
-> Either UrlFormationError Request
erRequest BaseRequest
base Maybe ClientCredential
credential PackageName
name
        , [Text]
erUniqueFields :: [Text]
erUniqueFields :: [Text]
erUniqueFields
        , Limits -> PackageName -> Text -> DocumentWalk full
erWalkFull :: Limits -> PackageName -> Text -> DocumentWalk full
erWalkFull :: Limits -> PackageName -> Text -> DocumentWalk full
erWalkFull
        , erFinishFull :: Limits
-> PackageName
-> Text
-> StreamResult full
-> Either MetadataError (PackageInfo, CachedDoc)
erFinishFull = \Limits
limits PackageName
name Text
base StreamResult full
streamed -> do
            Bool -> Either MetadataError () -> Either MetadataError ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
unless (Text
base Text -> Text -> Bool
forall a. Eq a => a -> a -> Bool
== Text
root) (MetadataError -> Either MetadataError ()
forall a b. a -> Either a b
Left MetadataError
MetadataUndecodable)
            Limits
-> PackageName
-> Text
-> StreamResult full
-> Either MetadataError (PackageInfo, CachedDoc)
erFinishFull Limits
limits PackageName
name Text
base StreamResult full
streamed
        , full -> RetainedEntries
erRetainedEntries :: full -> RetainedEntries
erRetainedEntries :: full -> RetainedEntries
erRetainedEntries
        , Limits -> PackageName -> Version -> DocumentWalk selected
erWalkSelected :: Limits -> PackageName -> Version -> DocumentWalk selected
erWalkSelected :: Limits -> PackageName -> Version -> DocumentWalk selected
erWalkSelected
        , erFinishSelected :: Limits
-> PackageName
-> Text
-> Version
-> StreamResult selected
-> Either MetadataError VersionRead
erFinishSelected = \Limits
limits PackageName
name Text
base Version
version StreamResult selected
streamed -> do
            Bool -> Either MetadataError () -> Either MetadataError ()
forall (f :: * -> *). Applicative f => Bool -> f () -> f ()
unless (Text
base Text -> Text -> Bool
forall a. Eq a => a -> a -> Bool
== Text
root) (MetadataError -> Either MetadataError ()
forall a b. a -> Either a b
Left MetadataError
MetadataUndecodable)
            Limits
-> PackageName
-> Text
-> Version
-> StreamResult selected
-> Either MetadataError VersionRead
erFinishSelected Limits
limits PackageName
name Text
base Version
version StreamResult selected
streamed
        }

-- | Whether preparation can bind the selected origin's full-read workspace callback into its reader.
canChargeFullReadWorkspace :: PrepareRead -> Bool
canChargeFullReadWorkspace :: PrepareRead -> Bool
canChargeFullReadWorkspace = \case
    StaticRead{} -> Bool
False
    PrepareRead{} -> Bool
True

-- | Prepare within the full-read operation, so cache hits need no preparation.
prepareManifest :: PrepareRead -> ManifestFetch
prepareManifest :: PrepareRead -> ManifestFetch
prepareManifest = \case
    StaticRead EcosystemRead
nativeRead -> EcosystemRead -> ManifestFetch
fetchManifest EcosystemRead
nativeRead
    PrepareRead OriginClient -> IO (Either MetadataError EcosystemRead)
prepare -> \TracingPort
tracing OriginClient
origin PackageName
name ->
        OriginClient -> IO (Either MetadataError EcosystemRead)
prepare OriginClient
origin IO (Either MetadataError EcosystemRead)
-> (Either MetadataError EcosystemRead
    -> IO (Either MetadataError Manifest))
-> IO (Either MetadataError Manifest)
forall a b. IO a -> (a -> IO b) -> IO b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= (MetadataError -> IO (Either MetadataError Manifest))
-> (EcosystemRead -> IO (Either MetadataError Manifest))
-> Either MetadataError EcosystemRead
-> IO (Either MetadataError Manifest)
forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either (Either MetadataError Manifest -> IO (Either MetadataError Manifest)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Either MetadataError Manifest
 -> IO (Either MetadataError Manifest))
-> (MetadataError -> Either MetadataError Manifest)
-> MetadataError
-> IO (Either MetadataError Manifest)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. MetadataError -> Either MetadataError Manifest
forall a b. a -> Either a b
Left) (\EcosystemRead
nativeRead -> EcosystemRead -> ManifestFetch
fetchManifest EcosystemRead
nativeRead TracingPort
tracing OriginClient
origin PackageName
name)

-- | Prepare independently for each selected-read operation under its actual credentials.
prepareVersion :: PrepareRead -> TracingPort -> OriginClient -> PackageName -> Version -> IO (Either MetadataError VersionRead)
prepareVersion :: PrepareRead
-> TracingPort
-> OriginClient
-> PackageName
-> Version
-> IO (Either MetadataError VersionRead)
prepareVersion = \case
    StaticRead EcosystemRead
nativeRead -> EcosystemRead
-> TracingPort
-> OriginClient
-> PackageName
-> Version
-> IO (Either MetadataError VersionRead)
fetchVersion EcosystemRead
nativeRead
    PrepareRead OriginClient -> IO (Either MetadataError EcosystemRead)
prepare -> \TracingPort
tracing OriginClient
origin PackageName
name Version
version ->
        OriginClient -> IO (Either MetadataError EcosystemRead)
prepare OriginClient
origin IO (Either MetadataError EcosystemRead)
-> (Either MetadataError EcosystemRead
    -> IO (Either MetadataError VersionRead))
-> IO (Either MetadataError VersionRead)
forall a b. IO a -> (a -> IO b) -> IO b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= (MetadataError -> IO (Either MetadataError VersionRead))
-> (EcosystemRead -> IO (Either MetadataError VersionRead))
-> Either MetadataError EcosystemRead
-> IO (Either MetadataError VersionRead)
forall a c b. (a -> c) -> (b -> c) -> Either a b -> c
either (Either MetadataError VersionRead
-> IO (Either MetadataError VersionRead)
forall a. a -> IO a
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Either MetadataError VersionRead
 -> IO (Either MetadataError VersionRead))
-> (MetadataError -> Either MetadataError VersionRead)
-> MetadataError
-> IO (Either MetadataError VersionRead)
forall b c a. (b -> c) -> (a -> b) -> a -> c
. MetadataError -> Either MetadataError VersionRead
forall a b. a -> Either a b
Left) (\EcosystemRead
nativeRead -> EcosystemRead
-> TracingPort
-> OriginClient
-> PackageName
-> Version
-> IO (Either MetadataError VersionRead)
fetchVersion EcosystemRead
nativeRead TracingPort
tracing OriginClient
origin PackageName
name Version
version)