Idempotency & Conflict Resolution
Relevant source files
The following files were used as context for generating this wiki page:
Idempotency and Conflict Resolution in Forze provide mechanisms to ensure that distributed operations remain consistent and safe even when faced with retries, network failures, or concurrent modifications. The system utilizes Idempotency Keys to prevent duplicate processing of the same request and Optimistic Concurrency Control (OCC) to resolve write conflicts when multiple actors attempt to modify the same resource simultaneously.
These features are integrated into the application layer through specialized contracts, ensuring that handlers can remain infrastructure-agnostic while benefiting from robust reliability patterns.
Sources: skills/forze-framework-usage/SKILL.md, src/forze/application/execution/resilience/occ.py:1-10
Idempotency System
The idempotency system ensures that an operation can be performed multiple times without changing the result beyond the initial application. This is primarily achieved through the IdempotencyPort, which manages the lifecycle of idempotency records.
Core Components
| Component | Description |
|---|---|
IdempotencySpec | Defines the logical configuration for idempotency, including TTL and route names. |
IdempotencyPort | Protocol defining methods to save, get, and delete idempotency records. |
IdempotencyRecord | Data structure containing the cached response, status, and request fingerprint. |
Sources: src/forze/application/contracts/idempotency/specs.py:10-25, src/forze/application/contracts/idempotency/ports.py:15-40
Idempotency Flow
The following diagram illustrates how the IdempotencyPort interacts with an operation execution to prevent duplicate work.
Configuration
Applications define idempotency requirements using the IdempotencySpec. This spec dictates how long responses are cached and which storage route is utilized.
Sources: src/forze/application/contracts/idempotency/specs.py:12-28
Conflict Resolution (OCC)
Forze implements Optimistic Concurrency Control (OCC) to manage concurrent writes to documents. Instead of locking resources, the system tracks a revision field (rev) on every document.
Concurrency Logic
When a write operation is initiated, the current revision of the document is provided. If another process has updated the document in the interim, the revision check will fail, and the system will raise a conflict exception.
- Revision Bearing Writes: Methods like
updateanddeletein theDocumentCommandPortrequire arevparameter to enforce this check. - Conflict Detection: The adapter compares the provided
revwith the one stored in the database. If they mismatch, the update is rejected.
Sources: skills/forze-documents-search/SKILL.md, src/forze/application/execution/resilience/occ.py:1-15
OCC Flow Diagram
Resilience & Retries
Conflict resolution is often paired with resilience policies to handle transient conflicts.
Resilience Integration
The ExecutionContext provides access to a ResilienceExecutorPort. This allows handlers to execute logic under named policies that can automatically retry operations when a conflict is detected.
- Retry on Conflict: A common pattern is to catch the conflict exception, re-read the latest state, and retry the update logic.
- Deadlines: Resilience policies also manage execution budgets, ensuring that retries do not exceed the
InvocationDeadline.
Sources: skills/forze-framework-usage/SKILL.md, skills/forze-resilience-deadlines/SKILL.md
Summary Table: Reliability Patterns
| Feature | Mechanism | Primary Goal |
|---|---|---|
| Idempotency | Key-based result caching | Prevent duplicate execution of retried requests. |
| OCC | Revision-based write guarding | Prevent data loss from "lost updates" in concurrent environments. |
| Resilience | Named retry/timeout policies | Gracefully recover from transient conflicts and failures. |
Sources: skills/forze-framework-usage/SKILL.md, src/forze/application/execution/resilience/occ.py, src/forze/application/contracts/idempotency/ports.py
Conclusion
The combination of Idempotency and OCC ensures that Forze-based applications maintain high data integrity. By enforcing revision checks on writes and providing a standardized port for request deduplication, Forze allows developers to build safe, distributed systems that handle retries and concurrency as first-class concerns.