phundrak/phundrak.com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Activity

feat: relay contact requests to SMTP server

Browse Source
This commit is contained in:
Lucien Cartier-Tilet 2025-11-04 16:27:54 +01:00
parent 1abbbdbf79
commit 8d55feca50
14 changed files with 1091 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
backend/Cargo.lock generated
View File

@ -1526,6 +1526,7 @@ dependencies = [
"tokio",
"tracing",
"tracing-subscriber",
"validator",
]
[[package]]
@ -1729,6 +1730,28 @@ dependencies = [
"toml_edit",
]
[[package]]
name = "proc-macro-error-attr2"
version = "2.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "96de42df36bb9bba5542fe9f1a054b8cc87e172759a1868aa05c1f3acc89dfc5"
dependencies = [
"proc-macro2",
"quote",
]
[[package]]
name = "proc-macro-error2"
version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "11ec05c52be0a07b08061f7dd003e7d7092e0472bc731b4af7bb1ef876109802"
dependencies = [
"proc-macro-error-attr2",
"proc-macro2",
"quote",
"syn 2.0.108",
]
[[package]]
name = "proc-macro2"
version = "1.0.103"
@ -2569,6 +2592,36 @@ version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
[[package]]
name = "validator"
version = "0.20.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "43fb22e1a008ece370ce08a3e9e4447a910e92621bb49b85d6e48a45397e7cfa"
dependencies = [
"idna",
"once_cell",
"regex",
"serde",
"serde_derive",
"serde_json",
"url",
"validator_derive",
]
[[package]]
name = "validator_derive"
version = "0.20.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b7df16e474ef958526d1205f6dda359fdfab79d9aa6d54bafcb92dcd07673dca"
dependencies = [
"darling",
"once_cell",
"proc-macro-error2",
"proc-macro2",
"quote",
"syn 2.0.108",
]
[[package]]
name = "valuable"
version = "0.1.1"

1
backend/Cargo.toml
View File

@ -26,6 +26,7 @@ thiserror = "2.0.17"
tokio = { version = "1.48.0", features = ["macros", "rt-multi-thread"] }
tracing = "0.1.41"
tracing-subscriber = { version = "0.3.20", features = ["fmt", "std", "env-filter", "registry", "json", "tracing-log"] }
validator = { version = "0.20.0", features = ["derive"] }
[lints.rust]
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(tarpaulin_include)'] }

151
backend/README.md
View File

