# Workflowdeadlines

Je kunt een deadline instellen voor workflows. Als een actieve workflow niet binnen de opgegeven tijd is voltooid, markeert Queuety deze als mislukt en roept eventueel een handler aan. Workflows die zijn gepauzeerd of wachten op een signaal of andere workflows, verlopen niet terwijl ze wachten. Deadlines worden ongeveer eens per minuut gecontroleerd door een langlopend proces `wp queuety work`, niet door `--once`-workers of de terugvaloptie WP-Cron. Dit fungeert als een dodemansknop voor langlopende workflows die niet eindeloos mogen doorlopen.

## Een deadline instellen

Gebruik `must_complete_within()` in de workflowbuilder om de maximaal toegestane duur in te stellen. Gebruik `on_deadline()` om een handler te registreren die wordt uitgevoerd wanneer de deadline wordt overschreden.

```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 ] );
```

De methode `must_complete_within()` accepteert benoemde parameters die bij elkaar worden opgeteld:

```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
```

## Deadlinehandler

De handlerklasse `on_deadline()` moet een methode `handle( array $state ): void` implementeren. Deze ontvangt de openbare workflowstatus (alle sleutels die niet beginnen met `_`).

```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'] );
        }
    }
}
```

De deadlinehandler is optioneel. Als je alleen wilt dat de workflow mislukt zonder aangepaste logica uit te voeren, gebruik je `must_complete_within()` zonder `on_deadline()`.

## Hoe deadlinecontrole werkt

De worker controleert elke 60 seconden op verlopen deadlines als onderdeel van de verwerkingslus. Wanneer deze een workflow vindt waarvan `status` nog steeds `running` is en waarvan `deadline_at` in het verleden ligt, roept deze de handler `on_deadline` aan als die is geregistreerd, markeert de workflow als mislukt met het foutbericht `Deadline exceeded` en registreert een logboekgebeurtenis `workflow_deadline_exceeded`. De deadline zelf wordt opgeslagen als een tijdstempel `deadline_at` op de workflowrij en wordt bij verzending berekend op basis van de ingestelde duur.

## Wat gebeurt er bij het verlopen

Wanneer een workflow de deadline overschrijdt, verandert de status in `failed`, wordt het foutbericht ingesteld op `Deadline exceeded`, wordt de deadlinehandler synchroon uitgevoerd als die is geregistreerd en wordt een logboekvermelding `workflow_deadline_exceeded` vastgelegd. Taken die worden uitgevoerd, worden niet halverwege onderbroken, maar de workflow gaat niet verder dan de grens van de verlopen stap. Als de deadlinehandler zelf een uitzondering gooit, wordt die stilzwijgend opgevangen en eindigt de workflow alsnog als mislukt.

## Methoden van WorkflowBuilder

| Methode | Beschrijving |
|---|---|
| `must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | Stelt de maximaal toegestane duur in. Alle parameters worden opgeteld. |
| `on_deadline( string $handler_class )` | Registreert een handler die wordt aangeroepen wanneer de deadline wordt overschreden. |

## Voorbeeld: deadline met nieuwe poging

Opnieuw proberen met een workflow die door de deadline is mislukt, is zelden nuttig. `retry_workflow()` zet de status terug naar `running` en zet de mislukte stap opnieuw in de wachtrij, maar wist of verlengt de deadline niet. De volgende deadlinecontrole, binnen ongeveer een minuut, laat de workflow dus opnieuw mislukken. Verzend in plaats daarvan een nieuwe workflow.

```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 );
}
```

## Deadline versus slaapvertragingen

Deadlines gelden voor de volledige workflowduur. Slaapvertragingen (`->delay()`) pauzeren de workflow gedurende een vaste tijd als onderdeel van de stappenreeks. Een workflow met een slaapvertraging van 1 hour en een deadline van 2 hours mislukt als de niet-slaapstappen in totaal meer dan 1 hour duren.