Struct fog_pack::schema::Schema

pub struct Schema { /* private fields */ }

A Schema, which can be used to encode/decode a document or entry, while verifying its contents.

Schema are decoded from a correctly formatted Document that describes the format of other documents and their associated entries. They also include recommended compression settings for documents & entries adhering to them, which may include compression dictionaries.

A schema must come from a Document. To create one directly, use the SchemaBuilder, then decode the resulting Document into a schema.

Implementations

impl Schema

pub fn from_doc(doc: &Document) -> Result<Self>

Attempt to create a schema from a given document. Fails if the document isn’t a schema.

Warnings

If working with external, untrusted schemas, it’s advisable to use Schema::from_doc_max_regex instead, as regular expressions are hands-down the easiest way to exhaust memory in a system.

pub fn from_doc_max_regex(doc: &Document, max_regex: u8) -> Result<Self>

Attempt to create a schema from a given document, first checking how many regular expressions would be present in the schema and failing out if it’s above the provided limit.

For a rough guide of what to set max_regex to, know that every regex has an approximate max memory size of 12 MiB, so a malicious schema can use up at least max_regex * 12 MiB bytes off the heap.

pub fn hash(&self) -> &Hash

Get the hash of this schema.

pub fn validate_new_doc(&self, doc: NewDocument) -> Result<Document>

Validate a NewDocument, turning it into a Document. Fails if the document doesn’t use this schema, or if it doesn’t meet this schema’s requirements.

pub fn encode_doc(&self, doc: Document) -> Result<(Hash, Vec<u8>)>

Encode a Document, returning the resulting Document’s hash and fully encoded format. Fails if the document doesn’t use this schema.

pub fn decode_doc(&self, doc: Vec<u8>) -> Result<Document>

Decode a document that uses this schema.

pub fn trusted_decode_doc(&self, doc: Vec<u8>) -> Result<Document>

Decode a Document, skipping any checks of the data. This should only be run when the raw document has definitely been passed through validation before, i.e. if it is stored in a local database after going through encode_doc.

pub fn validate_new_entry( &self, entry: NewEntry ) -> Result<DataChecklist<'_, Entry>>

Validate a NewEntry, turning it into a Entry. Fails if provided the wrong parent document, the parent document doesn’t use this schema, or the entry doesn’t meet the schema requirements. The resulting Entry is stored in a DataChecklist that must be iterated over in order to finish validation.

pub fn encode_entry( &self, entry: Entry ) -> Result<(EntryRef, Vec<u8>, Vec<Hash>)>

Encode an Entry, returning the resulting Entry’s reference, its fully encoded format, and a list of Hashes of the Documents it needs for validation. Fails if provided the wrong parent document or the parent document doesn’t use this schema.

pub fn decode_entry( &self, entry: Vec<u8>, key: &str, parent: &Document ) -> Result<DataChecklist<'_, Entry>>

Decode an entry, given the key and parent Hash. Result is in a DataChecklist that must be iterated over in order to finish verification and get the resulting Entry.

pub fn trusted_decode_entry( &self, entry: Vec<u8>, key: &str, parent: &Document, entry_hash: &Hash ) -> Result<Entry>

Decode a Entry, skipping most checks of the data. This should only be run when the raw entry has definitely been passed through validation before, i.e. if it is stored in a local database after going through encode_entry.

pub fn encode_query(&self, query: NewQuery) -> Result<Vec<u8>>

Encode a query into a byte sequence. Fails if the query is against an entry key that isn’t in the schema, or if the query isn’t a valid one according to the various query permissions in the schema’s validators.

Queries are encoded like fog-pack documents, but without the header containing compression and schema info.

pub fn decode_query(&self, query: Vec<u8>) -> Result<Query>

Attempt to decode a query from a byte sequence. Fails if the byte sequence isn’t a valid encoding, if the query is against an entry key that isn’t in the schema, or if the query isn’t a valid one according to the various query permissions in the schema’s validators.

Queries are encoded like fog-pack documents, but without the header containing compression and schema info.

Trait Implementations

impl Clone for Schema

fn clone(&self) -> Schema

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Schema

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.