From 99f1b6e950138b2414c83a30fe23f9c35c76ac19 Mon Sep 17 00:00:00 2001 From: Jayant Krishnamurthy Date: Thu, 3 Aug 2023 09:24:31 -0700 Subject: [PATCH] [hermes] Finish up docs (#1002) * docs * stuff * comment --- hermes/Cargo.lock | 2 +- hermes/Cargo.toml | 2 +- hermes/src/api/rest.rs | 6 ++++-- hermes/src/api/types.rs | 17 ++++++++--------- hermes/src/doc_examples.rs | 32 ++++++++++++++++++++++++++++++++ hermes/src/main.rs | 1 + 6 files changed, 47 insertions(+), 13 deletions(-) create mode 100644 hermes/src/doc_examples.rs diff --git a/hermes/Cargo.lock b/hermes/Cargo.lock index 2c307403..1e8883fe 100644 --- a/hermes/Cargo.lock +++ b/hermes/Cargo.lock @@ -1764,7 +1764,7 @@ checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8" [[package]] name = "hermes" -version = "0.1.6" +version = "0.1.7" dependencies = [ "anyhow", "axum", diff --git a/hermes/Cargo.toml b/hermes/Cargo.toml index 1d14b7d2..fc76ba86 100644 --- a/hermes/Cargo.toml +++ b/hermes/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "hermes" -version = "0.1.6" +version = "0.1.7" edition = "2021" [dependencies] diff --git a/hermes/src/api/rest.rs b/hermes/src/api/rest.rs index be488fac..214d5fad 100644 --- a/hermes/src/api/rest.rs +++ b/hermes/src/api/rest.rs @@ -5,6 +5,7 @@ use { RpcPriceIdentifier, }, crate::{ + doc_examples, impl_deserialize_for_hex_string_wrapper, store::types::{ RequestTime, @@ -111,7 +112,7 @@ pub struct LatestVaasQueryParams { get, path = "/api/latest_vaas", responses( - (status = 200, description = "VAAs retrieved successfully", body = Vec) + (status = 200, description = "VAAs retrieved successfully", body = Vec, example=json!([doc_examples::vaa_example()])) ), params( LatestVaasQueryParams @@ -199,7 +200,7 @@ pub struct GetPriceFeedQueryParams { id: PriceIdInput, /// The unix timestamp in seconds. This endpoint will return the first update /// whose publish_time is >= the provided value. - #[param(value_type = i64, example=1690576641)] + #[param(value_type = i64, example=doc_examples::timestamp_example)] publish_time: UnixTimestamp, /// If true, include the `metadata` field in the response with additional metadata about /// the price update. @@ -264,6 +265,7 @@ pub struct GetVaaQueryParams { #[derive(Debug, serde::Serialize, ToSchema)] pub struct GetVaaResponse { /// The VAA binary represented as a base64 string. + #[schema(example=doc_examples::vaa_example)] vaa: String, #[serde(rename = "publishTime")] #[schema(value_type = i64, example=1690576641)] diff --git a/hermes/src/api/types.rs b/hermes/src/api/types.rs index 6229fd06..90a13ea0 100644 --- a/hermes/src/api/types.rs +++ b/hermes/src/api/types.rs @@ -1,5 +1,6 @@ use { crate::{ + doc_examples, impl_deserialize_for_hex_string_wrapper, store::types::{ PriceFeedUpdate, @@ -19,23 +20,21 @@ use { Deref, DerefMut, }, - hex::FromHexError, pyth_sdk::PriceIdentifier, utoipa::ToSchema, wormhole_sdk::Chain, }; - /// A price id is a 32-byte hex string, optionally prefixed with "0x". /// Price ids are case insensitive. /// /// Examples: -/// * 0x63f341689d98a12ef60a5cff1d7f85c70a9e17bf1575f0e7c0b2512d48b1c8b3 -/// * 63f341689d98a12ef60a5cff1d7f85c70a9e17bf1575f0e7c0b2512d48b1c8b3 +/// * 0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43 +/// * e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43 /// /// See https://pyth.network/developers/price-feed-ids for a list of all price feed ids. #[derive(Debug, Clone, Deref, DerefMut, ToSchema)] -#[schema(value_type=String, example="63f341689d98a12ef60a5cff1d7f85c70a9e17bf1575f0e7c0b2512d48b1c8b3")] +#[schema(value_type=String, example=doc_examples::price_feed_id_example)] pub struct PriceIdInput([u8; 32]); // TODO: Use const generics instead of macro. impl_deserialize_for_hex_string_wrapper!(PriceIdInput, 32); @@ -54,7 +53,7 @@ pub struct RpcPriceFeedMetadata { pub slot: Slot, #[schema(example = 26)] pub emitter_chain: u16, - #[schema(value_type = i64, example=1690576641)] + #[schema(value_type = i64, example=doc_examples::timestamp_example)] pub price_service_receive_time: UnixTimestamp, } @@ -67,7 +66,7 @@ pub struct RpcPriceFeed { pub metadata: Option, /// The VAA binary represented as a base64 string. #[serde(skip_serializing_if = "Option::is_none")] - #[schema(value_type = Option, example="UE5BVQEAAAADuAEAAAADDQC1H7meY5fTed0FsykIb8dt+7nKpbuzfvU2DplDi+dcUl8MC+UIkS65+rkiq+zmNBxE2gaxkBkjdIicZ/fBo+X7AAEqp+WtlWb84np8jJfLpuQ2W+l5KXTigsdAhz5DyVgU3xs+EnaIZxBwcE7EKzjMam+V9rlRy0CGsiQ1kjqqLzfAAQLsoVO0Vu5gVmgc8XGQ7xYhoz36rsBgMjG+e3l/B01esQi/KzPuBf/Ar8Sg5aSEOvEU0muSDb+KIr6d8eEC+FtcAAPZEaBSt4ysXVL84LUcJemQD3SiG30kOfUpF8o7/wI2M2Jf/LyCsbKEQUyLtLbZqnJBSfZJR5AMsrnHDqngMLEGAAY4UDG9GCpRuPvg8hOlsrXuPP3zq7yVPqyG0SG+bNo8rEhP5b1vXlHdG4bZsutX47d5VZ6xnFROKudx3T3/fnWUAQgAU1+kUFc3e0ZZeX1dLRVEryNIVyxMQIcxWwdey+jlIAYowHRM0fJX3Scs80OnT/CERwh5LMlFyU1w578NqxW+AQl2E/9fxjgUTi8crOfDpwsUsmOWw0+Q5OUGhELv/2UZoHAjsaw9OinWUggKACo4SdpPlHYldoWF+J2yGWOW+F4iAQre4c+ocb6a9uSWOnTldFkioqhd9lhmV542+VonCvuy4Tu214NP+2UNd/4Kk3KJCf3iziQJrCBeLi1cLHdLUikgAQtvRFR/nepcF9legl+DywAkUHi5/1MNjlEQvlHyh2XbMiS85yu7/9LgM6Sr+0ukfZY5mSkOcvUkpHn+T+Nw/IrQAQ7lty5luvKUmBpI3ITxSmojJ1aJ0kj/dc0ZcQk+/qo0l0l3/eRLkYjw5j+MZKA8jEubrHzUCke98eSoj8l08+PGAA+DAKNtCwNZe4p6J1Ucod8Lo5RKFfA84CPLVyEzEPQFZ25U9grUK6ilF4GhEia/ndYXLBt3PGW3qa6CBBPM7rH3ABGAyYEtUwzB4CeVedA5o6cKpjRkIebqDNSOqltsr+w7kXdfFVtsK2FMGFZNt5rbpIR+ppztoJ6eOKHmKmi9nQ99ARKkTxRErOs9wJXNHaAuIRV38o1pxRrlQRzGsRuKBqxcQEpC8OPFpyKYcp6iD5l7cO/gRDTamLFyhiUBwKKMP07FAWTEJv8AAAAAABrhAfrtrFhR4yubI7X5QRqMK6xKrj7U3XuBHdGnLqSqcQAAAAAAGp0GAUFVV1YAAAAAAAUYUmIAACcQBsfKUtr4PgZbIXRxRESU79PjE4IBAFUA5i32yLSoX+GmfbRNwS3l2zMPesZrctxliv7fD0pBW0MAAAKqqMJFwAAAAAAqE/NX////+AAAAABkxCb7AAAAAGTEJvoAAAKqIcWxYAAAAAAlR5m4CP/mPsh1IezjYpDlJ4GRb5q4fTs2LjtyO6M0XgVimrIQ4kSh1qg7JKW4gbGkyRntVFR9JO/GNd3FPDit0BK6M+JzXh/h12YNCz9wxlZTvXrNtWNbzqT+91pvl5cphhSPMfAHyEzTPaGR9tKDy9KNu56pmhaY32d2vfEWQmKo22guegeR98oDxs67MmnUraco46a3zEnac2Bm80pasUgMO24=")] + #[schema(value_type = Option, example=doc_examples::vaa_example)] pub vaa: Option, } @@ -141,7 +140,7 @@ pub struct RpcPrice { pub expo: i32, /// When the price was published. The `publish_time` is a unix timestamp, i.e., the number of /// seconds since the Unix epoch (00:00:00 UTC on 1 Jan 1970). - #[schema(value_type = i64, example=1690576641)] + #[schema(value_type = i64, example=doc_examples::timestamp_example)] pub publish_time: UnixTimestamp, } @@ -163,7 +162,7 @@ pub struct RpcPrice { ToSchema, )] #[repr(C)] -#[schema(value_type = String, example = "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43")] +#[schema(value_type = String, example = doc_examples::price_feed_id_example)] pub struct RpcPriceIdentifier(#[serde(with = "hex")] [u8; 32]); impl RpcPriceIdentifier { diff --git a/hermes/src/doc_examples.rs b/hermes/src/doc_examples.rs new file mode 100644 index 00000000..3d44ec07 --- /dev/null +++ b/hermes/src/doc_examples.rs @@ -0,0 +1,32 @@ +use crate::store::types::UnixTimestamp; + +// Example values for the utoipa API docs. +// Note that each of these expressions is only evaluated once when the documentation is created, +// so the examples don't auto-update over time. We may want to adjust these examples for +// stable/beta in the future so that the example values in the docs work for both hermes and hermes-beta. +// (Currently all example values are for stable.) + +/// Example value for a price feed id +pub fn price_feed_id_example() -> &'static str { + return "e62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43"; +} + +/// Example value for a unix timestamp +pub fn timestamp_example() -> UnixTimestamp { + use std::time::{ + SystemTime, + UNIX_EPOCH, + }; + + let start = SystemTime::now(); + let since_the_epoch = start + .duration_since(UNIX_EPOCH) + .expect("Time went backwards"); + + return since_the_epoch.as_secs() as UnixTimestamp; +} + +/// Example value for a VAA +pub fn vaa_example() -> &'static str { + return "UE5BVQEAAAADuAEAAAADDQC1H7meY5fTed0FsykIb8dt+7nKpbuzfvU2DplDi+dcUl8MC+UIkS65+rkiq+zmNBxE2gaxkBkjdIicZ/fBo+X7AAEqp+WtlWb84np8jJfLpuQ2W+l5KXTigsdAhz5DyVgU3xs+EnaIZxBwcE7EKzjMam+V9rlRy0CGsiQ1kjqqLzfAAQLsoVO0Vu5gVmgc8XGQ7xYhoz36rsBgMjG+e3l/B01esQi/KzPuBf/Ar8Sg5aSEOvEU0muSDb+KIr6d8eEC+FtcAAPZEaBSt4ysXVL84LUcJemQD3SiG30kOfUpF8o7/wI2M2Jf/LyCsbKEQUyLtLbZqnJBSfZJR5AMsrnHDqngMLEGAAY4UDG9GCpRuPvg8hOlsrXuPP3zq7yVPqyG0SG+bNo8rEhP5b1vXlHdG4bZsutX47d5VZ6xnFROKudx3T3/fnWUAQgAU1+kUFc3e0ZZeX1dLRVEryNIVyxMQIcxWwdey+jlIAYowHRM0fJX3Scs80OnT/CERwh5LMlFyU1w578NqxW+AQl2E/9fxjgUTi8crOfDpwsUsmOWw0+Q5OUGhELv/2UZoHAjsaw9OinWUggKACo4SdpPlHYldoWF+J2yGWOW+F4iAQre4c+ocb6a9uSWOnTldFkioqhd9lhmV542+VonCvuy4Tu214NP+2UNd/4Kk3KJCf3iziQJrCBeLi1cLHdLUikgAQtvRFR/nepcF9legl+DywAkUHi5/1MNjlEQvlHyh2XbMiS85yu7/9LgM6Sr+0ukfZY5mSkOcvUkpHn+T+Nw/IrQAQ7lty5luvKUmBpI3ITxSmojJ1aJ0kj/dc0ZcQk+/qo0l0l3/eRLkYjw5j+MZKA8jEubrHzUCke98eSoj8l08+PGAA+DAKNtCwNZe4p6J1Ucod8Lo5RKFfA84CPLVyEzEPQFZ25U9grUK6ilF4GhEia/ndYXLBt3PGW3qa6CBBPM7rH3ABGAyYEtUwzB4CeVedA5o6cKpjRkIebqDNSOqltsr+w7kXdfFVtsK2FMGFZNt5rbpIR+ppztoJ6eOKHmKmi9nQ99ARKkTxRErOs9wJXNHaAuIRV38o1pxRrlQRzGsRuKBqxcQEpC8OPFpyKYcp6iD5l7cO/gRDTamLFyhiUBwKKMP07FAWTEJv8AAAAAABrhAfrtrFhR4yubI7X5QRqMK6xKrj7U3XuBHdGnLqSqcQAAAAAAGp0GAUFVV1YAAAAAAAUYUmIAACcQBsfKUtr4PgZbIXRxRESU79PjE4IBAFUA5i32yLSoX+GmfbRNwS3l2zMPesZrctxliv7fD0pBW0MAAAKqqMJFwAAAAAAqE/NX////+AAAAABkxCb7AAAAAGTEJvoAAAKqIcWxYAAAAAAlR5m4CP/mPsh1IezjYpDlJ4GRb5q4fTs2LjtyO6M0XgVimrIQ4kSh1qg7JKW4gbGkyRntVFR9JO/GNd3FPDit0BK6M+JzXh/h12YNCz9wxlZTvXrNtWNbzqT+91pvl5cphhSPMfAHyEzTPaGR9tKDy9KNu56pmhaY32d2vfEWQmKo22guegeR98oDxs67MmnUraco46a3zEnac2Bm80pasUgMO24="; +} diff --git a/hermes/src/main.rs b/hermes/src/main.rs index de5ef2e4..858ef9df 100644 --- a/hermes/src/main.rs +++ b/hermes/src/main.rs @@ -10,6 +10,7 @@ use { mod api; mod config; +mod doc_examples; mod macros; mod network; mod store;