Structuring and Architecting Rust Projects: A Comprehensive Guide¶

Rust rewards a little up-front thought about structure more than most languages do. The compiler enforces ownership, visibility, and thread-safety at module and crate boundaries, so the shape of your project directly affects how easy it is to change. A well-structured Rust codebase feels effortless to extend; a badly structured one turns every feature into a fight with the borrow checker.

This guide covers the whole life of a Rust project: how to lay out the repository, how to architect the code inside it, the core coding concepts that make individual pieces idiomatic, and the files that build, ship, and run it (Makefile, Dockerfile, Compose, Helm, systemd, CI). It's opinionated; where there's a real trade-off, it says so and gives the reasoning so you can choose differently.

It's written for someone who can already write a working Rust program and wants their next one to be well organised, testable, and pleasant to maintain. It assumes you're comfortable with ownership and borrowing. If not, start with Understanding Ownership, Moves, and Borrowing.

Three project shapes come up repeatedly, and the guide shows a layout for each:

Contents¶

1. Guiding principles
2. Part 1: Project structure: crates and workspaces, modules, repository layouts, root files, Cargo.toml, toolchain config
3. Part 2: Application architecture: layering, traits as boundaries, ownership-driven design, config, errors, logging, async, CLIs, web services, persistence
4. Part 3: Core coding concepts: type-driven design, traits, iterators, strings, patterns, builders, concurrency, macros, unsafe, performance
5. Part 4: Quality and supply chain: testing, documentation, tooling, git hooks, security, dependencies, API stability
6. Part 5: Build, deploy, and release: versioning, release builds, Makefile, containers, Compose, Helm, systemd, CI, releases
7. Part 6: Anti-patterns
8. New-project checklist
9. Further reading

Guiding principles¶

1. One source of truth per fact. The version lives in Cargo.toml. The CI header lives in a shared template. Lint rules live in one [lints] table. Everything else reads from those rather than restating them.
2. Thin binary, fat library. main.rs parses args, sets up logging, calls into the library, and maps errors to an exit code. All logic lives in lib.rs and below, where it can be tested.
3. Convention over configuration. Use Cargo's standard locations (src/, tests/, benches/, examples/, build.rs). Every tool in the ecosystem already knows where to look.
4. Deployment files are part of the app. The Dockerfile, chart and units are versioned with the code that they deploy, so a tag describes both.
5. Same shape across projects. When every repo has the same Makefile targets, the same deploy/ layout and the same CI stages, you can move between projects without re-learning anything, and shared tooling (template repos, CI includes, sync tools) works across all of them.
6. Fail locally before you fail in CI. fmt, clippy and test should run in a pre-commit/pre-push hook with the same flags CI uses.

Part 1: Project structure¶

Vocabulary: packages, crates, modules, workspaces¶

Rust's terms overlap with other ecosystems in confusing ways, so pin them down first:

Crates are also the unit of parallel compilation and incremental rebuilds. That's one of the main practical reasons to split a large project into several crates.

Single crate or workspace?¶

Start with a single crate unless you have a concrete reason not to. A single crate with good module boundaries is simpler to build, version and release.

Move to a workspace when one or more of these is true:

• You have several independently meaningful units (subcommands that are each hundreds of lines, with their own dependencies).
• Compile times hurt: changing one module rebuilds everything. Crates are Cargo's unit of incremental and parallel compilation, so splitting heavy code into crates lets unchanged ones stay cached.
• You want to share code between multiple binaries (a CLI and a server, say) without either depending on the other.
• Some code should be reusable outside the project (a client library for your own API).
• You want hard dependency boundaries: a core crate that cannot accidentally depend on axum.

Signs you split too early: crates with one file each, constant cross-crate refactoring, or pub everything just to make it visible to a sibling.

A useful middle ground: a single package that contains both src/lib.rs and src/main.rs. You get the library/binary split (for testing) without workspace overhead.

Start with a library, keep main.rs thin¶

The single most useful structural habit: put almost all your logic in src/lib.rs (and its modules), and keep src/main.rs as a thin shell.

my-tool/
├── Cargo.toml
└── src/
    ├── main.rs      # parse args, set up logging, call into the library, map errors to exit codes
    ├── lib.rs       # the public API of your crate
    ├── config.rs
    └── backup.rs

// src/main.rs
use std::process::ExitCode;

fn main() -> ExitCode {
    match my_tool::run(std::env::args_os()) {
        Ok(()) => ExitCode::SUCCESS,
        Err(err) => {
            eprintln!("error: {err:#}");
            ExitCode::FAILURE
        }
    }
}

Why this matters:

• Integration tests in tests/ can only access a crate's library API. Logic in main.rs is untestable from there.
• Doc tests only run for library crates.
• Reuse is free: a second binary, a benchmark, or another crate in the workspace can call the same code.
• It forces you to define an actual API boundary instead of a 900-line main.

For an async service the shape is the same: main also initialises telemetry, and lib.rs becomes a table of contents with a top-level run that dispatches subcommands.

// src/main.rs — the whole file
use std::process::ExitCode;

#[tokio::main]
async fn main() -> ExitCode {
    let cli = <myservice::cli::Cli as clap::Parser>::parse();
    if let Err(e) = myservice::telemetry::init(&cli.log) {
        eprintln!("failed to init logging: {e:#}");
        return ExitCode::FAILURE;
    }
    match myservice::run(cli).await {
        Ok(()) => ExitCode::SUCCESS,
        Err(e) => {
            tracing::error!(error = ?e, "fatal");
            eprintln!("error: {e:#}");
            ExitCode::FAILURE
        }
    }
}

// src/lib.rs
pub mod cli;
pub mod config;
pub mod error;
pub mod telemetry;

mod db;
mod domain;
mod storage;
mod http;
mod services;
mod state;

pub use error::{Error, Result};

pub async fn run(cli: cli::Cli) -> anyhow::Result<()> {
    let cfg = config::Config::load(&cli)?;
    match cli.command {
        cli::Command::Serve => http::serve(cfg).await,
        cli::Command::Migrate => db::migrate(&cfg).await,
        cli::Command::Healthcheck => http::health::probe(&cfg).await,
    }
}

Modules and visibility¶

File layout¶

A module named config can live in either src/config.rs or src/config/mod.rs. Since the 2018 edition, the preferred style for modules with children is:

src/
├── lib.rs           # mod storage;
├── storage.rs       # mod sqlite; mod memory;
└── storage/
    ├── sqlite.rs
    └── memory.rs

This avoids editor tabs full of identical mod.rs names. Both styles work; pick one and be consistent.

Visibility levels¶

Default to private. Use pub(crate) liberally for internals that several modules share, and reserve pub for what you deliberately expose. In a binary-only crate, pub and pub(crate) are effectively the same, but writing pub(crate) documents intent and keeps the code library-ready.

Curate the public API with re-exports¶

Your internal module tree doesn't have to be your public API. Re-export the important items at the crate root so users write my_crate::Client instead of my_crate::net::http::client::Client:

// src/lib.rs
mod client;
mod config;
mod error;

pub use client::Client;
pub use config::Config;
pub use error::{Error, Result};

Keeping the modules themselves private (mod, not pub mod) means you can reorganise files later without breaking anyone.

Avoid a junk-drawer utils module¶

utils.rs, helpers.rs, and common.rs grow without bound because nothing obviously belongs elsewhere. Name modules after what they're about (paths, retry, time_fmt), not after the fact that they're small.

Organise by layer or by feature¶

By layer (http/, services/, storage/, domain/) works well for small-to-medium web apps — everyone knows where SQL lives.

By feature (jobs/{http,service,storage,domain}.rs, companies/...) scales better once you have many domains, because a change to one feature touches one directory.

A practical path: start by layer; when a layer directory gets past ~10 files, regroup by feature.

Whichever you choose, keep lib.rs as a table of contents: module declarations, a few re-exports, and the top-level run.

