add: documentation

2026-06-30 15:45:24 +04:00
parent 540c1f7293
commit ca276d200f
1055 changed files with 47294 additions and 0 deletions
@@ -0,0 +1,44 @@
+# Tubulus (Bolvanka) & Polling Logic Discovery
+
+## Overview
+This document describes the critical discovery made regarding the Nubes Tubulus (Bolvanka) service and, more importantly, the strict polling logic required to interact with the Nubes API reliably.
+
+## The "Bolvanka" Service
+Tubulus is a test service ("Bolvanka") that mimics long-running operations. It is used to test the provider's lifecycle management capabilities, including:
+- Creating instances with delays.
+- Handling failures at different stages (Start, InProgress).
+- Soft Delete (Resume) logic.
+
+## Critical Polling Logic (The "Iron Logic")
+
+After analyzing 14+ HAR files (HTTP Archives) from real API interactions, the following **INVARIANT** behavior was established for Instance Operations (`instanceOperations`):
+
+### 1. The `dtFinish` Rule
+*   **dtFinish is NULL** while the operation is running (PENDING, IN_PROGRESS).
+*   **dtFinish is NOT NULL** (contains a timestamp) **IMMEDIATELY** when the operation finishes.
+*   **IMPLICATION**: `dtFinish` is the **ONLY** reliable source of truth for completion. Do not rely on `status`, `isInProgress`, or `isPending`.
+
+### 2. The Success/Failure Rule
+Once `dtFinish` is detected (not null), the success is determined solely by `isSuccessful`:
+*   **isSuccessful == true**: Operation succeeded. Proceed to read instance.
+*   **isSuccessful == false**: Operation failed.
+*   **isSuccessful == null**: Operation failed (or indeterminate state treated as failure).
+
+### 3. The Instance Status Rule
+*   Do NOT check instance status while the operation is running. It will be "not created" or "suspended".
+*   Only after Operation Success (dtFinish != nil && isSuccessful == true) should you expect the Instance status to be `running`.
+
+## Parameter Submission Logic
+To successfully execute an operation (`run`), parameters must be submitted correctly:
+1.  **Empty Maps/JSONs**: Must be sent as `"{}"`. Sending `""` causes `400 Bad Request`.
+2.  **Empty Lists**: Must be sent as `"[]"`.
+3.  **Mapping keys**: The API returns parameters with `code`, `name`, and `svcOperationCfsParam`. Terraform resource attributes must be mapped to one of these (fallback order: Code -> Name -> SvcOperationCfsParam).
+
+## Terraform "Unknown" Values
+The Terraform Provider Framework requires that all attributes marked as `Computed` have a known value after `Apply`.
+*   The Nubes API `readInstance` does NOT return fields like `fail_at_start`, `duration_ms`, etc.
+*   **SOLUTION**: In the `Create` method, after reading the instance status, all optional computed fields that are still `Unknown` must be explicitly set to `Null`.
+
+## Reference Code
+See `internal/provider/tubulus_resource.go` for the implementation.
+**DO NOT CHANGE THE POLLING OR PARAMETER LOGIC WITHOUT REVIEWING THIS DOCUMENT.**