焉知非鱼

Happy 37th Birthday

2025-05-07T00:00:00+00:00

Do you know what makes 37 such a fascinating number?

Well, it's not just any number—it's a prime! And not just any prime, but one with remarkable properties.

Thirty-seven is truly magnificent – a prime number that stands boldly in its mathematical uniqueness. It’s the twelfth prime, sitting proudly between 31 and 41 in the sequence of these indivisible numbers.

May this year be as unique and irreducible as the number itself – full of moments that can’t be divided or diminished.

Understanding Rust’s Conversion Traits

2025-05-06T00:00:00+00:00

Introduction

Rust’s type system is both powerful and strict, enforcing strong boundaries between different types. However, we often need to convert values between related types - for example, from a tuple like (i32, i32) to a custom Point struct, or from a String to a &str.

Some concepts are confusing to beginners, which are difficult to understand.

Don't worry. We have details explaining how to use each trait effectively, including best practices and common pitfalls.

This is where Rust’s conversion traits come into play. These traits provide standardized ways to convert between types, with clear semantics about cost, fallibility, and ownership. Understanding these traits is crucial for writing idiomatic, flexible Rust code.

This article explores the various conversion traits in Rust, explaining:

When to use each trait
How they relate to each other
Common pitfalls and best practices
Real-world examples of each trait in action

The Conversion Trait Ecosystem

Before diving into each trait, it’s helpful to understand how they relate to each other:

Trait Group Infallible Fallible Purpose

Trait Group	Infallible	Fallible	Purpose
Value conversion	`From`/`Into`	`TryFrom`/`TryInto`	Convert between owned values
String parsing	N/A	`FromStr`	Parse strings into types
Reference conversion	`AsRef`/`AsMut`	N/A	Cheap reference-to-reference conversion
Reference with semantics	`Borrow`/`BorrowMut`	N/A	Reference conversion preserving equality/hash/ordering
Borrowed to owned	`ToOwned`	N/A	Get owned values from borrowed data

Value conversion

From/Into

TryFrom/TryInto

Convert between owned values

String parsing

N/A

FromStr

Parse strings into types

Reference conversion

AsRef/AsMut

N/A

Cheap reference-to-reference conversion

Reference with semantics

Borrow/BorrowMut

N/A

Reference conversion preserving equality/hash/ordering

Borrowed to owned

ToOwned

N/A

Get owned values from borrowed data

From and Into

Core Concepts

From and Into are the most fundamental conversion traits in Rust. They handle infallible conversions between owned values.

pub trait From: Sized {
    fn from(value: T) -> Self;
}

pub trait Into: Sized {
    fn into(self) -> T;
}

These traits are reciprocal - implementing From automatically gives you Into thanks to a generic blanket implementation:

impl Into for T
where
    U: From,
{
    fn into(self) -> U {
        U::from(self)
    }
}

Key Characteristics

Ownership: Both traits take ownership of the source value and return an owned value
Infallible: Conversions are expected to always succeed (no Result return type)
Costly: May involve memory allocation and data copying
Direction: Prefer implementing From rather than Into due to the blanket implementation

When to Use From/Into

Use From and Into when:

You need to convert between owned values
The conversion cannot fail
You prefer a more ergonomic, method-call syntax (for Into)

Example: Point Conversion

Here’s a practical example showing how to implement From for converting between a tuple and a Point struct:

struct Point {
    x: i32,
    y: i32,
}

// Converting from a tuple to a Point
impl From<(i32, i32)> for Point {
    fn from((x, y): (i32, i32)) -> Self {
        Point { x, y }
    }
}

// Converting from a Point to a tuple
impl From for (i32, i32) {
    fn from(Point { x, y }: Point) -> Self {
        (x, y)
    }
}

fn example() {
    // Using From
    let p1 = Point::from((10, 20));

    // Using Into
    let p2: Point = (10, 20).into();

    // Converting back to a tuple
    let t1: (i32, i32) = p1.into();
    let t2 = (i32, i32)::from(p2);
}

Complex Example: Triangle from Points

This example demonstrates how to compose conversions, allowing a Triangle to be created from anything that can be converted into `Point`s:

struct Triangle {
    p1: Point,
    p2: Point,
    p3: Point,
}

// This implementation allows creating a Triangle from any array of 3 items,
// as long as those items can be converted into Points
impl From<[P; 3]> for Triangle
where
    P: Into,
{
    fn from([p1, p2, p3]: [P; 3]) -> Self {
        Triangle {
            p1: p1.into(),
            p2: p2.into(),
            p3: p3.into(),
        }
    }
}

fn example() {
    // Create a triangle directly from tuples
    let triangle: Triangle = [(0, 0), (1, 1), (2, 2)].into();

    // Mix and match different types that can convert to Points
    let p1 = Point { x: 0, y: 0 };
    let p2 = (1, 1);
    let p3 = Point { x: 2, y: 2 };
    let triangle = Triangle { p1, p2: p2.into(), p3 };
}

Best Practices for From/Into

Prefer implementing From over Into - You get Into for free, and From impls tend to be more reusable.
Reserve for infallible conversions - If your conversion might fail, use TryFrom/TryInto instead.
Be mindful of expensive conversions - These traits should be used for reasonable cost conversions; extremely expensive operations might warrant a different approach.
Follow the "newtype" pattern - When wrapping a type, always implement From and Into between the wrapper and the wrapped type.

TryFrom and TryInto

Core Concepts

TryFrom and TryInto are the fallible versions of From and Into. They return a Result to indicate whether the conversion succeeded or failed.

pub trait TryFrom: Sized {
    type Error;
    fn try_from(value: T) -> Result;
}

pub trait TryInto: Sized {
    type Error;
    fn try_into(self) -> Result;
}

Just like From and Into, these traits are reciprocal with a blanket implementation:

impl TryInto for T
where
    U: TryFrom,
{
    type Error = U::Error;
    fn try_into(self) -> Result {
        U::try_from(self)
    }
}

Key Characteristics

Ownership: Takes ownership and returns owned values
Fallible: Returns a Result type to handle conversion failures
Associated Error Type: Requires defining the error type for conversion failures
Compatibility: Cannot implement both From and TryFrom for the same type

When to Use TryFrom/TryInto

Use TryFrom and TryInto when:

Your conversion might reasonably fail
You need to communicate specific error conditions
You’re dealing with input validation or constraints

Example: Bounded Point Conversion

Let’s modify our Point example to ensure coordinates fall within a valid range:

use std::convert::TryFrom;
use std::error;
use std::fmt;

struct Point {
    x: i32,
    y: i32,
}

#[derive(Debug)]
struct OutOfBoundsError;

impl fmt::Display for OutOfBoundsError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "point coordinates out of bounds (must be between -1000 and 1000)")
    }
}

impl error::Error for OutOfBoundsError {}

// Now fallible - coordinates must be within range
impl TryFrom<(i32, i32)> for Point {
    type Error = OutOfBoundsError;

