3e3716411b
- Correction de l'API.md : Suppression des APIs Bitcoin Core, ajout des vraies APIs sdk_common - Correction du USAGE.md : Suppression des références WASM/npm inexistantes - Mise à jour de l'INDEX.md : Suppression des liens vers fichiers inexistants
430 lines
9.6 KiB
Markdown
430 lines
9.6 KiB
Markdown
# 📖 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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` :**
|
|
|
|
```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 :**
|
|
|
|
```rust
|
|
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
|
|
|
|
```rust
|
|
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
|
|
|
|
```rust
|
|
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
|
|
|
|
```rust
|
|
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
|
|
|
|
```rust
|
|
use sdk_common::{validate_process, validate_member};
|
|
|
|
// Valider un processus
|
|
validate_process(&process)?;
|
|
|
|
// Valider un membre
|
|
validate_member(&member)?;
|
|
```
|
|
|
|
### Validation Personnalisée
|
|
|
|
```rust
|
|
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
|
|
|
|
```rust
|
|
#[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
|
|
|
|
```rust
|
|
// 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
|
|
|
|
```toml
|
|
[dependencies]
|
|
sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", features = ["flate2"] }
|
|
```
|
|
|
|
### Variables d'Environnement
|
|
|
|
```bash
|
|
# Niveau de log
|
|
export RUST_LOG=debug
|
|
|
|
# Configuration de compression
|
|
export COMPRESSION_LEVEL=6
|
|
```
|
|
|
|
## 🚨 Gestion des Erreurs
|
|
|
|
### Types d'Erreurs
|
|
|
|
```rust
|
|
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 `?`
|
|
|
|
```rust
|
|
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
|
|
|
|
```rust
|
|
// 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
|
|
|
|
```bash
|
|
# Tests de performance
|
|
cargo bench
|
|
|
|
# Tests de compression
|
|
cargo test compression_benchmark
|
|
```
|
|
|
|
## 🔒 Sécurité
|
|
|
|
### Bonnes Pratiques
|
|
|
|
```rust
|
|
// 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```rust
|
|
// 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](API.md) - Documentation complète des APIs
|
|
- [Architecture](ARCHITECTURE.md) - Architecture technique détaillée
|
|
- [Configuration](CONFIGURATION.md) - Guide de configuration
|
|
- [Tests](TESTING.md) - Stratégies de tests
|
|
|
|
### Exemples
|
|
|
|
- [Exemples de base](../examples/) - Exemples d'utilisation
|
|
- [Tests d'intégration](../tests/) - Tests complets
|
|
- [Benchmarks](../benches/) - Tests de performance
|
|
|
|
---
|
|
|
|
**📖 Guide d'utilisation complet pour sdk_common - Bibliothèque commune pour les Silent Payments** 🚀
|
|
|
|
|