Add live social/sharing example binaries

Args-based (no hardcoded credentials) examples used to exercise the client
against a real Peergos server:
- follow_send_live: send a follow request
- complete_friend_share_live: accept/process a pending follow request, then
  read-share a file with the friend
- create_writeshare_live: create a file and share it writable
- mkdir_writeshare_live: create a directory and share it writable
- read_dir_live: list a directory and sanity-check any PDFs

Author: ianopolous

crates/peergos-fs/examples/complete_friend_share_live.rs

@@ -0,0 +1,70 @@
+//! Complete a friendship (process any pending follow request from `target`) and
+//! read-share a file with them, on a live server.
+//!   cargo run -p peergos-fs --example complete_friend_share_live -- <base> <username> <password> <target> <file-name>
+
+use peergos_core::mutable::HttpMutablePointers;
+use peergos_core::{ContentAddressedStorage, HttpStorage, ReqwestPoster};
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut args = std::env::args().skip(1);
+    let base = args.next().unwrap_or_else(|| "https://test.peergos.net/".to_string());
+    let username = args.next().expect("usage: <base> <username> <password> <target> <file-name>");
+    let password = args.next().expect("usage: <base> <username> <password> <target> <file-name>");
+    let target = args.next().expect("usage: <base> <username> <password> <target> <file-name>");
+    let file_name = args.next().expect("usage: <base> <username> <password> <target> <file-name>");
+
+    let poster = Arc::new(ReqwestPoster::new(&base, false)?);
+    let store: Arc<dyn ContentAddressedStorage> = Arc::new(HttpStorage::new(poster.clone(), true));
+    let mutable = HttpMutablePointers::new(poster.clone());
+
+    let user = peergos_fs::login(&username, &password, poster.as_ref(), store.clone(), &mutable, None).await?;
+    println!("logged in as {username}");
+
+    // --- Complete the friendship: handle any follow request from `target` -----
+    let pending = peergos_fs::get_pending_outgoing(&user, store.clone(), &mutable).await?;
+    let we_asked_them = pending.iter().any(|u| u == &target);
+    let requests = peergos_fs::get_follow_requests(&user, poster.as_ref()).await?;
+    let from_target = requests.into_iter().find(|r| r.sender() == Some(target.as_str()));
+
+    match from_target {
+        Some(req) => {
+            if we_asked_them {
+                // They accepted our request: process their reply so we follow them.
+                peergos_fs::process_follow_reply(&user, &req, poster.as_ref(), store.clone(), &mutable).await?;
+                println!("processed {target}'s reply to our follow request — friendship complete");
+            } else {
+                // A fresh request from them: accept and reciprocate.
+                peergos_fs::accept_follow_request(&user, &req, true, poster.as_ref(), store.clone(), &mutable).await?;
+                println!("accepted {target}'s follow request (reciprocated) — friendship complete");
+            }
+        }
+        None => {
+            println!(
+                "no pending follow request from {target} yet (we_asked_them={we_asked_them}); \
+                 they still need to accept before the friendship is mutual. Sharing anyway."
+            );
+        }
+    }
+
+    // Re-login to pick up the updated social state, then confirm friends.
+    let user = peergos_fs::login(&username, &password, poster.as_ref(), store.clone(), &mutable, None).await?;
+    let friends = peergos_fs::get_friends(&user, store.clone(), &mutable).await?;
+    println!("friends: {:?}", friends.iter().map(|e| e.owner_name.clone()).collect::<Vec<_>>());
+
+    // --- Share the file read-only with `target` -------------------------------
+    let home = user.home().ok_or("no home directory")?;
+    let entry = peergos_fs::list_directory(home, store.clone(), &mutable)
+        .await?
+        .into_iter()
+        .find(|e| e.name == file_name)
+        .ok_or_else(|| format!("no file named {file_name:?} in home"))?;
+    peergos_fs::share_read_access(&user, &file_name, &entry.cap, &target, store.clone(), &mutable).await?;
+    println!("read-shared {file_name:?} with {target}");
+
+    // Show who the file is now shared with.
+    let shared = peergos_fs::get_shared_with(&user, &file_name, peergos_fs::Access::Read, store.clone(), &mutable).await?;
+    println!("{file_name:?} is now read-shared with: {shared:?}");
+    Ok(())
+}

crates/peergos-fs/examples/create_writeshare_live.rs