    fn try_from((x, y): (i32, i32)) -> Result {
        if x.abs() > 1000 || y.abs() > 1000 {
            return Err(OutOfBoundsError);
        }
        Ok(Point { x, y })
    }
}

// Still infallible - any Point can be converted to a tuple
impl From for (i32, i32) {
    fn from(Point { x, y }: Point) -> Self {
        (x, y)
    }
}

fn example() -> Result<(), OutOfBoundsError> {
    // Valid point
    let p1 = Point::try_from((100, 200))?;

    // Using TryInto
    let p2: Result = (100, 200).try_into();

    // Will fail - out of bounds
    let p3 = Point::try_from((2000, 3000))?; // Returns Err

    Ok(())
}

Complex Example: Fallible Triangle Construction

Building on our previous example, we can make triangle construction fallible:

struct Triangle {
    p1: Point,
    p2: Point,
    p3: Point,
}

impl TryFrom<[P; 3]> for Triangle
where
    P: TryInto,
    P::Error: Into>, // Allow flexible error types
{
    type Error = Box;

    fn try_from([p1, p2, p3]: [P; 3]) -> Result {
        Ok(Triangle {
            p1: p1.try_into().map_err(Into::into)?,
            p2: p2.try_into().map_err(Into::into)?,
            p3: p3.try_into().map_err(Into::into)?,
        })
    }
}

fn create_triangle() -> Result> {
    // Will succeed if all points are within bounds
    let t: Triangle = [(0, 0), (100, 100), (200, 200)].try_into()?;

    // Will fail if any point is out of bounds
    let t_fail: Triangle = [(0, 0), (2000, 2000), (200, 200)].try_into()?;

    Ok(t)
}

Automatic TryFrom for From Types

It’s worth noting that types implementing From automatically get a TryFrom implementation:

use std::convert::Infallible;

// This is how the standard library provides it
impl TryFrom for T
where
    T: From,
{
    type Error = Infallible; // The empty type that can't be instantiated

    fn try_from(value: U) -> Result {
        Ok(T::from(value))
    }
}

This means you can always use try_from or try_into even on types that implement From/Into, which can be useful for API consistency.

Best Practices for TryFrom/TryInto

Use meaningful error types - Custom error types help users understand why conversions failed
Document failure conditions - Make it clear when and why conversions might fail
Be consistent - If a type might reasonably have both fallible and infallible conversions, consider sticking with TryFrom for all conversions for consistency
Consider validation needs - Use these traits when input validation is a key part of the conversion process

FromStr

Core Concepts

FromStr is a specialized parsing trait for creating types from string slices. It’s one of Rust’s most commonly used traits due to its integration with the .parse() method on strings.

pub trait FromStr: Sized {
    type Err;
    fn from_str(s: &str) -> Result;
}

Key Characteristics

String-Specific: Designed specifically for parsing strings
Fallible: Returns a Result to handle parsing failures
Integrated: Works with the .parse() method on string types
Read-Only: Takes a borrowed &str and doesn’t modify the original

When to Use FromStr

Use FromStr when:

You need to parse a string into your type
The parsing might fail
You want to support the standard .parse() method

Example: Parsing a Point

Let’s implement FromStr for our Point type to parse strings like "(10, 20)":

use std::error;
use std::fmt;
use std::str::FromStr;

struct Point {
    x: i32,
    y: i32,
}

#[derive(Debug, PartialEq)]
struct ParsePointError;

impl fmt::Display for ParsePointError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "failed to parse point - expected format: (x, y)")
    }
}

impl error::Error for ParsePointError {}

impl From for ParsePointError {
    fn from(_: std::num::ParseIntError) -> Self {
        ParsePointError
    }
}

impl FromStr for Point {
    type Err = ParsePointError;

    fn from_str(s: &str) -> Result {
        // Remove whitespace and check format
        let s = s.trim();
        if !s.starts_with('(') || !s.ends_with(')') {
            return Err(ParsePointError);
        }

        // Extract the content between parentheses
        let inner = &s[1..s.len()-1];
        let mut parts = inner.split(',');

        // Get x and y values
        let x_str = parts.next().ok_or(ParsePointError)?.trim();
        let y_str = parts.next().ok_or(ParsePointError)?.trim();

        // Ensure no extra parts
        if parts.next().is_some() {
            return Err(ParsePointError);
        }

        // Parse into integers
        let x = x_str.parse::()?;
        let y = y_str.parse::()?;

        Ok(Point { x, y })
    }
}

fn example() -> Result<(), ParsePointError> {
    // Using from_str directly
    let p1 = Point::from_str("(10, 20)")?;

    // Using parse method (most idiomatic)
    let p2: Point = "(30, 40)".parse()?;

    // Invalid format
    let result = "(not a point)".parse::();
    assert_eq!(result, Err(ParsePointError));

    Ok(())
}

Relationship with TryFrom<&str>

FromStr shares a similar signature with TryFrom<&str>. It’s good practice to implement both when one is present, by having one delegate to the other:

use std::convert::TryFrom;

// Implement TryFrom<&str> by delegating to FromStr
impl TryFrom<&str> for Point {
    type Error = ::Err;

    fn try_from(s: &str) -> Result {
        Point::from_str(s)
    }
}

fn example() {
    // Now we can use both approaches
    let p1: Result = "(10, 20)".parse();
    let p2 = Point::try_from("(10, 20)");
}

Best Practices for FromStr

Focus on parsing - The trait is specifically for string parsing, so avoid other side effects
Be flexible with formats - Accept reasonable variations (spaces, capitalization) when possible
Provide useful error messages - Make it clear why parsing failed
Include examples in documentation - Show the exact string formats you accept
Implement TryFrom<&str> - For consistency, also implement TryFrom<&str> by delegating to your FromStr implementation

AsRef and AsMut

Core Concepts

AsRef and AsMut traits provide cheap reference-to-reference conversions. They’re primarily used for making functions more flexible about the types they accept.

pub trait AsRef {
    fn as_ref(&self) -> &T;
}

pub trait AsMut {
    fn as_mut(&mut self) -> &mut T;
}

The ?Sized bound allows these traits to be implemented for unsized types like slices.

Key Characteristics

References Only: Convert between reference types, not owned values
Cheap: Conversions should be inexpensive, often just a cast
Read/Write: AsRef provides read-only access, while AsMut allows modification
Type-Based: Multiple implementations may exist for a single type, differing by the target type

When to Use AsRef/AsMut

Use AsRef and AsMut when:

You want to abstract over similar types, like String and &str
You need flexible APIs that accept multiple types
You’re exposing an inner reference to a wrapped type
You need to convert between reference types cheaply

Example: Flexible String Functions

A common use case is to write functions that accept either String or &str:

// This function accepts both String and &str
fn calculate_length>(s: S) -> usize {
    s.as_ref().len()
}

fn example() {
    let owned = String::from("hello");
    let borrowed = "world";

    // Both work!
    println!("Length: {}", calculate_length(&owned));
    println!("Length: {}", calculate_length(borrowed));
    println!("Length: {}", calculate_length(owned));  // Takes ownership
}