@ -4,12 +4,54 @@ The backend for [phundrak.com](https://phundrak.com), built with Rust and the [P
## Features
- **RESTful API** with OpenAPI documentation
- **RESTful API** with automatic OpenAPI/Swagger documentation
- **Contact form** with SMTP email relay (supports TLS, STARTTLS, and unencrypted)
- **Type-safe routing** using Poem's declarative API
- **Structured logging** with `tracing`
- **Hierarchical configuration** with YAML files and environment variable overrides
- **Structured logging** with `tracing` and `tracing-subscriber`
- **Strict linting** for code quality and safety
- **Comprehensive testing** with integration test support
## API Endpoints
The application provides the following endpoints:
- **Swagger UI**: `/` - Interactive API documentation
- **OpenAPI Spec**: `/specs` - OpenAPI specification in YAML format
- **Health Check**: `GET /api/health` - Returns server health status
- **Application Metadata**: `GET /api/meta` - Returns version and build info
- **Contact Form**: `POST /api/contact` - Submit contact form (relays to SMTP)
## Configuration
Configuration is loaded from multiple sources in order of precedence:
1. `settings/base.yaml` - Base configuration
2. `settings/{environment}.yaml` - Environment-specific (development/production)
3. Environment variables prefixed with `APP__` (e.g., `APP__APPLICATION__PORT=8080`)
The environment is determined by the `APP_ENVIRONMENT` variable (defaults to "development").
### Configuration Example
```yaml
application:
port: 3100
version: "0.1.0"
email:
host: smtp.example.com
port: 587
user: user@example.com
from: Contact Form <noreply@example.com>
password: your_password
recipient: Admin <admin@example.com>
starttls: true # Use STARTTLS (typically port 587)
tls: false # Use implicit TLS (typically port 465)
```
You can also use a `.env` file for local development settings.
## Development
### Prerequisites
@ -25,7 +67,7 @@ To start the development server:
cargo run
```
The server will start on the configured port (check your configuration for details).
The server will start on the configured port (default: 3100).
### Building
@ -49,6 +91,8 @@ Run all tests:
```bash
cargo test
# or
just test
```
Run a specific test:
@ -63,31 +107,53 @@ Run tests with output:
cargo test -- --nocapture
```
Run tests with coverage:
```bash
cargo tarpaulin --config .tarpaulin.local.toml
# or
just coverage
```
### Testing Notes
- Integration tests use random TCP ports to avoid conflicts
- Tests use `get_test_app()` helper for consistent test setup
- Telemetry is automatically disabled during tests
- Tests are organized in `#[cfg(test)]` modules within each file
## Code Quality
### Linting
This project uses strict Clippy linting rules:
This project uses extremely strict Clippy linting rules:
- `#![deny(clippy::all)]`
- `#![deny(clippy::pedantic)]`
- `#![deny(clippy::nursery)]`
- `#![warn(missing_docs)]`
Run Clippy to check for issues:
```bash
cargo clippy --all-targets
# or
just lint
```
All code must pass these checks before committing.
### Continuous Checking with Bacon
For continuous testing and linting during development, use [bacon](https://dystroy.org/bacon/):
```bash
bacon
bacon # Runs clippy-all by default
bacon test # Runs tests continuously
bacon clippy # Runs clippy on default target only
```
This will watch your files and automatically run clippy or tests on changes.
Press 'c' in bacon to run clippy-all.
## Code Style
@ -99,29 +165,29 @@ This will watch your files and automatically run clippy or tests on changes.
### Logging
- Use `tracing::event!` for logging
- Always set `target: "backend"`
- Use appropriate log levels (trace, debug, info, warn, error)
Always use `tracing::event!` with proper target and level:
Example:
```rust
tracing::event!(target: "backend", tracing::Level::INFO, "Server started");
tracing::event!(
target: "backend", // or "backend::module_name"
tracing::Level::INFO,
"Message here"
);
```
### Imports
Organize imports in three groups:
1. Standard library (`std::*`)
2. External crates
3. Local modules
2. External crates (poem, serde, etc.)
3. Local modules (`crate::*`)
Use explicit paths (e.g., `poem_openapi::ApiResponse` instead of wildcards).
### Testing Conventions
### Testing
- Use `#[cfg(test)]` module blocks
- Leverage Poem's test utilities for endpoint testing
- Use random TCP listeners for integration tests to avoid port conflicts
- Use `#[tokio::test]` for async tests
- Use descriptive test names that explain what is being tested
- Test both success and error cases
- For endpoint tests, verify both status codes and response bodies
## Project Structure
@ -129,15 +195,50 @@ Use explicit paths (e.g., `poem_openapi::ApiResponse` instead of wildcards).
backend/
├── src/
│ ├── main.rs # Application entry point
│ ├── api/ # API endpoints
│ ├── models/ # Data models
│ ├── services/ # Business logic
│ └── utils/ # Utility functions
├── tests/ # Integration tests
│ ├── lib.rs # Library root with run() and prepare()
│ ├── startup.rs # Application builder, server setup
│ ├── settings.rs # Configuration management
│ ├── telemetry.rs # Logging and tracing setup
│ └── route/ # API route handlers
│ ├── mod.rs # Route organization
│ ├── contact.rs # Contact form endpoint
│ ├── health.rs # Health check endpoint
│ └── meta.rs # Metadata endpoint
├── settings/ # Configuration files
│ ├── base.yaml # Base configuration
│ ├── development.yaml # Development overrides
│ └── production.yaml # Production overrides
├── Cargo.toml # Dependencies and metadata
└── README.md # This file
```
## Architecture
### Application Initialization Flow
1. `main.rs` calls `run()` from `lib.rs`
2. `run()` calls `prepare()` which:
- Loads environment variables from `.env` file
- Initializes `Settings` from YAML files and environment variables
- Sets up telemetry/logging (unless in test mode)
- Builds the `Application` with optional TCP listener
3. `Application::build()`:
- Sets up OpenAPI service with all API endpoints
- Configures Swagger UI at the root path (`/`)
- Configures API routes under `/api` prefix
- Creates server with TCP listener
4. Application runs with CORS middleware and settings injected as data
### Email Handling
The contact form supports multiple SMTP configurations:
- **Implicit TLS (SMTPS)** - typically port 465
- **STARTTLS (Always/Opportunistic)** - typically port 587
- **Unencrypted** (for local dev) - with or without authentication
The `SmtpTransport` is built dynamically from `EmailSettings` based on
TLS/STARTTLS configuration.
## License
See the root repository for license information.
AGPL-3.0-only - See the root repository for full license information.

6
backend/settings/base.yaml
View File

@ -3,7 +3,11 @@ application:
version: "0.1.0"
email:
host: localhost
host: email.example.com
port: 587
user: user
from: Contact Form <noreply@example.com>
password: hunter2
recipient: Admin <user@example.com>
starttls: false
tls: false

10
backend/settings/development.yaml
View File

@ -5,4 +5,12 @@ application:
protocol: http
host: 127.0.0.1
base_url: http://127.0.0.1:3100
name: "com.phundrak.backend.prod"
name: "com.phundrak.backend.dev"
email:
host: localhost
port: 1025
user: ""
password: ""
tls: false
starttls: false

22
backend/src/lib.rs
View File

@ -1,13 +1,23 @@
//! 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)]
#![allow(clippy::missing_panics_doc)]
#![allow(clippy::missing_errors_doc)]
#![warn(missing_docs)]
#![allow(clippy::unused_async)]
/// 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>>;
@ -36,13 +46,19 @@ fn prepare(listener: MaybeListener) -> startup::Application {
tracing::event!(
target: "backend",
tracing::Level::INFO,
"Documentation available at http://{}:{}/docs",
"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);

2
backend/src/main.rs
View File

@ -1,3 +1,5 @@
//! Backend server entry point.
#[cfg(not(tarpaulin_include))]
#[tokio::main]
async fn main() -> Result<(), std::io::Error> {

513
backend/src/route/contact.rs Normal file
View File

@ -0,0 +1,513 @@
//! 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)]
TooManyRequests(Json<ContactResponse>),
/// 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"));
}
}

12
backend/src/route/health.rs
View File

@ -1,3 +1,5 @@
//! Health check endpoint for monitoring service availability.
use poem_openapi::{ApiResponse, OpenApi};
use super::ApiCategory;
@ -8,13 +10,15 @@ enum HealthResponse {
Ok,
}
/// Health check API for monitoring service availability.
#[derive(Default, Clone)]
pub struct HealthApi;
#[OpenApi(prefix_path = "/v1/health-check", tag = "ApiCategory::Health")]
#[OpenApi(tag = "ApiCategory::Health")]
impl HealthApi {
#[oai(path = "/", method = "get")]
#[oai(path = "/health", method = "get")]
async fn ping(&self) -> HealthResponse {
tracing::event!(target: "backend", tracing::Level::DEBUG, "Accessing health-check endpoint");
tracing::event!(target: "backend::health", tracing::Level::DEBUG, "Accessing health-check endpoint");
HealthResponse::Ok
}
}
@ -23,7 +27,7 @@ impl HealthApi {
async fn health_check_works() {
let app = crate::get_test_app();
let cli = poem::test::TestClient::new(app);
let resp = cli.get("/v1/health-check").send().await;
let resp = cli.get("/api/health").send().await;
resp.assert_status_is_ok();
resp.assert_text("").await;
}

79
backend/src/route/meta.rs
View File

@ -1,8 +1,10 @@
//! 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::Settings;
use crate::settings::ApplicationSettings;
#[derive(Object, Debug, Clone, serde::Serialize, serde::Deserialize)]
struct Meta {
@ -10,10 +12,10 @@ struct Meta {
name: String,
}
impl From<poem::web::Data<&Settings>> for Meta {
fn from(value: poem::web::Data<&Settings>) -> Self {
let version = value.application.version.clone();
let name = value.application.name.clone();
impl From<&MetaApi> for Meta {
fn from(value: &MetaApi) -> Self {
let version = value.version.clone();
let name = value.name.clone();
Self { version, name }
}
}
@ -24,63 +26,56 @@ enum MetaResponse {
Meta(Json<Meta>),
}
pub struct MetaApi;
/// API for retrieving application metadata (name and version).
#[derive(Clone)]
pub struct MetaApi {
name: String,
version: String,
}
#[OpenApi(prefix_path = "/v1/meta", tag = "ApiCategory::Meta")]
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 = "/", method = "get")]
async fn meta(&self, settings: poem::web::Data<&Settings>) -> Result<MetaResponse> {
tracing::event!(target: "backend", tracing::Level::DEBUG, "Accessing meta endpoint");
Ok(MetaResponse::Meta(Json(settings.into())))
#[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 {
use super::*;
use crate::settings::ApplicationSettings;
#[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("/v1/meta").send().await;
let resp = cli.get("/api/meta").send().await;
resp.assert_status_is_ok();
// let json = resp.0.into_json().await;
// assert!(json.is_ok(), "Response should be valid JSON");
// let json_value: serde_json::Value = json.unwrap();
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");
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("/v1/meta").send().await;
let resp = cli.get("/api/meta").send().await;
resp.assert_status_is_ok();
}
#[test]
fn meta_from_settings_conversion() {
let settings = Settings {
application: 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(),
};
let meta: Meta = poem::web::Data(&settings).into();
assert_eq!(meta.name, "test-app");
assert_eq!(meta.version, "1.0.0");
}
}

44
backend/src/route/mod.rs
View File

@ -1,18 +1,46 @@
use poem_openapi::{OpenApi, Tags};
//! 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;
pub use health::HealthApi;
mod meta;
pub use meta::MetaApi;
use crate::settings::Settings;
#[derive(Tags)]
enum ApiCategory {
Contact,
Health,
Meta
Meta,
}
pub(crate) struct Api;
pub(crate) struct Api {
contact: contact::ContactApi,
health: health::HealthApi,
meta: meta::MetaApi,
}
#[OpenApi]
impl Api {}
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)
}
}

242
backend/src/settings.rs
View File

@ -1,12 +1,41 @@
//! 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,
}
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");
@ -31,20 +60,30 @@ impl Settings {
}
}
/// 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,
}
@ -80,12 +119,116 @@ impl TryFrom<&str> for Environment {
}
}
/// Email server configuration for the contact form.
#[derive(Debug, 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,
pub password: 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,
}
/// 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)
}
}
#[cfg(test)]
@ -106,18 +249,42 @@ mod tests {
#[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);
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);
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]
@ -154,4 +321,61 @@ mod tests {
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);
}
}

39
backend/src/startup.rs
View File

@ -1,12 +1,22 @@
//! 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::{settings::Settings, route::{Api, HealthApi, MetaApi}};
use crate::{route::Api, settings::Settings};
type Server = poem::Server<poem::listener::TcpListener<String>, std::convert::Infallible>;
/// The configured application with CORS and settings data.
pub type App = AddDataEndpoint<CorsEndpoint<Route>, Settings>;
/// Application builder that holds the server configuration before running.
pub struct Application {
server: Server,
app: poem::Route,
@ -15,12 +25,19 @@ pub struct Application {
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
}
@ -43,12 +60,16 @@ impl From<Application> for RunnableApplication {
impl Application {
fn setup_app(settings: &Settings) -> poem::Route {
let api_service = OpenApiService::new(
(Api, HealthApi, MetaApi),
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_service).nest("/docs", ui)
poem::Route::new()
.nest("/api", api_service.clone())
.nest("/specs", api_service.spec_endpoint_yaml())
.nest("/", ui)
}
fn setup_server(
@ -65,6 +86,9 @@ impl Application {
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,
@ -83,16 +107,19 @@ impl Application {
}
}
/// 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
@ -150,8 +177,8 @@ mod tests {
#[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 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}"));

16
backend/src/telemetry.rs
View File

@ -1,5 +1,14 @@
//! 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();
@ -17,6 +26,13 @@ pub fn get_subscriber(debug: bool) -> impl tracing::Subscriber + Send + Sync {
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");
}