Module p2panda_rs::document

Expand description

High-level datatype representing data published to the p2panda network as key-value pairs.

Documents are multi-writer and have automatic conflict resolution strategies which produce deterministic state for any two replicas. The underlying structure which make this possible is a directed acyclic graph of [Operation]’s. To arrive at the current state of a document the graph is topologically sorted, with any branches being ordered according to the conflicting operations [OperationId]. Each operation’s mutation is applied in order which results in a LWW (last write wins) resolution strategy.

All documents have an accomapanying Schema which describes the shape of the data they will contain. Every operation should have been validated aginst this schema before being included in the graph.

Documents are constructed through the DocumentBuilder or by conversion from vectors of a type implementing the [AsOperation], [WithId<OperationId>] and [WithPublicKey].

Example

// Construct a CREATE operation.
let operation_value = OperationValue::String("Panda Cafe".to_string());
let operation = OperationBuilder::new(&schema_id)
    .action(OperationAction::Create)
    .fields(&[("name", operation_value.clone())])
    .build()
    .unwrap();

// Build a document from a single operation, we include it's id and the public key of the
// author who published it.
let (document, _) = DocumentBuilder::new(vec![(operation_id.clone(), operation, public_key)]).build()?;
// The document view value contains the value we expect for the "name" field as well
// as the id of the operation which last updated this field.
assert_eq!(
    document.view().unwrap().get("name"),
    Some(&DocumentViewValue::new(&operation_id, &operation_value))
);

As can be seen in this example a tuple of ([OperationId], [Operation], [PublicKey]) is required for each operation included in the graph. The [OperationId] and [PublicKey] are both derived from the signed [Entry] the operation was published on.

A useful characteristic of documents is the ability to view state from any point in the past (as long as the operations have been retained, see below for details on this). Every state a document has passed through can be identified by a DocumentViewId which is the id’s of the current graph tip operations. This id can be used to request a view onto any state from the documents past.]

Example

// Construct a CREATE operation.
let operation_1_value = OperationValue::String("Panda Cafe".to_string());
let operation_1 = OperationBuilder::new(&schema_id)
    .action(OperationAction::Create)
    .fields(&[("name", operation_1_value.clone())])
    .build()
    .unwrap();

// Construct an UPDATE operation.
let operation_2_value = OperationValue::String("Polar Bear Cafe".to_string());
let operation_2 = OperationBuilder::new(&schema_id)
    .action(OperationAction::Update)
    .fields(&[("name", operation_2_value.clone())])
    .previous(&DocumentViewId::new(&[operation_id_1.clone()]))
    .build()
    .unwrap();

// Construct a document builder from these two operations.
let document_builder = DocumentBuilder::new(vec![
    (operation_id_1.clone(), operation_1, public_key),
    (operation_id_2.clone(), operation_2, public_key),
]);

// Build the document to it's latest view.
let (document, _) = document_builder.build().unwrap();

// The document view value contains the value we expect for the "name" field as well
// as the id of the operation which last updated this field.
assert_eq!(
    document.view().unwrap().get("name"),
    Some(&DocumentViewValue::new(&operation_id_2, &operation_2_value))
);

// Derive a document view id for the initial document state.
let document_view_id_1 = DocumentViewId::new(&[operation_id_1.clone()]);
// Build the document again but to this earlier state.
let (document, _) = document_builder.build_to_view_id(document_view_id_1).unwrap();

assert_eq!(
    document.view().unwrap().get("name"),
    Some(&DocumentViewValue::new(&operation_id_1, &operation_1_value))
)

Modules

error
Error types for creating or materializing documents and document views and validating the format of document ids and document view ids.
traits
Interfaces for interactions for document-like structs.

Structs

Document
High-level datatype representing data published to the p2panda network as key-value pairs.
DocumentBuilder
A struct for building documents from a collection of operations.
DocumentId
Identifier of a document.
DocumentView
The materialised view of a Document. It’s fields match the documents schema definition.
DocumentViewFields
A key value map of field keys to DocumentViewValues.
DocumentViewHash
Contains a hash over the sorted graph tips constituting this view id.
DocumentViewId
The identifier of a document view.
DocumentViewValue
The current value of a document fiew field as well as the id of the operation it came from.