ferripfs_network/

lib.rs

// Ported from: kubo/core/node/libp2p
// Kubo version: v0.39.0
// Original: https://github.com/ipfs/kubo/tree/v0.39.0/core/node/libp2p
//
// Original work: Copyright (c) Protocol Labs, Inc.
// Port: Copyright (c) 2026 ferripfs contributors
// SPDX-License-Identifier: MIT OR Apache-2.0

//! libp2p networking for ferripfs, ported from Kubo's core/node/libp2p.
//!
//! This crate provides:
//! - libp2p host initialization with configurable transports
//! - TCP, QUIC, WebSocket transport support
//! - Noise encryption and Yamux multiplexing
//! - mDNS local peer discovery
//! - Kademlia DHT for peer/content routing
//! - AutoNAT for NAT detection
//! - Circuit relay client
//! - Connection management
//! - Daemon process management

pub mod behavior;
pub mod daemon;
pub mod host;
pub mod swarm;

pub use behavior::FerripfsBehavior;
pub use daemon::{Daemon, DaemonConfig, DaemonHandle};
pub use host::{HostConfig, NetworkHost};
pub use swarm::{SwarmBuilder, SwarmConfig};

use thiserror::Error;

/// Network operation error types
#[derive(Debug, Error)]
pub enum NetworkError {
    #[error("Failed to initialize libp2p: {0}")]
    Init(String),

    #[error("Transport error: {0}")]
    Transport(String),

    #[error("Swarm error: {0}")]
    Swarm(String),

    #[error("Connection error: {0}")]
    Connection(String),

    #[error("Peer not found: {0}")]
    PeerNotFound(String),

    #[error("Invalid multiaddr: {0}")]
    InvalidMultiaddr(String),

    #[error("Invalid peer ID: {0}")]
    InvalidPeerId(String),

    #[error("Daemon error: {0}")]
    Daemon(String),

    #[error("Already running")]
    AlreadyRunning,

    #[error("Not running")]
    NotRunning,

    #[error("Config error: {0}")]
    Config(#[from] ferripfs_config::ConfigError),

    #[error("Repo error: {0}")]
    Repo(#[from] ferripfs_repo::RepoError),

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

/// Result type for network operations
pub type NetworkResult<T> = Result<T, NetworkError>;

/// Peer information returned by id command
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct PeerInfo {
    #[serde(rename = "ID")]
    pub id: String,
    #[serde(rename = "PublicKey")]
    pub public_key: String,
    #[serde(rename = "Addresses")]
    pub addresses: Vec<String>,
    #[serde(rename = "AgentVersion")]
    pub agent_version: String,
    #[serde(rename = "ProtocolVersion")]
    pub protocol_version: String,
    #[serde(rename = "Protocols")]
    pub protocols: Vec<String>,
}

/// Connected peer information
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ConnectedPeer {
    #[serde(rename = "Addr")]
    pub addr: String,
    #[serde(rename = "Peer")]
    pub peer: String,
    #[serde(rename = "Latency")]
    pub latency: Option<String>,
    #[serde(rename = "Muxer")]
    pub muxer: Option<String>,
    #[serde(rename = "Direction")]
    pub direction: String,
}

/// Ping result
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct PingResult {
    #[serde(rename = "Success")]
    pub success: bool,
    #[serde(rename = "Time")]
    pub time: u64,
    #[serde(rename = "Text")]
    pub text: String,
}

/// DHT provider information
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct DhtProvider {
    #[serde(rename = "ID")]
    pub id: String,
    #[serde(rename = "Addrs")]
    pub addrs: Vec<String>,
}

/// DHT query result
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct DhtQueryResult {
    #[serde(rename = "Type")]
    pub result_type: String,
    #[serde(rename = "Responses")]
    pub responses: Vec<DhtProvider>,
    #[serde(rename = "Extra")]
    pub extra: Option<String>,
    #[serde(rename = "Success")]
    pub success: bool,
    #[serde(rename = "Error")]
    pub error: Option<String>,
}

impl DhtQueryResult {
    /// Create a successful query result.
    pub fn success(result_type: &str, responses: Vec<DhtProvider>) -> Self {
        Self {
            result_type: result_type.to_string(),
            responses,
            extra: None,
            success: true,
            error: None,
        }
    }

    /// Create a successful query result with extra data.
    pub fn success_with_extra(result_type: &str, extra: String) -> Self {
        Self {
            result_type: result_type.to_string(),
            responses: vec![],
            extra: Some(extra),
            success: true,
            error: None,
        }
    }

    /// Create a failed query result.
    pub fn failure(result_type: &str, error: String) -> Self {
        Self {
            result_type: result_type.to_string(),
            responses: vec![],
            extra: None,
            success: false,
            error: Some(error),
        }
    }
}

/// DHT statistics
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct DhtStats {
    #[serde(rename = "Name")]
    pub name: String,
    #[serde(rename = "Buckets")]
    pub buckets: u32,
    #[serde(rename = "TotalPeers")]
    pub total_peers: u32,
    #[serde(rename = "Mode")]
    pub mode: String,
}

// =============================================================================
// Bitswap Types (Phase 9)
// Ported from: boxo/bitswap
// =============================================================================

/// Bitswap statistics
/// Ported from: boxo/bitswap/stat.go
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct BitswapStats {
    /// Protocol version
    #[serde(rename = "ProvideBufLen")]
    pub provide_buf_len: u64,
    /// Number of blocks received from other peers
    #[serde(rename = "BlocksReceived")]
    pub blocks_received: u64,
    /// Total bytes of data received
    #[serde(rename = "DataReceived")]
    pub data_received: u64,
    /// Number of blocks sent to other peers
    #[serde(rename = "BlocksSent")]
    pub blocks_sent: u64,
    /// Total bytes of data sent
    #[serde(rename = "DataSent")]
    pub data_sent: u64,
    /// Number of duplicate blocks received
    #[serde(rename = "DupBlksReceived")]
    pub dup_blks_received: u64,
    /// Total bytes of duplicate data received
    #[serde(rename = "DupDataReceived")]
    pub dup_data_received: u64,
    /// Number of messages received
    #[serde(rename = "MessagesReceived")]
    pub messages_received: u64,
    /// Number of peers in the wantlist
    #[serde(rename = "Wantlist")]
    pub wantlist: Vec<WantlistEntry>,
    /// Connected peers
    #[serde(rename = "Peers")]
    pub peers: Vec<String>,
}

impl BitswapStats {
    /// Create new empty stats
    pub fn new() -> Self {
        Self::default()
    }

    /// Record a block received
    pub fn record_block_received(&mut self, size: u64) {
        self.blocks_received += 1;
        self.data_received += size;
    }

    /// Record a block sent
    pub fn record_block_sent(&mut self, size: u64) {
        self.blocks_sent += 1;
        self.data_sent += size;
    }

    /// Record a duplicate block received
    pub fn record_duplicate(&mut self, size: u64) {
        self.dup_blks_received += 1;
        self.dup_data_received += size;
    }

    /// Record a message received
    pub fn record_message(&mut self) {
        self.messages_received += 1;
    }
}

/// Wantlist entry
/// Ported from: boxo/bitswap/wantlist/wantlist.go
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct WantlistEntry {
    /// CID of the wanted block
    #[serde(rename = "/")]
    pub cid: String,
    /// Priority of this want (higher = more important)
    #[serde(rename = "Priority", skip_serializing_if = "Option::is_none")]
    pub priority: Option<i32>,
    /// Whether this is a want-have or want-block
    #[serde(rename = "WantType", skip_serializing_if = "Option::is_none")]
    pub want_type: Option<String>,
}

impl WantlistEntry {
    /// Create a new wantlist entry
    pub fn new(cid: String) -> Self {
        Self {
            cid,
            priority: None,
            want_type: None,
        }
    }

    /// Create a new wantlist entry with priority
    pub fn with_priority(cid: String, priority: i32) -> Self {
        Self {
            cid,
            priority: Some(priority),
            want_type: None,
        }
    }

    /// Create a want-block entry
    pub fn want_block(cid: String, priority: i32) -> Self {
        Self {
            cid,
            priority: Some(priority),
            want_type: Some("Block".to_string()),
        }
    }

    /// Create a want-have entry
    pub fn want_have(cid: String, priority: i32) -> Self {
        Self {
            cid,
            priority: Some(priority),
            want_type: Some("Have".to_string()),
        }
    }
}

/// Bitswap ledger for a peer
/// Ported from: boxo/bitswap/decision/ledger.go
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct BitswapLedger {
    /// Peer ID this ledger is for
    #[serde(rename = "Peer")]
    pub peer: String,
    /// Value exchanged (positive = we sent more, negative = they sent more)
    #[serde(rename = "Value")]
    pub value: f64,
    /// Number of bytes sent to this peer
    #[serde(rename = "Sent")]
    pub sent: u64,
    /// Number of bytes received from this peer
    #[serde(rename = "Recv")]
    pub recv: u64,
    /// Number of blocks exchanged
    #[serde(rename = "Exchanged")]
    pub exchanged: u64,
}

impl BitswapLedger {
    /// Create a new ledger for a peer
    pub fn new(peer: String) -> Self {
        Self {
            peer,
            value: 0.0,
            sent: 0,
            recv: 0,
            exchanged: 0,
        }
    }

    /// Record bytes sent to this peer
    pub fn record_sent(&mut self, bytes: u64) {
        self.sent += bytes;
        self.exchanged += 1;
        self.update_value();
    }

    /// Record bytes received from this peer
    pub fn record_recv(&mut self, bytes: u64) {
        self.recv += bytes;
        self.exchanged += 1;
        self.update_value();
    }

    /// Update the exchange value (debt ratio)
    fn update_value(&mut self) {
        if self.recv > 0 {
            self.value = self.sent as f64 / self.recv as f64;
        } else if self.sent > 0 {
            self.value = f64::INFINITY;
        } else {
            self.value = 0.0;
        }
    }
}

/// Bitswap reprovide result
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ReprovideResult {
    /// Number of CIDs reprovided
    #[serde(rename = "Count")]
    pub count: u64,
    /// Duration of reprovide operation
    #[serde(rename = "Duration")]
    pub duration_ms: u64,
}

/// Bitswap protocol version
pub const BITSWAP_PROTOCOL_VERSION: &str = "/ipfs/bitswap/1.2.0";

/// Agent version string
pub const AGENT_VERSION: &str = concat!("ferripfs/", env!("CARGO_PKG_VERSION"));

/// Protocol version
pub const PROTOCOL_VERSION: &str = "ipfs/0.1.0";

// =============================================================================
// IPNS Types (Phase 10)
// Ported from: boxo/ipns
// =============================================================================

/// IPNS record validity type
/// Ported from: boxo/ipns/pb/ipns.proto
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[derive(Default)]
pub enum IpnsValidityType {
    /// End of life - record expires at a specific time
    #[serde(rename = "EOL")]
    #[default]
    Eol = 0,
}


impl std::fmt::Display for IpnsValidityType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Eol => write!(f, "EOL"),
        }
    }
}

