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.
2. Separate transport DTOs from domain types. Let serde deserialize incoming shapes, then convert DTO fields into validated domain values.
3. 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.
4. Give domain types private fields and smart constructors. Avoid unchecked pub fields or impl From<String> for fallible conversions.
5. Return typed validation errors that map to useful HTTP responses without leaking internal details.
6. Keep database and external API mapping explicit. Convert to raw strings at the final persistence or serialization edge.
7. 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.