weave-strand · crate

pub use bitfield::Bitfield;

pub use merkle_tree::{MerkleTree, Node, Proof as MerkleProof};

pub use storage::{FileStorage, MemoryStorage, Storage};

pub type Config = StrandConfig;

#[derive(Debug, Error)]
pub enum StrandError {
    /// Storage backend error
    #[error("Storage error: {0}")]
    Storage(#[from] storage::StorageError),

    /// Invalid configuration
    #[error("Configuration error: {0}")]
    Configuration(String),

    /// Cryptographic verification failed
    #[error("Verification failed: {0}")]
    VerificationFailed(String),

    /// Block not found
    #[error("Block not found: {0}")]
    BlockNotFound(u64),

    /// Invalid merkle proof
    #[error("Invalid proof")]
    InvalidProof,

    /// Invalid block sequence
    #[error("Invalid sequence: expected {expected}, got {actual}")]
    InvalidSequence {
        /// Expected sequence number
        expected: u64,
        /// Actual sequence number received
        actual: u64,
    },

    /// Sparse mode error
    #[error("Sparse mode error: {0}")]
    SparseError(String),

    /// Corrupted data
    #[error("Data corruption detected: {0}")]
    CorruptedData(String),

    /// I/O error
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),

    /// Serialization error
    #[error("Serialization error: {0}")]
    Serialization(#[from] serde_json::Error),

    // Network and identity errors are handled at higher layers
    /// Not implemented yet (used only for cross-crate sequencing gates)
    #[error("Not implemented: {0}")]
    NotImplemented(&'static str),
}

pub type Result<T> = std::result::Result<T, StrandError>;

pub fn recover_remote_writer_public_key(path: impl AsRef<Path>) -> Result<Option<[u8; 32]>>;

#[derive(Clone, Serialize, Deserialize, Default)]
pub struct StrandConfig {
/// Optional storage path for persistence

pub storage_path: Option<PathBuf>,
/// Encryption settings

pub encrypted: bool,
/// Sparse mode (download blocks on demand)

pub sparse: bool,
/// Value encoding (e.g., "binary", "utf-8", "json")

pub value_encoding: String,
/// Optional keypair for the writer (raw Ed25519 keys)

#[serde(skip)]
pub keypair: Option<zer0_crypto::KeyPair>,
/// Optional public key for read-only strands

#[serde(skip)]
pub public_key: Option<[u8; 32]>
}

pub fn new() -> Self;

pub fn with_storage(mut self, path: impl AsRef<Path>) -> Self;

pub fn with_encryption(mut self) -> Self;

pub fn with_sparse(mut self) -> Self;

pub fn with_keypair(mut self, keypair: zer0_crypto::KeyPair) -> Self;

pub fn with_public_key(mut self, public_key: [u8; 32]) -> Self;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Header {
/// Protocol version

pub version: u8,
/// Block sequence number

pub seq: u64,
/// Length of the data

pub length: u64,
/// Byte offset in the data file

#[serde(rename = "byteOffset")]
pub byte_offset: u64,
/// Hash of the previous signed block header and payload.

#[serde(default)]
pub prev_hash: [u8; 32],
/// Writer public key

pub writer_public_key: [u8; 32],
/// Timestamp when block was created

pub timestamp: u64,
/// Signature of the block

pub signature: Vec<u8>
}

#[derive(Debug, Clone, Default)]
pub struct Stats {
/// Number of blocks uploaded

pub uploaded: u64,
/// Number of blocks downloaded

pub downloaded: u64,
/// Number of bytes uploaded

pub uploaded_bytes: u64,
/// Number of bytes downloaded

pub downloaded_bytes: u64,
/// Number of peers connected

pub peers: usize,
/// Number of blocks verified

pub verified: u64,
/// Number of blocks rejected (invalid signature, etc.)

pub rejected: u64
}

pub struct ReplicationStream {

}

pub fn new(strand: Arc<Strand>) -> Self;

pub async fn handshake(&mut self) -> Result<()>;

pub fn stats(&self) -> &Stats;

pub async fn download_range(&mut self, start: u64, end: u64, linear: bool) -> Result<()>;

pub async fn cancel_range(&mut self, _start: u64, _end: u64) -> Result<()>;

pub async fn next(&mut self) -> Option<(u64, Vec<u8>)>;

pub struct Strand {

}

pub async fn new(config: StrandConfig) -> Result<Self>;

pub fn public_key(&self) -> &[u8];

pub fn can_sign_provider_delegation(&self) -> bool;

pub fn sign_provider_delegation(&self, payload: &[u8]) -> Result<Vec<u8>>;

pub fn discovery_key(&self) -> &[u8; 32];

pub fn len(&self) -> u64;

pub fn is_empty(&self) -> bool;

pub fn set_history_ceiling(&self, ceiling: Option<u64>);

pub fn history_ceiling(&self) -> Option<u64>;

pub fn history_checkpoint(&self) -> (Option<u64>, Option<[u8; 32]>);

pub fn set_history_checkpoint(
        &self,
        ceiling: u64,
        terminal_hash: Option<[u8; 32]>,
    ) -> Result<()>;

pub fn terminal_checkpoint(&self) -> Result<(u64, Option<[u8; 32]>)>;

pub fn refresh_from_storage(&self) -> Result<()>;

pub fn config(&self) -> &StrandConfig;

pub fn append_sync(&mut self, data: &[u8]) -> Result<u64>;

pub async fn append(&mut self, data: &[u8]) -> Result<u64>;

pub async fn get(&self, seq: u64) -> Result<Vec<u8>>;

pub async fn get_local(&self, seq: u64) -> Result<Vec<u8>>;

pub async fn fork(&self, new_path: Option<&std::path::Path>) -> Result<Strand>;

pub fn user_get(&self, key: &str) -> Option<Vec<u8>>;

pub fn user_get_fresh(&self, key: &str) -> Result<Option<Vec<u8>>>;

pub fn user_set(&self, key: String, value: Vec<u8>) -> Result<()>;

pub fn user_compare_and_set(
        &self,
        key: String,
        expected: Option<&[u8]>,
        value: Vec<u8>,
    ) -> Result<bool>;

pub fn telemetry(&self) -> (u64, u64);

pub async fn replication(&self, opts: ReplicationOptions) -> ReplicationHandle;

pub async fn get_header(&self, seq: u64) -> Result<Header>;

pub async fn proof(&self, seq: u64) -> Result<MerkleProof>;

pub async fn verify_proof(&self, proof: &MerkleProof, data: &[u8]) -> Result<bool>;

pub fn set_replication_client(&self, client: replication_client::SharedReplicationClient);

pub fn clear_replication_client(&self);

pub fn has_replication_client(&self) -> bool;

pub fn replication_client(&self) -> Option<replication_client::SharedReplicationClient>;

pub fn is_sparse(&self) -> bool;

pub fn has_block(&self, seq: u64) -> bool;

pub fn clear_cache(&mut self);

pub async fn ingest_remote_block(&self, seq: u64, header: &Header, data: &[u8]) -> Result<()>;

pub fn replicate(strand: Arc<Strand>) -> ReplicationStream;

#[cfg(feature = "policy-hooks")]
pub use policy::{set_strand_policy, AllowAllPolicy, StrandPolicy};

pub use replication_api::{RangeHandle, RangeSpec, ReplicationHandle, ReplicationOptions};

pub use replication_client::{
    ReplicationClient, SharedReplicationClient, UnsupportedReplicationClient,
};