pipeline-manager: fix checkpoint sync docs

swanandx · gz · commit 899da3689c86 · 2026-03-26T17:59:25.000Z
Signed-off-by: Swanand Mulay &lt;73115739+swanandx@users.noreply.github.com&gt;
diff --git a/crates/pipeline-manager/src/api/endpoints/pipeline_interaction.rs b/crates/pipeline-manager/src/api/endpoints/pipeline_interaction.rs
@@ -1126,7 +1126,7 @@ pub(crate) async fn get_checkpoint_status(
         (status = OK
          , description = "Checkpoint sync status retrieved successfully"
          , content_type = "application/json"
-         , body = CheckpointStatus),
+         , body = CheckpointSyncStatus),
         (status = NOT_FOUND
             , description = "Pipeline with that name does not exist"
             , body = ErrorResponse
diff --git a/crates/pipeline-manager/src/api/main.rs b/crates/pipeline-manager/src/api/main.rs
@@ -425,8 +425,10 @@ It contains the following fields:
         feldera_types::completion_token::CompletionStatus,
         feldera_types::completion_token::CompletionStatusResponse,
         feldera_types::checkpoint::CheckpointStatus,
+        feldera_types::checkpoint::CheckpointSyncStatus,
         feldera_types::checkpoint::CheckpointResponse,
         feldera_types::checkpoint::CheckpointFailure,
+        feldera_types::checkpoint::CheckpointSyncFailure,
         feldera_types::checkpoint::CheckpointMetadata,
         feldera_types::transaction::StartTransactionResponse,
         feldera_types::transaction::CommitProgressSummary,
diff --git a/docs.feldera.com/docs/pipelines/checkpoint-sync.md b/docs.feldera.com/docs/pipelines/checkpoint-sync.md
@@ -283,28 +283,57 @@ The status of the sync operation can be checked by making a `GET` request to:
 curl http://localhost/v0/pipelines/{PIPELINE_NAME}/checkpoint/sync_status
 ```
 
+### Response fields
+
+| Field      | Type            | Description                                                                                                  |
+| ---------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
+| `success`  | `uuid \| null`  | UUID of the most recently successful manually triggered checkpoint sync (`POST /checkpoint/sync`).           |
+| `failure`  | `object \| null`| Details of the most recently failed manually triggered checkpoint sync. Contains `uuid` and `error` fields.  |
+| `periodic` | `uuid \| null`  | UUID of the most recently successful automatic periodic checkpoint sync (configured via `push_interval`).    |
+
+`success` and `periodic` track different sync mechanisms:
+- `success` is updated only by manual syncs triggered via `POST /checkpoint/sync`.
+- `periodic` is updated only by automatic syncs configured via `push_interval`.
+
 ### Response examples
 
-**In Progress:**
+**No syncs yet:**
 
 ```json
-{ "success": null, "failure": null }
+{ "success": null, "failure": null, "periodic": null }
 ```
 
-**Success:**
+**Successful manual sync:**
 
 ```json
-{ "success": "019779b4-8760-75f2-bdf0-71b825e63610", "failure": null }
+{ "success": "019779b4-8760-75f2-bdf0-71b825e63610", "failure": null, "periodic": null }
 ```
 
-**Failure:**
+**Failed manual sync:**
 
 ```json
 {
   "success": null,
   "failure": {
     "uuid": "019779c1-8317-7a71-bd78-7b971f4a3c43",
     "error": "Error pushing checkpoint to object store: ... SignatureDoesNotMatch ..."
-  }
+  },
+  "periodic": null
+}
+```
+
+**Automatic periodic sync only (no manual syncs):**
+
+```json
+{ "success": null, "failure": null, "periodic": "019779c1-8317-7a71-bd78-7b971f4a3c43" }
+```
+
+**Both manual and automatic syncs:**
+
+```json
+{
+  "success": "019779b4-8760-75f2-bdf0-71b825e63610",
+  "failure": null,
+  "periodic": "019779c1-8317-7a71-bd78-7b971f4a3c43"
 }
 ```
diff --git a/openapi.json b/openapi.json
@@ -2310,7 +2310,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/CheckpointStatus"
+                  "$ref": "#/components/schemas/CheckpointSyncStatus"
                 }
               }
             }
@@ -6829,6 +6829,51 @@
           }
         }
       },
+      "CheckpointSyncFailure": {
+        "type": "object",
+        "description": "Information about a failed checkpoint sync.",
+        "required": [
+          "uuid",
+          "error"
+        ],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Error message associated with the failure."
+          },
+          "uuid": {
+            "type": "string",
+            "format": "uuid",
+            "description": "UUID of the failed checkpoint."
+          }
+        }
+      },
+      "CheckpointSyncStatus": {
+        "type": "object",
+        "description": "Checkpoint status returned by the `/checkpoint/sync_status` endpoint.",
+        "properties": {
+          "failure": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/CheckpointSyncFailure"
+              }
+            ],
+            "nullable": true
+          },
+          "periodic": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Most recently successful automated periodic checkpoint sync.",
+            "nullable": true
+          },
+          "success": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Most recently successful checkpoint sync.",
+            "nullable": true
+          }
+        }
+      },
       "Chunk": {
         "type": "object",
         "description": "A set of updates to a SQL table or view.\n\nThe `sequence_number` field stores the offset of the chunk relative to the\nstart of the stream and can be used to implement reliable delivery.\nThe payload is stored in the `bin_data`, `text_data`, or `json_data` field\ndepending on the data format used.",
