feat: add help for http api

GreptimeTeam · Nov 1, 2023 · 5a8974c · 5a8974c
1 parent b365ac6
commit 5a8974c
Show file tree

Hide file tree

Showing 6 changed files with 102 additions and 40 deletions.
diff --git a/src/meta-srv/src/bootstrap.rs b/src/meta-srv/src/bootstrap.rs
@@ -30,6 +30,7 @@ use tokio::net::TcpListener;
 use tokio::select;
 use tokio::sync::mpsc::{self, Receiver, Sender};
 use tonic::transport::server::{Router, TcpIncoming};
+use common_telemetry::info;
 
 use crate::election::etcd::EtcdElection;
 use crate::lock::etcd::EtcdLock;
@@ -134,6 +135,8 @@ pub async fn bootstrap_meta_srv_with_router(
         .await
         .context(error::TcpBindSnafu { addr: bind_addr })?;
 
+    info!("gRPC server is bound to: {bind_addr}");
+
     let incoming =
         TcpIncoming::from_listener(listener, true, None).context(error::TcpIncomingSnafu)?;
 

diff --git a/src/meta-srv/src/service/admin.rs b/src/meta-srv/src/service/admin.rs
@@ -42,12 +42,12 @@ pub fn make_admin_service(meta_srv: MetaSrv) -> Admin {
         },
     );
 
-    let router = router.route(
-        "/heartbeat",
-        heartbeat::HeartBeatHandler {
-            meta_peer_client: meta_srv.meta_peer_client().clone(),
-        },
-    );
+    let handler = heartbeat::HeartBeatHandler {
+        meta_peer_client: meta_srv.meta_peer_client().clone(),
+    };
+    let router = router
+        .route("/heartbeat", handler.clone())
+        .route("/heartbeat/help", handler);
 
     let router = router.route(
         "/catalogs",
@@ -56,26 +56,26 @@ pub fn make_admin_service(meta_srv: MetaSrv) -> Admin {
         },
     );
 
-    let router = router.route(
-        "/schemas",
-        meta::SchemasHandler {
-            table_metadata_manager: meta_srv.table_metadata_manager().clone(),
-        },
-    );
-
-    let router = router.route(
-        "/tables",
-        meta::TablesHandler {
-            table_metadata_manager: meta_srv.table_metadata_manager().clone(),
-        },
-    );
-
-    let router = router.route(
-        "/table",
-        meta::TableHandler {
-            table_metadata_manager: meta_srv.table_metadata_manager().clone(),
-        },
-    );
+    let handler = meta::SchemasHandler {
+        table_metadata_manager: meta_srv.table_metadata_manager().clone(),
+    };
+    let router = router
+        .route("/schemas", handler.clone())
+        .route("/schemas/help", handler);
+
+    let handler = meta::TablesHandler {
+        table_metadata_manager: meta_srv.table_metadata_manager().clone(),
+    };
+    let router = router
+        .route("/tables", handler.clone())
+        .route("/tables/help", handler);
+
+    let handler = meta::TableHandler {
+        table_metadata_manager: meta_srv.table_metadata_manager().clone(),
+    };
+    let router = router
+        .route("/table", handler.clone())
+        .route("/table/help", handler);
 
     let router = router.route(
         "/leader",
@@ -84,12 +84,12 @@ pub fn make_admin_service(meta_srv: MetaSrv) -> Admin {
         },
     );
 
