Copyright | Copyright (c) 2015, Michael Alan Dorman |
---|---|
License | MIT |
Maintainer | mdorman@jaunder.io |
Stability | experimental |
Portability | POSIX |
Safe Haskell | None |
Language | Haskell2010 |
These types are intended for interacting with a CouchDB database. We generally favor giving things distinct types for different uses, though this is not a hard and fast rule.
- newtype Db = Db {}
- newtype DocId = DocId {
- unwrapDocId :: Text
- newtype DocRev = DocRev {
- unwrapDocRev :: Text
- newtype Host = Host {
- unwrapHost :: Text
- newtype Password = Password {}
- newtype Port = Port {
- unwrapPort :: Int
- newtype User = User {
- unwrapUser :: Text
- reqDocId :: DocId -> ByteString
- reqDocRev :: DocRev -> ByteString
- reqPassword :: Password -> ByteString
- reqUser :: User -> ByteString
- data Context = Context {
- ctxManager :: Manager
- ctxHost :: Host
- ctxPort :: Port
- ctxCred :: Maybe Credentials
- ctxCookies :: CookieJar
- ctxDb :: Maybe Db
- reqDb :: Context -> ByteString
- reqHost :: Context -> ByteString
- reqPort :: Context -> Int
- data Credentials = Basic {}
- type QueryParameters = [(ByteString, Maybe ByteString)]
- class ToQueryParameters a where
- toQueryParameters :: a -> QueryParameters
- toQP :: ByteString -> (a -> ByteString) -> Maybe a -> Maybe (ByteString, Maybe ByteString)
- boolToQP :: ByteString -> Maybe Bool -> Maybe (ByteString, Maybe ByteString)
- docIdToQP :: ByteString -> Maybe DocId -> Maybe (ByteString, Maybe ByteString)
- docRevToQP :: ByteString -> Maybe DocRev -> Maybe (ByteString, Maybe ByteString)
- intToQP :: ByteString -> Maybe Int -> Maybe (ByteString, Maybe ByteString)
- textToQP :: ByteString -> Maybe Text -> Maybe (ByteString, Maybe ByteString)
- class ToHTTPHeaders a where
- toHTTPHeaders :: a -> [Header]
- toHH :: HeaderName -> (a -> ByteString) -> Maybe a -> Maybe Header
- boolToHH :: HeaderName -> Maybe Bool -> Maybe Header
- data DbUpdates = DbUpdates {}
- dbUpdatesParam :: DbUpdates
- data DbChanges = DbChanges {
- cDocIds :: Maybe [DocId]
- cConflicts :: Maybe Bool
- cDescending :: Maybe Bool
- cFeed :: Maybe FeedType
- cFilter :: Maybe Text
- cHeartBeat :: Maybe Int
- cIncludeDocs :: Maybe Bool
- cAttachments :: Maybe Bool
- cAttEncodingInfo :: Maybe Bool
- cLastEvent :: Maybe Text
- cSince :: Maybe SinceType
- cStyle :: Maybe StyleType
- cTimeout :: Maybe Int
- cView :: Maybe Text
- dbChangesParam :: DbChanges
- data DbAllDocs = DbAllDocs {
- adConflicts :: Maybe Bool
- adDescending :: Maybe Bool
- adEndKey :: Maybe Text
- adEndKeyDocId :: Maybe DocId
- adIncludeDocs :: Maybe Bool
- adInclusiveEnd :: Maybe Bool
- adKey :: Maybe Text
- adLimit :: Maybe Int
- adSkip :: Maybe Int
- adStale :: Maybe Bool
- adStartKey :: Maybe Text
- adStartKeyDocId :: Maybe DocId
- adUpdateSeq :: Maybe Bool
- dbAllDocs :: DbAllDocs
- data DbBulkDocs = DbBulkDocs {}
- dbBulkDocs :: DbBulkDocs
- data ModifyDoc = ModifyDoc {}
- modifyDoc :: ModifyDoc
- data RetrieveDoc = RetrieveDoc {
- dgdAttachments :: Maybe Bool
- dgdAttEncodingInfo :: Maybe Bool
- dgdAttsSince :: [DocRev]
- dgdConflicts :: Maybe Bool
- dgdDeletedConflicts :: Maybe Bool
- dgdLatest :: Maybe Bool
- dgdLocalSeq :: Maybe Bool
- dgdMeta :: Maybe Bool
- dgdOpenRevs :: [DocRev]
- dgdRev :: Maybe DocId
- dgdRevs :: Maybe Bool
- dgdRevsInfo :: Maybe Bool
- retrieveDoc :: RetrieveDoc
- data FeedType
- feedTypeToQP :: Maybe FeedType -> Maybe (ByteString, Maybe ByteString)
- data SinceType
- sinceTypeToQP :: Maybe SinceType -> Maybe (ByteString, Maybe ByteString)
- data StyleType
- styleTypeToQP :: Maybe StyleType -> Maybe (ByteString, Maybe ByteString)
- data DocRevMap = DocRevMap [(DocId, [DocRev])]
- data ViewSpec = ViewSpec {}
- data DesignDoc = DesignDoc {
- ddocId :: DocId
- ddocRev :: DocRev
- ddocLanguage :: Maybe Text
- ddocOptions :: Maybe (HashMap Text Text)
- ddocFilters :: Maybe (HashMap Text Text)
- ddocLists :: Maybe (HashMap Text Text)
- ddocShows :: Maybe (HashMap Text Text)
- ddocUpdates :: Maybe (HashMap Text Text)
- ddocValidation :: Maybe Text
- ddocViews :: Maybe (HashMap Text ViewSpec)
- data ViewIndexInfo = ViewIndexInfo {
- viCompactRunning :: Bool
- viDataSize :: Int
- viDiskSize :: Int
- viLanguage :: Text
- viPurgeSeq :: Int
- viSignature :: Text
- viUpdateSeq :: Int
- viUpdaterRunning :: Bool
- viWaitingClients :: Int
- viWaitingCommit :: Bool
- data ViewParams = ViewParams {
- vpAttachments :: Maybe Bool
- vpAttEncodingInfo :: Maybe Bool
- vpConflicts :: Maybe Bool
- vpDescending :: Maybe Bool
- vpEndKey :: Maybe Text
- vpEndKeyDocId :: Maybe DocId
- vpGroup :: Maybe Bool
- vpGroupLevel :: Maybe Int
- vpIncludeDocs :: Maybe Bool
- vpInclusiveEnd :: Maybe Bool
- vpKey :: Maybe Text
- vpLimit :: Maybe Int
- vpReduce :: Maybe Bool
- vpSkip :: Maybe Int
- vpStale :: Maybe Bool
- vpStartKey :: Maybe Text
- vpStartKeyDocId :: Maybe DocId
- vpUpdateSeq :: Maybe Bool
- viewParams :: ViewParams
- type Result a = Either Error (a, Maybe CookieJar)
- data CreateResult
- data Error
Basic types to distinguish CouchDB information
The name of a database
The id of a document
DocId | |
|
The revision of a document
The name of a host
Host | |
|
The password of a user
The name of a user
User | |
|
Handling encoding
reqDocId :: DocId -> ByteString Source
Convert a DocId
directly into a ByteString
reqDocRev :: DocRev -> ByteString Source
Convert a DocRev
directly into a ByteString
reqPassword :: Password -> ByteString Source
Convert a Password
directly into a ByteString
reqUser :: User -> ByteString Source
Convert a User
directly into a ByteString
Request Context
This represents the context for each CouchDB request.
This contains all the bits that are unlikely to vary between requests.
Eventually, we should have routines that are smart enough to pull this out of a suitably-set-up Monad, so you could just stash it there and forget about it.
Context | |
|
reqDb :: Context -> ByteString Source
Pull the appropriately encoded database out of the context
reqHost :: Context -> ByteString Source
Pull the appropriately encoded host out of the context
data Credentials Source
The credentials for each CouchDB request.
Many operations in CouchDB require some sort of authentication. We will store the credentials in their various forms here (though we're sticking to HTTP Basic Authentication for now).
There are operations on the request that know how to modify the request appropriately depending on which credential type is in play.
Building requests
Handling Query Parameters
type QueryParameters = [(ByteString, Maybe ByteString)] Source
A quick type alias for query parameters.
class ToQueryParameters a where Source
A typeclass for types that can be converted to query parameters.
toQueryParameters :: a -> QueryParameters Source
Performs the actual conversion
ToQueryParameters ViewParams | Convert to query parameters |
ToQueryParameters RetrieveDoc | Convert to query parameters |
ToQueryParameters ModifyDoc | Convert to query parameters (partial) |
ToQueryParameters DbAllDocs | Convert to query parameters |
ToQueryParameters DbChanges | Convert to query parameters |
ToQueryParameters DbUpdates | Convert to query parameters |
Helpers for converting values to Query Parameters
:: ByteString | The name of the query parameter |
-> (a -> ByteString) | A function from the raw value to a |
-> Maybe a | The raw value |
-> Maybe (ByteString, Maybe ByteString) |
Convert a value to a query parameter
boolToQP :: ByteString -> Maybe Bool -> Maybe (ByteString, Maybe ByteString) Source
Handle converting Bool
values
docIdToQP :: ByteString -> Maybe DocId -> Maybe (ByteString, Maybe ByteString) Source
Handle converting DocId
values
docRevToQP :: ByteString -> Maybe DocRev -> Maybe (ByteString, Maybe ByteString) Source
Handle converting DocRev
values
intToQP :: ByteString -> Maybe Int -> Maybe (ByteString, Maybe ByteString) Source
Handle converting Int
values
textToQP :: ByteString -> Maybe Text -> Maybe (ByteString, Maybe ByteString) Source
Handle converting Text
values
Handling Header values
class ToHTTPHeaders a where Source
A typeclass for types that can be converted to headers.
toHTTPHeaders :: a -> [Header] Source
Performs the actual conversion
ToHTTPHeaders ModifyDoc | Convert to HTTP Headers (partial) |
Helpers for converting values to Headers
:: HeaderName | The name of the header |
-> (a -> ByteString) | A function from the raw value to a |
-> Maybe a | The raw value |
-> Maybe Header |
Convert a value to a Header
Parameters for different requests.
Parameters for monitoring server database creation
The basic structure
ToQueryParameters DbUpdates | Convert to query parameters |
dbUpdatesParam :: DbUpdates Source
The default (empty) parameters
Parameters for monitoring database changes
The basic structure
DbChanges | |
|
ToQueryParameters DbChanges | Convert to query parameters |
dbChangesParam :: DbChanges Source
The default (empty) parameters
Parameters for bulk retrieval of documents.
The basic structure
DbAllDocs | |
|
ToQueryParameters DbAllDocs | Convert to query parameters |
Paramters for bulk creation and updating parameters
data DbBulkDocs Source
The basic structure
dbBulkDocs :: DbBulkDocs Source
The default (empty) parameters for bulk creation and update of documents
Parameters for modifying documents
The basic structure
ToHTTPHeaders ModifyDoc | Convert to HTTP Headers (partial) |
ToQueryParameters ModifyDoc | Convert to query parameters (partial) |
Parameters for retrieving documents
data RetrieveDoc Source
The basic structure
RetrieveDoc | |
|
ToQueryParameters RetrieveDoc | Convert to query parameters |
retrieveDoc :: RetrieveDoc Source
The default (empty) parameters
Specifying how to monitor updates
feedTypeToQP :: Maybe FeedType -> Maybe (ByteString, Maybe ByteString) Source
Convert feed to Query Parameter
sinceTypeToQP :: Maybe SinceType -> Maybe (ByteString, Maybe ByteString) Source
Convert since to Query Parameter
styleTypeToQP :: Maybe StyleType -> Maybe (ByteString, Maybe ByteString) Source
Convert style to Query Parameter
Document revision map
The basic data type
View specification type
The basic type
Design document type
The basic type
DesignDoc | |
|
A type for view information
data ViewIndexInfo Source
The basic type
ViewIndexInfo | |
|
Eq ViewIndexInfo | |
Show ViewIndexInfo | |
Generic ViewIndexInfo | |
FromJSON ViewIndexInfo | decode from JSON |
type Rep ViewIndexInfo |
Parameters for view retrieval.
data ViewParams Source
The basic type
ViewParams | |
|
ToQueryParameters ViewParams | Convert to query parameters |
viewParams :: ViewParams Source
The default (empty) parameters
Results of a request
type Result a = Either Error (a, Maybe CookieJar) Source
Calls in the Explicit interface will always return a Result
, so we make it easy to type here.
Some success values
data CreateResult Source
Result type for creating a new document in a database.
Error values These will come to cover the gamut from failure to parse a particular JSON value to document conflicts. We try to differentiate in useful ways without being slavish about it.
These represent Failure modes for making CouchDB requests.
AlreadyExists | The database already exists |
Conflict | The document already exists, and without the appropriate rev |
HttpError HttpException | The server complained about the content of our request. Sounds like the library is broken. :( |
ImplementationError Text | The server complained about the content of our request. Sounds like the library is broken. :( |
InvalidName Text | The name you tried to give for the DB is invalid |
NotFound | The thing you were looking for was not found |
ParseIncomplete | We ran out of input before we succeeded in parsing a JSON |
ParseFail Text | There was some sort of syntactic issue with the text we were attempting to parse. |
Unauthorized | The credentials you used do not have access to this resource |
Unknown | Don't understand the failure |