HYPERFLEET-774 - feat: aggregation logic

Author: rh-amarin

docs/api-operator-guide.md

@@ -32,6 +32,8 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/statuses
 ```
 
 **Response (201 Created):**
+<details>
+<summary>JSON response 201 created</summary>
 
 ```json
 {
@@ -55,7 +57,7 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/statuses
         "status": "False",
         "reason": "AwaitingAdapters",
         "message": "Waiting for adapters to report status",
-        "observed_generation": 0,
+        "observed_generation": 1,
         "created_time": "2025-01-01T00:00:00Z",
         "last_updated_time": "2025-01-01T00:00:00Z",
         "last_transition_time": "2025-01-01T00:00:00Z"
@@ -65,7 +67,7 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/statuses
         "status": "False",
         "reason": "AwaitingAdapters",
         "message": "Waiting for adapters to report status",
-        "observed_generation": 0,
+        "observed_generation": 1,
         "created_time": "2025-01-01T00:00:00Z",
         "last_updated_time": "2025-01-01T00:00:00Z",
         "last_transition_time": "2025-01-01T00:00:00Z"
@@ -75,6 +77,8 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/statuses
 }
 ```
 
+</details>
+
 **Note**: Status initially has `Available=False` and `Ready=False` conditions until adapters report status.
 
 ### Get Cluster
@@ -83,6 +87,9 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/statuses
 
 **Response (200 OK):**
 
+<details>
+<summary>JSON response</summary>
+
 ```json
 {
   "kind": "Cluster",
@@ -125,6 +132,8 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/statuses
 }
 ```
 
+</details>
+
 ### List Clusters
 
 **GET** `/api/hyperfleet/v1/clusters?page=1&pageSize=10`
@@ -156,6 +165,9 @@ Adapters use this endpoint to report their status.
 
 **Request Body:**
 
+<details>
+<summary>JSON response</summary>
+
 ```json
 {
   "adapter": "validator",
@@ -188,8 +200,13 @@ Adapters use this endpoint to report their status.
 }
 ```
 
+</details>
+
 **Response (201 Created):**
 
+<details>
+<summary>JSON response</summary>
+
 ```json
 {
   "adapter": "validator",
@@ -226,28 +243,9 @@ Adapters use this endpoint to report their status.
 }
 ```
 
-**Note**: The API automatically sets `created_time`, `last_report_time`, and `last_transition_time` fields.
-
-### Status Conditions
-
-The status uses Kubernetes-style conditions instead of a single phase field:
+</details>
 
-- **Ready** - Whether all adapters report successfully at the current generation
-  - `True`: All required adapters report `Available=True` at current spec generation
-  - `False`: One or more adapters report Available=False at current generation
-    - After every spec change, `Ready` becomes `False` since adapters take some time to report at current spec generation
-    - Default value when creating the cluster, when no adapters have reported yet any value
-
-- **Available** - Aggregated adapter result for a common `observed_generation`
-  - `True`: All required adapters report Available=True for the same observed_generation
-  - `False`: At least one adapter reports Available=False when all adapters report the same observed_generation
-    - Default value when creating the cluster, when no adapters have reported yet any value
-
-`Available` keeps its value unchanged in case adapters report from a different `observed_generation` or there is already a mix of `observed_generation` statuses
-
-- e.g. `Available=True` for `observed_generation==1`
-  - One adapter reports `Available=False` for `observed_generation=1` `Available` transitions to `False`
-  - One adapter reports `Available=False` for `observed_generation=2` `Available` keeps its `True` status
+**Note**: The API automatically sets `created_time`, `last_report_time`, and `last_transition_time` fields.
 
 ## NodePool Management
 
@@ -281,6 +279,9 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses
 
 **Response (201 Created):**
 
+<details>
+<summary>JSON response</summary>
+
 ```json
 {
   "kind": "NodePool",
@@ -307,7 +308,7 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses
         "status": "False",
         "reason": "AwaitingAdapters",
         "message": "Waiting for adapters to report status",
-        "observed_generation": 0,
+        "observed_generation": 1,
         "created_time": "2025-01-01T00:00:00Z",
         "last_updated_time": "2025-01-01T00:00:00Z",
         "last_transition_time": "2025-01-01T00:00:00Z"
@@ -317,7 +318,7 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses
         "status": "False",
         "reason": "AwaitingAdapters",
         "message": "Waiting for adapters to report status",
-        "observed_generation": 0,
+        "observed_generation": 1,
         "created_time": "2025-01-01T00:00:00Z",
         "last_updated_time": "2025-01-01T00:00:00Z",
         "last_transition_time": "2025-01-01T00:00:00Z"
@@ -327,12 +328,17 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses
 }
 ```
 
+</details>
+
 ### Get NodePool
 
 **GET** `/api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}`
 
 **Response (200 OK):**
 
+<details>
+<summary>JSON response</summary>
+
 ```json
 {
   "kind": "NodePool",
@@ -373,6 +379,8 @@ POST   /api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses
 }
 ```
 
+</details>
+
 ### Report NodePool Status
 
 **POST** `/api/hyperfleet/v1/clusters/{cluster_id}/nodepools/{nodepool_id}/statuses`

docs/api-resources.md

@@ -9,8 +9,8 @@ import (
 
 // AdapterStatus database model
 type AdapterStatus struct {
-	LastReportTime *time.Time `json:"last_report_time" gorm:"not null"`
-	CreatedTime    *time.Time `json:"created_time" gorm:"not null"`
+	LastReportTime time.Time `json:"last_report_time" gorm:"not null"`
+	CreatedTime    time.Time `json:"created_time" gorm:"not null"`
 	Meta
 	ResourceType       string         `json:"resource_type" gorm:"size:20;index:idx_resource;not null"`
 	ResourceID         string         `json:"resource_id" gorm:"size:255;index:idx_resource;not null"`

pkg/api/adapter_status_types.go

@@ -67,8 +67,8 @@ func ConvertAdapterStatus(
 		Conditions:         conditionsJSON,
 		Data:               dataJSON,
 		Metadata:           metadataJSON,
-		CreatedTime:        &now,
-		LastReportTime:     &now,
+		CreatedTime:        now,
+		LastReportTime:     now,
 	}, nil
 }
 
@@ -138,23 +138,12 @@ func PresentAdapterStatus(adapterStatus *api.AdapterStatus) (openapi.AdapterStat
 		}
 	}
 
-	// Set default times if nil (shouldn't happen in normal operation)
-	createdTime := time.Time{}
-	if adapterStatus.CreatedTime != nil {
-		createdTime = *adapterStatus.CreatedTime
-	}
-
-	lastReportTime := time.Time{}
-	if adapterStatus.LastReportTime != nil {
-		lastReportTime = *adapterStatus.LastReportTime
-	}
-
 	return openapi.AdapterStatus{
 		Adapter:            adapterStatus.Adapter,
 		Conditions:         openapiConditions,
-		CreatedTime:        createdTime,
+		CreatedTime:        adapterStatus.CreatedTime,
 		Data:               &data,
-		LastReportTime:     lastReportTime,
+		LastReportTime:     adapterStatus.LastReportTime,
 		Metadata:           openapiMetadata,
 		ObservedGeneration: adapterStatus.ObservedGeneration,
 	}, nil

pkg/api/presenters/adapter_status.go

@@ -278,8 +278,8 @@ func TestPresentAdapterStatus_Complete(t *testing.T) {
 		Conditions:         conditionsJSON,
 		Data:               dataJSON,
 		Metadata:           metadataJSON,
-		CreatedTime:        &now,
-		LastReportTime:     &now,
+		CreatedTime:        now,
+		LastReportTime:     now,
 	}
 
 	result, err := PresentAdapterStatus(adapterStatus)
@@ -310,8 +310,8 @@ func TestPresentAdapterStatus_Complete(t *testing.T) {
 	Expect(result.LastReportTime.Unix()).To(Equal(now.Unix()))
 }
 
-// TestPresentAdapterStatus_NilTimestamps tests handling of nil timestamps
-func TestPresentAdapterStatus_NilTimestamps(t *testing.T) {
+// TestPresentAdapterStatus_ZeroTimestamps tests that zero timestamps pass through as zero time.Time values.
+func TestPresentAdapterStatus_ZeroTimestamps(t *testing.T) {
 	RegisterTestingT(t)
 
 	adapterStatus := &api.AdapterStatus{
@@ -321,14 +321,12 @@ func TestPresentAdapterStatus_NilTimestamps(t *testing.T) {
 		ObservedGeneration: 5,
 		Conditions:         []byte("[]"),
 		Data:               []byte("{}"),
-		CreatedTime:        nil, // Nil timestamp
-		LastReportTime:     nil, // Nil timestamp
+		// CreatedTime and LastReportTime are zero-valued (unset)
 	}
 
 	result, err := PresentAdapterStatus(adapterStatus)
 	Expect(err).To(BeNil())
 
-	// Verify zero time.Time is returned (not nil)
 	Expect(result.CreatedTime.IsZero()).To(BeTrue())
 	Expect(result.LastReportTime.IsZero()).To(BeTrue())
 }
@@ -345,8 +343,8 @@ func TestPresentAdapterStatus_EmptyConditions(t *testing.T) {
 		ObservedGeneration: 2,
 		Conditions:         []byte("[]"), // Empty array JSON
 		Data:               []byte("{}"),
-		CreatedTime:        &now,
-		LastReportTime:     &now,
+		CreatedTime:        now,
+		LastReportTime:     now,
 	}
 
 	result, err := PresentAdapterStatus(adapterStatus)
@@ -368,8 +366,8 @@ func TestPresentAdapterStatus_EmptyData(t *testing.T) {
 		ObservedGeneration: 3,
 		Conditions:         []byte("[]"),
 		Data:               []byte("{}"), // Empty object JSON
-		CreatedTime:        &now,
-		LastReportTime:     &now,
+		CreatedTime:        now,
+		LastReportTime:     now,
 	}
 
 	result, err := PresentAdapterStatus(adapterStatus)
@@ -410,8 +408,8 @@ func TestPresentAdapterStatus_ConditionStatusConversion(t *testing.T) {
 			ObservedGeneration: 1,
 			Conditions:         conditionsJSON,
 			Data:               []byte("{}"),
-			CreatedTime:        &now,
-			LastReportTime:     &now,
+			CreatedTime:        now,
+			LastReportTime:     now,
 		}
 
 		result, err := PresentAdapterStatus(adapterStatus)
@@ -471,8 +469,8 @@ func TestPresentAdapterStatus_MalformedConditions(t *testing.T) {
 		ObservedGeneration: 5,
 		Conditions:         []byte("{invalid json}"), // Malformed JSON
 		Data:               []byte("{}"),
-		CreatedTime:        &now,
-		LastReportTime:     &now,
+		CreatedTime:        now,
+		LastReportTime:     now,
 	}
 	adapterStatus.ID = "adapter-status-malformed-conditions"
 
@@ -494,8 +492,8 @@ func TestPresentAdapterStatus_MalformedData(t *testing.T) {
 		ObservedGeneration: 5,
 		Conditions:         []byte("[]"),
 		Data:               []byte("{not valid json"), // Malformed JSON
-		CreatedTime:        &now,
-		LastReportTime:     &now,
+		CreatedTime:        now,
+		LastReportTime:     now,
 	}
 	adapterStatus.ID = "adapter-status-malformed-data"
 
@@ -518,8 +516,8 @@ func TestPresentAdapterStatus_MalformedMetadata(t *testing.T) {
 		Conditions:         []byte("[]"),
 		Data:               []byte("{}"),
 		Metadata:           []byte("[{incomplete"), // Malformed JSON
-		CreatedTime:        &now,
-		LastReportTime:     &now,
+		CreatedTime:        now,
+		LastReportTime:     now,
 	}
 	adapterStatus.ID = "adapter-status-malformed-metadata"