README

Une bibliothèque PHP légère pour implémenter le pattern Saga et gérer les transactions distribuées.

SagaLite permet de coordonner des opérations complexes en séquences d'étapes compensables, garantissant la cohérence des données même en cas d'échec partiel.

📋 Description

Le pattern Saga divise une transaction longue en une séquence d'étapes plus petites. Chaque étape possède une action principale et une action de compensation. Si une étape échoue, toutes les étapes précédentes sont automatiquement annulées via leurs compensations.

Cas d'usage typiques :

• Processus de commande e-commerce (réservation stock → paiement → expédition)
• Onboarding utilisateur (création compte → envoi email → activation)
• Intégrations entre microservices
• Workflows métier complexes

🎯 Pourquoi Sagalite ?

• 🪶 Léger : Aucune dépendance externe, focalisé sur l'essentiel
• 🔒 Fiable : Garantit la cohérence des données avec compensation automatique
• 🎮 Simple : API intuitive, démarrage en quelques lignes
• 🔧 Flexible : Support de handlers personnalisés et injection de dépendances
• 📊 Traçable : Journalisation complète des exécutions pour le debugging
• ⚡ Performant : Stockage optimisé avec verrouillage pessimiste
• 🧪 Testé : Suite de tests complète avec 98%+ de couverture

📦 Installation

composer require pixelee/sagalite

Prérequis :

• PHP 8.2+
• Extension PDO (SQLite, MySQL, PostgreSQL...)

🗄️ Initialisation de la base de données

Création des tables

SagaLite nécessite des tables spécifiques pour persister l'état des sagas. Pour cela, créer les tables nécessaires à partir du fichier migrations/001_init.sql fourni.

🚀 Utilisation rapide

Configuration basique

use Pixelee\SagaLite\Core\SagaManager;
use Pixelee\SagaLite\Persistence\PdoSagaStateStore;

// Configuration de la base de données
$pdo = new PDO('sqlite:saga.db');
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

// Lecture et exécution du script de migration
// $migrationSql = file_get_contents(__DIR__ . '/migrations/001_init.sql');
// $pdo->exec($migrationSql);

// Initialisation du store et manager
$store = new PdoSagaStateStore($pdo);
$manager = new SagaManager($store);

Définition d'un handler

use Pixelee\SagaLite\StepHandler;
use Pixelee\SagaLite\Context;

final class CreateUser implements StepHandler
{
    public function __construct(
        private Users $users
    ) {
    }

    public function handle(Context $context): Context
    {
        // Vérification idempotente - évite la re-création
        if ($context->get('user_created', false)) {
            return $context;
        }
        
        // Création de l'utilisateur avec les données du contexte
        $userId = $this->users->create(
            $context->get('email')
        );

        // Mise à jour du contexte avec le résultat
        return $context
            ->with('user_created', true) // Flag indiquant que l'action est faite
            ->with('user_id', $userId); // ID utilisable dans les étapes suivantes
    }

    public function compensate(Context $context): Context
    {
        // Annulation seulement si l'action a été faite
        if ($context->get('user_created', false)) {
            $this->users->deactivate(
                $context->get('user_id')
            );

            return $context->with('user_created', false);
        }

        return $context;
    }
}

Définition d'une saga

use Pixelee\SagaLite\SagaDefinition;
use Pixelee\SagaLite\StepDefinition;
use Pixelee\SagaLite\StepPolicy;

// Définition de la séquence d'étapes
$saga = new SagaDefinition('user_onboarding', [
    new StepDefinition(
        'create',                        // Nom de l'étape
        new CreateUser($users),          // Handler principal
        StepPolicy::retry([2, 5, 10])    // Policy de retry (2s, 5s, 10s)
    ),
    new StepDefinition('provision', new ProvisionStorage($storage)),
    new StepDefinition('welcome', new WelcomeMail($mailer)),
]);

Exécution automatique

