Synchronous Communication in Microservices

Order Service                         Inventory Service
     |---- POST /api/inventory/reservations --->|
     |           (waiting...)                   |  checks stock
     |<--------- 200 OK { reserved: true } -----|
     |
  continues with the next step

Browser -> Order Service
             |-- 1. reserve stock --> Inventory Service  (wait)
             |<--------- 200 OK ------
             |-- 2. charge card ----> Payment Service    (wait)
             |<--------- 200 OK ------
             |-- 3. save order (CONFIRMED)
Browser <- 201 Created

package com.example.order.client;

import java.util.List;

import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;

@Component
public class InventoryClient {

    private final RestClient restClient;

    public InventoryClient(RestClient.Builder builder) {
        this.restClient = builder.baseUrl("http://inventory-service").build();
    }

    public String reserve(String orderId, List<OrderLine> lines) {
        ReservationResponse response = restClient.post()
                .uri("/api/inventory/reservations")
                .body(new ReservationRequest(orderId, lines))
                .retrieve()
                // 409 means "out of stock": a business outcome, not a technical error
                .onStatus(status -> status.value() == 409, (request, resp) -> {
                    throw new OutOfStockException("Some items in order " + orderId + " are out of stock");
                })
                .body(ReservationResponse.class);

        return response.reservationId();
    }

    public void release(String reservationId) {
        restClient.delete()
                .uri("/api/inventory/reservations/{id}", reservationId)
                .retrieve()
                .toBodilessEntity();
    }

    public record OrderLine(String productId, int quantity) {
    }

    record ReservationRequest(String orderId, List<OrderLine> lines) {
    }

    record ReservationResponse(String reservationId) {
    }
}

package com.example.order;

import org.springframework.stereotype.Service;

import com.example.order.client.InventoryClient;
import com.example.order.client.PaymentClient;
import com.example.order.client.PaymentDeclinedException;

@Service
public class OrderService {

    private final InventoryClient inventoryClient;
    private final PaymentClient paymentClient;
    private final OrderRepository orders;

    public OrderService(InventoryClient inventoryClient, PaymentClient paymentClient,
                        OrderRepository orders) {
        this.inventoryClient = inventoryClient;
        this.paymentClient = paymentClient;
        this.orders = orders;
    }

    public Order placeOrder(PlaceOrderRequest request) {
        Order order = orders.save(Order.pending(request));

        // Synchronous call 1: throws OutOfStockException if stock is missing
        String reservationId = inventoryClient.reserve(order.getId(), request.lines());

        try {
            // Synchronous call 2
            String transactionId = paymentClient.charge(order.getId(), request.cardToken(), order.getTotal());
            order.confirm(transactionId);
        } catch (PaymentDeclinedException ex) {
            // Undo step 1 so the stock can be sold to someone else
            inventoryClient.release(reservationId);
            order.reject(ex.getMessage());
            orders.save(order);
            throw ex;
        }

        return orders.save(order);
    }
}

package com.example.inventory;

import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ReservationController {

    private final StockService stock;

    public ReservationController(StockService stock) {
        this.stock = stock;
    }

    @PostMapping("/api/inventory/reservations")
    public ResponseEntity<?> reserve(@RequestBody ReservationRequest request) {
        return stock.tryReserve(request)
                .<ResponseEntity<?>>map(reservationId -> ResponseEntity.ok(new ReservationResponse(reservationId)))
                .orElseGet(() -> {
                    ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                            HttpStatus.CONFLICT, "One or more items are out of stock");
                    problem.setTitle("Out of stock");
                    return ResponseEntity.of(problem).build();
                });
    }
}

{
  "type": "about:blank",
  "title": "Out of stock",
  "status": 409,
  "detail": "One or more items are out of stock",
  "instance": "/api/inventory/reservations"
}

package com.example.order.config;

import java.time.Duration;

import org.springframework.boot.web.client.RestClientCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.SimpleClientHttpRequestFactory;

@Configuration
public class HttpClientConfig {

    @Bean
    public RestClientCustomizer timeouts() {
        return builder -> {
            SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
            factory.setConnectTimeout(Duration.ofSeconds(1));   // time to open a connection
            factory.setReadTimeout(Duration.ofSeconds(3));      // time to wait for the response
            builder.requestFactory(factory);
        };
    }
}

200 threads, each request waits on a downstream call

Downstream answers in 0.1 s  ->  up to ~2,000 requests/second
Downstream answers in 10 s   ->  up to ~20 requests/second
                                 (all threads busy waiting)

