From 795b4a41b72dcc786849e5f6bf69a24eea114ca3 Mon Sep 17 00:00:00 2001
From: Alex Auvolat <lx@deuxfleurs.fr>
Date: Wed, 12 Mar 2025 10:52:58 +0100
Subject: [PATCH] admin api: add special endpoints to openapi spec

---
 doc/api/garage-admin-v2.json | 68 ++++++++++++++++++++++++++++++++++++
 src/api/admin/openapi.rs     | 57 ++++++++++++++++++++++++++++++
 2 files changed, 125 insertions(+)

diff --git a/doc/api/garage-admin-v2.json b/doc/api/garage-admin-v2.json
index 91d92e11..9379fee5 100644
--- a/doc/api/garage-admin-v2.json
+++ b/doc/api/garage-admin-v2.json
@@ -21,6 +21,74 @@
     }
   ],
   "paths": {
+    "/check": {
+      "get": {
+        "tags": [
+          "Special endpoints"
+        ],
+        "description": "\nStatic website domain name check. Checks whether a bucket is configured to serve\na static website for the requested domain. This is used by reverse proxies such\nas Caddy or Tricot, to avoid requesting TLS certificates for domain names that\ndo not correspond to an actual website.\n    ",
+        "operationId": "CheckDomain",
+        "parameters": [
+          {
+            "name": "domain",
+            "in": "path",
+            "description": "The domain name to check for",
+            "required": true
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The domain name redirects to a static website bucket"
+          },
+          "400": {
+            "description": "No static website bucket exists for this domain"
+          }
+        },
+        "security": [
+          {}
+        ]
+      }
+    },
+    "/health": {
+      "get": {
+        "tags": [
+          "Special endpoints"
+        ],
+        "description": "\nCheck cluster health. The status code returned by this function indicates\nwhether this Garage daemon can answer API requests.\nGarage will return `200 OK` even if some storage nodes are disconnected,\nas long as it is able to have a quorum of nodes for read and write operations.\n    ",
+        "operationId": "Health",
+        "responses": {
+          "200": {
+            "description": "Garage is able to answer requests"
+          },
+          "503": {
+            "description": "This Garage daemon is not able to handle requests"
+          }
+        },
+        "security": [
+          {}
+        ]
+      }
+    },
+    "/metrics": {
+      "get": {
+        "tags": [
+          "Special endpoints"
+        ],
+        "description": "Prometheus metrics endpoint",
+        "operationId": "Metrics",
+        "responses": {
+          "200": {
+            "description": "Garage daemon metrics exported in Prometheus format"
+          }
+        },
+        "security": [
+          {},
+          {
+            "bearerAuth": []
+          }
+        ]
+      }
+    },
     "/v2/AddBucketAlias": {
       "post": {
         "tags": [
diff --git a/src/api/admin/openapi.rs b/src/api/admin/openapi.rs
index 24319817..77d8dce8 100644
--- a/src/api/admin/openapi.rs
+++ b/src/api/admin/openapi.rs
@@ -5,6 +5,59 @@ use utoipa::{Modify, OpenApi};
 
 use crate::api::*;
 
+// **********************************************
+//      Special endpoints
+// **********************************************
+
+#[utoipa::path(get,
+    path = "/metrics",
+    tag = "Special endpoints",
+    description = "Prometheus metrics endpoint",
+    security((), ("bearerAuth" = [])),
+	responses(
+            (status = 200, description = "Garage daemon metrics exported in Prometheus format"),
+        ),
+)]
+fn Metrics() -> () {}
+
+#[utoipa::path(get,
+    path = "/health",
+    tag = "Special endpoints",
+    description = "
+Check cluster health. The status code returned by this function indicates
+whether this Garage daemon can answer API requests.
+Garage will return `200 OK` even if some storage nodes are disconnected,
+as long as it is able to have a quorum of nodes for read and write operations.
+    ",
+    security(()),
+	responses(
+            (status = 200, description = "Garage is able to answer requests"),
+            (status = 503, description = "This Garage daemon is not able to handle requests")
+        ),
+)]
+fn Health() -> () {}
+
+#[utoipa::path(get,
+    path = "/check",
+    tag = "Special endpoints",
+    description = "
+Static website domain name check. Checks whether a bucket is configured to serve
+a static website for the requested domain. This is used by reverse proxies such
+as Caddy or Tricot, to avoid requesting TLS certificates for domain names that
+do not correspond to an actual website.
+    ",
+    params(
+        ("domain", description = "The domain name to check for"),
+    ),
+    security(()),
+	responses(
+            (status = 200, description = "The domain name redirects to a static website bucket"),
+            (status = 400, description = "No static website bucket exists for this domain")
+        ),
+)]
+fn CheckDomain() -> () {}
+
+
 // **********************************************
 //      Cluster operations
 // **********************************************
@@ -794,6 +847,10 @@ impl Modify for SecurityAddon {
     modifiers(&SecurityAddon),
     security(("bearerAuth" = [])),
     paths(
+        // Special ops
+        Metrics,
+        Health,
+        CheckDomain,
         // Cluster operations
         GetClusterHealth,
         GetClusterStatus,