/// IPNS record structure
/// Ported from: boxo/ipns/record.go
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct IpnsRecord {
    /// The value being published (usually `/ipfs/<cid>`)
    #[serde(rename = "Value")]
    pub value: String,
    /// Signature data (base64 encoded)
    #[serde(rename = "SignatureV2")]
    pub signature_v2: String,
    /// Validity type (EOL)
    #[serde(rename = "ValidityType")]
    pub validity_type: IpnsValidityType,
    /// Validity timestamp (RFC3339)
    #[serde(rename = "Validity")]
    pub validity: String,
    /// Sequence number for versioning
    #[serde(rename = "Sequence")]
    pub sequence: u64,
    /// Time-to-live in nanoseconds
    #[serde(rename = "TTL")]
    pub ttl: u64,
    /// Public key (base64 encoded, optional if embedded in peer ID)
    #[serde(rename = "PubKey", skip_serializing_if = "Option::is_none")]
    pub pubkey: Option<String>,
}

impl IpnsRecord {
    /// Create a new IPNS record
    pub fn new(value: String, sequence: u64, validity: String, ttl: u64) -> Self {
        Self {
            value,
            signature_v2: String::new(),
            validity_type: IpnsValidityType::Eol,
            validity,
            sequence,
            ttl,
            pubkey: None,
        }
    }

    /// Check if the record is expired based on validity timestamp
    pub fn is_expired(&self) -> bool {
        use std::time::SystemTime;

        // Parse RFC3339 timestamp
        if let Ok(validity_time) = chrono_parse_rfc3339(&self.validity) {
            let now = SystemTime::now()
                .duration_since(SystemTime::UNIX_EPOCH)
                .unwrap_or_default()
                .as_secs();
            validity_time < now
        } else {
            true // Invalid timestamp = expired
        }
    }

    /// Get the sequence number
    pub fn get_sequence(&self) -> u64 {
        self.sequence
    }

    /// Increment the sequence number
    pub fn increment_sequence(&mut self) {
        self.sequence += 1;
    }
}

/// Simple RFC3339 timestamp parser (returns Unix timestamp)
fn chrono_parse_rfc3339(s: &str) -> Result<u64, ()> {
    // Basic RFC3339 parsing: 2024-01-15T12:00:00Z
    // This is a simplified parser; production code would use chrono crate
    if s.len() < 20 {
        return Err(());
    }

    let parts: Vec<&str> = s.split('T').collect();
    if parts.len() != 2 {
        return Err(());
    }

    let date_parts: Vec<&str> = parts[0].split('-').collect();
    if date_parts.len() != 3 {
        return Err(());
    }

    let year: u64 = date_parts[0].parse().map_err(|_| ())?;
    let month: u64 = date_parts[1].parse().map_err(|_| ())?;
    let day: u64 = date_parts[2].parse().map_err(|_| ())?;

    // Approximate days since Unix epoch
    let days_since_epoch = (year - 1970) * 365 + (month - 1) * 30 + day;
    Ok(days_since_epoch * 86400)
}

/// IPNS entry for display
/// Ported from: core/commands/name/publish.go
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct IpnsEntry {
    /// The IPNS name (peer ID or key name)
    #[serde(rename = "Name")]
    pub name: String,
    /// The value the name points to
    #[serde(rename = "Value")]
    pub value: String,
}

impl IpnsEntry {
    /// Create a new IPNS entry
    pub fn new(name: String, value: String) -> Self {
        Self { name, value }
    }
}

/// IPNS resolve result
/// Ported from: core/commands/name/resolve.go
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct IpnsResolveResult {
    /// The resolved path
    #[serde(rename = "Path")]
    pub path: String,
}

impl IpnsResolveResult {
    /// Create a new resolve result
    pub fn new(path: String) -> Self {
        Self { path }
    }
}

/// IPNS record inspection result
/// Ported from: core/commands/name/inspect.go
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct IpnsInspectResult {
    /// The record being inspected
    #[serde(rename = "Record")]
    pub record: IpnsRecord,
    /// Validation result
    #[serde(rename = "Validation")]
    pub validation: IpnsValidation,
}

/// IPNS validation result
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct IpnsValidation {
    /// Whether the record is valid
    #[serde(rename = "Valid")]
    pub valid: bool,
    /// Validation error message (if any)
    #[serde(rename = "Error", skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
    /// Whether the record is expired
    #[serde(rename = "Expired")]
    pub expired: bool,
}

impl IpnsValidation {
    /// Create a valid validation result
    pub fn valid(expired: bool) -> Self {
        Self {
            valid: true,
            error: None,
            expired,
        }
    }

    /// Create an invalid validation result
    pub fn invalid(error: String) -> Self {
        Self {
            valid: false,
            error: Some(error),
            expired: false,
        }
    }
}

// =============================================================================
// Key Management Types (Phase 10)
// Ported from: core/commands/keystore.go
// =============================================================================

/// Key type enumeration
/// Ported from: core/commands/keystore.go
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[derive(Default)]
pub enum KeyType {
    #[serde(rename = "ed25519")]
    #[default]
    Ed25519,
    #[serde(rename = "rsa")]
    Rsa,
    #[serde(rename = "ecdsa")]
    Ecdsa,
    #[serde(rename = "secp256k1")]
    Secp256k1,
}


impl std::fmt::Display for KeyType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Ed25519 => write!(f, "ed25519"),
            Self::Rsa => write!(f, "rsa"),
            Self::Ecdsa => write!(f, "ecdsa"),
            Self::Secp256k1 => write!(f, "secp256k1"),
        }
    }
}

impl std::str::FromStr for KeyType {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "ed25519" => Ok(Self::Ed25519),
            "rsa" => Ok(Self::Rsa),
            "ecdsa" => Ok(Self::Ecdsa),
            "secp256k1" => Ok(Self::Secp256k1),
            _ => Err(format!("unknown key type: {}", s)),
        }
    }
}

/// Key information
/// Ported from: core/commands/keystore.go
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct KeyInfo {
    /// Key name
    #[serde(rename = "Name")]
    pub name: String,
    /// Key ID (peer ID derived from public key)
    #[serde(rename = "Id")]
    pub id: String,
}

impl KeyInfo {
    /// Create a new key info
    pub fn new(name: String, id: String) -> Self {
        Self { name, id }
    }
}

/// Key list result
/// Ported from: core/commands/keystore.go
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct KeyList {
    /// List of keys
    #[serde(rename = "Keys")]
    pub keys: Vec<KeyInfo>,
}

impl KeyList {
    /// Create a new key list
    pub fn new(keys: Vec<KeyInfo>) -> Self {
        Self { keys }
    }

    /// Create an empty key list
    pub fn empty() -> Self {
        Self { keys: Vec::new() }
    }

    /// Add a key to the list
    pub fn add(&mut self, key: KeyInfo) {
        self.keys.push(key);
    }

    /// Get the number of keys
    pub fn len(&self) -> usize {
        self.keys.len()
    }

    /// Check if the list is empty
    pub fn is_empty(&self) -> bool {
        self.keys.is_empty()
    }
}

/// Key generation result
/// Ported from: core/commands/keystore.go
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct KeyGenResult {
    /// Key name
    #[serde(rename = "Name")]
    pub name: String,
    /// Key ID (peer ID)
    #[serde(rename = "Id")]
    pub id: String,
}

impl KeyGenResult {
    /// Create a new key generation result
    pub fn new(name: String, id: String) -> Self {
        Self { name, id }
    }
}

/// Key rename result
/// Ported from: core/commands/keystore.go
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct KeyRenameResult {
    /// Was the key renamed
    #[serde(rename = "Was")]
    pub was: String,
    /// New name
    #[serde(rename = "Now")]
    pub now: String,
    /// Key ID
    #[serde(rename = "Id")]
    pub id: String,
    /// Whether the key was overwritten
    #[serde(rename = "Overwrite")]
    pub overwrite: bool,
}

impl KeyRenameResult {
    /// Create a new key rename result
    pub fn new(was: String, now: String, id: String, overwrite: bool) -> Self {
        Self {
            was,
            now,
            id,
            overwrite,
        }
    }
}

/// Key removal result
/// Ported from: core/commands/keystore.go
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct KeyRmResult {
    /// List of removed keys
    #[serde(rename = "Keys")]
    pub keys: Vec<KeyInfo>,
}

impl KeyRmResult {
    /// Create a new key removal result
    pub fn new(keys: Vec<KeyInfo>) -> Self {
        Self { keys }
    }

    /// Create a single key removal result
    pub fn single(name: String, id: String) -> Self {
        Self {
            keys: vec![KeyInfo::new(name, id)],
        }
    }
}

/// IPNS publish options
/// Ported from: core/commands/name/publish.go
#[derive(Debug, Clone)]
pub struct IpnsPublishOptions {
    /// Key to use for signing (default: "self")
    pub key: String,
    /// Resolve the given path before publishing
    pub resolve: bool,
    /// Time duration this record should be valid for (e.g., "24h")
    pub lifetime: String,
    /// Time-to-live for the record
    pub ttl: Option<String>,
    /// Quieter output
    pub quieter: bool,
    /// Allow offline operation
    pub allow_offline: bool,
}

impl Default for IpnsPublishOptions {
    fn default() -> Self {
        Self {
            key: "self".to_string(),
            resolve: true,
            lifetime: "24h".to_string(),
            ttl: None,
            quieter: false,
            allow_offline: false,
        }
    }
}

/// IPNS resolve options
/// Ported from: core/commands/name/resolve.go
#[derive(Debug, Clone)]
pub struct IpnsResolveOptions {
    /// Resolve until the result is not an IPNS name
    pub recursive: bool,
    /// Do not use cached entries
    pub nocache: bool,
    /// Number of records to request for DHT resolution
    pub dht_record_count: u32,
    /// Timeout for DHT resolution
    pub dht_timeout: Option<String>,
    /// Stream resolution progress
    pub stream: bool,
}

impl Default for IpnsResolveOptions {
    fn default() -> Self {
        Self {
            recursive: true,
            nocache: false,
            dht_record_count: 16,
            dht_timeout: None,
            stream: false,
        }
    }
}

/// Default IPNS record TTL in nanoseconds (1 hour)
pub const IPNS_DEFAULT_TTL: u64 = 3_600_000_000_000;

/// Default IPNS record lifetime (24 hours)
pub const IPNS_DEFAULT_LIFETIME: &str = "24h";

/// IPNS protocol prefix
pub const IPNS_PREFIX: &str = "/ipns/";

