fog-pack builds on msgpack with a set of extensions useful for all structured data. The ultimate goal is to provide a single coherent approach to encoding data, validating it, and compressing it. Any existing data format can be replaced with fog-pack, without compromise.
To meet this lofty goal, it extends msg-pack by providing:
zstd for more information on the
compression used.First, include fog-pack in your Cargo.toml:
toml
[dependencies]
fog-pack = "0.1.0"
Before anything else, we must initialize the underlying crypto library:
```
crypto::init(); ```
Generally, a schema is the first thing you'll want to make. This specifies the format of all our immutable documents, along with the entries attached to them:
rust
// Create a simple schema for streaming text posts
let schema_doc = Document::new(fogpack!({
"req": {
"name": { "type": "Str" },
},
"entries": {
"post": {
"type": "Obj",
"req": {
"text": { "type": "Str" },
"time": { "type": "Time", "query": true, "ord": true}
}
}
}
})).unwrap();
let mut schema = Schema::from_doc(schema_doc).unwrap();
With a schema in place, we can create documents that adhere to them, and entries to attach to those documents:
```rust // Create a new text post document let mut my_posts = Document::new(fogpack!({ "": Value::from(schema.hash().clone()), "name": "My Text Posts", })).unwrap();
// Make our first post let now = SystemTime::now().durationsince(SystemTime::UNIXEPOCH).unwrap(); let mut firstpost = Entry::new( myposts.hash().clone(), "post".tostring(), fogpack!({ "text": "This is my very first post.", "time": Timestamp::fromsec(now.as_secs() as i64) }) ).unwrap(); ```
Entries are encoded fog-pack with an associated document and string field. They let us attach changing data to an immutable document, including links between documents.
Both documents and entries can be crytographically signed. This requires having a key vault in place, along with a key:
```rust // Create a Vault for storing our Identity, // which we'll use to sign posts. let mut vault = crypto::Vault::newfrompassword( crypto::PasswordLevel::Interactive, "Not a good password".tostring() ).unwrap(); let mykey = vault.new_key();
myposts.sign(&vault, &mykey).unwrap(); firstpost.sign(&vault, &mykey).unwrap(); ```
Both documents and entries go through a schema to be encoded; this lets them be validated and optionally compressed:
rust
let encoded_my_posts = schema.encode_doc(my_posts).unwrap();
let first_post_checklist = schema.encode_entry(first_post).unwrap();
let encoded_first_post = first_post_checklist.complete().unwrap();
Entries may require additional validation with documents they link to, but in this case, we don't need to do any additional validation and can retrieve the encoded entry right away.
Finally, where the schema allows it, we can make queries that will match against these entries:
rust
// We can create a query to use for picking posts within a time window
let my_posts_hash = extract_schema_hash(&encoded_my_posts[..]).unwrap().unwrap();
let query_last_day = Entry::new(
my_posts_hash,
"post".to_string(),
fogpack!({
"type": "Obj",
"unknown_ok": true,
"time": {
"type": "Time",
"min": (now.as_secs() as i64) - (24*60*60),
"max": now.as_secs() as i64,
}
})
).unwrap();
let query_last_day = encode_query(query_last_day);
Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.