Validation invariants can be bypassed via direct deserialisation

[coderabbitai]

Problem

Several "validated" domain entities derive Deserialize and expose public fields, allowing validation invariants to be bypassed when instances are created outside their new(...) constructors.

Affected Types

• RouteSummary and CommunityPick in the catalogue domain
• Tag, Badge, and SafetyToggle in the descriptors domain (generated via macro)

References

• backend/src/domain/catalogue/route_summary.rs:34
• backend/src/domain/catalogue/route_summary.rs:55
• backend/src/domain/catalogue/community_pick.rs:29
• backend/src/domain/catalogue/community_pick.rs:47
• backend/src/domain/descriptors/mod.rs:72
• backend/src/domain/descriptors/mod.rs:85

Impact

Invalid slugs, negative numeric values, or other constraint violations can exist in memory if these types are instantiated via:

• Direct struct construction (public fields)
• JSON/CBOR deserialisation bypassing the constructor

This weakens the "validated domain type" contract and could allow invalid data to propagate through the system.

Possible Solutions

1. Remove Deserialize derives and implement custom deserialisation that delegates to the validating constructor
2. Use #[serde(try_from = "Draft")] pattern (as done for SafetyPreset) to enforce validation during deserialisation
3. Make struct fields private and provide only getter methods
4. Combine approaches: private fields + custom TryFrom deserialisation

Related

This issue was flagged during PR #307 code review (catalogue and descriptor domain types).

[traycerai]

Plan

Observations

The codebase follows a consistent validation pattern for domain types, as seen in file:backend/src/domain/user.rs and file:backend/src/domain/interest_theme.rs. These types use private fields with #[serde(try_from = "T")] to enforce validation during deserialization. PR #307 is introducing new catalogue and descriptor domain types (RouteSummary, CommunityPick, Tag, Badge, SafetyToggle) that currently expose public fields with Deserialize derives, allowing validation invariants to be bypassed.

Approach

Apply the established validation pattern from existing domain types to the new catalogue and descriptor types. Use private fields with getter methods, implement TryFrom for validation, and leverage #[serde(try_from = "Draft")] pattern to enforce validation during deserialization. For macro-generated types, update the macro to emit the correct pattern. This ensures all domain types maintain their invariants regardless of how they're instantiated.

Implementation Steps

1. Create Validation Utilities Module

Create file:backend/src/domain/validation.rs to house shared validation logic:

• Add a validate_slug function that checks slug format (lowercase alphanumeric with hyphens, non-empty, reasonable length)
• Add a validate_positive_i32 function for numeric constraints
• Add a validate_non_negative_f32 function for rating/metric values
• Export these utilities from file:backend/src/domain/mod.rs

2. Refactor Catalogue Domain Types

RouteSummary (file:backend/src/domain/catalogue/route_summary.rs)

• Change all fields from pub to private
• Create a RouteSummaryDraft struct with public String fields for deserialization
• Implement validation in RouteSummary::new() constructor:
  • Validate slug format if present (optional field)
  • Validate distance_metres is positive
  • Validate duration_seconds is positive
  • Validate rating is between 0.0 and 5.0
• Add #[serde(try_from = "RouteSummaryDraft", into = "RouteSummaryDraft")] to RouteSummary
• Implement TryFrom<RouteSummaryDraft> that calls the validating constructor
• Implement From<RouteSummary> for RouteSummaryDraft for serialization
• Add getter methods for all fields (e.g., pub fn slug(&self) -> Option<&str>)
• Create RouteSummaryValidationError enum with variants for each validation failure

CommunityPick (file:backend/src/domain/catalogue/community_pick.rs)

• Change all fields from pub to private
• Create a CommunityPickDraft struct for deserialization
• Implement validation in CommunityPick::new():
  • Validate rating is between 0.0 and 5.0
  • Validate distance_metres is positive
  • Validate duration_seconds is positive
  • Validate saves is non-negative
  • Validate curator_display_name is non-empty
• Add #[serde(try_from = "CommunityPickDraft", into = "CommunityPickDraft")]
• Implement TryFrom<CommunityPickDraft> and From<CommunityPick>
• Add getter methods for all fields
• Create CommunityPickValidationError enum

3. Refactor Descriptor Domain Types

Update Descriptor Macro (file:backend/src/domain/descriptors/mod.rs)

Locate the macro that generates Tag, Badge, and SafetyToggle types and modify it to:

• Generate structs with private fields instead of public
• Generate a corresponding Draft struct for each type (e.g., TagDraft)
• Generate validation logic that checks:
  • slug is valid (using shared validate_slug utility)
  • icon_key is non-empty
• Generate #[serde(try_from = "TypeDraft", into = "TypeDraft")] attribute
• Generate TryFrom<TypeDraft> implementation that validates
• Generate From<Type> for TypeDraft for serialization
• Generate getter methods (slug(), icon_key(), localizations())
• Generate a validation error enum for each type

SafetyPreset

If SafetyPreset exists and already follows the correct pattern:

• Document it as the reference implementation
• Ensure it uses the same validation utilities

