Load Balancing

// ── Server-side load balancing: ──────────────────────────────────────
//
//  OrderService
//      │
//      └──▶  Load Balancer (nginx / AWS ALB)
//                  │
//                  ├──▶  UserService instance 1  172.18.0.2:8081
//                  ├──▶  UserService instance 2  172.18.0.3:8081
//                  └──▶  UserService instance 3  172.18.0.4:8081
//
//  Client always calls one address (the balancer).
//  The balancer decides which instance gets the request.
//  Client has no knowledge of individual instances.
//
//  Pros: simple client, centralised control
//  Cons: extra network hop, single point of failure if balancer is down

// ── Client-side load balancing (Spring Cloud default): ───────────────
//
//  Eureka Registry
//    user-service:
//      172.18.0.2:8081  ✓
//      172.18.0.3:8081  ✓
//      172.18.0.4:8081  ✓
//
//  OrderService (has local registry cache)
//      │
//      ├── 1. Fetch instances from the local Eureka cache
//      │        [172.18.0.2, 172.18.0.3, 172.18.0.4]
//      │
//      ├── 2. LoadBalancer picks one (round-robin)
//      │        → selected: 172.18.0.3:8081
//      │
//      └── 3. Call 172.18.0.3:8081/api/users/1 directly (no middle hop)
//
//  Pros: no extra hop, no single point of failure
//  Cons: every client must include balancer logic + registry dependency

// ── Spring Cloud LoadBalancer replaces Netflix Ribbon: ───────────────
// Netflix Ribbon was the original client-side load balancer. It was
// deprecated in the Hoxton release train and removed in Spring Cloud
// 2020.0. Spring Cloud LoadBalancer is its replacement and comes with
// spring-cloud-starter-netflix-eureka-client automatically.

// ── Configuration: ───────────────────────────────────────────────────
@Configuration
public class AppConfig {

    @Bean
    @LoadBalanced   // ← activates Spring Cloud LoadBalancer interceptor
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

// ── Usage in a service: ───────────────────────────────────────────────
@Service
@RequiredArgsConstructor
public class OrderService {

    private final RestTemplate     restTemplate;
    private final OrderRepository  orderRepository;

    public UserResponse getUser(Long userId) {
        // "user-service" is resolved at runtime via Eureka.
        // LoadBalancer picks an instance on every call.
        return restTemplate.getForObject(
            "http://user-service/api/users/" + userId,
            UserResponse.class
        );
    }

    public OrderResponse createOrder(CreateOrderRequest request) {
        UserResponse user = restTemplate.getForObject(
            "http://user-service/api/users/" + request.getUserId(),
            UserResponse.class
        );

        // Call another service — also load-balanced:
        InventoryResponse inventory = restTemplate.getForObject(
            "http://inventory-service/api/inventory/" +
                request.getProductId(),
            InventoryResponse.class
        );

        Order saved = orderRepository.save(
            Order.from(request, user, inventory));
        return OrderResponse.from(saved);
    }
}

// ── How the interceptor works internally: ─────────────────────────────
// 1. restTemplate.getForObject("http://user-service/api/users/1", ...)
// 2. LoadBalancerInterceptor.intercept() fires
// 3. It asks the LoadBalancerClient to choose an instance of "user-service"
// 4. The load balancer gets the instance list from its
//    ServiceInstanceListSupplier (backed by the Eureka client's local
//    cache — no network call to Eureka for each request)
// 5. RoundRobinLoadBalancer picks: ServiceInstance{host=172.18.0.3, port=8081}
// 6. URL rewritten: http://172.18.0.3:8081/api/users/1
// 7. Actual HTTP call made to 172.18.0.3:8081

// ── Configuration: ───────────────────────────────────────────────────
@Configuration
public class RestClientConfig {

    @Bean
    @LoadBalanced
    public RestClient.Builder loadBalancedRestClientBuilder() {
        return RestClient.builder();
    }
}

// ── Usage: build the client once and reuse it ────────────────────────
@Service
public class UserClient {

    private final RestClient restClient;

    public UserClient(RestClient.Builder builder) {
        this.restClient = builder
            .baseUrl("http://user-service")   // logical service name
            .build();
    }

    public UserResponse getUser(Long userId) {
        return restClient.get()
            .uri("/api/users/{id}", userId)
            .retrieve()
            .body(UserResponse.class);
    }
}

// ── Configuration: ───────────────────────────────────────────────────
@Configuration
public class WebClientConfig {

    @Bean
    @LoadBalanced   // ← same annotation, works on WebClient.Builder
    public WebClient.Builder webClientBuilder() {
        return WebClient.builder();
    }
}

// ── Blocking usage (equivalent to RestTemplate): ──────────────────────
@Service
public class OrderService {

