phundrak.com/backend

phundrak.com Backend

The backend for phundrak.com, built with Rust and the Poem web framework.

Features

• RESTful API with OpenAPI documentation
• Type-safe routing using Poem's declarative API
• Structured logging with tracing
• Strict linting for code quality and safety
• Comprehensive testing with integration test support

Development

Prerequisites

• Rust (latest stable version recommended)
• Cargo (comes with Rust)

Running the Server

To start the development server:

cargo run

The server will start on the configured port (check your configuration for details).

Building

For development builds:

cargo build

For optimized production builds:

cargo build --release

The compiled binary will be at target/release/backend.

Testing

Run all tests:

cargo test

Run a specific test:

cargo test <test_name>

Run tests with output:

cargo test -- --nocapture

Code Quality

Linting

This project uses strict Clippy linting rules:

• #![deny(clippy::all)]
• #![deny(clippy::pedantic)]
• #![deny(clippy::nursery)]

Run Clippy to check for issues:

cargo clippy --all-targets

Continuous Checking with Bacon

For continuous testing and linting during development, use bacon:

bacon

This will watch your files and automatically run clippy or tests on changes.

Code Style

Error Handling

• Use thiserror for custom error types
• Always return Result types for fallible operations
• Use descriptive error messages

Logging

• Use tracing::event! for logging
• Always set target: "backend"
• Use appropriate log levels (trace, debug, info, warn, error)

Example:

tracing::event!(target: "backend", tracing::Level::INFO, "Server started");

Imports

Organize imports in three groups:

1. Standard library (std::*)
2. External crates
3. Local modules

Use explicit paths (e.g., poem_openapi::ApiResponse instead of wildcards).

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

Project Structure

backend/
├── src/
│   ├── main.rs          # Application entry point
│   ├── api/             # API endpoints
│   ├── models/          # Data models
│   ├── services/        # Business logic
│   └── utils/           # Utility functions
├── tests/               # Integration tests
├── Cargo.toml           # Dependencies and metadata
└── README.md            # This file

License

See the root repository for license information.