chore: separate backend from frontend

src/lib.rs

@@ -0,0 +1,82 @@
+//! Backend API server for phundrak.com
+//!
+//! This is a REST API built with the Poem framework that provides:
+//! - Health check endpoints
+//! - Application metadata endpoints
+//! - Contact form submission with email integration
+
+#![deny(clippy::all)]
+#![deny(clippy::pedantic)]
+#![deny(clippy::nursery)]
+#![warn(missing_docs)]
+#![allow(clippy::unused_async)]
+
+/// Custom middleware implementations
+pub mod middleware;
+/// API route handlers and endpoints
+pub mod route;
+/// Application configuration settings
+pub mod settings;
+/// Application startup and server configuration
+pub mod startup;
+/// Logging and tracing setup
+pub mod telemetry;
+
+type MaybeListener = Option<poem::listener::TcpListener<String>>;
+
+fn prepare(listener: MaybeListener) -> startup::Application {
+    dotenvy::dotenv().ok();
+    let settings = settings::Settings::new().expect("Failed to read settings");
+    if !cfg!(test) {
+        let subscriber = telemetry::get_subscriber(settings.debug);
+        telemetry::init_subscriber(subscriber);
+    }
+    tracing::event!(
+        target: "backend",
+        tracing::Level::DEBUG,
+        "Using these settings: {:?}",
+        settings
+    );
+    let application = startup::Application::build(settings, listener);
+    tracing::event!(
+        target: "backend",
+        tracing::Level::INFO,
+        "Listening on http://{}:{}/",
+        application.host(),
+        application.port()
+    );
+    tracing::event!(
+        target: "backend",
+        tracing::Level::INFO,
+        "Documentation available at http://{}:{}/",
+        application.host(),
+        application.port()
+    );
+    application
+}
+
+/// Runs the application with the specified TCP listener.
+///
+/// # Errors
+///
+/// Returns a `std::io::Error` if the server fails to start or encounters
+/// an I/O error during runtime (e.g., port already in use, network issues).
+#[cfg(not(tarpaulin_include))]
+pub async fn run(listener: MaybeListener) -> Result<(), std::io::Error> {
+    let application = prepare(listener);
+    application.make_app().run().await
+}
+
+#[cfg(test)]
+fn make_random_tcp_listener() -> poem::listener::TcpListener<String> {
+    let tcp_listener =
+        std::net::TcpListener::bind("127.0.0.1:0").expect("Failed to bind a random TCP listener");
+    let port = tcp_listener.local_addr().unwrap().port();
+    poem::listener::TcpListener::bind(format!("127.0.0.1:{port}"))
+}
+
+#[cfg(test)]
+fn get_test_app() -> startup::App {
+    let tcp_listener = make_random_tcp_listener();
+    prepare(Some(tcp_listener)).make_app().into()
+}

src/main.rs

@@ -0,0 +1,7 @@
+//! Backend server entry point.
+
+#[cfg(not(tarpaulin_include))]
+#[tokio::main]
+async fn main() -> Result<(), std::io::Error> {
+    phundrak_dot_com_backend::run(None).await
+}

src/middleware/mod.rs

@@ -0,0 +1,5 @@
+//! Custom middleware for the application.
+//!
+//! This module contains custom middleware implementations including rate limiting.
+
+pub mod rate_limit;

src/middleware/rate_limit.rs

