Durable Functions

Durable-функции дают развёрнутой функции устойчивый перезапускаемый идентификатор: вы запускаете её как именованный инстанс, а платформа записывает этот инстанс в Postgres — так что его статус, результат и историю можно смотреть по id, а повторные запуски дедуплицируются. Это примитив надёжности вокруг одного запуска функции, а не DSL для воркфлоу. Для многошаговых сценариев с ветвлениями, fan-out, расписаниями и подтверждениями человека используйте графовые Пайплайны (см. страницу «Пайплайны»).

Durable-инстанс выполняет одну обычную развёрнутую функцию до завершения. Её возвращаемое значение становится результатом инстанса, а сам инстанс завершается со статусом COMPLETED (или FAILED, если обработчик бросил ошибку). Поскольку запуск записывается в Postgres до выполнения функции, инстанс переживает рестарт — платформа пере-запускает его из durable-очереди, а не теряет работу.

Запуск durable-инстанса

Из функции на Node.js внедрённый клиент global.durable запускает другую развёрнутую функцию как durable-инстанс через startNew(functionName, instanceId?, input?). Цель — обычный обработчик, не генератор. Передайте instanceId, чтобы сделать запуск идемпотентным: второй startNew с тем же id вернёт существующий инстанс, а не создаст дубль. То, что вы передаёте в input, становится event этой функции.

// process-order.js — an ORDINARY deployed function (Node.js). Its return value
// becomes the durable instance output. Deploy it like any other function.
exports.handler = async (event, context) => {
  const order = event; // the input you passed to startNew()
  const charged = await chargeCard(order);
  await reserveStock(order);
  return { ok: true, orderId: order.id, chargeId: charged.id };
};

// starter.js — a second Node.js function launches "process-order" as a durable,
// idempotent, restartable instance and follows it by id. global.durable is
// injected into the Node runtime only.
exports.handler = async (event, context) => {
  // startNew(functionName, instanceId?, input?). Passing an instanceId makes the
  // start idempotent — a duplicate start with the same id returns the same instance.
  const { instanceId } = await global.durable.startNew(
    'process-order',
    `order-${event.orderId}`,
    { id: event.orderId, amount: event.amount },
  );

  // Optional: block up to N ms for the instance to finish (resolves on COMPLETED,
  // throws on FAILED/TERMINATED/timeout). Otherwise poll global.durable.getStatus(id).
  const status = await global.durable.waitForCompletion(instanceId, 30000);
  return { instanceId, state: status.status, output: status.output };
};

Клиент управления (только Node.js)

global.durable внедряется в рантайм Node.js — функции на Python и Go его не получают. Он предоставляет:

• startNew(name, instanceId?, input?) — запустить именованную функцию как инстанс; резолвится в { instanceId, … }.
• getStatus(instanceId) — прочитать инстанс: status, output, createdAt, lastUpdatedAt и историю событий history (или null, если инстанса нет).
• waitForCompletion(instanceId, timeoutMs?) — опрашивать до статуса COMPLETED и вернуть статус; бросает ошибку при FAILED, TERMINATED или таймауте.
• terminate(instanceId, reason?) — остановить инстанс и пометить его TERMINATED.

HTTP API

Те же операции доступны по HTTP для вызывающих вне Node-функции. POST /durable/orchestrations/{name}/start возвращает 202 с { instanceId, statusQueryGetUri, terminatePostUri, … }, а GET /durable/orchestrations/{instanceId}/status возвращает инстанс. Эти маршруты авторизуются через вашу сессию входа или Bearer-PAT (скоупы jobs:read / jobs:write); global.durable обращается к ним за вас с внутренним токеном.

Durable, задачи или пайплайны

Берите durable-инстанс, когда нужен один фоновый запуск с устойчивым id — идемпотентный старт, статус для опроса и устойчивость к рестартам. Берите фоновую задачу (см. «Фоновые задачи»), когда нужна работа по принципу fire-and-forget с автоматическими ретраями, бэкоффом и очередью недоставленных (DLQ). Берите графовый Пайплайн, когда несколько функций образуют воркфлоу с ветвлениями, fan-out, запусками по расписанию или шагом подтверждения человеком (узел Human gate). Все три используют одни и те же функции на одной очереди в Postgres.