/// IPFS protocol prefix
pub const IPFS_PREFIX: &str = "/ipfs/";

// =============================================================================
// MFS Types (Phase 11)
// Ported from: core/commands/files.go
//
// The Mutable File System (MFS) provides a Unix-like filesystem interface
// on top of IPFS. It allows users to create, modify, and organize files
// in a familiar hierarchical structure while maintaining IPFS's
// content-addressed storage model.
//
// Key concepts:
// - MFS maintains a root directory that can be modified over time
// - All changes are tracked and can be published to IPNS
// - Files and directories are stored as UnixFS objects
// - The root CID changes when any content is modified
// =============================================================================

/// Type of a node in the Mutable File System.
///
/// MFS nodes can be either files or directories, mirroring the Unix
/// filesystem model. This enum is used in stat results and internally
/// to track node types.
///
/// # Kubo Equivalent
///
/// Corresponds to the type field in `ipfs files stat` output.
/// See `core/commands/files.go:filesStatCmd`.
///
/// # Serialization
///
/// Serializes to lowercase strings: `"file"` or `"directory"`.
///
/// # Example
///
/// ```
/// use ferripfs_network::MfsNodeType;
///
/// let file_type = MfsNodeType::File;
/// let dir_type = MfsNodeType::Directory;
///
/// assert_eq!(format!("{}", file_type), "file");
/// assert_eq!(format!("{}", dir_type), "directory");
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[derive(Default)]
pub enum MfsNodeType {
    /// A regular file containing data.
    #[serde(rename = "file")]
    #[default]
    File,
    /// A directory containing other files and directories.
    #[serde(rename = "directory")]
    Directory,
}


impl std::fmt::Display for MfsNodeType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::File => write!(f, "file"),
            Self::Directory => write!(f, "directory"),
        }
    }
}

/// Result of an MFS stat operation.
///
/// Contains metadata about a file or directory in the Mutable File System,
/// including its content hash, size, type information, and optional locality
/// information indicating whether content is available locally.
///
/// # Kubo Equivalent
///
/// Corresponds to the output of `ipfs files stat` command.
/// See `core/commands/files.go:filesStatCmd`.
///
/// # JSON Serialization
///
/// Field names are serialized in PascalCase to match Kubo's output format:
/// - `Hash`: CID of the content
/// - `Size`: Logical file size in bytes
/// - `CumulativeSize`: Total size including block overhead
/// - `Blocks`: Number of IPFS blocks
/// - `Type`: `"file"` or `"directory"`
///
/// # Example
///
/// ```
/// use ferripfs_network::{MfsStatResult, MfsNodeType};
///
/// let stat = MfsStatResult::file(
///     "QmExample...".to_string(),
///     1024,  // logical size
///     1152,  // cumulative size with overhead
///     2,     // number of blocks
/// );
///
/// assert_eq!(stat.node_type, MfsNodeType::File);
/// assert_eq!(stat.size, 1024);
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct MfsStatResult {
    /// CID hash of the file or directory root.
    ///
    /// For files, this is the CID of the UnixFS file node.
    /// For directories, this is the CID of the directory node.
    #[serde(rename = "Hash")]
    pub hash: String,

    /// Logical size of the content in bytes.
    ///
    /// For files, this is the actual file size.
    /// For directories, this is typically 0.
    #[serde(rename = "Size")]
    pub size: u64,

    /// Cumulative size including all blocks and metadata overhead.
    ///
    /// This includes the size of all blocks in the DAG, including
    /// intermediate nodes for large files and any protobuf encoding overhead.
    #[serde(rename = "CumulativeSize")]
    pub cumulative_size: u64,

    /// Number of blocks comprising this node.
    ///
    /// For small files this is 1. Larger files are split into multiple
    /// blocks arranged in a DAG structure.
    #[serde(rename = "Blocks")]
    pub blocks: u64,

    /// Type of the node: file or directory.
    #[serde(rename = "Type")]
    pub node_type: MfsNodeType,

    /// Whether locality information was requested.
    ///
    /// When `true`, the `local` and `size_local` fields contain meaningful data.
    /// Only present when `--with-local` flag is used.
    #[serde(rename = "WithLocality", skip_serializing_if = "Option::is_none")]
    pub with_locality: Option<bool>,

    /// Whether all blocks for this content are available locally.
    ///
    /// Only meaningful when `with_locality` is `Some(true)`.
    #[serde(rename = "Local", skip_serializing_if = "Option::is_none")]
    pub local: Option<bool>,

    /// Size of locally available data in bytes.
    ///
    /// Only meaningful when `with_locality` is `Some(true)`.
    #[serde(rename = "SizeLocal", skip_serializing_if = "Option::is_none")]
    pub size_local: Option<u64>,
}

impl MfsStatResult {
    /// Create a new stat result for a file.
    ///
    /// # Arguments
    ///
    /// * `hash` - The CID of the file's root block
    /// * `size` - The logical size of the file in bytes
    /// * `cumulative_size` - Total size including all blocks and metadata
    /// * `blocks` - Number of blocks comprising this file
    ///
    /// # Returns
    ///
    /// An `MfsStatResult` with `node_type` set to `MfsNodeType::File`
    /// and all locality fields set to `None`.
    pub fn file(hash: String, size: u64, cumulative_size: u64, blocks: u64) -> Self {
        Self {
            hash,
            size,
            cumulative_size,
            blocks,
            node_type: MfsNodeType::File,
            with_locality: None,
            local: None,
            size_local: None,
        }
    }

    /// Create a new stat result for a directory.
    ///
    /// # Arguments
    ///
    /// * `hash` - The CID of the directory node
    /// * `size` - The logical size (typically 0 for directories)
    /// * `cumulative_size` - Total size including all content and metadata
    /// * `blocks` - Number of blocks in the directory node
    ///
    /// # Returns
    ///
    /// An `MfsStatResult` with `node_type` set to `MfsNodeType::Directory`
    /// and all locality fields set to `None`.
    pub fn directory(hash: String, size: u64, cumulative_size: u64, blocks: u64) -> Self {
        Self {
            hash,
            size,
            cumulative_size,
            blocks,
            node_type: MfsNodeType::Directory,
            with_locality: None,
            local: None,
            size_local: None,
        }
    }
}

/// A single entry in an MFS directory listing.
///
/// Represents a file or directory within an MFS directory, containing
/// the name, type, size, and content hash.
///
/// # Kubo Equivalent
///
/// Corresponds to entries in the output of `ipfs files ls` command.
/// See `core/commands/files.go:filesLsCmd`.
///
/// # Type Field
///
/// The `entry_type` field uses integer values for compatibility with Kubo:
/// - `0` = file
/// - `1` = directory
///
/// Use the `is_file()` and `is_directory()` methods for type checking.
///
/// # Example
///
/// ```
/// use ferripfs_network::MfsLsEntry;
///
/// let file = MfsLsEntry::file("readme.txt".into(), 1024, "Qm...".into());
/// assert!(file.is_file());
/// assert_eq!(file.name, "readme.txt");
///
/// let dir = MfsLsEntry::directory("docs".into(), 0, "Qm...".into());
/// assert!(dir.is_directory());
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct MfsLsEntry {
    /// Name of the file or directory.
    ///
    /// This is the basename, not a full path.
    #[serde(rename = "Name")]
    pub name: String,

    /// Type indicator: 0 for file, 1 for directory.
    ///
    /// Use `is_file()` or `is_directory()` for type checking.
    #[serde(rename = "Type")]
    pub entry_type: i32,

    /// Size of the entry in bytes.
    ///
    /// For files, this is the logical file size.
    /// For directories, this is typically 0.
    #[serde(rename = "Size")]
    pub size: u64,

    /// CID hash of the entry's content.
    #[serde(rename = "Hash")]
    pub hash: String,
}

impl MfsLsEntry {
    /// Create a directory listing entry for a file.
    ///
    /// # Arguments
    ///
    /// * `name` - The filename (basename only)
    /// * `size` - The logical file size in bytes
    /// * `hash` - The CID of the file's content
    pub fn file(name: String, size: u64, hash: String) -> Self {
        Self {
            name,
            entry_type: 0,
            size,
            hash,
        }
    }

    /// Create a directory listing entry for a subdirectory.
    ///
    /// # Arguments
    ///
    /// * `name` - The directory name (basename only)
    /// * `size` - The size (typically 0 for directories)
    /// * `hash` - The CID of the directory node
    pub fn directory(name: String, size: u64, hash: String) -> Self {
        Self {
            name,
            entry_type: 1,
            size,
            hash,
        }
    }

    /// Returns `true` if this entry is a file.
    pub fn is_file(&self) -> bool {
        self.entry_type == 0
    }

    /// Returns `true` if this entry is a directory.
    pub fn is_directory(&self) -> bool {
        self.entry_type == 1
    }
}

/// Result of an MFS directory listing operation.
///
/// Contains a list of entries (files and directories) within an MFS directory.
///
/// # Kubo Equivalent
///
/// Corresponds to the JSON output of `ipfs files ls` command.
/// See `core/commands/files.go:filesLsCmd`.
///
/// # Example
///
/// ```
/// use ferripfs_network::{MfsLsResult, MfsLsEntry};
///
/// let mut result = MfsLsResult::empty();
/// result.add(MfsLsEntry::file("readme.txt".into(), 1024, "Qm...".into()));
/// result.add(MfsLsEntry::directory("docs".into(), 0, "Qm...".into()));
///
/// assert_eq!(result.len(), 2);
/// assert!(!result.is_empty());
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct MfsLsResult {
    /// List of directory entries.
    ///
    /// May be empty for an empty directory.
    #[serde(rename = "Entries")]
    pub entries: Vec<MfsLsEntry>,
}

impl MfsLsResult {
    /// Create a new directory listing result with the given entries.
    pub fn new(entries: Vec<MfsLsEntry>) -> Self {
        Self { entries }
    }

    /// Create an empty directory listing result.
    ///
    /// Represents an empty directory.
    pub fn empty() -> Self {
        Self {
            entries: Vec::new(),
        }
    }

    /// Add an entry to the directory listing.
    pub fn add(&mut self, entry: MfsLsEntry) {
        self.entries.push(entry);
    }

    /// Returns the number of entries in the listing.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Returns `true` if the directory listing is empty.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }
}

/// Result of an MFS flush operation.
///
/// Contains the CID of the flushed directory, which represents the
/// current state of the MFS tree after all pending changes have been
/// persisted to the blockstore.
///
/// # Kubo Equivalent
///
/// Corresponds to the output of `ipfs files flush` command.
/// See `core/commands/files.go:filesFlushCmd`.
///
/// # Example
///
/// ```
/// use ferripfs_network::MfsFlushResult;
///
/// let result = MfsFlushResult::new("QmRoot...".to_string());
/// println!("Flushed to CID: {}", result.cid);
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct MfsFlushResult {
    /// CID of the flushed directory/file.
    ///
    /// This is the content hash after all pending changes have been
    /// written to the blockstore.
    #[serde(rename = "Cid")]
    pub cid: String,
}