If it doesn't exist yet:

• Create it following the same pattern as the macro-generated types
• Add validation for safety_toggle_ids (non-empty array)

4. Update Ingestion Repository Ports

Modify file:backend/src/domain/ports/catalogue_ingestion_repository.rs and file:backend/src/domain/ports/descriptor_ingestion_repository.rs:

• Keep the *Ingestion structs as-is (they're DTOs for ingestion, not domain entities)
• Add conversion methods from *Ingestion to validated domain types
• Update repository trait methods to accept validated domain types instead of ingestion DTOs, OR
• Keep ingestion DTOs in the port but ensure adapters convert to validated types before persistence

5. Update Persistence Adapters

Modify file:backend/src/outbound/persistence/diesel_catalogue_ingestion_repository.rs and file:backend/src/outbound/persistence/diesel_descriptor_ingestion_repository.rs:

• Update From implementations to work with the new private fields using getter methods
• Ensure all conversions to database rows use the validated domain types
• Add error handling for validation failures during conversion

6. Add Validation Tests

For each domain type, add unit tests in their respective test modules:

• Test valid construction via new() constructor
• Test validation failures for each constraint (invalid slug, negative numbers, etc.)
• Test serde roundtrip: serialize → deserialize → verify equality
• Test that direct deserialization of invalid JSON fails with appropriate error
• Test that TryFrom conversions work correctly

Use rstest for parameterized test cases following the pattern in file:backend/src/domain/user.rs tests.

7. Update Documentation

• Add rustdoc comments to each domain type documenting invariants
• Document the validation pattern in file:backend/src/domain/mod.rs
• Update any architecture documentation to note that all domain types enforce validation during deserialization
• Add examples showing correct usage of constructors and deserialization

8. Migration Path for Existing Code

If PR #307 has already been merged:

• Create a deprecation path for public field access
• Add #[deprecated] attributes to public fields with migration guidance
• Provide a grace period before making fields private
• Update all internal usages to use getter methods

If PR #307 is still in review:

• Apply these changes directly to the PR before merging
• Ensure all validation is in place before the types enter the codebase

Validation Pattern Summary

sequenceDiagram
    participant Client
    participant Deserializer
    participant Draft
    participant TryFrom
    participant Constructor
    participant DomainType

    Client->>Deserializer: Deserialize JSON
    Deserializer->>Draft: Create Draft struct
    Draft->>TryFrom: try_from(draft)
    TryFrom->>Constructor: new(validated_fields)
    Constructor->>Constructor: Validate invariants
    alt Validation succeeds
        Constructor->>DomainType: Create instance
        DomainType->>Client: Return Ok(instance)
    else Validation fails
        Constructor->>Client: Return Err(ValidationError)
    end

Loading

Quality Gates

• All domain types must have private fields
• All domain types must validate invariants in constructors
• All domain types with Deserialize must use try_from pattern
• All validation errors must be documented and tested
• No direct struct construction should be possible outside the module
• 100% test coverage for validation logic

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase follows a consistent validation pattern for domain types, as seen in `file:backend/src/domain/user.rs` and `file:backend/src/domain/interest_theme.rs`. These types use private fields with `#[serde(try_from = "T")]` to enforce validation during deserialization. PR #307 is introducing new catalogue and descriptor domain types (`RouteSummary`, `CommunityPick`, `Tag`, `Badge`, `SafetyToggle`) that currently expose public fields with `Deserialize` derives, allowing validation invariants to be bypassed.

## Approach

Apply the established validation pattern from existing domain types to the new catalogue and descriptor types. Use private fields with getter methods, implement `TryFrom` for validation, and leverage `#[serde(try_from = "Draft")]` pattern to enforce validation during deserialization. For macro-generated types, update the macro to emit the correct pattern. This ensures all domain types maintain their invariants regardless of how they're instantiated.

## Implementation Steps

### 1. Create Validation Utilities Module

Create `file:backend/src/domain/validation.rs` to house shared validation logic:

- Add a `validate_slug` function that checks slug format (lowercase alphanumeric with hyphens, non-empty, reasonable length)
- Add a `validate_positive_i32` function for numeric constraints
- Add a `validate_non_negative_f32` function for rating/metric values
- Export these utilities from `file:backend/src/domain/mod.rs`

### 2. Refactor Catalogue Domain Types

#### RouteSummary (`file:backend/src/domain/catalogue/route_summary.rs`)

- Change all fields from `pub` to private
- Create a `RouteSummaryDraft` struct with public `String` fields for deserialization
- Implement validation in `RouteSummary::new()` constructor:
  - Validate slug format if present (optional field)
  - Validate `distance_metres` is positive
  - Validate `duration_seconds` is positive
  - Validate `rating` is between 0.0 and 5.0
- Add `#[serde(try_from = "RouteSummaryDraft", into = "RouteSummaryDraft")]` to `RouteSummary`
- Implement `TryFrom<RouteSummaryDraft>` that calls the validating constructor
- Implement `From<RouteSummary>` for `RouteSummaryDraft` for serialization
- Add getter methods for all fields (e.g., `pub fn slug(&self) -> Option<&str>`)
- Create `RouteSummaryValidationError` enum with variants for each validation failure

#### CommunityPick (`file:backend/src/domain/catalogue/community_pick.rs`)

- Change all fields from `pub` to private
- Create a `CommunityPickDraft` struct for deserialization
- Implement validation in `CommunityPick::new()`:
  - Validate `rating` is between 0.0 and 5.0
  - Validate `distance_metres` is positive
  - Validate `duration_seconds` is positive
  - Validate `saves` is non-negative
  - Validate `curator_display_name` is non-empty
- Add `#[serde(try_from = "CommunityPickDraft", into = "CommunityPickDraft")]`
- Implement `TryFrom<CommunityPickDraft>` and `From<CommunityPick>`
- Add getter methods for all fields
- Create `CommunityPickValidationError` enum

### 3. Refactor Descriptor Domain Types

#### Update Descriptor Macro (`file:backend/src/domain/descriptors/mod.rs`)

Locate the macro that generates `Tag`, `Badge`, and `SafetyToggle` types and modify it to:

- Generate structs with private fields instead of public
- Generate a corresponding `Draft` struct for each type (e.g., `TagDraft`)
- Generate validation logic that checks:
  - `slug` is valid (using shared `validate_slug` utility)
  - `icon_key` is non-empty
- Generate `#[serde(try_from = "TypeDraft", into = "TypeDraft")]` attribute
- Generate `TryFrom<TypeDraft>` implementation that validates
- Generate `From<Type>` for `TypeDraft` for serialization
- Generate getter methods (`slug()`, `icon_key()`, `localizations()`)
- Generate a validation error enum for each type

#### SafetyPreset

If `SafetyPreset` exists and already follows the correct pattern:
- Document it as the reference implementation
- Ensure it uses the same validation utilities

If it doesn't exist yet:
- Create it following the same pattern as the macro-generated types
- Add validation for `safety_toggle_ids` (non-empty array)

### 4. Update Ingestion Repository Ports

Modify `file:backend/src/domain/ports/catalogue_ingestion_repository.rs` and `file:backend/src/domain/ports/descriptor_ingestion_repository.rs`:

- Keep the `*Ingestion` structs as-is (they're DTOs for ingestion, not domain entities)
- Add conversion methods from `*Ingestion` to validated domain types
- Update repository trait methods to accept validated domain types instead of ingestion DTOs, OR
- Keep ingestion DTOs in the port but ensure adapters convert to validated types before persistence

### 5. Update Persistence Adapters

Modify `file:backend/src/outbound/persistence/diesel_catalogue_ingestion_repository.rs` and `file:backend/src/outbound/persistence/diesel_descriptor_ingestion_repository.rs`:

- Update `From` implementations to work with the new private fields using getter methods
- Ensure all conversions to database rows use the validated domain types
- Add error handling for validation failures during conversion

### 6. Add Validation Tests

For each domain type, add unit tests in their respective test modules:

- Test valid construction via `new()` constructor
- Test validation failures for each constraint (invalid slug, negative numbers, etc.)
- Test serde roundtrip: serialize → deserialize → verify equality
- Test that direct deserialization of invalid JSON fails with appropriate error
- Test that `TryFrom` conversions work correctly

Use `rstest` for parameterized test cases following the pattern in `file:backend/src/domain/user.rs` tests.

### 7. Update Documentation

- Add rustdoc comments to each domain type documenting invariants
- Document the validation pattern in `file:backend/src/domain/mod.rs`
- Update any architecture documentation to note that all domain types enforce validation during deserialization
- Add examples showing correct usage of constructors and deserialization

### 8. Migration Path for Existing Code

If PR #307 has already been merged:

- Create a deprecation path for public field access
- Add `#[deprecated]` attributes to public fields with migration guidance
- Provide a grace period before making fields private
- Update all internal usages to use getter methods

If PR #307 is still in review:

- Apply these changes directly to the PR before merging
- Ensure all validation is in place before the types enter the codebase

## Validation Pattern Summary

```mermaid
sequenceDiagram
    participant Client
    participant Deserializer
    participant Draft
    participant TryFrom
    participant Constructor
    participant DomainType

    Client->>Deserializer: Deserialize JSON
    Deserializer->>Draft: Create Draft struct
    Draft->>TryFrom: try_from(draft)
    TryFrom->>Constructor: new(validated_fields)
    Constructor->>Constructor: Validate invariants
    alt Validation succeeds
        Constructor->>DomainType: Create instance
        DomainType->>Client: Return Ok(instance)
    else Validation fails
        Constructor->>Client: Return Err(ValidationError)
    end
```

## Quality Gates

- All domain types must have private fields
- All domain types must validate invariants in constructors
- All domain types with `Deserialize` must use `try_from` pattern
- All validation errors must be documented and tested
- No direct struct construction should be possible outside the module
- 100% test coverage for validation logic

---

Execution Information

Branch: main
Commit: 6b98178

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.