tsk-63: Rust update (#67)

Closes #63

Reviewed-on: #67
Co-authored-by: phoenix <kundeng00@pm.me>
Co-committed-by: phoenix <kundeng00@pm.me>

.env.docker.sample

@@ -1,3 +1,8 @@
+APP_ENV=development
+BACKEND_PORT=8001
+FRONTEND_URL=http://localhost:4200
+RUST_LOG=debug
+ALLOWED_ORIGINS=https://soaricarus.com,https://www.soaricarus.com
 SECRET_KEY=refero34o8rfhfjn983thf39fhc943rf923n3h
 SERVICE_PASSPHRASE=iUOo1fxshf3y1tUGn1yU8l9raPApHCdinW0VdCHdRFEjqhR3Bf02aZzsKbLtaDFH
 POSTGRES_AUTH_USER=icarus_op

.env.sample

@@ -1,3 +1,8 @@
+APP_ENV=development
+BACKEND_PORT=8001
+FRONTEND_URL=http://localhost:4200
+RUST_LOG=debug
+ALLOWED_ORIGINS=https://soaricarus.com,https://www.soaricarus.com
 SECRET_KEY=refero34o8rfhfjn983thf39fhc943rf923n3h
 SERVICE_PASSPHRASE=iUOo1fxshf3y1tUGn1yU8l9raPApHCdinW0VdCHdRFEjqhR3Bf02aZzsKbLtaDFH
 POSTGRES_AUTH_USER=icarus_op_test

.gitea/workflows/tag_release.yml

@@ -10,14 +10,14 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0 # Important for git describe --tags
 
       - name: Install Rust
         uses: actions-rs/toolchain@v1
         with:
-          toolchain: 1.88.0
+          toolchain: 1.90.0
           components: cargo
 
       - name: Extract Version from Cargo.toml

.gitea/workflows/workflow.yml

@@ -15,10 +15,10 @@ jobs:
     name: Check
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: 1.88.0
+          toolchain: 1.90.0
       - run: |
           mkdir -p ~/.ssh
           echo "${{ secrets.MYREPO_TOKEN }}" > ~/.ssh/icarus_models_deploy_key
@@ -50,10 +50,10 @@ jobs:
           --health-retries 5
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: 1.88.0
+          toolchain: 1.90.0
       # --- Add this step for explicit verification ---
       - name: Verify Docker Environment
         run: |
@@ -91,10 +91,10 @@ jobs:
     name: Rustfmt
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: 1.88.0
+          toolchain: 1.90.0
       - run: rustup component add rustfmt
       - run: |
           mkdir -p ~/.ssh
@@ -110,10 +110,10 @@ jobs:
     name: Clippy
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: 1.88.0
+          toolchain: 1.90.0
       - run: rustup component add clippy
       - run: |
           mkdir -p ~/.ssh
@@ -129,10 +129,10 @@ jobs:
     name: build
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: 1.88.0
+          toolchain: 1.90.0
       - run: |
           mkdir -p ~/.ssh
           echo "${{ secrets.MYREPO_TOKEN }}" > ~/.ssh/icarus_models_deploy_key

Cargo.toml

@@ -1,27 +1,30 @@
 [package]
 name = "icarus_auth"
-version = "0.4.3"
+version = "0.6.0"
 edition = "2024"
-rust-version = "1.88"
+rust-version = "1.90"
 
 [dependencies]
-axum = { version = "0.8.4" }
-serde = { version = "1.0.219", features = ["derive"] }
-serde_json = { version = "1.0.140" }
-tokio = { version = "1.45.1", features = ["rt-multi-thread"] }
-tracing-subscriber = { version = "0.3.19" }
-tower = { version = "0.5.2" }
-hyper = { version = "1.6.0" }
+axum = { version = "0.8.6" }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = { version = "1.0.145" }
+tokio = { version = "1.47.1", features = ["rt-multi-thread"] }
+tracing-subscriber = { version = "0.3.20" }
+tower = { version = "0.5.2", features = ["full"] }
+tower-http = { version = "0.6.6", features = ["cors"] }
+hyper = { version = "1.7.0" }
 sqlx = { version = "0.8.6", features = ["postgres", "runtime-tokio-native-tls", "time", "uuid"] }
-uuid = { version = "1.17.0", features = ["v4", "serde"] }
+uuid = { version = "1.18.1", features = ["v4", "serde"] }
 argon2 = { version = "0.5.3", features = ["std"] } # Use the latest 0.5.x version
-rand = { version = "0.9.1" }
+rand = { version = "0.9.2" }
 time = { version = "0.3.41", features = ["macros", "serde"] }
 josekit = { version = "0.10.3" }
-icarus_models = { git = "ssh://git@git.kundeng.us/phoenix/icarus_models.git", tag = "v0.5.5-devel-bd793db08e-111" }
-icarus_envy = { git = "ssh://git@git.kundeng.us/phoenix/icarus_envy.git", tag = "v0.3.1-main-3cd42dab6b-006" }
+utoipa = { version = "5.4.0", features = ["axum_extras"] }
+utoipa-swagger-ui = { version = "9.0.2", features = ["axum"] }
+icarus_models = { git = "ssh://git@git.kundeng.us/phoenix/icarus_models.git", tag = "v0.7.0" }
+icarus_envy = { git = "ssh://git@git.kundeng.us/phoenix/icarus_envy.git", tag = "v0.5.0" }
 
 [dev-dependencies]
 http-body-util = { version = "0.1.3" }
-url = { version = "2.5.4" }
+url = { version = "2.5.7" }
 once_cell = { version = "1.21.3" } # Useful for lazy initialization in tests/app setup

Dockerfile

@@ -1,7 +1,7 @@
 # Stage 1: Build the application
 # Use a specific Rust version for reproducibility. Choose one that matches your development environment.
 # Using slim variant for smaller base image
-FROM rust:1.88 as builder
+FROM rust:1.90 as builder
 
 # Set the working directory inside the container
 WORKDIR /usr/src/app

README.md

@@ -1,9 +1,12 @@
+A auth web API services for the Icarus project.
 
 
 # Getting Started
-Copy the `.env.sample` file to `.env` and ensure that the variables are populated. This project
-can be used with regular hosting or with docker. For the sake of getting up to speed quickly,
-Docker will be covered. Make sure docker is running and your ssh identity has been loaded.
+The easiest way to get started is through docker. This assumes that docker is already installed
+on your system. Copy the `.env.docker.sample` as `.env`. Most of the data in the env file doesn't 
+need to be modified. The `SECRET_KEY` variable should be changed since it will be used for token
+generation. The `SECRET_PASSPHASE` should also be changed when in production mode, but make sure
+the respective `passphrase` database table record exists.
 
 Build image
 ```
@@ -24,3 +27,6 @@ Pruning
 ```
 docker system prune -a
 ```
+
+To view the OpenAPI spec, run the project and access `/swagger-ui`. If running through docker,
+the url would be something like `http://localhost:8000/swagger-ui`.

docker-compose.yaml

@@ -9,7 +9,7 @@ services:
     container_name: icarus_auth # Optional: Give the container a specific name
     ports:
       # Map host port 8000 to container port 3000 (adjust as needed)
-      - "8000:3000"
+      - "8001:8001"
     env_file:
       - .env
     depends_on:

src/callers/common.rs

@@ -1,7 +1,7 @@
 pub mod response {
     use serde::{Deserialize, Serialize};
 
-    #[derive(Deserialize, Serialize)]
+    #[derive(Deserialize, Serialize, utoipa::ToSchema)]
     pub struct TestResult {
         pub message: String,
     }
@@ -11,11 +11,28 @@ pub mod endpoint {
     use super::*;
     use axum::{Extension, Json, http::StatusCode};
 
-    // basic handler that responds with a static string
+    /// Endpoint to hit the root
+    /// basic handler that responds with a static string
+    #[utoipa::path(
+        get,
+        path = super::super::endpoints::ROOT,
+        responses(
+            (status = 200, description = "Test", body = &str),
+        )
+    )]
     pub async fn root() -> &'static str {
         "Hello, World!"
     }
 
