Service Registry

# Where the delays come from (Eureka defaults, worst case adds up)
#
#   instance registers / changes status
#     -> Eureka server response cache refreshes     every 30s   (response-cache-update-interval-ms)
#     -> client fetches the registry delta          every 30s   (registry-fetch-interval-seconds)
#     -> Spring Cloud LoadBalancer instance cache   up to 35s   (spring.cloud.loadbalancer.cache.ttl)
#
#   instance dies without deregistering
#     -> lease expires after                        90s default (lease-expiration-duration-in-seconds)
#     -> eviction task runs                         every 60s   (eviction-interval-timer-in-ms)
#     -> then the caches above must refresh
#
# Result: callers can keep sending traffic to a dead instance for several minutes.
# Plan for it with timeouts, retries on idempotent calls and circuit breakers.

# Choosing
#   Kubernetes                       -> Kubernetes Services (DNS) or spring-cloud-kubernetes
#   VMs / Docker hosts / hybrid      -> Eureka or Consul
#   Need KV config + health + ACLs   -> Consul
#   Spring-only estate, simple setup -> Eureka

<!-- pom.xml: import the release train matching your Spring Boot version -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>   <!-- e.g. 2024.0.x for Boot 3.4 -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- Eureka SERVER application -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-server</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

<!-- Every CLIENT service -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

@SpringBootApplication
@EnableEurekaServer
public class ServiceRegistryApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServiceRegistryApplication.class, args);
    }
}

@Configuration
@EnableWebSecurity
class EurekaSecurityConfig {

    @Bean
    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            .httpBasic(Customizer.withDefaults())
            // Eureka clients POST/PUT/DELETE without a CSRF token. Without this
            // line every registration and heartbeat fails with 403.
            .csrf(csrf -> csrf.ignoringRequestMatchers("/eureka/**"));
        return http.build();
    }
}

// Without that CSRF exclusion a client logs something like:
//   Cannot execute request on any known server  /  registration status: 403

# application.yml: standalone server (development)
server:
  port: 8761

spring:
  application:
    name: service-registry
  security:
    user:
      name: ${EUREKA_USER:eureka}
      password: ${EUREKA_PASSWORD}

eureka:
  instance:
    hostname: localhost
  client:
    register-with-eureka: false     # do not register with itself
    fetch-registry: false           # nothing to fetch from itself
    service-url:
      defaultZone: http://localhost:8761/eureka/
  server:
    # Time a starting server waits for peers to give it registry data.
    # No peers in standalone mode, so skip the wait. Keep the default in a cluster.
    wait-time-in-ms-when-sync-empty: 0

# Dashboard: http://localhost:8761  (basic auth)
# Registry API: GET http://localhost:8761/eureka/apps   (add Accept: application/json)

# application.yml: shared by both peers
spring:
  application:
    name: service-registry
  security:
    user:
      name: ${EUREKA_USER:eureka}
      password: ${EUREKA_PASSWORD}

eureka:
  client:
    register-with-eureka: true      # peers register with each other
    fetch-registry: true

---
spring:
  config:
    activate:
      on-profile: peer1
server:
  port: 8761
eureka:
  instance:
    hostname: eureka-peer1
  client:
    service-url:
      defaultZone: http://${EUREKA_USER}:${EUREKA_PASSWORD}@eureka-peer2:8761/eureka/

---
spring:
  config:
    activate:
      on-profile: peer2
server:
  port: 8761
eureka:
  instance:
    hostname: eureka-peer2
  client:
    service-url:
      defaultZone: http://${EUREKA_USER}:${EUREKA_PASSWORD}@eureka-peer1:8761/eureka/

# Clients list every server so they can fail over:
#   eureka.client.service-url.defaultZone:
#     http://user:pass@eureka-peer1:8761/eureka/,http://user:pass@eureka-peer2:8761/eureka/
#
# Start with: --spring.profiles.active=peer1  /  peer2

# application.yml: client service
spring:
  application:
    name: order-service              # service id, lowercase