impl MfsFlushResult {
    /// Create a new flush result with the given CID.
    pub fn new(cid: String) -> Self {
        Self { cid }
    }
}

/// Result of an MFS file read operation (internal).
///
/// Contains the data read from a file along with metadata about
/// the read operation.
///
/// # Note
///
/// This type is for internal use. The `files read` command writes
/// data directly to stdout rather than returning this struct.
///
/// # Kubo Reference
///
/// See `core/commands/files.go:filesReadCmd`.
#[derive(Debug, Clone)]
pub struct MfsReadResult {
    /// Raw data read from the file.
    pub data: Vec<u8>,

    /// Byte offset where the read started.
    pub offset: u64,

    /// Number of bytes read.
    pub length: u64,
}

impl MfsReadResult {
    /// Create a new read result.
    ///
    /// The `length` field is automatically calculated from the data length.
    pub fn new(data: Vec<u8>, offset: u64) -> Self {
        let length = data.len() as u64;
        Self {
            data,
            offset,
            length,
        }
    }
}

/// Options for an MFS file write operation.
///
/// Controls how data is written to a file in MFS, including whether
/// to create the file, where to write, and how to encode the content.
///
/// # Kubo Equivalent
///
/// Corresponds to the flags of `ipfs files write` command.
/// See `core/commands/files.go:filesWriteCmd`.
///
/// # Example
///
/// ```
/// use ferripfs_network::MfsWriteOptions;
///
/// // Create a file if it doesn't exist
/// let mut opts = MfsWriteOptions::default();
/// opts.create = true;
/// opts.parents = true;
///
/// assert!(opts.create);
/// assert!(opts.parents);
/// ```
#[derive(Debug, Clone)]
pub struct MfsWriteOptions {
    /// Create the file if it doesn't exist.
    ///
    /// Without this, writing to a non-existent file will fail.
    pub create: bool,

    /// Create parent directories as needed.
    ///
    /// Similar to `mkdir -p` behavior.
    pub parents: bool,

    /// Truncate the file before writing.
    ///
    /// When true, the file is cleared before new data is written.
    pub truncate: bool,

    /// Maximum number of bytes to write from input.
    ///
    /// If `None`, all input data is written.
    pub count: Option<u64>,

    /// Byte offset within the file to start writing at.
    ///
    /// Allows appending or overwriting at a specific position.
    pub offset: u64,

    /// Use raw leaves in the UnixFS DAG.
    ///
    /// When true, leaf nodes contain raw data without UnixFS wrapping.
    pub raw_leaves: bool,

    /// CID version to use for new blocks (0 or 1).
    pub cid_version: u8,

    /// Hash algorithm for content addressing.
    ///
    /// Default is "sha2-256".
    pub hash: String,
}

impl Default for MfsWriteOptions {
    fn default() -> Self {
        Self {
            create: false,
            parents: false,
            truncate: false,
            count: None,
            offset: 0,
            raw_leaves: false,
            cid_version: 0,
            hash: "sha2-256".to_string(),
        }
    }
}

impl MfsWriteOptions {
    /// Create options for creating a new file
    pub fn create_new() -> Self {
        Self {
            create: true,
            truncate: true,
            ..Self::default()
        }
    }

    /// Create options for appending to a file
    pub fn append() -> Self {
        Self {
            create: true,
            offset: u64::MAX, // Special value meaning "end of file"
            ..Self::default()
        }
    }
}

/// Options for an MFS copy operation.
///
/// Controls how files are copied within MFS or from IPFS to MFS.
///
/// # Kubo Equivalent
///
/// Corresponds to the flags of `ipfs files cp` command.
/// See `core/commands/files.go:filesCpCmd`.
#[derive(Debug, Clone, Default)]
pub struct MfsCpOptions {
    /// Create parent directories in the destination path as needed.
    ///
    /// Similar to `mkdir -p` behavior before copying.
    pub parents: bool,
}

/// Options for an MFS mkdir operation.
///
/// Controls how directories are created in MFS.
///
/// # Kubo Equivalent
///
/// Corresponds to the flags of `ipfs files mkdir` command.
/// See `core/commands/files.go:filesMkdirCmd`.
#[derive(Debug, Clone)]
pub struct MfsMkdirOptions {
    /// Create parent directories as needed.
    ///
    /// Similar to `mkdir -p` behavior.
    pub parents: bool,

    /// CID version to use for the new directory (0 or 1).
    pub cid_version: u8,

    /// Hash algorithm for content addressing.
    ///
    /// Default is "sha2-256".
    pub hash: String,
}

impl Default for MfsMkdirOptions {
    fn default() -> Self {
        Self {
            parents: false,
            cid_version: 0,
            hash: "sha2-256".to_string(),
        }
    }
}

/// Options for an MFS remove operation.
///
/// Controls how files and directories are removed from MFS.
///
/// # Kubo Equivalent
///
/// Corresponds to the flags of `ipfs files rm` command.
/// See `core/commands/files.go:filesRmCmd`.
#[derive(Debug, Clone, Default)]
pub struct MfsRmOptions {
    /// Recursively remove directories and their contents.
    ///
    /// Required to remove non-empty directories.
    pub recursive: bool,

    /// Force removal, ignoring errors if the path doesn't exist.
    pub force: bool,
}

/// Options for an MFS move/rename operation.
///
/// Controls how files and directories are moved within MFS.
///
/// # Kubo Equivalent
///
/// Corresponds to the flags of `ipfs files mv` command.
/// See `core/commands/files.go:filesMvCmd`.
#[derive(Debug, Clone, Default)]
pub struct MfsMvOptions {
    /// Flush changes to the blockstore after moving.
    pub flush: bool,
}

/// Options for changing CID settings in MFS.
///
/// Controls the CID version and hash algorithm used for content
/// at a specific path in MFS.
///
/// # Kubo Equivalent
///
/// Corresponds to the flags of `ipfs files chcid` command.
/// See `core/commands/files.go:filesChcidCmd`.
#[derive(Debug, Clone)]
#[derive(Default)]
pub struct MfsChcidOptions {
    /// New CID version to use (0 or 1).
    ///
    /// If `None`, the existing version is kept.
    pub cid_version: Option<u8>,

    /// New hash algorithm to use.
    ///
    /// If `None`, the existing algorithm is kept.
    pub hash: Option<String>,
}


/// Generic result for MFS operations.
///
/// Provides a simple success/failure indication with an optional
/// error message for failed operations.
///
/// # Example
///
/// ```
/// use ferripfs_network::MfsOpResult;
///
/// let success = MfsOpResult::success();
/// assert!(success.success);
///
/// let failure = MfsOpResult::failure("file not found".to_string());
/// assert!(!failure.success);
/// assert_eq!(failure.error, Some("file not found".to_string()));
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct MfsOpResult {
    /// Whether the operation completed successfully.
    #[serde(rename = "Success")]
    pub success: bool,

    /// Error message if the operation failed.
    #[serde(rename = "Error", skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
}

impl MfsOpResult {
    /// Create a successful operation result.
    pub fn success() -> Self {
        Self {
            success: true,
            error: None,
        }
    }

    /// Create a failed operation result with an error message.
    pub fn failure(error: String) -> Self {
        Self {
            success: false,
            error: Some(error),
        }
    }
}

/// The root path for MFS operations.
///
/// All MFS paths are absolute and start with this root.
pub const MFS_ROOT: &str = "/";

/// The path separator character used in MFS paths.
pub const MFS_SEPARATOR: char = '/';

// =============================================================================
// PubSub Types (Phase 12)
// Ported from: boxo/pubsub, core/commands/pubsub.go
// =============================================================================

/// A message received from or published to a pubsub topic.
///
/// # Kubo Equivalent
///
/// Corresponds to the message format used in `ipfs pubsub sub` output.
/// See `core/commands/pubsub.go:pubsubSubCmd`.
///
/// # Example
///
/// ```
/// use ferripfs_network::PubsubMessage;
///
/// // Create a simple message with just sender, topic, and data
/// let msg = PubsubMessage::simple(
///     "QmPeerID".to_string(),
///     "my-topic".to_string(),
///     b"Hello, world!".to_vec(),
/// );
/// assert_eq!(msg.topic, "my-topic");
///
/// // Or create a message with all fields
/// let msg_full = PubsubMessage::new(
///     "QmPeerID".to_string(),
///     b"Hello!".to_vec(),
///     vec![1, 2, 3, 4],  // seqno
///     vec!["my-topic".to_string()],  // topic_ids
///     "my-topic".to_string(),
/// );
/// assert_eq!(msg_full.seqno, vec![1, 2, 3, 4]);
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct PubsubMessage {
    /// Peer ID of the message sender.
    #[serde(rename = "from")]
    pub from: String,

    /// Data payload (base64 encoded in JSON).
    #[serde(rename = "data", with = "base64_serde")]
    pub data: Vec<u8>,

    /// Sequence number for ordering.
    #[serde(rename = "seqno", with = "base64_serde")]
    pub seqno: Vec<u8>,

    /// Topic IDs the message was received on.
    #[serde(rename = "topicIDs")]
    pub topic_ids: Vec<String>,

    /// Primary topic (convenience field).
    #[serde(skip)]
    pub topic: String,
}

impl PubsubMessage {
    /// Create a new pubsub message with all fields.
    ///
    /// # Arguments
    ///
    /// * `from` - Peer ID of the sender
    /// * `data` - Message payload
    /// * `seqno` - Sequence number bytes
    /// * `topic_ids` - List of topic IDs
    /// * `topic` - Primary topic
    pub fn new(
        from: String,
        data: Vec<u8>,
        seqno: Vec<u8>,
        topic_ids: Vec<String>,
        topic: String,
    ) -> Self {
        Self {
            from,
            data,
            seqno,
            topic_ids,
            topic,
        }
    }

    /// Create a simple message for a single topic.
    ///
    /// This is a convenience method that sets seqno to empty
    /// and derives topic_ids from the single topic.
    pub fn simple(from: String, topic: String, data: Vec<u8>) -> Self {
        Self {
            from,
            data,
            seqno: Vec::new(),
            topic_ids: vec![topic.clone()],
            topic,
        }
    }

    /// Create a message with a sequence number.
    pub fn with_seqno(from: String, topic: String, data: Vec<u8>, seqno: Vec<u8>) -> Self {
        Self {
            from,
            data,
            seqno,
            topic_ids: vec![topic.clone()],
            topic,
        }
    }

    /// Get the message data as a UTF-8 string (if valid).
    pub fn data_string(&self) -> Option<String> {
        String::from_utf8(self.data.clone()).ok()
    }
}