-    let router = router.route(
-        "/route",
-        route::RouteHandler {
-            table_metadata_manager: meta_srv.table_metadata_manager().clone(),
-        },
-    );
+    let handler = route::RouteHandler {
+        table_metadata_manager: meta_srv.table_metadata_manager().clone(),
+    };
+    let router = router
+        .route("/route", handler.clone())
+        .route("/route/help", handler);
 
     let router = router.route(
         "/inactive-regions/view",

diff --git a/src/meta-srv/src/service/admin/heartbeat.rs b/src/meta-srv/src/service/admin/heartbeat.rs
@@ -21,8 +21,9 @@ use tonic::codegen::http;
 use crate::cluster::MetaPeerClientRef;
 use crate::error::{self, Result};
 use crate::keys::StatValue;
-use crate::service::admin::HttpHandler;
+use crate::service::admin::{util, HttpHandler};
 
+#[derive(Clone)]
 pub struct HeartBeatHandler {
     pub meta_peer_client: MetaPeerClientRef,
 }
@@ -31,9 +32,18 @@ pub struct HeartBeatHandler {
 impl HttpHandler for HeartBeatHandler {
     async fn handle(
         &self,
-        _: &str,
+        path: &str,
         params: &HashMap<String, String>,
     ) -> Result<http::Response<String>> {
+        if path.ends_with("/help") {
+            return util::to_text_response(
+                r#"
+            - GET /heartbeat
+            - GET /heartbeat?addr=127.0.0.1:3001
+            "#,
+            );
+        }
+
         let stat_kvs = self.meta_peer_client.get_all_dn_stat_kvs().await?;
         let mut stat_vals: Vec<StatValue> = stat_kvs.into_values().collect();
 

diff --git a/src/meta-srv/src/service/admin/meta.rs b/src/meta-srv/src/service/admin/meta.rs
@@ -23,21 +23,25 @@ use store_api::storage::{RegionId, TableId};
 use tonic::codegen::http;
 
 use crate::error;
-use crate::error::{InvalidHttpBodySnafu, ParseNumSnafu, Result, TableMetadataManagerSnafu};
+use crate::error::{ParseNumSnafu, Result, TableMetadataManagerSnafu};
 use crate::service::admin::{util, HttpHandler};
 
+#[derive(Clone)]
 pub struct CatalogsHandler {
     pub table_metadata_manager: TableMetadataManagerRef,
 }
 
+#[derive(Clone)]
 pub struct SchemasHandler {
     pub table_metadata_manager: TableMetadataManagerRef,
 }
 
+#[derive(Clone)]
 pub struct TablesHandler {
     pub table_metadata_manager: TableMetadataManagerRef,
 }
 
+#[derive(Clone)]
 pub struct TableHandler {
     pub table_metadata_manager: TableMetadataManagerRef,
 }
@@ -65,9 +69,17 @@ impl HttpHandler for CatalogsHandler {
 impl HttpHandler for SchemasHandler {
     async fn handle(
         &self,
-        _: &str,
+        path: &str,
         params: &HashMap<String, String>,
     ) -> Result<http::Response<String>> {
+        if path.ends_with("/help") {
+            return util::to_text_response(
+                r#"
+            - GET /schemas?catalog=foo
+            "#,
+            );
+        }
+
         let catalog = util::get_value(params, "catalog")?;
         let stream = self
             .table_metadata_manager
@@ -89,9 +101,17 @@ impl HttpHandler for SchemasHandler {
 impl HttpHandler for TablesHandler {
     async fn handle(
         &self,
-        _: &str,
+        path: &str,
         params: &HashMap<String, String>,
     ) -> Result<http::Response<String>> {
+        if path.ends_with("/help") {
+            return util::to_text_response(
+                r#"
+            - GET /tables?catalog=foo&schema=bar
+            "#,
+            );
+        }
+
         let catalog = util::get_value(params, "catalog")?;
         let schema = util::get_value(params, "schema")?;
 
@@ -113,9 +133,19 @@ impl HttpHandler for TablesHandler {
 impl HttpHandler for TableHandler {
     async fn handle(
         &self,
-        _: &str,
+        path: &str,
         params: &HashMap<String, String>,
     ) -> Result<http::Response<String>> {
+        if path.ends_with("/help") {
+            return util::to_text_response(
+                r#"
+            - GET /table?region_ids=1,2,3,4,5
+            - GET /table?table_ids=1,2,3,4,5
+            - GET /table?catalog=foo&schema=bar&table=baz
+            "#,
+            );
+        }
+
         let table_ids = self.extract_table_ids(params).await?;
 
         let table_info_values = self
@@ -132,7 +162,7 @@ impl HttpHandler for TableHandler {
             .status(http::StatusCode::OK)
             // Safety: HashMap<String, String> is definitely "serde-json"-able.
             .body(serde_json::to_string(&table_info_values).unwrap())
-            .context(InvalidHttpBodySnafu)
+            .context(error::InvalidHttpBodySnafu)
     }
 }
 

diff --git a/src/meta-srv/src/service/admin/route.rs b/src/meta-srv/src/service/admin/route.rs
@@ -27,6 +27,7 @@ use crate::error::{
     ParseNumSnafu, Result, TableMetadataManagerSnafu, TableNotFoundSnafu, TableRouteNotFoundSnafu,
 };
 
+#[derive(Clone)]
 pub struct RouteHandler {
     pub table_metadata_manager: TableMetadataManagerRef,
 }
@@ -35,9 +36,19 @@ pub struct RouteHandler {
 impl HttpHandler for RouteHandler {
     async fn handle(
         &self,
-        _path: &str,
+        path: &str,
         params: &HashMap<String, String>,
     ) -> Result<http::Response<String>> {
+        if path.ends_with("/help") {
+            return util::to_text_response(
+                r#"
+            - GET /table?region_id=123
+            - GET /table?table_id=456
+            - GET /table?catalog=foo&schema=bar&table=baz
+            "#,
+            );
+        }
+
         let table_id = self.extract_table_id(params).await?;
 
         let table_route_value = self

diff --git a/src/meta-srv/src/service/admin/util.rs b/src/meta-srv/src/service/admin/util.rs
@@ -15,6 +15,7 @@
 use std::collections::HashMap;
 
 use snafu::{OptionExt, ResultExt};
+use tonic::codegen::http;
 
 use crate::error::{self, MissingRequiredParameterSnafu, ParseNumSnafu, Result};
 
@@ -35,3 +36,10 @@ pub fn get_value<'a>(params: &'a HashMap<String, String>, key: &str) -> Result<&
         .get(key)
         .context(error::MissingRequiredParameterSnafu { param: key })
 }
+
+pub fn to_text_response(text: &str) -> Result<http::Response<String>> {
+    http::Response::builder()
+        .status(http::StatusCode::OK)
+        .body(text.to_string())
+        .context(error::InvalidHttpBodySnafu)
+}