@@ -0,0 +1,211 @@
+//! Rate limiting middleware using the governor crate.
+//!
+//! This middleware implements per-IP rate limiting using the Generic Cell Rate
+//! Algorithm (GCRA) via the governor crate. It stores rate limiters in memory
+//! without requiring external dependencies like Redis.
+
+use std::{
+    net::IpAddr,
+    num::NonZeroU32,
+    sync::Arc,
+    time::Duration,
+};
+
+use governor::{
+    clock::DefaultClock,
+    state::{InMemoryState, NotKeyed},
+    Quota, RateLimiter,
+};
+use poem::{
+    Endpoint, Error, IntoResponse, Middleware, Request, Response, Result,
+};
+
+/// Rate limiting configuration.
+#[derive(Debug, Clone)]
+pub struct RateLimitConfig {
+    /// Maximum number of requests allowed in the time window (burst size).
+    pub burst_size: u32,
+    /// Time window in seconds for rate limiting.
+    pub per_seconds: u64,
+}
+
+impl RateLimitConfig {
+    /// Creates a new rate limit configuration.
+    ///
+    /// # Arguments
+    ///
+    /// * `burst_size` - Maximum number of requests allowed in the time window
+    /// * `per_seconds` - Time window in seconds
+    #[must_use]
+    pub const fn new(burst_size: u32, per_seconds: u64) -> Self {
+        Self {
+            burst_size,
+            per_seconds,
+        }
+    }
+
+    /// Creates a rate limiter from this configuration.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `burst_size` is zero.
+    #[must_use]
+    pub fn create_limiter(&self) -> RateLimiter<NotKeyed, InMemoryState, DefaultClock> {
+        let quota = Quota::with_period(Duration::from_secs(self.per_seconds))
+            .expect("Failed to create quota")
+            .allow_burst(NonZeroU32::new(self.burst_size).expect("Burst size must be non-zero"));
+        RateLimiter::direct(quota)
+    }
+}
+
+impl Default for RateLimitConfig {
+    fn default() -> Self {
+        // Default: 10 requests per second with burst of 20
+        Self::new(20, 1)
+    }
+}
+
+/// Middleware for rate limiting based on IP address.
+pub struct RateLimit {
+    limiter: Arc<RateLimiter<NotKeyed, InMemoryState, DefaultClock>>,
+}
+
+impl RateLimit {
+    /// Creates a new rate limiting middleware with the given configuration.
+    #[must_use]
+    pub fn new(config: &RateLimitConfig) -> Self {
+        Self {
+            limiter: Arc::new(config.create_limiter()),
+        }
+    }
+}
+
+impl<E: Endpoint> Middleware<E> for RateLimit {
+    type Output = RateLimitEndpoint<E>;
+
+    fn transform(&self, ep: E) -> Self::Output {
+        RateLimitEndpoint {
+            endpoint: ep,
+            limiter: self.limiter.clone(),
+        }
+    }
+}
+
+/// The endpoint wrapper that performs rate limiting checks.
+pub struct RateLimitEndpoint<E> {
+    endpoint: E,
+    limiter: Arc<RateLimiter<NotKeyed, InMemoryState, DefaultClock>>,
+}
+
+impl<E: Endpoint> Endpoint for RateLimitEndpoint<E> {
+    type Output = Response;
+
+    async fn call(&self, req: Request) -> Result<Self::Output> {
+        // Check rate limit
+        if self.limiter.check().is_err() {
+            let client_ip = Self::get_client_ip(&req)
+                .map_or_else(|| "unknown".to_string(), |ip| ip.to_string());
+
+            tracing::event!(
+                target: "backend::middleware::rate_limit",
+                tracing::Level::WARN,
+                client_ip = %client_ip,
+                "Rate limit exceeded"
+            );
+
+            return Err(Error::from_status(poem::http::StatusCode::TOO_MANY_REQUESTS));
+        }
+
+        // Process the request
+        let response = self.endpoint.call(req).await;
+        response.map(IntoResponse::into_response)
+    }
+}
+
+impl<E> RateLimitEndpoint<E> {
+    /// Extracts the client IP address from the request.
+    fn get_client_ip(req: &Request) -> Option<IpAddr> {
+        req.remote_addr().as_socket_addr().map(std::net::SocketAddr::ip)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn rate_limit_config_new() {
+        let config = RateLimitConfig::new(10, 60);
+        assert_eq!(config.burst_size, 10);
+        assert_eq!(config.per_seconds, 60);
+    }
+
+    #[test]
+    fn rate_limit_config_default() {
+        let config = RateLimitConfig::default();
+        assert_eq!(config.burst_size, 20);
+        assert_eq!(config.per_seconds, 1);
+    }
+
+    #[test]
+    fn rate_limit_config_creates_limiter() {
+        let config = RateLimitConfig::new(5, 1);
+        let limiter = config.create_limiter();
+
+        // First 5 requests should succeed
+        for _ in 0..5 {
+            assert!(limiter.check().is_ok());
+        }
+
+        // 6th request should fail
+        assert!(limiter.check().is_err());
+    }
+
+    #[tokio::test]
+    async fn rate_limit_middleware_allows_within_limit() {
+        use poem::{handler, test::TestClient, EndpointExt, Route};
+
+        #[handler]
+        async fn index() -> String {
+            "Hello".to_string()
+        }
+
+        let config = RateLimitConfig::new(5, 60);
+        let app = Route::new()
+            .at("/", poem::get(index))
+            .with(RateLimit::new(&config));
+        let cli = TestClient::new(app);
+
+        // First 5 requests should succeed
+        for _ in 0..5 {
+            let response = cli.get("/").send().await;
+            response.assert_status_is_ok();
+        }
+    }
+
+    #[tokio::test]
+    async fn rate_limit_middleware_blocks_over_limit() {
+        use poem::{handler, test::TestClient, EndpointExt, Route};
+
+        #[handler]
+        async fn index() -> String {
+            "Hello".to_string()
+        }
+
+        let config = RateLimitConfig::new(3, 60);
+        let app = Route::new()
+            .at("/", poem::get(index))
+            .with(RateLimit::new(&config));
+        let cli = TestClient::new(app);
+
+        // First 3 requests should succeed
+        for _ in 0..3 {
+            let response = cli.get("/").send().await;
+            response.assert_status_is_ok();
+        }
+
+        // 4th request should be rate limited
+        let response = cli.get("/").send().await;
+        response.assert_status(poem::http::StatusCode::TOO_MANY_REQUESTS);
+    }
+}

src/route/contact.rs

@@ -0,0 +1,514 @@
+//! Contact form endpoint for handling user submissions and sending emails.
+//!
+//! This module provides functionality to:
+//! - Validate contact form submissions
+//! - Detect spam using honeypot fields
+//! - Send emails via SMTP with various TLS configurations
+
+use lettre::{
+    Message, SmtpTransport, Transport, message::header::ContentType,
+    transport::smtp::authentication::Credentials,
+};
+use poem_openapi::{ApiResponse, Object, OpenApi, payload::Json};
+use validator::Validate;
+
+use super::ApiCategory;
+use crate::settings::{EmailSettings, Starttls};
+
+impl TryFrom<&EmailSettings> for SmtpTransport {
+    type Error = lettre::transport::smtp::Error;
+
+    fn try_from(settings: &EmailSettings) -> Result<Self, Self::Error> {
+        if settings.tls {
+            // Implicit TLS (SMTPS) - typically port 465
+            tracing::event!(target: "backend::contact", tracing::Level::DEBUG, "Using implicit TLS (SMTPS)");
+            let creds = Credentials::new(settings.user.clone(), settings.password.clone());
+            Ok(Self::relay(&settings.host)?
+                .port(settings.port)
+                .credentials(creds)
+                .build())
+        } else {
+            // STARTTLS or no encryption
+            match settings.starttls {
+                Starttls::Never => {
+                    // For local development without TLS
+                    tracing::event!(target: "backend::contact", tracing::Level::DEBUG, "Using unencrypted connection");
+                    let builder = Self::builder_dangerous(&settings.host).port(settings.port);
+                    if settings.user.is_empty() {
+                        Ok(builder.build())
+                    } else {
+                        let creds =
+                            Credentials::new(settings.user.clone(), settings.password.clone());
+                        Ok(builder.credentials(creds).build())
+                    }
+                }
+                Starttls::Opportunistic | Starttls::Always => {
+                    // STARTTLS - typically port 587
+                    tracing::event!(target: "backend::contact", tracing::Level::DEBUG, "Using STARTTLS");
+                    let creds = Credentials::new(settings.user.clone(), settings.password.clone());
+                    Ok(Self::starttls_relay(&settings.host)?
+                        .port(settings.port)
+                        .credentials(creds)
+                        .build())
+                }
+            }
+        }
+    }
+}
+
+#[derive(Debug, Object, Validate)]
+struct ContactRequest {
+    #[validate(length(
+        min = 1,
+        max = "100",
+        message = "Name must be between 1 and 100 characters"
+    ))]
+    name: String,
+    #[validate(email(message = "Invalid email address"))]
+    email: String,
+    #[validate(length(
+        min = 10,
+        max = 5000,
+        message = "Message must be between 10 and 5000 characters"
+    ))]
+    message: String,
+    /// Honeypot field - should always be empty
+    #[oai(rename = "website")]
+    honeypot: Option<String>,
+}
+
+#[derive(Debug, Object, serde::Deserialize)]
+struct ContactResponse {
+    success: bool,
+    message: String,
+}
+
+impl From<ContactResponse> for Json<ContactResponse> {
+    fn from(value: ContactResponse) -> Self {
+        Self(value)
+    }
+}
+
+#[derive(ApiResponse)]
+enum ContactApiResponse {
+    /// Success
+    #[oai(status = 200)]
+    Ok(Json<ContactResponse>),
+    /// Bad Request - validation failed
+    #[oai(status = 400)]
+    BadRequest(Json<ContactResponse>),
+    /// Too Many Requests - rate limit exceeded
+    #[oai(status = 429)]
+    #[allow(dead_code)]
+    TooManyRequests,
+    /// Internal Server Error
+    #[oai(status = 500)]
+    InternalServerError(Json<ContactResponse>),
+}
+
+/// API for handling contact form submissions and sending emails.
+#[derive(Clone)]
+pub struct ContactApi {
+    settings: EmailSettings,
+}
+
+impl From<EmailSettings> for ContactApi {
+    fn from(settings: EmailSettings) -> Self {
+        Self { settings }
+    }
+}
+
+#[OpenApi(tag = "ApiCategory::Contact")]
+impl ContactApi {
+    /// Submit a contact form
+    ///
+    /// Send a message through the contact form. Rate limited to prevent spam.
+    #[oai(path = "/contact", method = "post")]
+    async fn submit_contact(
+        &self,
+        body: Json<ContactRequest>,
+        remote_addr: Option<poem::web::Data<&poem::web::RemoteAddr>>,
+    ) -> ContactApiResponse {
+        let body = body.0;
+        if body.honeypot.is_some() {
+            tracing::event!(target: "backend::contact", tracing::Level::INFO, "Honeypot triggered, rejecting request silently. IP: {}", remote_addr.map_or_else(|| "No remote address found".to_owned(), |ip| ip.0.to_string()));
+            return ContactApiResponse::Ok(
+                ContactResponse {
+                    success: true,
+                    message: "Message sent successfully, but not really, you bot".to_owned(),
+                }
+                .into(),
+            );
+        }
+        if let Err(e) = body.validate() {
+            return ContactApiResponse::BadRequest(
+                ContactResponse {
+                    success: false,
+                    message: format!("Validation error: {e}"),
+                }
+                .into(),
+            );
+        }
+        match self.send_email(&body).await {
+            Ok(()) => {
+                tracing::event!(target: "backend::contact", tracing::Level::INFO, "Message sent successfully from: {}", body.email);
+                ContactApiResponse::Ok(
+                    ContactResponse {
+                        success: true,
+                        message: "Message sent successfully".to_owned(),
+                    }
+                    .into(),
+                )
+            }
+            Err(e) => {
+                tracing::event!(target: "backend::contact", tracing::Level::ERROR, "Failed to send email: {}", e);
+                ContactApiResponse::InternalServerError(
+                    ContactResponse {
+                        success: false,
+                        message: "Failed to send message. Please try again later.".to_owned(),
+                    }
+                    .into(),
+                )
+            }
+        }
+    }
+
+    async fn send_email(&self, request: &ContactRequest) -> Result<(), Box<dyn std::error::Error>> {
+        let email_body = format!(
+            r"New contact form submission:
+
+Name: {}
+Email: {},
+
+Message:
+{}",
+            request.name, request.email, request.message
+        );
+        tracing::event!(target: "email", tracing::Level::DEBUG, "Sending email content: {}", email_body);
+        let email = Message::builder()
+            .from(self.settings.from.parse()?)
+            .reply_to(format!("{} <{}>", request.name, request.email).parse()?)
+            .to(self.settings.recipient.parse()?)
+            .subject(format!("Contact Form: {}", request.name))
+            .header(ContentType::TEXT_PLAIN)
+            .body(email_body)?;
+        tracing::event!(target: "email", tracing::Level::DEBUG, "Email to be sent: {}", format!("{email:?}"));
+
+        let mailer = SmtpTransport::try_from(&self.settings)?;
+        mailer.send(&email)?;
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Tests for ContactRequest validation
+    #[test]
+    fn contact_request_valid() {
+        let request = ContactRequest {
+            name: "John Doe".to_string(),
+            email: "john@example.com".to_string(),
+            message: "This is a test message that is long enough.".to_string(),
+            honeypot: None,
+        };
+        assert!(request.validate().is_ok());
+    }
+
+    #[test]
+    fn contact_request_name_too_short() {
+        let request = ContactRequest {
+            name: String::new(),
+            email: "john@example.com".to_string(),
+            message: "This is a test message that is long enough.".to_string(),
+            honeypot: None,
+        };
+        assert!(request.validate().is_err());
+    }
+
+    #[test]
+    fn contact_request_name_too_long() {
+        let request = ContactRequest {
+            name: "a".repeat(101),
+            email: "john@example.com".to_string(),
+            message: "This is a test message that is long enough.".to_string(),
+            honeypot: None,
+        };
+        assert!(request.validate().is_err());
+    }
+
+    #[test]
+    fn contact_request_name_at_max_length() {
+        let request = ContactRequest {
+            name: "a".repeat(100),
+            email: "john@example.com".to_string(),
+            message: "This is a test message that is long enough.".to_string(),
+            honeypot: None,
+        };
+        assert!(request.validate().is_ok());
+    }
+
+    #[test]
+    fn contact_request_invalid_email() {
+        let request = ContactRequest {
+            name: "John Doe".to_string(),
+            email: "not-an-email".to_string(),
+            message: "This is a test message that is long enough.".to_string(),
+            honeypot: None,
+        };
+        assert!(request.validate().is_err());
+    }
+
+    #[test]
+    fn contact_request_message_too_short() {
+        let request = ContactRequest {
+            name: "John Doe".to_string(),
+            email: "john@example.com".to_string(),
+            message: "Short".to_string(),
+            honeypot: None,
+        };
+        assert!(request.validate().is_err());
+    }
+
+    #[test]
+    fn contact_request_message_too_long() {
+        let request = ContactRequest {
+            name: "John Doe".to_string(),
+            email: "john@example.com".to_string(),
+            message: "a".repeat(5001),
+            honeypot: None,
+        };
+        assert!(request.validate().is_err());
+    }
+
+    #[test]
+    fn contact_request_message_at_min_length() {
+        let request = ContactRequest {
+            name: "John Doe".to_string(),
+            email: "john@example.com".to_string(),
+            message: "a".repeat(10),
+            honeypot: None,
+        };
+        assert!(request.validate().is_ok());
+    }
+
+    #[test]
+    fn contact_request_message_at_max_length() {
+        let request = ContactRequest {
+            name: "John Doe".to_string(),
+            email: "john@example.com".to_string(),
+            message: "a".repeat(5000),
+            honeypot: None,
+        };
+        assert!(request.validate().is_ok());
+    }
+
+    // Tests for SmtpTransport TryFrom implementation
+    #[test]
+    fn smtp_transport_implicit_tls() {
+        let settings = EmailSettings {
+            host: "smtp.example.com".to_string(),
+            port: 465,
+            user: "user@example.com".to_string(),
+            password: "password".to_string(),
+            from: "from@example.com".to_string(),
+            recipient: "to@example.com".to_string(),
+            tls: true,
+            starttls: Starttls::Never,
+        };
+
+        let result = SmtpTransport::try_from(&settings);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn smtp_transport_starttls_always() {
+        let settings = EmailSettings {
+            host: "smtp.example.com".to_string(),
+            port: 587,
+            user: "user@example.com".to_string(),
+            password: "password".to_string(),
+            from: "from@example.com".to_string(),
+            recipient: "to@example.com".to_string(),
+            tls: false,
+            starttls: Starttls::Always,
+        };
+
+        let result = SmtpTransport::try_from(&settings);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn smtp_transport_starttls_opportunistic() {
+        let settings = EmailSettings {
+            host: "smtp.example.com".to_string(),
+            port: 587,
+            user: "user@example.com".to_string(),
+            password: "password".to_string(),
+            from: "from@example.com".to_string(),
+            recipient: "to@example.com".to_string(),
+            tls: false,
+            starttls: Starttls::Opportunistic,
+        };
+
+        let result = SmtpTransport::try_from(&settings);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn smtp_transport_no_encryption_with_credentials() {
+        let settings = EmailSettings {
+            host: "localhost".to_string(),
+            port: 1025,
+            user: "user@example.com".to_string(),
+            password: "password".to_string(),
+            from: "from@example.com".to_string(),
+            recipient: "to@example.com".to_string(),
+            tls: false,
+            starttls: Starttls::Never,
+        };
+
+        let result = SmtpTransport::try_from(&settings);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn smtp_transport_no_encryption_no_credentials() {
+        let settings = EmailSettings {
+            host: "localhost".to_string(),
+            port: 1025,
+            user: String::new(),
+            password: String::new(),
+            from: "from@example.com".to_string(),
+            recipient: "to@example.com".to_string(),
+            tls: false,
+            starttls: Starttls::Never,
+        };
+
+        let result = SmtpTransport::try_from(&settings);
+        assert!(result.is_ok());
+    }
+
+    // Integration tests for contact API endpoint
+    #[tokio::test]
+    async fn contact_endpoint_honeypot_triggered() {
+        let app = crate::get_test_app();
+        let cli = poem::test::TestClient::new(app);
+
+        let body = serde_json::json!({
+            "name": "Bot Name",
+            "email": "bot@example.com",
+            "message": "This is a spam message from a bot.",
+            "website": "http://spam.com"
+        });
+
+        let resp = cli.post("/api/contact").body_json(&body).send().await;
+        resp.assert_status_is_ok();
+
+        let json_text = resp.0.into_body().into_string().await.unwrap();
+        let json: ContactResponse = serde_json::from_str(&json_text).unwrap();
+        assert!(json.success);
+        assert!(json.message.contains("not really"));
+    }
+
+    #[tokio::test]
+    async fn contact_endpoint_validation_error_empty_name() {
+        let app = crate::get_test_app();
+        let cli = poem::test::TestClient::new(app);
+
+        let body = serde_json::json!({
+            "name": "",
+            "email": "test@example.com",
+            "message": "This is a valid message that is long enough."
+        });
+
+        let resp = cli.post("/api/contact").body_json(&body).send().await;
+        resp.assert_status(poem::http::StatusCode::BAD_REQUEST);
+
+        let json_text = resp.0.into_body().into_string().await.unwrap();
+        let json: ContactResponse = serde_json::from_str(&json_text).unwrap();
+        assert!(!json.success);
+        assert!(json.message.contains("Validation error"));
+    }
+
+    #[tokio::test]
+    async fn contact_endpoint_validation_error_invalid_email() {
+        let app = crate::get_test_app();
+        let cli = poem::test::TestClient::new(app);
+
+        let body = serde_json::json!({
+            "name": "Test User",
+            "email": "not-an-email",
+            "message": "This is a valid message that is long enough."
+        });
+
+        let resp = cli.post("/api/contact").body_json(&body).send().await;
+        resp.assert_status(poem::http::StatusCode::BAD_REQUEST);
+
+        let json_text = resp.0.into_body().into_string().await.unwrap();
+        let json: ContactResponse = serde_json::from_str(&json_text).unwrap();
+        assert!(!json.success);
+        assert!(json.message.contains("Validation error"));
+    }
+
+    #[tokio::test]
+    async fn contact_endpoint_validation_error_message_too_short() {
+        let app = crate::get_test_app();
+        let cli = poem::test::TestClient::new(app);
+
+        let body = serde_json::json!({
+            "name": "Test User",
+            "email": "test@example.com",
+            "message": "Short"
+        });
+
+        let resp = cli.post("/api/contact").body_json(&body).send().await;
+        resp.assert_status(poem::http::StatusCode::BAD_REQUEST);
+
+        let json_text = resp.0.into_body().into_string().await.unwrap();
+        let json: ContactResponse = serde_json::from_str(&json_text).unwrap();
+        assert!(!json.success);
+        assert!(json.message.contains("Validation error"));
+    }
+
+    #[tokio::test]
+    async fn contact_endpoint_validation_error_name_too_long() {
+        let app = crate::get_test_app();
+        let cli = poem::test::TestClient::new(app);
+
+        let body = serde_json::json!({
+            "name": "a".repeat(101),
+            "email": "test@example.com",
+            "message": "This is a valid message that is long enough."
+        });
+
+        let resp = cli.post("/api/contact").body_json(&body).send().await;
+        resp.assert_status(poem::http::StatusCode::BAD_REQUEST);
+
+        let json_text = resp.0.into_body().into_string().await.unwrap();
+        let json: ContactResponse = serde_json::from_str(&json_text).unwrap();
+        assert!(!json.success);
+        assert!(json.message.contains("Validation error"));
+    }
+
+    #[tokio::test]
+    async fn contact_endpoint_validation_error_message_too_long() {
+        let app = crate::get_test_app();
+        let cli = poem::test::TestClient::new(app);
+
+        let body = serde_json::json!({
+            "name": "Test User",
+            "email": "test@example.com",
+            "message": "a".repeat(5001)
+        });
+
+        let resp = cli.post("/api/contact").body_json(&body).send().await;
+        resp.assert_status(poem::http::StatusCode::BAD_REQUEST);
+
+        let json_text = resp.0.into_body().into_string().await.unwrap();
+        let json: ContactResponse = serde_json::from_str(&json_text).unwrap();
+        assert!(!json.success);
+        assert!(json.message.contains("Validation error"));
+    }
+}

src/route/health.rs

@@ -0,0 +1,38 @@
+//! Health check endpoint for monitoring service availability.
+
+use poem_openapi::{ApiResponse, OpenApi};
+
+use super::ApiCategory;
+
+#[derive(ApiResponse)]
+enum HealthResponse {
+    /// Success
+    #[oai(status = 200)]
+    Ok,
+    /// Too Many Requests - rate limit exceeded
+    #[oai(status = 429)]
+    #[allow(dead_code)]
+    TooManyRequests,
+}
+
+/// Health check API for monitoring service availability.
+#[derive(Default, Clone)]
+pub struct HealthApi;
+
+#[OpenApi(tag = "ApiCategory::Health")]
+impl HealthApi {
+    #[oai(path = "/health", method = "get")]
+    async fn ping(&self) -> HealthResponse {
+        tracing::event!(target: "backend::health", tracing::Level::DEBUG, "Accessing health-check endpoint");
+        HealthResponse::Ok
+    }
+}
+
+#[tokio::test]
+async fn health_check_works() {
+    let app = crate::get_test_app();
+    let cli = poem::test::TestClient::new(app);
+    let resp = cli.get("/api/health").send().await;
+    resp.assert_status_is_ok();
+    resp.assert_text("").await;
+}

src/route/meta.rs

@@ -0,0 +1,86 @@
+//! Application metadata endpoint for retrieving version and name information.
+
+use poem::Result;
+use poem_openapi::{ApiResponse, Object, OpenApi, payload::Json};
+
+use super::ApiCategory;
+use crate::settings::ApplicationSettings;
+
+#[derive(Object, Debug, Clone, serde::Serialize, serde::Deserialize)]
+struct Meta {
+    version: String,
+    name: String,
+}
+
+impl From<&MetaApi> for Meta {
+    fn from(value: &MetaApi) -> Self {
+        let version = value.version.clone();
+        let name = value.name.clone();
+        Self { version, name }
+    }
+}
+
+#[derive(ApiResponse)]
+enum MetaResponse {
+    /// Success
+    #[oai(status = 200)]
+    Meta(Json<Meta>),
+    /// Too Many Requests - rate limit exceeded
+    #[oai(status = 429)]
+    #[allow(dead_code)]
+    TooManyRequests,
+}
+
+/// API for retrieving application metadata (name and version).
+#[derive(Clone)]
+pub struct MetaApi {
+    name: String,
+    version: String,
+}
+
+impl From<&ApplicationSettings> for MetaApi {
+    fn from(value: &ApplicationSettings) -> Self {
+        let name = value.name.clone();
+        let version = value.version.clone();
+        Self { name, version }
+    }
+}
+
+#[OpenApi(tag = "ApiCategory::Meta")]
+impl MetaApi {
+    #[oai(path = "/meta", method = "get")]
+    async fn meta(&self) -> Result<MetaResponse> {
+        tracing::event!(target: "backend::meta", tracing::Level::DEBUG, "Accessing meta endpoint");
+        Ok(MetaResponse::Meta(Json(self.into())))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #[tokio::test]
+    async fn meta_endpoint_returns_correct_data() {
+        let app = crate::get_test_app();
+        let cli = poem::test::TestClient::new(app);
+        let resp = cli.get("/api/meta").send().await;
+        resp.assert_status_is_ok();
+
+        let json_value: serde_json::Value = resp.json().await.value().deserialize();
+
+        assert!(
+            json_value.get("version").is_some(),
+            "Response should have version field"
+        );
+        assert!(
+            json_value.get("name").is_some(),
+            "Response should have name field"
+        );
+    }
+
+    #[tokio::test]
+    async fn meta_endpoint_returns_200_status() {
+        let app = crate::get_test_app();
+        let cli = poem::test::TestClient::new(app);
+        let resp = cli.get("/api/meta").send().await;
+        resp.assert_status_is_ok();
+    }
+}

src/route/mod.rs

@@ -0,0 +1,46 @@
+//! API route handlers for the backend server.
+//!
+//! This module contains all the HTTP endpoint handlers organized by functionality:
+//! - Contact form handling
+//! - Health checks
+//! - Application metadata
+
+use poem_openapi::Tags;
+
+mod contact;
+mod health;
+mod meta;
+
+use crate::settings::Settings;
+
+#[derive(Tags)]
+enum ApiCategory {
+    Contact,
+    Health,
+    Meta,
+}
+
+pub(crate) struct Api {
+    contact: contact::ContactApi,
+    health: health::HealthApi,
+    meta: meta::MetaApi,
+}
+
+impl From<&Settings> for Api {
+    fn from(value: &Settings) -> Self {
+        let contact = contact::ContactApi::from(value.clone().email);
+        let health = health::HealthApi;
+        let meta = meta::MetaApi::from(&value.application);
+        Self {
+            contact,
+            health,
+            meta,
+        }
+    }
+}
+
+impl Api {
+    pub fn apis(self) -> (contact::ContactApi, health::HealthApi, meta::MetaApi) {
+        (self.contact, self.health, self.meta)
+    }
+}

src/settings.rs

@@ -0,0 +1,619 @@
+//! Application configuration settings.
+//!
+//! This module provides configuration structures that can be loaded from:
+//! - YAML configuration files (base.yaml and environment-specific files)
+//! - Environment variables (prefixed with APP__)
+//!
+//! Settings include application details, email server configuration, and environment settings.
+
+/// Application configuration settings.
+///
+/// Loads configuration from YAML files and environment variables.
+#[derive(Debug, serde::Deserialize, Clone, Default)]
+pub struct Settings {
+    /// Application-specific settings (name, version, host, port, etc.)
+    pub application: ApplicationSettings,
+    /// Debug mode flag
+    pub debug: bool,
+    /// Email server configuration for contact form
+    pub email: EmailSettings,
+    /// Frontend URL for CORS configuration
+    pub frontend_url: String,
+    /// Rate limiting configuration
+    #[serde(default)]
+    pub rate_limit: RateLimitSettings,
+}
+
+impl Settings {
+    /// Creates a new `Settings` instance by loading configuration from files and environment variables.
+    ///
+    /// # Errors
+    ///
+    /// Returns a `config::ConfigError` if:
+    /// - Configuration files cannot be read or parsed
+    /// - Required configuration values are missing
+    /// - Configuration values cannot be deserialized into the expected types
+    ///
+    /// # Panics
+    ///
+    /// Panics if:
+    /// - The current directory cannot be determined
+    /// - The `APP_ENVIRONMENT` variable contains an invalid value (not "dev", "development", "prod", or "production")
+    pub fn new() -> Result<Self, config::ConfigError> {
+        let base_path = std::env::current_dir().expect("Failed to determine the current directory");
+        let settings_directory = base_path.join("settings");
+        let environment: Environment = std::env::var("APP_ENVIRONMENT")
+            .unwrap_or_else(|_| "dev".into())
+            .try_into()
+            .expect("Failed to parse APP_ENVIRONMENT");
+        let environment_filename = format!("{environment}.yaml");
+        // Lower = takes precedence
+        let settings = config::Config::builder()
+            .add_source(config::File::from(settings_directory.join("base.yaml")))
+            .add_source(config::File::from(
+                settings_directory.join(environment_filename),
+            ))
+            .add_source(
+                config::Environment::with_prefix("APP")
+                    .prefix_separator("__")
+                    .separator("__"),
+            )
+            .build()?;
+        settings.try_deserialize()
+    }
+}
+
+/// Application-specific configuration settings.
+#[derive(Debug, serde::Deserialize, Clone, Default)]
+pub struct ApplicationSettings {
+    /// Application name
+    pub name: String,
+    /// Application version
+    pub version: String,
+    /// Port to bind to
+    pub port: u16,
+    /// Host address to bind to
+    pub host: String,
+    /// Base URL of the application
+    pub base_url: String,
+    /// Protocol (http or https)
+    pub protocol: String,
+}
+
+/// Application environment.
+#[derive(Debug, PartialEq, Eq, Default)]
+pub enum Environment {
+    /// Development environment
+    #[default]
+    Development,
+    /// Production environment
+    Production,
+}
+
+impl std::fmt::Display for Environment {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let self_str = match self {
+            Self::Development => "development",
+            Self::Production => "production",
+        };
+        write!(f, "{self_str}")
+    }
+}
+
+impl TryFrom<String> for Environment {
+    type Error = String;
+
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        Self::try_from(value.as_str())
+    }
+}
+
+impl TryFrom<&str> for Environment {
+    type Error = String;
+
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        match value.to_lowercase().as_str() {
+            "development" | "dev" => Ok(Self::Development),
+            "production" | "prod" => Ok(Self::Production),
+            other => Err(format!(
+                "{other} is not a supported environment. Use either `development` or `production`"
+            )),
+        }
+    }
+}
+
+/// Email server configuration for the contact form.
+#[derive(serde::Deserialize, Clone, Default)]
+pub struct EmailSettings {
+    /// SMTP server hostname
+    pub host: String,
+    /// SMTP server port
+    pub port: u16,
+    /// SMTP authentication username
+    pub user: String,
+    /// Email address to send from
+    pub from: String,
+    /// SMTP authentication password
+    pub password: String,
+    /// Email address to send contact form submissions to
+    pub recipient: String,
+    /// STARTTLS configuration
+    pub starttls: Starttls,
+    /// Whether to use implicit TLS (SMTPS)
+    pub tls: bool,
+}
+
+impl std::fmt::Debug for EmailSettings {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("EmailSettings")
+            .field("host", &self.host)
+            .field("port", &self.port)
+            .field("user", &self.user)
+            .field("from", &self.from)
+            .field("password", &"[REDACTED]")
+            .field("recipient", &self.recipient)
+            .field("starttls", &self.starttls)
+            .field("tls", &self.tls)
+            .finish()
+    }
+}
+
+/// STARTTLS configuration for SMTP connections.
+#[derive(Debug, PartialEq, Eq, Default, Clone)]
+pub enum Starttls {
+    /// Never use STARTTLS (unencrypted connection)
+    #[default]
+    Never,
+    /// Use STARTTLS if available (opportunistic encryption)
+    Opportunistic,
+    /// Always use STARTTLS (required encryption)
+    Always,
+}
+
+impl TryFrom<&str> for Starttls {
+    type Error = String;
+
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        match value.to_lowercase().as_str() {
+            "off" | "no" | "never" => Ok(Self::Never),
+            "opportunistic" => Ok(Self::Opportunistic),
+            "yes" | "always" => Ok(Self::Always),
+            other => Err(format!(
+                "{other} is not a supported option. Use either `yes`, `no`, or `opportunistic`"
+            )),
+        }
+    }
+}
+
+impl TryFrom<String> for Starttls {
+    type Error = String;
+    fn try_from(value: String) -> Result<Self, Self::Error> {
+        value.as_str().try_into()
+    }
+}
+
+impl From<bool> for Starttls {
+    fn from(value: bool) -> Self {
+        if value { Self::Always } else { Self::Never }
+    }
+}
+
+impl std::fmt::Display for Starttls {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let self_str = match self {
+            Self::Never => "never",
+            Self::Opportunistic => "opportunistic",
+            Self::Always => "always",
+        };
+        write!(f, "{self_str}")
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for Starttls {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        struct StartlsVisitor;
+
+        impl serde::de::Visitor<'_> for StartlsVisitor {
+            type Value = Starttls;
+
+            fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
+                formatter.write_str("a string or boolean representing STARTTLS setting (e.g., 'yes', 'no', 'opportunistic', true, false)")
+            }
+
+            fn visit_str<E>(self, value: &str) -> Result<Starttls, E>
+            where
+                E: serde::de::Error,
+            {
+                Starttls::try_from(value).map_err(E::custom)
+            }
+
+            fn visit_string<E>(self, value: String) -> Result<Starttls, E>
+            where
+                E: serde::de::Error,
+            {
+                Starttls::try_from(value.as_str()).map_err(E::custom)
+            }
+
+            fn visit_bool<E>(self, value: bool) -> Result<Starttls, E>
+            where
+                E: serde::de::Error,
+            {
+                Ok(Starttls::from(value))
+            }
+        }
+
+        deserializer.deserialize_any(StartlsVisitor)
+    }
+}
+
+/// Rate limiting configuration.
+#[derive(Debug, serde::Deserialize, Clone)]
+pub struct RateLimitSettings {
+    /// Whether rate limiting is enabled
+    #[serde(default = "default_rate_limit_enabled")]
+    pub enabled: bool,
+    /// Maximum number of requests allowed in the time window (burst size)
+    #[serde(default = "default_burst_size")]
+    pub burst_size: u32,
+    /// Time window in seconds for rate limiting
+    #[serde(default = "default_per_seconds")]
+    pub per_seconds: u64,
+}
+
+impl Default for RateLimitSettings {
+    fn default() -> Self {
+        Self {
+            enabled: default_rate_limit_enabled(),
+            burst_size: default_burst_size(),
+            per_seconds: default_per_seconds(),
+        }
+    }
+}
+
+const fn default_rate_limit_enabled() -> bool {
+    true
+}
+
+const fn default_burst_size() -> u32 {
+    100
+}
+
+const fn default_per_seconds() -> u64 {
+    60
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn environment_display_development() {
+        let env = Environment::Development;
+        assert_eq!(env.to_string(), "development");
+    }
+
+    #[test]
+    fn environment_display_production() {
+        let env = Environment::Production;
+        assert_eq!(env.to_string(), "production");
+    }
+
+    #[test]
+    fn environment_from_str_development() {
+        assert_eq!(
+            Environment::try_from("development").unwrap(),
+            Environment::Development
+        );
+        assert_eq!(
+            Environment::try_from("dev").unwrap(),
+            Environment::Development
+        );
+        assert_eq!(
+            Environment::try_from("Development").unwrap(),
+            Environment::Development
+        );
+        assert_eq!(
+            Environment::try_from("DEV").unwrap(),
+            Environment::Development
+        );
+    }
+
+    #[test]
+    fn environment_from_str_production() {
+        assert_eq!(
+            Environment::try_from("production").unwrap(),
+            Environment::Production
+        );
+        assert_eq!(
+            Environment::try_from("prod").unwrap(),
+            Environment::Production
+        );
+        assert_eq!(
+            Environment::try_from("Production").unwrap(),
+            Environment::Production
+        );
+        assert_eq!(
+            Environment::try_from("PROD").unwrap(),
+            Environment::Production
+        );
+    }
+
+    #[test]
+    fn environment_from_str_invalid() {
+        let result = Environment::try_from("invalid");
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("not a supported environment"));
+    }
+
+    #[test]
+    fn environment_from_string_development() {
+        assert_eq!(
+            Environment::try_from("development".to_string()).unwrap(),
+            Environment::Development
+        );
+    }
+
+    #[test]
+    fn environment_from_string_production() {
+        assert_eq!(
+            Environment::try_from("production".to_string()).unwrap(),
+            Environment::Production
+        );
+    }
+
+    #[test]
+    fn environment_from_string_invalid() {
+        let result = Environment::try_from("invalid".to_string());
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn environment_default_is_development() {
+        let env = Environment::default();
+        assert_eq!(env, Environment::Development);
+    }
+
+    #[test]
+    fn startls_deserialize_from_string_never() {
+        let json = r#""never""#;
+        let result: Starttls = serde_json::from_str(json).unwrap();
+        assert_eq!(result, Starttls::Never);
+
+        let json = r#""no""#;
+        let result: Starttls = serde_json::from_str(json).unwrap();
+        assert_eq!(result, Starttls::Never);
+
+        let json = r#""off""#;
+        let result: Starttls = serde_json::from_str(json).unwrap();
+        assert_eq!(result, Starttls::Never);
+    }
+
+    #[test]
+    fn startls_deserialize_from_string_always() {
+        let json = r#""always""#;
+        let result: Starttls = serde_json::from_str(json).unwrap();
+        assert_eq!(result, Starttls::Always);
+
+        let json = r#""yes""#;
+        let result: Starttls = serde_json::from_str(json).unwrap();
+        assert_eq!(result, Starttls::Always);
+    }
+
+    #[test]
+    fn startls_deserialize_from_string_opportunistic() {
+        let json = r#""opportunistic""#;
+        let result: Starttls = serde_json::from_str(json).unwrap();
+        assert_eq!(result, Starttls::Opportunistic);
+    }
+
+    #[test]
+    fn startls_deserialize_from_bool() {
+        let json = "true";
+        let result: Starttls = serde_json::from_str(json).unwrap();
+        assert_eq!(result, Starttls::Always);
+
+        let json = "false";
+        let result: Starttls = serde_json::from_str(json).unwrap();
+        assert_eq!(result, Starttls::Never);
+    }
+
+    #[test]
+    fn startls_deserialize_from_string_invalid() {
+        let json = r#""invalid""#;
+        let result: Result<Starttls, _> = serde_json::from_str(json);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn startls_default_is_never() {
+        let startls = Starttls::default();
+        assert_eq!(startls, Starttls::Never);
+    }
+
+    #[test]
+    fn startls_try_from_str_never() {
+        assert_eq!(Starttls::try_from("never").unwrap(), Starttls::Never);
+        assert_eq!(Starttls::try_from("no").unwrap(), Starttls::Never);
+        assert_eq!(Starttls::try_from("off").unwrap(), Starttls::Never);
+        assert_eq!(Starttls::try_from("NEVER").unwrap(), Starttls::Never);
+        assert_eq!(Starttls::try_from("No").unwrap(), Starttls::Never);
+    }
+
+    #[test]
+    fn startls_try_from_str_always() {
+        assert_eq!(Starttls::try_from("always").unwrap(), Starttls::Always);
+        assert_eq!(Starttls::try_from("yes").unwrap(), Starttls::Always);
+        assert_eq!(Starttls::try_from("ALWAYS").unwrap(), Starttls::Always);
+        assert_eq!(Starttls::try_from("Yes").unwrap(), Starttls::Always);
+    }
+
+    #[test]
+    fn startls_try_from_str_opportunistic() {
+        assert_eq!(
+            Starttls::try_from("opportunistic").unwrap(),
+            Starttls::Opportunistic
+        );
+        assert_eq!(
+            Starttls::try_from("OPPORTUNISTIC").unwrap(),
+            Starttls::Opportunistic
+        );
+    }
+
+    #[test]
+    fn startls_try_from_str_invalid() {
+        let result = Starttls::try_from("invalid");
+        assert!(result.is_err());
+        assert!(result
+            .unwrap_err()
+            .contains("not a supported option"));
+    }
+
+    #[test]
+    fn startls_try_from_string_never() {
+        assert_eq!(
+            Starttls::try_from("never".to_string()).unwrap(),
+            Starttls::Never
+        );
+    }
+
+    #[test]
+    fn startls_try_from_string_always() {
+        assert_eq!(
+            Starttls::try_from("yes".to_string()).unwrap(),
+            Starttls::Always
+        );
+    }
+
+    #[test]
+    fn startls_try_from_string_opportunistic() {
+        assert_eq!(
+            Starttls::try_from("opportunistic".to_string()).unwrap(),
+            Starttls::Opportunistic
+        );
+    }
+
+    #[test]
+    fn startls_try_from_string_invalid() {
+        let result = Starttls::try_from("invalid".to_string());
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn startls_from_bool_true() {
+        assert_eq!(Starttls::from(true), Starttls::Always);
+    }
+
+    #[test]
+    fn startls_from_bool_false() {
+        assert_eq!(Starttls::from(false), Starttls::Never);
+    }
+
+    #[test]
+    fn startls_display_never() {
+        let startls = Starttls::Never;
+        assert_eq!(startls.to_string(), "never");
+    }
+
+    #[test]
+    fn startls_display_always() {
+        let startls = Starttls::Always;
+        assert_eq!(startls.to_string(), "always");
+    }
+
+    #[test]
+    fn startls_display_opportunistic() {
+        let startls = Starttls::Opportunistic;
+        assert_eq!(startls.to_string(), "opportunistic");
+    }
+
+    #[test]
+    fn rate_limit_settings_default() {
+        let settings = RateLimitSettings::default();
+        assert!(settings.enabled);
+        assert_eq!(settings.burst_size, 100);
+        assert_eq!(settings.per_seconds, 60);
+    }
+
+    #[test]
+    fn rate_limit_settings_deserialize_full() {
+        let json = r#"{"enabled": true, "burst_size": 50, "per_seconds": 30}"#;
+        let settings: RateLimitSettings = serde_json::from_str(json).unwrap();
+        assert!(settings.enabled);
+        assert_eq!(settings.burst_size, 50);
+        assert_eq!(settings.per_seconds, 30);
+    }
+
+    #[test]
+    fn rate_limit_settings_deserialize_partial() {
+        let json = r#"{"enabled": false}"#;
+        let settings: RateLimitSettings = serde_json::from_str(json).unwrap();
+        assert!(!settings.enabled);
+        assert_eq!(settings.burst_size, 100); // default
+        assert_eq!(settings.per_seconds, 60); // default
+    }
+
+    #[test]
+    fn rate_limit_settings_deserialize_empty() {
+        let json = "{}";
+        let settings: RateLimitSettings = serde_json::from_str(json).unwrap();
+        assert!(settings.enabled); // default
+        assert_eq!(settings.burst_size, 100); // default
+        assert_eq!(settings.per_seconds, 60); // default
+    }
+
+    #[test]
+    fn startls_deserialize_from_incompatible_type() {
+        // Test that deserialization from an array fails with expected error message
+        let json = "[1, 2, 3]";
+        let result: Result<Starttls, _> = serde_json::from_str(json);
+        assert!(result.is_err());
+        let error = result.unwrap_err().to_string();
+        // The error should mention what was expected
+        assert!(
+            error.contains("STARTTLS") || error.contains("string") || error.contains("boolean")
+        );
+    }
+
+    #[test]
+    fn startls_deserialize_from_number() {
+        // Test that deserialization from a number fails
+        let json = "42";
+        let result: Result<Starttls, _> = serde_json::from_str(json);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn startls_deserialize_from_object() {
+        // Test that deserialization from an object fails
+        let json = r#"{"foo": "bar"}"#;
+        let result: Result<Starttls, _> = serde_json::from_str(json);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn email_settings_debug_redacts_password() {
+        let settings = EmailSettings {
+            host: "smtp.example.com".to_string(),
+            port: 587,
+            user: "user@example.com".to_string(),
+            from: "noreply@example.com".to_string(),
+            password: "super_secret_password".to_string(),
+            recipient: "admin@example.com".to_string(),
+            starttls: Starttls::Always,
+            tls: false,
+        };
+
+        let debug_output = format!("{settings:?}");
+
+        // Password should be redacted
+        assert!(debug_output.contains("[REDACTED]"));
+        // Password should not appear in output
+        assert!(!debug_output.contains("super_secret_password"));
+        // Other fields should still be present
+        assert!(debug_output.contains("smtp.example.com"));
+        assert!(debug_output.contains("user@example.com"));
+    }
+}

src/startup.rs

@@ -0,0 +1,228 @@
+//! Application startup and server configuration.
+//!
+//! This module handles:
+//! - Building the application with routes and middleware
+//! - Setting up the OpenAPI service and Swagger UI
+//! - Configuring CORS
+//! - Starting the HTTP server
+
+use poem::middleware::{AddDataEndpoint, Cors, CorsEndpoint};
+use poem::{EndpointExt, Route};
+use poem_openapi::OpenApiService;
+
+use crate::{
+    middleware::rate_limit::{RateLimit, RateLimitConfig},
+    route::Api,
+    settings::Settings,
+};
+
+use crate::middleware::rate_limit::RateLimitEndpoint;
+
+type Server = poem::Server<poem::listener::TcpListener<String>, std::convert::Infallible>;
+/// The configured application with rate limiting, CORS, and settings data.
+pub type App = AddDataEndpoint<CorsEndpoint<RateLimitEndpoint<Route>>, Settings>;
+
+/// Application builder that holds the server configuration before running.
+pub struct Application {
+    server: Server,
+    app: poem::Route,
+    host: String,
+    port: u16,
+    settings: Settings,
+}
+
+/// A fully configured application ready to run.
+pub struct RunnableApplication {
+    server: Server,
+    app: App,
+}
+
+impl RunnableApplication {
+    /// Runs the application server.
+    ///
+    /// # Errors
+    ///
+    /// Returns a `std::io::Error` if the server fails to start or encounters
+    /// an I/O error during runtime (e.g., port already in use, network issues).
+    pub async fn run(self) -> Result<(), std::io::Error> {
+        self.server.run(self.app).await
+    }
+}
+
+impl From<RunnableApplication> for App {
+    fn from(value: RunnableApplication) -> Self {
+        value.app
+    }
+}
+
+impl From<Application> for RunnableApplication {
+    fn from(value: Application) -> Self {
+        // Configure rate limiting based on settings
+        let rate_limit_config = if value.settings.rate_limit.enabled {
+            tracing::event!(
+                target: "backend::startup",
+                tracing::Level::INFO,
+                burst_size = value.settings.rate_limit.burst_size,
+                per_seconds = value.settings.rate_limit.per_seconds,
+                "Rate limiting enabled"
+            );
+            RateLimitConfig::new(
+                value.settings.rate_limit.burst_size,
+                value.settings.rate_limit.per_seconds,
+            )
+        } else {
+            tracing::event!(
+                target: "backend::startup",
+                tracing::Level::INFO,
+                "Rate limiting disabled (using very high limits)"
+            );
+            // Use very high limits to effectively disable rate limiting
+            RateLimitConfig::new(u32::MAX, 1)
+        };
+
+        let app = value
+            .app
+            .with(RateLimit::new(&rate_limit_config))
+            .with(Cors::new())
+            .data(value.settings);
+
+        let server = value.server;
+        Self { server, app }
+    }
+}
+
+impl Application {
+    fn setup_app(settings: &Settings) -> poem::Route {
+        let api_service = OpenApiService::new(
+            Api::from(settings).apis(),
+            settings.application.clone().name,
+            settings.application.clone().version,
+        )
+        .url_prefix("/api");
+        let ui = api_service.swagger_ui();
+        poem::Route::new()
+            .nest("/api", api_service.clone())
+            .nest("/specs", api_service.spec_endpoint_yaml())
+            .nest("/", ui)
+    }
+
+    fn setup_server(
+        settings: &Settings,
+        tcp_listener: Option<poem::listener::TcpListener<String>>,
+    ) -> Server {
+        let tcp_listener = tcp_listener.unwrap_or_else(|| {
+            let address = format!(
+                "{}:{}",
+                settings.application.host, settings.application.port
+            );
+            poem::listener::TcpListener::bind(address)
+        });
+        poem::Server::new(tcp_listener)
+    }
+
+    /// Builds a new application with the given settings and optional TCP listener.
+    ///
+    /// If no listener is provided, one will be created based on the settings.
+    #[must_use]
+    pub fn build(
+        settings: Settings,
+        tcp_listener: Option<poem::listener::TcpListener<String>>,
+    ) -> Self {
+        let port = settings.application.port;
+        let host = settings.application.clone().host;
+        let app = Self::setup_app(&settings);
+        let server = Self::setup_server(&settings, tcp_listener);
+        Self {
+            server,
+            app,
+            host,
+            port,
+            settings,
+        }
+    }
+
+    /// Converts the application into a runnable application.
+    #[must_use]
+    pub fn make_app(self) -> RunnableApplication {
+        self.into()
+    }
+
+    /// Returns the host address the application is configured to bind to.
+    #[must_use]
+    pub fn host(&self) -> String {
+        self.host.clone()
+    }
+
+    /// Returns the port the application is configured to bind to.
+    #[must_use]
+    pub const fn port(&self) -> u16 {
+        self.port
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn create_test_settings() -> Settings {
+        Settings {
+            application: crate::settings::ApplicationSettings {
+                name: "test-app".to_string(),
+                version: "1.0.0".to_string(),
+                port: 8080,
+                host: "127.0.0.1".to_string(),
+                base_url: "http://localhost:8080".to_string(),
+                protocol: "http".to_string(),
+            },
+            debug: false,
+            email: crate::settings::EmailSettings::default(),
+            frontend_url: "http://localhost:3000".to_string(),
+            rate_limit: crate::settings::RateLimitSettings {
+                enabled: false,
+                burst_size: 100,
+                per_seconds: 60,
+            },
+        }
+    }
+
+    #[test]
+    fn application_build_and_host() {
+        let settings = create_test_settings();
+        let app = Application::build(settings.clone(), None);
+        assert_eq!(app.host(), settings.application.host);
+    }
+
+    #[test]
+    fn application_build_and_port() {
+        let settings = create_test_settings();
+        let app = Application::build(settings, None);
+        assert_eq!(app.port(), 8080);
+    }
+
+    #[test]
+    fn application_host_returns_correct_value() {
+        let settings = create_test_settings();
+        let app = Application::build(settings, None);
+        assert_eq!(app.host(), "127.0.0.1");
+    }
+
+    #[test]
+    fn application_port_returns_correct_value() {
+        let settings = create_test_settings();
+        let app = Application::build(settings, None);
+        assert_eq!(app.port(), 8080);
+    }
+
+    #[test]
+    fn application_with_custom_listener() {
+        let settings = create_test_settings();
+        let tcp_listener =
+            std::net::TcpListener::bind("127.0.0.1:0").expect("Failed to bind random port");
+        let port = tcp_listener.local_addr().unwrap().port();
+        let listener = poem::listener::TcpListener::bind(format!("127.0.0.1:{port}"));
+
+        let app = Application::build(settings, Some(listener));
+        assert_eq!(app.host(), "127.0.0.1");
+        assert_eq!(app.port(), 8080);
+    }
+}

src/telemetry.rs

@@ -0,0 +1,69 @@
+//! Logging and tracing configuration.
+//!
+//! This module provides utilities for setting up structured logging using the tracing crate.
+//! Supports both pretty-printed logs for development and JSON logs for production.
+
+use tracing_subscriber::layer::SubscriberExt;
+
+/// Creates a tracing subscriber configured for the given debug mode.
+///
+/// In debug mode, logs are pretty-printed to stdout.
+/// In production mode, logs are output as JSON.
+#[must_use]
+pub fn get_subscriber(debug: bool) -> impl tracing::Subscriber + Send + Sync {
+    let env_filter = if debug { "debug" } else { "info" }.to_string();
+    let env_filter = tracing_subscriber::EnvFilter::try_from_default_env()
+        .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new(env_filter));
+    let stdout_log = tracing_subscriber::fmt::layer().pretty();
+    let subscriber = tracing_subscriber::Registry::default()
+        .with(env_filter)
+        .with(stdout_log);
+    let json_log = if debug {
+        None
+    } else {
+        Some(tracing_subscriber::fmt::layer().json())
+    };
+    subscriber.with(json_log)
+}
+
+/// Initializes the global tracing subscriber.
+///
+/// # Panics
+///
+/// Panics if:
+/// - A global subscriber has already been set
+/// - The subscriber cannot be set as the global default
+pub fn init_subscriber(subscriber: impl tracing::Subscriber + Send + Sync) {
+    tracing::subscriber::set_global_default(subscriber).expect("Failed to set subscriber");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn get_subscriber_debug_mode() {
+        let subscriber = get_subscriber(true);
+        // If we can create the subscriber without panicking, the test passes
+        // We can't easily inspect the subscriber's internals, but we can verify it's created
+        let _ = subscriber;
+    }
+
+    #[test]
+    fn get_subscriber_production_mode() {
+        let subscriber = get_subscriber(false);
+        // If we can create the subscriber without panicking, the test passes
+        let _ = subscriber;
+    }
+
+    #[test]
+    fn get_subscriber_creates_valid_subscriber() {
+        // Test both debug and non-debug modes create valid subscribers
+        let debug_subscriber = get_subscriber(true);
+        let prod_subscriber = get_subscriber(false);
+
+        // Basic smoke test - if these are created without panicking, they're valid
+        let _ = debug_subscriber;
+        let _ = prod_subscriber;
+    }
+}