    private final WebClient webClient;

    public OrderService(WebClient.Builder builder) {
        this.webClient = builder.build();
    }

    public UserResponse getUser(Long userId) {
        return webClient.get()
            .uri("http://user-service/api/users/" + userId)
            .retrieve()
            .bodyToMono(UserResponse.class)
            .block();   // block() makes it synchronous
    }
}

// ── Non-blocking reactive usage: ─────────────────────────────────────
@Service
public class ReactiveOrderService {

    private final WebClient       webClient;
    private final OrderRepository orderRepository;   // blocking JPA repository

    public ReactiveOrderService(WebClient.Builder builder,
                                OrderRepository orderRepository) {
        this.webClient       = builder.build();
        this.orderRepository = orderRepository;
    }

    public Mono<OrderResponse> placeOrder(CreateOrderRequest request) {
        Mono<UserResponse> userMono = webClient.get()
            .uri("http://user-service/api/users/" + request.getUserId())
            .retrieve()
            .bodyToMono(UserResponse.class);

        Mono<InventoryResponse> inventoryMono = webClient.get()
            .uri("http://inventory-service/api/inventory/" +
                request.getProductId())
            .retrieve()
            .bodyToMono(InventoryResponse.class);

        // Make both calls in parallel, combine results:
        return Mono.zip(userMono, inventoryMono)
            .flatMap(tuple -> {
                Order order = Order.from(
                    request, tuple.getT1(), tuple.getT2());
                // JPA is blocking: run it on a bounded-elastic thread
                return Mono.fromCallable(() -> orderRepository.save(order))
                           .subscribeOn(Schedulers.boundedElastic());
            })
            .map(OrderResponse::from);
    }
}

// ── Default: RoundRobinLoadBalancer ──────────────────────────────────
// Cycles through instances in order using an atomic counter.
// Request 1 → instance[0]
// Request 2 → instance[1]
// Request 3 → instance[2]
// Request 4 → instance[0]  (wraps around)

// ── Override per service: ─────────────────────────────────────────────
@Configuration
@LoadBalancerClient(
    name = "user-service",              // applies only to user-service
    configuration = RandomLBConfig.class
)
public class UserServiceLBConfig { }

// Plain class: no @Configuration, so component scanning does not
// register it as a global default.
public class RandomLBConfig {

    @Bean
    ReactorLoadBalancer<ServiceInstance> randomLoadBalancer(
            Environment env,
            LoadBalancerClientFactory factory) {
        String name = env.getProperty(
            LoadBalancerClientFactory.PROPERTY_NAME);
        return new RandomLoadBalancer(
            factory.getLazyProvider(name,
                ServiceInstanceListSupplier.class),
            name
        );
    }
}

// ── Override globally (all services): ────────────────────────────────
@Configuration
@LoadBalancerClients(defaultConfiguration = RandomLBConfig.class)
public class GlobalLoadBalancerConfig { }

// ── Custom algorithm — weighted random: ───────────────────────────────
public class WeightedLoadBalancer implements
        ReactorServiceInstanceLoadBalancer {

    private final String serviceId;
    private final ObjectProvider<ServiceInstanceListSupplier> supplier;

    public WeightedLoadBalancer(
            ObjectProvider<ServiceInstanceListSupplier> supplier,
            String serviceId) {
        this.supplier  = supplier;
        this.serviceId = serviceId;
    }

    @Override
    public Mono<Response<ServiceInstance>> choose(Request request) {
        return supplier
            .getIfAvailable(NoopServiceInstanceListSupplier::new)
            .get(request)
            .next()
            .map(this::pickWeighted);
    }

    // Separate method so both branches return Response<ServiceInstance>
    private Response<ServiceInstance> pickWeighted(
            List<ServiceInstance> instances) {
        // Read "weight" from instance metadata, set per instance with
        // eureka.instance.metadata-map.weight=3  (keep weights small)
        List<ServiceInstance> weighted = new ArrayList<>();
        for (ServiceInstance instance : instances) {
            int weight = Integer.parseInt(
                instance.getMetadata().getOrDefault("weight", "1"));
            for (int i = 0; i < weight; i++) {
                weighted.add(instance);   // add proportionally
            }
        }
        if (weighted.isEmpty()) {
            return new EmptyResponse();
        }
        return new DefaultResponse(weighted.get(
            ThreadLocalRandom.current().nextInt(weighted.size())));
    }
}

// ── Register the custom algorithm for a service: ──────────────────────
public class WeightedLBConfig {

