Workflow-Fristen

Als Markdown anzeigen Auf GitHub bearbeiten Dokumentation zu 2cc7b2b

Für Workflows kann eine Frist festgelegt werden. Wenn ein laufender Workflow nicht innerhalb der vorgegebenen Dauer abgeschlossen wird, markiert Queuety ihn als fehlgeschlagen und ruft optional einen Handler auf. Während sie pausiert sind oder auf ein Signal oder andere Workflows warten, laufen die Fristen für Workflows nicht ab. Ein lang laufender wp queuety work-Prozess prüft etwa einmal pro Minute die Fristen, nicht die Worker --once oder der WP-Cron-Fallback. So fungiert die Frist als Sicherheitsmechanismus für lang laufende Workflows, die nicht unbegrenzt laufen sollen.

Eine Frist festlegen

Verwende must_complete_within() im Workflow-Builder, um die maximal zulässige Dauer festzulegen. Mit on_deadline() registrierst du einen Handler, der bei Überschreitung der Frist ausgeführt wird.

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

Die Methode must_complete_within() akzeptiert benannte Parameter, die addiert werden:

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

Fristenhandler

Die Handler-Klasse für Fristen on_deadline() muss eine handle( array $state ): void-Methode implementieren. Sie erhält den öffentlichen Workflow-Zustand (alle Schlüssel, die nicht mit _ beginnen).

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

Der Fristenhandler ist optional. Wenn der Workflow nur fehlschlagen soll, ohne benutzerdefinierte Logik auszuführen, verwende must_complete_within() ohne on_deadline().

So funktioniert die Fristenprüfung

Der Worker prüft in seiner Verarbeitungsschleife alle 60 Sekunden auf abgelaufene Fristen. Findet er einen Workflow, dessen status weiterhin running ist und dessen deadline_at in der Vergangenheit liegt, ruft er den Handler on_deadline auf, sofern einer registriert ist, markiert den Workflow mit der Fehlermeldung Deadline exceeded als fehlgeschlagen und protokolliert ein Ereignis vom Typ workflow_deadline_exceeded. Die Frist selbst wird als Zeitstempel deadline_at in der Workflow-Zeile gespeichert und beim Start anhand der konfigurierten Dauer berechnet.

Was beim Fristablauf geschieht

Wenn ein Workflow seine Frist überschreitet, ändert sich sein Status zu failed, die Fehlermeldung wird auf Deadline exceeded gesetzt, der Fristen-Handler wird synchron ausgeführt, sofern einer registriert ist, und es wird ein workflow_deadline_exceeded-Protokolleintrag erfasst. Laufende Jobs werden nicht mitten in der Ausführung unterbrochen, aber der Workflow wird nicht über die abgelaufene Schrittgrenze hinaus fortgesetzt. Löst der Fristen-Handler selbst eine Ausnahme aus, wird diese stillschweigend abgefangen und der Workflow endet trotzdem im Fehlerstatus.

WorkflowBuilder-Methoden

Methode	Beschreibung
`must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	Legt die maximal zulässige Dauer fest. Alle Parameter werden addiert.
`on_deadline( string $handler_class )`	Registriert einen Handler, der aufgerufen wird, wenn die Frist überschritten ist.

Beispiel: Frist mit Wiederholung

Einen Workflow erneut auszuführen, der wegen Fristüberschreitung fehlgeschlagen ist, ist selten sinnvoll. retry_workflow() setzt ihn auf running zurück und reiht den fehlgeschlagenen Schritt erneut ein, löscht oder verlängert aber nicht die Frist. Daher schlägt der Workflow bei der nächsten Fristenprüfung innerhalb von etwa einer Minute erneut fehl. Starte stattdessen einen neuen 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 );
}

Fristen und Wartezeiten im Vergleich

Fristen gelten für die gesamte Workflow-Dauer. Wartezeiten (->delay()) pausieren den Workflow für eine festgelegte Dauer innerhalb der Schrittfolge. Ein Workflow mit einer Wartezeit von 1 Stunde und einer Frist von 2 Stunden schlägt fehl, wenn die Schritte ohne Wartezeit insgesamt mehr als 1 Stunde dauern.