@@ -0,0 +1,41 @@
+//! Create a file in home and share it WRITABLE with a target user, on a live server.
+//!   cargo run -p peergos-fs --example create_writeshare_live -- <base> <username> <password> <target>
+
+use peergos_core::mutable::HttpMutablePointers;
+use peergos_core::{ContentAddressedStorage, HttpStorage, ReqwestPoster};
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut args = std::env::args().skip(1);
+    let base = args.next().unwrap_or_else(|| "https://test.peergos.net/".to_string());
+    let username = args.next().expect("usage: <base> <username> <password> <target>");
+    let password = args.next().expect("usage: <base> <username> <password> <target>");
+    let target = args.next().expect("usage: <base> <username> <password> <target>");
+
+    let poster = Arc::new(ReqwestPoster::new(&base, false)?);
+    let store: Arc<dyn ContentAddressedStorage> = Arc::new(HttpStorage::new(poster.clone(), true));
+    let mutable = HttpMutablePointers::new(poster.clone());
+
+    let name = "test.md";
+    let content = b"# Test\n\nThis is a collaboratively editable test file created by the Rust Peergos client.\n";
+
+    // Create the file in home.
+    let user = peergos_fs::login(&username, &password, poster.as_ref(), store.clone(), &mutable, None).await?;
+    let home = user.home().ok_or("no home directory")?.clone();
+    let signer = peergos_fs::recover_signer(&home, store.clone(), &mutable).await?;
+    peergos_fs::upload_file(&home, name, content, None, Some(signer), user.mirror_bat_id().as_ref(), store.clone(), &mutable).await?;
+    println!("created {name:?} ({} bytes) in /{username}", content.len());
+
+    // Re-login for fresh state, then write-share it with the target.
+    let user = peergos_fs::login(&username, &password, poster.as_ref(), store.clone(), &mutable, None).await?;
+    let home = user.home().ok_or("no home directory")?.clone();
+    peergos_fs::share_write_access(&user, "", &home, name, &target, store.clone(), &mutable).await?;
+    println!("write-shared {name:?} with {target}");
+
+    // Confirm.
+    let user = peergos_fs::login(&username, &password, poster.as_ref(), store.clone(), &mutable, None).await?;
+    let shared = peergos_fs::get_shared_with(&user, name, peergos_fs::Access::Write, store.clone(), &mutable).await?;
+    println!("{name:?} is now write-shared with: {shared:?}");
+    Ok(())
+}

crates/peergos-fs/examples/follow_send_live.rs

@@ -0,0 +1,28 @@
+//! Send a follow request to a target user on a live server.
+//!   cargo run -p peergos-fs --example follow_send_live -- <base> <username> <password> <target>
+
+use peergos_core::mutable::HttpMutablePointers;
+use peergos_core::{ContentAddressedStorage, HttpStorage, ReqwestPoster};
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut args = std::env::args().skip(1);
+    let base = args.next().unwrap_or_else(|| "https://test.peergos.net/".to_string());
+    let username = args.next().expect("usage: follow_send_live <base> <username> <password> <target>");
+    let password = args.next().expect("usage: follow_send_live <base> <username> <password> <target>");
+    let target = args.next().expect("usage: follow_send_live <base> <username> <password> <target>");
+
+    let poster = Arc::new(ReqwestPoster::new(&base, false)?);
+    let store: Arc<dyn ContentAddressedStorage> = Arc::new(HttpStorage::new(poster.clone(), true));
+    let mutable = HttpMutablePointers::new(poster.clone());
+
+    let user = peergos_fs::login(&username, &password, poster.as_ref(), store.clone(), &mutable, None).await?;
+    println!("logged in as {username}; sending a follow request to {target} ...");
+    let sent = peergos_fs::send_follow_request(&user, &target, true, poster.as_ref(), store.clone(), &mutable).await?;
+    println!("follow request sent = {sent}");
+    if !sent {
+        return Err("server rejected the follow request (already pending, or already following?)".into());
+    }
+    Ok(())
+}

crates/peergos-fs/examples/mkdir_writeshare_live.rs

@@ -0,0 +1,38 @@
+//! Create a directory in home and share it WRITABLE with a target user, live.
+//!   cargo run -p peergos-fs --example mkdir_writeshare_live -- <base> <username> <password> <target> <dir-name>
+
+use peergos_core::mutable::HttpMutablePointers;
+use peergos_core::{ContentAddressedStorage, HttpStorage, ReqwestPoster};
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut args = std::env::args().skip(1);
+    let base = args.next().unwrap_or_else(|| "https://test.peergos.net/".to_string());
+    let username = args.next().expect("usage: <base> <username> <password> <target> <dir-name>");
+    let password = args.next().expect("usage: <base> <username> <password> <target> <dir-name>");
+    let target = args.next().expect("usage: <base> <username> <password> <target> <dir-name>");
+    let dir = args.next().unwrap_or_else(|| "write".to_string());
+
+    let poster = Arc::new(ReqwestPoster::new(&base, false)?);
+    let store: Arc<dyn ContentAddressedStorage> = Arc::new(HttpStorage::new(poster.clone(), true));
+    let mutable = HttpMutablePointers::new(poster.clone());
+
+    // Create the directory in home.
+    let user = peergos_fs::login(&username, &password, poster.as_ref(), store.clone(), &mutable, None).await?;
+    let home = user.home().ok_or("no home directory")?.clone();
+    let signer = peergos_fs::recover_signer(&home, store.clone(), &mutable).await?;
+    peergos_fs::create_directory(&home, &dir, Some(signer), user.mirror_bat_id().as_ref(), store.clone(), &mutable).await?;
+    println!("created directory {dir:?} in /{username}");
+
+    // Re-login for fresh state, then write-share it with the target.
+    let user = peergos_fs::login(&username, &password, poster.as_ref(), store.clone(), &mutable, None).await?;
+    let home = user.home().ok_or("no home directory")?.clone();
+    peergos_fs::share_write_access(&user, "", &home, &dir, &target, store.clone(), &mutable).await?;
+    println!("write-shared {dir:?} with {target}");
+
+    let user = peergos_fs::login(&username, &password, poster.as_ref(), store.clone(), &mutable, None).await?;
+    let shared = peergos_fs::get_shared_with(&user, &dir, peergos_fs::Access::Write, store.clone(), &mutable).await?;
+    println!("{dir:?} is now write-shared with: {shared:?}");
+    Ok(())
+}

