Primeiros passos com Durable Workflow 2.0

Antes de começar

Objetivo: executar um workflow em modo serviço e ler seu resultado durável concluído com PHP, Python ou Rust.

Tempo estimado: cerca de 15 minutos depois que seu runtime estiver disponível.

Resultado final: o SDK escolhido inicia um worker e um workflow, depois exibe um identificador de workflow, status=completed e Hello, <language>!.

Pré-requisitos:

• curl e um terminal
• Docker para o caminho local sob sua administração, ou um namespace provisionado no Durable Workflow Cloud
• ferramentas de uma linguagem: PHP 8.1+ com Composer, Python 3.10+ ou Rust 1.86+

O modo serviço não exige Laravel. O caminho para Laravel integrado aparece separadamente no fim deste guia.

1. Escolha seu runtime em modo serviço

Runtime	Quando escolher	Próxima ação
Durable Workflow Cloud	Você quer que Durable Workflow opere o runtime, a persistência e o Managed Waterline.	Siga o guia executável Primeiro workflow no Cloud, que conecta os programas completos de PHP, Python e Rust às credenciais provisionadas e a um resultado completed. Não execute Server nem um serviço Waterline separado.
Server sob sua administração	Você quer operar o runtime ou executar este exercício local com os artefatos publicados.	Continue abaixo com Docker e curl. Implante Waterline separadamente apenas se quiser sua interface de operação.

O exemplo abaixo usa um Server local sob sua administração. Assim, você pode executá-lo sem criar uma conta nem obter o código-fonte. O Cloud usa o mesmo modelo de SDK e worker. Substitua a conexão de desenvolvimento local pelos valores provisionados descritos em Runtime gerenciado do Cloud.

2. Inicie o Server local

Pule esta etapa se escolheu Cloud. Para o caminho sob sua administração, expanda e execute a configuração com a versão fixada. Ela inicia um Server que não depende de um checkout do código-fonte, com SQLite e um token de desenvolvimento.

Iniciar a imagem fixada do Server

export DW_SERVER_IMAGE=durableworkflow/server:2.5.13
export DW_AUTH_TOKEN=dev-token

docker volume create durable-workflow-quickstart

docker run --rm \
  -v durable-workflow-quickstart:/app/database \
  -e DW_AUTH_DRIVER=token \
  -e DW_AUTH_TOKEN="$DW_AUTH_TOKEN" \
  "$DW_SERVER_IMAGE" server-bootstrap

docker rm -f durable-workflow-server >/dev/null 2>&1 || true
docker run -d --name durable-workflow-server \
  -p 8080:8080 \
  -v durable-workflow-quickstart:/app/database \
  -e DW_AUTH_DRIVER=token \
  -e DW_AUTH_TOKEN="$DW_AUTH_TOKEN" \
  "$DW_SERVER_IMAGE"

until curl -sf http://localhost:8080/api/ready >/dev/null; do sleep 1; done
curl -H "Authorization: Bearer $DW_AUTH_TOKEN" \
  http://localhost:8080/api/cluster/info

Resultado esperado: a verificação de prontidão é bem-sucedida e a resposta de informações do cluster identifica o Server local independente. Mantenha-o em execução enquanto conclui o caminho de uma linguagem.

3. Escolha uma linguagem

Os três SDKs oficiais têm o mesmo destaque. Apenas a aba selecionada é exibida, para que você possa seguir um caminho sem percorrer os programas das outras duas linguagens.

PHP

Requisitos: PHP 8.1 ou superior e Composer. Este é o pacote durable-workflow/sdk, independente de framework, e não o mecanismo integrado ao Laravel.

1. Instale o SDK.

mkdir durable-workflow-php-quickstart
cd durable-workflow-php-quickstart
composer require durable-workflow/sdk:2.2.6

2. Adicione o worker e o cliente. Expanda o código completo e copie os dois arquivos para o novo projeto.

Código PHP completo para execução

O worker registra um tipo de workflow e um tipo de atividade em sua própria fila de tarefas.

cat > worker.php <<'PHP'
<?php

declare(strict_types=1);

require __DIR__.'/vendor/autoload.php';

use DurableWorkflow\Client;
use DurableWorkflow\Worker;
use DurableWorkflow\Worker\ActivityContext;
use DurableWorkflow\Worker\WorkflowContext;

$client = new Client('http://localhost:8080', token: 'dev-token');
$worker = new Worker($client, 'quickstart-php');

$worker->registerActivity(
    'quickstart.greet',
    static fn (ActivityContext $context, string $name): string => "Hello, {$name}!",
);