Example: Exposing Inner References

AsRef is valuable when you have a wrapper type and want to provide access to its inner data:

struct EmailAddress {
    address: String,  // Private field with invariants
}

impl EmailAddress {
    fn new(address: String) -> Option {
        // Validate email format
        if is_valid_email(&address) {
            Some(EmailAddress { address })
        } else {
            None
        }
    }
}

// Allow accessing the inner string as a str
impl AsRef for EmailAddress {
    fn as_ref(&self) -> &str {
        &self.address
    }
}

fn is_valid_email(s: &str) -> bool {
    // Implementation omitted
    s.contains('@')
}

fn example() {
    let email = EmailAddress::new(String::from("user@example.com")).unwrap();

    // We can use it with any function accepting AsRef
    let length = calculate_length(&email);

    // We can get the &str directly
    let domain = email.as_ref().split('@').nth(1).unwrap();
}

The "IS-A" Relationship

AsRef is often used to express an "IS-A" relationship between types. When you have a type that can conceptually be treated as another type, AsRef makes this relationship explicit:

struct Human {
    health_points: u32,
}

// A Soldier IS-A Human with a weapon
struct Soldier {
    human: Human,
    weapon: String,
}

impl AsRef for Soldier {
    fn as_ref(&self) -> &Human {
        &self.human
    }
}

// A Knight IS-A Soldier with armor
struct Knight {
    soldier: Soldier,
    armor: String,
}

impl AsRef for Knight {
    fn as_ref(&self) -> &Soldier {
        &self.soldier
    }
}

// Knights can also be treated as Humans directly
impl AsRef for Knight {
    fn as_ref(&self) -> &Human {
        &self.soldier.human
    }
}

// Generic function that works with any Human-like type
fn heal>(entity: &T, amount: u32) {
    println!("Healing for {} points", amount);
    // In a real implementation, we would modify health_points here
}

fn example() {
    let human = Human { health_points: 100 };
    let soldier = Soldier { human: Human { health_points: 120 }, weapon: "Sword".into() };
    let knight = Knight {
        soldier: Soldier { human: Human { health_points: 150 }, weapon: "Lance".into() },
        armor: "Plate".into(),
    };

    // All these work because of our AsRef implementations
    heal(&human, 10);
    heal(&soldier, 10);
    heal(&knight, 10);
}

When Not to Use AsRef

AsRef is sometimes overused or used incorrectly. Here are some anti-patterns to avoid:

struct User {
    name: String,
    email: String,
    age: u32,
}

// INCORRECT: Using AsRef to extract fields
impl AsRef for User {
    fn as_ref(&self) -> &String {
        // Which field should we return? Not clear!
        &self.name
    }
}

// INCORRECT: Using AsRef for unrelated types
impl AsRef for User {
    fn as_ref(&self) -> &u32 {
        &self.age
    }
}

These implementations are problematic because:

They don’t represent true "IS-A" relationships
They create ambiguity (which string field does as_ref return?)
They lead to unintuitive behavior

Best Practices for AsRef/AsMut

Use for "IS-A" relationships - Implement when one type can be viewed as another
Keep conversions cheap - Avoid expensive computations in as_ref/as_mut
Be consistent - If implementing AsRef, consider implementing AsMut if mutability makes sense
Don’t overuse - Not every field deserves an AsRef implementation
Respect semantics - Don’t implement for conceptually unrelated types

Borrow and BorrowMut

Core Concepts

Borrow and BorrowMut are similar to AsRef and AsMut but with an additional semantic guarantee: the borrowed and borrowing types must behave equivalently with regard to equality, hashing, and ordering.

pub trait Borrow {
    fn borrow(&self) -> &Borrowed;
}

pub trait BorrowMut: Borrow {
    fn borrow_mut(&mut self) -> &mut Borrowed;
}

Key Characteristics

Stricter Than AsRef: Requires equivalent behavior for hashing and comparisons
References Only: Converts references, not owned values
Semantic Guarantee: Must preserve equality, hash, and ordering properties
Collections Focus: Primarily used in hash and tree-based collections

When to Use Borrow/BorrowMut

Use Borrow and BorrowMut when:

You need to lookup objects in collections using different but equivalent types
You’re implementing a hash-based or tree-based collection
You need to guarantee that borrowed and owned versions behave identically for comparisons

The HashMap/HashSet Use Case

The most common use case for Borrow is in hash maps and sets, allowing lookups with borrowed versions of keys:

use std::collections::HashMap;
use std::borrow::Borrow;
use std::hash::Hash;

fn example() {
    let mut map: HashMap = HashMap::new();

    // Insert with owned String keys
    map.insert(String::from("apple"), 1);
    map.insert(String::from("banana"), 2);
    map.insert(String::from("cherry"), 3);

    // Lookup with &str - works because String: Borrow
    let apple_value = map.get("apple");
    assert_eq!(apple_value, Some(&1));

    // How does this work? Because HashMap's get method is defined like:
    // fn get(&self, k: &Q) -> Option<&V>
    // where K: Borrow, Q: Hash + Eq
}

This works because the standard library implements Borrow for String, ensuring that a String and its borrowed &str form have the same hash value and equality behavior.

Visualizing the Difference between AsRef and Borrow

Here’s an example that demonstrates the semantic difference between AsRef and Borrow:

use std::borrow::Borrow;
use std::hash::{Hash, Hasher};
use std::collections::hash_map::DefaultHasher;

// Calculate the hash of a value
fn get_hash(t: &T) -> u64 {
    let mut hasher = DefaultHasher::new();
    t.hash(&mut hasher);
    hasher.finish()
}

// This type has different hash/eq behavior for different views
struct CustomString {
    data: String,
}

impl Hash for CustomString {
    fn hash(&self, state: &mut H) {
        // Custom hash implementation that differs from str's hash
        self.data.len().hash(state);
    }
}

impl PartialEq for CustomString {
    fn eq(&self, other: &Self) -> bool {
        self.data.len() == other.data.len()
    }
}

impl Eq for CustomString {}

// AsRef implementation - just returns a reference
impl AsRef for CustomString {
    fn as_ref(&self) -> &str {
        &self.data
    }
}

// We CANNOT implement Borrow because it would violate
// the semantic requirements - CustomString and str have
// different hash and equality behavior

fn example() {
    let s1 = CustomString { data: String::from("hello") };
    let s2 = CustomString { data: String::from("world") };

    // AsRef works fine
    let r1: &str = s1.as_ref();
    let r2: &str = s2.as_ref();

    // But hash values differ between CustomString and &str
    println!("CustomString hash: {}", get_hash(&s1));
    println!("str hash: {}", get_hash(&r1));

    // And equality behavior differs too
    println!("Same length, equal as CustomString: {}", s1 == CustomString { data: "hello2".into() });
    println!("Different content, not equal as str: {}", r1 == "hello2");

    // This is why we shouldn't implement Borrow for CustomString
}

Best Practices for Borrow/BorrowMut