/// Helper module for base64 serialization of byte vectors.
mod base64_serde {
    use base64::{engine::general_purpose::STANDARD, Engine};
    use serde::{Deserialize, Deserializer, Serializer};

    pub fn serialize<S>(bytes: &Vec<u8>, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_str(&STANDARD.encode(bytes))
    }

    pub fn deserialize<'de, D>(deserializer: D) -> Result<Vec<u8>, D::Error>
    where
        D: Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        STANDARD.decode(&s).map_err(serde::de::Error::custom)
    }
}

/// Information about a peer subscribed to a pubsub topic.
///
/// # Kubo Equivalent
///
/// Corresponds to the output of `ipfs pubsub peers`.
/// See `core/commands/pubsub.go:pubsubPeersCmd`.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct PubsubPeer {
    /// Peer ID of the subscriber.
    #[serde(rename = "ID")]
    pub id: String,
}

impl PubsubPeer {
    /// Create a new pubsub peer.
    pub fn new(id: String) -> Self {
        Self { id }
    }
}

/// Result of listing pubsub topics.
///
/// # Kubo Equivalent
///
/// Corresponds to the output of `ipfs pubsub ls`.
/// See `core/commands/pubsub.go:pubsubLsCmd`.
///
/// # Example
///
/// ```
/// use ferripfs_network::PubsubLsResult;
///
/// let mut result = PubsubLsResult::empty();
/// result.add("topic1".to_string());
/// result.add("topic2".to_string());
/// assert_eq!(result.len(), 2);
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct PubsubLsResult {
    /// List of topic strings.
    #[serde(rename = "Strings")]
    pub strings: Vec<String>,
}

impl PubsubLsResult {
    /// Create a new topic list.
    pub fn new(strings: Vec<String>) -> Self {
        Self { strings }
    }

    /// Create an empty topic list.
    pub fn empty() -> Self {
        Self {
            strings: Vec::new(),
        }
    }

    /// Add a topic to the list.
    pub fn add(&mut self, topic: String) {
        self.strings.push(topic);
    }

    /// Get the number of topics.
    pub fn len(&self) -> usize {
        self.strings.len()
    }

    /// Check if the list is empty.
    pub fn is_empty(&self) -> bool {
        self.strings.is_empty()
    }
}

/// Result of listing peers for a pubsub topic.
///
/// # Kubo Equivalent
///
/// Corresponds to the output of `ipfs pubsub peers <topic>`.
/// See `core/commands/pubsub.go:pubsubPeersCmd`.
///
/// # Example
///
/// ```
/// use ferripfs_network::{PubsubPeersResult, PubsubPeer};
///
/// let mut result = PubsubPeersResult::empty();
/// result.add(PubsubPeer::new("QmPeer1".to_string()));
/// assert_eq!(result.len(), 1);
/// ```
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct PubsubPeersResult {
    /// List of peer strings (peer IDs).
    #[serde(rename = "Strings")]
    pub strings: Vec<String>,
}

impl PubsubPeersResult {
    /// Create a new peers result.
    pub fn new(peers: Vec<String>) -> Self {
        Self { strings: peers }
    }

    /// Create an empty peers result.
    pub fn empty() -> Self {
        Self {
            strings: Vec::new(),
        }
    }

    /// Add a peer to the result.
    pub fn add(&mut self, peer: PubsubPeer) {
        self.strings.push(peer.id);
    }

    /// Add a peer ID string directly.
    pub fn add_id(&mut self, id: String) {
        self.strings.push(id);
    }

    /// Get the number of peers.
    pub fn len(&self) -> usize {
        self.strings.len()
    }

    /// Check if empty.
    pub fn is_empty(&self) -> bool {
        self.strings.is_empty()
    }
}

/// Result of publishing a message to a pubsub topic.
///
/// # Kubo Equivalent
///
/// Corresponds to the output of `ipfs pubsub pub`.
/// See `core/commands/pubsub.go:pubsubPubCmd`.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct PubsubPublishResult {
    /// Whether the publish was successful.
    #[serde(rename = "Success")]
    pub success: bool,

    /// Error message if publish failed.
    #[serde(rename = "Error", skip_serializing_if = "Option::is_none")]
    pub error: Option<String>,
}

impl PubsubPublishResult {
    /// Create a successful publish result.
    pub fn success() -> Self {
        Self {
            success: true,
            error: None,
        }
    }

    /// Create a failed publish result.
    pub fn failure(error: String) -> Self {
        Self {
            success: false,
            error: Some(error),
        }
    }
}

/// Subscription state for pubsub.
///
/// Tracks an active subscription to a topic.
#[derive(Debug, Clone)]
pub struct PubsubSubscription {
    /// Topic being subscribed to.
    pub topic: String,

    /// Whether the subscription is active.
    pub active: bool,
}

impl PubsubSubscription {
    /// Create a new subscription.
    pub fn new(topic: String) -> Self {
        Self {
            topic,
            active: true,
        }
    }

    /// Cancel the subscription.
    pub fn cancel(&mut self) {
        self.active = false;
    }
}

/// PubSub router type enumeration.
///
/// # Kubo Equivalent
///
/// Corresponds to the router types in Kubo's pubsub configuration.
/// GossipSub is the default and recommended router.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum PubsubRouter {
    /// GossipSub router (default, recommended).
    #[default]
    #[serde(rename = "gossipsub")]
    Gossipsub,

    /// FloodSub router (simple flooding).
    #[serde(rename = "floodsub")]
    Floodsub,
}

impl std::fmt::Display for PubsubRouter {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Gossipsub => write!(f, "gossipsub"),
            Self::Floodsub => write!(f, "floodsub"),
        }
    }
}

impl std::str::FromStr for PubsubRouter {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s.to_lowercase().as_str() {
            "gossipsub" => Ok(Self::Gossipsub),
            "floodsub" => Ok(Self::Floodsub),
            _ => Err(format!("unknown pubsub router: {}", s)),
        }
    }
}

/// PubSub statistics.
///
/// # Kubo Equivalent
///
/// Statistics about pubsub operation, similar to what would be
/// returned by a hypothetical `ipfs stats pubsub` command.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct PubsubStats {
    /// Number of topics subscribed to.
    #[serde(rename = "NumTopics")]
    pub num_topics: u64,

    /// Number of peers across all topics.
    #[serde(rename = "NumPeers")]
    pub num_peers: u64,

    /// Number of messages received.
    #[serde(rename = "MessagesReceived")]
    pub messages_received: u64,

    /// Number of messages sent.
    #[serde(rename = "MessagesSent")]
    pub messages_sent: u64,

    /// Total bytes received.
    #[serde(rename = "BytesReceived")]
    pub bytes_received: u64,

    /// Total bytes sent.
    #[serde(rename = "BytesSent")]
    pub bytes_sent: u64,
}

impl PubsubStats {
    /// Create new stats with all values specified.
    ///
    /// # Arguments
    ///
    /// * `num_topics` - Number of subscribed topics
    /// * `num_peers` - Number of connected peers
    /// * `messages_received` - Count of received messages
    /// * `messages_sent` - Count of sent messages
    /// * `bytes_received` - Total bytes received
    /// * `bytes_sent` - Total bytes sent
    pub fn new(
        num_topics: u64,
        num_peers: u64,
        messages_received: u64,
        messages_sent: u64,
        bytes_received: u64,
        bytes_sent: u64,
    ) -> Self {
        Self {
            num_topics,
            num_peers,
            messages_received,
            messages_sent,
            bytes_received,
            bytes_sent,
        }
    }

    /// Create new empty stats.
    pub fn empty() -> Self {
        Self::default()
    }

    /// Record a received message.
    pub fn record_received(&mut self, bytes: u64) {
        self.messages_received += 1;
        self.bytes_received += bytes;
    }

    /// Record a sent message.
    pub fn record_sent(&mut self, bytes: u64) {
        self.messages_sent += 1;
        self.bytes_sent += bytes;
    }
}

/// Protocol version for pubsub.
pub const PUBSUB_PROTOCOL_VERSION: &str = "/meshsub/1.1.0";

/// Default GossipSub protocol ID.
pub const GOSSIPSUB_PROTOCOL_ID: &str = "/meshsub/1.1.0";

/// FloodSub protocol ID.
pub const FLOODSUB_PROTOCOL_ID: &str = "/floodsub/1.0.0";

// =============================================================================
// HTTP Gateway Types (Phase 13)
// =============================================================================

/// Default gateway port.
pub const DEFAULT_GATEWAY_PORT: u16 = 8080;

/// Default gateway address.
pub const DEFAULT_GATEWAY_ADDRESS: &str = "127.0.0.1:8080";

/// IPFS path prefix.
pub const IPFS_PATH_PREFIX: &str = "/ipfs/";

/// IPNS path prefix.
pub const IPNS_PATH_PREFIX: &str = "/ipns/";

/// Parsed gateway path representing an IPFS or IPNS request.
///
/// # Kubo Equivalent
///
/// Corresponds to path parsing in `boxo/gateway/handler.go`.
///
/// # Example
///
/// ```
/// use ferripfs_network::GatewayPath;
///
/// let path = GatewayPath::parse("/ipfs/QmTest123/file.txt").unwrap();
/// assert!(path.is_ipfs());
/// assert_eq!(path.root(), "QmTest123");
/// assert_eq!(path.remainder(), Some("file.txt".to_string()));
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GatewayPath {
    /// Path type (ipfs or ipns)
    pub path_type: GatewayPathType,
    /// Root identifier (CID for IPFS, name for IPNS)
    pub root: String,
    /// Remaining path after root (e.g., "/file.txt")
    pub remainder: Option<String>,
}

impl GatewayPath {
    /// Parse a gateway path string.
    ///
    /// # Arguments
    ///
    /// * `path` - Path string like "/ipfs/Qm.../file.txt"
    ///
    /// # Returns
    ///
    /// Parsed path or None if invalid
    pub fn parse(path: &str) -> Option<Self> {
        let path = path.trim_start_matches('/');

        if let Some(rest) = path.strip_prefix("ipfs/") {
            Self::parse_with_type(rest, GatewayPathType::Ipfs)
        } else if let Some(rest) = path.strip_prefix("ipns/") {
            Self::parse_with_type(rest, GatewayPathType::Ipns)
        } else {
            None
        }
    }

    fn parse_with_type(rest: &str, path_type: GatewayPathType) -> Option<Self> {
        if rest.is_empty() {
            return None;
        }

        let parts: Vec<&str> = rest.splitn(2, '/').collect();
        let root = parts[0].to_string();

        if root.is_empty() {
            return None;
        }

        let remainder = if parts.len() > 1 && !parts[1].is_empty() {
            Some(parts[1].to_string())
        } else {
            None
        };

        Some(Self {
            path_type,
            root,
            remainder,
        })
    }

