p2panda_core/
extensions.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Traits required for defining custom extensions.
4//!
5//! User-defined extensions can be added to an operation's `Header` in order to extend the basic
6//! functionality of the core p2panda data types or to encode application-specific fields which
7//! should not be contained in the [`Body`](crate::Body). Extension values can themselves be
8//! derived from other header material, such as `PublicKey` or a headers' `Hash`.
9//!
10//! At a lower level this might be information relating to capabilities or group encryption schemes
11//! which is required to enforce access-control restrictions during sync. Alternatively, extensions
12//! might be used to set expiration timestamps and deletion flags in order to facilitate garbage
13//! collection of stale data from the network. The core p2panda data types intentionally don't
14//! enforce a single approach to such areas where there are rightly many different approaches, with
15//! the most suitable being dependent on specific use-case requirements.
16//!
17//! Interfaces which use p2panda core data types can require certain extensions to be present on
18//! any headers that their APIs accept using trait bounds. `p2panda-stream`, for example, uses the
19//! [`PruneFlag`](crate::PruneFlag) in order to implement automatic network-wide garbage
20//! collection.
21//!
22//! Extensions are encoded on a header and sent over the wire. We need to satisfy all trait
23//! requirements that `Header` requires, including `Serialize` and `Deserialize`.
24//!
25//! //! ## Example
26//!
27//! ```
28//! use p2panda_core::{Body, Hash, Extension, Header, PrivateKey};
29//! use serde::{Serialize, Deserialize};
30//!
31//! #[derive(Clone, Debug, Serialize, Deserialize)]
32//! struct LogId(Hash);
33//!
34//! #[derive(Clone, Debug, Default, Serialize, Deserialize)]
35//! struct Expiry(u64);
36//!
37//! #[derive(Clone, Debug, Serialize, Deserialize)]
38//! struct CustomExtensions {
39//!     log_id: Option<LogId>,
40//!     expires: Expiry,
41//! }
42//!
43//! impl Extension<LogId> for CustomExtensions {
44//!     fn extract(header: &Header<Self>) -> Option<LogId> {
45//!         if header.seq_num == 0 {
46//!             return Some(LogId(header.hash()));
47//!         };
48//!
49//!         header.extensions.log_id.clone()
50//!     }
51//! }
52//!
53//! impl Extension<Expiry> for CustomExtensions {
54//!     fn extract(header: &Header<Self>) -> Option<Expiry> {
55//!        Some(header.extensions.expires.clone())
56//!     }
57//! }
58//!
59//! let extensions = CustomExtensions {
60//!     log_id: None,
61//!     expires: Expiry(0123456),
62//! };
63//!
64//! let private_key = PrivateKey::new();
65//! let body: Body = Body::new("Hello, Sloth!".as_bytes());
66//!
67//! let mut header = Header {
68//!     version: 1,
69//!     public_key: private_key.public_key(),
70//!     signature: None,
71//!     payload_size: body.size(),
72//!     payload_hash: Some(body.hash()),
73//!     timestamp: 0,
74//!     seq_num: 0,
75//!     backlink: None,
76//!     previous: vec![],
77//!     extensions: extensions.clone(),
78//! };
79//!
80//! header.sign(&private_key);
81//!
82//! let log_id: LogId = header.extension().unwrap();
83//! let expiry: Expiry = header.extension().unwrap();
84//!
85//! assert_eq!(header.hash(), log_id.0);
86//! assert_eq!(extensions.expires.0, expiry.0);
87//! ```
88use std::fmt::Debug;
89
90use serde::{Deserialize, Serialize};
91
92use crate::Header;
93
94/// Trait definition of a single header extension type.
95pub trait Extension<T>: Extensions {
96    /// Extract the extension value from a header.
97    fn extract(_header: &Header<Self>) -> Option<T> {
98        None
99    }
100}
101
102/// Super-trait defining trait bounds required by custom extensions types.
103pub trait Extensions: Clone + Debug + for<'de> Deserialize<'de> + Serialize {}
104
105/// Blanket implementation of `Extensions` trait any type with the required bounds satisfied.
106impl<T> Extensions for T where T: Clone + Debug + for<'de> Deserialize<'de> + Serialize {}
p2panda_core/extensions.rs

p2panda_core/
extensions.rs
