feat: implement Esri-compatible transaction handling for ApplyEdits (#12)

[mikemcdougall]

Summary

Implements enhanced transaction handling for the ApplyEdits endpoint with Esri-compatible rollback behavior.

Changes

• Enhanced FeatureEditBatch with RollbackOnFailure and UseGlobalIds properties
• Extended FeatureEditResult with detailed operation tracking and rollback status
• Updated PostgresFeatureStore to support conditional transaction rollback behavior
• Added EditOperationResult struct for individual operation tracking
• Implemented Esri-compatible transaction behavior:
  • rollbackOnFailure=true: rollback entire transaction on any error
  • rollbackOnFailure=false: commit successful operations (Esri default)

Transaction Behavior

• Default behavior (rollbackOnFailure=false): Partial success - successful operations are committed, failed operations are tracked individually
• Strict behavior (rollbackOnFailure=true): All-or-nothing - entire transaction is rolled back if any operation fails
• Maintains backward compatibility with existing functionality
• Provides detailed operation results for improved error reporting

Test Coverage

• Added comprehensive transaction handling tests
• Updated existing tests to use enhanced API
• All 19 PostgreSQL feature store tests pass
• Verified both rollback scenarios work correctly

Closes #12

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4 [email protected]

[github-actions]

🤖 LLM Architecture Review

⚠️ Assessment: NEEDS_ATTENTION

🏗️ Architecture Review Summary

✅ Good Patterns Found:

• Proper use of record structs for immutable data structures in FeatureEdit.cs and PostgresFeatureStore.cs, enhancing thread safety and predictability ([FeatureEdit.cs:10], [PostgresFeatureStore.cs:10]).
• Comprehensive XML documentation on public methods and types, ensuring clarity and maintainability ([FeatureEdit.cs:12], [PostgresFeatureStore.cs:15]).
• Use of parameterized queries to prevent SQL injection, adhering to security best practices ([PostgresFeatureStore.cs:264]).

⚠️ Architecture Concerns:

• Dependency Direction Violation: Honua.Core should not depend on Honua.Postgres. This is a critical architectural principle to ensure layer separation ([FeatureEdit.cs:5]).
• Public Infrastructure Types: Types related to database operations in PostgresFeatureStore.cs should be internal to avoid exposing database specifics ([PostgresFeatureStore.cs:10]).
• Complex Methods: Some methods in PostgresFeatureStore.cs are quite complex and handle multiple responsibilities, such as transaction management, error handling, and data transformation ([PostgresFeatureStore.cs:264]). This could benefit from further refactoring to simplify and enhance testability.

💡 Recommendations:

• Refactor to Remove Core Dependency on Infrastructure: Ensure that Honua.Core does not directly reference Honua.Postgres. Instead, use dependency inversion principles. Define interfaces in Honua.Core and implement these in Honua.Postgres.

  // In Honua.Core
  public interface IFeatureStore {
      Task<FeatureEditResult> ApplyEditsAsync(int layerId, FeatureEditBatch editBatch, CancellationToken cancellationToken = default);
  }
  
  // In Honua.Postgres
  internal class PostgresFeatureStore : IFeatureStore {
      // Implementation
  }

• Encapsulate Infrastructure Types: Change the access modifier of PostgresFeatureStore from internal to private or limit its exposure through a factory or provider pattern.

  internal class PostgresFeatureStore : IFeatureStore {
      // Implementation
  }

• Simplify Complex Methods: Break down complex methods into smaller, more manageable private methods. This aids in understanding and testing individual components of the transaction handling.

  private async Task ProcessCreates(...) {
      // Handle creation logic
  }
  private async Task ProcessUpdates(...) {
      // Handle update logic
  }
  private async Task ProcessDeletes(...) {
      // Handle delete logic
  }

📚 Educational Notes:

• Dependency Direction: Maintaining a strict layer separation by enforcing dependency direction (Core should not depend on Infrastructure) is crucial for building scalable and maintainable systems. It ensures that the core logic can evolve independently of the external dependencies and remains easily testable.
• Encapsulation: Keeping infrastructure types internal protects the application from external changes and misuse. It encapsulates the database-specific logic, making the system more robust and adaptable to changes in storage technologies.
• Complexity Management: Simplifying complex methods into smaller parts makes the system easier to understand, debug, and test. It also helps in adhering to the Single Responsibility Principle, one of the SOLID principles, which promotes greater modularity and flexibility in the application.

Overall Assessment: NEEDS ATTENTION

CRITICAL: The PR must ensure that the core layer does not improperly depend on the infrastructure layer. This is essential for maintaining a clean and scalable architecture. Additionally, the public exposure of infrastructure-specific types needs addressing to safeguard the application's internal mechanisms.

---

Automated architectural analysis powered by OpenAI GPT-4
This review focuses on architectural patterns and design decisions
Human review still recommended for complex changes