    /// Check if this is an IPFS path.
    pub fn is_ipfs(&self) -> bool {
        self.path_type == GatewayPathType::Ipfs
    }

    /// Check if this is an IPNS path.
    pub fn is_ipns(&self) -> bool {
        self.path_type == GatewayPathType::Ipns
    }

    /// Get the root identifier.
    pub fn root(&self) -> &str {
        &self.root
    }

    /// Get the remainder path.
    pub fn remainder(&self) -> Option<String> {
        self.remainder.clone()
    }

    /// Get the full path string.
    pub fn to_path_string(&self) -> String {
        let prefix = match self.path_type {
            GatewayPathType::Ipfs => IPFS_PATH_PREFIX,
            GatewayPathType::Ipns => IPNS_PATH_PREFIX,
        };
        match &self.remainder {
            Some(r) => format!("{}{}/{}", prefix, self.root, r),
            None => format!("{}{}", prefix, self.root),
        }
    }
}

/// Type of gateway path (IPFS or IPNS).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GatewayPathType {
    /// Content-addressed path (/ipfs/...)
    Ipfs,
    /// Name-addressed path (/ipns/...)
    Ipns,
}

impl std::fmt::Display for GatewayPathType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            GatewayPathType::Ipfs => write!(f, "ipfs"),
            GatewayPathType::Ipns => write!(f, "ipns"),
        }
    }
}

/// HTTP method for gateway requests.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GatewayMethod {
    /// GET request
    Get,
    /// HEAD request
    Head,
    /// OPTIONS request (CORS preflight)
    Options,
}

impl std::fmt::Display for GatewayMethod {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            GatewayMethod::Get => write!(f, "GET"),
            GatewayMethod::Head => write!(f, "HEAD"),
            GatewayMethod::Options => write!(f, "OPTIONS"),
        }
    }
}

/// Content type for gateway responses.
///
/// # Kubo Equivalent
///
/// Corresponds to content type handling in `boxo/gateway/handler.go`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum GatewayContentType {
    /// Raw bytes (application/octet-stream)
    Raw,
    /// JSON (application/json)
    Json,
    /// CBOR (application/cbor)
    Cbor,
    /// CAR archive (application/vnd.ipld.car)
    Car,
    /// HTML (text/html)
    Html,
    /// Plain text (text/plain)
    Text,
    /// Directory listing (text/html)
    Directory,
    /// Custom MIME type
    Custom(String),
}

impl GatewayContentType {
    /// Get the MIME type string.
    pub fn mime_type(&self) -> &str {
        match self {
            GatewayContentType::Raw => "application/octet-stream",
            GatewayContentType::Json => "application/json",
            GatewayContentType::Cbor => "application/cbor",
            GatewayContentType::Car => "application/vnd.ipld.car",
            GatewayContentType::Html => "text/html; charset=utf-8",
            GatewayContentType::Text => "text/plain; charset=utf-8",
            GatewayContentType::Directory => "text/html; charset=utf-8",
            GatewayContentType::Custom(s) => s,
        }
    }

    /// Parse from Accept header value.
    pub fn from_accept(accept: &str) -> Self {
        let accept_lower = accept.to_lowercase();
        if accept_lower.contains("application/vnd.ipld.car") {
            GatewayContentType::Car
        } else if accept_lower.contains("application/vnd.ipld.raw") {
            GatewayContentType::Raw
        } else if accept_lower.contains("application/json") {
            GatewayContentType::Json
        } else if accept_lower.contains("application/cbor") {
            GatewayContentType::Cbor
        } else if accept_lower.contains("text/html") {
            GatewayContentType::Html
        } else {
            GatewayContentType::Raw
        }
    }
}

impl std::fmt::Display for GatewayContentType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.mime_type())
    }
}

/// Gateway request information.
///
/// # Kubo Equivalent
///
/// Corresponds to request handling in `boxo/gateway/handler.go`.
#[derive(Debug, Clone)]
pub struct GatewayRequest {
    /// HTTP method
    pub method: GatewayMethod,
    /// Parsed path
    pub path: GatewayPath,
    /// Accept header for content negotiation
    pub accept: Option<String>,
    /// Range header for partial content
    pub range: Option<String>,
    /// Host header (for subdomain gateway)
    pub host: Option<String>,
    /// Query parameters
    pub query: std::collections::HashMap<String, String>,
}

impl GatewayRequest {
    /// Create a new gateway request.
    pub fn new(method: GatewayMethod, path: GatewayPath) -> Self {
        Self {
            method,
            path,
            accept: None,
            range: None,
            host: None,
            query: std::collections::HashMap::new(),
        }
    }

    /// Set the accept header.
    pub fn with_accept(mut self, accept: String) -> Self {
        self.accept = Some(accept);
        self
    }

    /// Set the range header.
    pub fn with_range(mut self, range: String) -> Self {
        self.range = Some(range);
        self
    }

    /// Set the host header.
    pub fn with_host(mut self, host: String) -> Self {
        self.host = Some(host);
        self
    }

    /// Get the desired content type based on Accept header.
    pub fn content_type(&self) -> GatewayContentType {
        match &self.accept {
            Some(accept) => GatewayContentType::from_accept(accept),
            None => GatewayContentType::Raw,
        }
    }

    /// Check if this is a subdomain gateway request.
    pub fn is_subdomain_request(&self) -> bool {
        if let Some(host) = &self.host {
            // Subdomain format: <cid>.ipfs.<domain> or <name>.ipns.<domain>
            host.contains(".ipfs.") || host.contains(".ipns.")
        } else {
            false
        }
    }
}

/// Gateway response data.
///
/// # Kubo Equivalent
///
/// Corresponds to response handling in `boxo/gateway/handler.go`.
#[derive(Debug, Clone)]
pub struct GatewayResponse {
    /// HTTP status code
    pub status: u16,
    /// Content type
    pub content_type: GatewayContentType,
    /// Response body
    pub body: Vec<u8>,
    /// Response headers
    pub headers: std::collections::HashMap<String, String>,
    /// Content length (if known)
    pub content_length: Option<u64>,
}

impl GatewayResponse {
    /// Create a successful response.
    pub fn ok(content_type: GatewayContentType, body: Vec<u8>) -> Self {
        let content_length = Some(body.len() as u64);
        Self {
            status: 200,
            content_type,
            body,
            headers: std::collections::HashMap::new(),
            content_length,
        }
    }

    /// Create a not found response.
    pub fn not_found(message: &str) -> Self {
        Self {
            status: 404,
            content_type: GatewayContentType::Text,
            body: message.as_bytes().to_vec(),
            headers: std::collections::HashMap::new(),
            content_length: Some(message.len() as u64),
        }
    }

    /// Create a bad request response.
    pub fn bad_request(message: &str) -> Self {
        Self {
            status: 400,
            content_type: GatewayContentType::Text,
            body: message.as_bytes().to_vec(),
            headers: std::collections::HashMap::new(),
            content_length: Some(message.len() as u64),
        }
    }

    /// Create an internal error response.
    pub fn internal_error(message: &str) -> Self {
        Self {
            status: 500,
            content_type: GatewayContentType::Text,
            body: message.as_bytes().to_vec(),
            headers: std::collections::HashMap::new(),
            content_length: Some(message.len() as u64),
        }
    }

    /// Create a redirect response.
    pub fn redirect(location: &str) -> Self {
        let mut headers = std::collections::HashMap::new();
        headers.insert("Location".to_string(), location.to_string());
        Self {
            status: 301,
            content_type: GatewayContentType::Text,
            body: Vec::new(),
            headers,
            content_length: Some(0),
        }
    }

    /// Add a header to the response.
    pub fn with_header(mut self, key: &str, value: &str) -> Self {
        self.headers.insert(key.to_string(), value.to_string());
        self
    }

    /// Add CORS headers to the response.
    pub fn with_cors(self) -> Self {
        self.with_header("Access-Control-Allow-Origin", "*")
            .with_header("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
            .with_header(
                "Access-Control-Allow-Headers",
                "Content-Type, Range, X-Requested-With",
            )
            .with_header(
                "Access-Control-Expose-Headers",
                "Content-Range, Content-Length, X-Ipfs-Path, X-Ipfs-Roots",
            )
    }

    /// Add cache control headers.
    pub fn with_cache_control(self, immutable: bool) -> Self {
        if immutable {
            // IPFS content is immutable, cache forever
            self.with_header("Cache-Control", "public, max-age=31536000, immutable")
        } else {
            // IPNS content may change
            self.with_header("Cache-Control", "public, max-age=60")
        }
    }

    /// Add IPFS-specific headers.
    pub fn with_ipfs_headers(self, path: &GatewayPath) -> Self {
        self.with_header("X-Ipfs-Path", &path.to_path_string())
    }
}

/// Gateway statistics.
///
/// # Kubo Equivalent
///
/// Corresponds to gateway metrics.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct GatewayStats {
    /// Total requests served
    #[serde(rename = "TotalRequests")]
    pub total_requests: u64,

    /// Successful requests (2xx)
    #[serde(rename = "SuccessfulRequests")]
    pub successful_requests: u64,

    /// Failed requests (4xx, 5xx)
    #[serde(rename = "FailedRequests")]
    pub failed_requests: u64,

    /// Total bytes sent
    #[serde(rename = "BytesSent")]
    pub bytes_sent: u64,

    /// IPFS path requests
    #[serde(rename = "IpfsRequests")]
    pub ipfs_requests: u64,

    /// IPNS path requests
    #[serde(rename = "IpnsRequests")]
    pub ipns_requests: u64,

    /// Subdomain requests
    #[serde(rename = "SubdomainRequests")]
    pub subdomain_requests: u64,
}

impl GatewayStats {
    /// Create new empty stats.
    pub fn new() -> Self {
        Self::default()
    }

    /// Record a request.
    pub fn record_request(&mut self, path: &GatewayPath, subdomain: bool) {
        self.total_requests += 1;
        if path.is_ipfs() {
            self.ipfs_requests += 1;
        } else {
            self.ipns_requests += 1;
        }
        if subdomain {
            self.subdomain_requests += 1;
        }
    }

    /// Record a successful response.
    pub fn record_success(&mut self, bytes: u64) {
        self.successful_requests += 1;
        self.bytes_sent += bytes;
    }

    /// Record a failed response.
    pub fn record_failure(&mut self) {
        self.failed_requests += 1;
    }
}

/// Directory entry for gateway directory listing.
///
/// # Kubo Equivalent
///
/// Corresponds to directory listing in `boxo/gateway/handler_unixfs_dir.go`.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct GatewayDirEntry {
    /// Entry name
    #[serde(rename = "Name")]
    pub name: String,

    /// Entry type (file or directory)
    #[serde(rename = "Type")]
    pub entry_type: GatewayEntryType,

    /// Size in bytes (for files)
    #[serde(rename = "Size")]
    pub size: u64,

    /// CID of the entry
    #[serde(rename = "Cid")]
    pub cid: String,
}