$worker->registerWorkflow(
    'quickstart.greeter',
    static function (WorkflowContext $context, string $name): array {
        $greeting = $context->activity('quickstart.greet', [$name]);

        return ['greeting' => $greeting, 'language' => 'php'];
    },
);

$worker->run();
PHP

Cliente e leitura do resultado

Este cliente inicia um workflow com nome único, aguarda a execução selecionada e consulta o estado terminal durável mantido pelo Server.

cat > start.php <<'PHP'
<?php

declare(strict_types=1);

require __DIR__.'/vendor/autoload.php';

use DurableWorkflow\Client;

$client = new Client('http://localhost:8080', token: 'dev-token');
$workflowId = 'quickstart-php-greeter-'.bin2hex(random_bytes(4));
$handle = $client->startWorkflow(
    workflowType: 'quickstart.greeter',
    workflowId: $workflowId,
    taskQueue: 'quickstart-php',
    input: ['PHP'],
);

$result = $handle->result(timeoutSeconds: 30);
$execution = $handle->describeSelectedRun();

echo "workflow_id={$execution->workflowId}\n";
echo "status={$execution->status}\n";
echo 'result='.json_encode($result, JSON_THROW_ON_ERROR)."\n";
PHP

3. Execute o worker e o cliente.

php worker.php > quickstart-worker.log 2>&1 &
export QUICKSTART_WORKER_PID=$!
trap 'kill "$QUICKSTART_WORKER_PID" 2>/dev/null || true' EXIT

php start.php

kill "$QUICKSTART_WORKER_PID" 2>/dev/null || true
trap - EXIT

Resultado esperado: status=completed e um resultado contendo "greeting":"Hello, PHP!". Você executou um worker PHP independente e inspecionou seu resultado durável sem Laravel.

Continue com o Guia do SDK PHP.

Python

Requisitos: Python 3.10 ou superior. O programa mantém o worker e o cliente em um único processo, mas ambos se comunicam com o Server pelas APIs públicas de workers e do plano de controle.

1. Instale o SDK.

   Use a versão estável do SDK Python indicada no manifesto acima. O requisito exato gerado mantém este caminho executável na versão estável documentada.

mkdir durable-workflow-python-quickstart
cd durable-workflow-python-quickstart

python3 -m venv .venv
. .venv/bin/activate
pip install durable-workflow==2.5.0

2. Crie e execute o worker e o cliente. Expanda o programa completo. Seu último comando executa o programa.

Código Python completo para execução

cat > greeter.py <<'PY'
import asyncio
import time

from durable_workflow import Client, Worker, activity, workflow


@activity.defn(name="quickstart.greet")
async def greet(name: str) -> dict:
    return {"greeting": f"Hello, {name}!", "language": "python"}


@workflow.defn(name="quickstart.greeter")
class GreeterWorkflow:
    def run(self, ctx, name):
        return (yield ctx.schedule_activity("quickstart.greet", [name]))


async def main():
    workflow_id = f"quickstart-python-greeter-{int(time.time())}"

    async with Client(
        "http://localhost:8080",
        token="dev-token",
        namespace="default",
    ) as client:
        handle = await client.start_workflow(
            workflow_type="quickstart.greeter",
            task_queue="quickstart-python",
            workflow_id=workflow_id,
            input=["Python"],
        )

        worker = Worker(
            client,
            task_queue="quickstart-python",
            workflows=[GreeterWorkflow],
            activities=[greet],
        )
        await worker.run_until(workflow_id=workflow_id, timeout=30.0)

        result = await handle.result(timeout=10.0)
        execution = await handle.describe_run()

    print(f"workflow_id={execution.workflow_id}")
    print(f"status={execution.status}")
    print(f"result={result}")


asyncio.run(main())
PY

python greeter.py

Resultado esperado: status=completed e um resultado contendo Hello, Python!. As duas últimas chamadas do SDK leem o resultado da execução selecionada e seu estado terminal durável no Server.

Continue com o Guia do SDK Python.

Rust

Requisitos: Rust 1.86 ou superior. Este exemplo executa um worker nativo e um cliente em um único processo Tokio.

1. Instale o SDK.

cargo new durable-workflow-rust-quickstart
cd durable-workflow-rust-quickstart
cargo add durable-workflow@=3.4.1
cargo add tokio --features macros,rt-multi-thread,time

2. Crie e execute o worker e o cliente. Expanda o programa completo. Seu último comando compila e executa o programa.

Código Rust completo para execução