Repository layouts¶

The trees below show everything that typically lives in the repository, not just src/. The deployment directories are covered in Part 5.

Archetype A — CLI tool (single crate)¶

myapp/
├── .cargo/
│   └── config.toml          # project-level cargo aliases (optional)
├── .gitlab-ci.yml
├── .gitignore
├── .editorconfig
├── Cargo.toml
├── Cargo.lock               # committed
├── CHANGELOG.md
├── LICENSE
├── Makefile
├── README.md
├── clippy.toml              # optional
├── deny.toml
├── rust-toolchain.toml
├── rustfmt.toml
├── build.rs                 # optional: embeds git sha
├── deploy/
│   └── systemd/             # only if it runs as a service/timer
│       ├── myapp.service
│       └── myapp.timer
├── docs/
│   └── adr/                 # architecture decision records
├── examples/
│   └── config.example.toml
├── src/
│   ├── main.rs              # thin: parse, init logging, call lib, exit code
│   ├── lib.rs               # pub mod declarations + run()
│   ├── cli.rs               # clap structs
│   ├── config.rs
│   ├── error.rs
│   └── commands/
│       ├── mod.rs           # dispatch
│       ├── list.rs
│       └── sync.rs
└── tests/
    ├── cli.rs               # end-to-end: run the binary
    └── fixtures/

Archetype A, variant — a CLI with many subcommands¶

Give each subcommand its own module with a run function; the top-level cli.rs only dispatches:

src/
├── main.rs
├── lib.rs
├── cli.rs             # Cli { command: Command } + match dispatch
└── commands/
    ├── mod.rs  (or commands.rs)
    ├── backup.rs      # pub fn run(args: BackupArgs, ctx: &Context) -> Result<()>
    ├── restore.rs
    └── status.rs

When subcommands grow large or pull in heavy dependencies, promote each to its own crate in a workspace (next section).

Archetype B — Web service (axum + SQLite)¶

myservice/
├── .dockerignore
├── .gitlab-ci.yml
├── .sqlx/                   # sqlx offline query metadata (committed)
├── Cargo.toml
├── Cargo.lock
├── CHANGELOG.md
├── Dockerfile               # at repo root (CI templates detect it here)
├── Makefile
├── README.md
├── build.rs
├── deny.toml
├── rust-toolchain.toml
├── rustfmt.toml
├── deploy/
│   ├── compose/
│   │   ├── compose.yaml
│   │   └── .env.example
│   └── helm/
│       └── myservice/
│           ├── Chart.yaml
│           ├── values.yaml
│           └── templates/...
├── migrations/
│   ├── 20261001120000_init.sql
│   └── 20261008093000_add_tags.sql
├── static/                  # css/js/images, embedded or served
├── templates/               # askama/minijinja templates
├── src/
│   ├── main.rs              # thin: parse, init telemetry, call lib::run, exit code
│   ├── lib.rs
│   ├── cli.rs               # `serve`, `migrate`, `healthcheck`, `export`
│   ├── config.rs
│   ├── error.rs             # domain/service error types
│   ├── telemetry.rs
│   ├── state.rs             # AppState
│   ├── db.rs                # pool setup + migrations
│   ├── domain/              # pure types and rules; no axum, no sqlx
│   │   ├── job.rs
│   │   └── company.rs
│   ├── services/            # use cases that orchestrate domain + storage; no HTTP types
│   │   └── jobs.rs
│   ├── storage/             # repository trait implementations (SQL lives here)
│   │   └── jobs.rs
│   └── http/                # router, handlers, extractors, DTOs, AppError
│       ├── mod.rs
│       ├── error.rs
│       ├── jobs.rs
│       └── health.rs
└── tests/
    ├── common/
    │   └── mod.rs           # spawn app on random port, temp DB
    ├── health.rs
    └── jobs_api.rs

This is layer-first, which is easiest to navigate for small-to-medium services. As the service grows past a dozen or so features, flip to feature-first (jobs/{domain,storage,http}.rs) so that working on one feature touches one directory.

Archetype C — Multi-tool workspace¶

mytools/
├── Cargo.toml               # [workspace] only, no [package] (virtual manifest)
├── Cargo.lock
├── Makefile
├── README.md
├── CHANGELOG.md
├── deny.toml
├── rust-toolchain.toml
├── rustfmt.toml
├── .gitlab-ci.yml
├── crates/
│   ├── mytools/             # the ONE binary crate; clap + dispatch only
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   ├── mytools-core/        # shared: config, errors, output formatting, http client
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   ├── mytools-certs/       # one library crate per subcommand
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   ├── mytools-links/
│   └── mytools-ssl/
├── xtask/                   # optional: build automation written in Rust
│   ├── Cargo.toml
│   └── src/main.rs
└── tests/                   # optional workspace-level e2e tests live in the bin crate instead

Workspaces¶

A workspace lets several packages share one lockfile, one build directory, and one set of dependency versions. Single crate or workspace? covers when to reach for one; this section covers how to run one well.

Conventions that keep a workspace sane:

• crates/ directory, flat. Avoid nesting crates inside crates.
• Prefix crate names with the project name (mytools-certs), and use the directory name equal to the crate name. This avoids clashes on crates.io and makes cargo -p obvious.
• One binary crate. Subcommand crates are libraries exposing something like pub fn run(args: Args) -> Result<()> plus a clap Args struct. The bin crate just wires them into a Subcommand enum.
• Dependency direction is one-way: bin → subcommand crates → core. Subcommand crates never depend on each other; anything they share moves down to core.
• Each subcommand crate owns its clap Args (derive clap::Args). This keeps argument definitions next to the code that uses them.

// crates/mytools/src/main.rs
use clap::{Parser, Subcommand};

#[derive(Parser)]
#[command(version, about)]
struct Cli {
    #[command(flatten)]
    global: mytools_core::GlobalArgs,
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    /// Manage certificates
    Certs(mytools_certs::Args),
    /// Check links in markdown
    Links(mytools_links::Args),
    /// Inspect TLS endpoints
    Ssl(mytools_ssl::Args),
}

fn main() -> std::process::ExitCode {
    let cli = Cli::parse();
    mytools_core::telemetry::init(&cli.global);
    let result = match cli.command {
        Command::Certs(a) => mytools_certs::run(&cli.global, a),
        Command::Links(a) => mytools_links::run(&cli.global, a),
        Command::Ssl(a) => mytools_ssl::run(&cli.global, a),
    };
    mytools_core::exit::report(result)
}

Optional: cargo features per subcommand. If some subcommands pull in heavy dependencies, gate them behind features in the bin crate (default = ["certs", "links", "ssl"]) so a slim build is possible. Only bother if build size or time actually matters.

Root Cargo.toml¶

[workspace]
resolver = "3"                  # required explicitly in a virtual manifest
members = ["crates/*", "xtask"]
default-members = ["crates/mytools"]

[workspace.package]
version = "1.6.0"               # single version for the whole workspace
edition = "2024"
rust-version = "1.85"
license = "MIT"
repository = "https://gitlab.com/<namespace>/mytools"
publish = false

[workspace.dependencies]
# internal crates
mytools-core  = { path = "crates/mytools-core" }
mytools-certs = { path = "crates/mytools-certs" }
mytools-links = { path = "crates/mytools-links" }
mytools-ssl   = { path = "crates/mytools-ssl" }
# external crates: versions pinned ONCE here
anyhow = "1"
clap = { version = "4", features = ["derive", "env"] }
reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "json", "blocking"] }
serde = { version = "1", features = ["derive"] }
thiserror = "2"
tracing = "0.1"

[workspace.lints.rust]
unsafe_code = "forbid"

[workspace.lints.clippy]
all = { level = "warn", priority = -1 }
pedantic = { level = "warn", priority = -1 }
module_name_repetitions = "allow"

[profile.release]
lto = "thin"
codegen-units = 1
strip = "symbols"

