HORIZON HASKELLDocslts/ghc-9.10.x248f8f02026-10-05Search names, modules, packages, or :: a typeCtrl K

GHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05

Modulehackage-security-0.6.3.2Haskell2010

Hackage.Security.Client.Repository

Abstract definition of a Repository

Most clients should only need to import this module if they wish to define their own Repository implementations.

  • 11 types
  • 1 class
  • 6 values

Files

7 declarations
datadata RemoteFile a b where
#

Abstract definition of files we might have to download

RemoteFile is parametrized by the type of the formats that we can accept from the remote repository, as well as with information on whether this file is metadata actual binary content.

NOTE: Haddock lacks GADT support so constructors have only regular comments.

Constructors

Instances2Show, Pretty
  • Show (RemoteFile fs typ)Defined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
  • Pretty (RemoteFile fs typ)Defined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
datadata CachedFile
#

Files that we might request from the local cache

Constructors

Instances4Eq, Ord, Show, Pretty
  • Eq CachedFileDefined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
  • Ord CachedFileDefined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
  • Show CachedFileDefined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
  • Pretty CachedFileDefined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
datadata IndexFile a where
#

Files that we might request from the index

The type index tells us the type of the decoded file, if any. For files for which the library does not support decoding this will be (). NOTE: Clients should NOT rely on this type index being (), or they might break if we add support for parsing additional file formats in the future.

TODO: If we wanted to support legacy Hackage, we should also have a case for the global preferred-versions file. But supporting legacy Hackage will probably require more work anyway..

Constructors

Instances4SomePretty, SomeShow, Show, Pretty
  • SomePretty IndexFileDefined in hackage-security-0.6.3.2 · Hackage.Security.TUF.Layout.Index
  • SomeShow IndexFileDefined in hackage-security-0.6.3.2 · Hackage.Security.TUF.Layout.Index
  • Show (IndexFile dec)Defined in hackage-security-0.6.3.2 · Hackage.Security.TUF.Layout.Index
  • Pretty (IndexFile dec)Defined in hackage-security-0.6.3.2 · Hackage.Security.TUF.Layout.Index
valueremoteFileDefaultFormat :: RemoteFile fs typ -> Some (HasFormat fs)
#

Default format for each file type

For most file types we don't have a choice; for the index the repository is only required to offer the GZip-compressed format so that is the default.

Repository proper

5 declarations
datadata Repository (down :: Type -> Type)
#

Repository

This is an abstract representation of a repository. It simply provides a way to download metafiles and target files, without specifying how this is done. For instance, for a local repository this could just be doing a file read, whereas for remote repositories this could be using any kind of HTTP client.

Constructors

  • DownloadedFile down => Repository
    • repGetRemote :: forall fs typ. Throws SomeRemoteError => AttemptNr -> RemoteFile fs typ -> Verify (Some (HasFormat fs), down typ)

      Get a file from the server

      Responsibilies of repGetRemote:

      • Download the file from the repository and make it available at a temporary location

      • Use the provided file length to protect against endless data attacks. (Repositories such as local repositories that are not susceptible to endless data attacks can safely ignore this argument.)

      • Move the file from its temporary location to its permanent location if verification succeeds.

      NOTE: Calls to repGetRemote should _always_ be in the scope of repWithMirror.

    • repGetCached :: CachedFile -> IO (Maybe (Path Absolute))

      Get a cached file (if available)

    • repGetCachedRoot :: IO (Path Absolute)

      Get the cached root

      This is a separate method only because clients must ALWAYS have root information available.

    • repClearCache :: IO ()

      Clear all cached data

      In particular, this should remove the snapshot and the timestamp. It would also be okay, but not required, to delete the index.

    • repWithIndex :: forall a. (Handle -> IO a) -> IO a

      Open the tarball for reading

      This function has this shape so that:

      • We can read multiple files from the tarball without having to open and close the handle each time

      • We can close the handle immediately when done.

    • repGetIndexIdx :: IO TarIndex

      Read the index index

    • repLockCache :: IO () -> IO ()

      Lock the cache (during updates)

    • repWithMirror :: forall a. Maybe [Mirror] -> IO a -> IO a

      Mirror selection

      The purpose of repWithMirror is to scope mirror selection. The idea is that if we have

      repWithMirror mirrorList $
  someCallback

      then the repository may pick a mirror before calling someCallback, catch exceptions thrown by someCallback, and potentially try the callback again with a different mirror.

      The list of mirrors may be Nothing if we haven't yet downloaded the list of mirrors from the repository, or when our cached list of mirrors is invalid. Of course, if we did download it, then the list of mirrors may still be empty. In this case the repository must fall back to its primary download mechanism.

      Mirrors as currently defined (in terms of a "base URL") are inherently a HTTP (or related) concept, so in repository implementations such as the local-repo repWithMirrors is probably just an identity operation (see ignoreMirrors). Conversely, HTTP implementations of repositories may have other, out-of-band information (for example, coming from a cabal config file) that they may use to influence mirror selection.

    • repLog :: LogMessage -> IO ()

      Logging

    • repLayout :: RepoLayout

      Layout of this repository

    • repIndexLayout :: IndexLayout

      Layout of the index

      Since the repository hosts the index, the layout of the index is not independent of the layout of the repository.

    • repDescription :: String

      Description of the repository (used in the show instance)

Instances1Show
  • Show (Repository down)Defined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
newtypenewtype AttemptNr
#

Are we requesting this information because of a previous validation error?

Clients can take advantage of this to tell caches to revalidate files.

Constructors

Instances3Eq, Num, Ord
  • Eq AttemptNrDefined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
  • Num AttemptNrDefined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
  • Ord AttemptNrDefined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
datadata LogMessage
#

Log messages

We use a RemoteFile rather than a RepoPath here because we might not have a RepoPath for the file that we were trying to download (that is, for example if the server does not provide an uncompressed tarball, it doesn't make much sense to list the path to that non-existing uncompressed tarball).

Constructors

Instances1Pretty
  • Pretty LogMessageDefined in hackage-security-0.6.3.2 · Hackage.Security.Client.Repository
datadata UpdateFailure
#

Records why we are downloading a file rather than updating it.

Constructors

  • UpdateImpossibleUnsupported

    Server does not support incremental downloads

  • UpdateImpossibleNoLocalCopy

    We don't have a local copy of the file to update

  • UpdateFailedTwice

    Update failed twice

    If we attempt an incremental update the first time, and it fails, we let it go round the loop, update local security information, and try again. But if an incremental update then fails _again_, we instead attempt a regular download.

  • UpdateFailed SomeException

    Update failed (for example: perhaps the local file got corrupted)

Instances1Pretty
datadata SomeRemoteError where
#

Repository-specific exceptions

For instance, for repositories using HTTP this might correspond to a 404; for local repositories this might correspond to file-not-found, etc.

Constructors

Instances3Show, Exception, Pretty

Downloaded files

classclass DownloadedFile (down :: Type -> Type) where
#

Methods

Instances2DownloadedFile

Helpers

Paths

2 declarations

Utility

2 declarations