impl GatewayDirEntry {
    /// Create a file entry.
    pub fn file(name: String, size: u64, cid: String) -> Self {
        Self {
            name,
            entry_type: GatewayEntryType::File,
            size,
            cid,
        }
    }

    /// Create a directory entry.
    pub fn directory(name: String, cid: String) -> Self {
        Self {
            name,
            entry_type: GatewayEntryType::Directory,
            size: 0,
            cid,
        }
    }
}

/// Entry type for directory listings.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum GatewayEntryType {
    /// Regular file
    File,
    /// Directory
    Directory,
}

impl std::fmt::Display for GatewayEntryType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            GatewayEntryType::File => write!(f, "file"),
            GatewayEntryType::Directory => write!(f, "directory"),
        }
    }
}

/// Directory listing result for gateway.
///
/// # Kubo Equivalent
///
/// Corresponds to directory listing output in `boxo/gateway/handler_unixfs_dir.go`.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct GatewayDirListing {
    /// Directory path
    #[serde(rename = "Path")]
    pub path: String,

    /// Directory CID
    #[serde(rename = "Cid")]
    pub cid: String,

    /// Entries in the directory
    #[serde(rename = "Entries")]
    pub entries: Vec<GatewayDirEntry>,
}

impl GatewayDirListing {
    /// Create a new directory listing.
    pub fn new(path: String, cid: String, entries: Vec<GatewayDirEntry>) -> Self {
        Self { path, cid, entries }
    }

    /// Render as HTML.
    pub fn to_html(&self) -> String {
        let mut html = String::new();
        html.push_str("<!DOCTYPE html>\n<html>\n<head>\n");
        html.push_str(&format!("<title>Index of {}</title>\n", self.path));
        html.push_str("<style>body{font-family:monospace;} table{border-collapse:collapse;} td,th{padding:4px 8px;text-align:left;}</style>\n");
        html.push_str("</head>\n<body>\n");
        html.push_str(&format!("<h1>Index of {}</h1>\n", self.path));
        html.push_str("<table>\n<tr><th>Name</th><th>Size</th><th>CID</th></tr>\n");

        // Parent directory link if not root
        if self.path != "/" && !self.path.is_empty() {
            html.push_str("<tr><td><a href=\"..\">..</a></td><td>-</td><td>-</td></tr>\n");
        }

        for entry in &self.entries {
            let link = if entry.entry_type == GatewayEntryType::Directory {
                format!("{}/", entry.name)
            } else {
                entry.name.clone()
            };
            let size_str = if entry.entry_type == GatewayEntryType::Directory {
                "-".to_string()
            } else {
                format_bytes(entry.size)
            };
            html.push_str(&format!(
                "<tr><td><a href=\"{}\">{}</a></td><td>{}</td><td>{}</td></tr>\n",
                link,
                entry.name,
                size_str,
                &entry.cid[..12.min(entry.cid.len())]
            ));
        }

        html.push_str("</table>\n</body>\n</html>");
        html
    }

    /// Render as JSON.
    pub fn to_json(&self) -> String {
        serde_json::to_string_pretty(self).unwrap_or_default()
    }
}

/// Format bytes as human-readable string (for directory listings).
fn format_bytes(bytes: u64) -> String {
    const KB: u64 = 1024;
    const MB: u64 = KB * 1024;
    const GB: u64 = MB * 1024;

    if bytes >= GB {
        format!("{:.1}G", bytes as f64 / GB as f64)
    } else if bytes >= MB {
        format!("{:.1}M", bytes as f64 / MB as f64)
    } else if bytes >= KB {
        format!("{:.1}K", bytes as f64 / KB as f64)
    } else {
        format!("{}B", bytes)
    }
}

// ============================================================================
// Phase 14: HTTP RPC API Types
// ============================================================================

/// Default RPC API port (matches Kubo).
pub const DEFAULT_API_PORT: u16 = 5001;

/// Default RPC API address.
pub const DEFAULT_API_ADDRESS: &str = "127.0.0.1:5001";

/// API version string.
pub const API_VERSION: &str = "v0";

/// RPC API request.
///
/// # Kubo Equivalent
///
/// Corresponds to HTTP requests in `core/corehttp/corehttp.go`.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiRequest {
    /// The API endpoint being called (e.g., "/api/v0/id")
    #[serde(rename = "Endpoint")]
    pub endpoint: String,

    /// HTTP method (usually POST for Kubo RPC)
    #[serde(rename = "Method")]
    pub method: String,

    /// Request arguments
    #[serde(rename = "Arguments")]
    pub arguments: std::collections::HashMap<String, String>,

    /// Request body (for file uploads, etc.)
    #[serde(rename = "Body", skip_serializing_if = "Option::is_none")]
    pub body: Option<Vec<u8>>,
}

impl ApiRequest {
    /// Create a new API request.
    pub fn new(endpoint: &str) -> Self {
        Self {
            endpoint: endpoint.to_string(),
            method: "POST".to_string(),
            arguments: std::collections::HashMap::new(),
            body: None,
        }
    }

    /// Add an argument to the request.
    pub fn with_arg(mut self, key: &str, value: &str) -> Self {
        self.arguments.insert(key.to_string(), value.to_string());
        self
    }

    /// Set the request body.
    pub fn with_body(mut self, body: Vec<u8>) -> Self {
        self.body = Some(body);
        self
    }

    /// Build the full URL for this request.
    pub fn build_url(&self, base_url: &str) -> String {
        let mut url = format!("{}/api/{}{}", base_url, API_VERSION, self.endpoint);
        if !self.arguments.is_empty() {
            url.push('?');
            let params: Vec<String> = self
                .arguments
                .iter()
                .map(|(k, v)| format!("{}={}", k, urlencoding(v)))
                .collect();
            url.push_str(&params.join("&"));
        }
        url
    }
}

/// Simple URL encoding for API parameters.
fn urlencoding(s: &str) -> String {
    s.replace('%', "%25")
        .replace(' ', "%20")
        .replace('&', "%26")
        .replace('=', "%3D")
        .replace('?', "%3F")
        .replace('#', "%23")
}

/// RPC API response.
///
/// # Kubo Equivalent
///
/// Corresponds to HTTP responses from Kubo's RPC API.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiResponse {
    /// HTTP status code
    #[serde(rename = "StatusCode")]
    pub status_code: u16,

    /// Response headers
    #[serde(rename = "Headers")]
    pub headers: std::collections::HashMap<String, String>,

    /// Response body (JSON-encoded for most endpoints)
    #[serde(rename = "Body")]
    pub body: Vec<u8>,

    /// Error message if the request failed
    #[serde(rename = "Error", skip_serializing_if = "Option::is_none")]
    pub error: Option<ApiError>,
}

impl ApiResponse {
    /// Create a successful response.
    pub fn ok(body: Vec<u8>) -> Self {
        Self {
            status_code: 200,
            headers: std::collections::HashMap::new(),
            body,
            error: None,
        }
    }

    /// Create an error response.
    pub fn error(status_code: u16, message: &str, code: i32) -> Self {
        Self {
            status_code,
            headers: std::collections::HashMap::new(),
            body: Vec::new(),
            error: Some(ApiError {
                message: message.to_string(),
                code,
                error_type: "error".to_string(),
            }),
        }
    }

    /// Create a not found response.
    pub fn not_found(message: &str) -> Self {
        Self::error(404, message, 0)
    }

    /// Create a bad request response.
    pub fn bad_request(message: &str) -> Self {
        Self::error(400, message, 0)
    }

    /// Create an internal error response.
    pub fn internal_error(message: &str) -> Self {
        Self::error(500, message, 0)
    }

    /// Check if the response is successful.
    pub fn is_success(&self) -> bool {
        self.status_code >= 200 && self.status_code < 300
    }

    /// Get the body as a string.
    pub fn body_string(&self) -> String {
        String::from_utf8_lossy(&self.body).to_string()
    }

    /// Parse the body as JSON.
    pub fn body_json<T: serde::de::DeserializeOwned>(&self) -> Result<T, serde_json::Error> {
        serde_json::from_slice(&self.body)
    }

    /// Add a header to the response.
    pub fn with_header(mut self, key: &str, value: &str) -> Self {
        self.headers.insert(key.to_string(), value.to_string());
        self
    }

    /// Add content-type header.
    pub fn with_content_type(self, content_type: &str) -> Self {
        self.with_header("Content-Type", content_type)
    }

    /// Add CORS headers.
    pub fn with_cors(self) -> Self {
        self.with_header("Access-Control-Allow-Origin", "*")
            .with_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
            .with_header(
                "Access-Control-Allow-Headers",
                "Content-Type, Authorization",
            )
    }
}

/// API error structure.
///
/// # Kubo Equivalent
///
/// Corresponds to error responses from Kubo's RPC API.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiError {
    /// Error message
    #[serde(rename = "Message")]
    pub message: String,

    /// Error code
    #[serde(rename = "Code")]
    pub code: i32,

    /// Error type
    #[serde(rename = "Type")]
    pub error_type: String,
}

impl std::fmt::Display for ApiError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.message)
    }
}

impl std::error::Error for ApiError {}

/// API endpoint information.
///
/// Describes an available API endpoint.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiEndpoint {
    /// Endpoint path (e.g., "/id")
    #[serde(rename = "Path")]
    pub path: String,

    /// Endpoint description
    #[serde(rename = "Description")]
    pub description: String,

    /// HTTP methods supported
    #[serde(rename = "Methods")]
    pub methods: Vec<String>,

    /// Required arguments
    #[serde(rename = "Arguments")]
    pub arguments: Vec<ApiArgument>,

    /// Whether the endpoint requires authentication
    #[serde(rename = "RequiresAuth")]
    pub requires_auth: bool,
}

impl ApiEndpoint {
    /// Create a new endpoint definition.
    pub fn new(path: &str, description: &str) -> Self {
        Self {
            path: path.to_string(),
            description: description.to_string(),
            methods: vec!["POST".to_string()],
            arguments: Vec::new(),
            requires_auth: false,
        }
    }

    /// Add an argument to this endpoint.
    pub fn with_arg(mut self, arg: ApiArgument) -> Self {
        self.arguments.push(arg);
        self
    }

    /// Mark as requiring authentication.
    pub fn with_auth(mut self) -> Self {
        self.requires_auth = true;
        self
    }
}

/// API argument definition.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiArgument {
    /// Argument name
    #[serde(rename = "Name")]
    pub name: String,

    /// Argument description
    #[serde(rename = "Description")]
    pub description: String,

    /// Argument type (string, bool, int, etc.)
    #[serde(rename = "Type")]
    pub arg_type: String,

    /// Whether the argument is required
    #[serde(rename = "Required")]
    pub required: bool,

    /// Default value if not provided
    #[serde(rename = "Default", skip_serializing_if = "Option::is_none")]
    pub default: Option<String>,
}