try {
    // Exécution complète de toutes les étapes
    $result = $manager->execute(
        $saga, 
        new Context(['email' => 'alice@example.com']) // Contexte initial
    );
    
    echo "Saga terminée : " . $result->getId();
} catch (Exception $e) {
    // En cas d'échec, compensation automatique des étapes réussies
    echo "Échec avec compensation automatique : " . $e->getMessage();
}

Exécution manuelle étape par étape

// Configuration du loader pour l'injection de dépendances
$loader = function(string $handlerClass) {
    return match($handlerClass) {
        CreateUser::class => new CreateUser($users),
        ProvisionStorage::class => new ProvisionStorage($storage),
        WelcomeMail::class => new WelcomeMail($mailer),
        default => throw new Exception("Handler inconnu : $handlerClass")
    };
};

// Démarrage de la saga
$sagaId = $manager->start($saga, new Context(['email' => 'alice@example.com']));

// Exécution contrôlée étape par étape
$manager->resume($sagaId, $loader); // étape 0: create
$manager->resume($sagaId, $loader); // étape 1: provision  
$manager->resume($sagaId, $loader); // étape 2: welcome -> COMPLETED

Policies avancées

// Policy de retry avec backoff exponentiel
$exponentialBackoff = StepPolicy::retry([1, 2, 4, 8, 16]);

// Timeout personnalisé
$withTimeout = StepPolicy::timeout(300); // 5 minutes

// Combinaison de policies (si supporté)
$criticalStep = new StepDefinition(
    'critical-operation',
    new CriticalHandler(),
    $exponentialBackoff
);

🔧 Configuration avancée

Configuration du store

$store = new PdoSagaStateStore($pdo, [
    'table_prefix' => 'my_saga_',       // Préfixe des tables
    'enable_logging' => true,           // Activer les logs détaillés
    'lock_timeout' => 300,              // Timeout de verrouillage
    'cleanup_completed_after' => 7200   // Nettoyage après 2h
]);

❌ Ce qu'il ne faut PAS faire

🚫 Handlers non-idempotents

// MAUVAIS : peut créer des doublons à chaque retry
final class BadHandler implements StepHandler
{
    public function handle(Context $context): Context
    {
        $this->db->insert('logs', ['action' => 'done']); // Pas de vérification !
        return $context;
    }
}

// BON : idempotent avec flag de vérification
final class GoodHandler implements StepHandler
{
    public function handle(Context $context): Context
    {
        if ($context->get('action_done', false)) {
            return $context; // Action déjà effectuée
        }
        
        $this->db->insert('logs', ['saga_id' => $context->getSagaId()]);
        return $context->with('action_done', true);
    }
}

🚫 Modification d'état externe sans flag

// MAUVAIS : pas de trace dans le contexte
public function handle(Context $context): Context
{
    $this->externalService->updateStatus($context->get('user_id'), 'active');
    return $context; // Pas de flag !
}

// BON : toujours marquer les actions
public function handle(Context $context): Context
{
    if (!$context->get('external_updated', false)) {
        $this->externalService->updateStatus($context->get('user_id'), 'active');
    }
    return $context->with('external_updated', true);
}

🚫 Compensation destructrice

// MAUVAIS : suppression définitive des données
public function compensate(Context $context): Context
{
    $this->users->delete($context->get('user_id')); // Perte de données !
    return $context;
}

// BON : désactivation réversible
public function compensate(Context $context): Context
{
    if ($context->get('user_created', false)) {
        $this->users->markAsInactive($context->get('user_id'));
        return $context->with('user_created', false);
    }
    return $context;
}

🐛 Debugging

Inspection du contexte

// Vérifier l'état d'une saga
$state = $store->load($sagaId);
$context = $state->getContext();

echo "Données actuelles :\n";
foreach ($context->all() as $key => $value) {
    echo "  {$key}: " . json_encode($value) . "\n";
}

Vérification des flags

// Dans un handler, vérifier l'état précédent
public function handle(Context $context): Context
{
    echo "État actuel du contexte :\n";
    echo "- user_created: " . ($context->get('user_created', false) ? 'oui' : 'non') . "\n";
    echo "- user_id: " . $context->get('user_id', 'non défini') . "\n";
    
    // ... logique métier
}