skeleton of changes for nym api batch requests

Author: jmwample

common/client-libs/validator-client/src/client.rs

@@ -498,6 +498,11 @@ impl NymApiClient {
         Ok(nodes)
     }
 
+    /// retrieve basic information for all bonded nodes on the network
+    pub async fn retrieve_basic_nodes_batch(&self, node_ids: Vec<u32>) -> Result<Vec<SkimmedNode>, ValidatorClientError> {
+        Ok(self.nym_api.retrieve_basic_nodes_batch(&node_ids).await?.nodes)
+    }
+
     pub async fn health(&self) -> Result<ApiHealthResponse, ValidatorClientError> {
         Ok(self.nym_api.health().await?)
     }

common/client-libs/validator-client/src/nym_api/mod.rs

@@ -256,10 +256,10 @@ pub trait NymApiClientExt: ApiClient {
         self.get_json(
             &[
                 routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                 routes::NYM_NODES_ROUTES,
                 "mixnodes",
-                "skimmed",
+                routes::SKIMMED,
             ],
             NO_PARAMS,
         )
@@ -272,10 +272,10 @@ pub trait NymApiClientExt: ApiClient {
         self.get_json(
             &[
                 routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                 routes::NYM_NODES_ROUTES,
                 "gateways",
-                "skimmed",
+                routes::SKIMMED,
             ],
             NO_PARAMS,
         )
@@ -321,9 +321,9 @@ pub trait NymApiClientExt: ApiClient {
         self.get_json(
             &[
                 routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                 routes::NYM_NODES_ROUTES,
-                "skimmed",
+                routes::SKIMMED,
                 "entry-gateways",
                 "all",
             ],
@@ -358,9 +358,9 @@ pub trait NymApiClientExt: ApiClient {
         self.get_json(
             &[
                 routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                 routes::NYM_NODES_ROUTES,
-                "skimmed",
+                routes::SKIMMED,
                 "mixnodes",
                 "active",
             ],
@@ -395,9 +395,9 @@ pub trait NymApiClientExt: ApiClient {
         self.get_json(
             &[
                 routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                 routes::NYM_NODES_ROUTES,
-                "skimmed",
+                routes::SKIMMED,
                 "mixnodes",
                 "all",
             ],
@@ -406,6 +406,31 @@ pub trait NymApiClientExt: ApiClient {
         .await
     }
 
+    /// Send a Post request with a set of node ids. A successful response will contain descriptors
+    /// for all nodes associated with those node IDs available in the current full topology.
+    ///
+    /// If a provided node ID is not present there will be no descriptor for that node in the response.
+    ///
+    /// If no node IDs are provided the response will contain no descriptors.
+    #[instrument(level = "debug", skip(self))]
+    async fn retrieve_basic_nodes_batch(
+        &self,
+        node_ids: &[NodeId],
+    ) -> Result<CachedNodesResponse<SkimmedNode>, NymAPIError> {
+        self.post_json(
+            &[
+                routes::API_VERSION,
+                routes::UNSTABLE,
+                routes::NYM_NODES_ROUTES,
+                routes::SKIMMED,
+                routes::BATCH,
+            ],
+            NO_PARAMS,
+            node_ids,
+        )
+        .await
+    }
+
     #[instrument(level = "debug", skip(self))]
     async fn get_basic_nodes(
         &self,
@@ -430,9 +455,9 @@ pub trait NymApiClientExt: ApiClient {
         self.get_json(
             &[
                 routes::API_VERSION,
-                "unstable",
+                routes::UNSTABLE,
                 routes::NYM_NODES_ROUTES,
-                "skimmed",
+                routes::SKIMMED,
             ],
             &params,
         )

common/client-libs/validator-client/src/nym_api/routes.rs

@@ -71,3 +71,7 @@ pub const SERVICE_PROVIDERS: &str = "services";
 
 pub const DETAILS: &str = "details";
 pub const NETWORK: &str = "network";
+
+pub const UNSTABLE: &str = "unstable";
+pub const SKIMMED: &str = "skimmed";
+pub const BATCH: &str = "batch";

nym-api/src/nym_nodes/handlers/unstable/skimmed.rs

@@ -25,6 +25,7 @@ use tracing::trace;
 use utoipa::ToSchema;
 
 pub type PaginatedSkimmedNodes = AxumResult<Json<PaginatedCachedNodesResponse<SkimmedNode>>>;
+type SkimmedNodes = AxumResult<Json<CachedNodesResponse<SkimmedNode>>>;
 
 /// Given all relevant caches, build part of response for JUST Nym Nodes
 fn build_nym_nodes_response<'a, NI>(
@@ -196,7 +197,7 @@ where
 pub(super) async fn deprecated_gateways_basic(
     state: State<AppState>,
     query_params: Query<NodesParams>,
-) -> AxumResult<Json<CachedNodesResponse<SkimmedNode>>> {
+) -> SkimmedNodes {
     // 1. call '/v1/unstable/skimmed/entry-gateways/all'
     let all_gateways = entry_gateways_basic_all(state, query_params).await?;
 
@@ -223,7 +224,7 @@ pub(super) async fn deprecated_gateways_basic(
 pub(super) async fn deprecated_mixnodes_basic(
     state: State<AppState>,
     query_params: Query<NodesParams>,
-) -> AxumResult<Json<CachedNodesResponse<SkimmedNode>>> {
+) -> SkimmedNodes {
     // 1. call '/v1/unstable/nym-nodes/skimmed/mixnodes/active'
     let active_mixnodes = mixnodes_basic_active(state, query_params).await?;
 
@@ -239,7 +240,7 @@ async fn nodes_basic(
     state: State<AppState>,
     Query(_query_params): Query<NodesParams>,
     active_only: bool,
-) -> PaginatedSkimmedNodes {
+) -> SkimmedNodes {
     // unfortunately we have to build the response semi-manually here as we need to add two sources of legacy nodes
 
     // 1. grab all relevant described nym-nodes
@@ -281,10 +282,10 @@ async fn nodes_basic(
         legacy_gateways.timestamp(),
     ]);
 
-    Ok(Json(PaginatedCachedNodesResponse::new_full(
+    Ok(Json(CachedNodesResponse {
         refreshed_at,
         nodes,
-    )))
+    }))
 }
 
 #[allow(dead_code)] // not dead, used in OpenAPI docs
@@ -329,6 +330,31 @@ pub(super) async fn nodes_basic_all(
     nodes_basic(state, Query(query_params.into()), false).await
 }
 
+/// Post request handler taking a json array of NodeId (u32) values and returning descriptors for
+/// the provided NodeId values. A successful response will contain descriptors for all nodes
+/// associated with those node IDs available in the current full topology.
+///
+/// If a provided node ID is not present in the current topology there will be no descriptor for
+/// that node in the response.
+///
+/// If no node IDs are provided the response will contain no descriptors.
+#[utoipa::path(
+    tag = "Unstable Nym Nodes batch by Node ID",
+    get,
+    params(NodesParamsWithRole),
+    path = "batch",
+    context_path = "/v1/unstable/nym-nodes/skimmed",
+    responses(
+        (status = 200, body = PaginatedCachedNodesResponseSchema)
+    )
+)]
+pub(super) async fn nodes_basic_batch(
+    state: State<AppState>,
+    Query(query_params): Query<NodesParamsWithRole>,
+) -> SkimmedNodes {
+    nodes_basic(state, Query(query_params.into()), false).await
+}
+
 /// Return Nym Nodes and optionally legacy mixnodes/gateways (if `no-legacy` flag is not used)
 /// that are currently bonded and are in the **active set**
 #[utoipa::path(