Safe Haskell	None
Language	GHC2021

Ecluse.Core.Registry.Adapter

Contents

The capability record
Registration

Description

The ecosystem adapter registry: resolve an Ecosystem to its registered capability record.

The registry is the build's answer to "which ecosystems does this binary support?", independent of anything an operator configures. That keeps three situations distinct and legible:

an ecosystem the build does not support resolves to Nothing here;
a supported ecosystem with no mount configured is simply not activated -- no error, nothing served under its prefix;
a configured ecosystem that resolves to Nothing is the composition root's loud missing-adapter boot error, never a half-wired mount.

adapterFor is a total case over the closed Ecosystem sum with an explicit arm per constructor, so supporting a new ecosystem is additive: it brings its own adapter module (npm's is Ecluse.Core.Registry.Npm.Adapter) and gains an arm here, touching neither another ecosystem's code nor the core engine. The adapter is consumed only at the composition root, which resolves it once per activation and projects each consuming pipeline's dependency record from its fields; the pipelines never import this module.

Synopsis

data RegistryAdapter = RegistryAdapter {
}
data AdapterServe = AdapterServe {
- serveRouter :: MountRouter
- serveRoutes :: NonEmpty RouteSpec
}
data AdapterMetadata = AdapterMetadata {
- metadataNewClient :: TracingPort -> MetricsPort -> Upstream -> ManifestCaching -> (PackageName -> MetadataError -> IO ()) -> (PackageName -> [InvalidEntry] -> IO ()) -> (PackageName -> IO ()) -> Limits -> Manager -> Text -> Maybe Secret -> MetadataClient
- metadataAssemble :: Text -> Map SourceId CachedDoc -> MergePlan -> Maybe CachedDoc -> CachedDoc
- metadataSerialise :: CachedDoc -> LByteString
}
data AdapterArtifact = AdapterArtifact {
- artifactByFile :: Limits -> Manager -> Text -> Maybe Secret -> PackageName -> Text -> Either UrlFormationError Request
- artifactByUrl :: Limits -> Manager -> Text -> Maybe Secret -> Text -> Either UrlFormationError Request
- artifactHosts :: [Text]
}
data AdapterPublish = AdapterPublish {
- publishRelay :: Limits -> Manager -> Text -> Maybe Secret -> PackageName -> ByteString -> IO (Either PublishRelayFault PublishRelayResponse)
- publishCanonicaliseName :: Text -> Maybe PackageName
- publishDeclaredNames :: LByteString -> [Text]
- publishCodec :: PublishCodec
}
adapterFor :: Ecosystem -> Maybe RegistryAdapter

The capability record

data RegistryAdapter Source #

One ecosystem's complete capability record: the interfaces every consuming pipeline's wiring is projected from. Assembled once per ecosystem (npm's is npmAdapter) and resolved through adapterFor.

Constructors

RegistryAdapter

Fields

adapterEcosystem :: Ecosystem
The ecosystem this record serves. The registry's key must agree with it (pinned by the adapter spec), so a record can never be registered under a foreign ecosystem unnoticed.
adapterServe :: AdapterServe
The web-facing serve surface: the route grammar and response contracts.
adapterMetadata :: AdapterMetadata
The metadata capability: the read-handle constructor and the packument assembly.
adapterArtifact :: AdapterArtifact
The artifact request formation, by filename and by authoritative URL.
adapterPublish :: AdapterPublish
The publish capability: the first-party relay, the name canonicaliser, the declared-name extractor the anti-shadowing guard reads a publish body through, and the mirror write's protocol codec.

data AdapterServe Source #

The ecosystem's web-facing serve surface: the one slice of the record that is about HTTP shape rather than registry protocol, typed against the agnostic action and response vocabulary (Ecluse.Core.Server.Context, Ecluse.Core.Server.Response) because it is web-facing by definition (the registry-to-server import direction is deliberate here). Serve surfaces are where ecosystems diverge most, so this slice stands alone rather than sharing shape with the protocol slices.

Both routing fields are derived by the adapter from one declarative route table (npm's is Ecluse.Core.Registry.Npm.Route), so the surface the server routes and the surface the manifest documents are two interpretations of a single declaration and cannot drift apart.

Constructors

AdapterServe

Fields

serveRouter :: MountRouter
The ecosystem's whole routing decision: which of its paths a mount-relative request names, and what serving that amounts to (an RouteAction). The authoritative router the server dispatches through. An unrecognised path yields the deny-by-default 404.
serveRoutes :: NonEmpty RouteSpec
The same route table as data: the declarative RouteSpec projection of the patterns serveRouter routes on, one per served route. The capability manifest (Ecluse.Manifest) renders this rather than re-describing the path grammar, so the documented surface cannot drift from what is routed.

data AdapterMetadata Source #

The ecosystem's metadata capability: how a package's metadata is read from an origin and how a served document is assembled. The fields have exactly the shapes the consuming dependency records carry (pdNewMetadataClient and pdAssemble), so the composition root projects them unchanged and registering an adapter cannot reshape a pipeline.

Constructors

AdapterMetadata

Fields

metadataNewClient :: TracingPort -> MetricsPort -> Upstream -> ManifestCaching -> (PackageName -> MetadataError -> IO ()) -> (PackageName -> [InvalidEntry] -> IO ()) -> (PackageName -> IO ()) -> Limits -> Manager -> Text -> Maybe Secret -> MetadataClient
Build a per-request metadata client for one origin, given the per-fetch runtime parameters; the adapter closes over the ecosystem's raw fetch primitives.
metadataAssemble :: Text -> Map SourceId CachedDoc -> MergePlan -> Maybe CachedDoc -> CachedDoc
Assemble the served document (CachedDoc) from a merge plan and the raw source documents, rewriting each surviving version's artifact URL under the given mount base. The adapter projects each source and the precedence-winning base document (Nothing when there is none) into its own representation, merges, and injects the result back, so the neutral pipeline threads the documents without reading them.
metadataSerialise :: CachedDoc -> LByteString
Encode an assembled served document (CachedDoc) to its wire bytes. The adapter projects the document to its own representation and serialises it, so the neutral serve tail turns a served document into bytes without knowing its shape.

data AdapterArtifact Source #

The ecosystem's artifact request formation: the two ways an artifact is addressed, by conventional filename under a registry base and by its authoritative upstream URL. The fields have exactly the shapes the consuming dependency records carry (pdBuildArtifactRequestByFile and pdBuildArtifactRequestByUrl).

Constructors

AdapterArtifact

Fields

artifactByFile :: Limits -> Manager -> Text -> Maybe Secret -> PackageName -> Text -> Either UrlFormationError Request
Build an artifact request by conventional filename path under a base URL: how a trusted origin is addressed.
artifactByUrl :: Limits -> Manager -> Text -> Maybe Secret -> Text -> Either UrlFormationError Request
Build an artifact request at its authoritative upstream URL: how a location the upstream chose is honoured. The URL is complete on its own, so an implementation must form the request from it alone: a caller may pass an empty base URL (there is no base to resolve against) and an anonymous credential (Nothing), as the mirror worker's fetch does.
artifactHosts :: [Text]
The ecosystem's canonical artifact hosts, as URLs whose authorities feed the tarball-host gate: hosts the public registry serves artifact bytes from by design (PyPI's https://files.pythonhosted.org), so the secure-default same-host policy admits them without the operator naming hostnames. Empty for an ecosystem (npm) whose artifacts ride the registry host.

data AdapterPublish Source #

The ecosystem's publish capability: relaying a client's own publish document, canonicalising a raw package name, extracting the names a publish body declares, and the mirror-write protocol codec. The relay, canonicaliser, and declared-name extractor have exactly the shapes the consuming dependency record carries (pubRelayPublish, pubCanonicaliseName, and pubDeclaredNames); the codec is the protocol half of the mirror write, which the composition root marries to the shared publish transport per mounted ecosystem (newMirrorPublish).

Constructors

AdapterPublish

Fields

publishRelay :: Limits -> Manager -> Text -> Maybe Secret -> PackageName -> ByteString -> IO (Either PublishRelayFault PublishRelayResponse)
Relay a client's publish document to the publication target, returning its response.
publishCanonicaliseName :: Text -> Maybe PackageName
Canonicalise a raw package-name string, or Nothing when it cannot be parsed.
publishDeclaredNames :: LByteString -> [Text]
Extract every package name a publish body declares as its own identity, read from the ecosystem's own publish-document schema. The neutral publish pipeline's anti-shadowing body-name guard injects this and refuses any declared name that disagrees with the URL-path name, so npm's document shape stays adapter-side rather than coupling the pipeline. A body that declares no readable name yields [].
publishCodec :: PublishCodec
The mirror write's protocol codec: publish document assembly and request formation, the probe's request and version-list projection, and the status semantics -- protocol only. The manager, credential mint, and fault classification are the shared transport's, supplied at the marriage.

Registration

adapterFor :: Ecosystem -> Maybe RegistryAdapter Source #

Resolve an ecosystem to its registered RegistryAdapter, or Nothing for one this build carries no adapter for. Total over the closed Ecosystem sum, every arm explicit, so an added ecosystem is a compiler-visible arm here rather than a fall-through.