Інтерфейс зовнішнього виконання

Durable Workflow v2 визначає зовнішнє виконання публічним контрактом продукту. Окремий Server публікує його машиночитаний загальний опис через GET /api/cluster/info у worker_protocol.external_execution_surface_contract.

Контракт називається activity_grade_external_execution. Він призначений для стійкої обмеженої роботи, яка може виконуватися поза повним runtime workflow:

• activity обслуговування оператора;
• автоматизація платформи;
• передавання між інтеграціями;
• адаптери мостів, що запускають, надсилають signal/update або передають роботу;
• обробники на основі скриптів, daemon, HTTP, черг, serverless чи агентів.

Основний напрям — автоматизація операцій, платформи та інтеграцій. AI-агенти й скрипти є важливими споживачами стабільних інтерфейсів, але не змінюють межі runtime.

Межа

Зовнішні обробники можуть:

• виконувати одне орендоване завдання workflow або activity;
• повідомляти поступ оренди через heartbeat протоколу worker;
• повертати структурований конверт успіху чи помилки;
• використовувати адаптер мосту для запуску, signal, update або передавання обмеженої роботи.

Зовнішні обробники не повинні:

• інтерпретувати семантику replay workflow;
• володіти поведінкою ContinueAsNew;
• застосовувати правила порядку signal, update чи query поза контрактом runtime;
• прямо змінювати історію подій;
• працювати як необмежений runtime workflow.

Ці правила залишаються в Server і повноцінних runtime SDK. Транспорт має лише переносити оголошені конверти входу й результатів через транспортну межу.

Опубліковані точки контракту

Прочитайте GET /api/cluster/info перед підключенням транспорту. Відповідні шляхи v2:

Шлях	Призначення
worker_protocol.external_execution_surface_contract	Межі продукту й runtime, допустимі класи транспорту та статус точок контракту.
worker_protocol.external_task_input_contract	Незалежний від транспорту конверт входу одного орендованого завдання workflow або activity.
worker_protocol.external_task_result_contract	Незалежний від транспорту конверт успіху, помилки та неправильно сформованого виводу.
worker_protocol.server_capabilities.external_execution_surface	Компактний покажчик можливості для узгодження площини worker.

Інтерфейс зовнішнього виконання також називає заплановані точки детермінованого поєднання автентифікації/профілю/TLS, конфігураційного зіставлення обробників, обмежених адаптерів мостів, зовнішнього сховища payload і безпеки допуску/розгортання. Це точки контракту, а не приватні деталі реалізації.

Вимоги до транспорту

Допустимим транспортом може бути CLI чи daemon з опитуванням, виклик обробника HTTP, worker на основі черги або виклик serverless. Транспорт може відрізнятися, але ці вимоги спільні:

• створювати оголошену схему входу;
• приймати оголошену схему результату;
• зберігати task.id, task.attempt і task.idempotency_key;
• відображати транспортні помилки в структуровану помилку або результат неправильно сформованого виводу;
• детерміновано розв’язувати входи автентифікації, TLS, профілю й середовища.

Коди завершення, stderr, падіння процесів, помилки HTTP, тайм-аути видимості черг та помилки платформи serverless є фактами транспорту. Вони стають фактами workflow лише після відображення транспортом в оголошений конверт результату або malformed_output.

Перший конкретний транспорт за цим контрактом — викличний транспорт HTTP, опублікований у worker_protocol.invocable_carrier_contract. Він підтримує лише завдання activity, потребує HTTPS, дозволяючи loopback HTTP лише для розробки, та розв’язує автентифікацію через конфігурацію зовнішнього виконавця. Його транспортна retry_policy відрізняється від стійкої політики повторних спроб activity. Після повідомлення результату останню визначає Server/runtime.

Адаптери мостів

Адаптери мостів є обмеженими інтерфейсами входу або передавання. Вони можуть запускати, надсилати signal/update або передавати роботу, але не є runtime workflow та не повинні приховувати поведінку replay чи історії подій.

Кожен адаптер мосту потребує явних машинних результатів для:

• невідомої цілі;
• помилки автентифікації;
• неправильно сформованого payload;
• повторного запуску;
• непідтримуваної маршрутизації;
• прийнятого передавання;
• відхиленого передавання.

Зберігайте ту саму зрозумілість для оператора, що й у решті площини керування: стабільні коди статусу, іменовані значення reason і достатній контекст для dw, Waterline, SDK та агентів, щоб пояснити подію без розбору текстових пояснень.

CLI безпосередньо надає інтерфейс мосту webhook:

dw bridge:webhook stripe \
  --action=start_workflow \
  --idempotency-key=stripe-event-1001 \
  --target='{"workflow_type":"orders.fulfillment","task_queue":"external-workflows","business_key":"order-1001"}' \
  --input='{"order_id":"order-1001"}' \
  --json

Відповідь JSON є тим самим контрактом результатів адаптера мосту, який публікує /api/cluster/info, включно з outcome, reason, control_plane_outcome, idempotency_key і прихованим від чутливих даних описом target.

Форма для керування агентами

Інтерфейс зовнішнього виконання є частиною підходу v2 до розробки за допомогою AI. Люди вивчають інваріант workflow/activity/replay, а інструменти працюють через стабільні контракти:

1. виявити інтерфейс зовнішнього виконання через /api/cluster/info;
2. обрати транспорт за опублікованими вимогами;
3. створити конверт входу зовнішнього завдання;
4. зберегти ідентичність та ідемпотентність завдання;
5. повернути конверт успіху, помилки або неправильно сформованого виводу;
6. повідомити помилки мосту й транспорту іменованими результатами.

Це робить генерацію коду за допомогою AI та автоматизацію оператора передбачуваними: інструмент посилається на маніфест протоколу, конверт завдання, конверт результату та результат мосту, замість виводити поведінку з одного демонстраційного скрипта.