rust-domain-boundaries

Rust Domain Boundaries

Use this skill to keep invalid states out of Rust service internals. Parse raw

input once at the boundary, store validated values in narrow domain types, and

make unchecked construction difficult.

Core Workflow

1. Find raw input boundaries: HTTP payloads, path/query parameters, config

files, environment variables, database rows, queues, and CLI flags.

1. Separate transport DTOs from domain types. Let serde deserialize incoming

shapes, then convert DTO fields into validated domain values.

1. Replace primitive strings with small types for ruled values: email addresses,

usernames, passwords, subscriber names, slugs, tenant IDs, idempotency keys,

and money-like or duration-like values.

1. Give domain types private fields and smart constructors. Avoid unchecked

pub fields or impl From<String> for fallible conversions.

1. Return typed validation errors that map to useful HTTP responses without

leaking internal details.

1. Keep database and external API mapping explicit. Convert to raw strings at

the final persistence or serialization edge.

1. Test invariants directly. Cover valid examples, malformed inputs, boundary

lengths, normalization rules, and round trips.

Type Design Rules

• Prefer TryFrom<String>, TryFrom<&str>, or FromStr for fallible parsing.
• Keep stored values owned unless profiling proves borrowing is necessary.
• Implement AsRef<str> or a named accessor for read-only exposure.
• Implement Display only when the formatted value is safe to show in logs,

errors, and UI.

• Avoid deriving Debug for secret-bearing values unless the debug output is

redacted.

• Make normalization visible in tests: trim, lowercase, Unicode handling, and

canonicalization.

Request Boundary Pattern

Deserialize into a request shape, then construct a command:

#[derive(serde::Deserialize)]
pub struct SubscribeRequest {
    email: String,
    name: String,
}

pub struct SubscribeCommand {
    pub email: EmailAddress,
    pub name: SubscriberName,
}

impl TryFrom<SubscribeRequest> for SubscribeCommand {
    type Error = SubscribeValidationError;

    fn try_from(value: SubscribeRequest) -> Result<Self, Self::Error> {
        Ok(Self {
            email: EmailAddress::parse(value.email)?,
            name: SubscriberName::parse(value.name)?,
        })
    }
}

Handlers should reject invalid input before business logic or database code. If

validation needs database state, keep pure parsing separate from uniqueness or

authorization checks.

Tests

Read references/property-testing.md when invariants have many edge cases or

when an AI agent is likely to miss invalid inputs with example-only tests.

Minimum tests for a new domain type:

• Accept a realistic valid value.
• Reject empty input and whitespace-only input.
• Reject too-long input when storage or product rules impose limits.
• Reject format violations.
• Preserve or normalize exactly as documented by tests.
• Round-trip through serde or SQL mapping when that type crosses those

boundaries.

Reference Files

• references/newtype-patterns.md: constructor, trait, serde, and persistence

patterns for Rust newtypes.

• references/property-testing.md: property-testing strategy for parsers and

domain constructors.