v3xlabs · lucemans · Apr 17, 2024 · Apr 17, 2024 · Apr 17, 2024 · Apr 17, 2024
diff --git a/server/Cargo.lock b/server/Cargo.lock
diff --git a/server/Cargo.toml b/server/Cargo.toml
@@ -8,53 +8,64 @@ description = "enstate"
 repository = "https://github.com/v3xlabs/enstate"
 authors = [
  "Luc van Kampen <[email protected]>",
+ "Jakob Helgesson <[email protected]>",
  "Antonio Fran Trstenjak <[email protected]>",
  "Miguel Piedrafita <[email protected]>",
 ]
 
 [dependencies]
 enstate_shared = { path = "../shared" }
 
-ethers = "2"
-axum = "0.6.18"
-anyhow = "1.0.71"
-tracing = "0.1.27"
-tracing-subscriber = { version = "0.3.18", features = ["env-filter"] }
+# Server
 dotenvy = "0.15.7"
-serde_json = "1.0.96"
-serde = { version = "1.0", features = ["derive"] }
+axum = "0.7.5"
+anyhow = "1.0.71"
+thiserror = "1.0.48"
+futures = "0.3.29"
 tokio = { version = "1.28.0", features = ["full", "tracing"] }
 tokio-util = "0.7.10"
-futures = "0.3.29"
-utoipa = { version = "4.1.0", features = ["axum_extras"] }
-utoipa-swagger-ui = { version = "4.0.0", features = ["axum"] }
-redis = { version = "0.23.0", features = ["connection-manager", "tokio-comp"] }
-tower-http = { version = "0.4.4", features = ["cors", "tracing", "trace"] }
+tokio-stream = "0.1.14"
+tower-http = { version = "0.5.2", features = ["cors", "tracing", "trace"] }
 rand = "0.8.5"
 chrono = "0.4.31"
+regex = "1.9.5"
+hex-literal = "0.4.1"
+axum-macros = "0.4.1"
+lazy_static = "1.4.0"
+rustc-hex = "2.0.1"
+
+# Serde
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0.96"
+serde_with = "3.3.0"
+serde_qs = "0.13.0"
+
+# Logging & Tracing
+tracing = "0.1.27"
+tracing-subscriber = { version = "0.3.18", features = ["env-filter"] }
+opentelemetry = "0.22.0"
+opentelemetry_sdk = { version = "0.22.1", features = ["rt-tokio"] }
+opentelemetry-otlp = "0.15.0"
+tracing-opentelemetry = "0.23.0"
+
+# Ethereum
+ethers = "2"
 ethers-contract = "2.0.9"
 ethers-core = "2.0.9"
-hex = "0.4.3"
-thiserror = "1.0.48"
-regex = "1.9.5"
-rustls = "0.21.7"
+
+# Hashing
 bs58 = "0.5.0"
 sha2 = "0.10.7"
-digest = "0.10.7"
-hex-literal = "0.4.1"
-axum-macros = "0.3.8"
-lazy_static = "1.4.0"
 base32 = "0.4.0"
 crc16 = "0.4.0"
 blake2 = "0.10.6"
-rustc-hex = "2.0.1"
-serde_with = "3.3.0"
 bech32 = "0.10.0-alpha"
 crc32fast = "1.3.2"
+
+# Other
+hex = "0.4.3"
+redis = { version = "0.25.3", features = ["connection-manager", "tokio-comp"] }
+rustls = "0.23"
+digest = "0.10.7"
 ciborium = "0.2.1"
