Hails.Database.MongoDB

Documentation

module Hails.Data.LBson

Types

type CollectionName = Collection

Name of collection

data CollectionPolicy l

Labels and policies associated with a collection. See Collection.

data Collection l

A collection policy is is a label, clearance and labeling policy. The label specifies who can write to a collection (i.e., only computatoin whose current label flows to the label of the collection). The clearance limits the sensitivity of the data written to the collection (i.e., the labels of all data in the collection must flow to the clearance). Note that the collection label does not impose a restriction on the data (i.e., data can have high integrity). The collection policy specifies the policies for labeling documents and fields of documents.

type CollectionMap l = Labeled l (Map CollectionName (CollectionPolicy l))

A labeled Collection map.

collection

Arguments

:: LabelState l p s

=> CollectionName

Collection name

-> l

Collection label

-> l

Collection clearance

-> RawPolicy l

Collection policy

-> LIO l p s (Collection l)

Create a collection given a collection name, label, clearance, and policy. Note that the collection label and clearance must be above the current label and below the current clearance.

collectionP

Arguments

:: LabelState l p s

=> p

Privileges

-> CollectionName

Collection name

-> l

Collection label

-> l

Collection clearance

-> RawPolicy l

Collection policy

-> LIO l p s (Collection l)

Same as collection, but uses privileges when comparing the collection label and clearance with the current label and clearance.

type DatabaseName = Database

Name of database

data Database l

A database has a label, which is used for controlling access to the database, an internal identifier corresponding to the underlying MongoDB database, and a set of Collections protected by a label.

assocCollection :: LabelState l p s => Collection l -> Database l -> LIO l p s (Database l)

Same as assocCollectionP, but does not use privileges when writing to database collection map.

assocCollectionP :: LabelState l p s => p -> Collection l -> Database l -> LIO l p s (Database l)

Associate a collection with the underlying database.

data RawPolicy l

A RawPolicy encodes a document policy, and all field policies. It is required that all fields of type PolicyLabled have a field/column policy -- if using only this low-level interface a runtime-error will occur if this is not satisfied.

Constructors

RawPolicy

Fields

rawDocPolicy :: Document l -> l

A row (document) policy is a function from a Document to a Label.

rawFieldPolicies :: [(Key, FieldPolicy l)]

A column (field) policy is a function from a Document to a Label, for each field of type PolicyLabeled.

data FieldPolicy l

A FieldPolicy specifies the policy-generated label of a field. SearchabelField specifies that the field can be referenced in the selection clause of a Query, and therefore the document label does not apply to it.

Constructors

SearchableField

FieldPolicy (Document l -> l)

isSearchableField :: FieldPolicy l -> Bool

Returns True if the policy is for a searchable field

data PolicyError

Field/column policies are required for every PolicyLabled value in a document.

Constructors

NoFieldPolicy

Policy for field not specified

InvalidPolicy

Policy application invalid

NoColPolicy

Policy for Collection not specified

InvalidFieldPolicyType

Field with associated policy is not of PolicyLabeled type

InvalidSearchableType

Searchable fields cannot contain labeled values

PolicyViolation

Policy has been violated

Instances

Show PolicyError

Typeable PolicyError

Exception PolicyError

data Action l p s a

Instances

Monad (Action l p s)

Functor (Action l p s)

Applicative (Action l p s)

LabelState l p s => MonadLIO (Action l p s) l p s

getDatabase :: Action l p s (Database l)

Get underlying database.

data Selection l

Selects documents in specified collection that match the selector.

Constructors

Selection

Fields

selector :: Selector l

Selector

coll :: CollectionName

Collection operaing

Instances

Select Selection

data Query l

Use select to create a basic query with defaults, then modify if desired. Example: (select sel col) {limit =: 10}. Note that unlike MongoDB's query functionality, our queries do not allow for projections (since policies may need a field that is not projects). Both the selection and sorting are restricted to searchable fields.

TODO: add snapshot.

Constructors

