Storage API

The Pubky SDK provides two ways to access storage: public (read-only) and authenticated.

Public Storage (Read-Only)

Public storage allows you to read publicly accessible data from any user without authentication.

async fn storage_public() -> pubky::Result<()> {
    let pubky = Pubky::new()?;

    // Get the public storage accessor
    let public = pubky.public_storage();

    // The public key of the user whose data you want to access
    let user_pubkey = PublicKey::try_from("o4dksfbqk85ogzdb5osziw6befigbuxmuxkuxq8434q89uj56uyy")
        .expect("Valid user public key");

    // Read a file
    let file = public
        .get(format!("pubky://{}/pub/acme.app/file.txt", user_pubkey))
        .await?
        .bytes()
        .await?;
    println!("Retrieved file: {:?}", file);

    // List directory entries with limit
    let entries = public
        .list(format!("pubky://{}/pub/acme.app/", user_pubkey))?
        .limit(10)
        .send()
        .await?;

    for entry in entries {
        println!("Entry: {}", entry.to_pubky_url());
    }

    Ok(())
}

Key features:

• Uses addressed format like "pubky://<user>/pub/app/file.txt"
• No authentication required
• Read-only access
• Can list directory contents with pagination
• Works with any user's public data

Convention: Store your app's public data under a domain-like folder in /pub, for example /pub/mycoolnew.app/.

Session Storage (Authenticated)

Session storage allows you to read and write your own data using an authenticated session. This is used when you need to store or modify data on your homeserver.

async fn storage_session() -> pubky::Result<()> {
    let pubky = Pubky::new()?;
    let keypair = Keypair::random();
    let signer = pubky.signer(keypair);

    // Sign in to get a session
    let session = signer.signin().await?;

    // Get the session storage
    let storage = session.storage();

    // Write data
    storage
        .put("/pub/my.app/data.txt", "Hello from session storage")
        .await?;

    // Read data
    let text = storage.get("/pub/my.app/data.txt").await?.text().await?;
    println!("Retrieved: {}", text);

    Ok(())
}

Key features:

• Uses absolute paths like "/pub/my.app/data.txt"
• Requires authentication via a PubkySession
• Supports read and write operations
• All operations are authenticated using your session