-serde_qs = "0.12.0"
-tokio-stream = "0.1.14"
-opentelemetry = "0.22.0"
-opentelemetry_sdk = { version = "0.22.1", features = ["rt-tokio"] }
-opentelemetry-otlp = "0.15.0"
-tracing-opentelemetry = "0.23.0"
+utoipa = "4.2.0"
diff --git a/server/src/cache.rs b/server/src/cache.rs
@@ -35,9 +35,7 @@ impl CacheLayer for Redis {
  .set_ex(
  key,
  value,
- expires
- .try_into()
- .map_err(|x: TryFromIntError| CacheError::Other(x.to_string()))?,
+ expires.into(),
  )
  .await;
 

diff --git a/server/src/docs/index.html b/server/src/docs/index.html
@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>API Reference</title>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ </head>
+ <body>
+ <script
+ id="api-reference"
+ data-url="/docs/openapi.json"
+ ></script>
+ <script>
+ var configuration = {
+ theme: "blue",
+ };
+
+ var apiReference = document.getElementById("api-reference");
+ apiReference.dataset.configuration = JSON.stringify(configuration);
+ </script>
+ <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+ </body>
+</html>
diff --git a/server/src/docs/mod.rs b/server/src/docs/mod.rs
@@ -0,0 +1,30 @@
+use crate::models::bulk::{BulkResponse, ListResponse};
+use crate::models::error::ErrorResponse;
+use crate::models::profile::ENSProfile;
+use utoipa::openapi::{ExternalDocs, License};
+use utoipa::OpenApi;
+
+#[derive(OpenApi)]
+#[openapi(
+ info(
+ title = "enstate.rs",
+ description = "A hosted ENS API allowing for easy access to ENS data.",
+ ),
+ paths(
+ crate::routes::address::get, crate::routes::name::get, crate::routes::universal::get,
+ crate::routes::address::get_bulk, crate::routes::name::get_bulk, crate::routes::universal::get_bulk
+ ),
+ components(schemas(ENSProfile, ListResponse<BulkResponse<ENSProfile>>, ErrorResponse))
+)]
+pub struct ApiDoc;
+
+pub async fn openapi() -> String {
+ let mut doc = ApiDoc::openapi();
+
+ let license = License::new("GPLv3");
+
+ doc.info.license = Some(license);
+ doc.external_docs = Some(ExternalDocs::new("https://github.com/v3xlabs/enstate"));
+
+ doc.to_json().unwrap()
+}
diff --git a/server/src/http.rs b/server/src/http.rs
@@ -1,28 +1,18 @@
+use axum::response::{Html, Redirect};
 use std::{net::SocketAddr, sync::Arc};
+use utoipa::OpenApi;
+use utoipa_swagger_ui::SwaggerUi;
 
-use axum::body::HttpBody;
-use axum::routing::MethodRouter;
 use axum::{routing::get, Router};
+use tokio::net::TcpListener;
 use tokio_util::sync::CancellationToken;
 use tower_http::cors::CorsLayer;
 use tower_http::trace::TraceLayer;
 use tracing::info;
-use utoipa::OpenApi;
-use utoipa_swagger_ui::SwaggerUi;
 
-use crate::models::bulk::{BulkResponse, ListResponse};
-use crate::models::error::ErrorResponse;
-use crate::models::profile::ENSProfile;
 use crate::routes;
 use crate::state::AppState;
 
-#[derive(OpenApi)]
-#[openapi(
- paths(routes::address::get, routes::name::get, routes::universal::get),
- components(schemas(ENSProfile, ListResponse<BulkResponse<ENSProfile>>, ErrorResponse))
-)]
-pub struct ApiDoc;
-
 pub struct App {
  router: Router,
 }
