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,42 @@
+# 02. Tubulus Stabilization & The "Iron Logic" of Polling
+
+**Date:** 2026-01-27
+**Operator:** GitHub Copilot (Gemini 3 Pro)
+**Task:** Fix Tubulus Creation and Polling
+
+## The Problem
+The `nubes_tubulus_instance` resource was unstable:
+1.  **Timeouts**: Operations would finish, but the provider kept waiting until the hard timeout.
+2.  **Bad Requests**: Valid inputs (empty maps) were rejected by the API.
+3.  **Terraform Errors**: "Provider returned invalid result object" (Unknown values) after Apply.
+
+## The Investigation (HAR Analysis)
+We analyzed 14 HAR files covering various scenarios (Success, Failure, Fast, Slow).
+Key finding: The API has a strict contract regarding `dtFinish`.
+- `dtFinish` appears exactly when the operation ends.
+- Waiting for `status="COMPLETED"` or similar text fields is unreliable.
+- `isSuccessful` is only valid after `dtFinish` is present.
+
+## The Solution
+1.  **Refactored Polling (`waitForOperationAndInstanceStatus`)**:
+    - Implemented strict check: If `dtFinish != nil`, stop waiting.
+    - If `isSuccessful` is true -> Success. Else -> Error.
+    - Removed arbitrary sleeps and secondary status checks.
+
+2.  **Fixed Parameter Submission (`submitOperationParams`)**:
+    - Restored logic to send `"{}"` for empty map/json types.
+    - Added fallback mapping using `SvcOperationCfsParam` key.
+
+3.  **Fixed Instance Reading (`readInstance`)**:
+    - Added `?fields=...explainedStatus` to GET request to ensure status is returned.
+    - Updated `InstanceResponse` struct to match API wrapper `{"instance": {...}}`.
+
+4.  **Fixed Terraform State (`Create`)**:
+    - Explicitly set all `Unknown` computed fields to `Null` at the end of resource creation to satisfy Terraform's safety checks.
+
+## Outcome
+Test 014 (Lifecycle Create) passed successfully in 33 seconds.
+
+## Directives for Future
+- **DO NOT TOUCH** `tubulus_resource.go` polling logic. It is based on hard evidence.
+- Always check `dtFinish` for Nubes operations.