Query

Fields

options :: [QueryOption]

Query options, default [].

selection :: Selection l

WHERE clause,default [].

skip :: Word32

Number of documents to skip, default 0.

limit :: Limit

Max number of documents to return. Default, 0, means no limit.

sort :: Order l

Sort result by given order, default [].

batchSize :: BatchSize

The number of document to return in each batch response from the server. 0 means Mongo default.

hint :: Order l

Force mongoDB to use this index (must be only searchable fields). Default [], no hint.

Instances

Select Query

data Cursor l

A labeled cursor. The cursor is labeled with the join of the database and collection it reads from.

data DBConf

Database configuration, used to invoke withDB

Instances

Show DBConf

type DCAction = Action DCLabel DCPrivTCB ()

dcAccess :: Database DCLabel -> DCAction a -> DC (Either Failure a)

Open a pipe to a supplied server, or localhost. TODO: add support for connecting to replicas.

labelDatabase

Arguments

:: DBConf

Database configuratoin

-> DCLabel

Label of collection policies

-> DCLabel

Database label

-> DC (Database DCLabel)

The withDB functions should use this function to label their databases. TODO (DS/AL(: make every searchable field indexable.

class DatabasePolicy dbp where

Policy modules are instances of this class. In particular, when an application accesses a database, the runtime invokes createDatabasePolicy in the appropriate policy module.

Methods

createDatabasePolicy :: DBConf -> DCPrivTCB -> DC dbp

Given a DBConf generate an instance of this DatabasePolicy. This is the main entry point for policy modules. Policies should, in general, ether discard DBConf or store it in such a way that it is inaccessible to other modules since it contains the priviledge of the policy.

policyDB :: dbp -> Database DCLabel

Get the actual underlying Database instance for this policy.

class DatabasePolicy dbp => PolicyGroup dbp where

Class used to define groups in a policy-specific manner.

Methods

expandGroup :: dbp -> Principal -> DCAction [Principal]

Expands a principal of the form "#group_name" into a list of Principals

relabelGroups :: dbp -> DCLabeled a -> DC (DCLabeled a)

Relabeles the Labeled value by using the policy's privilege to downgrade the label and optionally re-taint in an application specific way, e.g. exanding groups of the form "#group_name" to a policy specified disjuction of real principals.

Policies are expected to implement this function by wrapping relabelGroupsP using their privilege and implementing expandGroup, which is called by relabelGroupsP.

relabelGroupsP :: PolicyGroup dbp => dbp -> DCPrivTCB -> Labeled DCLabel a -> DC (DCLabeled a)

Looks for disjuctions the privilege is able to downgrade and rewrites them by invoking expandGroup on each principle in the disjuction. Using the result, the function relabels the Labeled value. Clients should not call this directly, instead clients should call relabelGroups which policies may implement by wrapping this function.

relabelGroupsSafe :: PolicyGroup dbp => dbp -> Labeled DCLabel a -> DC (DCLabeled a)

A wrapper around relabelGroups that drops the current privileges and restores them after getting a result from relabelGroups.

class DatabasePolicy dbp => PrivilegeGrantGate dbp where

Class used to define policy-specifi privilege granting gate.

Methods

grantPriv

Arguments

:: dbp

Policy

-> Principal

App principal

-> DC (DCGate DCPrivTCB)

Request the policy's privilege-granting gate.

withLabel :: DCPrivTCB -> DCLabel -> DC a -> DC a

Given a set of privileges, a desired label and action. Lower the current label as close tothe desired label as possible, execute the action and raise the current label.

gateToLabeled :: DCPrivTCB -> DCLabeled (Document DCLabel) -> (Document DCLabel -> DC a) -> DC (DCLabeled a)

Given a set of privileges, a labeled document and computaiton on the (unlabeled version of the) documnet, downgrade the current label with the supplied privileges execute (only integrity), unlabel the document and apply the computation to it. The result is then labeled with the current label and the current label is reset to the original (if possible).

Query

insert :: Insert l p s doc => CollectionName -> doc -> Action l p s (Value l)

Insert document into collection and return its _id value, which is created automatically if not supplied. It is required that the current label flow to the label of the collection and database (and vice versa). Additionally, the document must be well-formed with respect to the collection policy. In other words, all the labeled values must be below the collection clearance and the policy be applied successfully.

insert_ :: Insert l p s doc => CollectionName -> doc -> Action l p s ()

Same as insert except it does not return _id

insertP :: Insert l p s doc => p -> CollectionName -> doc -> Action l p s (Value l)

Same as insert, but uses privileges when applying the collection policies, and doing label comparisons.

insertP_ :: Insert l p s doc => p -> CollectionName -> doc -> Action l p s ()

Same as insertP except it does not return _id

save :: Insert l p s doc => CollectionName -> doc -> Action l p s ()

Update a document based on the _id value. The IFC requirements subsume those of insert. Specifically, in addition to being able to apply all the policies and requiring that the current label flow to the label of the collection and database save requires that the current label flow to the label of the existing database record.

saveP :: Insert l p s doc => p -> CollectionName -> doc -> Action l p s ()

Like save, but uses privileges when performing label comparisons.

deleteOne :: (LabelState l p s, Serialize l) => Selection l -> Action l p s ()

Given a query, delete first object in selection. In addition to being able to read the object, write to the database and collection, it must be that the current label flow to the label of the existing document.

deleteOneP :: (LabelState l p s, Serialize l) => p -> Selection l -> Action l p s ()

Same as deleteOne, but uses privileges when performing label comparisons.

find :: (Serialize l, LabelState l p s) => Query l -> Action l p s (Cursor l)

Fetch documents satisfying query. A labeled Cursor is returned, which can be used to retrieve the actual Documents. Current label is raised to the join of the collection, database, and ccollection-policy label.

findP :: (Serialize l, LabelState l p s) => p -> Query l -> Action l p s (Cursor l)

Same as find, but uses privileges when raising the current label

findOne :: (LabelState l p s, Serialize l) => Query l -> Action l p s (Maybe (LabeledDocument l))

Fetch the first document satisfying query, or Nothing if not documents matched the query.

findOneP :: (LabelState l p s, Serialize l) => p -> Query l -> Action l p s (Maybe (LabeledDocument l))

Same as findOne, but uses privileges when performing label comparisons.

next :: (LabelState l p s, Serialize l) => Cursor l -> Action l p s (Maybe (LabeledDocument l))

Return next document in query result, or Nothing if finished. The current label is raised to join of the current label and Cursor label. The document is labeled according to the underlying 'Collection'\'s policies.

nextP :: (LabelState l p s, Serialize l) => p -> Cursor l -> Action l p s (Maybe (LabeledDocument l))

Same as next, but usess privileges raising the current label.

select :: (Select selectionOrQuery, Label l) => Selector l -> CollectionName -> selectionOrQuery l

Query or Selection that selects documents in collection that match selector. The choice of end type depends on use, for example, in find select sel col is a Query, but in delete it is a Selection.

Misc

data Failure

A connection failure, or a read or write exception like cursor expired or inserting a duplicate key. Note, unexpected data from the server is not a Failure, rather it is a programming error (you should call error in this case) because the client and server are incompatible and requires a programming change.

Instances

Eq Failure

Show Failure

Error Failure

fail is treated the same as a programming error. In other words, don't use it.

Monad m => MonadError Failure (Action m)

labeledDocI :: LabelState l p s => HttpReq a -> Labeled l ByteString -> LIO l p s (Labeled l (Document l))

Trusted transformer that takes a Labeled tuple with HttpReq and the request body as a ByteString and returns a Labeled Document with keys and values corresponding to the form fields from the request. The label on the Labeled result is the same as input. Arguments values are parsed in to BSON Strings except if the key is of the form "key_name[]" in which case all such arguments will be combined into an array of Strings.