crates/peergos-fs/examples/read_dir_live.rs

@@ -0,0 +1,76 @@
+//! List a directory on a live server and sanity-check any PDF files in it.
+//!   cargo run -p peergos-fs --example read_dir_live -- <base> <username> <password> <dir-path>
+
+use peergos_core::mutable::{HttpMutablePointers, MutablePointers};
+use peergos_core::{ContentAddressedStorage, HttpPoster, HttpStorage, ReqwestPoster};
+use peergos_fs::UserContext;
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut args = std::env::args().skip(1);
+    let base = args.next().unwrap_or_else(|| "https://test.peergos.net/".to_string());
+    let username = args.next().expect("usage: <base> <username> <password> <dir-path>");
+    let password = args.next().expect("usage: <base> <username> <password> <dir-path>");
+    let dir_path = args.next().expect("usage: <base> <username> <password> <dir-path>");
+
+    let poster: Arc<dyn HttpPoster> = Arc::new(ReqwestPoster::new(&base, false)?);
+    let store: Arc<dyn ContentAddressedStorage> = Arc::new(HttpStorage::new(Arc::new(ReqwestPoster::new(&base, false)?), true));
+    let mutable: Arc<dyn MutablePointers> = Arc::new(HttpMutablePointers::new(Arc::new(ReqwestPoster::new(&base, false)?)));
+
+    let ctx = UserContext::sign_in(&username, &password, None, poster, store, mutable).await?;
+    println!("signed in as {username}");
+
+    let dir = ctx.get_by_path(&dir_path).await?.ok_or_else(|| format!("no directory at {dir_path}"))?;
+    let children = dir.children().await?;
+    println!("{dir_path} has {} entries:", children.len());
+    for c in &children {
+        let kind = if c.is_directory() { "dir " } else { "file" };
+        println!("  [{kind}] {} ({} bytes)", c.name(), c.size());
+    }
+
+    for c in &children {
+        if c.is_directory() {
+            continue;
+        }
+        let data = c.read().await?;
+        if data.starts_with(b"%PDF-") {
+            let version = std::str::from_utf8(&data[5..8]).unwrap_or("?");
+            let has_eof = data.windows(5).rev().take(1024).any(|w| w == b"%%EOF")
+                || data.windows(5).any(|w| w == b"%%EOF");
+            // Rough page count: occurrences of "/Type /Page" not followed by 's'.
+            let pages = count_pages(&data);
+            println!(
+                "\nPDF {:?}: {} bytes, version {version}, valid trailer={has_eof}, ~{pages} page(s)",
+                c.name(),
+                data.len(),
+            );
+        } else if c.name().to_lowercase().ends_with(".pdf") {
+            println!("\n{:?} is named .pdf but does not start with %PDF- (first bytes: {:02x?})", c.name(), &data[..data.len().min(8)]);
+        }
+    }
+    Ok(())
+}
+
+/// Rough page count: `/Type /Page` (optionally with whitespace) but not `/Pages`.
+fn count_pages(data: &[u8]) -> usize {
+    let needle = b"/Type";
+    let mut count = 0;
+    let mut i = 0;
+    while let Some(pos) = find(&data[i..], needle) {
+        let start = i + pos + needle.len();
+        // skip whitespace and a possible '/'
+        let rest = &data[start..(start + 8).min(data.len())];
+        let s: String = rest.iter().map(|&b| b as char).collect();
+        let s = s.trim_start().trim_start_matches('/');
+        if s.starts_with("Page") && !s.starts_with("Pages") {
+            count += 1;
+        }
+        i = start;
+    }
+    count
+}
+
+fn find(haystack: &[u8], needle: &[u8]) -> Option<usize> {
+    haystack.windows(needle.len()).position(|w| w == needle)
+}