feat(api): add blocks by milestone endpoints (#876)

* Add blocks by milestone endpoints

* Docs

* Fix build

* fix query

* Fix requests (#922)

* Fix requests

* Stupid me

* Fixes the returned cursor in `feat/api/blocks-by-milestone` (#923)

* limit +1

* Do it like in the other places

Co-authored-by: /alex/ <[email protected]>
Co-authored-by: Jochen Görtler <[email protected]>
Co-authored-by: Jochen Görtler <[email protected]>

Author: 3 people

documentation/api/api-explorer.yml

@@ -105,6 +105,62 @@ paths:
           $ref: "#/components/responses/NoResults"
         "500":
           $ref: "#/components/responses/InternalError"
+  /api/explorer/v2/milestones/{milestoneId}/blocks:
+    get:
+      tags:
+        - blocks
+      summary: Returns blocks in a given milestone by ID.
+      description: >-
+        Returns block IDs in a given milestone by ID sorted by white flag index.
+      parameters:
+        - $ref: "#/components/parameters/milestoneId"
+        - $ref: "#/components/parameters/sort"
+        - $ref: "#/components/parameters/pageSize"
+        - $ref: "#/components/parameters/cursor"
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BlocksByMilestoneResponse"
+              examples:
+                default:
+                  $ref: "#/components/examples/blocks-by-milestone-example"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "404":
+          $ref: "#/components/responses/NoResults"
+        "500":
+          $ref: "#/components/responses/InternalError"
+  /api/explorer/v2/milestones/by-index/{milestoneIndex}/blocks:
+    get:
+      tags:
+        - blocks
+      summary: Returns blocks in a given milestone by index.
+      description: >-
+        Returns block IDs in a given milestone by index sorted by white flag index.
+      parameters:
+        - $ref: "#/components/parameters/milestoneIndex"
+        - $ref: "#/components/parameters/sort"
+        - $ref: "#/components/parameters/pageSize"
+        - $ref: "#/components/parameters/cursor"
+      responses:
+        "200":
+          description: Successful operation.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BlocksByMilestoneResponse"
+              examples:
+                default:
+                  $ref: "#/components/examples/blocks-by-milestone-example"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "404":
+          $ref: "#/components/responses/NoResults"
+        "500":
+          $ref: "#/components/responses/InternalError"
   /api/explorer/v2/ledger/updates/by-address/{address}:
     get:
       tags:
@@ -336,6 +392,19 @@ components:
           description: The cursor which can be used to retrieve the next logical page of results.
       required:
         - items
+    BlocksByMilestoneResponse:
+      description: Paged block IDs by milestone.
+      properties:
+        blocks:
+          type: array
+          description: A list of block ids.
+          items:
+            type: string
+        cursor:
+          type: string
+          description: The cursor which can be used to retrieve the next logical page of results.
+      required:
+        - blocks
     RichestAddressesResponse:
       description: Richest addresses statistics.
       properties:
@@ -486,6 +555,15 @@ components:
       description: >-
         The milestone index to be used to determine the ledger state. Defaults to the 
         application's current ledger index.
+    milestoneIndex:
+      in: path
+      name: milestoneIndex
+      schema:
+        type: integer
+      example: 200000
+      required: true
+      description: >-
+        The milestone index to be used.
     top:
       in: query
       name: top
@@ -531,7 +609,7 @@ components:
             index: 100
           - milestoneId: "0xfa0de75d225cca2799395e5fc340702fc7eac821d2bdd79911126f131ae097a2"
             index: 101
-        cursor: 102.2
+        cursor: "102.2"
     richest-addresses-example:
       value:
         top:
@@ -563,3 +641,10 @@ components:
             addressCount: "27"
             totalBalance: "25486528000"
         ledgerIndex: 1005429
+    blocks-by-milestone-example:
+      value:
+        blocks:
+          - "0xd0d361341fa3bb2f6855039a82ee9ea470c3336eaf34d22767fdfa901ba63e31"
+          - "0x7a09324557e9200f39bf493fc8fd6ac43e9ca750c6f6d884cc72386ddcb7d695"
+          - "0xfa0de75d225cca2799395e5fc340702fc7eac821d2bdd79911126f131ae097a2"
+        cursor: "4.100"

src/bin/inx-chronicle/api/stardust/explorer/extractors.rs

@@ -330,6 +330,123 @@ impl<B: Send> FromRequest<B> for MilestoneRange {
     }
 }
 
+pub struct BlocksByMilestoneIndexPagination {
+    pub sort: SortOrder,
+    pub page_size: usize,
+    pub cursor: Option<u32>,
+}
+
+#[derive(Clone, Deserialize, Default)]
+#[serde(default, deny_unknown_fields, rename_all = "camelCase")]
+pub struct BlocksByMilestoneIndexPaginationQuery {
+    pub sort: Option<String>,
+    pub page_size: Option<usize>,
+    pub cursor: Option<String>,
+}
+
+#[derive(Clone)]
+pub struct BlocksByMilestoneCursor {
+    pub white_flag_index: u32,
+    pub page_size: usize,
+}
+
+impl FromStr for BlocksByMilestoneCursor {
+    type Err = ApiError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let parts: Vec<_> = s.split('.').collect();
+        Ok(match parts[..] {
+            [wfi, ps] => BlocksByMilestoneCursor {
+                white_flag_index: wfi.parse().map_err(RequestError::from)?,
+                page_size: ps.parse().map_err(RequestError::from)?,
+            },
+            _ => return Err(ApiError::from(RequestError::BadPagingState)),
+        })
+    }
+}
+
+impl Display for BlocksByMilestoneCursor {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}.{}", self.white_flag_index, self.page_size)
+    }
+}
+
+#[async_trait]
+impl<B: Send> FromRequest<B> for BlocksByMilestoneIndexPagination {
+    type Rejection = ApiError;
+
+    async fn from_request(req: &mut axum::extract::RequestParts<B>) -> Result<Self, Self::Rejection> {
+        let Query(query) = Query::<BlocksByMilestoneIndexPaginationQuery>::from_request(req)
+            .await
+            .map_err(RequestError::from)?;
+        let Extension(config) = Extension::<ApiData>::from_request(req).await?;
+
+        let sort = query
+            .sort
+            .as_deref()
+            .map_or(Ok(Default::default()), str::parse)
+            .map_err(RequestError::SortOrder)?;
+
+        let (page_size, cursor) = if let Some(cursor) = query.cursor {
+            let cursor: BlocksByMilestoneCursor = cursor.parse()?;
+            (cursor.page_size, Some(cursor.white_flag_index))
+        } else {
+            (query.page_size.unwrap_or(DEFAULT_PAGE_SIZE), None)
+        };
+
+        Ok(BlocksByMilestoneIndexPagination {
+            sort,
+            page_size: page_size.min(config.max_page_size),
+            cursor,
+        })
+    }
+}
+
+pub struct BlocksByMilestoneIdPagination {
+    pub sort: SortOrder,
+    pub page_size: usize,
+    pub cursor: Option<u32>,
+}
+
+#[derive(Clone, Deserialize, Default)]
+#[serde(default, deny_unknown_fields, rename_all = "camelCase")]
+pub struct BlocksByMilestoneIdPaginationQuery {
+    pub sort: Option<String>,
+    pub page_size: Option<usize>,
+    pub cursor: Option<String>,
+}
+
+#[async_trait]
+impl<B: Send> FromRequest<B> for BlocksByMilestoneIdPagination {
+    type Rejection = ApiError;
+
+    async fn from_request(req: &mut axum::extract::RequestParts<B>) -> Result<Self, Self::Rejection> {
+        let Query(query) = Query::<BlocksByMilestoneIdPaginationQuery>::from_request(req)
+            .await
+            .map_err(RequestError::from)?;
+        let Extension(config) = Extension::<ApiData>::from_request(req).await?;
+
+        let sort = query
+            .sort
+            .as_deref()
+            .map_or(Ok(Default::default()), str::parse)
+            .map_err(RequestError::SortOrder)?;
+
+        let (page_size, cursor) = if let Some(cursor) = query.cursor {
+            let cursor: BlocksByMilestoneCursor = cursor.parse()?;
+            (cursor.page_size, Some(cursor.white_flag_index))
+        } else {
+            (query.page_size.unwrap_or(DEFAULT_PAGE_SIZE), None)
+        };
+
+        Ok(BlocksByMilestoneIdPagination {
+            sort,
+            page_size: page_size.min(config.max_page_size),
+            cursor,
+        })
+    }
+}
+
 #[cfg(test)]
 mod test {
     use axum::{extract::RequestParts, http::Request};

src/bin/inx-chronicle/api/stardust/explorer/responses.rs

@@ -82,8 +82,6 @@ pub struct BalanceResponse {
 
 impl_success_response!(BalanceResponse);
 
-/// Response of GET /api/explorer/v2/blocks/{block_id}/children.
-/// Returns all children of a specific block.
 #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct BlockChildrenResponse {
@@ -104,6 +102,15 @@ pub struct MilestonesResponse {
 
 impl_success_response!(MilestonesResponse);
 
+#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BlocksByMilestoneResponse {
+    pub blocks: Vec<String>,
+    pub cursor: Option<String>,
+}
+
+impl_success_response!(BlocksByMilestoneResponse);
+
 #[derive(Clone, Debug, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct MilestoneDto {

src/bin/inx-chronicle/api/stardust/explorer/routes.rs

@@ -20,12 +20,14 @@ use futures::{StreamExt, TryStreamExt};
 
 use super::{
     extractors::{
-        LedgerIndex, LedgerUpdatesByAddressCursor, LedgerUpdatesByAddressPagination, LedgerUpdatesByMilestoneCursor,
+        BlocksByMilestoneCursor, BlocksByMilestoneIdPagination, BlocksByMilestoneIndexPagination, LedgerIndex,
+        LedgerUpdatesByAddressCursor, LedgerUpdatesByAddressPagination, LedgerUpdatesByMilestoneCursor,
         LedgerUpdatesByMilestonePagination, MilestonesCursor, MilestonesPagination, RichestAddressesQuery,
     },
     responses::{
-        AddressStatDto, BalanceResponse, BlockChildrenResponse, LedgerUpdatesByAddressResponse,
-        LedgerUpdatesByMilestoneResponse, MilestonesResponse, RichestAddressesResponse, TokenDistributionResponse,
+        AddressStatDto, BalanceResponse, BlockChildrenResponse, BlocksByMilestoneResponse,
+        LedgerUpdatesByAddressResponse, LedgerUpdatesByMilestoneResponse, MilestonesResponse, RichestAddressesResponse,
+        TokenDistributionResponse,
     },
 };
 use crate::api::{
@@ -39,7 +41,13 @@ pub fn routes() -> Router {
     Router::new()
         .route("/balance/:address", get(balance))
         .route("/blocks/:block_id/children", get(block_children))
-        .route("/milestones", get(milestones))
+        .nest(
+            "/milestones",
+            Router::new()
+                .route("/", get(milestones))
+                .route("/:milestone_id/blocks", get(blocks_by_milestone_id))
+                .route("/by-index/:milestone_index/blocks", get(blocks_by_milestone_index)),
+        )
         .nest(
             "/ledger",
             Router::new()
@@ -223,6 +231,69 @@ async fn milestones(
     Ok(MilestonesResponse { items, cursor })
 }
 
+async fn blocks_by_milestone_index(
+    database: Extension<MongoDb>,
+    Path(milestone_index): Path<MilestoneIndex>,
+    BlocksByMilestoneIndexPagination {
+        sort,
+        page_size,
+        cursor,
+    }: BlocksByMilestoneIndexPagination,
+) -> ApiResult<BlocksByMilestoneResponse> {
+    let mut record_stream = database
+        .collection::<BlockCollection>()
+        .get_blocks_by_milestone_index(milestone_index, page_size + 1, cursor, sort)
+        .await?;
+
+    // Take all of the requested records first
+    let blocks = record_stream
+        .by_ref()
+        .take(page_size)
+        .map_ok(|rec| rec.block_id.to_hex())
+        .try_collect()
+        .await?;
+
+    // If any record is left, use it to make the paging state
+    let cursor = record_stream.try_next().await?.map(|rec| {
+        BlocksByMilestoneCursor {
+            white_flag_index: rec.white_flag_index,
+            page_size,
+        }
+        .to_string()
+    });
+
+    Ok(BlocksByMilestoneResponse { blocks, cursor })
+}
+
+async fn blocks_by_milestone_id(
+    database: Extension<MongoDb>,
+    Path(milestone_id): Path<String>,
+    BlocksByMilestoneIdPagination {
+        sort,
+        page_size,
+        cursor,
+    }: BlocksByMilestoneIdPagination,
+) -> ApiResult<BlocksByMilestoneResponse> {
+    let milestone_id = MilestoneId::from_str(&milestone_id).map_err(RequestError::from)?;
+    let milestone_index = database
+        .collection::<MilestoneCollection>()
+        .get_milestone_payload_by_id(&milestone_id)
+        .await?
+        .ok_or(MissingError::NoResults)?
+        .essence
+        .index;
+    blocks_by_milestone_index(
+        database,
+        Path(milestone_index),
+        BlocksByMilestoneIndexPagination {
+            sort,
+            page_size,
+            cursor,
+        },
+    )
+    .await
+}
+
 async fn richest_addresses_ledger_analytics(
     database: Extension<MongoDb>,
     RichestAddressesQuery { top, ledger_index }: RichestAddressesQuery,