eureka:
  client:
    service-url:
      # one line: folded (>) YAML would insert spaces into the URL
      defaultZone: http://${EUREKA_USER:eureka}:${EUREKA_PASSWORD}@eureka-server:8761/eureka/
    registry-fetch-interval-seconds: 30     # local registry cache refresh
  instance:
    prefer-ip-address: true                 # under eureka.instance, NOT eureka.client
    # unique per instance, also with server.port=0
    instance-id: ${spring.application.name}:${spring.cloud.client.ip-address}:${spring.application.instance_id:${random.value}}
    lease-renewal-interval-in-seconds: 10   # heartbeat (default 30)
    lease-expiration-duration-in-seconds: 30  # evict after this long without one (default 90)
    status-page-url-path: /actuator/info
    health-check-url-path: /actuator/health

management:
  endpoints:
    web:
      exposure:
        include: health,info

// Optional in Spring Boot 3, since discovery is auto-configured:
//   @EnableDiscoveryClient
//
// Verify: GET http://eureka-server:8761/eureka/apps/ORDER-SERVICE

# application.yml
eureka:
  client:
    healthcheck:
      enabled: true     # propagate Actuator health to Eureka; without it, heartbeat = UP

management:
  endpoint:
    health:
      probes:
        enabled: true             # adds /actuator/health/liveness and /readiness
      show-details: when-authorized
  health:
    # Keep the registration-driving group narrow: only what this instance cannot live without.
    readinessstate:
      enabled: true
    db:
      enabled: true               # still visible under /actuator/health, see group below
  endpoint.health.group:
    readiness:
      include: readinessState     # add "db" only if the instance truly cannot serve without it

# Eureka statuses
#   UP              taking traffic
#   DOWN            health check failed (needs healthcheck.enabled=true)
#   STARTING        still starting
#   OUT_OF_SERVICE  deliberately taken out of rotation (see graceful shutdown)

// Custom indicator, if you really need one: honour the result of isValid
@Component
class ExternalQuotaHealthIndicator implements HealthIndicator {

    private final DataSource dataSource;

    ExternalQuotaHealthIndicator(DataSource dataSource) {
        this.dataSource = dataSource;
    }

    @Override
    public Health health() {
        try (Connection c = dataSource.getConnection()) {
            return c.isValid(2)
                ? Health.up().build()
                : Health.down().withDetail("reason", "connection not valid").build();
        } catch (SQLException ex) {
            return Health.down(ex).build();
        }
    }
}

# application.yml of the CALLER (e.g. order-service in zone a)
spring:
  cloud:
    loadbalancer:
      zone: us-east-1a                  # this caller's zone, used by withZonePreference()
      cache:
        ttl: 10s                        # instance list cache (default 35s); shorter = fresher

# application.yml of EVERY service instance: what it publishes
eureka:
  instance:
    metadata-map:
      zone: us-east-1a
      version: "2.1.0"
      weight: "100"                     # relative weight used by withWeighted()

// Not annotated with @Configuration: it must not be component-scanned globally.
class InventoryLoadBalancerConfig {

    @Bean
    ServiceInstanceListSupplier supplier(ConfigurableApplicationContext context) {
        return ServiceInstanceListSupplier.builder()
            .withDiscoveryClient()
            .withZonePreference()       // prefer same-zone instances
            .withCaching()
            .build(context);
    }
}

@SpringBootApplication
@LoadBalancerClient(name = "inventory-service",
                    configuration = InventoryLoadBalancerConfig.class)
public class OrderServiceApplication { ... }

// For all services instead of one:
//   @LoadBalancerClients(defaultConfiguration = InventoryLoadBalancerConfig.class)
//
// Weighted instead of zone-based:
//   ServiceInstanceListSupplier.builder().withDiscoveryClient().withWeighted().withCaching().build(context)

@Configuration
class HttpClientConfig {

    @Bean
    @LoadBalanced                              // resolves "inventory-service" via the registry
    RestClient.Builder loadBalancedRestClientBuilder() {
        return RestClient.builder();
    }

    @Bean
    RestClient inventoryRestClient(RestClient.Builder builder) {
        return builder
            .baseUrl("http://inventory-service")       // service id, not host:port
            .requestFactory(timeouts())
            .build();
    }

