@eltonssouza/development-utility-kit 1.0.0

package/.claude/stacks/java/spring-boot-4.md

@@ -0,0 +1,438 @@
+---
+stack: java/spring-boot-4
+versions_covered: "4.0.x"
+last_validated: 2026-05-27
+validated_against: "sandbox — Java 25 LTS + Spring Boot 4.0.0"
+status: active
+pack_owner: "@elton"
+security_review: 2026-05-27
+next_review_due: 2027-05-27
+---
+
+# Java 25 + Spring Boot 4.x
+
+Canonical knowledge pack for greenfield projects on Java 25 LTS (or 26) + Spring Boot 4.0+. For projects still on Java 17/21 + Spring Boot 3.x, use `spring-boot-3.md`. SB 4 brings first-class AOT/native compilation, virtual threads by default on several sinks, Spring Security 7, and a maturity step on `@HttpExchange` and `ProblemDetail`.
+
+## 1. When to use this pack
+
+- Project declares `Primary stack: Java 25 + Spring Boot 4.x` (or Java 26) in `## Project Identity`.
+- `pom.xml` declares `<java.version>25</java.version>` (or 26) and `<spring-boot.version>4.0.x</spring-boot.version>`.
+- Greenfield: **prefer this pack** over `spring-boot-3.md`. SB 4 is the default for new projects since 2026.
+- Legacy maintenance (still on Java 17/21 + SB 3.x): use `spring-boot-3.md` instead.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| Java | 25 LTS (min) / 26 (latest) | Java 25 LTS until 2033; Virtual Threads + scoped values default; pattern matching for switch maduro; sealed types maduros |
+| Spring Boot | 4.0.x | AOT first-class; native compile sem flags extras; Virtual Threads default em Tomcat + @Scheduled |
+| Jakarta EE | 11 (jakarta.* namespace) | NEVER mix with javax.*; mesmo namespace de SB 3 (sem migration cost) |
+| JPA / Hibernate | Hibernate 7.x (jakarta.persistence) | Records JPA stable; schema validation via Flyway/Liquibase, never Hibernate auto |
+| Spring Security | 7.x | SecurityFilterChain mantido; novo OAuth2 Resource Server DSL mais sucinto |
+| Validation | Jakarta Validation 3.x | `jakarta.validation.constraints.*` |
+| Tomcat / Jetty / Undertow | Tomcat 11 (Servlet 6.1) | Tomcat default; Virtual Threads habilitados via property |
+| Build | Maven 3.9+ or Gradle 8.10+ | Maven Wrapper / Gradle Wrapper committed |
+| Tests | JUnit 5.11+, Mockito 5.14+, Testcontainers 1.21+ | Never H2 as Postgres stand-in |
+| Mutation | PIT (Pitest) 1.16+ | Target ≥70% on domain/ + application/ |
+| Observability | Micrometer Observation API + OpenTelemetry SDK | Tracing W3C Trace Context; HTTP/3 native |
+| HTTP Client | RestClient + `@HttpExchange` declarative interfaces | RestTemplate **deprecated** in SB 4 |
+
+## 3. Project structure (DDD)
+
+```
+backend/
+├── src/main/java/com/<company>/<project>/
+│   ├── domain/           ← pure POJOs (record-friendly), value objects, domain services, repository PORTS (interfaces)
+│   ├── application/      ← use cases (1 public method each), record DTOs req/res, mappers
+│   ├── infrastructure/   ← JPA adapters, JpaRepository, RestClient + @HttpExchange adapters, security, config
+│   └── web/              ← @RestController, @RestControllerAdvice, filters
+├── src/main/resources/
+│   ├── application.yml
+│   ├── application-{dev,prod}.yml
+│   └── db/migration/V<ts>__<verb>_<subject>.sql   ← Flyway migrations
+└── src/test/java/com/<company>/<project>/
+    ├── <pkg>...Test.java   ← unit (JUnit 5 + Mockito)
+    └── <pkg>...IT.java     ← integration (Testcontainers Postgres 16)
+```
+
+## 4. Code patterns
+
+### DTOs as records (req/res separated, Java 25 idioms)
+
+```java
+// application/dto/CreateProductRequest.java
+public record CreateProductRequest(
+    @NotBlank @Size(max = 120) String name,
+    @NotNull @Positive BigDecimal price,
+    @NotNull @PositiveOrZero Integer stock
+) {}
+
+// application/dto/ProductResponse.java
+public record ProductResponse(
+    UUID id, String name, BigDecimal price, Integer stock, Instant createdAt
+) {
+    public static ProductResponse from(Product p) {
+        return new ProductResponse(p.id(), p.name(), p.price(), p.stock(), p.createdAt());
+    }
+}
+```
+
+**Rule**: never expose JPA `@Entity` to controllers. Mapper layer is explicit. Records are the default; use sealed interfaces for domain ADTs (e.g. `sealed interface PaymentResult permits Success, Declined, GatewayError`).
+
+### Controller + ProblemDetail (RFC 9457, SB 4 enhancements)
+
+```java
+@RestController
+@RequestMapping("/api/v1/products")
+public class ProductController {
+    private final CreateProductUseCase createUseCase;
+
+    public ProductController(CreateProductUseCase createUseCase) {
+        this.createUseCase = createUseCase;
+    }
+
+    @PostMapping
+    @ResponseStatus(HttpStatus.CREATED)
+    public ProductResponse create(@Valid @RequestBody CreateProductRequest req) {
+        return createUseCase.execute(req);
+    }
+}
+
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
+        var pd = ProblemDetail.forStatus(HttpStatus.UNPROCESSABLE_ENTITY);
+        pd.setTitle("Validation failed");
+        // SB 4: MDC correlation ID auto-injected into ProblemDetail "instance"
+        pd.setProperty("traceId", MDC.get("traceId"));
+        pd.setProperty("errors", ex.getBindingResult().getFieldErrors().stream()
+            .map(e -> Map.of("field", e.getField(), "msg", e.getDefaultMessage()))
+            .toList());
+        return pd;
+    }
+}
+```
+
+### Pattern matching for switch (Java 25, sealed domain results)
+
+```java
+sealed interface PaymentResult permits Success, Declined, GatewayError {}
+record Success(UUID txId) implements PaymentResult {}
+record Declined(String reason) implements PaymentResult {}
+record GatewayError(int status, String body) implements PaymentResult {}
+
+// in use case:
+return switch (gateway.charge(cmd)) {
+    case Success s        -> ProductResponse.confirmed(s.txId());
+    case Declined d       -> throw new PaymentDeclinedException(d.reason());
+    case GatewayError ge  -> throw new PaymentGatewayException(ge.status(), ge.body());
+};
+```
+
+### Transactions
+
+- `@Transactional(readOnly = true)` on query methods (avoids dirty-check overhead).
+- `@Transactional` on commands. Propagation = REQUIRED (default). Explicit `REQUIRES_NEW` only with documented reason.
+- Never `@Transactional` on controllers — keep on `application/` use cases.
+- SB 4: transactional methods run on virtual threads by default when invoked from a virtual-thread context.
+
+### External calls — `@HttpExchange` (declarative, preferred in SB 4)
+
+```java
+// infrastructure/adapter/PaymentGatewayClient.java
+@HttpExchange(url = "/charges", accept = "application/json", contentType = "application/json")
+public interface PaymentGatewayClient {
+    @PostExchange
+    PaymentResult charge(@RequestBody ChargeCommand cmd);
+}
+
+// infrastructure/config/HttpClientConfig.java
+@Configuration
+public class HttpClientConfig {
+    @Bean
+    PaymentGatewayClient paymentGatewayClient(RestClient.Builder builder, AppProps props) {
+        var restClient = builder
+            .baseUrl(props.paymentGatewayUrl())
+            .requestFactory(ClientHttpRequestFactoryBuilder.detect()
+                .build(ClientHttpRequestFactorySettings.defaults()
+                    .withConnectTimeout(Duration.ofSeconds(3))
+                    .withReadTimeout(Duration.ofSeconds(10))))
+            .build();
+        var adapter = RestClientAdapter.create(restClient);
+        return HttpServiceProxyFactory.builderFor(adapter).build()
+            .createClient(PaymentGatewayClient.class);
+    }
+}
+```
+
+**Rules**: explicit timeout (connect + read), retry + circuit breaker via Resilience4j on external calls. Map foreign exceptions to domain exceptions. Prefer `@HttpExchange` for typed clients; fall back to `RestClient` directly only when streaming or dynamic URLs.
+
+### Virtual Threads (default in SB 4)
+
+```yaml
+# application.yml
+spring:
+  threads:
+    virtual:
+      enabled: true   # default true in SB 4 — listed here for explicitness
+```
+
+```java
+// CompletableFuture on virtual thread executor
+@Bean
+ExecutorService virtualExecutor() {
+    return Executors.newVirtualThreadPerTaskExecutor();
+}
+```
+
+### Pagination
+
+```java
+@GetMapping
+public Page<ProductResponse> list(Pageable pageable) {
+    return service.findAll(pageable).map(ProductResponse::from);
+}
+```
+
+Client passes `?page=0&size=20&sort=name,asc`. Response wraps `content`, `totalElements`, `totalPages`, `number`, `size`.
+
+## 5. Testing
+
+### Unit (JUnit 5.11 + Mockito 5.14 + AssertJ)
+
+```java
+@ExtendWith(MockitoExtension.class)
+class CreateProductUseCaseTest {
+    @Mock ProductRepository repo;
+    @InjectMocks CreateProductUseCase useCase;
+
+    @Test
+    void rejectsNegativePrice() {
+        var cmd = new CreateProductCommand("widget", BigDecimal.valueOf(-1), 10);
+        assertThatThrownBy(() -> useCase.execute(cmd))
+            .isInstanceOf(BusinessRuleException.class)
+            .hasMessageContaining("price");
+    }
+}
+```
+
+### Integration (Testcontainers 1.21, NEVER H2)
+
+```java
+@SpringBootTest
+@Testcontainers
+@ActiveProfiles("test")
+class ProductRepositoryIT {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
+
+    @DynamicPropertySource
+    static void props(DynamicPropertyRegistry r) {
+        r.add("spring.datasource.url", postgres::getJdbcUrl);
+        r.add("spring.datasource.username", postgres::getUsername);
+        r.add("spring.datasource.password", postgres::getPassword);
+    }
+
+    @Autowired ProductRepository repo;
+    // ...
+}
+```
+
+### Web slice (@WebMvcTest, SB 4 supports MockMvcTester fluent API)
+
+```java
+@WebMvcTest(ProductController.class)
+class ProductControllerTest {
+    @Autowired MockMvcTester mvc;            // SB 4 fluent assertions
+    @MockitoBean CreateProductUseCase useCase;
+
+    @Test
+    void returns422OnInvalidPayload() {
+        assertThat(mvc.post().uri("/api/v1/products")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("{}"))
+            .hasStatus(HttpStatus.UNPROCESSABLE_ENTITY)
+            .bodyJson().extractingPath("$.title").isEqualTo("Validation failed");
+    }
+}
+```
+
+### Mutation (PIT 1.16+)
+
+Target ≥ 70% on `domain/` + `application/`. Run via:
+```bash
+./mvnw pitest:mutationCoverage
+```
+
+### Native image smoke (optional, AOT first-class in SB 4)
+
+```bash
+./mvnw -Pnative native:compile
+./target/<app> --spring.profiles.active=test
+```
+
+## 6. Build & run commands
+
+```bash
+./mvnw clean verify                                  # full build + tests + coverage
+./mvnw spring-boot:run                               # local dev (port 8080), virtual threads on
+./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
+./mvnw spring-boot:test-run                          # hot-reload (devtools)
+./mvnw native:compile                                # AOT native image (SB 4 first-class)
+./mvnw spotbugs:check                                # static analysis
+./mvnw org.owasp:dependency-check-maven:check        # CVE scan
+./mvnw pitest:mutationCoverage                       # mutation testing
+./mvnw jacoco:report                                 # coverage report
+```
+
+## 7. Security (per ADR-007 + ADR-027 — MANDATORY section)
+
+### 7.1 Authentication & Authorization
+
+- **Spring Security 7** with `SecurityFilterChain` Bean (NEVER `WebSecurityConfigurerAdapter` — removed since SS 6).
+- **JWT validation** via `spring-boot-starter-oauth2-resource-server`; new SS 7 DSL is more sucinto.
+- **`@PreAuthorize`** on controller methods or use cases. Avoid URL-based authorization for fine-grained rules.
+- **Password hashing**: `BCryptPasswordEncoder(strength = 12)` ou Argon2 quando disponível. NEVER MD5/SHA1.
+
+```java
+@Configuration
+@EnableMethodSecurity
+public class SecurityConfig {
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+            .csrf(CsrfConfigurer::disable)  // stateless API; enable for stateful UI
+            .cors(Customizer.withDefaults())
+            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/v1/auth/**", "/actuator/health").permitAll()
+                .anyRequest().authenticated()
+            )
+            .oauth2ResourceServer(oauth -> oauth.jwt())   // SS 7 sucinto DSL
+            .headers(h -> h
+                .contentSecurityPolicy(csp -> csp.policyDirectives("default-src 'self'"))
+                .httpStrictTransportSecurity(hsts -> hsts.maxAgeInSeconds(31536000).includeSubDomains(true))
+                .frameOptions(FrameOptionsConfig::deny)
+            )
+            .build();
+    }
+}
+```
+
+### 7.2 CORS
+
+NEVER `*` in production. Explicit list:
+
+```java
+@Bean
+public CorsConfigurationSource corsConfigurationSource() {
+    var config = new CorsConfiguration();
+    config.setAllowedOrigins(List.of("https://app.example.com"));
+    config.setAllowedMethods(List.of("GET","POST","PUT","DELETE","OPTIONS"));
+    config.setAllowedHeaders(List.of("Authorization","Content-Type"));
+    config.setAllowCredentials(true);
+    config.setMaxAge(3600L);
+    var source = new UrlBasedCorsConfigurationSource();
+    source.registerCorsConfiguration("/api/**", config);
+    return source;
+}
+```
+
+### 7.3 Validation & input sanitization
+
+- **All `@RequestBody`** must be `@Valid`. ProblemDetail returns 422 on violation.
+- **HTML/XSS**: sanitize via OWASP Java HTML Sanitizer if rendering user input back. Never trust client.
+- **SQL injection**: NEVER concatenate. Use `@Query` with named params, Specifications, or JPA Criteria.
+- **Path traversal**: validate file paths against allowlist; reject `..` sequences; resolve to canonical path before comparison.
+- **Deserialization**: Jackson with `FAIL_ON_UNKNOWN_PROPERTIES=true` for inbound DTOs.
+
+### 7.4 Secrets management
+
+- NEVER in `application.properties` or `application.yml` committed to git.
+- Use environment variables (`spring.datasource.password=${DB_PASSWORD}`) or Spring Cloud Config + Vault.
+- Local dev: `application-local.yml` in `.gitignore` OR `~/.secrets/<project>.env`.
+- Production: Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager.
+- SB 4: `spring.config.import=optional:vault://...` mais robusto que SB 3.
+
+### 7.5 Rate limiting
+
+For public endpoints (login, signup, password reset) — Bucket4j 8.x:
+
+```java
+@Component
+public class RateLimitFilter extends OncePerRequestFilter {
+    private final Bucket bucket = Bucket.builder()
+        .addLimit(limit -> limit.capacity(10).refillIntervally(10, Duration.ofMinutes(1)))
+        .build();
+    // applies on /api/v1/auth/*
+}
+```
+
+For distributed rate limiting, prefer Redis-backed Bucket4j (`bucket4j-redis`) or API Gateway (Kong / Spring Cloud Gateway).
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in this stack |
+|---|---|
+| A01 Broken Access Control | `@PreAuthorize` + IDOR check (always validate principal owns resource) |
+| A02 Cryptographic Failures | BCrypt 12 / Argon2; JWT signed RS256 (never HS256 in distributed system); HTTPS/HTTP3 only |
+| A03 Injection | JPA parameterized queries; never `String.format` SQL; input validation |
+| A04 Insecure Design | Threat model + ADR for new bounded contexts; sealed domain types to constrain states |
+| A05 Security Misconfiguration | SecurityFilterChain explicit; headers via `.headers()`; `/actuator/*` restricted; native image reduces attack surface |
+| A06 Vulnerable Components | OWASP dependency-check in CI; Renovate/Dependabot bumps; SBOM via CycloneDX Maven plugin |
+| A07 Auth Failures | Rate limit on auth; `@Lock` on user account after N failures; MFA where critical |
+| A08 Data Integrity | JWT signature; Maven artifact checksums; supply chain via SBOM + Sigstore |
+| A09 Logging Failures | Structured JSON logs + correlation ID via MDC; AUDIT topic separated; PII never logged |
+| A10 SSRF | Allowlist of outbound hosts in `application.yml`; `@HttpExchange` client validates URL against list |
+
+### 7.7 LGPD specifics (if applicable)
+
+- Identify PII fields (email, CPF, phone) and tag with `@JsonIgnore` on logging serializers.
+- Right to deletion: implement soft-delete + audit log of deletion request.
+- Data subject access: endpoint to export user's data in machine-readable format (JSON/CSV).
+- Encryption at rest for sensitive columns (e.g. via JPA `AttributeConverter` + AES-256-GCM).
+- ANPD breach notification: alarme automático em `security-engineer` quando audit log detecta acesso anômalo.
+
+## 8. Anti-patterns (block in code-review)
+
+| ❌ Bad | ✅ Good | Why |
+|---|---|---|
+| `@Entity` returned from controller | `@Entity` → mapper → `record Response` | Decouples API contract from DB |
+| `javax.validation.constraints.*` | `jakarta.validation.constraints.*` | SB 3/4 use jakarta namespace |
+| `WebSecurityConfigurerAdapter` | `SecurityFilterChain` Bean | Removed in Spring Security 6+ |
+| `RestTemplate` for new code | `@HttpExchange` or `RestClient` | RestTemplate deprecated in SB 4 |
+| Hibernate 5 patterns (`SessionFactory`) | Hibernate 7 + `EntityManager` | Hibernate 5 incompatible with jakarta |
+| `H2` in tests | `Testcontainers` Postgres 16 | H2 has different SQL dialect |
+| `@Autowired` field injection | Constructor injection | Testable, immutable, final fields |
+| `var` in method signature | Full type in signature | Public API contract should be explicit |
+| `// TODO` committed | `docs/brain/architecture/tech-debt.md` | Trackable |
+| `log.info(token)` | `log.info("token=***")` redaction | Never log credentials/PII |
+| `password.equals(input)` | `passwordEncoder.matches(input, hash)` | Timing-safe + hashed comparison |
+| Platform thread executor for blocking I/O | `Executors.newVirtualThreadPerTaskExecutor()` | Java 25 virtual threads — sem custo de pool |
+| Imperative `if/else` cascading on sealed type | Pattern matching `switch` (Java 25) | Compiler enforces exhaustiveness |
+
+## 9. Migration hints — Spring Boot 4.x → 5.x
+
+When SB 5 is released (speculative, expected ~2027):
+
+- Java baseline likely 26 or 27 LTS. Plan upgrade of Java version first.
+- Spring Security 8: review breaking changes in OAuth2 / WebAuthn DSL.
+- Virtual Threads possibly default em todos os sinks (incluindo JPA).
+- Possible removal of `RestTemplate` (final deprecation).
+- AOT/native compile likely required for production by default.
+- Use `migrator` agent — it tracks both SB 4 and SB 5 packs and proposes ADR per major cross.
+
+For migrations **from** SB 3.x **to** SB 4.x, see `spring-boot-3.md` section 9 ("Migration hints").
+
+## 10. References
+
+- ADR-007 (Senior+ gate thresholds — apply to projects using this pack)
+- ADR-026 (Generic agents + packs architecture)
+- ADR-027 (Pack governance — frontmatter + security review schedule)
+- ADR-029 (Canonical pack format)
+- Spring Boot 4.x release notes: https://github.com/spring-projects/spring-boot/wiki
+- Spring Security 7 reference: https://docs.spring.io/spring-security/reference/
+- Java 25 release notes: https://openjdk.org/projects/jdk/25/
+- OWASP Top 10 (2021): https://owasp.org/Top10/
+- Jakarta EE 11 release notes: https://jakarta.ee/release/11/