Merge pull request #545 from AmbireTech/get-cfg-documentation

GET `/cfg` Sentry API documentation

Author: elpiel

primitives/Cargo.toml

@@ -75,6 +75,9 @@ name = "validator_messages_list_query"
 [[example]]
 name = "validator_messages_list_response"
 
+[[example]]
+name = "get_cfg_response"
+
 [dependencies]
 # (De)Serialization
 serde = { version = "1.0", features = ["derive"] }

primitives/examples/get_cfg_response.rs

@@ -0,0 +1,70 @@
+use primitives::Config;
+use serde_json::{from_value, json};
+
+fn main() {
+    let json = json!({
+      "max_channels": 512,
+      "channels_find_limit": 200,
+      "campaigns_find_limit": 200,
+      "spendable_find_limit": 200,
+      "wait_time": 500,
+      "msgs_find_limit": 10,
+      "analytics_find_limit": 5000,
+      "analytics_maxtime": 20000,
+      "heartbeat_time": 30000,
+      "health_threshold_promilles": 950,
+      "health_unsignable_promilles": 750,
+      "propagation_timeout": 2000,
+      "fetch_timeout": 5000,
+      "all_campaigns_timeout": 5000,
+      "channel_tick_timeout": 8000,
+      "ip_rate_limit": {
+        "type": "ip",
+        "timeframe": 1200000
+      },
+      "creators_whitelist": [],
+      "validators_whitelist": [],
+      "admins": [
+        "0x80690751969B234697e9059e04ed72195c3507fa"
+      ],
+      "chain": {
+        "Ganache #1337": {
+          "chain_id": 1337,
+          "rpc": "http://localhost:1337/",
+          "outpace": "0xAbc27d46a458E2e49DaBfEf45ca74dEDBAc3DD06",
+          "token": {
+            "Mocked TOKEN 1337": {
+              "min_campaign_budget": "1000000000000000000",
+              "min_validator_fee": "1000000000000",
+              "precision": 18,
+              "address": "0x2BCaf6968aEC8A3b5126FBfAb5Fd419da6E8AD8E"
+            }
+          }
+        },
+        "Ganache #1": {
+          "chain_id": 1,
+          "rpc": "http://localhost:8545/",
+          "outpace": "0x26CBc2eAAe377f6Ac4b73a982CD1125eF4CEC96f",
+          "token": {
+            "Mocked TOKEN 1": {
+              "min_campaign_budget": "1000000000000000000",
+              "min_validator_fee": "1000000000000",
+              "precision": 18,
+              "address": "0x12a28f2bfBFfDf5842657235cC058242f40fDEa6"
+            }
+          }
+        }
+      },
+      "platform": {
+        "url": "https://platform.adex.network/",
+        "keep_alive_interval": 1200000
+      },
+      "limits": {
+        "units_for_slot": {
+          "max_campaigns_earning_from": 25,
+          "global_min_impression_price": "1000000"
+        }
+      }
+    });
+    assert!(from_value::<Config>(json).is_ok());
+}

primitives/src/config.rs

@@ -5,7 +5,7 @@ use crate::{
     Address, BigNum, ChainOf, ValidatorId,
 };
 use once_cell::sync::Lazy;
-use serde::{Deserialize, Deserializer, Serialize};
+use serde::{Deserialize, Serialize};
 use std::{collections::HashMap, num::NonZeroU8, time::Duration};
 use thiserror::Error;
 
@@ -47,6 +47,10 @@ impl Default for Environment {
     }
 }
 