    private ClientHttpRequestFactory timeouts() {
        SimpleClientHttpRequestFactory f = new SimpleClientHttpRequestFactory();
        f.setConnectTimeout(Duration.ofSeconds(2));
        f.setReadTimeout(Duration.ofSeconds(5));
        return f;
    }
}

@Service
class InventoryGateway {

    private final RestClient inventory;

    InventoryGateway(@Qualifier("inventoryRestClient") RestClient inventory) {
        this.inventory = inventory;
    }

    @CircuitBreaker(name = "inventory")                 // Resilience4j
    StockResponse checkStock(Long productId) {
        return inventory.get()
            .uri("/api/v1/stock/{id}", productId)
            .retrieve()
            .body(StockResponse.class);
    }
}

// Reactive equivalent
@Bean
@LoadBalanced
WebClient.Builder loadBalancedWebClientBuilder() {
    return WebClient.builder();
}

// DiscoveryClient: inspection only
@Service
class RegistryInspector {

    private final DiscoveryClient discovery;

    RegistryInspector(DiscoveryClient discovery) {
        this.discovery = discovery;
    }

    List<String> services() {
        return discovery.getServices();
    }

    List<ServiceInstance> instances(String serviceId) {
        return discovery.getInstances(serviceId);   // host, port, metadata
    }

    // Do NOT do this for real calls: no balancing, no zone preference, no health awareness
    //   discovery.getInstances(id).get(0).getUri()
}

# application.yml: production defaults
eureka:
  server:
    enable-self-preservation: true
    renewal-percent-threshold: 0.85        # protect when renewals drop BELOW 85% of expected
    eviction-interval-timer-in-ms: 60000   # how often expired leases are removed (default)

---
spring:
  config:
    activate:
      on-profile: dev
eureka:
  server:
    enable-self-preservation: false        # dev only: dead instances vanish quickly
    eviction-interval-timer-in-ms: 5000

# Dashboard banner when it triggers:
#   "EMERGENCY! EUREKA MAY BE INCORRECTLY CLAIMING INSTANCES ARE UP WHEN THEY'RE NOT.
#    RENEWALS ARE LESSER THAN THRESHOLD AND HENCE THE INSTANCES ARE NOT BEING EXPIRED
#    JUST TO BE SAFE."
#
# Practical effect: stale entries persist. Callers need timeouts, retries and circuit breakers.

# application.yml
server:
  shutdown: graceful                       # finish in-flight requests

spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

management:
  endpoints:
    web:
      exposure:
        include: health,info,serviceregistry

# Pre-stop sequence in a deployment script or container hook:
#
#   1. Mark the instance as out of rotation
#        curl -X POST http://localhost:8080/actuator/serviceregistry \
#             -H "Content-Type: application/json" \
#             -d '{"status":"OUT_OF_SERVICE"}'
#
#   2. Wait for callers to refresh their caches (roughly fetch interval + LB cache TTL)
#        sleep 40
#
#   3. Send SIGTERM; Spring finishes in-flight work, deregisters and exits.

# Kubernetes sketch
#   lifecycle:
#     preStop:
#       exec:
#         command: ["sh", "-c", "curl -s -X POST localhost:8080/actuator/serviceregistry -H 'Content-Type: application/json' -d '{\"status\":\"OUT_OF_SERVICE\"}'; sleep 40"]
#   terminationGracePeriodSeconds: 90

<!-- pom.xml: replace the Eureka client -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-consul-discovery</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-consul-config</artifactId>
</dependency>

# application.yml
spring:
  application:
    name: order-service
  config:
    import: "optional:consul:"            # required on Boot 2.4+ to read Consul KV config
  cloud:
    consul:
      host: ${CONSUL_HOST:localhost}
      port: ${CONSUL_PORT:8500}
      token: ${CONSUL_TOKEN:}              # ACL token on secured clusters
      discovery:
        prefer-ip-address: true
        instance-id: ${spring.application.name}:${spring.cloud.client.ip-address}:${server.port}
        health-check-path: /actuator/health
        health-check-interval: 10s
        health-check-timeout: 5s
        health-check-critical-timeout: 30s   # deregister if critical this long
        tags:
          - version=${app.version:1.0.0}
          - zone=${AVAILABILITY_ZONE:default}
      config:
        prefix: config
        default-context: application
        format: YAML
        data-key: data
        # Reads KV entries (YAML) at:
        #   config/application/data       shared by all services
        #   config/order-service/data     this service only

