Eventual Consistency

// Eventual consistency example:
//
// 1. User places order → Order Service writes to DB, publishes OrderPlaced event
//    Order Service DB: orderId=123, status=PLACED  ✓
//
// 2. User immediately queries "my orders" via Order Query Service
//    Query Service reads Elasticsearch projection — still processing the event
//    Query Result: orderId=123 NOT YET VISIBLE  ← stale read
//
// 3. ~50ms later: Order Query Service processes OrderPlaced event
//    Elasticsearch: orderId=123, status=PLACED  ✓
//    User's next refresh: orderId=123 IS visible
//
// The window: ~50ms to a few seconds depending on consumer speed and load

// Pattern 1: Optimistic UI — assume success, show immediately
// After POST /orders, add the new order to the UI state locally
// without waiting for the query endpoint to reflect it
orderList.add(newOrder);  // client-side state update — eventual consistency UX trick

// Pattern 2: Return immediate result from command side
@PostMapping("/orders")
public ResponseEntity<Order> placeOrder(@RequestBody OrderRequest req) {
    Order order = orderCommandHandler.handle(new PlaceOrderCommand(req));
    // Return the order directly from the write side — don't query the projection
    // The projection will catch up in the background
    return ResponseEntity.status(HttpStatus.CREATED).body(order);
    // Client gets the order immediately; the query endpoint will be consistent shortly
}

// Pattern 3: Idempotent event consumer handles out-of-order events
@EventListener
public void on(OrderStatusUpdatedEvent event) {
    Optional<OrderProjection> existing = projectionRepo.findById(event.getOrderId());
    if (existing.isPresent() && existing.get().getVersion() >= event.getVersion()) {
        log.debug("Skipping stale event version {} for order {}",
                  event.getVersion(), event.getOrderId());
        return;  // do not apply older event over newer state
    }
    // Apply event
    projectionRepo.save(OrderProjection.from(event));
}

// Pattern 4: Optimistic locking on write side
@Entity
public class Order {
    @Version
    private Long version;  // incremented on every UPDATE; stale write → OptimisticLockException
}

// Explicit intermediate states handle the consistency window gracefully
public enum OrderStatus {
    // Stable states
    PLACED,
    PAID,
    SHIPPED,
    DELIVERED,
    CANCELLED,

    // Intermediate states (visible during Saga execution)
    PAYMENT_PENDING,      // waiting for payment service to respond
    INVENTORY_RESERVING,  // waiting for inventory reservation
    SHIPMENT_SCHEDULING,  // waiting for shipping service
    CANCELLING            // compensation in progress
}

// UI shows appropriate messaging for each state:
// PAYMENT_PENDING → "Processing payment..." (spinner)
// PAID            → "Payment confirmed" (green check)
// CANCELLING      → "Cancellation in progress..."
// CANCELLED       → "Order cancelled" (with refund info)

// Never design a Saga without intermediate states — the consistency window
// guarantees these states will be visible to users