Перейти до основного вмісту
Версія: 2.x

Update

Update дають змогу одночасно отримати інформацію про поточний стан workflow і змінити його. По суті, це поєднання query та signal в одному виклику.

Явні команди update​

Кожен прийнятий update:

  • Є викликом запит–відповідь до активного workflow. attemptUpdate*() очікує на завершення обробника, а submitUpdate*() повертається відразу після стійкого прийняття команди й надає inspectUpdate($updateId) для подальшого опитування.
  • Використовує оголошену стійку назву update в історії команд і маршрутизації webhook. #[UpdateMethod('mark-approved')] зберігає публічну назву виклику за перейменування PHP-методу.
  • Відхиляється для історичних або вже закритих запусків замість непомітної зміни поточного запуску.
  • До виконання обробника відхиляє неоголошені назви методів як rejected_unknown_update, а аргументи, що порушують контракт, як rejected_invalid_arguments із машиночитаними validation_errors.

Як і query, update спочатку відтворюють зафіксовану історію. На відміну від query, update можуть змінювати безпечний щодо replay стан workflow і повертати значення.

Щоб визначити метод update у workflow, використовуйте анотацію UpdateMethod. Необов’язковий рядковий аргумент фіксує публічну стійку назву, яка зберігається за перейменування PHP-методу:

use Workflow\UpdateMethod;
use Workflow\V2\Workflow;

final class MyWorkflow extends Workflow
{
private bool $ready = false;

#[UpdateMethod('mark-ready')]
public function updateReady(bool $ready): bool
{
$this->ready = $ready;

return $this->ready;
}
}

Викликайте метод update безпосередньо, якщо потрібне лише повернене значення:

use Workflow\V2\WorkflowStub;

$workflow = WorkflowStub::load('order-123');

$ready = $workflow->updateReady(true);

Прямий PHP-виклик і далі використовує назву методу. Стійка ціль команди залишається mark-ready.

Використовуйте attemptUpdate(), якщо також потрібен результат стійкої команди. Передайте йому стійку назву update:

use Workflow\V2\WorkflowStub;

$workflow = WorkflowStub::load('order-123');

$result = $workflow->attemptUpdate('mark-ready', true);

$result->accepted(); // true
$result->completed(); // true when the update body ran successfully
$result->updateStatus(); // "accepted", "completed", "failed", or "rejected"
$result->updateId(); // Durable update lifecycle id
$result->result(); // Raw update return value when completed
$result->failureMessage(); // Failure message when the update body threw

attemptUpdate() спочатку записує прийнятий update, а потім очікує, доки worker workflow застосує його й закриє життєвий цикл update. Час очікування обмежено workflows.v2.update_wait.completion_timeout_seconds. Якщо до спливу бюджету worker не закрив update, attemptUpdate() повертає прийнятий життєвий цикл із waitTimedOut() === true та updateStatus() === 'accepted'.

Використовуйте withUpdateWaitTimeout(), якщо одному виклику потрібен інший бюджет очікування завершення:

use Workflow\V2\WorkflowStub;

$workflow = WorkflowStub::load('order-123')
->withUpdateWaitTimeout(5);

$result = $workflow->attemptUpdate('mark-ready', true);

Використовуйте attemptUpdateWithArguments(), якщо код виклику вже має позиційний список або мапу іменованих параметрів:

$result = $workflow->attemptUpdateWithArguments('mark-ready', [
'ready' => true,
]);

Іменовані мапи перевіряються за стійко зафіксованим контрактом update й нормалізуються в порядку оголошення до прийняття.

Використовуйте submitUpdate() або submitUpdateWithArguments(), якщо потрібне лише стійке прийняття, а worker workflow може застосувати update пізніше:

$accepted = $workflow->submitUpdate('mark-ready', true);

$accepted->accepted(); // true
$accepted->completed(); // false
$accepted->updateStatus(); // "accepted"
$accepted->result(); // null until the worker records UpdateCompleted

Використовуйте inspectUpdate(), якщо вже маєте update_id і хочете пізніше прочитати збережений життєвий цикл без повторного очікування:

$latest = $workflow->inspectUpdate($accepted->updateId());

$latest->updateStatus(); // "accepted"
$latest->closedAt(); // null until the lifecycle closes

inspectUpdate() не очікує на виконання workflow. Він повторно завантажує збережений стійкий життєвий цикл і повертає поточний UpdateResult.

Відновлення після невизначеної відповіді​

Durable-приймання, завершення обробника й зовнішній бізнес-ефект є окремими фактами. Тайм-аут виклику може залишити прийнятий update активним, а втрачена відповідь може приховати вже зафіксований результат. Подальша відмова новому update не визначає результат початкового.

Якщо застосунок зберіг update ID, перевірте його lifecycle замість нового надсилання. Зберігайте початковий run ID, щоб continue-as-new не перенаправив перевірку до іншого виконання:

use Workflow\V2\WorkflowStub;