Respect the semantic contract - Only implement Borrow if the borrowed type behaves identically for hash, eq, and ord operations
Use for collection lookups - The primary use case is enabling flexible lookups in hash and tree collections
Consider alternatives - If you don’t need the semantic guarantees, AsRef is usually sufficient
Delegate to standard impls - For custom wrapper types, delegate to the inner type’s implementation

ToOwned

Core Concepts

ToOwned generalizes the concept of cloning for borrowed types, allowing creation of owned values from arbitrary borrowed data.

pub trait ToOwned {
    type Owned: Borrow;
    fn to_owned(&self) -> Self::Owned;

    // Provided default implementation
    fn clone_into(&self, target: &mut Self::Owned) { ... }
}

Key Characteristics

Generalized Clone: Similar to Clone, but for borrowed-to-owned conversions
Associated Type: Specifies the owned type for a borrowed type
Reverse of Borrow: If T: Borrow, then U: ToOwned

Standard Library Use: Used for common pairs like str/String, Path/PathBuf

When to Use ToOwned

Use ToOwned when:

You need to convert borrowed types to owned types
You’re implementing a data structure that can exist in both borrowed and owned forms
You need more flexibility than the standard Clone trait

Common ToOwned Implementations

The standard library implements ToOwned for several common types:

// str -> String
impl ToOwned for str {
    type Owned = String;
    fn to_owned(&self) -> String {
        String::from(self)
    }
}

// [T] -> Vec
impl ToOwned for [T] {
    type Owned = Vec;
    fn to_owned(&self) -> Vec {
        self.to_vec()
    }
}

// Path -> PathBuf
impl ToOwned for Path {
    type Owned = PathBuf;
    fn to_owned(&self) -> PathBuf {
        self.to_path_buf()
    }
}

Example: Custom ToOwned Implementation

Let’s create a pair of types with a ToOwned relationship:

use std::borrow::Borrow;
use std::borrow::ToOwned;

#[derive(Debug)]
struct Name {
    first: String,
    last: String,
}

#[derive(Debug)]
struct NameRef<'a> {
    first: &'a str,
    last: &'a str,
}

// Name can be borrowed as NameRef
impl<'a> Borrow> for Name {
    fn borrow(&self) -> &NameRef<'a> {
        // Safety: This is safe because the lifetimes are guaranteed
        // to match and the representation is compatible.
        // In real code, you'd likely implement this differently.
        unsafe {
            &*(self as *const Name as *const NameRef<'a>)
        }
    }
}

// NameRef can be converted to owned Name
impl<'a> ToOwned for NameRef<'a> {
    type Owned = Name;

    fn to_owned(&self) -> Name {
        Name {
            first: self.first.to_owned(),
            last: self.last.to_owned(),
        }
    }
}

fn example() {
    // Create a borrowed version
    let name_ref = NameRef {
        first: "John",
        last: "Doe",
    };

    // Convert to owned using ToOwned
    let owned_name = name_ref.to_owned();

    println!("Borrowed: {:?}", name_ref);
    println!("Owned: {:?}", owned_name);
}

Best Practices for ToOwned

Implement with Borrow - ToOwned and Borrow should be implemented as pairs
Consider performance - The to_owned method will likely allocate memory, so document performance characteristics
Use for borrowed/owned pairs - This trait is most appropriate when you have distinct borrowed and owned types
Provide clone_into when beneficial - Override the default implementation when you can implement it more efficiently

Conversion Traits in Practice

Now that we’ve covered each conversion trait individually, let’s explore some practical patterns and considerations for using them effectively.

Choosing the Right Trait

To select the appropriate conversion trait, consider these questions:

Is the conversion fallible?
- Yes → TryFrom/TryInto or FromStr (for strings)
- No → From/Into
Are you converting between references or values?
- References → AsRef/AsMut or Borrow/BorrowMut
- Values → From/Into or TryFrom/TryInto
Do you need to preserve hash/equality behavior?
- Yes → Borrow/BorrowMut
- No → AsRef/AsMut
Are you creating an owned value from a borrowed one?
- Yes → ToOwned
- No → Other traits

Composing Conversions

Rust’s conversion traits work well together, allowing you to build flexible and composable APIs:

// A function that accepts anything convertible to a Point
fn distance_from_origin(point: P) -> f64
where
    P: Into,
{
    let point = point.into();
    ((point.x.pow(2) + point.y.pow(2)) as f64).sqrt()
}

// A function that accepts anything convertible to a &str
fn find_pattern>(text: S, pattern: S) -> bool {
    text.as_ref().contains(pattern.as_ref())
}

// A function that tries to parse a value from a string-like input
fn parse_value(input: S) -> Result
where
    S: AsRef,
    T: FromStr,
{
    input.as_ref().parse::()
}

Generic API Design Pattern

One powerful pattern is to design APIs that accept the most general form of input:

struct Config {
    database_url: String,
    port: u16,
    allowed_origins: Vec,
    // other fields...
}

impl Config {
    // This constructor accepts flexible inputs for all string fields
    pub fn new(database_url: S1, port: u16, origins: I) -> Self
    where
        S1: Into,
        S2: Into,
        I: IntoIterator,
    {
        Config {
            database_url: database_url.into(),
            port,
            allowed_origins: origins.into_iter().map(Into::into).collect(),
        }
    }
}

fn example() {
    // Works with various combinations of strings
    let config = Config::new(
        "postgres://localhost/db",  // &str
        8080,
        vec!["http://localhost:3000", String::from("https://example.com")]
    );
}

Common Pitfalls and Solutions

1. Trait Bounds Too Restrictive

// Too restrictive - requires exactly String
fn bad_function(s: String) {
    // ...
}

// Better - accepts anything convertible to String
fn better_function>(s: S) {
    let s = s.into();
    // ...
}

// Also good - doesn't take ownership if not needed
fn best_function>(s: S) {
    let s = s.as_ref();
    // ...
}

2. Unnecessary Conversions

// Inefficient - converts to String when &str would work
fn tokenize>(s: S) -> Vec {
    let s = s.into();  // Potentially unnecessary allocation
    s.split_whitespace().map(|s| s.to_string()).collect()
}

// Better - uses AsRef to avoid unnecessary conversion
fn tokenize_better>(s: S) -> Vec {
    s.as_ref().split_whitespace().map(|s| s.to_string()).collect()
}

3. Missing Error Context

// Loses context about which field failed
fn parse_config>(
    name: S,
    value: S,
) -> Result {
    let name = name.as_ref();
    let value = value.as_ref();

    let port: u16 = value.parse()?;  // Which field caused this error?
    let timeout: u64 = value.parse()?;

    // ...
}

// Better - preserves context
enum FieldError {
    Port(std::num::ParseIntError),
    Timeout(std::num::ParseIntError),
    // ...
}

fn parse_config_better>(
    name: S,
    value: S,
) -> Result {
    let name = name.as_ref();
    let value = value.as_ref();

    let port: u16 = value.parse().map_err(FieldError::Port)?;
    let timeout: u64 = value.parse().map_err(FieldError::Timeout)?;

    // ...
}

