Skip to content
2 changes: 1 addition & 1 deletion docs/configuration/microservices.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,4 +131,4 @@ php artisan queue:work shared --queue=workflows
php artisan queue:work shared --queue=activities
```

App A's worker replays workflows and schedules activity tasks. App B's worker picks up those activity tasks, executes them, and returns results. The engine handles the handoff through the shared database.
App A's worker replays workflows and schedules activity tasks. Set its job timeout as described in [Worker timeout](/docs/installation/#worker-timeout). App B's worker picks up those activity tasks, executes them, and returns results. The engine handles the handoff through the shared database.
40 changes: 40 additions & 0 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,3 +62,43 @@ php artisan migrate
## Running Workers

Durable Workflow uses queues to run workflows and activities in the background. You will need to either run the `queue:work` [command](https://laravel.com/docs/12.x/queues#the-queue-work-command) or use [Horizon](https://laravel.com/docs/12.x/horizon) to run your queue workers. Without a queue worker, workflows and activities will not be processed. To run workflows and activities in parallel, you will need more than one queue worker.

### Worker timeout {#worker-timeout}

When PHP has the `pcntl` extension, a queue worker kills any job that runs longer than its timeout: the worker's `--timeout`, 60 seconds by default, unless the job sets its own. A workflow task that is killed is rolled back. It is retried only after its lease expires (`workflows.v2.workflow_task_lease_seconds`, 300 seconds by default) and is counted as a lost lease, and the retry repeats the same work. A workflow task that always needs longer than the timeout, such as one that schedules or finishes a wide `all()`, never completes.

Three settings must line up:

- The **timeout of the workers that run workflow tasks** must cover your longest workflow task. A killed workflow task waits out the rest of its lease before it is retried.
- The queue connection's **`retry_after`** must exceed the timeout of every job on it, as Laravel requires. Otherwise the queue hands a job that is still running to a second worker.
- **Activities** should keep a bounded timeout, so that a hung activity cannot hold a worker forever. Do not use `--timeout=0`.

To give activities a shorter timeout than workflow tasks, run them on their own queue with their own workers. Activities run on their workflow's connection and queue unless the activity class sets `$connection` or `$queue`, or the workflow passes `ActivityOptions`.

```php
// config/queue.php
'redis' => [
'driver' => 'redis',
'connection' => 'default',
'queue' => 'default',
'retry_after' => 330, // above the workflow task workers' timeout
],
```

```php
use Workflow\V2\Activity;

final class ChargeCardActivity extends Activity
{
public ?string $queue = 'activities';
}
```

```bash
php artisan queue:work redis --queue=default --timeout=300 # workflow tasks
php artisan queue:work redis --queue=activities --timeout=60 # activities
```

In Horizon, each supervisor's `timeout` option is the worker timeout.

Workflow 2.34.0 adds `DW_V2_WORKFLOW_TASK_JOB_TIMEOUT_SECONDS`, unset by default. When it is set, every workflow task job carries that timeout, kept 10 seconds below its connection's `retry_after`, and workers use it in place of their own timeout for those jobs, so workflow tasks and activities can share workers. From that release, a worker that serves the workflow queue logs a warning at start when the timeout its workflow tasks run under is below the workflow task lease.
2 changes: 2 additions & 0 deletions docs/laravel-adoption.md
Original file line number Diff line number Diff line change
Expand Up @@ -298,6 +298,8 @@ Run the Laravel queue worker exactly as an embedded deployment requires:
php artisan queue:work redis --queue=orders
```

Set this worker's job timeout as described in [Worker timeout](/docs/installation/#worker-timeout).

Use the embedded fake through the same application action. It executes ready
workflow tasks inline and records activity dispatches:

Expand Down
2 changes: 2 additions & 0 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -454,6 +454,8 @@ php artisan migrate
php artisan queue:work
```

Before running wide fan-outs, set the worker's job timeout as described in [Worker timeout](/docs/installation/#worker-timeout).

When you want the operator UI inside that same Laravel application, add the
qualified embedded Waterline Composer package:

Expand Down
2 changes: 2 additions & 0 deletions docs/sample-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,8 @@ Start the queue worker. This will enable the processing of workflows and activit
php artisan queue:work
```

