sdk_common/docs/USAGE.md

📖 Guide d'Utilisation - sdk_common

Guide complet pour utiliser la bibliothèque commune sdk_common pour les Silent Payments.

🚀 Compilation et Build

1. Build de Développement

# Build de base
cargo build

# Build avec toutes les features
cargo build --all-features

# Build avec une feature spécifique
cargo build --features flate2

2. Build de Production

# Build optimisé
cargo build --release

# Build avec optimisations avancées
RUSTFLAGS="-C target-cpu=native" cargo build --release

# Build avec LTO
RUSTFLAGS="-C lto=fat" cargo build --release

🔧 Intégration dans les Projets

1. Intégration Rust

Dans Cargo.toml :

[dependencies]
sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", branch = "docker-support" }

# Avec features spécifiques
sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", features = ["flate2"] }

Utilisation dans le code :

use sdk_common::{
    types::{Process, Member, ValidationRule, ProcessState},
    traits::ProcessOperations,
    error::SdkError,
    compress_data, decompress_data
};

fn main() -> Result<(), SdkError> {
    // Créer un processus
    let process = Process {
        id: "process_123".to_string(),
        name: "Mon Processus".to_string(),
        device_id: "device_456".to_string(),
        state: ProcessState::Active,
        states: vec![ProcessState::Active],
        description: None,
        created_at: None,
        updated_at: None,
    };

    // Utiliser la compression
    let data = b"données à compresser";
    let compressed = compress_data(data)?;
    let decompressed = decompress_data(&compressed)?;

    // Valider le processus
    sdk_common::validate_process(&process)?;

    Ok(())
}

📦 Types et Structures

Types de Base

use sdk_common::{
    Process, ProcessState, Member, ValidationRule, ValidationRuleType
};

// Créer un état de processus
let state = ProcessState::Active;

// Créer un processus
let process = Process {
    id: "process_123".to_string(),
    name: "Mon Processus".to_string(),
    device_id: "device_456".to_string(),
    state: ProcessState::Active,
    states: vec![ProcessState::Active],
    description: Some("Description".to_string()),
    created_at: None,
    updated_at: None,
};

// Créer un membre
let member = Member {
    id: "member_123".to_string(),
    name: "John Doe".to_string(),
    public_key: "public_key_here".to_string(),
    process_id: "process_123".to_string(),
    roles: vec!["admin".to_string()],
    sp_addresses: Some(vec!["address1".to_string()]),
    created_at: None,
    updated_at: None,
};

// Créer une règle de validation
let rule = ValidationRule {
    id: "rule_123".to_string(),
    field_name: "amount".to_string(),
    rule_type: ValidationRuleType::Range,
    parameters: Some(serde_json::json!({"min": 0, "max": 1000})),
    role_id: "admin".to_string(),
    quorum: Some(2),
    created_at: None,
    updated_at: None,
};

🔄 Compression et Sérialisation

Compression avec flate2

use sdk_common::{compress_data, decompress_data};

// Compression
let original_data = b"données importantes à compresser";
let compressed = compress_data(original_data)?;

// Décompression
let decompressed = decompress_data(&compressed)?;
assert_eq!(original_data, decompressed.as_slice());

Sérialisation JSON

use sdk_common::{serialize_process, deserialize_process};

// Sérialisation
let json = serialize_process(&process)?;

// Désérialisation
let deserialized_process = deserialize_process(&json)?;

✅ Validation

Validation des Structures

use sdk_common::{validate_process, validate_member};

// Valider un processus
validate_process(&process)?;

// Valider un membre
validate_member(&member)?;

Validation Personnalisée

use sdk_common::ValidationError;

fn validate_custom_process(process: &Process) -> Result<(), ValidationError> {
    if process.name.is_empty() {
        return Err(ValidationError::InvalidProcess("Name cannot be empty".to_string()));
    }

    if process.device_id.is_empty() {
        return Err(ValidationError::InvalidProcess("Device ID cannot be empty".to_string()));
    }

    Ok(())
}

🧪 Tests et Validation

Tests Unitaires

#[cfg(test)]
mod tests {
    use super::*;
    use sdk_common::{Process, ProcessState, validate_process};

    #[test]
    fn test_process_validation() {
        let process = Process {
            id: "test_123".to_string(),
            name: "Test Process".to_string(),
            device_id: "device_123".to_string(),
            state: ProcessState::Active,
            states: vec![ProcessState::Active],
            description: None,
            created_at: None,
            updated_at: None,
        };

        assert!(validate_process(&process).is_ok());
    }

