Runner callback api

lib/trento_web/controllers/cluster_controller.ex

@@ -42,7 +42,7 @@ defmodule TrentoWeb.ClusterController do
     responses: [
       accepted:
         {"The Command has been accepted and the Requested execution is scheduled",
-         "application/json", %OpenApiSpex.Schema{example: %{}}},
+         "application/json", Schema.Common.EmptyResponse},
       bad_request:
         {"Something went wrong while triggering an Execution Request", "application/json",
          Schema.Common.BadRequestResponse}
@@ -63,7 +63,27 @@ defmodule TrentoWeb.ClusterController do
     end
   end
 
-  operation :runner_callback, false
+  operation :runner_callback,
+    summary: "Hook for Checks Execution progress updates",
+    tags: ["Checks"],
+    description:
+      "The Runner executing the Checks Selection on the target infrastructure, publishes updates about the progress of the Execution.",
+    parameters: [
+      callback_event: [
+        in: :body,
+        required: true,
+        type: Schema.Runner.CallbackEvent
+      ]
+    ],
+    responses: [
+      accepted:
+        {"The Operation has been accepted, and the proper followup processes will trigger",
+         "application/json", Schema.Common.EmptyResponse},
+      bad_request:
+        {"Something went wrong during the operation", "application/json",
+         Schema.Common.BadRequestResponse}
+    ]
+
   @spec runner_callback(Plug.Conn.t(), map) :: Plug.Conn.t()
   def runner_callback(conn, params) do
     case Checks.handle_callback(params) do
@@ -94,7 +114,7 @@ defmodule TrentoWeb.ClusterController do
     responses: [
       accepted:
         {"The Selection has been successfully collected", "application/json",
-         %OpenApiSpex.Schema{example: %{}}},
+         Schema.Common.EmptyResponse},
       bad_request:
         {"Something went wrong with the collection of the Checks Selection", "application/json",
          Schema.Common.BadRequestResponse}

lib/trento_web/openapi/schema/checks.ex

@@ -60,7 +60,7 @@ defmodule TrentoWeb.OpenApi.Schema.Checks do
         },
         result: %Schema{
           type: :string,
-          description: "Host's last heartbeat status",
+          description: "The Result of the Check",
           enum: [:passing, :warning, :critical, :skipped, :unknown]
         },
         inserted_at: %Schema{

lib/trento_web/openapi/schema/common.ex

@@ -4,6 +4,12 @@ defmodule TrentoWeb.OpenApi.Schema.Common do
   require OpenApiSpex
   alias OpenApiSpex.Schema
 
+  defmodule EmptyResponse do
+    @moduledoc false
+
+    OpenApiSpex.schema(%{example: %{}})
+  end
+
   defmodule BadRequestResponse do
     @moduledoc false
 

lib/trento_web/openapi/schema/runner.ex

@@ -0,0 +1,114 @@
+defmodule TrentoWeb.OpenApi.Schema.Runner do
+  @moduledoc false
+
+  require OpenApiSpex
+  alias OpenApiSpex.Schema
+
+  defmodule ResourceIdentifier do
+    @moduledoc false
+
+    OpenApiSpex.schema(%{
+      type: :string,
+      format: :uuid
+    })
+  end
+
+  defmodule ExecutionStarted do
+    @moduledoc false
+
+    OpenApiSpex.schema(%{
+      title: "ExecutionStarted",
+      description:
+        "The execution of the Check Selection started on the target infrastructure, for a specific Cluster",
+      type: :object,
+      properties: %{
+        cluster_id: ResourceIdentifier
+      }
+    })
+  end
+
+  defmodule ExecutionCompleted do
+    @moduledoc false
+
+    OpenApiSpex.schema(%{
+      title: "ExecutionCompleted",
+      description:
+        "The execution of the Check Selection completed on the target infrastructure, for a specific Cluster",
+      type: :object,
+      properties: %{
+        cluster_id: ResourceIdentifier,
+        hosts: %Schema{
+          type: :array,
+          items: %Schema{
+            type: :object,
+            properties: %{
+              host_id: ResourceIdentifier,
+              reachable: %Schema{type: :boolean},
+              msg: %Schema{type: :string},
+              results: %Schema{
+                type: :array,
+                items: %Schema{
+                  type: :object,
+                  properties: %{
+                    check_id: %Schema{type: :string},
+                    result: %Schema{
+                      type: :string,
+                      description: "The Result of the Check",
+                      enum: [:passing, :warning, :critical, :skipped]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    })
+  end
+
+  defmodule CallbackEvent do
+    @moduledoc false
+
+    OpenApiSpex.schema(%{
+      title: "CallbackEvent",
+      description:
+        "Represents a progress update sent during Checks Execution to notify the system",
+      type: :object,
+      properties: %{
+        event: %Schema{type: :string, enum: [:execution_started, :execution_completed]},
+        execution_id: %Schema{
+          type: :string,
+          format: :uuid,
+          description:
+            "The identifier of an execution. It has been provided on execution request."
+        },
+        payload: %Schema{
+          oneOf: [
+            ExecutionStarted,
+            ExecutionCompleted
+          ]
+        }
+      },
+      example: %{
+        event: "execution_completed",
+        execution_id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
+        payload: %{
+          cluster_id: "146a4e9f-9cdb-466e-9601-9af94b8b4f65",
+          hosts: [
+            %{
+              host_id: "ae44943b-d866-4878-88c9-b4d49006460d",
+              reachable: true,
+              msg: "Some message",
+              results: [
+                %{
+                  check_id: "ACH3CK1D",
+                  result: :passing
+                }
+              ]
+            }
+          ]
+        }
+      }
+    })
+  end
+end