In your own application, set the worker's job timeout as described in [Worker timeout](/docs/installation/#worker-timeout).

When you want to prove the repair loop itself without waiting for a busy queue worker to hit another `Looping` cycle, run one explicit recovery sweep from a second terminal:

```bash
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,8 @@ php artisan queue:work shared --queue=activities
```

Der Worker von Anwendung A spielt Workflows erneut ab und plant
Aktivitätsaufgaben ein. Der Worker von Anwendung B übernimmt diese Aufgaben,
führt sie aus und gibt Ergebnisse zurück. Die Engine wickelt die Übergabe
über die gemeinsame Datenbank ab.
Aktivitätsaufgaben ein. Legen Sie sein Job-Timeout wie unter
[Worker-Timeout](/docs/installation/#worker-timeout) beschrieben fest. Der
Worker von Anwendung B übernimmt diese Aufgaben, führt sie aus und gibt
Ergebnisse zurück. Die Engine wickelt die Übergabe über die gemeinsame Datenbank
ab.
40 changes: 40 additions & 0 deletions i18n/de/docusaurus-plugin-content-docs/current/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,3 +54,43 @@ php artisan migrate
## Worker ausführen {#running-workers}

Durable Workflow führt Workflows und Aktivitäten im Hintergrund über Warteschlangen aus. Starten Sie Queue-Worker mit dem [Befehl `queue:work`](https://laravel.com/docs/12.x/queues#the-queue-work-command) oder mit [Horizon](https://laravel.com/docs/12.x/horizon). Ohne Queue-Worker werden Workflows und Aktivitäten nicht verarbeitet. Für parallele Ausführung benötigen Sie mehr als einen Queue-Worker.

### Worker-Timeout {#worker-timeout}

Wenn PHP die Erweiterung `pcntl` hat, beendet ein Queue-Worker jeden Job, der länger als sein Timeout läuft: das `--timeout` des Workers, standardmäßig 60 Sekunden, sofern der Job kein eigenes festlegt. Eine so beendete Workflow-Aufgabe wird zurückgerollt. Sie wird erst nach Ablauf ihrer Lease erneut versucht (`workflows.v2.workflow_task_lease_seconds`, standardmäßig 300 Sekunden) und als verlorene Lease gezählt, und der neue Versuch wiederholt dieselbe Arbeit. Eine Workflow-Aufgabe, die immer länger als das Timeout braucht, etwa eine, die ein breites `all()` plant oder abschließt, wird nie abgeschlossen.

Drei Einstellungen müssen zusammenpassen:

- Das **Timeout der Worker, die Workflow-Aufgaben ausführen**, muss Ihre längste Workflow-Aufgabe abdecken. Eine beendete Workflow-Aufgabe wartet den Rest ihrer Lease ab, bevor sie erneut versucht wird.
- **`retry_after`** der Queue-Verbindung muss das Timeout jedes Jobs auf dieser Verbindung übersteigen, wie Laravel es verlangt. Andernfalls übergibt die Queue einen noch laufenden Job an einen zweiten Worker.
- **Aktivitäten** sollten ein begrenztes Timeout behalten, damit eine hängende Aktivität einen Worker nicht für immer blockieren kann. Verwenden Sie nicht `--timeout=0`.

Damit Aktivitäten ein kürzeres Timeout als Workflow-Aufgaben erhalten, führen Sie sie auf einer eigenen Queue mit eigenen Workern aus. Aktivitäten laufen auf der Verbindung und Queue ihres Workflows, es sei denn, die Aktivitätsklasse legt `$connection` oder `$queue` fest oder der Workflow übergibt `ActivityOptions`.

```php
// config/queue.php
'redis' => [
'driver' => 'redis',
'connection' => 'default',
'queue' => 'default',
'retry_after' => 330, // above the workflow task workers' timeout
],
```

```php
use Workflow\V2\Activity;

final class ChargeCardActivity extends Activity
{
public ?string $queue = 'activities';
}
```

```bash
php artisan queue:work redis --queue=default --timeout=300 # workflow tasks
php artisan queue:work redis --queue=activities --timeout=60 # activities
```

In Horizon ist die Option `timeout` jedes Supervisors das Worker-Timeout.

Workflow 2.34.0 fügt `DW_V2_WORKFLOW_TASK_JOB_TIMEOUT_SECONDS` hinzu, das standardmäßig nicht gesetzt ist. Ist es gesetzt, trägt jeder Job einer Workflow-Aufgabe dieses Timeout, mindestens 10 Sekunden unter dem `retry_after` seiner Verbindung gehalten, und Worker verwenden es für diese Jobs anstelle ihres eigenen Timeouts, sodass sich Workflow-Aufgaben und Aktivitäten Worker teilen können. Ab diesem Release protokolliert ein Worker, der die Workflow-Queue bedient, beim Start eine Warnung, wenn das Timeout, unter dem seine Workflow-Aufgaben laufen, unter der Lease der Workflow-Aufgabe liegt.
Original file line number Diff line number Diff line change
Expand Up @@ -268,6 +268,8 @@ Starten Sie den Laravel-Warteschlangen-Worker so, wie es eine eingebettete Berei
php artisan queue:work redis --queue=orders
```

Legen Sie das Job-Timeout dieses Workers wie unter [Worker-Timeout](/docs/installation/#worker-timeout) beschrieben fest.

Verwenden Sie den eingebetteten Fake über dieselbe Anwendungsaktion. Er führt bereite Workflow-Aufgaben direkt aus und zeichnet Aktivitätszuteilungen auf:

<!-- docs-example id="laravel.adoption.v2-embedded.fake" -->
Expand Down
2 changes: 2 additions & 0 deletions i18n/de/docusaurus-plugin-content-docs/current/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -422,6 +422,8 @@ php artisan migrate
php artisan queue:work
```

Bevor Sie breite Fan-outs ausführen, legen Sie das Job-Timeout des Workers wie unter [Worker-Timeout](/docs/installation/#worker-timeout) beschrieben fest.

Für die Betriebsoberfläche in derselben Laravel-Anwendung installieren Sie das qualifizierte eingebettete Waterline-Composer-Paket:

```bash
Expand Down
2 changes: 2 additions & 0 deletions i18n/de/docusaurus-plugin-content-docs/current/sample-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,8 @@ Starten Sie den Warteschlangen-Worker. Damit werden Workflows und Aktivitäten v
php artisan queue:work
```

Legen Sie in Ihrer eigenen Anwendung das Job-Timeout des Workers wie unter [Worker-Timeout](/docs/installation/#worker-timeout) beschrieben fest.

Wenn Sie die Reparaturschleife selbst nachweisen möchten, ohne auf einen weiteren `Looping`-Zyklus eines beschäftigten Warteschlangen-Workers zu warten, starten Sie in einem zweiten Terminal einen expliziten Wiederherstellungsdurchlauf:

```bash
Expand Down
10 changes: 5 additions & 5 deletions i18n/de/source-hashes.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"configuration/customization-matrix.md": "3d115863eaee7852b541bcd01615f424cc19c5847c7cd7d75e5ae63bc3f5cc78",
"configuration/database-connection.md": "cc83ae77133236309506fa44d39bfd0c939c32a6154c0bd6099bc64c83bdaec9",
"configuration/ensuring-same-server.md": "6c665f37cc198c7b1a775a60a94aab5ff4e55383385e76f1834c7840559b512a",
"configuration/microservices.md": "46dc4afa07588b78829a7e3d259177ce0cf40861f0e31b88dbb6de3a83aa5488",
"configuration/microservices.md": "7421f8f18b62bc326601e2670ba15ba45fb02056da0d70e94ef89b3870f79cb0",
"configuration/options.md": "d5079c5059aaa1072693ac09b3b8ea2be9176279820459370e5ebe6660d9f43b",
"configuration/pruning-workflows.md": "6f6ee2be3bd185ffec764e86c3ed3cbd40c45f75d28671b4cd11226493e11afb",
"configuration/publishing-config.md": "c757acd749c0d2696a6e19484249c9298dd15970ce0cf2ae0e6d2dfd82c8b6d6",
Expand Down Expand Up @@ -60,9 +60,9 @@
"features/webhooks.md": "edcdfc05ccb0d34a77c51594f85bc3cab343e787f8e0e08d2cd4ddebd048e8c8",
"features/worker-sessions.md": "5065368fb5b93599dbd08d97cb9ac312576eb42fee14f081db663aa9f78fb68c",
"how-it-works.md": "90454c37f4244297d5c11bcc59549859acf59f88d15ecd26f0a6951c115f86eb",
"installation.md": "895d390a17a71f4846223c4637ed1e70adf1221ba99d6b422ce1a5480c2f167b",
"installation.md": "8b2599dd58cda5a455c7df1ef4897521f9ec4ca823282f7446828024bce08117",
"introduction.md": "06bf96d164d402d4e376c6308b20f96d324110b2e0cf96c2a1a67b39906072e3",
"laravel-adoption.md": "8974d4906658a0727a185ba3d53bf03e8e33494cd63d84def0b9ae62fcc7507e",
"laravel-adoption.md": "55a4df64436667b9477c9a39dd69ddde9f4c30739ba3dfd2ff316b553a55ba4f",
"mcp-workflows.md": "1c0b5bb7f2e5c7ca835dfdfa57bbe8f6624172c855f4e225057ac2377abf360e",
"migration.md": "7304a53786d5e45d3a639c33386e6558e855ee77982883a5e051ef5084b8453b",
"monitoring.md": "346b8a5207b7d69cea63dc9bfec95bf1911d3038a9d30ad06939b13130079279",
Expand Down Expand Up @@ -103,9 +103,9 @@
"polyglot/worker-protocol.md": "91b18b39d626c1288bfa3f6b8212fa8246aa14393cb489a39fe90379bc4cd4b2",
"polyglot/workflow-signals.md": "c8b4280f844570ad7eed0884130724ac4ad62a2a58041de76cd02621ae5ee03f",
"polyglot/workflow-streams.md": "5675a8ea1b9d0b1f7223fecb90b3b048d3006670bf505950bc783709287a6432",
"quickstart.md": "887c6b500e17d41e6098f97f62e07ab3f2a05cd94e36aed93bf05fcce7b532e2",
"quickstart.md": "744ad91ea47202d056e14f6582dd751c471d329433565bcc4cb4182ae4cc76fb",
"rolling-upgrades.md": "6acff017f2148d4f7553ebd4811aff8bde59cf6da4251845f4240ef7d1b1a970",
"sample-app.md": "d9cfd76ef3830c9a945949f2b7ca720e6434dbb15dcea96749c01f7e688534db",
"sample-app.md": "0a5e7c704344750c49dccac5e1be058471a70ad2dc68f82bf3920dee30e08cde",
"sdk-neutrality.md": "7b0714c123ade4904591870fc20e9a797da1e5485b2a6c87ca3eaa00c5de6ed6",
"sponsors.md": "e85e14375743ca8fa50e3a48f894b160e28272573aa88480064f74010ebee98a",
"support.md": "706807b3902599dda6080f632ec1f893017ea18bbe9585f533dcdbd6d85f4621",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -131,4 +131,4 @@ php artisan queue:work shared --queue=workflows
php artisan queue:work shared --queue=activities
```

El worker de la aplicación A reproduce los workflows y programa tareas de actividad. El worker de la aplicación B recoge esas tareas, las ejecuta y devuelve resultados. El motor gestiona el traspaso mediante la base de datos compartida.
El worker de la aplicación A reproduce los workflows y programa tareas de actividad. Configura su tiempo límite de jobs como se describe en [Tiempo límite del worker](/docs/installation/#worker-timeout). El worker de la aplicación B recoge esas tareas, las ejecuta y devuelve resultados. El motor gestiona el traspaso mediante la base de datos compartida.
65 changes: 65 additions & 0 deletions i18n/es/docusaurus-plugin-content-docs/current/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,68 @@ plano. Necesitas ejecutar el [comando `queue:work`](https://laravel.com/docs/12.
o usar [Horizon](https://laravel.com/docs/12.x/horizon) para administrar los
workers de las colas. Sin un worker, los workflows y las actividades no se
procesan. Para ejecutarlos en paralelo, necesitas más de un worker.

### Tiempo límite del worker {#worker-timeout}

Cuando PHP tiene la extensión `pcntl`, un worker de colas termina cualquier job
que se ejecute más allá de su tiempo límite: el `--timeout` del worker, 60
segundos por defecto, salvo que el job defina el suyo. Una tarea de workflow
terminada así se revierte. Solo se reintenta cuando vence su lease
(`workflows.v2.workflow_task_lease_seconds`, 300 segundos por defecto) y se
cuenta como un lease perdido, y el reintento repite el mismo trabajo. Una tarea
de workflow que siempre necesita más tiempo que el límite, como una que programa
o termina un `all()` amplio, nunca se completa.

Tres ajustes deben encajar:

- El **tiempo límite de los workers que ejecutan tareas de workflow** debe
cubrir tu tarea de workflow más larga. Una tarea de workflow terminada espera
el resto de su lease antes de reintentarse.
- El **`retry_after`** de la conexión de cola debe superar el tiempo límite de
cada job que pase por ella, como exige Laravel. De lo contrario, la cola
entrega un job que sigue en ejecución a un segundo worker.
- Las **actividades** deben mantener un tiempo límite acotado, para que una
actividad bloqueada no pueda retener un worker para siempre. No uses
`--timeout=0`.

Para dar a las actividades un tiempo límite más corto que a las tareas de
workflow, ejecútalas en su propia cola con sus propios workers. Las actividades
se ejecutan en la conexión y la cola de su workflow, salvo que la clase de la
actividad defina `$connection` o `$queue`, o que el workflow pase
`ActivityOptions`.

```php
// config/queue.php
'redis' => [
'driver' => 'redis',
'connection' => 'default',
'queue' => 'default',
'retry_after' => 330, // above the workflow task workers' timeout
],
```

```php
use Workflow\V2\Activity;

final class ChargeCardActivity extends Activity
{
public ?string $queue = 'activities';
}
```

```bash
php artisan queue:work redis --queue=default --timeout=300 # workflow tasks
php artisan queue:work redis --queue=activities --timeout=60 # activities
```

En Horizon, la opción `timeout` de cada supervisor es el tiempo límite del
worker.

Workflow 2.34.0 añade `DW_V2_WORKFLOW_TASK_JOB_TIMEOUT_SECONDS`, sin definir por
defecto. Cuando se define, cada job de tarea de workflow lleva ese tiempo
límite, mantenido al menos 10 segundos por debajo del `retry_after` de su
conexión, y los workers lo usan en lugar de su propio tiempo límite para esos
jobs, de modo que las tareas de workflow y las actividades pueden compartir
workers. A partir de esa versión, un worker que atiende la cola de workflows
registra una advertencia al iniciarse cuando el tiempo límite con el que se
ejecutan sus tareas de workflow es inferior al lease de la tarea de workflow.
Original file line number Diff line number Diff line change
Expand Up @@ -298,6 +298,9 @@ Ejecuta el worker de colas Laravel según el despliegue integrado:
php artisan queue:work redis --queue=orders
```

Configura el tiempo límite de jobs de este worker como se describe en
[Tiempo límite del worker](/docs/installation/#worker-timeout).

Usa la simulación integrada desde la misma acción. Ejecuta inmediatamente las
tareas listas y registra despachos de actividad:

Expand Down
4 changes: 4 additions & 0 deletions i18n/es/docusaurus-plugin-content-docs/current/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -454,6 +454,10 @@ php artisan migrate
php artisan queue:work
```

Antes de ejecutar ramificaciones amplias, configura el tiempo límite de jobs del
worker como se describe en
[Tiempo límite del worker](/docs/installation/#worker-timeout).

Para añadir la interfaz de operación a esa misma aplicación, instala el
paquete Composer de Waterline integrado:

Expand Down
2 changes: 2 additions & 0 deletions i18n/es/docusaurus-plugin-content-docs/current/sample-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,8 @@ Inicia el worker de colas para procesar workflows y actividades.
php artisan queue:work
```

En tu propia aplicación, configura el tiempo límite de jobs del worker como se describe en [Tiempo límite del worker](/docs/installation/#worker-timeout).

Para comprobar el propio ciclo de reparación sin esperar a que un worker ocupado llegue a otro ciclo `Looping`, ejecuta una pasada explícita de recuperación desde un segundo terminal:

```bash
Expand Down
Loading