examples/

modified:   Cargo.lock
modified:   Cargo.toml
new file:   examples/disk.rs
new file:   examples/memory.rs
new file:   examples/template.rs

Author: RandyMcMillan

Cargo.lock

@@ -74,6 +74,7 @@ oorandom = "11.1.3"
 random-access-storage = "5.0.0"
 random-access-disk = { version = "3.0.0", default-features = false }
 random-access-memory = "3.0.0"
+tempfile = "3.8.1"
 
 [dev-dependencies]
 async-std = { version = "1.12.0", features = ["attributes", "unstable"] }

Cargo.toml

@@ -0,0 +1,93 @@
+#[cfg(feature = "async-std")]
+use async_std::main as async_main;
+use hypercore::{HypercoreBuilder, HypercoreError, Storage};
+use tempfile::Builder;
+#[cfg(feature = "tokio")]
+use tokio::main as async_main;
+
+/// Example about using an in-memory hypercore.
+#[async_main]
+async fn main() {
+
+    // For the purposes of this example, first create a
+    // temporary directory to hold hypercore.
+    let dir = Builder::new()
+        .prefix("gnostr")
+        .tempdir()
+        .unwrap()
+        .into_path();
+
+    println!(
+        "{}",
+        dir.display());
+
+    // Create a disk storage, overwriting existing values.
+    let overwrite = true;
+    let storage = Storage::new_disk(&dir, overwrite)
+        .await
+        .expect("Could not create disk storage");
+
+    // Build a new disk hypercore
+    let mut hypercore = HypercoreBuilder::new(storage)
+        .build()
+        .await
+        .expect("Could not create disk hypercore");
+
+    // Append values to the hypercore
+    hypercore.append(b"Hello, ").await.unwrap();
+    hypercore.append(b"from ").await.unwrap();
+
+    // Close hypercore
+    drop(hypercore);
+
+    // Open hypercore again from same directory, not
+    // overwriting.
+    let overwrite = false;
+    let storage = Storage::new_disk(&dir, overwrite)
+        .await
+        .expect("Could not open existing disk storage");
+    let mut hypercore = HypercoreBuilder::new(storage)
+        .open(true)
+        .build()
+        .await
+        .expect("Could not open disk hypercore");
+
+    // Append new values to the hypercore
+    hypercore.append(b" disk hypercore!").await.unwrap();
+
+    // Add three values and clear the first two
+    let batch: &[&[u8]] = &[
+        b"first value to clear",
+        b"second value to clear",
+        b"third value to keep",
+    ];
+    let new_length = hypercore.append_batch(batch).await.unwrap().length;
+    hypercore
+        .clear(new_length - 3, new_length - 1)
+        .await
+        .unwrap();
+
+    // The two values return None, but the last one returns correctly
+    assert!(hypercore.get(3).await.unwrap().is_none());
+    assert!(hypercore.get(4).await.unwrap().is_none());
+    assert_eq!(
+        hypercore.get(5).await.unwrap().unwrap(),
+        b"third value to keep"
+    );
+
+    // Print the first three values, converting binary back to string
+    println!(
+        "{}{}{}",
+        format_res(hypercore.get(0).await),
+        format_res(hypercore.get(1).await),
+        format_res(hypercore.get(2).await)
+    ); // prints "Hello, from disk hypercore!"
+}
+
+fn format_res(res: Result<Option<Vec<u8>>, HypercoreError>) -> String {
+    match res {
+        Ok(Some(bytes)) => String::from_utf8(bytes).expect("Shouldn't fail in example"),
+        Ok(None) => "Got None in feed".to_string(),
+        Err(e) => format!("Error getting value from feed, reason = {e:?}"),
+    }
+}

examples/disk.rs

@@ -0,0 +1,59 @@
+#[cfg(feature = "async-std")]
+use async_std::main as async_main;
+use hypercore::{HypercoreBuilder, HypercoreError, Storage};
+#[cfg(feature = "tokio")]
+use tokio::main as async_main;
+
+/// Example about using an in-memory hypercore.
+#[async_main]
+async fn main() {
+    // Create a memory storage
+    let storage = Storage::new_memory()
+        .await
+        .expect("Could not create memory storage");
+
+    // Build hypercore
+    let mut hypercore = HypercoreBuilder::new(storage)
+        .build()
+        .await
+        .expect("Could not create memory hypercore");
+
+    // Append values
+    hypercore.append(b"Hello, ").await.unwrap();
+    hypercore.append(b"from memory hypercore!").await.unwrap();
+
+    // Add three values and clear the first two
+    let batch: &[&[u8]] = &[
+        b"first value to clear",
+        b"second value to clear",
+        b"third value to keep",
+    ];
+    let new_length = hypercore.append_batch(batch).await.unwrap().length;
+    hypercore
+        .clear(new_length - 3, new_length - 1)
+        .await
+        .unwrap();
+
+    // The two values return None, but the last one returns correctly
+    assert!(hypercore.get(2).await.unwrap().is_none());
+    assert!(hypercore.get(3).await.unwrap().is_none());
+    assert_eq!(
+        hypercore.get(4).await.unwrap().unwrap(),
+        b"third value to keep"
+    );
+
+    // Print values, converting binary back to string
+    println!(
+        "{}{}",
+        format_res(hypercore.get(0).await),
+        format_res(hypercore.get(1).await)
+    ); // prints "Hello, from memory hypercore!"
+}
+
+fn format_res(res: Result<Option<Vec<u8>>, HypercoreError>) -> String {
+    match res {
+        Ok(Some(bytes)) => String::from_utf8(bytes).expect("Shouldn't fail in example"),
+        Ok(None) => "Got None in feed".to_string(),
+        Err(e) => format!("Error getting value from feed, reason = {e:?}"),
+    }
+}