# Local development: a single dev agent
#   docker run -d --name consul -p 8500:8500 hashicorp/consul agent -dev -client=0.0.0.0
#   UI: http://localhost:8500

# src/test/resources/application-test.yml
eureka:
  client:
    enabled: false                  # no registration, no registry fetch
spring:
  cloud:
    discovery:
      enabled: false
    loadbalancer:
      enabled: false

# Consul equivalent
#   spring.cloud.consul.enabled: false
#   spring.cloud.consul.discovery.enabled: false

// Or per test class
@SpringBootTest(properties = {
    "eureka.client.enabled=false",
    "spring.cloud.discovery.enabled=false"
})
class OrderServiceTest { ... }

// For calls to other services in tests, point the client at a stub (WireMock / MockWebServer)
// and use a plain base URL instead of the service id.

# docker-compose.yml (development)
# services:
#   registry:
#     build: ./service-registry
#     environment: { EUREKA_USER: eureka, EUREKA_PASSWORD: dev, SPRING_PROFILES_ACTIVE: dev }
#     ports: ["8761:8761"]
#   order-service:
#     build: ./order-service
#     environment:
#       EUREKA_USER: eureka
#       EUREKA_PASSWORD: dev
#       EUREKA_CLIENT_SERVICEURL_DEFAULTZONE: http://eureka:dev@registry:8761/eureka/

# Symptom -> likely cause -> fix

# Client logs "Cannot execute request on any known server" / 403 on registration
#   Eureka server has Spring Security with CSRF enabled.
#   -> csrf.ignoringRequestMatchers("/eureka/**") on the server; check credentials.

# Service registers but is not reachable (wrong host or an internal name)
#   Instance registered with a container hostname that other services cannot resolve.
#   -> eureka.instance.prefer-ip-address=true (under eureka.instance, not eureka.client);
#      or set eureka.instance.hostname / ip-address explicitly.

# Dashboard shows one instance although three are running
#   Identical instance ids overwrite each other (same host and port, or a random-port app).
#   -> make instance-id unique, include ${random.value} when server.port=0.

# Registration URL looks broken, with spaces in it
#   Folded YAML scalar (>) turned newlines into spaces.
#   -> keep the URL or instance-id on one line.

# Instance shows UP while it is actually broken
#   Eureka only sees heartbeats by default.
#   -> eureka.client.healthcheck.enabled=true, with a narrow readiness health group.

# Every instance goes DOWN together when the database is down
#   A shared dependency is part of the health group that drives registration.
#   -> keep external dependencies out of that group; use circuit breakers for them.

# Requests still reach a stopped instance for a minute or more
#   Caches: server response cache, client registry cache, LoadBalancer cache; lease expiry.
#   -> graceful shutdown, OUT_OF_SERVICE before stop, timeouts, retries for idempotent calls,
#      lower spring.cloud.loadbalancer.cache.ttl and registry-fetch-interval-seconds.

# Dashboard banner "RENEWALS ARE LESSER THAN THRESHOLD"
#   Self-preservation is active; dead instances are not evicted.
#   -> investigate network issues; in dev, enable-self-preservation=false.

# Unknown host: inventory-service from a @LoadBalanced client
#   The target is not registered, the name differs from spring.application.name,
#   or the client is not load-balanced (builder missing @LoadBalanced).
#   -> check /eureka/apps; names are case-insensitive but must match.

# Config in Consul KV is ignored
#   Missing spring.config.import: "optional:consul:" (Boot 2.4+), or wrong key path.
#   -> add the import; keys live under config/<application>/data.

# Startup fails with classpath / NoSuchMethodError in Spring Cloud classes
#   Spring Cloud release train does not match the Spring Boot version.
#   -> import the matching spring-cloud-dependencies BOM.