# Délais limites des flux de travail

Un délai limite peut être défini pour les flux de travail. Si un flux en cours d’exécution n’est pas terminé dans la durée spécifiée, Queuety le marque comme ayant échoué et peut appeler un gestionnaire. Les flux mis en pause ou en attente d’un signal ou d’autres flux ne sont pas expirés pendant cette attente. Les délais limites sont vérifiés environ une fois par minute par un processus `wp queuety work` de longue durée, et non par les workers `--once` ou le mécanisme de secours WP-Cron. Cela sert de dispositif de sécurité pour les flux de longue durée qui ne doivent pas s’exécuter indéfiniment.

## Définir un délai limite

Utilisez `must_complete_within()` sur le générateur de flux de travail pour définir la durée maximale autorisée. Utilisez `on_deadline()` pour enregistrer un gestionnaire exécuté lorsque le délai limite est dépassé.

```php
use Queuety\Queuety;

Queuety::workflow( 'data_import' )
    ->then( FetchDataHandler::class )
    ->then( TransformDataHandler::class )
    ->then( LoadDataHandler::class )
    ->must_complete_within( hours: 24 )
    ->on_deadline( ImportTimeoutHandler::class )
    ->dispatch( [ 'source' => $url ] );
```

La méthode `must_complete_within()` accepte des paramètres nommés qui sont additionnés :

```php
->must_complete_within( hours: 2, minutes: 30 )  // 2.5 hours
->must_complete_within( days: 1 )                 // 24 hours
->must_complete_within( seconds: 3600 )           // 1 hour
->must_complete_within( days: 1, hours: 12 )      // 36 hours
```

## Gestionnaire de délai limite

La classe du gestionnaire `on_deadline()` doit implémenter une méthode `handle( array $state ): void`. Elle reçoit l’état public du flux de travail (toutes les clés qui ne commencent pas par `_`).

```php
class ImportTimeoutHandler {

    public function handle( array $state ): void {
        // Alert the team.
        wp_mail(
            'ops@example.com',
            'Import workflow timed out',
            'Workflow for source ' . ( $state['source'] ?? 'unknown' ) . ' exceeded its deadline.'
        );

        // Clean up partial work.
        if ( isset( $state['temp_file'] ) ) {
            unlink( $state['temp_file'] );
        }
    }
}
```

Le gestionnaire de délai limite est facultatif. Si vous voulez simplement que le flux échoue sans exécuter de logique personnalisée, utilisez `must_complete_within()` sans `on_deadline()`.

## Fonctionnement de la vérification des délais limites

Le worker vérifie les délais limites expirés toutes les 60 secondes dans le cadre de sa boucle de traitement. Lorsqu’il trouve un flux dont `status` est toujours `running` et dont `deadline_at` est passée, il appelle le gestionnaire `on_deadline` s’il en existe un, marque le flux comme ayant échoué avec le message d’erreur `Deadline exceeded` et consigne un événement de journal `workflow_deadline_exceeded`. Le délai limite lui-même est enregistré sous forme d’horodatage `deadline_at` sur la ligne du flux de travail et est calculé au moment de la mise en file à partir de la durée configurée.

## Conséquences de l’expiration

Lorsqu’un flux de travail dépasse son délai limite, son statut devient `failed`, le message d’erreur est défini sur `Deadline exceeded`, le gestionnaire de délai limite s’exécute de manière synchrone s’il est enregistré, et une entrée de journal `workflow_deadline_exceeded` est consignée. Les tâches en cours ne sont pas interrompues pendant leur exécution, mais le flux ne dépasse pas la limite de l’étape expirée. Si le gestionnaire de délai limite lève lui-même une exception, celle-ci est ignorée et le flux se termine tout de même en échec.

## Méthodes de WorkflowBuilder

| Méthode | Description |
|---|---|
| `must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | Définit la durée maximale autorisée. Tous les paramètres sont additionnés. |
| `on_deadline( string $handler_class )` | Enregistre un gestionnaire appelé lorsque le délai limite est dépassé. |

## Exemple : délai limite avec nouvelle tentative

Relancer un flux de travail qui a échoué à cause de son délai limite est rarement utile. `retry_workflow()` le réinitialise à `running` et remet l’étape en échec dans la file, mais n’efface ni ne prolonge le délai limite ; la prochaine vérification, dans environ une minute, le fera donc échouer à nouveau. Lancez plutôt un nouveau flux de travail.

```php
$status = Queuety::workflow_status( $workflow_id );

if ( 'failed' === $status->status->value ) {
    // Check if it was a deadline failure.
    // You may want to dispatch a new workflow instead of retrying.
    Queuety::retry_workflow( $workflow_id );
}
```

## Délai limite et pauses

Les délais limites s’appliquent à la durée totale du flux de travail. Les pauses (`->delay()`) suspendent le flux pendant une durée fixe, dans le cadre de sa séquence d’étapes. Un flux avec une pause d’une heure et un délai limite de deux heures échouera si les étapes hors pause prennent plus d’une heure au total.