Safe Haskell | None |
---|---|
Language | Haskell2010 |
Abstract definition of a Repository
Most clients should only need to import this module if they wish to define their own Repository implementations.
- data RemoteFile :: * -> * where
- RemoteTimestamp :: RemoteFile (FormatUn :- ())
- RemoteRoot :: Maybe (Trusted FileInfo) -> RemoteFile (FormatUn :- ())
- RemoteSnapshot :: Trusted FileInfo -> RemoteFile (FormatUn :- ())
- RemoteMirrors :: Trusted FileInfo -> RemoteFile (FormatUn :- ())
- RemoteIndex :: HasFormat fs FormatGz -> Formats fs (Trusted FileInfo) -> RemoteFile fs
- RemotePkgTarGz :: PackageIdentifier -> Trusted FileInfo -> RemoteFile (FormatGz :- ())
- data CachedFile
- data IndexFile
- remoteFileDefaultFormat :: RemoteFile fs -> Some (HasFormat fs)
- remoteFileDefaultInfo :: RemoteFile fs -> Maybe (Trusted FileInfo)
- data Repository = Repository {
- repWithRemote :: forall a fs. (Throws VerificationError, Throws SomeRemoteError) => IsRetry -> RemoteFile fs -> (forall f. HasFormat fs f -> TempPath -> IO a) -> IO a
- repGetCached :: CachedFile -> IO (Maybe AbsolutePath)
- repGetCachedRoot :: IO AbsolutePath
- repClearCache :: IO ()
- repGetFromIndex :: IndexFile -> IO (Maybe ByteString)
- repWithMirror :: forall a. Maybe [Mirror] -> IO a -> IO a
- repLog :: LogMessage -> IO ()
- repLayout :: RepoLayout
- repDescription :: String
- type TempPath = AbsolutePath
- data IsRetry
- data LogMessage
- data UpdateFailure
- data SomeRemoteError :: * where
- SomeRemoteError :: Exception e => e -> SomeRemoteError
- mirrorsUnsupported :: Maybe [Mirror] -> IO a -> IO a
- remoteRepoPath :: RepoLayout -> RemoteFile fs -> Formats fs RepoPath
- remoteRepoPath' :: RepoLayout -> RemoteFile fs -> HasFormat fs f -> RepoPath
- indexFilePath :: IndexLayout -> IndexFile -> IndexPath
- data IsCached
- mustCache :: RemoteFile fs -> IsCached
Files
data RemoteFile :: * -> * where Source
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.
NOTE: Haddock lacks GADT support so constructors have only regular comments.
RemoteTimestamp :: RemoteFile (FormatUn :- ()) | |
RemoteRoot :: Maybe (Trusted FileInfo) -> RemoteFile (FormatUn :- ()) | |
RemoteSnapshot :: Trusted FileInfo -> RemoteFile (FormatUn :- ()) | |
RemoteMirrors :: Trusted FileInfo -> RemoteFile (FormatUn :- ()) | |
RemoteIndex :: HasFormat fs FormatGz -> Formats fs (Trusted FileInfo) -> RemoteFile fs | |
RemotePkgTarGz :: PackageIdentifier -> Trusted FileInfo -> RemoteFile (FormatGz :- ()) |
Show (RemoteFile fs) | |
Pretty (RemoteFile fs) |
data CachedFile Source
Files that we might request from the local cache
CachedTimestamp | Timestamp metadata ( |
CachedRoot | Root metadata ( |
CachedSnapshot | Snapshot metadata ( |
CachedMirrors | Mirrors list ( |
Files that we might request from the index
TODO: We should also provide a way to extract preferred versions info from the tarball. After all, this is a security sensitive, as it might be used for rollback/freeze attacks. Until we have author signing however this is not a strict necessity, as the preferred versions comes from the index which is itself signed.
IndexPkgMetadata PackageIdentifier | Package-specific metadata ( |
IndexPkgCabal PackageIdentifier | Cabal file for a package |
remoteFileDefaultFormat :: RemoteFile fs -> Some (HasFormat fs) Source
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 -> Maybe (Trusted FileInfo) Source
Default file info (see also remoteFileDefaultFormat
)
Repository proper
data Repository Source
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.
Repository | |
|
type TempPath = AbsolutePath Source
Path to temporary file
Are we requesting this information because of a previous validation error?
Clients can take advantage of this to tell caches to revalidate files.
data LogMessage Source
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).
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 (Some RemoteFile) | Download a file from a repository |
LogUpdating (Some RemoteFile) | Incrementally updating a file from a repository |
LogSelectedMirror MirrorDescription | Selected a particular mirror |
LogUpdateFailed (Some RemoteFile) UpdateFailure | Updating a file failed (we will try again by downloading it whole) |
LogMirrorFailed MirrorDescription SomeException | We got an exception with a particular mirror (we will try with a different mirror if any are available) |
data UpdateFailure Source
Records why we are downloading a file rather than updating it.
UpdateImpossibleOnlyCompressed | Server only provides compressed form of the file |
UpdateNotUsefulWantsCompressed | Likewise, it's possible that client _wants_ the compressed form of the file, in which case downloading the uncompressed form is not useful. |
UpdateImpossibleUnsupported | Server does not support incremental downloads |
UpdateImpossibleNoLocalCopy | We don't have a local copy of the file to update |
UpdateTooLarge | Updating the local file would actually mean downloading MORE data then doing a regular download. |
UpdateFailed SomeException | Update failed |
data SomeRemoteError :: * where Source
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.
SomeRemoteError :: Exception e => e -> SomeRemoteError |
Helpers
mirrorsUnsupported :: Maybe [Mirror] -> IO a -> IO a Source
Helper function to implement repWithMirrors
.
Paths
remoteRepoPath :: RepoLayout -> RemoteFile fs -> Formats fs RepoPath Source
remoteRepoPath' :: RepoLayout -> RemoteFile fs -> HasFormat fs f -> RepoPath Source
indexFilePath :: IndexLayout -> IndexFile -> IndexPath Source
Utility
Is a particular remote file cached?
CacheAs CachedFile | This remote file should be cached, and we ask for it by name |
DontCache | We don't cache this remote file This doesn't mean a Repository should not feel free to cache the file if desired, but it does mean the generic algorithms will never ask for this file from the cache. |
CacheIndex | The index is somewhat special: it should be cached, but we never ask for it directly. Instead, we will ask the Repository for files _from_ the index, which it can serve however it likes. For instance, some repositories might keep the index in uncompressed form, others in compressed form; some might keep an index tarball index for quick access, others may scan the tarball linearly, etc. |
mustCache :: RemoteFile fs -> IsCached Source
Which remote files should we cache locally?