impl ApiArgument {
    /// Create a required argument.
    pub fn required(name: &str, arg_type: &str, description: &str) -> Self {
        Self {
            name: name.to_string(),
            description: description.to_string(),
            arg_type: arg_type.to_string(),
            required: true,
            default: None,
        }
    }

    /// Create an optional argument.
    pub fn optional(name: &str, arg_type: &str, description: &str) -> Self {
        Self {
            name: name.to_string(),
            description: description.to_string(),
            arg_type: arg_type.to_string(),
            required: false,
            default: None,
        }
    }

    /// Set default value.
    pub fn with_default(mut self, default: &str) -> Self {
        self.default = Some(default.to_string());
        self
    }
}

/// API server configuration.
///
/// # Kubo Equivalent
///
/// Corresponds to `core/corehttp/corehttp.go` server configuration.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiServerConfig {
    /// Listen address
    #[serde(rename = "Address")]
    pub address: String,

    /// Enable CORS
    #[serde(rename = "EnableCORS")]
    pub enable_cors: bool,

    /// Allowed origins for CORS
    #[serde(rename = "AllowedOrigins")]
    pub allowed_origins: Vec<String>,

    /// API timeout in seconds
    #[serde(rename = "Timeout")]
    pub timeout: u64,

    /// Maximum request body size
    #[serde(rename = "MaxBodySize")]
    pub max_body_size: u64,

    /// Enable authentication
    #[serde(rename = "EnableAuth")]
    pub enable_auth: bool,
}

impl Default for ApiServerConfig {
    fn default() -> Self {
        Self {
            address: DEFAULT_API_ADDRESS.to_string(),
            enable_cors: true,
            allowed_origins: vec!["*".to_string()],
            timeout: 60,
            max_body_size: 50 * 1024 * 1024, // 50MB default
            enable_auth: false,
        }
    }
}

impl ApiServerConfig {
    /// Create a new server config with the given address.
    pub fn new(address: &str) -> Self {
        Self {
            address: address.to_string(),
            ..Default::default()
        }
    }
}

/// API server statistics.
///
/// # Kubo Equivalent
///
/// Corresponds to API server metrics.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct ApiStats {
    /// Total requests received
    #[serde(rename = "TotalRequests")]
    pub total_requests: u64,

    /// Successful requests
    #[serde(rename = "SuccessfulRequests")]
    pub successful_requests: u64,

    /// Failed requests
    #[serde(rename = "FailedRequests")]
    pub failed_requests: u64,

    /// Total bytes received
    #[serde(rename = "BytesReceived")]
    pub bytes_received: u64,

    /// Total bytes sent
    #[serde(rename = "BytesSent")]
    pub bytes_sent: u64,

    /// Currently active connections
    #[serde(rename = "ActiveConnections")]
    pub active_connections: u32,

    /// Average response time in milliseconds
    #[serde(rename = "AvgResponseTimeMs")]
    pub avg_response_time_ms: f64,
}

impl ApiStats {
    /// Create new empty stats.
    pub fn new() -> Self {
        Self::default()
    }

    /// Record a request.
    pub fn record_request(&mut self, bytes_in: u64) {
        self.total_requests += 1;
        self.bytes_received += bytes_in;
    }

    /// Record a successful response.
    pub fn record_success(&mut self, bytes_out: u64, response_time_ms: f64) {
        self.successful_requests += 1;
        self.bytes_sent += bytes_out;
        // Update rolling average
        let total = self.successful_requests as f64;
        self.avg_response_time_ms =
            (self.avg_response_time_ms * (total - 1.0) + response_time_ms) / total;
    }

    /// Record a failed request.
    pub fn record_failure(&mut self) {
        self.failed_requests += 1;
    }
}

/// API endpoint listing result.
///
/// # Kubo Equivalent
///
/// Corresponds to `/api/v0/commands` output.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiCommandsResult {
    /// List of available commands/endpoints
    #[serde(rename = "Commands")]
    pub commands: Vec<ApiCommandInfo>,
}

/// Information about a single API command.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiCommandInfo {
    /// Command name
    #[serde(rename = "Name")]
    pub name: String,

    /// Full path to command
    #[serde(rename = "Path")]
    pub path: String,

    /// Subcommands
    #[serde(rename = "Subcommands", skip_serializing_if = "Vec::is_empty")]
    pub subcommands: Vec<ApiCommandInfo>,

    /// Options
    #[serde(rename = "Options", skip_serializing_if = "Vec::is_empty")]
    pub options: Vec<ApiOptionInfo>,
}

impl ApiCommandInfo {
    /// Create a new command info.
    pub fn new(name: &str, path: &str) -> Self {
        Self {
            name: name.to_string(),
            path: path.to_string(),
            subcommands: Vec::new(),
            options: Vec::new(),
        }
    }

    /// Add a subcommand.
    pub fn with_subcommand(mut self, subcmd: ApiCommandInfo) -> Self {
        self.subcommands.push(subcmd);
        self
    }

    /// Add an option.
    pub fn with_option(mut self, opt: ApiOptionInfo) -> Self {
        self.options.push(opt);
        self
    }
}

/// Information about a command option.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiOptionInfo {
    /// Option name
    #[serde(rename = "Name")]
    pub name: String,

    /// Option description
    #[serde(rename = "Description")]
    pub description: String,
}

impl ApiOptionInfo {
    /// Create a new option info.
    pub fn new(name: &str, description: &str) -> Self {
        Self {
            name: name.to_string(),
            description: description.to_string(),
        }
    }
}

/// API client for connecting to a running IPFS daemon.
///
/// # Kubo Equivalent
///
/// Corresponds to HTTP client functionality in `client/rpc/api.go`.
#[derive(Debug, Clone)]
pub struct ApiClient {
    /// Base URL of the API server
    pub base_url: String,

    /// Authentication token (if any)
    pub auth_token: Option<String>,

    /// Timeout in seconds
    pub timeout: u64,
}

impl ApiClient {
    /// Create a new API client.
    pub fn new(base_url: &str) -> Self {
        Self {
            base_url: base_url.trim_end_matches('/').to_string(),
            auth_token: None,
            timeout: 60,
        }
    }

    /// Create a client from the API file in a repo.
    pub fn from_repo(repo_path: &std::path::Path) -> Option<Self> {
        let api_file = repo_path.join("api");
        if api_file.exists() {
            let content = std::fs::read_to_string(&api_file).ok()?;
            let addr = content.trim();
            // Convert multiaddr to HTTP URL if needed
            let url = if addr.starts_with("/ip4/") || addr.starts_with("/ip6/") {
                multiaddr_to_url(addr)
            } else {
                addr.to_string()
            };
            Some(Self::new(&url))
        } else {
            None
        }
    }

    /// Set authentication token.
    pub fn with_auth(mut self, token: &str) -> Self {
        self.auth_token = Some(token.to_string());
        self
    }

    /// Set timeout.
    pub fn with_timeout(mut self, timeout: u64) -> Self {
        self.timeout = timeout;
        self
    }

    /// Build URL for an endpoint.
    pub fn url(&self, endpoint: &str) -> String {
        format!("{}/api/{}{}", self.base_url, API_VERSION, endpoint)
    }

    /// Check if the daemon is reachable.
    pub fn is_online(&self) -> bool {
        // In a full implementation, this would make an HTTP request
        // For now, we just check if the base_url is valid
        !self.base_url.is_empty()
    }
}

/// Convert a multiaddr to an HTTP URL.
fn multiaddr_to_url(addr: &str) -> String {
    // Parse multiaddr like /ip4/127.0.0.1/tcp/5001
    let parts: Vec<&str> = addr.split('/').filter(|s| !s.is_empty()).collect();

    let mut host = "127.0.0.1";
    let mut port = "5001";

    let mut i = 0;
    while i < parts.len() {
        match parts[i] {
            "ip4" | "ip6" => {
                if i + 1 < parts.len() {
                    host = parts[i + 1];
                    i += 2;
                } else {
                    i += 1;
                }
            }
            "tcp" => {
                if i + 1 < parts.len() {
                    port = parts[i + 1];
                    i += 2;
                } else {
                    i += 1;
                }
            }
            _ => i += 1,
        }
    }

    format!("http://{}:{}", host, port)
}

/// Result of API version query.
///
/// # Kubo Equivalent
///
/// Corresponds to `/api/v0/version` output.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ApiVersionResult {
    /// Version string
    #[serde(rename = "Version")]
    pub version: String,

    /// Commit hash
    #[serde(rename = "Commit")]
    pub commit: String,

    /// Repository version
    #[serde(rename = "Repo")]
    pub repo: String,

    /// System information
    #[serde(rename = "System")]
    pub system: String,

    /// Golang version (or Rust version for ferripfs)
    #[serde(rename = "Golang")]
    pub golang: String,
}

impl ApiVersionResult {
    /// Create version info for ferripfs.
    pub fn ferripfs() -> Self {
        Self {
            version: "0.1.0".to_string(),
            commit: "unknown".to_string(),
            repo: "18".to_string(),
            system: format!("{}/{}", std::env::consts::ARCH, std::env::consts::OS),
            golang: "rust".to_string(),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_agent_version() {
        assert!(AGENT_VERSION.starts_with("ferripfs/"));
    }

    #[test]
    fn test_api_request_building() {
        let req = ApiRequest::new("/id").with_arg("format", "json");

        let url = req.build_url("http://localhost:5001");
        assert!(url.contains("/api/v0/id"));
        assert!(url.contains("format=json"));
    }

    #[test]
    fn test_api_response() {
        let resp = ApiResponse::ok(b"test".to_vec());
        assert!(resp.is_success());
        assert_eq!(resp.body_string(), "test");

        let err = ApiResponse::error(500, "internal error", 1);
        assert!(!err.is_success());
        assert!(err.error.is_some());
    }

    #[test]
    fn test_multiaddr_to_url() {
        assert_eq!(
            multiaddr_to_url("/ip4/127.0.0.1/tcp/5001"),
            "http://127.0.0.1:5001"
        );
        assert_eq!(
            multiaddr_to_url("/ip4/0.0.0.0/tcp/8080"),
            "http://0.0.0.0:8080"
        );
    }

    #[test]
    fn test_api_stats() {
        let mut stats = ApiStats::new();
        stats.record_request(100);
        stats.record_success(200, 50.0);
        stats.record_failure();

        assert_eq!(stats.total_requests, 1);
        assert_eq!(stats.successful_requests, 1);
        assert_eq!(stats.failed_requests, 1);
        assert_eq!(stats.bytes_received, 100);
        assert_eq!(stats.bytes_sent, 200);
    }
}