$latest = WorkflowStub::loadRun($savedRunId, $savedNamespace)->inspectUpdate($savedUpdateId);

$latest->updateStatus();
$latest->result(); // Available when that retained update completed.

Збережені ID належать початковій операції. Перевірка читає збережений запис і може працювати після закриття чи переходу виконання в історичний стан. Відсутні або видалені дані залишають результат невизначеним і не дозволяють повторювати бізнес-ефект. Зберігайте власний запис операції для звіряння, якщо початкова відповідь і згенерований update ID були втрачені.

Request ID та збережені квитанції​

Зберігайте namespace, instance ID, початковий run ID, update ID, назву операції та її незмінний зміст у записі застосунку. Квитанція accepted підтверджує стійке приймання. Завершений lifecycle містить записаний результат обробника. Жоден із цих фактів не доводить одноразове виконання окремого платежу, листа чи запису в БД.

request_id не є переносимим контрактом Update-ID у межах одного запуску. Перевірені PHP-шляхи можуть повернути перший збережений update, навіть якщо повторний запит із тим самим ключем має інші аргументи. Embedded-пошук також охоплює різні назви update в цьому екземплярі. Після continue-as-new той самий ключ може повернути результат попередника без нового update в наступному запуску. Збережена квитанція за ключем може повертатися й після закриття, тоді як новий update буде відхилено.

Вбудовані Laravel-webhook для update беруть ключ викликача з X-Request-Id. Зберігайте цей заголовок під час проходження через проксі. HTTP-update окремого Server беруть ключ лише з request_id у JSON-тілі; їхній заголовок X-Request-Id використовується для кореляції. Без ключа в тілі update не має ключа дедуплікації, навіть якщо запити мають однаковий заголовок.

Перевірені PHP-шляхи можуть знайти ту саму збережену квитанцію для різних назв update в одному екземплярі. Використовуйте один ключ для однієї логічної операції та зберігайте її початковий зміст. Не змінюйте аргументи, не використовуйте ключ для іншої назви й не вважайте його новою операцією в наступному запуску. Перевірка опублікованих PHP-артефактів підтверджує незалежність ключів від заголовків проксі та збереження квитанцій після закриття. Це відновлення не обіцяє переносимого виявлення конфліктів, коли той самий ключ використано з іншим змістом. Ширший контракт розглядається у спільному issue 216. Native Server та інші SDK потребують окремої перевірки.

Відновлення квитанції залежить від збережених команд, update та історії. Тут не обіцяється універсальний строк дедуплікації. Перегляньте зберігання історії та зберігайте бізнес-журнал стільки, скільки потрібно застосунку. За відсутності доказів результат залишається невідомим.

Захист бізнес-ефекту​

Для операції на кшталт оплати рахунку:

  1. Перед командою збережіть ключ операції, наприклад tenant-1:charge:invoice-123, і її незмінний зміст. Під час відновлення використовуйте той самий ключ.
  2. В activity, що застосовує ефект, установіть у БД унікальне обмеження для tenant і ключа операції. В одній транзакції перевірте збережений зміст, застосуйте локальний ефект і запишіть результат. Для дубліката з тим самим змістом повертайте збережений результат. Інший зміст відхиляйте.
  3. Для зовнішнього провайдера використовуйте його контракт ідемпотентності або outbox і звіряння. Транзакція вашої БД не робить окремий виклик провайдера атомарним.
  4. Після невизначеної відповіді звірте запис операції, початковий lifecycle update і докази провайдера. Перед наступною дією зафіксуйте, чи ефект очікується, застосований, неуспішний або все ще невідомий.

Між query та наступною командою залишається можливість гонки. Дублікат signal може запустити ще одну activity після приймання початкової. Захист застосунку має витримувати повторну доставку. Перевірений приклад виконує дві activity з одним ключем, але фіксує один локальний ефект у БД. Це не доводить exactly-once виконання для довільних зовнішніх систем.

Правила update:

  • load($instanceId) оновлює найновіший стійкий запуск екземпляра, зокрема після continue-as-new.
  • Нові update через loadRun($runId) відхиляються з rejected_not_current, щойно вибраний запуск стає історичним. Перевірка збереженої квитанції є окремою дією.
  • Нові update закритих запусків відхиляються з rejected_not_active. Повернення збереженої квитанції за ключем є окремою дією.
  • Update, прийнятий під час виконання workflow-завдання, яке завершує запуск, отримує один хід доставки перед закриттям запуску, як і signal. Його обробник виконується, а викликач отримує результат. Update, що ще очікують, коли запуск завершується помилкою, скасовується або примусово зупиняється, закриваються з явною помилкою.
  • Помилки тіла update не закривають запуск workflow. Вони записуються як помилки рівня update й залишають запуск відкритим для наступного завдання replay.
  • Query відтворюють завершені update, а відхилені чи неуспішні update залишаються лише фактами команд та історії, які не відтворюються.