Member Cargo.toml¶

# crates/mytools-ssl/Cargo.toml
[package]
name = "mytools-ssl"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
publish.workspace = true

[dependencies]
mytools-core.workspace = true
anyhow.workspace = true
clap.workspace = true
reqwest.workspace = true
# a member can add features on top of the workspace definition:
serde = { workspace = true, features = ["rc"] }

[lints]
workspace = true

Why this matters: dependency versions, lint policy and the release version are each defined in exactly one place. Bumping reqwest or the app version is a one-line change.

Version strategy in a workspace: for an application (as opposed to a set of published libraries), one shared workspace.package.version is almost always right. The internal crates are implementation details; they don't need their own semver.

Dependency direction¶

Draw the crate graph and keep it a DAG pointing inward: binaries depend on feature crates, feature crates depend on core, and core depends on nothing internal. If two feature crates need to talk to each other, the shared piece probably belongs in core.

mytools (bin) ──► mytools-ssl ──► mytools-core
       │                              ▲
       └──────► mytools-links ────────┘

Workspace caveats¶

• Don't split prematurely. Each crate adds a Cargo.toml, a public API to maintain, and friction when moving code. A single crate with good modules is fine up to tens of thousands of lines.
• Features are unified across the workspace during a build: if any member enables tokio/fs, every member sees it. That's usually harmless, but it can hide a missing feature declaration that only shows up when a crate is built alone (cargo build -p name).

Root-level files¶

.gitignore¶

