hails- Multi-app web platform framework

Safe HaskellUnsafe




This module exports the type for a Hails BSON document, HsonDoc. A Hails document is akin to Data.Bson's documents, but differs in two ways. First, Hails restricts the number of types to a subset of BSON's (see BsonVal). This restriction is primarily due to the fact that many of the BSON types are redundant and not used (at least within Hails). Second, Hails allows for documents to contain policy-labeled values.

Policy labeled values (PolicyLabeled) are permitted only at the "top-level" of a document. (This is primarily done to keep policy-specification simple and may change in the future.) Consequently to allow for nested documents and documents containing an array of values we separate top-level fields (HsonField), that may contain policy labeled values, from potentially-nested fields (BsonField). A top-level field HsonField is thus either a BsonField or a PolicyLabled value.

To keep the TCB compact, this module does not export the combinators used to create documents in a friendly fashion. See Hails.Data.Hson for the safe external API.

Credit: Much of this code is based on/reuses Data.Bson.



type HsonDocument = [HsonField] Source

A top-level document containing HsonFields.

type BsonDocument = [BsonField] Source

A (possibly top-)level document containing BsonFields.


type FieldName = Text Source

The name of a field.


data HsonValue Source

An HsonValue is a top-level value that may either be a BsonValue or a policy labeled value. The separation of values into BsonValue and HsonValue is solely due to the restriction that policy-labeled values may only occur at the top level and BsonValues may be nested (e.g. using BsonArray and BsonDoc).


HsonValue BsonValue

Bson value

HsonLabeled PolicyLabeled

Policy labeled value

data BsonValue Source

A BsonValue is a subset of BSON (Data.Bson) values. Note that a BsonValue cannot contain any labeled values; all labeled values occur in a document as HsonValues. Correspondingly, BsonValues may be arbitrarily nested.


BsonFloat Double

Float value

BsonString Text

String value

BsonDoc BsonDocument

Inner document

BsonArray [BsonValue]

List of values

BsonBlob Binary

Binary blob value

BsonObjId ObjectId

Object Id value

BsonBool Bool

Boolean value


Time stamp value


The NULL value

BsonInt32 Int32

32-bit integer

BsonInt64 Int64

64-bit integer

data PolicyLabeled Source

A PolicyLabeled value can be either an unlabeled value for which the policy needs to be applied (NeedPolicyTCB), or an already labeled value (HasPolicyTCB). PolicyLabeled is a partially-opaque type; code should not be able to inspect the value of an unlabeleda value, but may inspect an already labeled value.


NeedPolicyTCB BsonValue

Policy was not applied

HasPolicyTCB (DCLabeled BsonValue)

Policy applied

data ObjectId :: *

A BSON ObjectID is a 12-byte value consisting of a 4-byte timestamp (seconds since epoch), a 3-byte machine id, a 2-byte process id, and a 3-byte counter. Note that the timestamp and counter fields must be stored big endian unlike the rest of BSON. This is because they are compared byte-by-byte and we want to ensure a mostly increasing order.


Oid Word32 Word64 

newtype Binary Source

Arbitrary binary blob




unBinary :: S8

type S8 = ByteString Source

Strict ByeString

Marshall to/from Data.Bson

hsonDocToDataBsonDocTCB :: HsonDocument -> Document Source

Convert a top-level document (i.e., HsonDocument) to a Data.Bson Document. This is the primary marshall-out function. All PolicyLabeled values are marshalled out as Data.Bson UserDefined values. This means that the UserDefined type is reserved and exposing it as a type in BsonValue would potentially lead to vulnerabilities in which labeled values can be marshalled in from well-crafted ByteStrings. Moreover, untrusted code should not have access to this function; having such access would allow it to inspect the serialized labeled values and thus violate IFC.

dataBsonDocToHsonDocTCB :: Document -> HsonDocument Source

Convert Data.Bson Document to a HsonDocument. This is the top-level function that marshalls BSON documents to Hails documents. This function assumes that all documents have been marshalled out using hsonDocToDataBsonDocTCB. Otherwise, the PolicyLabled values that are created from the document may be forged.


add__hails_prefix :: FieldName -> FieldName Source

Hails internal prefix that is used to serialized labeled values.