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.

Files

data Metadata

data Binary

data RemoteFile :: * -> * -> * 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

RemoteTimestamp :: RemoteFile (FormatUn :- ()) Metadata

RemoteRoot :: Maybe (Trusted FileInfo) -> RemoteFile (FormatUn :- ()) Metadata

RemoteSnapshot :: Trusted FileInfo -> RemoteFile (FormatUn :- ()) Metadata

RemoteMirrors :: Trusted FileInfo -> RemoteFile (FormatUn :- ()) Metadata

RemoteIndex :: HasFormat fs FormatGz -> Formats fs (Trusted FileInfo) -> RemoteFile fs Binary

RemotePkgTarGz :: PackageIdentifier -> Trusted FileInfo -> RemoteFile (FormatGz :- ()) Binary

Instances

Show (RemoteFile fs typ)

Methods

showsPrec :: Int -> RemoteFile fs typ -> ShowS

show :: RemoteFile fs typ -> String

showList :: [RemoteFile fs typ] -> ShowS

Pretty (RemoteFile fs typ)

Methods

pretty :: RemoteFile fs typ -> String

data CachedFile

Files that we might request from the local cache

Constructors

CachedTimestamp

Timestamp metadata (timestamp.json)

CachedRoot

Root metadata (root.json)

CachedSnapshot

Snapshot metadata (snapshot.json)

CachedMirrors

Mirrors list (mirrors.json)

Instances

Eq CachedFile

Methods

(==) :: CachedFile -> CachedFile -> Bool

(/=) :: CachedFile -> CachedFile -> Bool

Ord CachedFile

Methods

compare :: CachedFile -> CachedFile -> Ordering

(<) :: CachedFile -> CachedFile -> Bool

(<=) :: CachedFile -> CachedFile -> Bool

(>) :: CachedFile -> CachedFile -> Bool

(>=) :: CachedFile -> CachedFile -> Bool

max :: CachedFile -> CachedFile -> CachedFile

min :: CachedFile -> CachedFile -> CachedFile

Show CachedFile

Methods

showsPrec :: Int -> CachedFile -> ShowS

show :: CachedFile -> String

showList :: [CachedFile] -> ShowS

Pretty CachedFile

Methods

pretty :: CachedFile -> String

data IndexFile :: * -> * 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

IndexPkgMetadata :: PackageIdentifier -> IndexFile (Signed Targets)

IndexPkgCabal :: PackageIdentifier -> IndexFile ()

IndexPkgPrefs :: PackageName -> IndexFile ()

Instances

SomePretty IndexFile

Methods

somePretty :: DictPretty (IndexFile a)

SomeShow IndexFile

Methods

someShow :: DictShow (IndexFile a)

Show (IndexFile dec)

Methods

showsPrec :: Int -> IndexFile dec -> ShowS

show :: IndexFile dec -> String

showList :: [IndexFile dec] -> ShowS

Pretty (IndexFile dec)

Methods

pretty :: IndexFile dec -> String

remoteFileDefaultFormat :: 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.

remoteFileDefaultInfo :: RemoteFile fs typ -> Maybe (Trusted FileInfo)

Default file info (see also remoteFileDefaultFormat)

Repository proper

data Repository down

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

Fields

• 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 suspectible 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)

Instances

Show (Repository down)

Methods

showsPrec :: Int -> Repository down -> ShowS

show :: Repository down -> String

showList :: [Repository down] -> ShowS

newtype 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

AttemptNr Int

Instances

Eq AttemptNr

Methods

(==) :: AttemptNr -> AttemptNr -> Bool

(/=) :: AttemptNr -> AttemptNr -> Bool

Num AttemptNr

Methods

(+) :: AttemptNr -> AttemptNr -> AttemptNr

(-) :: AttemptNr -> AttemptNr -> AttemptNr

(*) :: AttemptNr -> AttemptNr -> AttemptNr

negate :: AttemptNr -> AttemptNr

abs :: AttemptNr -> AttemptNr

signum :: AttemptNr -> AttemptNr

fromInteger :: Integer -> AttemptNr

Ord AttemptNr

Methods