    @Bean
    ReactorLoadBalancer<ServiceInstance> weightedLoadBalancer(
            Environment env,
            LoadBalancerClientFactory factory) {
        String name = env.getProperty(
            LoadBalancerClientFactory.PROPERTY_NAME);
        return new WeightedLoadBalancer(
            factory.getLazyProvider(name,
                ServiceInstanceListSupplier.class),
            name);
    }
}

@Configuration
@LoadBalancerClient(name = "user-service",
                    configuration = WeightedLBConfig.class)
public class WeightedLBRegistration { }

// ── Enable health-check aware instance filtering: ────────────────────

// application.yml:
// spring:
//   cloud:
//     loadbalancer:
//       configurations: health-check   # activate the health-check supplier
//       health-check:
//         initial-delay: 0
//         interval: 25s                # re-check instance health every 25 seconds

// ── Programmatic health-check supplier configuration: ────────────────
public class HealthCheckLBConfig {

    @Bean
    public ServiceInstanceListSupplier serviceInstanceListSupplier(
            ConfigurableApplicationContext context) {
        return ServiceInstanceListSupplier.builder()
            .withDiscoveryClient()       // fetch from Eureka
            .withHealthChecks()          // filter unhealthy instances
            .build(context);
    }
}

@Configuration
@LoadBalancerClients(defaultConfiguration = HealthCheckLBConfig.class)
public class GlobalLBConfig { }

// ── Zone-preference supplier (prefer same-zone instances): ────────────
public class ZonePreferenceLBConfig {

    @Bean
    public ServiceInstanceListSupplier serviceInstanceListSupplier(
            ConfigurableApplicationContext context) {
        return ServiceInstanceListSupplier.builder()
            .withDiscoveryClient()
            .withZonePreference()    // prefer instances in the same zone
            .withHealthChecks()      // still filter unhealthy ones
            .build(context);
    }
}

// application.yml — declare the current zone so the supplier can prefer it:
// spring:
//   cloud:
//     loadbalancer:
//       zone: us-east-1a
//
// eureka:
//   instance:
//     metadata-map:
//       zone: us-east-1a   # instances tag themselves with their zone

# application.yml — cache, retry and logging
spring:
  cloud:
    loadbalancer:
      cache:
        enabled: true            # default: true
        ttl: 35s                 # evict and refresh after 35 seconds
        capacity: 256            # max number of services cached
      retry:
        enabled: true
        max-retries-on-same-service-instance: 0   # don't retry the same instance
        max-retries-on-next-service-instance: 2   # try 2 other instances
        retry-on-all-operations: false            # only retry GET (idempotent)
        retryable-status-codes: 500, 502, 503

# Disabling the cache means an instance lookup on EVERY request.
# Use that only in development or low-traffic scenarios:
#   spring.cloud.loadbalancer.cache.enabled: false

# Verify which instance was chosen (debug logging):
logging:
  level:
    org.springframework.cloud.loadbalancer: DEBUG

# Example debug output:
# [RoundRobinLoadBalancer] Selected instance: {serviceId='user-service',
#   host='172.18.0.3', port=8081, secure=false, metadata={zone=us-east-1a}}

// ── Problem 1: UnknownHostException: user-service ────────────────────
// ❌ Plain RestTemplate cannot resolve a service name
@Bean
public RestTemplate restTemplate() {
    return new RestTemplate();
}

// ✅ Add @LoadBalanced
@Bean
@LoadBalanced
public RestTemplate restTemplate() {
    return new RestTemplate();
}

// ── Problem 2: need both a load-balanced and a plain client ──────────
@Bean
@LoadBalanced
public RestTemplate loadBalancedRestTemplate() {
    return new RestTemplate();
}

@Bean
public RestTemplate externalRestTemplate() {      // for external URLs
    return new RestTemplate();
}

@Service
public class PaymentClient {
    private final RestTemplate restTemplate;

    public PaymentClient(
            @Qualifier("externalRestTemplate") RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
}

// ── Problem 3: "No instances available for user-service" ─────────────
// 1. Check the name registered in Eureka matches the URL host:
//      spring.application.name: user-service
// 2. Open the Eureka dashboard and confirm the instance status is UP
// 3. Wait for the cache TTL, or lower it while testing:
//      spring.cloud.loadbalancer.cache.ttl: 5s
// 4. Enable DEBUG logging for org.springframework.cloud.loadbalancer

// ── Problem 4: per-service config applied to every service ───────────
// ❌ Config class annotated with @Configuration and picked up by
//    component scanning becomes the global default.
// ✅ Leave @Configuration off classes used in @LoadBalancerClient(...),
//    or keep them outside the package that is component-scanned.