cat > src/main.rs <<'RS'
use std::time::{Duration, SystemTime, UNIX_EPOCH};

use durable_workflow::{json, Client, Result, Worker, WorkflowResultOptions};

#[tokio::main]
async fn main() -> Result<()> {
    let client = Client::builder("http://localhost:8080")
        .token(Some("dev-token".to_string()))
        .namespace("default")
        .build()?;
    let task_queue = "quickstart-rust";
    let mut worker = Worker::new(client.clone(), task_queue);

    worker.register_activity("quickstart.greet", |_context, arguments| async move {
        let name = arguments
            .get(0)
            .and_then(|value| value.as_str())
            .unwrap_or("Rust");
        Ok(json!({"greeting": format!("Hello, {name}!"), "language": "rust"}))
    });

    worker.register_workflow("quickstart.greeter", |context, input| async move {
        let name = input.get(0).and_then(|value| value.as_str()).unwrap_or("Rust");
        context.activity("quickstart.greet", json!([name])).await
    });

    worker.register().await?;
    let workflow_id = format!("quickstart-rust-greeter-{}", unique_suffix());
    let handle = client
        .start_workflow(
            "quickstart.greeter",
            task_queue,
            &workflow_id,
            json!(["Rust"]),
        )
        .await?;

    let watcher = handle.clone();
    worker
        .run_until(async move {
            loop {
                if watcher.describe().await.is_ok_and(|run| run.is_terminal()) {
                    break;
                }
                tokio::time::sleep(Duration::from_millis(500)).await;
            }
        })
        .await?;

    let result = handle.result(WorkflowResultOptions::default()).await?;
    let execution = handle.describe_selected_run().await?;

    println!("workflow_id={workflow_id}");
    println!("status={}", execution.status.as_deref().unwrap_or("unknown"));
    println!("result={result}");
    Ok(())
}

fn unique_suffix() -> u128 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default()
        .as_millis()
}
RS

cargo run

Resultado esperado: status=completed e um resultado JSON contendo "greeting":"Hello, Rust!". O exemplo aguarda o worker concluir a execução, depois lê o estado durável e o resultado decodificado da execução selecionada.

Continue com o Guia do SDK Rust.

4. Remova o Server local

Quem usa Cloud não tem um Server local para remover. Para o exercício sob sua administração:

docker rm -f durable-workflow-server
docker volume rm durable-workflow-quickstart

Caminho separado: Laravel integrado

Laravel integrado é um modo oficial de implantação em PHP para aplicações que querem manter o estado dos workflows, a execução em fila, a configuração e as ferramentas de operação na infraestrutura Laravel existente. Ele instala durable-workflow/workflow. Não usa Server nem durable-workflow/sdk.

Crie uma aplicação integrada com o pacote publicado:

composer create-project laravel/laravel durable-workflow-laravel-quickstart
cd durable-workflow-laravel-quickstart
composer require durable-workflow/workflow:2.5.4
php artisan migrate
php artisan queue:work

Para usar a interface de operação dentro da mesma aplicação Laravel, adicione o pacote Composer qualificado do Waterline integrado:

composer require durable-workflow/waterline:2.3.1
php artisan waterline:install

Esse pacote Composer não é a forma de instalar o serviço Waterline separado para um Server sob sua administração. Laravel integrado não executa Server nem instala um SDK de modo serviço.

Continue em Instalação integrada para configurar uma fila Laravel diferente de sync. Depois, defina e inicie um workflow integrado. Modos de implantação compara esse caminho especializado com a plataforma em modo serviço.

Próximos passos

• Consulte o Índice de capacidades para verificar o que seu runtime e SDK oferecem.
• Continue com o guia de modo serviço do SDK PHP, SDK Python ou SDK Rust.
• Compare ciclo de vida, mensagens, agendamentos, visibilidade e execução de workers em Capacidades de clientes e workers.
• Opere o runtime escolhido com Runtime gerenciado do Cloud ou Server sob sua administração. Adicione a CLI quando a automação pelo terminal for útil.
• Planeje a implantação segura de workers em modo serviço com Compatibilidade e roteamento de workers e Implantação por build ID.

Para os recursos de código do Laravel integrado, como temporizadores, sinais, consultas, atividades e workflows filhos, use a Documentação integrada.

A qualificação de releases é separada deste guia de primeiro resultado. A Suíte de conformidade da plataforma reúne a matriz exata de artefatos, as verificações do código público, os registros completos de execução, os critérios de tempo, a limpeza e o contrato de primeiros passos legível por máquina.