Trait Coherence and the Orphan Rule

When working with conversion traits, you’ll encounter Rust’s "orphan rule," which prevents you from implementing external traits for external types. This affects how you can implement conversion traits:

// OK: Implementing From for std::path::PathBuf
struct MyType(String);
impl From for std::path::PathBuf {
    fn from(mt: MyType) -> Self {
        PathBuf::from(mt.0)
    }
}

// ERROR: Cannot implement std::convert::From for MyType
// because both types are defined outside your crate
impl From for MyType {
    fn from(path: std::path::PathBuf) -> Self {
        MyType(path.to_string_lossy().into_owned())
    }
}

Workarounds for the orphan rule:

Use a newtype wrapper - Wrap the external type in your own type
Use extension traits - Create your own trait that extends the functionality
Use TryFrom instead of From - Sometimes this can avoid coherence issues due to different associated types

Conclusion

Rust’s conversion traits provide a rich, flexible system for handling type conversions in a way that’s both safe and expressive. By understanding the distinctions between these traits and their intended use cases, you can design APIs that are both ergonomic and idiomatic.

Key takeaways:

Use From/Into for infallible value conversions
Use TryFrom/TryInto for fallible value conversions
Use FromStr for parsing from string representations
Use AsRef/AsMut for cheap reference conversions
Use Borrow/BorrowMut when hash and equality semantics matter
Use ToOwned for borrowed-to-owned conversions

These traits form the backbone of Rust’s approach to interoperability between different types, enabling code that is both flexible and type-safe. By following the patterns and best practices outlined in this article, you’ll be able to leverage these traits effectively in your own Rust programs.

Authentication with Axum

2025-05-03T00:00:00+00:00

Consider this scenario: you’re building a website that has a classic navbar at the top, this navbar has a button that reflects the user authentication status, showing a "Profile" button if the user is authenticated and showing a "Login" button in case the user is unauthenticated.

This is a very common scenario, let’s sketch something quick using axum and askama.





    {% block title %}{% endblock %}
    
    
    {% block head %}{% endblock %}


    
        
            
                {% if ctx.authed %}
                    Profile
                {% else %}
                    Login
                {% endif %}
            
        
    
    {% block content %}
    {% endblock %}

This will be our layout.jinja file that we can build upon. The template above would be served by an endpoint that looks like the following

#[derive(Debug, Default)]
pub struct Context {
    authed: bool,
}

#[derive(Template)]
#[templage = "layout.jinja"]
struct HomeTemplate {
    ctx: Context
};

pub async fn home() -> impl IntoResponse {
    HtmlTemplate(
        HomeTemplate { ctx: Context::default() }
    ).into_response()
}

We have something to work with, all is missing is a way derive a Context from a user’s HTTP request.

I’d argue the simplest way to handle user authentication if you’re doing SSR is using cookies. Cookies are a cornerstone of backend authentication because they’re reliable, browser-managed, and can be hardened with specific attributes to mitigate common security risks. Here’s why:

HttpOnly Attribute: Prevents client-side JavaScript from accessing the cookie, neutralizing XSS attacks. If an attacker injects malicious scripts, they can’t steal your session cookie.
Secure Attribute: Ensures the cookie is only sent over HTTPS, protecting it from interception on insecure networks (e.g., public Wi-Fi).
SameSite Attribute: Mitigates CSRF (Cross-Site Request Forgery) by controlling when cookies are sent in cross-origin requests. SameSite=Strict blocks cookies in requests from external sites, while SameSite=Lax allows safe methods like GET.
Expiration and Domain/Path Scoping: Cookies can be set to expire after a session or a fixed time, reducing the window for misuse. Scoping to specific domains and paths (e.g., domain=api.example.com, path=/auth) limits their exposure.
Signed Cookies: Frameworks often support signing cookies with a secret key, ensuring they haven’t been tampered with on the client side.

This is a typical reponse that uses the Set-Cookies header to instruct the browser to set those cookies

HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: session=xyz123; HttpOnly; Secure; SameSite=Strict; Max-Age=86400; Path=/; Domain=api.example.com

When configured correctly, cookies are a fortress for storing session IDs, JWTs, or other authentication tokens in SSR apps. They’re automatically sent by the browser with every request, simplifying server-side validation compared to managing tokens in localStorage or HTTP headers.

Axum provides a cool axum-extra crate that makes it easy to work with them. That crate contains a very useful extractor called CookieJar that exposes a very minimal interface to .add and .remove cookies for a user. This is the utility function I use to generate a default cookie

pub(crate) fn default_cookie<'a>(
    key: &str,
    token: String,
    duration_hrs: i64
) -> Cookie<'a> {
    Cookie::build((key.to_string(), token))
        .path("/")
        .http_only(true)
        .max_age(Duration::hours(duration_hrs))
        .secure(if cfg!(debug_assertions) {
            // Safari won't allow secure cookies
            // coming from localhost in debug mode
            false
        } else {
            // Secure cookies in release mode
            true
        })
        .build()
}

I won’t get sucked into the session ID vs. JWT argument, but honestly, using JWTs in cookies is a win because you don’t have to fuss with storing session data on the server.

Jwt are usually very short-lived, they shouldn’t last for long periods of time and they must be renewed frequently for security purposes. For that reason you usually issue two different cookies:

jwt: short-lived token containing information about a user in json format, signed with a secret key so you know you were the one who issued it
refresh token: a longer-lived token with which you can request new jwts

Now that we’ve covered the cookies and jwt basics, let’s start by implementing a standard login endpoint with which users can be given these two cookies.

#[derive(Debug)]
struct LoginData {
    username: String,
    password: String
}

pub async fn login(
    State(app): State,
    jar: CookieJar, // CookieJar is available in axum_extras
    Form(LoginData { username, password }): Form
) -> impl IntoResponse {
    // dummy function to get a user
    let user = match db::user::get(&app.pg_pool, &username, &password).await {
        None => return Redirect::to("/signup").into_response()
        Some(user) => user
    };

    // get/create a refresh token for the user
    let refresh_token = match db::refresh_tokens::create(user.id).await {
        Ok(token) => token,
        Err(_) => {
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                "Somethign bad happened, try again later"
            ).into_response();
        }
    };

    let claims = Claims::with(user.email, user.id);
    match jwt::generate_jwt(app.jwt_signing_key.as_bytes(), claims) {
        Ok(token) => (
            [("hx-redirect", "/")],
            jar.add(default_cookie("jwt", token, 1)).add(default_cookie(
                "refresh",
                refresh_token,
                30 * 24,
            ),
        )
            .into_response()),
        Err(_) => {
            return (
                StatusCode::INTERNAL_SERVER_ERROR,
                "Somethign bad happened, try again later"
            ).into_response();
        }
    }
}

This login endpoint will receive a request with some form data that contain a username and a password. First thing you usually have to do is check if the user exists in your database, otherwise you’ll kindly 302 to a signup page where he/she has to register, returning a message to show in the login form sometimes works as well - whatever suits you.

