Data.ContentStore

Create content stores, put objects into them, and retrieve objects from them.

Documentation

data ContentStore

The ContentStore is an opaque type that contains various pieces of information used to describe an on-disk content store. Values of this type are constructed via mkContentStore and openContentStore, depending on which operation you need to perform. Users should not need to concern themselves with the internals of this type.

data CsError

A type to represent various errors that can occur during content store operations.

Constructors

CsError String

Miscellaneous, uncategorized errors. The string is the exact error message.

CsErrorCollision String

An object with this digest already exists in the content store. This error is not typically raised during write operations, because attempting to write the same thing twice is not really an error.

CsErrorConfig String

A parse error occurred reading the content store's internal config file. This generally represents either a programming error or that someone has been modifying the internals. The string contains the error message.

CsErrorInvalid String

The content store directory is invalid. This usually occurs because some file or directory is missing. The string is the name of what is missing.

CsErrorMissing

The content store does not exist.

CsErrorNoSuchObject String

The requested object does not exist in the content store. The string contains the object digest requested.

CsErrorUnsupportedHash String

The hashing algorithm is not supported by the content store. Not all possible algorithms are supported. The string contains the name of the algorithm requested.

Instances

Eq CsError

Methods

(==) :: CsError -> CsError -> Bool

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

Show CsError

Methods

showsPrec :: Int -> CsError -> ShowS

show :: CsError -> String

showList :: [CsError] -> ShowS

MonadError CsError CsMonad

Methods

throwError :: CsError -> CsMonad a

catchError :: CsMonad a -> (CsError -> CsMonad a) -> CsMonad a

data CsMonad a

Working with a ContentStore requires a lot of behind-the-scenes management of ResourceT, ExceptT, and IO. Along with runCsMonad, this provides a type and function for doing much of that management for you. These two can be used like so:

result <- runCsMonad $ do
    cs <- mkContentStore "/tmp/cs.repo"
    storeDirectory cs "/tmp/test-data"

case result of
    Left e  -> print e
    Right d -> do putStrLn "Stored objects: "
                  mapM_ print d

Most functions in this module do not explicitly require use of CsMonad, but any that have a return type including m can be run inside it.

Instances

Monad CsMonad

Methods

(>>=) :: CsMonad a -> (a -> CsMonad b) -> CsMonad b

(>>) :: CsMonad a -> CsMonad b -> CsMonad b

return :: a -> CsMonad a

fail :: String -> CsMonad a

Functor CsMonad

Methods

fmap :: (a -> b) -> CsMonad a -> CsMonad b

(<$) :: a -> CsMonad b -> CsMonad a

Applicative CsMonad

Methods

pure :: a -> CsMonad a

(<*>) :: CsMonad (a -> b) -> CsMonad a -> CsMonad b

(*>) :: CsMonad a -> CsMonad b -> CsMonad b

(<*) :: CsMonad a -> CsMonad b -> CsMonad a

MonadIO CsMonad

Methods

liftIO :: IO a -> CsMonad a

MonadResource CsMonad

Methods

liftResourceT :: ResourceT IO a -> CsMonad a

MonadThrow CsMonad

Methods

throwM :: Exception e => e -> CsMonad a

MonadBase IO CsMonad

Methods

liftBase :: IO α -> CsMonad α

MonadBaseControl IO CsMonad

Associated Types

type StM (CsMonad :: * -> *) a :: *

Methods

liftBaseWith :: (RunInBase CsMonad IO -> IO a) -> CsMonad a

restoreM :: StM CsMonad a -> CsMonad a

MonadError CsError CsMonad

Methods

throwError :: CsError -> CsMonad a

catchError :: CsMonad a -> (CsError -> CsMonad a) -> CsMonad a

type StM CsMonad a

type StM CsMonad a = StM (ResourceT (ExceptT CsError IO)) a

runCsMonad :: CsMonad a -> IO (Either CsError a)

See the documentation for CsMonad.

contentStoreDigest :: ContentStore -> DigestAlgorithm

Return the digest type used by a content store.

contentStoreValid :: (MonadError CsError m, MonadIO m) => FilePath -> m Bool

Check that a content store exists and contains everything it's supposed to. This does not check the validity of all the contents, however. A CsError will be thrown if there are any problems. Otherwise, this function returns True.

fetchByteString

Arguments

:: (MonadBaseControl IO m, MonadError CsError m, MonadIO m, MonadThrow m)