/target
**/*.rs.bk
*.pdb

# local env / secrets
.env
*.local.toml

# editor
.idea/
.vscode/
*.swp

# runtime data from local runs
/data/
*.db
*.db-journal
*.db-wal
*.db-shm

# helm
deploy/helm/**/charts/*.tgz

If you keep a global target-dir (for example under ~/.cache) in ~/.cargo/config.toml, /target in the repo will stay empty locally — keep the ignore line anyway, because CI and Docker builds use the in-repo target/.

.editorconfig¶

root = true

[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8
trim_trailing_whitespace = true

[*.rs]
indent_style = space
indent_size = 4

[*.{toml,yml,yaml,json,md}]
indent_style = space
indent_size = 2

[Makefile]
indent_style = tab

Cargo.toml in depth¶

Single-crate manifest¶

[package]
name = "myservice"
version = "0.4.2"
edition = "2024"
rust-version = "1.85"           # MSRV: oldest compiler you promise to support
description = "Tracks companies and their addresses"
license = "MIT"
repository = "https://gitlab.com/<namespace>/myservice"
readme = "README.md"
publish = false                 # prevents accidental `cargo publish`
default-run = "myservice"

[[bin]]
name = "myservice"
path = "src/main.rs"

[dependencies]
anyhow = "1"
axum = "0.8"
clap = { version = "4", features = ["derive", "env"] }
serde = { version = "1", features = ["derive"] }
sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio", "sqlite", "migrate", "macros", "chrono"] }
thiserror = "2"
tokio = { version = "1", features = ["macros", "rt-multi-thread", "signal"] }
tower-http = { version = "0.6", features = ["trace", "fs", "compression-gzip"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }

[dev-dependencies]
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
tempfile = "3"
insta = { version = "1", features = ["yaml"] }

[build-dependencies]
# none needed for a simple git-sha build.rs

[lints.rust]
unsafe_code = "forbid"
missing_debug_implementations = "warn"

[lints.clippy]
all = { level = "warn", priority = -1 }
pedantic = { level = "warn", priority = -1 }
# pedantic is noisy; opt out of the ones you disagree with
module_name_repetitions = "allow"
missing_errors_doc = "allow"
unwrap_used = "warn"
expect_used = "warn"

[profile.release]
lto = "thin"
codegen-units = 1
strip = "symbols"
# panic = "abort"   # smaller/faster, but see note below

[profile.dev.package."*"]
opt-level = 1        # dependencies compiled with light optimization; your code stays fast to rebuild

Notes:

• Version numbers in [dependencies]. Use caret ranges at the granularity you care about ("1", "0.8"). The lockfile gives you reproducibility; the manifest expresses compatibility.
• default-features = false on large crates (sqlx, reqwest) keeps you from silently pulling in OpenSSL, extra runtimes or TLS backends. Prefer rustls over native-tls — it removes the system OpenSSL dependency, which makes static and distroless builds far simpler.
• panic = "abort" shrinks binaries and skips unwinding. For a CLI it is usually fine. For a web server, remember that with abort a panic inside any request handler kills the whole process instead of just that task. Leave it at the default unwind for servers unless you have a supervisor you trust and no panics you expect.
• [lints] in the manifest (stable since Rust 1.74) replaces #![deny(...)] attributes scattered around lib.rs, and Cargo passes them consistently to every target.

Features¶

Cargo features are compile-time switches for optional functionality and optional dependencies:

[features]
default = ["sqlite"]
sqlite = ["dep:sqlx", "sqlx/sqlite"]
postgres = ["dep:sqlx", "sqlx/postgres"]
tls = ["dep:rustls"]

[dependencies]
sqlx = { version = "0.8", optional = true, default-features = false, features = ["runtime-tokio"] }
rustls = { version = "0.23", optional = true }

Rules that keep features sane:

• Features must be additive. Enabling a feature may add functionality, never remove or change it, because Cargo unifies features across the dependency graph and any crate can turn one on.
• Never make two features mutually exclusive if you can avoid it; prefer runtime configuration.
• Test the important combinations in CI: --no-default-features, default, --all-features.
• Name features after capabilities (postgres, sqlite, tls), not after the dependencies that implement them.
• If the matrix grows, cargo hack --feature-powerset checks every combination.

Toolchain and tooling config¶

rust-toolchain.toml¶

[toolchain]
channel = "1.90"       # pin to the stable version you actually test with; bump deliberately
components = ["rustfmt", "clippy"]
profile = "minimal"
# targets = ["x86_64-unknown-linux-musl"]

Pinning means "it built yesterday and fails today" can only be caused by your changes, not by a new clippy release. Bump the pin in its own commit, fix the new lints, move on. (The alternative, channel = "stable", is reasonable for personal tools if you prefer always-current.)

Keep rust-version in Cargo.toml (your minimum supported) and the toolchain pin (what you build with) distinct. For apps they are often the same; for libraries MSRV is usually lower.

rustfmt.toml¶

Keep it short; the defaults are good and most options are nightly-only.

edition = "2024"
max_width = 100
use_field_init_shorthand = true
use_try_shorthand = true

clippy.toml¶

Thresholds, not levels (levels go in [lints]):

too-many-arguments-threshold = 8
cognitive-complexity-threshold = 30
allow-unwrap-in-tests = true
allow-expect-in-tests = true

.cargo/config.toml (project-level)¶

Good for aliases and target-specific settings. Do not put target-dir or absolute paths here — those belong in your user-level ~/.cargo/config.toml, otherwise Docker builds and CI break.

[alias]
lint = "clippy --all-targets --all-features -- -D warnings"
t    = "test --all-targets --all-features"
xtask = "run --package xtask --"

[target.x86_64-unknown-linux-musl]
rustflags = ["-C", "target-feature=+crt-static"]

Part 2: Application architecture¶

Layering and dependency direction¶

Almost every non-trivial program has the same three concerns, whether or not you name them:

1. Domain: the types and rules that make your program your program (a Job can't move from Rejected back to Applied; a backup has a retention policy).
2. Application / services: use cases that orchestrate the domain and the outside world ("record an application", "rotate old backups").
3. Adapters / infrastructure: everything that talks to something external: HTTP handlers, CLI parsing, databases, files, APIs, clocks.

The rule that makes this valuable: dependencies point inward. Adapters know about the domain; the domain knows nothing about adapters. Your Job type shouldn't import axum or sqlx. When the domain is pure, it's trivially unit-testable, and swapping SQLite for Postgres, or a CLI for a web UI, touches only the outer layer.

You don't need ceremony to get this. In a small crate it's just three modules and a habit of not importing infrastructure types into domain/.

Ports and adapters with traits¶

Where the domain or services need something external (storage, an HTTP client, the current time), define a trait describing what they need, in terms of domain types. That trait is a port. The real implementation, and a test fake, are adapters.

// domain/job.rs: pure types
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct JobId(pub i64);

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Status {
    Applied,
    Interviewing,
    Offer,
    Rejected,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Job {
    pub id: JobId,
    pub company: String,
    pub status: Status,
}

// services/jobs.rs: the port, expressed in domain terms
pub trait JobRepository {
    fn get(&self, id: JobId) -> Result<Option<Job>, RepoError>;
    fn save(&self, job: &Job) -> Result<(), RepoError>;
}

#[derive(Debug, thiserror::Error)]
#[error("storage failure: {0}")]
pub struct RepoError(String);

#[derive(Debug, thiserror::Error)]
pub enum ServiceError {
    #[error("job {0:?} not found")]
    NotFound(JobId),
    #[error("cannot move a job from {from:?} to {to:?}")]
    InvalidTransition { from: Status, to: Status },
    #[error(transparent)]
    Repo(#[from] RepoError),
}

pub struct JobService<R> {
    repo: R,
}

impl<R: JobRepository> JobService<R> {
    pub fn new(repo: R) -> Self {
        Self { repo }
    }

    pub fn get(&self, id: JobId) -> Result<Job, ServiceError> {
        self.repo.get(id)?.ok_or(ServiceError::NotFound(id))
    }

    pub fn advance(&self, id: JobId, to: Status) -> Result<Job, ServiceError> {
        let mut job = self.repo.get(id)?.ok_or(ServiceError::NotFound(id))?;
        if job.status == Status::Rejected {
            return Err(ServiceError::InvalidTransition { from: job.status, to });
        }
        job.status = to;
        self.repo.save(&job)?;
        Ok(job)
    }
}

The real adapter (SqliteJobRepository) lives in storage/ and implements JobRepository with sqlx. Tests use an in-memory fake:

#[cfg(test)]
mod tests {
    use super::*;
    use std::{cell::RefCell, collections::HashMap};

    #[derive(Default)]
    struct FakeRepo(RefCell<HashMap<JobId, Job>>);

    impl JobRepository for FakeRepo {
        fn get(&self, id: JobId) -> Result<Option<Job>, RepoError> {
            Ok(self.0.borrow().get(&id).cloned())
        }
        fn save(&self, job: &Job) -> Result<(), RepoError> {
            self.0.borrow_mut().insert(job.id, job.clone());
            Ok(())
        }
    }

    #[test]
    fn rejected_jobs_cannot_advance() {
        let repo = FakeRepo::default();
        let id = JobId(1);
        repo.save(&Job { id, company: "Acme".into(), status: Status::Rejected }).unwrap();

        let svc = JobService::new(repo);
        assert!(matches!(
            svc.advance(id, Status::Offer),
            Err(ServiceError::InvalidTransition { .. })
        ));
    }
}

Don't over-abstract¶

A trait for every struct is Java-in-Rust and makes code harder to read. Introduce a port when there's a real reason:

• the dependency is slow, flaky, or external (network, DB, clock, filesystem) and you want fast deterministic tests, or
• there are, or will soon be, genuinely multiple implementations.

For everything else, concrete types are simpler and the compiler will tell you everything that breaks when you refactor.

Generics or dyn?¶

JobService<R: JobRepository> uses static dispatch: the compiler generates specialised code for each R. The alternative is JobService { repo: Arc<dyn JobRepository> }, dynamic dispatch through a vtable. For application wiring, both are fine; see Generics vs. trait objects for the trade-offs.

Ownership-driven design¶

Ownership isn't just a local rule about variables; it's an architectural tool. Most "fighting the borrow checker" at scale comes from an unclear answer to "who owns this data?"

Make ownership a tree. Ideally, your program's data forms a tree: App owns Config and Services; each service owns its repository; each repository owns its connection pool. Borrowing flows down the tree for the duration of a call. Trees are what Rust's ownership model expresses naturally.

When you need a graph, use IDs, not references. Structures where many things point at many things (graphs, ECS-style game state, a document with cross-references) don't fit single ownership. Rather than Rc<RefCell<Node>> everywhere, store nodes in a Vec or HashMap and refer to them by index or ID:

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
struct NodeId(usize);

struct Graph {
    nodes: Vec<Node>,
}

struct Node {
    name: String,
    edges: Vec<NodeId>, // no lifetimes, no Rc, no RefCell
}

This is how most production Rust handles graph-shaped data: it's simple, cache-friendly, and trivially serialisable. (Crates such as slotmap add generational IDs to catch stale references.)

Share immutable state with Arc; isolate mutable state. Long-lived shared state (configuration, connection pools, caches) goes behind an Arc. If it must be mutable, put the smallest possible piece behind a Mutex/RwLock, or give it to a single task that owns it and talk to it over a channel (the actor pattern).

Short borrows, owned boundaries. Inside a function, borrow freely. Across long-lived boundaries (struct fields, thread/task spawns, channel messages, return values from service layers) prefer owned data. Structs with lifetime parameters are excellent for short-lived views (parsers, iterators, request-scoped helpers) and painful as long-lived application state.

Split structs to split borrows. If two methods conflict because both need &mut self, the struct may be doing two jobs. Borrowing two different fields mutably at once is fine; borrowing self twice isn't. Splitting state into sub-structs lets each method borrow only what it needs.

Configuration¶

Most programs end up with configuration from several sources. Establish one precedence order and stick to it:

built-in defaults  <  config file  <  environment variables  <  command-line flags

Practical guidance:

• Deserialise into one strongly typed Config struct with serde, validate it once at startup, and pass it (or the relevant sub-struct) down. Don't call std::env::var from deep inside business logic.
• Represent durations, sizes, URLs, and paths as real types (Duration, Url, PathBuf), not strings.
• Keep secrets out of config files where you can: read them from the environment, a secret manager, or a password store at startup, and wrap them in a type that doesn't print its contents (for example secrecy::SecretString, or your own newtype with a redacting Debug).
• Follow platform conventions for file locations (the directories / dirs crates resolve XDG paths on Linux).
• clap can read env vars directly (#[arg(long, env = "APP_PORT")]), which covers the top two layers for small tools. Crates like figment or config handle full layering for larger services.

use serde::Deserialize;
use std::{path::PathBuf, time::Duration};

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)] // catch typos in config files
pub struct Config {
    pub database_url: String,
    pub backup_dir: PathBuf,
    #[serde(default = "default_retention_days")]
    pub retention_days: u32,
    #[serde(with = "humantime_serde", default = "default_timeout")]
    pub timeout: Duration,
}

fn default_retention_days() -> u32 { 14 }
fn default_timeout() -> Duration { Duration::from_secs(30) }

A few more rules that pay off:

• Validate at startup, fail fast with a clear message. A config check subcommand that loads and prints the effective config (with secrets redacted) is cheap and very handy.
• Secrets never come from the repo. Read them from env vars, from a file path (DATABASE_PASSWORD_FILE → works with Docker/Kubernetes secrets mounted as files), or at the CLI level from a password manager like pass. Wrap secret strings in a type (e.g. secrecy::SecretString) so they never appear in Debug output or logs.
• Ship examples/config.example.toml with every key documented, and keep it in sync (a test that parses it is a cheap way to enforce that).

Error handling strategy¶

Error handling is an architectural decision, not just syntax. The widely used convention:

Typed errors with thiserror¶

use std::path::PathBuf;

#[derive(Debug, thiserror::Error)]
pub enum BackupError {
    #[error("source directory {} does not exist", .0.display())]
    MissingSource(PathBuf),

    #[error("failed to write archive {}", path.display())]
    Write {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },

    #[error("retention must be at least 1 day, got {0}")]
    InvalidRetention(u32),
}

Guidelines for error types:

• Describe what failed, not what the caller should do. Messages are lowercase, without trailing punctuation, so they compose in chains: failed to run backup: failed to write archive /x: permission denied.
• Keep the cause with #[source] or #[from] so the full chain is available for reporting.
• One error enum per module or layer, not one giant crate-wide enum that every function returns. A function that can only fail in two ways shouldn't advertise twenty.
• Don't leak dependency types in a library's public error unless you're fine with that dependency becoming part of your semver contract. Wrap them.
• Mark public error enums #[non_exhaustive] if you may add variants later.

Context at the edges with anyhow¶

use anyhow::{Context, Result};

pub fn run(config_path: &std::path::Path) -> Result<()> {
    let raw = std::fs::read_to_string(config_path)
        .with_context(|| format!("reading config {}", config_path.display()))?;
    let config: Config = toml::from_str(&raw).context("parsing config")?;
    backup::run(&config).context("running backup")?;
    Ok(())
}

Printing with {:#} shows the whole chain on one line; {:?} shows it as a multi-line report (with a backtrace if RUST_BACKTRACE=1).

Panics are for bugs¶

panic!, unwrap(), expect(), out-of-bounds indexing, and integer overflow in debug builds all signal a bug in the program, not a runtime condition. Use them when an invariant is violated and continuing would be wrong. Return Result for anything that can legitimately fail: I/O, parsing, user input, network calls.

expect("…") beats unwrap() when you do assert something, because the message documents why it can't fail:

let re = regex::Regex::new(r"^\d+\.\d+\.\d+$").expect("version regex is valid");

Mapping errors to the outside world¶

The outermost layer translates internal errors into whatever the outside world understands: exit codes for a CLI, HTTP status codes for a service. Do that translation in exactly one place (see Web service design), not scattered through handlers.

Logging and observability¶

Use the tracing ecosystem rather than println! or the older log crate. It gives you structured fields, spans that carry context across async boundaries, and pluggable output.

use tracing::{info, instrument, warn};

#[instrument(skip(repo), fields(job_id = id.0))]
pub fn advance(repo: &impl JobRepository, id: JobId, to: Status) -> Result<Job, ServiceError> {
    info!(?to, "advancing job");
    let mut job = repo.get(id)?.ok_or(ServiceError::NotFound(id))?;
    if job.status == Status::Rejected {
        warn!(from = ?job.status, "refusing transition");
        return Err(ServiceError::InvalidTransition { from: job.status, to });
    }
    job.status = to;
    repo.save(&job)?;
    Ok(job)
}

Initialise the subscriber once, in main, and let libraries only emit events:

fn init_tracing() {
    use tracing_subscriber::{fmt, EnvFilter};
    fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();
}

• Control verbosity with RUST_LOG=my_crate=debug,tower_http=info.
• For services, emit JSON (.json()) so log shippers (Vector, Logstash, Loki) can index fields.
• Log errors once, where they're handled, not at every layer they pass through. Re-logging the same error at each ? creates noise.
• tracing-opentelemetry connects spans to distributed tracing backends when you need it.
• For metrics, the metrics crate with a Prometheus exporter keeps instrumentation decoupled from the backend.

A reusable telemetry module¶

In practice, wrap subscriber setup in a small telemetry module so verbosity and output format come from flags or the environment:

// src/telemetry.rs
use tracing_subscriber::{fmt, prelude::*, EnvFilter};
use crate::cli::{LogArgs, LogFormat};

pub fn init(args: &LogArgs) -> anyhow::Result<()> {
    let default = match args.verbose {
        0 => "info",
        1 => "debug",
        _ => "trace",
    };
    // RUST_LOG wins if set, e.g. RUST_LOG=myservice=debug,tower_http=info
    let filter = EnvFilter::try_from_default_env()
        .unwrap_or_else(|_| EnvFilter::new(format!("{}={default},tower_http=info", env!("CARGO_CRATE_NAME"))));

    let registry = tracing_subscriber::registry().with(filter);
    match args.log_format {
        LogFormat::Json => registry.with(fmt::layer().json().with_current_span(true)).try_init()?,
        LogFormat::Pretty => registry.with(fmt::layer().with_target(false)).try_init()?,
    }
    Ok(())
}

Guidelines:

• Logs go to stdout/stderr, never directly to files, for anything running under Docker, Kubernetes or systemd. Collection (journald, Vector, Loki, Elasticsearch) is the platform's job.
• JSON in production, pretty locally. Make it a flag/env var, not a compile-time choice.
• Use structured fields (tracing::info!(company_id = %id, "created company")) instead of interpolating values into the message; they become queryable fields downstream.
• Instrument key functions with #[tracing::instrument(skip(pool))] to get spans with timing.
• For web apps add tower_http::trace::TraceLayer for per-request spans, and a request-ID layer (tower_http::request_id) so a single request can be traced across log lines.

Async and concurrency architecture¶

Do you need async?¶

Async Rust shines when you have many concurrent I/O-bound tasks: web servers, proxies, crawlers, anything juggling hundreds of sockets. It adds real complexity (Send bounds, pinning, runtime selection, colored functions).

If most of the ecosystem you need is async (axum, sqlx, reqwest), just use async; fighting it is worse.

Async rules of thumb¶

• Pick one runtime (in practice, tokio) and use it consistently.
• Never block the runtime. Long CPU work or blocking I/O (std::fs, a sync DB driver, heavy compression) inside an async fn stalls every task on that worker thread. Wrap it in tokio::task::spawn_blocking, or use async equivalents (tokio::fs).
• Don't hold a std::sync::Mutex guard across .await. Lock, copy or modify, drop the guard, then await. A std::sync::Mutex is fine (and faster) for short critical sections; use tokio::sync::Mutex only when you truly must hold a lock across an await point.
• Spawned tasks need 'static + Send. Anything moved into tokio::spawn must be owned (no borrowed references) and thread-safe. This is where Arc and cloning cheap handles come in.
• Bound your concurrency. Spawning one task per item in a 100,000-item list will happily open 100,000 sockets. Use futures::stream::iter(..).buffer_unordered(n), a Semaphore, or JoinSet with a limit.
• Plan for cancellation. Dropping a future cancels it at its current .await. Make sure partial work is safe to abandon, and use tokio::select! with a shutdown signal (tokio::signal::ctrl_c(), a CancellationToken) for graceful shutdown.

use futures::stream::{self, StreamExt};

async fn check_all(urls: Vec<String>, client: &reqwest::Client) -> Vec<(String, bool)> {
    stream::iter(urls)
        .map(|url| async move {
            let ok = client.head(&url).send().await.is_ok_and(|r| r.status().is_success());
            (url, ok)
        })
        .buffer_unordered(16) // at most 16 in flight
        .collect()
        .await
}

Concurrency shapes¶

CLI design¶

clap with the derive API is the standard:

use clap::{Args, Parser, Subcommand};
use std::path::PathBuf;

/// Back up and restore application data.
#[derive(Debug, Parser)]
#[command(version, about)]
pub struct Cli {
    /// Path to the config file.
    #[arg(short, long, env = "BACKUP_CONFIG", default_value = "backup.toml")]
    pub config: PathBuf,

    /// Increase log verbosity (-v, -vv).
    #[arg(short, long, action = clap::ArgAction::Count, global = true)]
    pub verbose: u8,

    #[command(subcommand)]
    pub command: Command,
}

#[derive(Debug, Subcommand)]
pub enum Command {
    /// Create a new backup.
    Create(CreateArgs),
    /// List existing backups.
    List,
    /// Delete backups older than the retention period.
    Prune {
        /// Show what would be deleted without deleting it.
        #[arg(long)]
        dry_run: bool,
    },
}

#[derive(Debug, Args)]
pub struct CreateArgs {
    /// Database name to back up.
    pub database: String,
    /// Compress the archive with zstd.
    #[arg(long)]
    pub compress: bool,
}

Conventions that make CLIs pleasant:

• Output data to stdout, diagnostics to stderr. That way tool list | grep x works and logs don't corrupt piped output.
• Offer --json (or --output json) for anything a script might consume.
• Meaningful exit codes: 0 success, 1 general failure, 2 usage error (clap does this automatically). Document any others.
• --dry-run for anything destructive; confirm interactively only when stdin is a TTY (std::io::IsTerminal).
• Respect NO_COLOR, and disable colour when stdout isn't a terminal.
• Generate shell completions and man pages from the same definitions (clap_complete, clap_mangen).

Global flags, environment variables, and operational subcommands¶

For tools that run in containers or under systemd, flatten shared flags into a struct, give every deployable flag an environment variable, and add a few operational subcommands:

// src/cli.rs
use clap::{Args, Parser, Subcommand, ValueEnum};
use std::path::PathBuf;

#[derive(Debug, Parser)]
#[command(version = crate::build_info::VERSION_LONG, about, propagate_version = true)]
pub struct Cli {
    /// Path to config file
    #[arg(short, long, global = true, env = "MYSERVICE_CONFIG")]
    pub config: Option<PathBuf>,

    #[command(flatten)]
    pub log: LogArgs,

    #[command(subcommand)]
    pub command: Command,
}

#[derive(Debug, Args)]
pub struct LogArgs {
    /// Increase verbosity (-v, -vv)
    #[arg(short, long, global = true, action = clap::ArgAction::Count)]
    pub verbose: u8,
    /// Log output format
    #[arg(long, global = true, value_enum, default_value_t = LogFormat::Pretty, env = "MYSERVICE_LOG_FORMAT")]
    pub log_format: LogFormat,
}

#[derive(Debug, Clone, Copy, ValueEnum)]
pub enum LogFormat { Pretty, Json }

#[derive(Debug, Subcommand)]
pub enum Command {
    /// Run the HTTP server
    Serve,
    /// Apply database migrations and exit
    Migrate,
    /// Exit 0 if the running server is healthy (for container healthchecks)
    Healthcheck,
}

• Every flag that a deployment might set gets an env = "...". Containers and systemd units can then configure the app without a config file.
• A healthcheck subcommand lets distroless/scratch images (which have no curl) run Docker healthchecks.
• Output format flag (--output table|json) on CLIs that print data — makes them scriptable.

Web service design¶

The axum + tokio + tower stack is the common choice. Architectural guidance:

Shared application state lives in one cloneable struct. Cheap-to-clone handles (connection pools, HTTP clients) are already Arc-based internally:

use axum::{
    Json, Router,
    extract::{Path, State},
    http::StatusCode,
    response::{IntoResponse, Response},
    routing::get,
};
use std::sync::Arc;

#[derive(Clone)]
pub struct AppState {
    pub jobs: Arc<JobService<SqliteJobRepository>>,
}

pub fn router(state: AppState) -> Router {
    Router::new()
        .route("/health", get(|| async { "ok" }))
        .route("/jobs/{id}", get(get_job))
        .with_state(state)
}

Handlers stay thin: extract inputs, call a service, convert the result. No SQL, no business rules:

#[derive(serde::Serialize)]
pub struct JobDto {
    id: i64,
    company: String,
    status: String,
}

impl From<Job> for JobDto {
    fn from(job: Job) -> Self {
        Self { id: job.id.0, company: job.company, status: format!("{:?}", job.status) }
    }
}

async fn get_job(
    State(state): State<AppState>,
    Path(id): Path<i64>,
) -> Result<Json<JobDto>, AppError> {
    let job = state.jobs.get(JobId(id))?;
    Ok(Json(job.into()))
}

(The repository in this example is synchronous for brevity. With an async driver such as sqlx, the trait methods become async fn and the handler .awaits the service call; the structure is identical.)

One error type for the HTTP layer, converted from service errors, mapped to status codes in exactly one place:

pub enum AppError {
    NotFound,
    BadRequest(String),
    Internal(anyhow::Error),
}

impl From<ServiceError> for AppError {
    fn from(err: ServiceError) -> Self {
        match err {
            ServiceError::NotFound(_) => AppError::NotFound,
            ServiceError::InvalidTransition { .. } => AppError::BadRequest(err.to_string()),
            ServiceError::Repo(e) => AppError::Internal(e.into()),
        }
    }
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        match self {
            AppError::NotFound => StatusCode::NOT_FOUND.into_response(),
            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg).into_response(),
            AppError::Internal(err) => {
                tracing::error!(error = ?err, "internal error");
                // Don't leak internal details to clients.
                StatusCode::INTERNAL_SERVER_ERROR.into_response()
            }
        }
    }
}

Separate DTOs from domain types. The JSON shape your API exposes (JobDto) is a contract with clients; your domain Job should be free to change. From impls convert between them.

Cross-cutting concerns as tower middleware: request tracing (tower_http::trace::TraceLayer), timeouts, compression, CORS, request IDs, and auth. Don't hand-roll them per handler.

The router assembly below keeps state minimal (pool plus config) for brevity; in a layered app, AppState holds the services built from them, as above.

Router assembly and graceful shutdown¶

// src/http/mod.rs
use axum::{routing::get, Router};
use tower_http::{compression::CompressionLayer, services::ServeDir, trace::TraceLayer};
use crate::{config::Config, state::AppState};

pub mod companies;
pub mod error;
pub mod health;

pub fn router(state: AppState) -> Router {
    Router::new()
        .route("/healthz", get(health::live))
        .route("/readyz", get(health::ready))
        .nest("/api/companies", companies::router())
        .nest_service("/static", ServeDir::new("static"))
        .layer(TraceLayer::new_for_http())
        .layer(CompressionLayer::new())
        .with_state(state)
}

pub async fn serve(cfg: Config) -> anyhow::Result<()> {
    let db = crate::db::connect(&cfg).await?;
    crate::db::run_migrations(&db).await?;
    let state = AppState { db, cfg: cfg.clone().into() };

    let listener = tokio::net::TcpListener::bind(cfg.listen).await?;
    tracing::info!(addr = %cfg.listen, version = env!("CARGO_PKG_VERSION"), "listening");
    axum::serve(listener, router(state))
        .with_graceful_shutdown(shutdown_signal())
        .await?;
    Ok(())
}

async fn shutdown_signal() {
    let ctrl_c = async { tokio::signal::ctrl_c().await.ok(); };
    #[cfg(unix)]
    let term = async {
        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
            .expect("install SIGTERM handler")
            .recv()
            .await;
    };
    #[cfg(not(unix))]
    let term = std::future::pending::<()>();
    tokio::select! { () = ctrl_c => {}, () = term => {} }
    tracing::info!("shutdown signal received");
}

Handling SIGTERM is not optional for containers: Kubernetes and docker stop send SIGTERM and wait; without a handler, in-flight requests are cut off and SQLite writes may be interrupted.

Health endpoints¶

• /healthz (liveness): process is up and the event loop responds. No dependencies checked — otherwise a DB blip causes restart loops.
• /readyz (readiness): dependencies are reachable (e.g. SELECT 1). Failing readiness removes the pod from service without restarting it.

Static assets and templates¶

Two options:

• Serve from disk (ServeDir): simple, lets you tweak CSS without rebuilding; the Dockerfile must copy static/ and templates/.
• Embed in the binary (rust-embed, include_str!, or compile-time templates with askama): one self-contained file, nothing to forget in the image. Usually the better choice for small homelab apps.

Persistence¶

• sqlx gives you async SQL with optional compile-time checked queries (query!, query_as!) against a real database or offline metadata (cargo sqlx prepare). diesel is a mature alternative with a typed query builder; rusqlite is a good synchronous choice for SQLite in CLIs.
• Put SQL behind a repository (the port from earlier), returning domain types, so handlers and services never see rows.
• Use transactions for multi-statement operations; pass &mut Transaction down into repository methods that must participate.

Migrations¶

• Keep migrations in migrations/ at the repo root, named YYYYMMDDHHMMSS_description.sql (what sqlx migrate add generates).
• Migrations are forward-only and immutable once released. Fix mistakes with a new migration.
• Embed them: sqlx::migrate!("./migrations").run(&pool).await? compiles the SQL into the binary, so the image doesn't need the files.
• Run them at startup for single-instance apps, and also expose a migrate subcommand for when you want to run them separately (a Kubernetes init container or Helm hook).
• With sqlx's compile-time checked macros (query!, query_as!), commit the .sqlx/ directory produced by cargo sqlx prepare and set SQLX_OFFLINE=true in CI and Docker so builds don't need a live database. Add a CI check (cargo sqlx prepare --check) so the metadata can't go stale.

SQLite in production¶

• Enable WAL mode and a busy timeout on connect (journal_mode=WAL, busy_timeout=5000), and foreign keys (foreign_keys=ON — off by default in SQLite).
• SQLite apps are single-writer, single-replica. In Kubernetes: replicas: 1, a ReadWriteOnce PVC, and strategy: Recreate so the old pod releases the file before the new one starts.
• Back up with SQLite's online backup (VACUUM INTO 'backup.db' or sqlite3 .backup), not by copying the live file.

Part 3: Core coding concepts¶

Type-driven design¶

Rust's type system is expressive enough to make many bugs unrepresentable. This is the single biggest lever for code quality.

Enums for states and alternatives¶

An enum (a sum type) says "exactly one of these". Use it instead of multiple booleans or optional fields that are only valid in some combinations:

// Fragile: what does `connected: false, session: Some(..)` mean?
struct ConnectionBad {
    connected: bool,
    session: Option<String>,
    error: Option<String>,
}

// Each state carries exactly the data that's valid in it.
enum Connection {
    Disconnected,
    Connecting { attempt: u32 },
    Connected { session: String },
    Failed { error: String },
}

match on an enum is exhaustive: add a variant, and the compiler lists every place that needs updating. That's what makes enums so valuable during refactoring.

Replace boolean parameters with enums¶

// What do these mean at the call site?
export(&data, true, false);

// Self-documenting, and impossible to swap by accident:
export(&data, Format::Json, Overwrite::No);

The newtype pattern¶

Wrap a primitive in a single-field struct to give it meaning and invariants:

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct UserId(u64);

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct OrderId(u64);

fn cancel(order: OrderId, by: UserId) { /* ... */ }
// cancel(user_id, order_id) is now a compile error instead of a data bug.