Once you know the user exists you need to create a refresh token. It usually makes sense to implement refresh_token::create so that it returns a valid non-expired refresh token stored in your database associated with the user before creating a new one. This is because users can delete cookies and/or users can authenticate with different devices and you don’t want to create a refresh token each time.

When you get your refresh token back you’re ready to move on and handle the last part of the process, which is generating the jwt and returning a valid response to the user that will set those cookies.

Ignore `hx-redirect` header for now, this was a snippet of code that I had laying around on github. Also, note that the responses I return in case of errors are not very exhaustive for most scenarios, I'm conciously leaving out the details because it's not the focus of this blog post.

If login is successful the user will be redirected to the homepage at / and will trigger the home endpoint again but his navbar will still show the login button because we’re using Context::default(). Let’s change that with our first approach using Axum extractors.

When I first started using Axum I really liked the idea of Extractors, if you’ve used the framework you’re probably familiar with them (i.e Json, Form etc.). Everything that implements FromRequest or FromRequestParts (and the Option alternative since Axum 0.8!) can be considered an extractor and can be used in the function signature to get something out of a request.

In our case, we would like to get some user data out of a request (cookies are always sent with an HTTP request), in particular we can create a custom extractor that tries to extract our user data from the jwt token in the user’s request, if present. Let’s implement CookieJwt which we’re going to use to get that information out of requests that reaches our endpoints.

/// Basic claims that a classic jwt contain
#[derive(Debug, Serialize, Deserialize)]
pub struct Claims {
    pub sub: String,
    pub exp: usize,
    pub user_id: uuid::Uuid,
}

/// A flexible extractor that tries
/// to get a type `T` from a request cookie
#[derive(Debug, PartialEq, Eq, Clone)]
pub struct CookieJwt(pub T);

// since axum 0.8 you can implement extractors meant to be Option
// this is very useful, expecially for scenarios where endpoint can be accessed
// both by authed users and non-authed users
impl OptionalFromRequestParts for CookieJwt
where
    AppState: FromRef,
    S: Send + Sync,
    T: DeserializeOwned,
{
    type Rejection = Redirect;

    async fn from_request_parts(
        req: &mut Parts,
        state: &S,
    ) -> Result, Self::Rejection> {
        let jar = CookieJar::from_headers(&req.headers);
        if let Some(jwt) = jar.get("jwt").map(|c| c.value()) {
            return match validate_jwt::(JWT_SIGNING_KEY, jwt) {
                Ok(data) => return Ok(Some(CookieJwt(data))),
                // user tampered with cookie here, we want to delete that cookie
                // returning None here would have been okay too if you're okay with
                // manufactured cookies :)
                Err(_) => Err(Redirect::to("/logout")),
            };
        }

        // if refresh token is present, try and get a new jwt
        // by redirecting user to /refresh_token endpoint
        if jar.get("refresh").is_some() {
            return Err(Redirect::to(
                format!("/refresh_token?next={}", req.uri).as_str(),
            ));
        }

        // at this point, user has no jwt and no refresh token
        Ok(None)
    }
}

And we can use our brand new extractor in our home function

pub async fn home(jwt: Option>) -> impl IntoResponse { HtmlTemplate( HomeTemplate { ctx: Context { authed: jwt.is_some() } } ).into_response() }

Now each time try and navigate to / the extractor is going to peek into your request and look for jwt and refresh cookies, if jwt is found and can be decoded to Claims then jwt: Option<_> is going to contain Some(jwt) data and our user will see the "Profile" button in his navbar, indicating he’s correctly logged in. If neither of the cookies is found then the user will be returned the classic navbar with the option to "Login". If however jwt can’t be found but a refresh cookie is present we can still do something for the user and get him a proper jwt.

Indeed, the logic implemented above will redirect the user to /refresh_token along with a query parameter indicating where the user was previously navigating to. This way we’re not distrupting the original user’s intent and everything is going to happen in a quick succession of requests. How does our /refresh_token endpoint look like?

#[derive(Debug, Deserialize)] pub struct RefreshTokenQuery { next: Option, } pub async fn refresh_token( State(app): State, jar: CookieJar, Query(RefreshTokenQuery { next }): Query, ) -> impl IntoResponse { let token = match jar.get("refresh") { Some(token) => token, None => { // if there's no token then the user goes back to /login return Redirect::to("/login").into_response(); } }; // if something goes wrong here we remove the token, otherwise the user could end up // in a loop where he's constantly being redirected here and this function fails every time let user = match db::refresh_tokens::get_user(&app.pg_pool, token.value()).await { Ok(Some(user)) => user, _ => { return (jar.remove(Cookie::from("refresh")), Redirect::to("/login")).into_response(); } }; // set new jwt let claims = Claims::with(user.email, user.id); match jwt::generate_jwt(app.jwt_signing_key.as_bytes(), claims) { Ok(token) => ( jar.add(default_cookie("jwt", token, 1)), Redirect::to(&next.unwrap_or("/".to_owned())), ) .into_response(), Err(_) => { (jar.remove(Cookie::from("refresh")), Redirect::to("/login")).into_response() } } }

Nothing surprising here, our refresh token endpoint is going to check that the refresh cookie is part of the request and if it is it will try to ask the db to return the user information associated to that refresh token. Once the information is retrieved it re-generates the valid jwt and redirect the user to his previous url next, if present.

Even though it is a great starting point and has worked very well for me, it’s not flawless:

It doesn’t feel right: handling authentication logic in an extractor doesn’t feel quite right.

It’s not flexible for more complex authentication scenarios i.e restricting some endpoints to users with a specific role.

If a user sends a POST request that has a body attached to it the /refresh_token redirect will break that flow because almost every browser won’t expect a 302 redirect to have a body.

If you’re a backend developer, authentication screams middleware. To level up the cookie-based authentication we’ve discussed, authentication middleware offers a cleaner, reusable way to validate cookies and secure routes.

Axum gives you quite a few options when you want to implement a middleware. You don’t have to give up on the granularity that extractor provided because axum middleware can be applied at the app level down to the individual route level.

Axum allows you to add middleware just about anywhere

The easiest way to implement an Axum middleware is to create a function that matches the axum::middleware::from_fn (or axum::middleware::from_fn_with_sate if you need State) function. The requirements are pretty straightfoward:

Be an async fn.

Take zero or more FromRequestParts extractors.

Take exactly one FromRequest extractor as the second to last argument.

Take Next as the last argument.

Return something that implements IntoResponse.

With that in mind, let’s try and create our authentication middleware.