=> ContentStore

An opened ContentStore.

-> ObjectDigest

The ObjectDigest for some stored object.

-> m ByteString

Lookup and return some previously stored object as a strict ByteString. Note that you'll probably need to use fromByteString to produce an ObjectDigest from whatever text or binary representation you've got from the usermddbetc.

fetchByteStringC :: (MonadError CsError m, MonadResource m) => ContentStore -> Conduit ObjectDigest m ByteString

Given an opened ContentStore and a Conduit of ObjectDigests, load each one into a strict ByteString and put it into the conduit. This is useful for stream many objects out of the content store at a time, like with exporting an RPM or other package format.

fetchFile

Arguments

:: (MonadBaseControl IO m, MonadError CsError m, MonadResource m)

=> ContentStore

An opened ContentStore.

-> ObjectDigest

The ObjectDigest of some stored object.

-> FilePath

The destination

-> m ()

Find some object in the content store and write it to a destination. If the destination already exists, it will be overwritten. If the object does not already exist, a CsErrorNoSuchObject will be thrown.

fetchLazyByteString :: (MonadBaseControl IO m, MonadError CsError m, MonadIO m, MonadThrow m) => ContentStore -> ObjectDigest -> m ByteString

Like fetchByteString, but uses lazy ByteStrings instead.

fetchLazyByteStringC :: (MonadError CsError m, MonadResource m) => ContentStore -> Conduit ObjectDigest m ByteString

Like fetchByteStringC, but uses lazy ByteStrings instead.

mkContentStore :: (MonadError CsError m, MonadIO m) => FilePath -> m ContentStore

Create a new ContentStore on disk, rooted at the path given, and return it as if openContentStore had also been called. If a content store already exists at the given root and is valid, return that as if openContentStore had been called. Various CsErrors could be thrown by this process.

openContentStore :: (MonadError CsError m, MonadIO m) => FilePath -> m ContentStore

Return an already existing ContentStore, after checking that it is valid. Various CsErrors could be thrown by this process.

storeByteString

Arguments

:: (MonadBaseControl IO m, MonadError CsError m, MonadIO m, MonadThrow m)

=> ContentStore

An opened ContentStore.

-> ByteString

An object to be stored, as a strict ByteString.

-> m ObjectDigest

Store some object into the content store and return its ObjectDigest. If an object with the same digest already exists in the content store, this is a duplicate. Simply return the digest of the already stored object and do nothing else. A CsErrorCollision will NOT be thrown.

storeByteStringC :: (MonadError CsError m, MonadResource m) => ContentStore -> Conduit ByteString m ObjectDigest

Like storeByteString, but read strict ByteStrings from a Conduit and put their ObjectDigests into the conduit. This is useful for storing many objects at a time, like with importing an RPM or other package format.

storeByteStringSink :: MonadResource m => ContentStore -> Sink ByteString m ObjectDigest

Read in a Conduit of strict ByteStrings, store the stream into an object in an already opened ContentStore, and return the final digest. This is useful for storing a stream of data as a single object.

storeDirectory

Arguments

:: (MonadBaseControl IO m, MonadError CsError m, MonadResource m)

=> ContentStore

An opened ContentStore.

-> FilePath

A directory tree containing many objects.

-> m [(FilePath, ObjectDigest)]

Store all objects in a directory tree in the content store, returning the name and ObjectDigest of each. Note that directories will not be stored. The content store only contains things that have content. If you need to store directory information, that should be handled externally to this module.

storeFile

Arguments

:: (MonadBaseControl IO m, MonadError CsError m, MonadResource m)

=> ContentStore

An opened ContentStore.

-> FilePath

The file to be stored.

-> m ObjectDigest

Store an already existing file in the content store, returning its ObjectDigest. The original file will be left on disk.

storeLazyByteString :: (MonadBaseControl IO m, MonadError CsError m, MonadIO m, MonadThrow m) => ContentStore -> ByteString -> m ObjectDigest

Like storeByteString, but uses lazy ByteStrings instead.

storeLazyByteStringC :: (MonadError CsError m, MonadResource m) => ContentStore -> Conduit ByteString m ObjectDigest

Like storeByteStringC, but uses lazy ByteStrings instead.

storeLazyByteStringSink :: MonadResource m => ContentStore -> Sink ByteString m ObjectDigest

Like storeByteStringSink, but uses lazy ByteStrings instead.