Admin API: parameter to include total number of items

This allows removing the count calculation when not needed, or to skip
the list of items entirely.

Author: sandhose

crates/handlers/src/admin/params.rs

@@ -7,7 +7,7 @@
 // Generated code from schemars violates this rule
 #![allow(clippy::str_to_string)]
 
-use std::num::NonZeroUsize;
+use std::{borrow::Cow, num::NonZeroUsize};
 
 use aide::OperationIo;
 use axum::{
@@ -64,6 +64,34 @@ impl std::ops::Deref for UlidPathParam {
 /// The default page size if not specified
 const DEFAULT_PAGE_SIZE: usize = 10;
 
+#[derive(Deserialize, JsonSchema, Clone, Copy, Default, Debug)]
+pub enum IncludeCount {
+    /// Include the total number of items (default)
+    #[default]
+    #[serde(rename = "true")]
+    True,
+
+    /// Do not include the total number of items
+    #[serde(rename = "false")]
+    False,
+
+    /// Only include the total number of items, skip the items themselves
+    #[serde(rename = "only")]
+    Only,
+}
+
+impl IncludeCount {
+    pub(crate) fn add_to_base(self, base: &str) -> Cow<'_, str> {
+        let separator = if base.contains('?') { '&' } else { '?' };
+        match self {
+            // This is the default, don't add anything
+            Self::True => Cow::Borrowed(base),
+            Self::False => format!("{base}{separator}count=false").into(),
+            Self::Only => format!("{base}{separator}count=only").into(),
+        }
+    }
+}
+
 #[derive(Deserialize, JsonSchema, Clone, Copy)]
 struct PaginationParams {
     /// Retrieve the items before the given ID
@@ -83,6 +111,10 @@ struct PaginationParams {
     /// Retrieve the last N items
     #[serde(rename = "page[last]")]
     last: Option<NonZeroUsize>,
+
+    /// Include the total number of items. Defaults to `true`.
+    #[serde(rename = "count")]
+    include_count: Option<IncludeCount>,
 }
 
 #[derive(Debug, thiserror::Error)]
@@ -107,7 +139,7 @@ impl IntoResponse for PaginationRejection {
 /// An extractor for pagination parameters in the query string
 #[derive(OperationIo, Debug, Clone, Copy)]
 #[aide(input_with = "Query<PaginationParams>")]
-pub struct Pagination(pub mas_storage::Pagination);
+pub struct Pagination(pub mas_storage::Pagination, pub IncludeCount);
 
 impl<S: Send + Sync> FromRequestParts<S> for Pagination {
     type Rejection = PaginationRejection;
@@ -130,11 +162,14 @@ impl<S: Send + Sync> FromRequestParts<S> for Pagination {
             (None, Some(last)) => (PaginationDirection::Backward, last.into()),
         };
 
-        Ok(Self(mas_storage::Pagination {
-            before: params.before,
-            after: params.after,
-            direction,
-            count,
-        }))
+        Ok(Self(
+            mas_storage::Pagination {
+                before: params.before,
+                after: params.after,
+                direction,
+                count,
+            },
+            params.include_count.unwrap_or_default(),
+        ))
     }
 }

crates/handlers/src/admin/response.rs

@@ -21,10 +21,12 @@ struct PaginationLinks {
     self_: String,
 
     /// The link to the first page of results
-    first: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    first: Option<String>,
 
     /// The link to the last page of results
-    last: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    last: Option<String>,
 
     /// The link to the next page of results
     ///
@@ -42,17 +44,26 @@ struct PaginationLinks {
 #[derive(Serialize, JsonSchema)]
 struct PaginationMeta {
     /// The total number of results
-    count: usize,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    count: Option<usize>,
+}
+
+impl PaginationMeta {
+    fn is_empty(&self) -> bool {
+        self.count.is_none()
+    }
 }
 
 /// A top-level response with a page of resources
 #[derive(Serialize, JsonSchema)]
 pub struct PaginatedResponse<T> {
     /// Response metadata
+    #[serde(skip_serializing_if = "PaginationMeta::is_empty")]
     meta: PaginationMeta,
 
     /// The list of resources
-    data: Vec<SingleResource<T>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    data: Option<Vec<SingleResource<T>>>,
 
     /// Related links
     links: PaginationLinks,
@@ -87,16 +98,22 @@ fn url_with_pagination(base: &str, pagination: Pagination) -> String {
 }
 
 impl<T: Resource> PaginatedResponse<T> {
-    pub fn new(
+    pub fn for_page(
         page: mas_storage::Page<T>,
         current_pagination: Pagination,
-        count: usize,
+        count: Option<usize>,
         base: &str,
     ) -> Self {
         let links = PaginationLinks {
             self_: url_with_pagination(base, current_pagination),
-            first: url_with_pagination(base, Pagination::first(current_pagination.count)),
-            last: url_with_pagination(base, Pagination::last(current_pagination.count)),
+            first: Some(url_with_pagination(
+                base,
+                Pagination::first(current_pagination.count),
+            )),
+            last: Some(url_with_pagination(
+                base,
+                Pagination::last(current_pagination.count),
+            )),
             next: page.has_next_page.then(|| {
                 url_with_pagination(
                     base,
@@ -121,7 +138,23 @@ impl<T: Resource> PaginatedResponse<T> {
 
         Self {
             meta: PaginationMeta { count },
-            data,
+            data: Some(data),
+            links,
+        }
+    }
+
+    pub fn for_count_only(count: usize, base: &str) -> Self {
+        let links = PaginationLinks {
+            self_: base.to_owned(),
+            first: None,
+            last: None,
+            next: None,
+            prev: None,
+        };
+
+        Self {
+            meta: PaginationMeta { count: Some(count) },
+            data: None,
             links,
         }
     }

crates/handlers/src/admin/v1/compat_sessions/list.rs

@@ -21,7 +21,7 @@ use crate::{
     admin::{
         call_context::CallContext,
         model::{CompatSession, Resource},
-        params::Pagination,
+        params::{IncludeCount, Pagination},
         response::{ErrorResponse, PaginatedResponse},
     },
     impl_from_error_for_route,
@@ -143,10 +143,10 @@ Use the `filter[status]` parameter to filter the sessions by their status and `p
             };
 
             t.description("Paginated response of compatibility sessions")
-                .example(PaginatedResponse::new(
+                .example(PaginatedResponse::for_page(
                     page,
                     pagination,
-                    42,
+                    Some(42),
                     CompatSession::PATH,
                 ))
         })
@@ -159,10 +159,11 @@ Use the `filter[status]` parameter to filter the sessions by their status and `p
 #[tracing::instrument(name = "handler.admin.v1.compat_sessions.list", skip_all)]
 pub async fn handler(
     CallContext { mut repo, .. }: CallContext,
-    Pagination(pagination): Pagination,
+    Pagination(pagination, include_count): Pagination,
     params: FilterParams,
 ) -> Result<Json<PaginatedResponse<CompatSession>>, RouteError> {
     let base = format!("{path}{params}", path = CompatSession::PATH);
+    let base = include_count.add_to_base(&base);
     let filter = CompatSessionFilter::default();
 
     // Load the user from the filter
@@ -206,15 +207,31 @@ pub async fn handler(
         None => filter,
     };
 
-    let page = repo.compat_session().list(filter, pagination).await?;
-    let count = repo.compat_session().count(filter).await?;
+    let response = match include_count {
+        IncludeCount::True => {
+            let page = repo
+                .compat_session()
+                .list(filter, pagination)
+                .await?
+                .map(CompatSession::from);
+            let count = repo.compat_session().count(filter).await?;
+            PaginatedResponse::for_page(page, pagination, Some(count), &base)
+        }
+        IncludeCount::False => {
+            let page = repo
+                .compat_session()
+                .list(filter, pagination)
+                .await?
+                .map(CompatSession::from);
+            PaginatedResponse::for_page(page, pagination, None, &base)
+        }
+        IncludeCount::Only => {
+            let count = repo.compat_session().count(filter).await?;
+            PaginatedResponse::for_count_only(count, &base)
+        }
+    };
 
-    Ok(Json(PaginatedResponse::new(
-        page.map(CompatSession::from),
-        pagination,
-        count,
-        &base,
-    )))
+    Ok(Json(response))
 }
 
 #[cfg(test)]

crates/handlers/src/admin/v1/oauth2_sessions/list.rs

@@ -25,7 +25,7 @@ use crate::{
     admin::{
         call_context::CallContext,
         model::{OAuth2Session, Resource},
-        params::Pagination,
+        params::{IncludeCount, Pagination},
         response::{ErrorResponse, PaginatedResponse},
     },
     impl_from_error_for_route,
@@ -198,10 +198,10 @@ Use the `filter[status]` parameter to filter the sessions by their status and `p
             };
 
             t.description("Paginated response of OAuth 2.0 sessions")
-                .example(PaginatedResponse::new(
+                .example(PaginatedResponse::for_page(
                     page,
                     pagination,
-                    42,
+                    Some(42),
                     OAuth2Session::PATH,
                 ))
         })
@@ -218,10 +218,11 @@ Use the `filter[status]` parameter to filter the sessions by their status and `p
 #[tracing::instrument(name = "handler.admin.v1.oauth2_sessions.list", skip_all)]
 pub async fn handler(
     CallContext { mut repo, .. }: CallContext,
-    Pagination(pagination): Pagination,
+    Pagination(pagination, include_count): Pagination,
     params: FilterParams,
 ) -> Result<Json<PaginatedResponse<OAuth2Session>>, RouteError> {
     let base = format!("{path}{params}", path = OAuth2Session::PATH);
+    let base = include_count.add_to_base(&base);
     let filter = OAuth2SessionFilter::default();
 
     // Load the user from the filter
@@ -300,15 +301,31 @@ pub async fn handler(
         None => filter,
     };
 
-    let page = repo.oauth2_session().list(filter, pagination).await?;
-    let count = repo.oauth2_session().count(filter).await?;
+    let response = match include_count {
+        IncludeCount::True => {
+            let page = repo
+                .oauth2_session()
+                .list(filter, pagination)
+                .await?
+                .map(OAuth2Session::from);
+            let count = repo.oauth2_session().count(filter).await?;
+            PaginatedResponse::for_page(page, pagination, Some(count), &base)
+        }
+        IncludeCount::False => {
+            let page = repo
+                .oauth2_session()
+                .list(filter, pagination)
+                .await?
+                .map(OAuth2Session::from);
+            PaginatedResponse::for_page(page, pagination, None, &base)
+        }
+        IncludeCount::Only => {
+            let count = repo.oauth2_session().count(filter).await?;
+            PaginatedResponse::for_count_only(count, &base)
+        }
+    };
 
-    Ok(Json(PaginatedResponse::new(
-        page.map(OAuth2Session::from),
-        pagination,
-        count,
-        &base,
-    )))
+    Ok(Json(response))
 }
 
 #[cfg(test)]