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

-- | npm request paths, metadata negotiation and credentials over shared HTTP mechanics.
module Ecluse.Core.Registry.Npm.Request (
    -- * Content negotiation
    MetadataForm (..),

    -- * The ecosystem's artifact hosts
    npmArtifactHosts,

    -- * Request building
    metadataRequest,
    metadataRequestUnder,
    artifactRequestByFile,
    artifactRequestByUrl,
    artifactFileUrl,
    packageUrl,

    -- * Shared internals
    jsonPutRequest,
    withToken,
) where

import Network.HTTP.Client (
    Request (method, requestBody, requestHeaders),
    RequestBody (RequestBodyBS),
 )
import Network.HTTP.Types.Header (hAccept, hContentType)

import Ecluse.Core.Credential (ClientCredential)
import Ecluse.Core.Package (PackageName, pkgNamespace, renderPackageName, unScope, unscopedName)
import Ecluse.Core.Registry (UrlFormationError)
import Ecluse.Core.Registry.Npm.Credential (npmCredential)
import Ecluse.Core.Registry.Request (BaseRequest, attachCredential, joinPath, parseRequestEither, requestAt)
import Ecluse.Core.Registry.Request qualified as Request
import Ecluse.Core.Server.Path (encodeComponent)

-- | Which of npm's two metadata documents to request, selected by the @Accept@ header.
data MetadataForm
    = -- | The install view (@application/vnd.npm.install-v1+json@), which drops the @time@ map.
      Abbreviated
    | -- | The full packument (@application/json@), the only form carrying the @time@ map.
      Full
    deriving stock (MetadataForm -> MetadataForm -> Bool
(MetadataForm -> MetadataForm -> Bool)
-> (MetadataForm -> MetadataForm -> Bool) -> Eq MetadataForm
forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
$c== :: MetadataForm -> MetadataForm -> Bool
== :: MetadataForm -> MetadataForm -> Bool
$c/= :: MetadataForm -> MetadataForm -> Bool
/= :: MetadataForm -> MetadataForm -> Bool
Eq, Int -> MetadataForm -> ShowS
[MetadataForm] -> ShowS
MetadataForm -> String
(Int -> MetadataForm -> ShowS)
-> (MetadataForm -> String)
-> ([MetadataForm] -> ShowS)
-> Show MetadataForm
forall a.
(Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
$cshowsPrec :: Int -> MetadataForm -> ShowS
showsPrec :: Int -> MetadataForm -> ShowS
$cshow :: MetadataForm -> String
show :: MetadataForm -> String
$cshowList :: [MetadataForm] -> ShowS
showList :: [MetadataForm] -> ShowS
Show)

metadataAccept :: MetadataForm -> ByteString
metadataAccept :: MetadataForm -> Method
metadataAccept = \case
    MetadataForm
Abbreviated -> Method
"application/vnd.npm.install-v1+json"
    MetadataForm
Full -> Method
"application/json"

-- | npm registries serve their own artifacts, so no extra hosts enter the artifact gate.
npmArtifactHosts :: [Text]
npmArtifactHosts :: [Text]
npmArtifactHosts = []

-- | Fetch @{baseUrl}/{encoded-name}@ with the requested metadata form and gzip negotiation.
metadataRequest ::
    Text ->
    Maybe ClientCredential ->
    MetadataForm ->
    PackageName ->
    Either UrlFormationError Request
metadataRequest :: Text
-> Maybe ClientCredential
-> MetadataForm
-> PackageName
-> Either UrlFormationError Request
metadataRequest Text
baseUrl Maybe ClientCredential
token MetadataForm
form PackageName
name = Maybe ClientCredential -> MetadataForm -> Request -> Request
metadataGet Maybe ClientCredential
token MetadataForm
form (Request -> Request)
-> Either UrlFormationError Request
-> Either UrlFormationError Request
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> (Text -> PackageName -> Either UrlFormationError Text
packageUrl Text
baseUrl PackageName
name Either UrlFormationError Text
-> (Text -> Either UrlFormationError Request)
-> Either UrlFormationError Request
forall a b.
Either UrlFormationError a
-> (a -> Either UrlFormationError b) -> Either UrlFormationError b
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= Text -> Either UrlFormationError Request
parseRequestEither)

-- | 'metadataRequest' under a base parsed once, through 'requestAt'.
metadataRequestUnder ::
    BaseRequest ->
    Maybe ClientCredential ->
    MetadataForm ->
    PackageName ->
    Either UrlFormationError Request
metadataRequestUnder :: BaseRequest
-> Maybe ClientCredential
-> MetadataForm
-> PackageName
-> Either UrlFormationError Request
metadataRequestUnder BaseRequest
base Maybe ClientCredential
token MetadataForm
form PackageName
name = Maybe ClientCredential -> MetadataForm -> Request -> Request
metadataGet Maybe ClientCredential
token MetadataForm
form (Request -> Request)
-> Either UrlFormationError Request
-> Either UrlFormationError Request
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> BaseRequest -> Text -> Either UrlFormationError Request
requestAt BaseRequest
base (PackageName -> Text
encodePackagePath PackageName
name)

metadataGet :: Maybe ClientCredential -> MetadataForm -> Request -> Request
metadataGet :: Maybe ClientCredential -> MetadataForm -> Request -> Request
metadataGet Maybe ClientCredential
token MetadataForm
form = CredentialMapping
-> Maybe ClientCredential -> Method -> Request -> Request
Request.metadataGet CredentialMapping
npmCredential Maybe ClientCredential
token (MetadataForm -> Method
metadataAccept MetadataForm
form)

-- | Fetch @{base}/{encoded-pkg}/-/{filename}@ under the client's filename through 'requestAt'.
artifactRequestByFile ::
    BaseRequest ->
    Maybe ClientCredential ->
    PackageName ->
    Text ->
    Either UrlFormationError Request
artifactRequestByFile :: BaseRequest
-> Maybe ClientCredential
-> PackageName
-> Text
-> Either UrlFormationError Request
artifactRequestByFile BaseRequest
base Maybe ClientCredential
token PackageName
name Text
filename = CredentialMapping -> Maybe ClientCredential -> Request -> Request
Request.artifactGet CredentialMapping
npmCredential Maybe ClientCredential
token (Request -> Request)
-> Either UrlFormationError Request
-> Either UrlFormationError Request
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> BaseRequest -> Text -> Either UrlFormationError Request
requestAt BaseRequest
base (PackageName -> Text -> Text
artifactPath PackageName
name Text
filename)

-- | Fetch the preserved @dist.tarball@ URL under npm's credential presentation.
artifactRequestByUrl ::
    Maybe ClientCredential ->
    Text ->
    Either UrlFormationError Request
artifactRequestByUrl :: Maybe ClientCredential -> Text -> Either UrlFormationError Request
artifactRequestByUrl = CredentialMapping
-> Maybe ClientCredential
-> Text
-> Either UrlFormationError Request
Request.artifactRequestByUrl CredentialMapping
npmCredential

-- | The metadata and publish URL for a package: @{baseUrl}/{encoded-name}@.
packageUrl :: Text -> PackageName -> Either UrlFormationError Text
packageUrl :: Text -> PackageName -> Either UrlFormationError Text
packageUrl Text
baseUrl PackageName
name = Text -> Text -> Either UrlFormationError Text
joinPath Text
baseUrl (PackageName -> Text
encodePackagePath PackageName
name)

-- | Encode the filename as one component in @{baseUrl}/{encoded-name}/-/{encoded-filename}@.
artifactFileUrl :: Text -> PackageName -> Text -> Either UrlFormationError Text
artifactFileUrl :: Text -> PackageName -> Text -> Either UrlFormationError Text
artifactFileUrl Text
baseUrl PackageName
name Text
filename = Text -> Text -> Either UrlFormationError Text
joinPath Text
baseUrl (PackageName -> Text -> Text
artifactPath PackageName
name Text
filename)

artifactPath :: PackageName -> Text -> Text
artifactPath :: PackageName -> Text -> Text
artifactPath PackageName
name Text
filename = PackageName -> Text
encodePackagePath PackageName
name Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
"/-/" Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text -> Text
encodeComponent Text
filename

{- This builder writes the @\@@ and the @%2F@ itself and percent-encodes every component, so a
reserved byte in a decoded name never reaches the upstream URL raw. -}
encodePackagePath :: PackageName -> Text
encodePackagePath :: PackageName -> Text
encodePackagePath PackageName
name = case PackageName -> Maybe Scope
pkgNamespace PackageName
name of
    Just Scope
scope -> Text
"@" Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text -> Text
encodeComponent (Scope -> Text
unScope Scope
scope) Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text
"%2F" Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text -> Text
encodeComponent (PackageName -> Text
unscopedName PackageName
name)
    Maybe Scope
Nothing -> Text -> Text
encodeComponent (PackageName -> Text
renderPackageName PackageName
name)

-- | Publish JSON under the injected credential, declaring the media type npm registries require.
jsonPutRequest :: Maybe ClientCredential -> Text -> ByteString -> Either UrlFormationError Request
jsonPutRequest :: Maybe ClientCredential
-> Text -> Method -> Either UrlFormationError Request
jsonPutRequest Maybe ClientCredential
credential Text
url Method
document = do
    base <- Text -> Either UrlFormationError Request
parseRequestEither Text
url
    pure
        . withToken credential
        $ base
            { method = "PUT"
            , requestBody = RequestBodyBS document
            , requestHeaders =
                (hContentType, "application/json")
                    : (hAccept, "application/json")
                    : requestHeaders base
            }

-- | Attach npm's credential presentation and preserve the shared redirect and identity controls.
withToken :: Maybe ClientCredential -> Request -> Request
withToken :: Maybe ClientCredential -> Request -> Request
withToken = CredentialMapping -> Maybe ClientCredential -> Request -> Request
attachCredential CredentialMapping
npmCredential