docs: add documentation to middlewares

Signed-off-by: Gustavo Inacio <[email protected]>

Author: gusinacio

crates/monitor/src/deployment_to_allocation.rs

@@ -8,7 +8,8 @@ use tokio::sync::watch::Receiver;
 use indexer_allocation::Allocation;
 use indexer_watcher::map_watcher;
 
-/// An always up-to-date list of attestation signers, one for each of the indexer's allocations.
+/// Watcher of indexer allocation
+/// returning a map of subgraph deployment to allocation id
 pub fn deployment_to_allocation(
     indexer_allocations_rx: Receiver<HashMap<Address, Allocation>>,
 ) -> Receiver<HashMap<DeploymentId, Address>> {

crates/service/src/metrics.rs

@@ -5,19 +5,30 @@ use lazy_static::lazy_static;
 use prometheus::{register_counter_vec, register_histogram_vec, CounterVec, HistogramVec};
 
 lazy_static! {
-    /// Register indexer error metrics in Prometheus registry
+    /// Metric registered in global registry for
+    /// indexer query handler
+    ///
+    /// Labels: "deployment", "allocation", "sender"
     pub static ref HANDLER_HISTOGRAM: HistogramVec = register_histogram_vec!(
         "indexer_query_handler_seconds",
         "Histogram for default indexer query handler",
         &["deployment", "allocation", "sender"]
     ).unwrap();
 
+    /// Metric registered in global registry for
+    /// Failed queries to handler
+    ///
+    /// Labels: "deployment"
     pub static ref HANDLER_FAILURE: CounterVec = register_counter_vec!(
         "indexer_query_handler_failed_total",
         "Failed queries to handler",
         &["deployment"]
     ).unwrap();
 
+    /// Metric registered in global registry for
+    /// Failed receipt checks
+    ///
+    /// Labels: "deployment", "allocation", "sender"
     pub static ref FAILED_RECEIPT: CounterVec = register_counter_vec!(
         "indexer_receipt_failed_total",
         "Failed receipt checks",

crates/service/src/middleware/inject_allocation.rs

@@ -1,13 +1,6 @@
 // Copyright 2023-, Edge & Node, GraphOps, and Semiotic Labs.
 // SPDX-License-Identifier: Apache-2.0
 
-//! injects allocation id in extensions
-//! - check if allocation id already exists
-//! - else, try to fetch allocation id from deployment_id and allocations watcher
-//! - execute query
-//!
-//! Needs signed receipt Extension to be added OR deployment id
-
 use std::collections::HashMap;
 
 use alloy::primitives::Address;
@@ -20,6 +13,7 @@ use tap_core::receipt::SignedReceipt;
 use thegraph_core::DeploymentId;
 use tokio::sync::watch;
 
+/// The current query Allocation Id address
 #[derive(Clone)]
 pub struct Allocation(pub Address);
 
@@ -29,11 +23,18 @@ impl From<Allocation> for String {
     }
 }
 
+/// State to be used by allocation middleware
 #[derive(Clone)]
 pub struct AllocationState {
+    /// watcher that maps deployment ids to allocation ids
     pub deployment_to_allocation: watch::Receiver<HashMap<DeploymentId, Address>>,
 }
 
+/// Injects allocation id in extensions
+/// - check if allocation id already exists
+/// - else, try to fetch allocation id from deployment_id to allocations map
+///
+/// Requires signed receipt Extension to be added OR deployment id
 pub async fn allocation_middleware(
     State(my_state): State<AllocationState>,
     mut request: Request,

crates/service/src/middleware/inject_deployment.rs

@@ -9,6 +9,7 @@ use axum::{
 };
 use thegraph_core::DeploymentId;
 
+/// Injects deployment id in the extensions from the path
 pub async fn deployment_middleware(mut request: Request, next: Next) -> Response {
     let deployment_id = request.extract_parts::<Path<DeploymentId>>().await.ok();
     if let Some(Path(deployment_id)) = deployment_id {

crates/service/src/middleware/inject_labels.rs

@@ -1,10 +1,6 @@
 // Copyright 2023-, Edge & Node, GraphOps, and Semiotic Labs.
 // SPDX-License-Identifier: Apache-2.0
 
-//! Injects Metric Labels
-//!
-//! Require Sender, Allocation and Deployment extensions
-
 use std::sync::Arc;
 
 use axum::{extract::Request, middleware::Next, response::Response};
@@ -20,6 +16,10 @@ const NO_DEPLOYMENT_ID: &str = "no-deployment";
 const NO_ALLOCATION: &str = "no-allocation";
 const NO_SENDER: &str = "no-sender";
 
+/// Labels used by metrics which implements MetricLabelProvider
+///
+/// Might contain sender, allocation and deployment id and fills
+/// the gaps with constant values when they are not present
 #[derive(Clone, Default)]
 pub struct SenderAllocationDeploymentLabels {
     sender: Option<String>,
@@ -49,6 +49,9 @@ impl MetricLabelProvider for SenderAllocationDeploymentLabels {
     }
 }
 
+/// Injects Metric Labels to be used by MetricMiddleware
+///
+/// Soft requirement for Sender, Allocation and Deployment extensions
 pub async fn labels_middleware(mut request: Request, next: Next) -> Response {
     let sender: Option<String> = request
         .extensions()

crates/service/src/middleware/inject_receipt.rs

@@ -6,6 +6,9 @@ use axum_extra::TypedHeader;
 
 use crate::service::TapReceipt;
 
+/// Injects tap receipts in the extensions
+///
+/// This is useful to not deserialize multiple times the same receipt
 pub async fn receipt_middleware(mut request: Request, next: Next) -> Response {
     if let Ok(TypedHeader(receipt)) = request.extract_parts::<TypedHeader<TapReceipt>>().await {
         if let Some(receipt) = receipt.into_signed_receipt() {

crates/service/src/middleware/inject_sender.rs

@@ -13,12 +13,16 @@ use tokio::sync::watch;
 
 use crate::error::IndexerServiceError;
 
+/// Stated used by sender middleware
 #[derive(Clone)]
 pub struct SenderState {
+    /// Used to recover the signer address
     pub domain_separator: Eip712Domain,
+    /// Used to get the sender address given the signer address
     pub escrow_accounts: watch::Receiver<EscrowAccounts>,
 }
 
+/// The current query Sender address
 #[derive(Clone)]
 pub struct Sender(pub Address);
 
@@ -28,6 +32,9 @@ impl From<Sender> for String {
     }
 }
 
+/// Injects the sender found from the signer in the receipt
+///
+/// Requires Receipt extension
 pub async fn sender_middleware(
     State(state): State<SenderState>,
     mut request: Request,

crates/service/src/middleware/prometheus_metrics.rs

@@ -20,16 +20,22 @@ pub trait MetricLabelProvider {
     fn get_labels(&self) -> Vec<&str>;
 }
 
+/// Middleware for metrics
 #[derive(Clone)]
 pub struct PrometheusMetricsMiddleware<S> {
     inner: S,
     histogram: prometheus::HistogramVec,
     failure: prometheus::CounterVec,
 }
 
+/// MetricsMiddleware used in tower components
+///
+/// Register prometheus metrics in case of success or failure
 #[derive(Clone)]
 pub struct PrometheusMetricsMiddlewareLayer {
+    /// Histogram used to register the processing timer
     histogram: prometheus::HistogramVec,
+    /// Counter metric in case of failure
     failure: prometheus::CounterVec,
 }