compare :: AttemptNr -> AttemptNr -> Ordering

(<) :: AttemptNr -> AttemptNr -> Bool

(<=) :: AttemptNr -> AttemptNr -> Bool

(>) :: AttemptNr -> AttemptNr -> Bool

(>=) :: AttemptNr -> AttemptNr -> Bool

max :: AttemptNr -> AttemptNr -> AttemptNr

min :: AttemptNr -> AttemptNr -> AttemptNr

data 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

LogRootUpdated

Root information was updated

This message is issued when the root information is updated as part of the normal check for updates procedure. If the root information is updated because of a verification error WarningVerificationError is issued instead.

LogVerificationError VerificationError

A verification error

Verification errors can be temporary, and may be resolved later; hence these are just warnings. (Verification errors that cannot be resolved are thrown as exceptions.)

LogDownloading (RemoteFile fs typ)

Download a file from a repository

LogUpdating (RemoteFile fs Binary)

Incrementally updating a file from a repository

LogSelectedMirror MirrorDescription

Selected a particular mirror

LogCannotUpdate (RemoteFile fs Binary) UpdateFailure

Updating a file failed (we will instead download it whole)

LogMirrorFailed MirrorDescription SomeException

We got an exception with a particular mirror (we will try with a different mirror if any are available)

Instances

Pretty LogMessage

Methods

pretty :: LogMessage -> String

data 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)

Instances

Pretty UpdateFailure

Methods

pretty :: UpdateFailure -> String

data 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

SomeRemoteError :: Exception e => e -> SomeRemoteError

Instances

Show SomeRemoteError

Methods

showsPrec :: Int -> SomeRemoteError -> ShowS

show :: SomeRemoteError -> String

showList :: [SomeRemoteError] -> ShowS

Exception SomeRemoteError

Methods

toException :: SomeRemoteError -> SomeException

fromException :: SomeException -> Maybe SomeRemoteError

displayException :: SomeRemoteError -> String

Pretty SomeRemoteError

Methods

pretty :: SomeRemoteError -> String

Downloaded files

class DownloadedFile (down :: * -> *) where

Minimal complete definition

downloadedVerify, downloadedRead, downloadedCopyTo

Methods

downloadedVerify :: down a -> Trusted FileInfo -> IO Bool

Verify a download file

downloadedRead :: down Metadata -> IO ByteString

Read the file we just downloaded into memory

We never read binary data, only metadata.

downloadedCopyTo :: down a -> Path Absolute -> IO ()

Copy a downloaded file to its destination

Instances

DownloadedFile RemoteTemp

Methods

downloadedVerify :: RemoteTemp a -> Trusted FileInfo -> IO Bool

downloadedRead :: RemoteTemp Metadata -> IO ByteString

downloadedCopyTo :: RemoteTemp a -> Path Absolute -> IO ()

DownloadedFile LocalFile

Methods

downloadedVerify :: LocalFile a -> Trusted FileInfo -> IO Bool

downloadedRead :: LocalFile Metadata -> IO ByteString

downloadedCopyTo :: LocalFile a -> Path Absolute -> IO ()

Helpers

mirrorsUnsupported :: Maybe [Mirror] -> IO a -> IO a

Helper function to implement repWithMirrors.

Paths

remoteRepoPath :: RepoLayout -> RemoteFile fs typ -> Formats fs RepoPath

remoteRepoPath' :: RepoLayout -> RemoteFile fs typ -> HasFormat fs f -> RepoPath

Utility

data IsCached :: * -> * where

Is a particular remote file cached?

Constructors

CacheAs :: CachedFile -> IsCached Metadata

DontCache :: IsCached Binary

CacheIndex :: IsCached Binary

Instances

Eq (IsCached typ)

Methods

(==) :: IsCached typ -> IsCached typ -> Bool

(/=) :: IsCached typ -> IsCached typ -> Bool

Show (IsCached typ)

Methods

showsPrec :: Int -> IsCached typ -> ShowS

show :: IsCached typ -> String

showList :: [IsCached typ] -> ShowS

mustCache :: RemoteFile fs typ -> IsCached typ

Which remote files should we cache locally?