@@ -35,11 +25,14 @@ impl App {
  ) -> Result<(), anyhow::Error> {
  let addr = SocketAddr::from(([0, 0, 0, 0], port));
 
- let server = axum::Server::try_bind(&addr)?
- .serve(self.router.into_make_service())
- .with_graceful_shutdown(async {
- shutdown_signal.cancelled().await;
- });
+ let listener = TcpListener::bind(&addr).await?;
+
+ async fn await_shutdown(shutdown_signal: CancellationToken) {
+ shutdown_signal.cancelled().await;
+ }
+
+ let server = axum::serve(listener, self.router.into_make_service())
+ .with_graceful_shutdown(await_shutdown(shutdown_signal));
 
  info!("Listening HTTP on {}", addr);
 
@@ -53,19 +46,24 @@ impl App {
 
 pub fn setup(state: AppState) -> App {
  let router = Router::new()
- .merge(SwaggerUi::new("/docs").url("/docs/openapi.json", ApiDoc::openapi()))
- .route("/", get(routes::root::get))
- .directory_route("/a/:address", get(routes::address::get))
- .directory_route("/n/:name", get(routes::name::get))
- .directory_route("/u/:name_or_address", get(routes::universal::get))
- .directory_route("/i/:name_or_address", get(routes::image::get))
- .directory_route("/h/:name_or_address", get(routes::header::get))
- .directory_route("/bulk/a", get(routes::address::get_bulk))
- .directory_route("/bulk/n", get(routes::name::get_bulk))
- .directory_route("/bulk/u", get(routes::universal::get_bulk))
- .directory_route("/sse/a", get(routes::address::get_bulk_sse))
- .directory_route("/sse/n", get(routes::name::get_bulk_sse))
- .directory_route("/sse/u", get(routes::universal::get_bulk_sse))
+ .route(
+ "/",
+ get(|| async { Redirect::temporary("/docs") }),
+ )
+ .route("/docs", get(scalar_handler))
+ .route("/docs/openapi.json", get(crate::docs::openapi))
+ .route("/this", get(routes::root::get))
+ .route("/a/:address", get(routes::address::get))
+ .route("/n/:name", get(routes::name::get))
+ .route("/u/:name_or_address", get(routes::universal::get))
+ .route("/i/:name_or_address", get(routes::image::get))
+ .route("/h/:name_or_address", get(routes::header::get))
+ .route("/bulk/a", get(routes::address::get_bulk))
+ .route("/bulk/n", get(routes::name::get_bulk))
+ .route("/bulk/u", get(routes::universal::get_bulk))
+ .route("/sse/a", get(routes::address::get_bulk_sse))
+ .route("/sse/n", get(routes::name::get_bulk_sse))
+ .route("/sse/u", get(routes::universal::get_bulk_sse))
  .fallback(routes::four_oh_four::handler)
  .layer(CorsLayer::permissive())
  .layer(TraceLayer::new_for_http())
@@ -74,21 +72,8 @@ pub fn setup(state: AppState) -> App {
  App { router }
 }
 
-trait RouterExt<S, B>
-where
- B: HttpBody + Send + 'static,
- S: Clone + Send + Sync + 'static,
-{
- fn directory_route(self, path: &str, method_router: MethodRouter<S, B>) -> Self;
-}
-
-impl<S, B> RouterExt<S, B> for Router<S, B>
-where
- B: HttpBody + Send + 'static,
- S: Clone + Send + Sync + 'static,
-{
- fn directory_route(self, path: &str, method_router: MethodRouter<S, B>) -> Self {
- self.route(path, method_router.clone())
- .route(&format!("{path}/"), method_router)
- }
+// Loads from docs/index.html with headers html
+async fn scalar_handler() -> Html<&'static str> {
+ let contents = include_str!("./docs/index.html");
+ axum::response::Html(contents)
 }
diff --git a/server/src/main.rs b/server/src/main.rs
@@ -13,6 +13,7 @@ use state::AppState;
 mod abi;
 mod cache;
 mod database;
+mod docs;
 mod http;
 mod models;
 mod provider;

diff --git a/server/src/models/profile.rs b/server/src/models/profile.rs
@@ -6,20 +6,26 @@ use utoipa::ToSchema;
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, ToSchema)]
 pub struct ENSProfile {
  // Name
+ #[schema(example = "vitalik.eth")]
  pub name: String,
  // Ethereum Mainnet Address
+ #[schema(example = "0x225f137127d9067788314bc7fcc1f36746a3c3B5")]
  pub address: Option<String>,
  // Avatar URL
+ #[schema(example = "https://cloudflare-ipfs.com/ipfs/bafkreifnrjhkl7ccr2ifwn2n7ap6dh2way25a6w5x2szegvj5pt4b5nvfu")]
  pub avatar: Option<String>,
  // Preferred Capitalization of Name
+ #[schema(example = "LuC.eTh")]
  pub display: String,
  // Records
  pub records: BTreeMap<String, String>,
  // Addresses on different chains
  pub chains: BTreeMap<String, String>,
  // Unix Timestamp of date it was loaded
+ #[schema(example = "1713363899484")]
  pub fresh: i64,
  // Resolver the information was fetched from
+ #[schema(example = "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41")]
  pub resolver: String,
  // Errors encountered while fetching & decoding
  pub errors: BTreeMap<String, String>,

diff --git a/server/src/routes/address.rs b/server/src/routes/address.rs
@@ -68,15 +68,15 @@ pub struct AddressGetBulkQuery {
 
 #[utoipa::path(
  get,
- path = "/bulk/a/",
+ path = "/bulk/a",
  responses(
  (status = 200, description = "Successfully found address.", body = BulkResponse<ENSProfile>),
  (status = BAD_REQUEST, description = "Invalid address.", body = ErrorResponse),
  (status = NOT_FOUND, description = "No name was associated with this address.", body = ErrorResponse),
  (status = UNPROCESSABLE_ENTITY, description = "Reverse record not owned by this address.", body = ErrorResponse),
  ),
  params(
- ("addresses" = Vec<String>, Path, description = "Addresses to lookup name data for"),
+ ("addresses[]" = Vec<String>, Query, description = "Addresses to lookup name data for"),
  )
 )]
 pub async fn get_bulk(

diff --git a/server/src/routes/name.rs b/server/src/routes/name.rs
@@ -61,13 +61,13 @@ pub struct NameGetBulkQuery {
 
 #[utoipa::path(
  get,
- path = "/bulk/n/",
+ path = "/bulk/n",
  responses(
  (status = 200, description = "Successfully found name.", body = ListButWithLength<BulkResponse<Profile>>),
  (status = NOT_FOUND, description = "No name could be found.", body = ErrorResponse),
  ),
  params(
- ("name" = String, Path, description = "Name to lookup the name data for."),
+ ("names[]" = Vec<String>, Query, description = "Names to lookup name data for"),
  )
 )]
 pub async fn get_bulk(

diff --git a/server/src/routes/universal.rs b/server/src/routes/universal.rs
@@ -14,6 +14,7 @@ use enstate_shared::core::{ENSService, Profile};
 use futures::future::join_all;
 use serde::Deserialize;
 use tokio_stream::wrappers::UnboundedReceiverStream;
+use utoipa::IntoParams;
 
 use crate::models::bulk::{BulkResponse, ListResponse};
 use crate::models::sse::SSEResponse;
@@ -51,7 +52,7 @@ pub async fn get(
  })?
 }
 
-#[derive(Deserialize)]
+#[derive(Deserialize, IntoParams)]
 pub struct UniversalGetBulkQuery {
  // TODO (@antony1060): remove when proper serde error handling
  #[serde(default)]
@@ -63,14 +64,14 @@ pub struct UniversalGetBulkQuery {
 
 #[utoipa::path(
  get,
- path = "/bulk/u/",
+ path = "/bulk/u",
  responses(
  (status = 200, description = "Successfully found name or address.", body = BulkResponse<ENSProfile>),
  (status = NOT_FOUND, description = "No name or address could be found.", body = ErrorResponse),
  (status = UNPROCESSABLE_ENTITY, description = "Reverse record not owned by this address.", body = ErrorResponse),
  ),
  params(
- ("name_or_address" = String, Path, description = "Name or address to lookup the name data for."),
+ ("queries[]" = Vec<String>, Query, description = "Names to lookup name data for"),
  )
 )]
 pub async fn get_bulk(