/// Middleware that handles both authenticated and unauthenticated requests. /// /// This middleware performs JWT-based authentication by checking for `jwt` and `refresh` cookies. /// It establishes a [`UserContext`] that flows through the request chain and manages cookie updates. /// /// # Behavior /// - **JWT Present**: Validates the JWT and extracts user claims if successful. /// - Invalid JWT: Clears auth cookies (potential tampering) /// - **No JWT but Refresh Token Present**: /// - Attempts to refresh the token and issue a new JWT /// - On success: Sets new cookies and establishes authenticated context /// - **No Auth Cookies**: Proceeds with default unauthenticated context /// /// # Cookie Management /// - Automatically removes suspicious/invalid auth cookies /// - Adds new JWT cookies when refresh is successful /// - Propagates all cookie changes in the response pub async fn base( State(app): State, mut request: Request, next: Next, ) -> impl IntoResponse { let mut jar = CookieJar::from_headers(request.headers()); let jwt = jar.get("jwt"); let refresh = jar.get("refresh"); // Default context for unauthenticated requests let mut context = UserContext { user_id: None, is_admin: false, }; // JWT takes precedence if present if let Some(jwt) = jwt { match validate_jwt::(JWT_SIGNING_KEY, jwt.value()) { Ok(claims) => { context.user_id = Some(claims.user_id); } Err(_) => { // Clear potentially compromised cookies jar = jar.remove("jwt").remove("refresh"); } } } // Fall back to refresh token if JWT is absent/invalid else if let Some(refresh) = refresh { if let Ok(Some(user)) = db::refresh_tokens::get_user(&app.pg_pool, refresh.value()).await { let claims = Claims::with(user.email, user.uuid); if let Ok(jwt) = generate_jwt(app.jwt_signing_key.as_bytes(), claims) { context.user_id = Some(user.uuid); jar = jar.add(default_cookie("jwt", jwt, 1)); } // Note: JWT generation errors are intentionally swallowed here // to prevent refresh token from being invalidated due to // temporary JWT generation issues } } // Inject the resolved context into request extensions request.extensions_mut().insert(context); let response = next.run(request).await; // Merge cookie updates with the response (jar, response).into_response() }

The middleware we’ve built takes the same core idea as our initial extractor but makes it far more powerful. Unlike a simple extractor, middleware can intercept and modify responses and modify it as needed. This enables us to do much more interesting things.

First of all, the middleware initializes the UserContext with some default values that an un-authenticated users will reflect. After that, it goes through the first authentication step which tries to look for a valid jwt token in the request’s cookies, if it finds one it updates the UserContext accordingly with the data decoded from the jwt. If a jwt token is not found, it falls back to the refresh token and uses it to generate a valid jwt for the user and updates the UserContext accordingly. The authentication part of middleware is now complete and the UserContext is passed along with the request so that handlers can make use of it. But we’re not done yet! The middleware will wait for the response returned by whatever we have running in next.run(_) and does something pretty cool: in case the request wasn’t originally authenticated (did not have a jwt attached) it sends back with the response new a new cookie containing the generated jwt.

This last part is very cool for different reasons:

Silent Authentication: Requests that come in un-authenticated will be treated as authenticated (if refresh is present!) because we do the heavy lifting of generating the jwt in the middleware.

Works with all request types: whatever the request was (POST, PUT, GET etc.), the middleware won’t distrupt the flow and the user will get back a fresh jwt if he’s missing one.

Simplified Architecture: with this middleware we don’t need extra round trips to authenticate the user, therefore we can also get rid of the /refresh_token endpoint.

Our new home endpoint now would end up looking like this

pub async fn home(Extension(usr_ctx): Extension) -> impl IntoResponse { HtmlTemplate( HomeTemplate { ctx: Context { authed: usr_ctx.user_id.is_some() } } ).into_response() }

Nothing is stopping us from generating a Context directly in the middleware, that would actually be a better approach here so that we can pop it in directly in the template

pub async fn home(Extension(ctx): Extension) -> impl IntoResponse { HtmlTemplate(HomeTemplate { ctx }).into_response() }

We’re not done yet - one last cool thing that you can do with middlewares is stack them on top of each other and have multiple layers of logic to protect different parts of your backend, just like an onion.

Let’s consider the scenario where you want some parts of your application to be public, some others to be for authenticated only users and then you have a very special dashboard that only super admins can access. You can leverage middlewares to implement all of those protection layers

/// middleware that requires the user to be authenticated pub async fn required_auth( Extension(context): Extension, request: Request, next: Next ) -> impl IntoResponse { if context.user_id.is_none() { return Redirect::to("/login").into_response(); } next.run(request).await } /// middleware that requires the user to be authenticated pub async fn required_admin( Extension(context): Extension, request: Request, next: Next, ) -> impl IntoResponse { if !context.is_admin { return Redirect::to("/").into_response(); } next.run(request).await }

If you remember correctly, middlewares can have zero or more FromRequestParts in its signature, which means you can use as many extractors as you want to and Extension is an extractor too! This means you can re-use something that the previous middleware computed in the following middlewares. The only thing you have to pay attention to in this case is to apply the middlewares in the correct order. This is a pretty good look of how middlewares work in Axum

+-----------------------+ | Requests | +-----------------------+ | v +-----------------------+ | Layer Three | | +-----------------+ | | | Layer Two | | | | +-----------+ | | | | | Layer One | | | | | | +---+ | | | | | | | H | | | | | | | | a | | | | | | | | n | | | | | | | | d | | | | | | | | l | | | | | | | | e | | | | | | | | r | | | | | | | +---+ | | | | | +-----------+ | | | +-----------------+ | +-----------------------+ | v +-----------------------+ | Responses | +-----------------------+

It really is like an onion after all

let app = Router::new() .route("/admin", get(admin::get)) // only admins can access the routes above .layer( middleware::from_fn_with_state(state.clone(), required_admin) ) .route("/profile", get(profile::get)) // routes above will need to be authenticated .layer( middleware::from_fn_with_state(state.clone(), required_auth) ) .route("/", get(home)) // most external layer, will provide // `Extension` to all the routes above .layer( middleware::from_fn_with_state(state.clone(), base) );

For better readability you can also create different routers with different layers and finally merge them together into the main app’s router.

let admin = Router::new() .route("/admin", get(handler)) .layer( middleware::from_fn_with_state(state.clone(), required_admin) ); let protected = Router::new() .route("/profile") .layer( middleware::from_fn_with_state(state.clone(), required_auth) ); let public = Router::new() .route("/"); let app = Router::new() .merge(public) .merge(protected) .merge(admin); .layer( middleware::from_fn_with_state(state.clone(), base) )

I’ve been playing with middlewares for a while now in Axum and I feel they provide a much better option for this scenario than creative alternatives like the one I’ve talked about initially. Axum provides much more powerful features for middlewares if you need it, but I still haven’t delved into those that much because there was no need for me to do it, I almost always can get stuff done with the simple middleware::from_fn_with_sate function. You should give them a try!

Rust Books That I Read

2024-10-01T00:00:00+00:00

Title

Desc

精通 Rust（第2版）

Done

Black Hat Rust

34%

Code Like a Pro in Rust

Done

Learn Rust in a Month of Lunches

Done

Rust in Action

1%

Rust Servers Services and Apps

4%

Rust Web Development

41%

Mastering Rust Programming

26%

Command-Line Rust

Done

Programming Rust

Done

Rust Atomics

15%

Programming with Rust

15%

