From 04484940918de89828103d9001c536f63b2ac51f Mon Sep 17 00:00:00 2001 From: h1alexbel Date: Thu, 18 Jul 2024 12:04:30 +0300 Subject: [PATCH 1/2] feat(#84): warn on missing_docs, handlers for better consistency --- server/Cargo.toml | 3 ++ server/src/{routes => handlers}/home.rs | 7 ++-- server/src/{routes => handlers}/mod.rs | 3 +- .../src/{routes => handlers}/register_user.rs | 14 ++++++++ server/src/lib.rs | 35 ++++++++++++++++--- server/src/objects/mod.rs | 1 + server/src/objects/user.rs | 17 ++++++++- server/src/report/mod.rs | 1 + server/src/routes/rs_err.rs | 29 --------------- server/src/xml/mod.rs | 1 + server/src/xml/storage.rs | 23 ++++++++++-- 11 files changed, 90 insertions(+), 44 deletions(-) rename server/src/{routes => handlers}/home.rs (96%) rename server/src/{routes => handlers}/mod.rs (95%) rename server/src/{routes => handlers}/register_user.rs (83%) delete mode 100644 server/src/routes/rs_err.rs diff --git a/server/Cargo.toml b/server/Cargo.toml index abdc6c35..883c5fcf 100644 --- a/server/Cargo.toml +++ b/server/Cargo.toml @@ -34,6 +34,9 @@ authors = ["Aliaksei Bialíauski ", "Ivanchuk Ivan [lib] path = "src/lib.rs" +[lints.rust] +missing_docs = "warn" + [dependencies] openapi = { path = "../github-mirror" } anyhow = "1.0.86" diff --git a/server/src/routes/home.rs b/server/src/handlers/home.rs similarity index 96% rename from server/src/routes/home.rs rename to server/src/handlers/home.rs index 79207220..f17453f8 100644 --- a/server/src/routes/home.rs +++ b/server/src/handlers/home.rs @@ -27,10 +27,7 @@ use log::debug; use crate::ServerConfig; use openapi::models::MetaRoot200Response; -// @todo #79:45min Make mod/fn/struct documentation required. -// Let's configure cargo in such way, so documentation will be required at all -// levels. When such rule will be configured, please fix all warnings/errors -// and integrate changes into master branch. +/// Home handler. pub async fn home(State(config): State) -> impl IntoResponse { let response = Json( MetaRoot200Response::new( @@ -191,7 +188,7 @@ pub async fn home(State(config): State) -> impl IntoResponse { #[cfg(test)] mod tests { - use crate::routes::home::home; + use crate::handlers::home::home; use crate::ServerConfig; use anyhow::Result; use axum::body::to_bytes; diff --git a/server/src/routes/mod.rs b/server/src/handlers/mod.rs similarity index 95% rename from server/src/routes/mod.rs rename to server/src/handlers/mod.rs index 1e466dc4..4c86d7fb 100644 --- a/server/src/routes/mod.rs +++ b/server/src/handlers/mod.rs @@ -19,6 +19,7 @@ // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE // SOFTWARE. +/// Home handler. pub mod home; +/// Handler for internal user registration. pub mod register_user; -pub mod rs_err; diff --git a/server/src/routes/register_user.rs b/server/src/handlers/register_user.rs similarity index 83% rename from server/src/routes/register_user.rs rename to server/src/handlers/register_user.rs index ae5edbd4..351fd547 100644 --- a/server/src/routes/register_user.rs +++ b/server/src/handlers/register_user.rs @@ -24,6 +24,20 @@ use axum::Json; use crate::objects::user::User; +/// Register user. +/// +/// # Fields +/// +/// * `payload`: JSON payload +/// +/// # Examples +/// +/// ``` +/// use axum::Json; +/// use server::handlers::register_user::register_user; +/// use server::objects::user::User; +/// let registration = register_user(Json(User::new(String::from("jeff")))); +/// ``` pub async fn register_user(Json(payload): Json) -> Result { let user = User::new(payload.username.clone()); match user.save().await { diff --git a/server/src/lib.rs b/server/src/lib.rs index d618463e..cb75d677 100644 --- a/server/src/lib.rs +++ b/server/src/lib.rs @@ -19,6 +19,9 @@ // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE // SOFTWARE. +/*! +Fakehub server and storage. + */ use std::io; use anyhow::Result; @@ -26,32 +29,53 @@ use axum::routing::{get, post}; use axum::Router; use tokio::net::TcpListener; -use crate::routes::home; -use crate::routes::register_user::register_user; +use crate::handlers::home; +use crate::handlers::register_user::register_user; use crate::xml::storage::Storage; -mod objects; +/// Handlers. +pub mod handlers; +/// GitHub domain objects. +pub mod objects; +/// Reports. pub mod report; -mod routes; -mod xml; +/// XML storage. +pub mod xml; #[allow(unused_imports)] #[macro_use] extern crate hamcrest; +/// Server. #[derive(Default)] pub struct Server { + /// Port. port: usize, } impl Server { + /// Create new server with port. + /// + /// * `port`: Server port + /// + /// returns: Server + /// + /// Examples: + /// + /// ``` + /// use server::Server; + /// let server = Server::new(1234); + /// ``` pub fn new(port: usize) -> Server { Server { port } } } +/// Server configuration. #[derive(Clone)] pub struct ServerConfig { + /// Server host. pub host: String, + /// Server port. pub port: usize, } @@ -59,6 +83,7 @@ pub struct ServerConfig { // Let's create a handler that would log requests failed with 404. Let's use // info!() for this one. impl Server { + /// Start a server. pub async fn start(self) -> Result<()> { tracing_subscriber::fmt::init(); Storage::new(Some("fakehub.xml")); diff --git a/server/src/objects/mod.rs b/server/src/objects/mod.rs index 06c393b7..5c804301 100644 --- a/server/src/objects/mod.rs +++ b/server/src/objects/mod.rs @@ -19,4 +19,5 @@ // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE // SOFTWARE. +/// GitHub user. pub mod user; diff --git a/server/src/objects/user.rs b/server/src/objects/user.rs index 4519d4a4..88276706 100644 --- a/server/src/objects/user.rs +++ b/server/src/objects/user.rs @@ -24,12 +24,26 @@ use log::{debug, info}; use serde::{Deserialize, Serialize}; use serde_xml_rs::to_string; +/// GitHub user. #[derive(Debug, Serialize, Deserialize)] pub struct User { + /// Username. pub(crate) username: String, } impl User { + /// New user. + /// + /// # Fields + /// + /// * `username`: Username + /// + /// # Examples + /// + /// ``` + /// use server::objects::user::User; + /// let jeff = User::new(String::from("jeff123")); + /// ``` pub fn new(username: String) -> User { User { username } } @@ -45,8 +59,9 @@ impl User { // We should prohibit to use #unwrap() function in our code. Let's configure // clippy tool in the respective manner and get rid of all #unwrap() calls. impl User { + /// Save user. pub async fn save(self) -> Result<()> { - info!("registering user @{}", self.username); + info!("saving user @{}", self.username); let xml = to_string(&self).unwrap(); debug!("XMLed user: {}", xml); Ok(()) diff --git a/server/src/report/mod.rs b/server/src/report/mod.rs index d320dffa..a4bda56c 100644 --- a/server/src/report/mod.rs +++ b/server/src/report/mod.rs @@ -22,4 +22,5 @@ // @todo #41:45min Create similar to latex.rs functions for XML and TXT formats. // Let's create similar to latex.rs functions for generating reports in XML and TXT. // Don't forget to remove this puzzle. +/// LaTeX report. pub mod latex; diff --git a/server/src/routes/rs_err.rs b/server/src/routes/rs_err.rs deleted file mode 100644 index e0d54b3c..00000000 --- a/server/src/routes/rs_err.rs +++ /dev/null @@ -1,29 +0,0 @@ -// The MIT License (MIT) -// -// Copyright (c) 2024 Aliaksei Bialiauski -// -// Permission is hereby granted, free of charge, to any person obtaining a copy -// of this software and associated documentation files (the "Software"), to deal -// in the Software without restriction, including without limitation the rights -// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -// copies of the Software, and to permit persons to whom the Software is -// furnished to do so, subject to the following conditions: -// -// The above copyright notice and this permission notice shall be included -// in all copies or substantial portions of the Software. -// -// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE -// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -// SOFTWARE. -use serde::Serialize; - -#[derive(Serialize)] -pub struct RsErr { - pub status: String, - pub message: String, - pub trace: String, -} diff --git a/server/src/xml/mod.rs b/server/src/xml/mod.rs index e263c1e6..770a42f2 100644 --- a/server/src/xml/mod.rs +++ b/server/src/xml/mod.rs @@ -19,4 +19,5 @@ // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE // SOFTWARE. +/// Storage. pub mod storage; diff --git a/server/src/xml/storage.rs b/server/src/xml/storage.rs index 939b4c7d..fa68afd2 100644 --- a/server/src/xml/storage.rs +++ b/server/src/xml/storage.rs @@ -1,6 +1,3 @@ -use std::fs::File; -use std::io::Write; - // The MIT License (MIT) // // Copyright (c) 2024 Aliaksei Bialiauski @@ -24,9 +21,12 @@ use std::io::Write; // SOFTWARE. use anyhow::Result; use log::info; +use std::fs::File; +use std::io::Write; #[derive(Default)] #[allow(dead_code)] +/// Storage. pub struct Storage { pub(crate) path: String, } @@ -37,6 +37,22 @@ const INIT_XML: &str = " "; impl Storage { + /// New storage. + /// + /// # Fields + /// * `path`: Storage path + /// + /// # Examples + /// + /// ``` + /// use server::xml::storage::Storage; + /// let storage = Storage::new(Some("test.xml")); + /// ``` + /// Or use default path: + /// ``` + /// use server::xml::storage::Storage; + /// let storage = Storage::new(None); + /// ``` pub fn new(path: Option<&str>) -> Storage { let location = path.unwrap_or("fakehub.xml"); info!("Initializing XML storage: {location}"); @@ -62,6 +78,7 @@ impl Storage { // Don't forget to create a unit tests related to #xml function. impl Storage { #[allow(dead_code)] + /// Return XML from the storage. pub fn xml() -> Result<()> { Ok(()) } From 6e382e618a87616497c944f7d9dc69f242ca568a Mon Sep 17 00:00:00 2001 From: h1alexbel Date: Sun, 21 Jul 2024 14:22:12 +0300 Subject: [PATCH 2/2] feat(#84): deny instead of wanr --- server/Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/server/Cargo.toml b/server/Cargo.toml index 883c5fcf..00b8f755 100644 --- a/server/Cargo.toml +++ b/server/Cargo.toml @@ -35,7 +35,7 @@ authors = ["Aliaksei Bialíauski ", "Ivanchuk Ivan path = "src/lib.rs" [lints.rust] -missing_docs = "warn" +missing_docs = "deny" [dependencies] openapi = { path = "../github-mirror" }