    #[test]
    fn test_compression() {
        let data = b"test data for compression";
        let compressed = compress_data(data).unwrap();
        let decompressed = decompress_data(&compressed).unwrap();

        assert_eq!(data, decompressed.as_slice());
    }
}

Tests d'Intégration

// tests/integration_test.rs
use sdk_common::{Process, Member, ValidationRule};

#[test]
fn test_process_member_integration() {
    let process = Process { /* ... */ };
    let member = Member { /* ... */ };

    // Test d'intégration entre processus et membre
    assert_eq!(member.process_id, process.id);
}

🔧 Configuration

Features Cargo

[dependencies]
sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", features = ["flate2"] }

Variables d'Environnement

# Niveau de log
export RUST_LOG=debug

# Configuration de compression
export COMPRESSION_LEVEL=6

🚨 Gestion des Erreurs

Types d'Erreurs

use sdk_common::{
    SdkError, ValidationError, SerializationError, CompressionError
};

fn handle_errors() -> Result<(), SdkError> {
    match some_operation() {
        Ok(result) => Ok(result),
        Err(SdkError::Validation(ValidationError::InvalidProcess(msg))) => {
            eprintln!("Erreur de validation: {}", msg);
            Err(SdkError::Validation(ValidationError::InvalidProcess(msg)))
        },
        Err(SdkError::Compression(CompressionError::CompressionFailed(msg))) => {
            eprintln!("Erreur de compression: {}", msg);
            Err(SdkError::Compression(CompressionError::CompressionFailed(msg)))
        },
        Err(e) => Err(e),
    }
}

Gestion des Erreurs avec ?

fn process_data() -> Result<(), SdkError> {
    let data = b"données à traiter";

    // Compression avec gestion d'erreur automatique
    let compressed = compress_data(data)?;

    // Validation avec gestion d'erreur automatique
    let process = create_process()?;
    validate_process(&process)?;

    Ok(())
}

📊 Performance

Optimisations

// Utilisation de références pour éviter les copies
fn process_large_data(data: &[u8]) -> Result<Vec<u8>, SdkError> {
    compress_data(data)
}

// Utilisation de Vec avec capacité pré-allouée
fn create_process_list(count: usize) -> Vec<Process> {
    let mut processes = Vec::with_capacity(count);
    // ... remplir la liste
    processes
}

Benchmarks

# Tests de performance
cargo bench

# Tests de compression
cargo test compression_benchmark

🔒 Sécurité

Bonnes Pratiques

// Validation systématique des entrées
fn create_secure_process(name: &str, device_id: &str) -> Result<Process, SdkError> {
    if name.is_empty() || device_id.is_empty() {
        return Err(SdkError::InvalidInput("Name and device_id cannot be empty".to_string()));
    }

    let process = Process {
        id: generate_secure_id(),
        name: name.to_string(),
        device_id: device_id.to_string(),
        state: ProcessState::Active,
        states: vec![ProcessState::Active],
        description: None,
        created_at: None,
        updated_at: None,
    };

    validate_process(&process)?;
    Ok(process)
}

// Gestion sécurisée des erreurs
fn handle_sensitive_data(data: &[u8]) -> Result<(), SdkError> {
    // Ne pas exposer les données sensibles dans les logs
    let compressed = compress_data(data).map_err(|e| {
        log::error!("Compression failed: {}", e);
        SdkError::Internal("Compression failed".to_string())
    })?;

    Ok(())
}

🛠️ Développement

Workflow de Développement

# 1. Cloner le projet
git clone https://git.4nkweb.com/4nk/sdk_common.git
cd sdk_common

# 2. Installer les dépendances
cargo build

# 3. Lancer les tests
cargo test

# 4. Vérifier le code
cargo clippy -- -D warnings
cargo fmt -- --check

# 5. Générer la documentation
cargo doc --open

Debugging

// Utilisation de logs pour le debugging
use log::{debug, info, warn, error};

fn debug_process(process: &Process) {
    debug!("Processing process: {:?}", process);

    match validate_process(process) {
        Ok(()) => info!("Process validation successful"),
        Err(e) => warn!("Process validation failed: {:?}", e),
    }
}

📚 Ressources Additionnelles

Documentation

• API Reference - Documentation complète des APIs
• Architecture - Architecture technique détaillée
• Configuration - Guide de configuration
• Tests - Stratégies de tests

Exemples

• Exemples de base - Exemples d'utilisation
• Tests d'intégration - Tests complets
• Benchmarks - Tests de performance

---

📖 Guide d'utilisation complet pour sdk_common - Bibliothèque commune pour les Silent Payments 🚀