content-store-0.2.0: Store and retrieve data from an on-disk store

Copyright(c) 2017 Red Hat Inc.
LicenseLGPL
Maintainerhttps://github.com/weldr
Stabilityalpha
Portabilityportable
Safe HaskellNone
LanguageHaskell2010

Data.ContentStore

Description

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

Synopsis

Documentation

data ContentStore Source #

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 Source #

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.

data CsMonad a Source #

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 Source # 

Methods

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

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

return :: a -> CsMonad a #

fail :: String -> CsMonad a #

Functor CsMonad Source # 

Methods

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

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

Applicative CsMonad Source # 

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 Source # 

Methods

liftIO :: IO a -> CsMonad a #

MonadResource CsMonad Source # 
MonadThrow CsMonad Source # 

Methods

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

MonadBase IO CsMonad Source # 

Methods

liftBase :: IO α -> CsMonad α #

MonadBaseControl IO CsMonad Source # 

Associated Types

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

MonadError CsError CsMonad Source # 

Methods

throwError :: CsError -> CsMonad a #

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

type StM CsMonad a Source # 

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

See the documentation for CsMonad.

contentStoreDigest :: ContentStore -> DigestAlgorithm Source #

Return the digest type used by a content store.

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

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 Source #

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 Source #

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 Source #

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.

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

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 Source #

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

storeByteString Source #

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 Source #

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 Source #

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 Source #

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 Source #

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.