docs(architecture): зафиксированы решения Q1/Q2/Q4

- Q1: POST не ретраится (не идемпотентен; Idempotency-Key у API нет) — решение.
- Q2: при ошибке после POST /instanceOperations и до run операция остаётся черновиком;
  отмены нет (ни в коде, ни в HAR — DELETE /instanceOperations/{uid} отсутствует).
- Q4: единый контракт жизненного цикла — keep_on_destroy + suspend_on_destroy;
  delete_strategy (YAML) = маппинг на них (noop_warn/inverse/error).
This commit is contained in:
Repinoid
2026-09-30 20:53:31 +03:00
parent 9da97663c6
commit 7a6f6650c6
+21 -9
View File
@@ -125,9 +125,14 @@ Each operation has a kind:
Gateway may temporarily reject valid JWT tokens.
- Implemented: `isRetryable` (`core/http.go`) includes 401 alongside {429, 502, 503, 504};
retry applies to GET requests only.
- Network errors and HTTP retryable statuses are retried for **GET only**. POST is not
retried (a blind retry of the creating `POST /instanceOperations` could duplicate an
operation — see open question on idempotency).
- Network errors and HTTP retryable statuses are retried for **GET only** (decided
2026-09-30). POST is NEVER retried: `POST /instanceOperations` is not idempotent, and a
blind retry would duplicate the operation. The API has no `Idempotency-Key` support.
- Draft operation on failure (decided 2026-09-30): if an error occurs after
`POST /instanceOperations` but before `.../run`, the operation remains created but was
never executed (the instance is unaffected). No cancellation API is known — neither the
provider code nor the captured HAR contain `DELETE /instanceOperations/{uid}`.
- Transient 401 is retried for GET (see `isRetryable`).
### Generated Code Resilience
@@ -227,14 +232,21 @@ From the unified YAML, generate:
## Lifecycle Vocabulary (single contract)
⚠️ The destroy-behaviour vocabulary is currently INCONSISTENT across resource kinds:
**Target contract (decided 2026-09-30):** two runtime flags — `keep_on_destroy` and
`suspend_on_destroy` — express destroy behaviour for ALL resource kinds. The compile-time
`delete_strategy` (YAML) is a generator input that MAPS onto them:
1. generated instance resources: runtime flags `suspend_on_destroy` / `keep_on_destroy`;
2. generated modifiers: compile-time `delete_strategy` (no runtime flag);
3. hand-written modifiers: runtime `keep_on_destroy` only.
| `delete_strategy` | Runtime meaning |
|---|---|
| `noop_warn` | `keep_on_destroy = true` (platform effect left untouched) |
| `inverse` | normal destroy (inverse modify is performed) |
| `error` | destroy refused with a validation error |
All three express the same intent ("what happens to the platform effect on destroy").
Canonical direction: one unified vocabulary/contract for all resource kinds.
Current state (2026-09-30) — to be migrated:
1. generated instance resources: already `suspend_on_destroy` / `keep_on_destroy`;
2. generated modifiers: `delete_strategy` only (no runtime flag yet);
3. hand-written modifiers: already `keep_on_destroy`.
## Non-Negotiable Rules