Rust for the IoT

9%

The Rust Programming Language

Done

Zero To Production In Rust

Done

Ultimate Rust for Systems Programming

39%

深入浅出 Rust

Done

Rust 权威指南

Done

Environment Variables & Rust

2024-03-07T00:00:00+00:00

If you’ve ever worked on some kind of project you definitley have encountered the need to declare some environment variables for it.

Environment variables are an easy way to setup essential parameters that your program is going to use at runtime, i.e database URL, tracing level, production or local environment.

In Rust you have multiple ways to make use of them

use axum::{response::Html, routing::get, Router}; #[tokio::main] async fn main() { // let's get our database let db_connection_str = std::env::var("DATABASE_URL") .expect("cannot find DATABASE_URL env"); let pool = PgPoolOptions::new() .max_connections(5) .acquire_timeout(Duration::from_secs(3)) .connect(&db_connection_str) .await .expect("can't connect to database"); let app = Router::new().route("/", get(handler)).with_state(pool); let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") .await .unwrap(); println!("listening on {}", listener.local_addr().unwrap()); axum::serve(listener, app).await.unwrap(); } async fn handler() -> Html<&'static str> { Html("Hello, World!") }

With the example above, the program expects to find DATABASE_URL in the process environment variables. To make it work you’d have to run

$ export DATABASE_URL="postgres://postgres:password@localhost" $ cargo run

Or you could use a simple one liner

DATABASE_URL="postgres://postgres:password@localhost" cargo run

Both of these will run the program okay, but there are some issues you might want to look out for:

The command/s above are now stored in your ~/.[zsh|bash|fish]_history file now, in plaintext, and that’s bad, especially when you type out the production database password

You have to type that everytime you are in a new shell session, that’s especially bad if you have a terrible shell config without autocompletion and suggestions (please, do yourself a favor and fix that)

Come on... everybody uses .env files nowadays!

I know, I know, you already know all that, it’s basic software dev stuff after all.

In order to not leak sensitive data, we can use a .env file in the project’s folder (I’ll talk about how I F-up with those files one day). There’s a pretty common crate in Rust to read environment variables at runtime and that’s dotenv.

dotenv will check if you have a .env file in your project’s folder and load the env variables in there for you. Here’s how the whole thing would look like:

$ cat .env DATABASE_URL="postgres://postgres:password@localhost"

use dotenv::dotenv; use axum::{response::Html, routing::get, Router}; #[tokio::main] async fn main() { // load environments from .env dotenv().ok(); // let's get our database let db_connection_str = std::env::var("DATABASE_URL") .expect("cannot find DATABASE_URL env"); let pool = PgPoolOptions::new() .max_connections(5) .acquire_timeout(Duration::from_secs(3)) .connect(&db_connection_str) .await .expect("can't connect to database"); let app = Router::new().route("/", get(handler)).with_state(pool); let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") .await .unwrap(); println!("listening on {}", listener.local_addr().unwrap()); axum::serve(listener, app).await.unwrap(); } async fn handler() -> Html<&'static str> { Html("Hello, World!") }

I see dotenv used all over the place, but there’s another way to achieve the same without the .env file.

Since Cargo 1.56 you can use configurable-env

The [env] section allows you to set additional environment variables for build scripts, rustc invocations, cargo run and cargo build.

I prefer this method to the dotenv one because it does pretty much the same and the environment variables are set by cargo itself instead of the program runtime. Also, most of my deployments don’t have a .env file to parse, but I just set environment variables in the container itself or in the parent process and this approach better simulates that kind of setup.

Let’s get rid of dotenv and use .cargo/config.toml

$ rm .env $ cat .cargo/config.toml [env] DATABASE_URL="postgres://postgres:password@localhost"

use axum::{response::Html, routing::get, Router}; #[tokio::main] async fn main() { // it's the same as the first iteration, if you don't find // differences it's because there's none :) // let's get our database let db_connection_str = std::env::var("DATABASE_URL") .expect("cannot find DATABASE_URL env"); let pool = PgPoolOptions::new() .max_connections(5) .acquire_timeout(Duration::from_secs(3)) .connect(&db_connection_str) .await .expect("can't connect to database"); let app = Router::new().route("/", get(handler)).with_state(pool); let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") .await .unwrap(); println!("listening on {}", listener.local_addr().unwrap()); axum::serve(listener, app).await.unwrap(); } async fn handler() -> Html<&'static str> { Html("Hello, World!") }

Much neater, and we removed a crate from the project dependencies. But we’re not done yet, there’s another scenario that we’ve not yet talked about.

Up until now we’ve only covered environment variables that won’t change frequently, that is the reason why we can easily create a file and write them there and we’d be okay forever. What if we need environment variables that need to change very frequently? Or that depend on complex logic? Or some command?

It’s common in a lot of open source programs to see their commit hash somewhere to indicate that the version that you’re currently using is the one that has that HEAD commit. How would you do that in Rust?

Well, turns out that it’s easily achievable with the build.rs file.

Placing a file named build.rs in the root of a package will cause Cargo to compile that script and execute it just before building the package.

Within build.rs we can provide whatever environment variable we want to the rustc compiler by using println!("cargo:rustc-env=…"), that way we can expose that value into our project at compiletime.

// [build.rs] fn main() { set_revision_hash(); } // pass the result of `git rev-parse --short=10 HEAD` to rustc fn set_revision_hash() { use std::process::Command; let args = &["rev-parse", "--short=10", "HEAD"]; let Ok(output) = Command::new("git").args(args).output() else { return; }; let rev = String::from_utf8_lossy(&output.stdout).trim().to_string(); if rev.is_empty() { return; } println!("cargo:rustc-env=BUILD_GIT_HASH={}", rev); }

With that in place we can make use BUILD_GIT_HASH in our program

use axum::{response::Html, routing::get, Router}; #[tokio::main] async fn main() { // let's get our database let db_connection_str = std::env::var("DATABASE_URL") .expect("cannot find DATABASE_URL env"); let pool = PgPoolOptions::new() .max_connections(5) .acquire_timeout(Duration::from_secs(3)) .connect(&db_connection_str) .await .expect("can't connect to database"); let app = Router::new() .route("/", get(handler)) // here we can now take that environment // at compiletime with env!() .route("/_meta", get(|| async { env!("BUILD_GIT_HASH") })) .with_state(pool); let listener = tokio::net::TcpListener::bind("127.0.0.1:3000") .await .unwrap(); println!("listening on {}", listener.local_addr().unwrap()); axum::serve(listener, app).await.unwrap(); } async fn handler() -> Html<&'static str> { Html("Welcome!") }

Notice that this time I’ve used the env! macro, which takes environment variables at compiletime and not at runtime, big difference there!

I’m sure there are other infinite ways to do what I’ve explained above, but these are the ones that I’ve seen used the most.

To be fair, I’ve been a dotenv guy for quite some time when I first started with Rust, but I’ve discovered the .cargo/config.toml alternative recently even though it’s been around for a long time, so I hope it’s something new for you too.