# Handle each request on a virtual thread (Java 21+)
spring.threads.virtual.enabled=true

@Service
public class ProductPageService {

    private final CatalogClient catalogClient;
    private final ReviewClient reviewClient;
    private final InventoryClient inventoryClient;
    private final ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();

    public ProductPageService(CatalogClient catalogClient, ReviewClient reviewClient,
                              InventoryClient inventoryClient) {
        this.catalogClient = catalogClient;
        this.reviewClient = reviewClient;
        this.inventoryClient = inventoryClient;
    }

    public ProductPage load(String productId) {
        var product = CompletableFuture.supplyAsync(() -> catalogClient.get(productId), executor);
        var reviews = CompletableFuture.supplyAsync(() -> reviewClient.top(productId), executor);
        var stock = CompletableFuture.supplyAsync(() -> inventoryClient.stockLevel(productId), executor);

        // About max(t1, t2, t3) instead of t1 + t2 + t3
        return new ProductPage(product.join(), reviews.join(), stock.join());
    }
}

syntax = "proto3";

option java_package = "com.example.inventory.grpc";
option java_multiple_files = true;

service InventoryService {
  rpc CheckStock (StockRequest) returns (StockReply);
}

message StockRequest {
  string product_id = 1;
  int32 quantity = 2;
}

message StockReply {
  bool available = 1;
  int32 in_stock = 2;
}

package com.example.order.client;

import java.util.concurrent.TimeUnit;

import com.example.inventory.grpc.InventoryServiceGrpc;
import com.example.inventory.grpc.StockReply;
import com.example.inventory.grpc.StockRequest;

import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class GrpcInventoryClient {

    private final InventoryServiceGrpc.InventoryServiceBlockingStub stub;

    public GrpcInventoryClient(String host, int port) {
        ManagedChannel channel = ManagedChannelBuilder.forAddress(host, port)
                .usePlaintext()            // use TLS in production
                .build();
        this.stub = InventoryServiceGrpc.newBlockingStub(channel);
    }

    public boolean isAvailable(String productId, int quantity) {
        StockReply reply = stub
                .withDeadlineAfter(2, TimeUnit.SECONDS)   // gRPC's timeout
                .checkStock(StockRequest.newBuilder()
                        .setProductId(productId)
                        .setQuantity(quantity)
                        .build());
        return reply.getAvailable();
    }
}

@Retry(name = "payment")
@CircuitBreaker(name = "payment", fallbackMethod = "paymentUnavailable")
public String charge(String orderId, String cardToken, BigDecimal amount) {
    return restClient.post()
            .uri("/api/payments")
            .header("Idempotency-Key", orderId)   // safe to retry: never charges twice
            .body(new ChargeRequest(orderId, cardToken, amount))
            .retrieve()
            .body(ChargeResponse.class)
            .transactionId();
}

private String paymentUnavailable(String orderId, String cardToken, BigDecimal amount, Exception ex) {
    throw new ServiceTemporarilyUnavailableException("Payments are temporarily unavailable. Please try again.");
}

package com.example.order.client;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.springframework.test.web.client.match.MockRestRequestMatchers.method;
import static org.springframework.test.web.client.match.MockRestRequestMatchers.requestTo;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withStatus;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withSuccess;

import java.util.List;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.client.RestClientTest;
import org.springframework.http.HttpMethod;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.test.web.client.MockRestServiceServer;

@RestClientTest(InventoryClient.class)
class InventoryClientTest {

    private static final String URL = "http://inventory-service/api/inventory/reservations";

    @Autowired
    private InventoryClient client;

    @Autowired
    private MockRestServiceServer server;

    @Test
    void returnsReservationIdWhenStockIsAvailable() {
        server.expect(requestTo(URL))
              .andExpect(method(HttpMethod.POST))
              .andRespond(withSuccess("{\"reservationId\":\"R-77\"}", MediaType.APPLICATION_JSON));

        String id = client.reserve("1001", List.of(new InventoryClient.OrderLine("P-11", 2)));

        assertThat(id).isEqualTo("R-77");
    }

    @Test
    void throwsOutOfStockOn409() {
        server.expect(requestTo(URL))
              .andRespond(withStatus(HttpStatus.CONFLICT));

        assertThatThrownBy(() -> client.reserve("1001", List.of(new InventoryClient.OrderLine("P-11", 99))))
                .isInstanceOf(OutOfStockException.class);
    }
}