Hails.Database.Structured

This module exports classes DCRecord and DCLabeledRecord that provide a way for Hails applications to interact with persistent data more easily. Specifically, it provides a way to work with Haskell types as opposed to "unstructured" Documents.

Documentation

class DCRecord a where

Class for converting from "structured" records to documents (and vice versa). Minimal definition consists of toDocument, fromDocument, and recordCollection. All database operations performed on the collection defined by recordCollection.

Methods

fromDocument :: Monad m => Document -> m a

Convert a document to a record

toDocument :: a -> Document

Convert a record to a document

recordCollection :: a -> CollectionName

Get the collection name for the record

findBy :: (BsonVal v, MonadDB m) => CollectionName -> FieldName -> v -> m (Maybe a)

Find an object with matching value for the given key. If the object does not exist or cannot be read (its label is above the clearance), this returns Nothing.

findWhere :: MonadDB m => Query -> m (Maybe a)

Find an object with given query

insertRecord :: MonadDB m => a -> m ObjectId

Insert a record into the database

saveRecord :: MonadDB m => a -> m ()

Update a record in the database

findByP :: (BsonVal v, MonadDB m) => DCPriv -> CollectionName -> FieldName -> v -> m (Maybe a)

Same as findBy, but uses privileges.

findWhereP :: MonadDB m => DCPriv -> Query -> m (Maybe a)

Same as findWhere, but uses privileges.

insertRecordP :: MonadDB m => DCPriv -> a -> m ObjectId

Same as insertRecord, but uses privileges.

saveRecordP :: MonadDB m => DCPriv -> a -> m ()

Same as saveRecord, but uses privileges.

findAll :: (DCRecord a, MonadDB m) => Query -> m [a]

Find all records that satisfy the query and can be read, subject to the current clearance.

findAllP :: (DCRecord a, MonadDB m) => DCPriv -> Query -> m [a]

Same as findAll, but uses privileges.

class (PolicyModule pm, DCRecord a) => DCLabeledRecord pm a | a -> pm where

Class used by a policy module to translate a labeled record to a labeled document. Since the insert and save functions use the policy module's privileges, only the policy module should be allowed to create an instance of this class. Thus, we leverage the fact that the value constructor for a PolicyModule is not exposed to untrusted code and require the policy module to create such a value in endorseInstance. The minimal implementation needs to define endorseInstance.

Methods

insertLabeledRecord :: MonadDB m => DCLabeled a -> m ObjectId

Insert a labeled record into the database.

saveLabeledRecord :: MonadDB m => DCLabeled a -> m ()

Insert a labeled record into the database

insertLabeledRecordP :: MonadDB m => DCPriv -> DCLabeled a -> m ObjectId

Same as insertLabeledRecord, but using explicit privileges.

saveLabeledRecordP :: MonadDB m => DCPriv -> DCLabeled a -> m ()

Same as saveLabeledRecord, but using explicit privileges.

endorseInstance :: DCLabeled a -> pm

Endorse the implementation of this instance. Note that this is reduced to WHNF to catch invalid instances that use undefined.

Example implementation:

 endorseInstance _ = MyPolicyModuleTCB {- May leave other values undefined -}

toLabeledDocument :: (MonadDB m, DCLabeledRecord pm a) => DCLabeled a -> m (DCLabeled Document)

Convert labeled record to labeled document.

fromLabeledDocument :: forall m pm a. (MonadDB m, DCLabeledRecord pm a) => DCLabeled Document -> m (DCLabeled a)

Convert labeled document to labeled record

toLabeledDocumentP

Arguments

:: (MonadDB m, DCLabeledRecord pm a)

=> DCPriv

-> DCLabeled a

Labeled record

-> m (DCLabeled Document)

Uses the policy modules's privileges to convert a labeled record to a labeled document, if the policy module created an instance of DCLabeledRecord.

fromLabeledDocumentP :: forall m pm a. (MonadDB m, DCLabeledRecord pm a) => DCPriv -> DCLabeled Document -> m (DCLabeled a)

Uses the policy modules's privileges to convert a labeled document to a labeled record, if the policy module created an instance of DCLabeledRecord.