examples/memory.rs

@@ -0,0 +1,121 @@
+#[cfg(feature = "async-std")]
+use async_std::main as async_main;
+use hypercore::{
+    Hypercore, HypercoreBuilder, HypercoreError, PartialKeypair, RequestBlock, RequestUpgrade,
+    Storage,
+};
+use random_access_disk::RandomAccessDisk;
+use random_access_memory::RandomAccessMemory;
+use tempfile::Builder;
+#[cfg(feature = "tokio")]
+use tokio::main as async_main;
+
+/// Example on how to replicate a (disk) hypercore to another (memory) hypercore.
+/// NB: The replication functions used here are low-level, built for use in the wire
+/// protocol.
+#[async_main]
+async fn main() {
+    // For the purposes of this example, first create a
+    // temporary directory to hold hypercore.
+    let dir = Builder::new()
+        .prefix("examples_replication")
+        .tempdir()
+        .unwrap()
+        .into_path();
+
+    println!(
+        "{}",
+        dir.display());
+
+
+    // Create a disk storage, overwriting existing values.
+    let overwrite = true;
+    let storage = Storage::new_disk(&dir, overwrite)
+        .await
+        .expect("Could not create disk storage");
+
+    // Build a new disk hypercore
+    let mut origin_hypercore = HypercoreBuilder::new(storage)
+        .build()
+        .await
+        .expect("Could not create disk hypercore");
+
+    // Append values to the hypercore
+    let batch: &[&[u8]] = &[b"Hello, ", b"from ", b"replicated ", b"hypercore!"];
+    origin_hypercore.append_batch(batch).await.unwrap();
+
+    // Store the public key
+    let origin_public_key = origin_hypercore.key_pair().public;
+
+    // Create a peer of the origin hypercore using the public key
+    let mut replicated_hypercore = HypercoreBuilder::new(
+        Storage::new_memory()
+            .await
+            .expect("Could not create memory storage"),
+    )
+    .key_pair(PartialKeypair {
+        public: origin_public_key,
+        secret: None,
+    })
+    .build()
+    .await
+    .expect("Could not create memory hypercore");
+
+    // Replicate the four values in random order
+    replicate_index(&mut origin_hypercore, &mut replicated_hypercore, 3).await;
+    replicate_index(&mut origin_hypercore, &mut replicated_hypercore, 0).await;
+    replicate_index(&mut origin_hypercore, &mut replicated_hypercore, 2).await;
+    replicate_index(&mut origin_hypercore, &mut replicated_hypercore, 1).await;
+
+    // Print values from replicated hypercore, converting binary back to string
+    println!(
+        "{}{}{}{}",
+        format_res(replicated_hypercore.get(0).await),
+        format_res(replicated_hypercore.get(1).await),
+        format_res(replicated_hypercore.get(2).await),
+        format_res(replicated_hypercore.get(3).await)
+    ); // prints "Hello, from replicated hypercore!"
+}
+
+async fn replicate_index(
+    origin_hypercore: &mut Hypercore<RandomAccessDisk>,
+    replicated_hypercore: &mut Hypercore<RandomAccessMemory>,
+    request_index: u64,
+) {
+    let missing_nodes = origin_hypercore
+        .missing_nodes(request_index)
+        .await
+        .expect("Could not get missing nodes");
+    let upgrade_start = replicated_hypercore.info().contiguous_length;
+    let upgrade_length = origin_hypercore.info().contiguous_length - upgrade_start;
+
+    let proof = origin_hypercore
+        .create_proof(
+            Some(RequestBlock {
+                index: request_index,
+                nodes: missing_nodes,
+            }),
+            None,
+            None,
+            Some(RequestUpgrade {
+                start: upgrade_start,
+                length: upgrade_length,
+            }),
+        )
+        .await
+        .expect("Creating proof error")
+        .expect("Could not get proof");
+    // Then the proof is verified and applied to the replicated party.
+    assert!(replicated_hypercore
+        .verify_and_apply_proof(&proof)
+        .await
+        .expect("Verifying and applying proof failed"));
+}
+
+fn format_res(res: Result<Option<Vec<u8>>, HypercoreError>) -> String {
+    match res {
+        Ok(Some(bytes)) => String::from_utf8(bytes).expect("Shouldn't fail in example"),
+        Ok(None) => "Got None in feed".to_string(),
+        Err(e) => format!("Error getting value from feed, reason = {e:?}"),
+    }
+}