+    /// Endpoint to do a database ping
+    #[utoipa::path(
+        get,
+        path = super::super::endpoints::DBTEST,
+        responses(
+            (status = 200, description = "Successful ping of the db", body = super::response::TestResult),
+            (status = 400, description = "Failure in pinging the db", body = super::response::TestResult)
+        )
+    )]
     pub async fn db_ping(
         Extension(pool): Extension<sqlx::PgPool>,
     ) -> (StatusCode, Json<response::TestResult>) {

src/callers/login.rs

@@ -1,21 +1,21 @@
 pub mod request {
     use serde::{Deserialize, Serialize};
 
-    #[derive(Default, Deserialize, Serialize)]
+    #[derive(Default, Deserialize, Serialize, utoipa::ToSchema)]
     pub struct Request {
         pub username: String,
         pub password: String,
     }
 
     pub mod service_login {
-        #[derive(Debug, serde::Deserialize, serde::Serialize)]
+        #[derive(Debug, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
         pub struct Request {
             pub passphrase: String,
         }
     }
 
     pub mod refresh_token {
-        #[derive(Debug, serde::Deserialize, serde::Serialize)]
+        #[derive(Debug, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
         pub struct Request {
             pub access_token: String,
         }
@@ -25,14 +25,14 @@ pub mod request {
 pub mod response {
     use serde::{Deserialize, Serialize};
 
-    #[derive(Default, Deserialize, Serialize)]
+    #[derive(Default, Deserialize, Serialize, utoipa::ToSchema)]
     pub struct Response {
         pub message: String,
         pub data: Vec<icarus_models::login_result::LoginResult>,
     }
 
     pub mod service_login {
-        #[derive(Debug, Default, serde::Deserialize, serde::Serialize)]
+        #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
         pub struct Response {
             pub message: String,
             pub data: Vec<icarus_models::login_result::LoginResult>,
@@ -40,7 +40,7 @@ pub mod response {
     }
 
     pub mod refresh_token {
-        #[derive(Debug, Default, serde::Deserialize, serde::Serialize)]
+        #[derive(Debug, Default, serde::Deserialize, serde::Serialize, utoipa::ToSchema)]
         pub struct Response {
             pub message: String,
             pub data: Vec<icarus_models::login_result::LoginResult>,
@@ -48,6 +48,7 @@ pub mod response {
     }
 }
 
+/// Module for login endpoints
 pub mod endpoint {
     use axum::{Json, http::StatusCode};
 
@@ -72,6 +73,20 @@ pub mod endpoint {
         )
     }
 
+    /// Endpoint to login
+    #[utoipa::path(
+        post,
+        path = super::super::endpoints::LOGIN,
+        request_body(
+            content = request::Request,
+            description = "Data required to login",
+            content_type = "application/json"
+        ),
+        responses(
+            (status = 200, description = "Successfully logged in", body = response::Response),
+            (status = 404, description = "Could not login with credentials", body = response::Response)
+        )
+    )]
     pub async fn login(
         axum::Extension(pool): axum::Extension<sqlx::PgPool>,
         Json(payload): Json<request::Request>,
@@ -81,7 +96,7 @@ pub mod endpoint {
             Ok(user) => {
                 if hashing::verify_password(&payload.password, user.password.clone()).unwrap() {
                     // Create token
-                    let key = icarus_envy::environment::get_secret_key().await;
+                    let key = icarus_envy::environment::get_secret_key().await.value;
                     let (token_literal, duration) =
                         token_stuff::create_token(&key, &user.id).unwrap();
 
@@ -115,6 +130,20 @@ pub mod endpoint {
         }
     }
 
+    /// Endpoint to login as a service user
+    #[utoipa::path(
+        post,
+        path = super::super::endpoints::SERVICE_LOGIN,
+        request_body(
+            content = request::service_login::Request,
+            description = "Data required to login as a service user",
+            content_type = "application/json"
+        ),
+        responses(
+            (status = 200, description = "Login successful", body = response::Response),
+            (status = 400, description = "Error logging in with credentials", body = response::Response)
+        )
+    )]
     pub async fn service_login(
         axum::Extension(pool): axum::Extension<sqlx::PgPool>,
         axum::Json(payload): axum::Json<request::service_login::Request>,
@@ -126,7 +155,7 @@ pub mod endpoint {
 
         match repo::service::valid_passphrase(&pool, &payload.passphrase).await {
             Ok((id, _passphrase, _date_created)) => {
-                let key = icarus_envy::environment::get_secret_key().await;
+                let key = icarus_envy::environment::get_secret_key().await.value;
                 let (token_literal, duration) =
                     token_stuff::create_service_token(&key, &id).unwrap();
 
@@ -154,6 +183,22 @@ pub mod endpoint {
         }
     }
 
+    /// Endpoint to retrieve a refresh token
+    #[utoipa::path(
+        post,
+        path = super::super::endpoints::REFRESH_TOKEN,
+        request_body(
+            content = request::refresh_token::Request,
+            description = "Data required to retrieve a refresh token",
+            content_type = "application/json"
+        ),
+        responses(
+            (status = 200, description = "Refresh token generated", body = response::Response),
+            (status = 400, description = "Error verifying token", body = response::Response),
+            (status = 404, description = "Could not validate token", body = response::Response),
+            (status = 500, description = "Error extracting token", body = response::Response)
+        )
+    )]
     pub async fn refresh_token(
         axum::Extension(pool): axum::Extension<sqlx::PgPool>,
         axum::Json(payload): axum::Json<request::refresh_token::Request>,
@@ -162,7 +207,7 @@ pub mod endpoint {
         axum::Json<response::refresh_token::Response>,
     ) {
         let mut response = response::refresh_token::Response::default();
-        let key = icarus_envy::environment::get_secret_key().await;
+        let key = icarus_envy::environment::get_secret_key().await.value;
 
         if token_stuff::verify_token(&key, &payload.access_token) {
             let token_type = token_stuff::get_token_type(&key, &payload.access_token).unwrap();

src/callers/register.rs

@@ -6,7 +6,7 @@ use crate::repo;
 pub mod request {
     use serde::{Deserialize, Serialize};
 
-    #[derive(Default, Deserialize, Serialize)]
+    #[derive(Default, Deserialize, Serialize, utoipa::ToSchema)]
     pub struct Request {
         #[serde(skip_serializing_if = "String::is_empty")]
         pub username: String,
@@ -26,13 +26,28 @@ pub mod request {
 pub mod response {
     use serde::{Deserialize, Serialize};
 
-    #[derive(Deserialize, Serialize)]
+    #[derive(Deserialize, Serialize, utoipa::ToSchema)]
     pub struct Response {
         pub message: String,
         pub data: Vec<icarus_models::user::User>,
     }
 }
 
+/// Endpoint to register a user
+#[utoipa::path(
+    post,
+    path = super::endpoints::REGISTER,
+    request_body(
+        content = request::Request,
+        description = "Data required to register",
+        content_type = "application/json"
+    ),
+    responses(
+        (status = 201, description = "User created", body = response::Response),
+        (status = 404, description = "User already exists", body = response::Response),
+        (status = 400, description = "Issue creating user", body = response::Response)
+    )
+)]
 pub async fn register_user(
     axum::Extension(pool): axum::Extension<sqlx::PgPool>,
     Json(payload): Json<request::Request>,

src/config/mod.rs

@@ -6,5 +6,5 @@ fn get_address() -> String {
 }
 
 fn get_port() -> String {
-    String::from("3000")
+    String::from("8001")
 }

src/lib.rs

@@ -1,3 +1,4 @@
+// TODO: Get rid of this file and place the code in more appropriate places
 pub mod callers;
 pub mod config;
 pub mod hashing;
@@ -15,7 +16,7 @@ pub mod db {
     use crate::connection_settings;
 
     pub async fn create_pool() -> Result<sqlx::PgPool, sqlx::Error> {
-        let database_url = icarus_envy::environment::get_db_url().await;
+        let database_url = icarus_envy::environment::get_db_url().await.value;
         println!("Database url: {database_url}");
 
         PgPoolOptions::new()

src/main.rs

@@ -8,7 +8,7 @@ async fn main() {
 
     let app = init::app().await;
 
-    // run our app with hyper, listening globally on port 3000
+    // run our app with hyper, listening globally on port 8001
     let url = config::get_full();
     let listener = tokio::net::TcpListener::bind(url).await.unwrap();
     axum::serve(listener, app).await.unwrap();
@@ -19,8 +19,79 @@ mod init {
         Router,
         routing::{get, post},
     };
+    use utoipa::OpenApi;
 
     use crate::callers;
+    use callers::common as common_callers;
+    use callers::login as login_caller;
+    use callers::register as register_caller;
+    use login_caller::endpoint as login_endpoints;
+    use login_caller::response as login_responses;
+    use register_caller::response as register_responses;
+
+    #[derive(utoipa::OpenApi)]
+    #[openapi(
+        paths(
+            common_callers::endpoint::db_ping, common_callers::endpoint::root,
+            register_caller::register_user,
+            login_endpoints::login, login_endpoints::service_login, login_endpoints::refresh_token
+            ),
+        components(schemas(common_callers::response::TestResult,
+                register_responses::Response,
+            login_responses::Response, login_responses::service_login::Response, login_responses::refresh_token::Response)),
+        tags(
+            (name = "Icarus Auth API", description = "Auth API for Icarus API")
+            )
+    )]
+    struct ApiDoc;
+
+    mod cors {
+        pub async fn configure_cors() -> tower_http::cors::CorsLayer {
+            // Start building the CORS layer with common settings
+            let cors = tower_http::cors::CorsLayer::new()
+                .allow_methods([
+                    axum::http::Method::GET,
+                    axum::http::Method::POST,
+                    axum::http::Method::PUT,
+                    axum::http::Method::DELETE,
+                ]) // Specify allowed methods:cite[2]
+                .allow_headers([
+                    axum::http::header::CONTENT_TYPE,
+                    axum::http::header::AUTHORIZATION,
+                ]) // Specify allowed headers:cite[2]
+                .allow_credentials(true) // If you need to send cookies or authentication headers:cite[2]
+                .max_age(std::time::Duration::from_secs(3600)); // Cache the preflight response for 1 hour:cite[2]
+
+            // Dynamically set the allowed origin based on the environment
+            match std::env::var(icarus_envy::keys::APP_ENV).as_deref() {
+                Ok("production") => {
+                    let allowed_origins_env = icarus_envy::environment::get_allowed_origins().await;
+                    match icarus_envy::utility::delimitize(&allowed_origins_env) {
+                        Ok(alwd) => {
+                            let allowed_origins: Vec<axum::http::HeaderValue> = alwd
+                                .into_iter()
+                                .map(|s| s.parse::<axum::http::HeaderValue>().unwrap())
+                                .collect();
+                            cors.allow_origin(allowed_origins)
+                        }
+                        Err(err) => {
+                            eprintln!(
+                                "Could not parse out allowed origins from env: Error: {err:?}"
+                            );
+                            std::process::exit(-1);
+                        }
+                    }
+                }
+                _ => {
+                    // Development (default): Allow localhost origins
+                    cors.allow_origin(vec![
+                        "http://localhost:4200".parse().unwrap(),
+                        "http://127.0.0.1:4200".parse().unwrap(),
+                    ])
+                }
+            }
+        }
+    }
 
     pub async fn routes() -> Router {
         // build our application with a route
@@ -49,6 +120,7 @@ mod init {
                 callers::endpoints::REFRESH_TOKEN,
                 post(callers::login::endpoint::refresh_token),
             )
+            .layer(cors::configure_cors().await)
     }
 
     pub async fn app() -> Router {
@@ -58,7 +130,13 @@ mod init {
 
         icarus_auth::db::migrations(&pool).await;
 
-        routes().await.layer(axum::Extension(pool))
+        routes()
+            .await
+            .merge(
+                utoipa_swagger_ui::SwaggerUi::new("/swagger-ui")
+                    .url("/api-docs/openapi.json", ApiDoc::openapi()),
+            )
+            .layer(axum::Extension(pool))
     }
 }
 
@@ -80,7 +158,7 @@ mod tests {
         pub const LIMIT: usize = 6;
 
         pub async fn get_pool() -> Result<sqlx::PgPool, sqlx::Error> {
-            let tm_db_url = icarus_envy::environment::get_db_url().await;
+            let tm_db_url = icarus_envy::environment::get_db_url().await.value;
             let tm_options = sqlx::postgres::PgConnectOptions::from_str(&tm_db_url).unwrap();
             sqlx::PgPool::connect_with(tm_options).await
         }
@@ -93,7 +171,7 @@ mod tests {
         }
 
         pub async fn connect_to_db(db_name: &str) -> Result<sqlx::PgPool, sqlx::Error> {
-            let db_url = icarus_envy::environment::get_db_url().await;
+            let db_url = icarus_envy::environment::get_db_url().await.value;
             let options = sqlx::postgres::PgConnectOptions::from_str(&db_url)?.database(db_name);
             sqlx::PgPool::connect_with(options).await
         }
@@ -120,7 +198,7 @@ mod tests {
         }
 
         pub async fn get_database_name() -> Result<String, Box<dyn std::error::Error>> {
-            let database_url = icarus_envy::environment::get_db_url().await;
+            let database_url = icarus_envy::environment::get_db_url().await.value;
 
             let parsed_url = url::Url::parse(&database_url)?;
             if parsed_url.scheme() == "postgres" || parsed_url.scheme() == "postgresql" {
@@ -423,7 +501,7 @@ mod tests {
 
         let app = init::routes().await.layer(axum::Extension(pool));
         let id = uuid::Uuid::parse_str("22f9c775-cce9-457a-a147-9dafbb801f61").unwrap();
-        let key = icarus_envy::environment::get_secret_key().await;
+        let key = icarus_envy::environment::get_secret_key().await.value;
 
         match icarus_auth::token_stuff::create_service_token(&key, &id) {
             Ok((token, _expire)) => {

src/token_stuff/mod.rs

@@ -124,7 +124,9 @@ mod tests {
     #[test]
     fn test_tokenize() {
         let rt = tokio::runtime::Runtime::new().unwrap();
-        let special_key = rt.block_on(icarus_envy::environment::get_secret_key());
+        let special_key = rt
+            .block_on(icarus_envy::environment::get_secret_key())
+            .value;
         let id = uuid::Uuid::new_v4();
         match create_token(&special_key, &id) {
             Ok((token, _duration)) => {