tf_provider/docs/20_discovery/tubulus_and_polling_logic.md

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.