feat: new task endpoints (#249)

Author: jason-lynch

api/apiv1/design/api.go

@@ -526,6 +526,156 @@ var _ = g.Service("control-plane", func() {
 			g.Meta("openapi:tag:Database")
 		})
 	})
+	g.Method("list-host-tasks", func() {
+		g.Description("Lists all tasks for a host.")
+		g.Meta("openapi:summary", "List host tasks")
+		g.Payload(func() {
+			g.Attribute("host_id", Identifier, func() {
+				g.Description("ID of the host to list tasks for.")
+				g.Example("host-1")
+			})
+			g.Attribute("after_task_id", g.String, func() {
+				g.Description("ID of the task to start from.")
+				g.Format(g.FormatUUID)
+				g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
+			})
+			g.Attribute("limit", g.Int, func() {
+				g.Description("Maximum number of tasks to return.")
+				g.Example(100)
+			})
+			g.Attribute("sort_order", g.String, func() {
+				g.Enum("asc", "ascend", "ascending", "desc", "descend", "descending")
+				g.Description("Sort order for the tasks.")
+				g.Example("ascend")
+			})
+
+			g.Required("host_id")
+		})
+		g.Result(ListHostTasksResponse)
+		g.Error("cluster_not_initialized")
+		g.Error("invalid_input")
+		g.Error("not_found")
+
+		g.HTTP(func() {
+			g.GET("/v1/hosts/{host_id}/tasks")
+			g.Param("after_task_id")
+			g.Param("limit")
+			g.Param("sort_order")
+
+			g.Meta("openapi:tag:Host")
+		})
+	})
+
+	g.Method("get-host-task", func() {
+		g.Description("Returns information about a particular task for a host.")
+		g.Meta("openapi:summary", "Get host task")
+		g.Payload(func() {
+			g.Attribute("host_id", Identifier, func() {
+				g.Description("ID of the host the task belongs to.")
+				g.Example("host-1")
+			})
+			g.Attribute("task_id", g.String, func() {
+				g.Description("ID of the task to get.")
+				g.Format(g.FormatUUID)
+				g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
+			})
+
+			g.Required("host_id", "task_id")
+		})
+		g.Result(Task)
+		g.Error("cluster_not_initialized")
+		g.Error("invalid_input")
+		g.Error("not_found")
+
+		g.HTTP(func() {
+			g.GET("/v1/hosts/{host_id}/tasks/{task_id}")
+
+			g.Meta("openapi:tag:Host")
+		})
+	})
+
+	g.Method("get-host-task-log", func() {
+		g.Description("Returns the log of a particular task for a host.")
+		g.Meta("openapi:summary", "Get host task logs")
+		g.Payload(func() {
+			g.Attribute("host_id", Identifier, func() {
+				g.Description("ID of the host to get the task logs for.")
+				g.Example("host-1")
+			})
+			g.Attribute("task_id", g.String, func() {
+				g.Description("ID of the task to get the logs for.")
+				g.Format(g.FormatUUID)
+				g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
+			})
+			g.Attribute("after_entry_id", g.String, func() {
+				g.Description("ID of the entry to start from.")
+				g.Format(g.FormatUUID)
+				g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
+			})
+			g.Attribute("limit", g.Int, func() {
+				g.Description("Maximum number of entries to return.")
+				g.Example(100)
+			})
+
+			g.Required("host_id", "task_id")
+		})
+		g.Result(TaskLog)
+		g.Error("cluster_not_initialized")
+		g.Error("invalid_input")
+		g.Error("not_found")
+
+		g.HTTP(func() {
+			g.GET("/v1/hosts/{host_id}/tasks/{task_id}/logs")
+			g.Param("after_entry_id")
+			g.Param("limit")
+
+			g.Meta("openapi:tag:Host")
+		})
+	})
+
+	g.Method("list-tasks", func() {
+		g.Description("Lists tasks across all scopes with optional filtering by scope and entity ID.")
+		g.Meta("openapi:summary", "List tasks")
+		g.Payload(func() {
+			g.Attribute("scope", g.String, func() {
+				g.Enum("database", "host")
+				g.Description("Optional scope to filter tasks (database or host).")
+				g.Example("database")
+			})
+			g.Attribute("entity_id", Identifier, func() {
+				g.Description("Optional entity ID to filter tasks. Requires scope to be set.")
+				g.Example("my-app")
+			})
+			g.Attribute("after_task_id", g.String, func() {
+				g.Description("ID of the task to start from.")
+				g.Format(g.FormatUUID)
+				g.Example("3c875a27-f6a6-4c1c-ba5f-6972fb1fc348")
+			})
+			g.Attribute("limit", g.Int, func() {
+				g.Description("Maximum number of tasks to return.")
+				g.Example(100)
+			})
+			g.Attribute("sort_order", g.String, func() {
+				g.Enum("asc", "ascend", "ascending", "desc", "descend", "descending")
+				g.Description("Sort order for the tasks.")
+				g.Example("ascend")
+			})
+		})
+		g.Result(ListTasksResponse)
+		g.Error("cluster_not_initialized")
+		g.Error("invalid_input")
+
+		g.HTTP(func() {
+			g.GET("/v1/tasks")
+			g.Param("scope")
+			g.Param("entity_id")
+			g.Param("after_task_id")
+			g.Param("limit")
+			g.Param("sort_order")
+
+			g.Meta("openapi:tag:System")
+		})
+	})
 
 	g.Method("restore-database", func() {
 		g.Description("Perform an in-place restore of one or more nodes using the given restore configuration.")

api/apiv1/design/task.go

@@ -310,3 +310,52 @@ var ListDatabaseTasksResponse = g.Type("ListDatabaseTasksResponse", func() {
 		},
 	})
 })
+
+var ListHostTasksResponse = g.Type("ListHostTasksResponse", func() {
+	g.Attribute("tasks", g.ArrayOf(Task))
+
+	g.Example(map[string]any{
+		"tasks": []map[string]any{
+			{
+				"completed_at": "2025-06-18T17:54:36Z",
+				"created_at":   "2025-06-18T17:54:28Z",
+				"scope":        "host",
+				"entity_id":    "host-1",
+				"host_id":      "host-1",
+				"status":       "completed",
+				"task_id":      "0197842d-9082-7496-b787-77bd2e11809f",
+				"type":         "remove_host",
+			},
+		},
+	})
+})
+
+var ListTasksResponse = g.Type("ListTasksResponse", func() {
+	g.Attribute("tasks", g.ArrayOf(Task))
+
+	g.Example(map[string]any{
+		"tasks": []map[string]any{
+			{
+				"completed_at": "2025-06-18T17:54:36Z",
+				"created_at":   "2025-06-18T17:54:28Z",
+				"scope":        "database",
+				"entity_id":    "storefront",
+				"database_id":  "storefront",
+				"instance_id":  "storefront-n1-689qacsi",
+				"status":       "completed",
+				"task_id":      "0197842d-9082-7496-b787-77bd2e11809f",
+				"type":         "node_backup",
+			},
+			{
+				"completed_at": "2025-06-18T17:54:36Z",
+				"created_at":   "2025-06-18T17:54:28Z",
+				"scope":        "host",
+				"entity_id":    "host-1",
+				"host_id":      "host-1",
+				"status":       "completed",
+				"task_id":      "0197842d-9082-7496-b787-77bd2e11809f",
+				"type":         "remove_host",
+			},
+		},
+	})
+})