Synchronous vs Asynchronous Communication

// Synchronous: Order → Inventory → Warehouse call chain
// If Warehouse is down (or slow), the entire chain is affected
@Service
class OrderService {
    private final InventoryClient inventoryClient;  // HTTP Feign client

    @CircuitBreaker(name = "inventory")             // break the chain on failure
    @TimeLimiter(name = "inventory")                // enforce timeout
    public CompletableFuture<OrderResult> place(Order order) {
        // Blocks waiting for inventory response
        StockResponse stock = inventoryClient.reserve(order.getSku(), order.getQty());
        return CompletableFuture.completedFuture(new OrderResult(order, stock));
    }
}

// Use sync when:
// - User needs an immediate answer ("is item in stock?" → must be sync)
// - Business transaction requires a real-time response
// - Request volume is low-moderate
// - Services are co-located (low latency network)

// Asynchronous: Order publishes event → Inventory consumes independently
@Service
class OrderService {
    private final KafkaTemplate<String, OrderPlacedEvent> kafka;

    public Order place(CreateOrderRequest req) {
        Order order = orderRepo.save(new Order(req));
        // Fire-and-forget — does NOT wait for inventory to reserve
        kafka.send("order-placed", order.getId().toString(),
                   new OrderPlacedEvent(order.getId(), order.getItems()));
        return order;  // returns immediately regardless of inventory state
    }
}

@Component
class InventoryConsumer {
    @KafkaListener(topics = "order-placed")
    void reserve(OrderPlacedEvent event) {
        // Runs independently, can retry on failure, scales separately
        inventoryService.reserve(event.items());
    }
}

// Use async when:
// - Operations can be eventually consistent (email send, analytics update)
// - Consumers are slower than producers (need buffering)
// - Independent scaling of producer and consumer is required
// - High volume / throughput scenarios

// Practical hybrid architecture:
//
// READ  path (sync):  GET /orders/{id} → order-service → return Order DTO
// WRITE path (async): POST /orders → publish OrderCreated event → return 202 Accepted
//
// REST response for async command
@PostMapping("/orders")
ResponseEntity<?> placeOrder(@RequestBody @Valid CreateOrderRequest req) {
    String requestId = UUID.randomUUID().toString();
    orderCommandBus.send(new PlaceOrderCommand(requestId, req));  // async
    return ResponseEntity
        .accepted()
        .header("Location", "/orders/status/" + requestId)
        .body(Map.of("requestId", requestId, "status", "ACCEPTED"));
}

// Polling endpoint
@GetMapping("/orders/status/{requestId}")
OrderStatus getStatus(@PathVariable String requestId) {
    return orderStatusRepo.findByRequestId(requestId)
        .map(s -> new OrderStatus(s.getState(), s.getOrderId()))
        .orElse(new OrderStatus("PENDING", null));
}