Newtypes cost nothing at runtime. They also let you implement foreign traits on foreign types (you can't impl Display for Vec<String>, but you can for struct Lines(Vec<String>)).

Parse, don't validate¶

Instead of passing around a String and checking it's a valid email/hostname/version in several places, parse it once into a type that can only hold valid values:

use std::{fmt, str::FromStr};

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Hostname(String);

#[derive(Debug, thiserror::Error)]
#[error("invalid hostname: {0:?}")]
pub struct InvalidHostname(String);

impl FromStr for Hostname {
    type Err = InvalidHostname;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let valid = !s.is_empty()
            && s.len() <= 253
            && s.split('.').all(|label| {
                !label.is_empty()
                    && label.len() <= 63
                    && !label.starts_with('-')
                    && !label.ends_with('-')
                    && label.chars().all(|c| c.is_ascii_alphanumeric() || c == '-')
            });
        if valid {
            Ok(Hostname(s.to_ascii_lowercase()))
        } else {
            Err(InvalidHostname(s.to_owned()))
        }
    }
}

impl fmt::Display for Hostname {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.0)
    }
}

impl AsRef<str> for Hostname {
    fn as_ref(&self) -> &str {
        &self.0
    }
}

The inner field is private, so the only way to get a Hostname is through from_str. Every function that takes a Hostname can rely on it being valid with no further checks. With FromStr implemented, clap and serde (via #[serde(try_from = "String")] plus a TryFrom<String> impl) can parse straight into it.

Typestate: encode protocol steps in types¶

When an object must go through steps in order, make each step a different type so calling things out of order doesn't compile:

pub struct Draft { body: String }
pub struct Reviewed { body: String, reviewer: String }
pub struct Published { url: String }

impl Draft {
    pub fn new(body: impl Into<String>) -> Self { Draft { body: body.into() } }
    pub fn review(self, reviewer: &str) -> Reviewed {
        Reviewed { body: self.body, reviewer: reviewer.to_owned() }
    }
}

impl Reviewed {
    pub fn publish(self, slug: &str) -> Published {
        // ... persist self.body, record self.reviewer ...
        Published { url: format!("/posts/{slug}") }
    }
}

// Draft::new("hi").publish(); // error: no method `publish` on `Draft`

Each transition takes self by value, consuming the old state. Use typestate for genuinely sequential APIs (builders, connection handshakes, request pipelines); don't force it onto everything.

Traits¶

Generics vs. trait objects¶

Default to generics for functions and small helpers. Use dyn for plugin systems, heterogeneous collections, and to cut compile times in large application wiring.

impl Trait in argument position is shorthand for a generic. In return position it hides a concrete type behind a trait (very common for iterators and closures):

fn evens(limit: u32) -> impl Iterator<Item = u32> {
    (0..limit).filter(|n| n % 2 == 0)
}

Associated types vs. generic parameters¶

Use an associated type when each implementing type has exactly one natural choice (Iterator::Item, FromStr::Err). Use a generic parameter when a type might implement the trait several times for different parameters (From<T>, Add<Rhs>).

The orphan rule¶

You can implement a trait for a type only if either the trait or the type is defined in your crate. You can't impl Display for Vec<u8>. The workaround is a newtype. This rule is what keeps two crates from providing conflicting impls.

Extension traits¶

To add methods to a type you don't own, define a trait and implement it for that type:

pub trait StrExt {
    fn truncate_ellipsis(&self, max: usize) -> String;
}

impl StrExt for str {
    fn truncate_ellipsis(&self, max: usize) -> String {
        if self.chars().count() <= max {
            self.to_owned()
        } else {
            let cut: String = self.chars().take(max.saturating_sub(1)).collect();
            format!("{cut}…")
        }
    }
}

Async functions in traits¶

async fn in traits is stable (since Rust 1.75) and works well with generics. Such traits aren't dyn-compatible, so if you need Box<dyn Trait> with async methods, use the async-trait crate or return boxed futures manually.

Standard traits to implement¶

Implementing the right standard traits makes your types work smoothly with the rest of the ecosystem. For a typical value type, consider:

Implement From, never Into directly. The blanket impl gives you Into automatically.

Error handling in code¶

Beyond the architecture covered in Error handling strategy, a few everyday idioms:

// `?` propagates errors and converts them via `From`.
fn load(path: &Path) -> Result<Config, AppError> {
    let text = std::fs::read_to_string(path)?;   // io::Error -> AppError via From
    let cfg = toml::from_str(&text)?;            // toml error -> AppError via From
    Ok(cfg)
}

// `?` also works on Option inside functions returning Option.
fn first_word_len(s: &str) -> Option<usize> {
    Some(s.split_whitespace().next()?.len())
}

// Converting between Option and Result.
let port: u16 = env_port.ok_or(ConfigError::MissingPort)?;
let maybe: Option<u16> = "8080".parse().ok();

// Defaults without unwrap.
let retries = cfg.retries.unwrap_or(3);
let name = cfg.name.unwrap_or_default();
let dir = cfg.dir.unwrap_or_else(default_dir); // lazily computed

// Collecting an iterator of Results stops at the first error.
let nums: Result<Vec<u32>, _> = ["1", "2", "x"].iter().map(|s| s.parse::<u32>()).collect();

Useful combinators to know: map, map_err, and_then, ok_or/ok_or_else, unwrap_or/unwrap_or_else/unwrap_or_default, is_some_and/is_ok_and, as_ref/as_deref, transpose, inspect_err.

Iterators and closures¶

Iterators are lazy, composable, and compile down to the same code as hand-written loops (often better, since bounds checks are elided).

let active_emails: Vec<&str> = users
    .iter()                                  // borrow each User
    .filter(|u| u.active)
    .map(|u| u.email.as_str())
    .collect();

let total_bytes: u64 = files.iter().map(|f| f.size).sum();

let by_domain: std::collections::HashMap<&str, usize> =
    emails.iter().fold(Default::default(), |mut acc, e| {
        let domain = e.rsplit('@').next().unwrap_or("");
        *acc.entry(domain).or_default() += 1;
        acc
    });

The three ways to iterate a collection:

Closures capture their environment in the least restrictive way the body allows. The trait they implement tells callers how they can be used:

Accept the most permissive bound you can as a function parameter (FnOnce > FnMut > Fn in what callers may pass). Add move to a closure to force it to take ownership of its captures, which is required when the closure outlives the current scope (threads, spawned tasks, returned closures).

Prefer a plain for loop when the body has side effects, early returns, or ?. Iterator chains are for transforming data; don't contort logic into fold for style points.

Strings, paths, and conversions¶

API guidelines:

• Accept borrowed, return owned. Take &str, &[T], &Path; return String, Vec<T>, PathBuf.
• For flexible path parameters, take impl AsRef<Path>, so callers can pass &str, String, PathBuf, or &Path.
• If a function will store a string, take impl Into<String> (or just String) so callers who already own one can hand it over without a copy.
• Don't convert paths to String to manipulate them. Use Path::join, extension, file_stem, parent. Use path.display() to print one.

use std::path::{Path, PathBuf};

pub struct Archive {
    name: String,
    dir: PathBuf,
}

impl Archive {
    pub fn new(name: impl Into<String>, dir: impl AsRef<Path>) -> Self {
        Self { name: name.into(), dir: dir.as_ref().to_path_buf() }
    }

    pub fn path(&self) -> PathBuf {
        self.dir.join(format!("{}.tar.zst", self.name))
    }
}

Pattern matching idioms¶

// let-else: bind or bail out early, keeping the happy path unindented.
let Some(user) = repo.find(id)? else {
    return Err(Error::NotFound(id));
};

// if let chains (Rust 2024 edition, 1.88+): combine pattern and boolean tests.
if let Some(cfg) = config
    && let Some(port) = cfg.port
    && port != 0
{
    listen(port);
}

// matches! for boolean pattern tests.
let is_terminal = matches!(status, Status::Offer | Status::Rejected);

// Bind and test at once with @.
match code {
    c @ 200..=299 => println!("success {c}"),
    c @ 400..=499 => println!("client error {c}"),
    other => println!("other {other}"),
}

// Match on a reference to avoid moving out of the value.
match &state {
    Connection::Connected { session } => println!("{session}"), // session: &String
    _ => {}
}

Avoid a catch-all _ => arm on your own enums where you can. Listing every variant means adding a new one produces a compile error at every match that needs a decision. (See the worked partial-move example for how bindings in patterns move or borrow.)

Builders¶

Rust has no named or default arguments. For types with many optional settings, use a builder:

#[derive(Debug, Clone)]
pub struct Client {
    base_url: String,
    timeout: std::time::Duration,
    retries: u32,
    user_agent: String,
}

#[derive(Debug, Default)]
pub struct ClientBuilder {
    timeout: Option<std::time::Duration>,
    retries: Option<u32>,
    user_agent: Option<String>,
}

impl Client {
    pub fn builder() -> ClientBuilder {
        ClientBuilder::default()
    }
}

impl ClientBuilder {
    pub fn timeout(mut self, t: std::time::Duration) -> Self {
        self.timeout = Some(t);
        self
    }
    pub fn retries(mut self, n: u32) -> Self {
        self.retries = Some(n);
        self
    }
    pub fn user_agent(mut self, ua: impl Into<String>) -> Self {
        self.user_agent = Some(ua.into());
        self
    }
    pub fn build(self, base_url: impl Into<String>) -> Client {
        Client {
            base_url: base_url.into(),
            timeout: self.timeout.unwrap_or(std::time::Duration::from_secs(30)),
            retries: self.retries.unwrap_or(3),
            user_agent: self.user_agent.unwrap_or_else(|| "my-tool/1.0".into()),
        }
    }
}

// let client = Client::builder().retries(5).build("https://api.example.com");

Required values go in build() (or builder()) so they can't be forgotten; optional ones get setters. For simpler cases, a Default impl plus struct-update syntax is often enough:

let opts = Options { verbose: true, ..Default::default() };

Concurrency primitives¶

Rust's thread-safety guarantees rest on two auto-traits:

• Send: a value can be moved to another thread.
• Sync: a value can be shared by reference between threads (&T is Send).

The compiler implements them automatically and refuses to compile code that would share non-thread-safe types (like Rc or RefCell) across threads. That's the "fearless concurrency" promise: data races are compile errors.

Tools, from simplest to most involved:

// Scoped threads can borrow from the enclosing stack frame, so no Arc is needed.
let data = vec![1, 2, 3, 4, 5, 6];
let (left, right) = data.split_at(data.len() / 2);
let (a, b) = std::thread::scope(|s| {
    let ha = s.spawn(|| left.iter().sum::<i32>());
    let hb = s.spawn(|| right.iter().sum::<i32>());
    (ha.join().unwrap(), hb.join().unwrap())
});
assert_eq!(a + b, 21);

// Data parallelism with rayon: change .iter() to .par_iter().
// use rayon::prelude::*;
// let total: u64 = files.par_iter().map(|f| hash_file(f)).sum();

// Channels for message passing.
let (tx, rx) = std::sync::mpsc::channel();
std::thread::spawn(move || {
    for i in 0..3 {
        tx.send(i).unwrap();
    }
});
let received: Vec<i32> = rx.iter().collect();

One-time global initialisation without external crates:

use std::sync::LazyLock;

static VERSION_RE: LazyLock<regex::Regex> =
    LazyLock::new(|| regex::Regex::new(r"^\d+\.\d+\.\d+$").expect("valid regex"));

Prefer passing state explicitly over globals. LazyLock/OnceLock are for genuinely global, immutable things like compiled regexes or lookup tables.

Macros¶

Declarative macros (macro_rules!) eliminate repetitive code that functions and generics can't express, such as generating similar impls for several types:

macro_rules! impl_id {
    ($($name:ident),* $(,)?) => {
        $(
            #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
            pub struct $name(pub i64);

            impl std::fmt::Display for $name {
                fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                    write!(f, "{}", self.0)
                }
            }
        )*
    };
}

impl_id!(JobId, CompanyId, ContactId);

Procedural macros (derives like #[derive(Serialize)], attributes like #[tokio::main]) are powerful but live in their own crate, slow down compilation, and are harder to debug.

Reach for a function first, generics second, and a macro only when both fall short. Macros are harder to read, harder for IDEs to analyse, and produce worse error messages.

Unsafe code¶

unsafe doesn't turn off the borrow checker; it unlocks five extra abilities (dereferencing raw pointers, calling unsafe functions including FFI, accessing mutable statics, implementing unsafe traits, accessing union fields). In those blocks you are responsible for upholding Rust's invariants.

For application code, you almost never need it. If you do:

• Put #![forbid(unsafe_code)] (or the workspace lint) in every crate that doesn't need it.
• Encapsulate unsafe code in a small module with a safe public API.
• Write a // SAFETY: comment on every unsafe block explaining why the invariants hold.
• Test it under Miri (cargo +nightly miri test), which detects undefined behaviour at runtime.
• Prefer a well-reviewed crate over your own unsafe code.

Performance¶