+/// Examples:
+/// ```
+#[doc = include_str!("../../primitives/examples/get_cfg_response.rs")]
+/// ```
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct Config {
     /// The maximum number of [`Channel`](crate::Channel)s that the worker
@@ -73,7 +77,7 @@ pub struct Config {
     /// finish before running a new tick in the Validator Worker.
     ///
     /// In milliseconds
-    #[serde(deserialize_with = "milliseconds_to_std_duration")]
+    #[serde(with = "std_duration_millis")]
     pub wait_time: Duration,
     /// The maximum allowed limit of [`ValidatorMessage`](crate::sentry::ValidatorMessage)s per page
     /// returned by Sentry's GET `/v5/channel/0xXXX.../validator-messages` route.
@@ -104,12 +108,12 @@ pub struct Config {
     /// - GET `/v5/analytics/for-admin`
     ///
     /// In milliseconds
-    #[serde(deserialize_with = "milliseconds_to_std_duration")]
+    #[serde(with = "std_duration_millis")]
     pub analytics_maxtime: Duration,
     /// The amount of time that should have passed before sending a new heartbeat.
     ///
     /// In milliseconds
-    #[serde(deserialize_with = "milliseconds_to_std_duration")]
+    #[serde(with = "std_duration_millis")]
     pub heartbeat_time: Duration,
     /// The pro miles below which the [`ApproveState`](crate::validator::ApproveState)
     /// becomes **unhealthy** in the [`Channel`](crate::Channel)'s Follower.
@@ -128,7 +132,7 @@ pub struct Config {
     /// to a validator.
     ///
     /// In milliseconds
-    #[serde(deserialize_with = "milliseconds_to_std_duration")]
+    #[serde(with = "std_duration_millis")]
     pub propagation_timeout: Duration,
     /// The Client timeout for `SentryApi`.
     ///
@@ -138,20 +142,20 @@ pub struct Config {
     /// [`Config.propagation_timeout`](Config::propagation_timeout).
     ///
     /// In milliseconds
-    #[serde(deserialize_with = "milliseconds_to_std_duration")]
+    #[serde(with = "std_duration_millis")]
     pub fetch_timeout: Duration,
     /// The Client timeout for `SentryApi` when collecting all channels
     /// and Validators using the `/campaign/list` route.
     ///
     /// In milliseconds
-    #[serde(deserialize_with = "milliseconds_to_std_duration")]
+    #[serde(with = "std_duration_millis")]
     pub all_campaigns_timeout: Duration,
     /// The timeout for a single tick of a [`Channel`](crate::Channel) in
     /// the Validator Worker.
     /// This timeout is applied to both the leader and follower ticks.
     ///
     /// In milliseconds
-    #[serde(deserialize_with = "milliseconds_to_std_duration")]
+    #[serde(with = "std_duration_millis")]
     pub channel_tick_timeout: Duration,
     /// The default IP rate limit that will be imposed if
     /// [`Campaign.event_submission`](crate::Campaign::event_submission) is [`None`].
@@ -210,7 +214,7 @@ impl Config {
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct PlatformConfig {
     pub url: ApiUrl,
-    #[serde(deserialize_with = "milliseconds_to_std_duration")]
+    #[serde(with = "std_duration_millis")]
     pub keep_alive_interval: Duration,
 }
 
@@ -248,21 +252,35 @@ pub struct Limits {
     pub units_for_slot: limits::UnitsForSlot,
 }
 
-fn milliseconds_to_std_duration<'de, D>(deserializer: D) -> Result<Duration, D::Error>
-where
-    D: Deserializer<'de>,
-{
-    use serde::de::Error;
-    use toml::Value;
+/// Module for [`Config`] (de)serialization of [`std::time::Duration`] from
+/// and to milliseconds.
+pub mod std_duration_millis {
+    use serde::{Deserialize, Deserializer, Serializer};
+    use std::time::Duration;
+
+    pub fn deserialize<'de, D>(deserializer: D) -> Result<Duration, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        use serde::de::Error;
+        use toml::Value;
 
-    let toml_value: Value = Value::deserialize(deserializer)?;
+        let toml_value: Value = Value::deserialize(deserializer)?;
 
-    let milliseconds = match toml_value {
-        Value::Integer(mills) => u64::try_from(mills).map_err(Error::custom),
-        _ => Err(Error::custom("Only integers allowed for this value")),
-    }?;
+        let milliseconds = match toml_value {
+            Value::Integer(mills) => u64::try_from(mills).map_err(Error::custom),
+            _ => Err(Error::custom("Only integers allowed for this value")),
+        }?;
 
-    Ok(Duration::from_millis(milliseconds))
+        Ok(Duration::from_millis(milliseconds))
+    }
+
+    pub fn serialize<S>(duration: &Duration, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        serializer.serialize_str(&duration.as_millis().to_string())
+    }
 }
 
 pub mod limits {

sentry/src/db/analytics.rs

@@ -9,7 +9,7 @@ use tokio_postgres::{types::ToSql, Row};
 
 use super::{DbPool, PoolError};
 
-pub async fn get_analytics(
+pub async fn fetch_analytics(
     pool: &DbPool,
     query: AnalyticsQuery,
     allowed_keys: HashSet<AllowedKey>,
@@ -180,7 +180,7 @@ mod test {
     use crate::db::tests_postgres::{setup_test_migrations, DATABASE_POOL};
 
     #[tokio::test]
-    async fn insert_update_and_get_analytics() {
+    async fn insert_update_and_fetch_analytics() {
         let database = DATABASE_POOL.get().await.expect("Should get a DB pool");
 
         let ad_unit = DUMMY_AD_UNITS[0].clone();
@@ -393,7 +393,7 @@ mod test {
 
         // Impression query - should count all inserted Analytics
         {
-            let count_impressions = get_analytics(
+            let count_impressions = fetch_analytics(
                 &database.pool,
                 impression_query.clone(),
                 ALLOWED_KEYS.clone(),
@@ -436,7 +436,7 @@ mod test {
             let mut paid_impressions_query = impression_query.clone();
             paid_impressions_query.metric = Metric::Paid;
 
-            let paid_impressions = get_analytics(
+            let paid_impressions = fetch_analytics(
                 &database.pool,
                 paid_impressions_query,
                 ALLOWED_KEYS.clone(),
@@ -498,7 +498,7 @@ mod test {
 
         // Click query - should count all inserted Analytics
         {
-            let count_clicks = get_analytics(
+            let count_clicks = fetch_analytics(
                 &database.pool,
                 click_query.clone(),
                 ALLOWED_KEYS.clone(),
@@ -541,7 +541,7 @@ mod test {
             let mut paid_clicks_query = impression_query.clone();
             paid_clicks_query.metric = Metric::Paid;
 
-            let paid_impressions = get_analytics(
+            let paid_impressions = fetch_analytics(
                 &database.pool,
                 paid_clicks_query,
                 ALLOWED_KEYS.clone(),
@@ -595,7 +595,7 @@ mod test {
             };
             click_germany_query.country = Some("Germany".into());
 
-            let count_clicks = get_analytics(
+            let count_clicks = fetch_analytics(
                 &database.pool,
                 click_germany_query.clone(),
                 ALLOWED_KEYS.clone(),
@@ -646,7 +646,7 @@ mod test {
                 chains: vec![],
             };
 
-            let count_impressions = get_analytics(
+            let count_impressions = fetch_analytics(
                 &database.pool,
                 ad_unit_2_query.clone(),
                 ALLOWED_KEYS.clone(),
@@ -702,7 +702,7 @@ mod test {
                 chains: vec![],
             };
 
-            let count_impressions = get_analytics(
+            let count_impressions = fetch_analytics(
                 &database.pool,
                 filter_by_publisher_2_query.clone(),
                 ALLOWED_KEYS.clone(),
@@ -758,7 +758,7 @@ mod test {
                 chains: vec![],
             };
 
-            let count_impressions = get_analytics(
+            let count_impressions = fetch_analytics(
                 &database.pool,
                 authenticate_as_publisher_2_query.clone(),
                 ALLOWED_KEYS.clone(),
@@ -814,7 +814,7 @@ mod test {
                 chains: vec![],
             };
 
-            let count_impressions = get_analytics(
+            let count_impressions = fetch_analytics(
                 &database.pool,
                 segment_ad_units_query.clone(),
                 ALLOWED_KEYS.clone(),

sentry/src/routes.rs

@@ -29,6 +29,8 @@
 //!   - [GET `/v5/analytics/for-publisher`](#get-v5analyticsfor-publisher-auth-required) (auth required)
 //!   - [GET `/v5/analytics/for-advertiser`](#get-v5analyticsfor-advertiser-auth-required) (auth required)
 //!   - [GET `/v5/analytics/for-admin`](#get-v5analyticsfor-admin-auth-required) (auth required)
+//! - [Config](#config) route
+//!   - [GET `/cfg`](#get-cfg)
 //!
 //! ## Channel
 //!
@@ -475,6 +477,24 @@
 //!
 //! See [GET `/v5/analytics`](#get-v5analytics)
 //!
+//! ## Config
+//!
+//! #### GET `/cfg`
+//!
+//! Gets the config that the validator is running on.
+//!
+//! The route is handled by [`get_cfg()`](crate::routes::get_cfg())
+//!
+//! Response: [`Config`](primitives::Config)
+//!
+//! ##### Examples
+//!
+//! Response:
+//!
+//! ```
+#![doc = include_str!("../../primitives/examples/get_cfg_response.rs")]
+//! ```
+//!
 //! [`Adapter`]: adapter::Adapter
 //! [`Address`]: primitives::Address
 //! [`AllowedKey`]: primitives::analytics::query::AllowedKey
@@ -505,9 +525,9 @@
 //! [`SuccessResponse`]: primitives::sentry::SuccessResponse
 //! [`ValidatorId`]: primitives::ValidatorId
 
-pub use analytics::analytics as get_analytics;
+pub use analytics::get_analytics;
 
-pub use cfg::config as get_cfg;
+pub use cfg::get_cfg;
 
 // `analytics` module has single request, so we only export this request
 mod analytics;