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
- Find raw input boundaries: HTTP payloads, path/query parameters, config
files, environment variables, database rows, queues, and CLI flags.
- Separate transport DTOs from domain types. Let
serde deserialize incoming
shapes, then convert DTO fields into validated domain values.
- 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.
- Give domain types private fields and smart constructors. Avoid unchecked
pub fields or impl From<String> for fallible conversions.
- Return typed validation errors that map to useful HTTP responses without
leaking internal details.
- Keep database and external API mapping explicit. Convert to raw strings at
the final persistence or serialization edge.
- 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.
1---2name: rust-domain-boundaries3description: Use when modeling, validating, refactoring, or reviewing Rust service domain boundaries, especially when replacing primitive String fields with newtypes, parse-don't-validate constructors, private invariants, TryFrom/FromStr parsers, request DTO boundaries, or property tests.4license: MIT5compatibility: Codex, Claude Code, and other Agent Skills-compatible clients.6metadata:7 source: https://skillmd.com/skills/hashgraph-online/rust-domain-boundaries8 version: "0.1.0"9 displayName: Rust Domain Boundaries10 category: Rust11 tags: rust,domain-modeling,newtypes,validation,property-testing12---1314# Rust Domain Boundaries1516Use this skill to keep invalid states out of Rust service internals. Parse raw17input once at the boundary, store validated values in narrow domain types, and18make unchecked construction difficult.1920## Core Workflow21221. Find raw input boundaries: HTTP payloads, path/query parameters, config23 files, environment variables, database rows, queues, and CLI flags.242. Separate transport DTOs from domain types. Let `serde` deserialize incoming25 shapes, then convert DTO fields into validated domain values.263. Replace primitive strings with small types for ruled values: email addresses,27 usernames, passwords, subscriber names, slugs, tenant IDs, idempotency keys,28 and money-like or duration-like values.294. Give domain types private fields and smart constructors. Avoid unchecked30 `pub` fields or `impl From<String>` for fallible conversions.315. Return typed validation errors that map to useful HTTP responses without32 leaking internal details.336. Keep database and external API mapping explicit. Convert to raw strings at34 the final persistence or serialization edge.357. Test invariants directly. Cover valid examples, malformed inputs, boundary36 lengths, normalization rules, and round trips.3738## Type Design Rules3940- Prefer `TryFrom<String>`, `TryFrom<&str>`, or `FromStr` for fallible parsing.41- Keep stored values owned unless profiling proves borrowing is necessary.42- Implement `AsRef<str>` or a named accessor for read-only exposure.43- Implement `Display` only when the formatted value is safe to show in logs,44 errors, and UI.45- Avoid deriving `Debug` for secret-bearing values unless the debug output is46 redacted.47- Make normalization visible in tests: trim, lowercase, Unicode handling, and48 canonicalization.4950## Request Boundary Pattern5152Deserialize into a request shape, then construct a command:5354```rust55#[derive(serde::Deserialize)]56pub struct SubscribeRequest {57 email: String,58 name: String,59}6061pub struct SubscribeCommand {62 pub email: EmailAddress,63 pub name: SubscriberName,64}6566impl TryFrom<SubscribeRequest> for SubscribeCommand {67 type Error = SubscribeValidationError;6869 fn try_from(value: SubscribeRequest) -> Result<Self, Self::Error> {70 Ok(Self {71 email: EmailAddress::parse(value.email)?,72 name: SubscriberName::parse(value.name)?,73 })74 }75}76```7778Handlers should reject invalid input before business logic or database code. If79validation needs database state, keep pure parsing separate from uniqueness or80authorization checks.8182## Tests8384Read `references/property-testing.md` when invariants have many edge cases or85when an AI agent is likely to miss invalid inputs with example-only tests.8687Minimum tests for a new domain type:8889- Accept a realistic valid value.90- Reject empty input and whitespace-only input.91- Reject too-long input when storage or product rules impose limits.92- Reject format violations.93- Preserve or normalize exactly as documented by tests.94- Round-trip through `serde` or SQL mapping when that type crosses those95 boundaries.9697## Reference Files9899- `references/newtype-patterns.md`: constructor, trait, serde, and persistence100 patterns for Rust newtypes.101- `references/property-testing.md`: property-testing strategy for parsers and102 domain constructors.