MicroProfile Core Rules

# CLAUDE.md — MicroProfile Core

## What MicroProfile is

- A set of cloud-native specs that complement Jakarta EE: Config, Health, Metrics, OpenAPI, REST Client, Fault Tolerance, JWT, OpenTracing.
- Implemented by Quarkus (SmallRye), Open Liberty, Helidon, Payara Micro, WildFly.
- Use it on top of Jakarta EE for the "operability" layer that Jakarta EE proper doesn't cover.

## Configuration (MicroProfile Config)

- `@ConfigProperty(name = "...")` to inject config values into beans:
  ```java
  @Inject @ConfigProperty(name = "app.email.from") String fromAddress;
  ```
- Sources by precedence: system properties → env vars → `microprofile-config.properties` → user-defined sources.
- For grouped, type-safe config, use `@ConfigMapping` (Quarkus / SmallRye) or roll a `@ApplicationScoped` config bean.
- Default values: `@ConfigProperty(name = "app.timeout", defaultValue = "30")`.

## Health (MicroProfile Health)

- `/health` for combined, `/health/live` for liveness, `/health/ready` for readiness.
- One `HealthCheck` per dependency:
  ```java
  @Liveness @ApplicationScoped
  public class AppLive implements HealthCheck {
      public HealthCheckResponse call() { return HealthCheckResponse.up("app"); }
  }
  ```
- Liveness checks must not depend on external systems (DB, Redis). They check process health only.
- Readiness checks include external systems. Failure means "remove from load balancer".

## Metrics (MicroProfile Metrics / Micrometer)

- MicroProfile Metrics API → SmallRye Metrics or Micrometer (Quarkus 3 prefers Micrometer).
- Standard metrics: HTTP requests, JVM, GC, threads. Custom:
  ```java
  @Counted(name = "checkout_attempts")
  public void checkout(...) { ... }
  ```
- Tag with low-cardinality dimensions (`endpoint`, `status`, `tenant_id` only if bounded). Never `user_id`.
- Expose at `/metrics` in Prometheus format.

## REST Client

- Type-safe HTTP clients defined as interfaces (see the dedicated REST Client guide).

## Fault tolerance

- Retries, circuit breaker, fallback, timeout, bulkhead — declarative annotations on methods (see the dedicated Fault Tolerance guide).

## OpenAPI

- `@OpenAPIDefinition` on the application class for global metadata.
- Most documentation is auto-generated from JAX-RS + Bean Validation.
- See dedicated OpenAPI guide for details.

## JWT

- `@LoginConfig(authMethod = "MP-JWT")` on the application class enables JWT auth.
- Inject claims with `@Inject @Claim("groups") Instance<String> groups`.
- See the dedicated JWT auth guide.

## Don't

- Don't reach for a separate config library when MicroProfile Config is on the platform. Use what's there.
- Don't mix MicroProfile Metrics and Micrometer in the same project — pick one.
- Don't use `Liveness` checks that depend on the DB. The pod will be restarted unnecessarily on DB blips.
- Don't expose `/metrics` to the public internet without auth.