GET /api/materials?type=BOOK&page=0&size=20 HTTP/1.1
Host: bibliotech.nexussoftware.com
Accept: application/json
User-Agent: curl/8.5.0

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 284

{"content":[{"isbn":"978-0000000001","title":"Effective Java","type":"BOOK"}],
 "page":{"size":20,"number":0,"totalElements":3,"totalPages":1}}

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

// CatalogServer, module 9: you wrote it, all of it
public void serve(Socket client) throws IOException {
    try (var in = new BufferedReader(new InputStreamReader(client.getInputStream(), UTF_8));
         var out = new PrintWriter(client.getOutputStream(), true)) {

        String request = in.readLine();                // "FIND 978-0000000001"
        String[] parts = request.split(" ", 2);        // protocol parsing

        switch (parts[0]) {                            // routing
            case "FIND" -> {
                Optional<Material> m = catalog.byIsbn(parts[1]);
                if (m.isPresent()) {
                    out.println("OK " + serialise(m.get()));        // serialisation
                } else {
                    out.println("ERROR 404 Not found");             // error code
                }
            }
            case "LIST" -> out.println("OK " + serialise(catalog.all()));
            default -> out.println("ERROR 400 Unknown command");
        }
    }
}

@RestController
@RequestMapping("/api/materials")
public class CatalogController {

    private final QueryCatalog catalog;

    @GetMapping("/{isbn}")
    public MaterialResponse byIsbn(@PathVariable Isbn isbn) {
        return catalog.byIsbn(isbn)
                .map(MaterialResponse::from)
                .orElseThrow(() -> new MaterialNotFoundException(isbn));
    }
}

POST /api/loans HTTP/1.1
Idempotency-Key: 3f2504e0-4f89-11d3-9a0c-0305e82c3301
Content-Type: application/json

{"isbn":"978-0000000001","employeeId":1,"days":15}

# Option A: a subresource that represents the event. The preferred one.
POST /api/loans/42/return

# Option B: PATCH on the status
PATCH /api/loans/42
{"status": "RETURNED"}

# Option C: a verb in the path. Pragmatic, and acceptable used sparingly.
POST /api/loans/42/returnLoan

package com.nexussoftware.bibliotech.web.catalog;

@RestController                              // = @Controller + @ResponseBody
@RequestMapping("/api/materials")            // prefix shared by every method
public class CatalogController {

    private final QueryCatalog catalog;
    private final ManageCatalog management;

    public CatalogController(QueryCatalog catalog, ManageCatalog management) {
        this.catalog = catalog;
        this.management = management;
    }

    @GetMapping
    public PageResponse<MaterialResponse> list(@Valid MaterialCriteriaRequest criteria,
                                               Pageable pageable) { … }

    @GetMapping("/{isbn}")
    public MaterialResponse byIsbn(@PathVariable Isbn isbn) { … }

    @PostMapping
    public ResponseEntity<MaterialResponse> create(@Valid @RequestBody CreateMaterialRequest request) { … }

    @PutMapping("/{isbn}")
    public MaterialResponse replace(@PathVariable Isbn isbn,
                                    @Valid @RequestBody UpdateMaterialRequest request) { … }

    @PatchMapping("/{isbn}/copies")
    public MaterialResponse adjustCopies(@PathVariable Isbn isbn,
                                         @Valid @RequestBody AdjustCopiesRequest request) { … }

    @DeleteMapping("/{isbn}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable Isbn isbn) { … }
}

@GetMapping(value = "/{isbn}", produces = MediaType.APPLICATION_JSON_VALUE)
@PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
@GetMapping(value = "/{isbn}", produces = "text/csv")          // content negotiation
@GetMapping(params = "format=summary")                         // based on a parameter
@GetMapping(headers = "X-Api-Version=2")                       // based on a header

@GetMapping("/{isbn}/loans")
public List<LoanResponse> history(

        // Part of the path: identifies the resource
        @PathVariable Isbn isbn,

        // A required query parameter
        @RequestParam LoanStatus status,

        // Optional with a default value
        @RequestParam(defaultValue = "10") int limit,

        // Genuinely optional: Optional (10-04)
        @RequestParam Optional<LocalDate> from,

        // A name different from the Java parameter's
        @RequestParam(name = "sort_by", defaultValue = "DATE") SortCriterion sort,

        // Repeatable: ?tag=java&tag=design
        @RequestParam(required = false) List<String> tag,

        // A header
        @RequestHeader(value = "Accept-Language", defaultValue = "en") Locale language) { … }

@PostMapping
public ResponseEntity<LoanResponse> create(@Valid @RequestBody CreateLoanRequest request) { … }

@Component
public class StringToIsbnConverter implements Converter<String, Isbn> {

    @Override
    public Isbn convert(String text) {
        try {
            return Isbn.of(text);
        } catch (InvalidIsbnException e) {
            // IllegalArgumentException → Spring translates it into a 400, not a 500
            throw new IllegalArgumentException("Invalid ISBN: " + text, e);
        }
    }
}

@GetMapping("/{isbn}")
public MaterialResponse byIsbn(@PathVariable Isbn isbn) { … }     // 200 + JSON

@PostMapping
public ResponseEntity<LoanResponse> create(@Valid @RequestBody CreateLoanRequest request) {
    Loan created = manager.lend(request.isbn(), request.employeeId(), request.days());

    URI location = ServletUriComponentsBuilder
            .fromCurrentRequest()          // http://host/api/loans
            .path("/{id}")
            .buildAndExpand(created.getId())
            .toUri();                      // http://host/api/loans/42

    return ResponseEntity.created(location).body(LoanResponse.from(created));
}

@PutMapping("/{isbn}")
public ResponseEntity<MaterialResponse> replace(@PathVariable Isbn isbn,
                                                @Valid @RequestBody UpdateMaterialRequest r) {
    UpdateResult result = management.createOrUpdate(isbn, r);

    return result.wasCreated()
            ? ResponseEntity.status(HttpStatus.CREATED).body(MaterialResponse.from(result.material()))
            : ResponseEntity.ok(MaterialResponse.from(result.material()));
}

@GetMapping("/{isbn}")
public ResponseEntity<MaterialResponse> byIsbn(@PathVariable Isbn isbn) {
    Material material = catalog.byIsbn(isbn).orElseThrow(() -> new MaterialNotFoundException(isbn));

    return ResponseEntity.ok()
            .eTag("\"" + material.getVersion() + "\"")     // JPA's @Version used as the ETag
            .cacheControl(CacheControl.maxAge(5, TimeUnit.MINUTES).cachePublic())
            .body(MaterialResponse.from(material));
}

@DeleteMapping("/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)      // 204
public void cancel(@PathVariable Long id) { reservations.cancel(id); }

package com.nexussoftware.bibliotech.web.loans;

@Schema(description = "Information about a loan")            // OpenAPI documentation
public record LoanResponse(

        @Schema(example = "42") Long id,
        @Schema(example = "978-0000000001") String isbn,
        @Schema(example = "Effective Java") String materialTitle,
        @Schema(example = "Marta Ruiz") String employeeName,
        LocalDate loanDate,
        LocalDate dueDate,

        @Schema(description = "Null if the material is still on loan")
        LocalDate returnDate,

        @Schema(example = "ACTIVE") String status,

        @Schema(description = "Negative if it is overdue", example = "5")
        long daysRemaining,

        @Schema(example = "2.50") BigDecimal accruedFine) {

    public static LoanResponse from(Loan l, LocalDate today) {
        return new LoanResponse(
                l.getId(),
                l.getIsbn().value(),
                l.materialTitle(),
                l.employeeName(),
                l.getLoanDate(),
                l.getDueDate(),
                l.getReturnDate().orElse(null),          // JSON has no Optional
                l.getStatus().name(),
                ChronoUnit.DAYS.between(today, l.getDueDate()),
                l.accruedFine(today).amount());
    }
}

public record CreateLoanRequest(

        @NotBlank(message = "The ISBN is required")
        @ValidIsbn
        @Schema(example = "978-0000000001")
        String isbn,

        @NotNull(message = "The employee identifier is required")
        @Positive
        Long employeeId,

        @Positive @Max(value = 90, message = "The maximum duration is 90 days")
        @Schema(description = "Loan days. If omitted, the standard one for the material type")
        Integer days) {
}

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

@PostMapping
public ResponseEntity<LoanResponse> create(@Valid @RequestBody CreateLoanRequest request) {
    // If we get here, the request is syntactically valid.
    // If not, Spring has already thrown MethodArgumentNotValidException.
}

@RestController
@Validated                                   // enables validation of standalone parameters
@RequestMapping("/api/materials")
public class CatalogController {

    @GetMapping
    public List<MaterialResponse> list(
            @RequestParam @Size(min = 2, message = "At least 2 characters") String title,
            @RequestParam @Max(100) int limit) { … }
}

@ValidDateRange          // a custom validator: from <= to
public record FinesQueryRequest(
        @NotNull @PastOrPresent LocalDate from,
        @NotNull @PastOrPresent LocalDate to,
        Long employeeId) {
}

package com.nexussoftware.bibliotech.web.validation;

@Documented
@Constraint(validatedBy = IsbnValidator.class)
@Target({ElementType.FIELD, ElementType.PARAMETER, ElementType.RECORD_COMPONENT})
@Retention(RetentionPolicy.RUNTIME)
public @interface ValidIsbn {

    String message() default "Invalid ISBN-13: check the format and the check digit";

    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};

    /** If true, accepts the ISBN with hyphens and spaces. */
    boolean allowSeparators() default true;
}

public class IsbnValidator implements ConstraintValidator<ValidIsbn, String> {

    private static final Pattern WITH_SEPARATORS = Pattern.compile("^97[89][- ]?\\d{1,5}[- ]?\\d+[- ]?\\d+[- ]?\\d$");
    private static final Pattern WITHOUT_SEPARATORS = Pattern.compile("^97[89]\\d{10}$");

    private boolean allowSeparators;

    @Override
    public void initialize(ValidIsbn annotation) {
        this.allowSeparators = annotation.allowSeparators();
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {
        // A null value counts as valid: it is @NotNull that makes a field required.
        // Separating responsibilities between validators is the right thing to do.
        if (value == null) return true;

        String normalised = allowSeparators ? value.replaceAll("[- ]", "") : value;

        if (!WITHOUT_SEPARATORS.matcher(normalised).matches()) {
            message(context, "The ISBN must start with 978 or 979 and have 13 digits");
            return false;
        }
        if (!checkDigitIsCorrect(normalised)) {
            message(context, "The ISBN check digit is not correct");
            return false;
        }
        return true;
    }

    /**
     * The official ISBN-13 algorithm: the first 12 digits are multiplied
     * alternately by 1 and 3 and added up, and the check digit is whatever
     * is missing to reach the next multiple of 10.
     */
    private boolean checkDigitIsCorrect(String isbn) {
        int sum = 0;
        for (int i = 0; i < 12; i++) {
            int digit = isbn.charAt(i) - '0';
            sum += (i % 2 == 0) ? digit : digit * 3;
        }
        int check = (10 - (sum % 10)) % 10;
        return check == (isbn.charAt(12) - '0');
    }

    /** Replaces the generic message with one specific to the actual failure. */
    private void message(ConstraintValidatorContext context, String text) {
        context.disableDefaultConstraintViolation();
        context.buildConstraintViolationWithTemplate(text).addConstraintViolation();
    }
}

{
  "type": "https://bibliotech.nexussoftware.com/errors/loan-limit",
  "title": "Loan limit exceeded",
  "status": 409,
  "detail": "Employee Diego Alonso already has 3 active loans (maximum: 3).",
  "instance": "/api/loans",
  "timestamp": "2026-08-05T10:23:45Z",
  "traceId": "a7f3e91c4b2d",
  "activeLoans": [12, 27, 38]
}

spring:
  mvc:
    problemdetails:
      enabled: true      # Spring's standard exceptions already come out in RFC 7807 format

package com.nexussoftware.bibliotech.web.error;

@RestControllerAdvice
public class GlobalErrorHandler {

    private static final Logger log = LoggerFactory.getLogger(GlobalErrorHandler.class);
    private static final String TYPE_BASE = "https://bibliotech.nexussoftware.com/errors/";

    // ---------- 404 ----------
    @ExceptionHandler({MaterialNotFoundException.class,
                       LoanNotFoundException.class,
                       EmployeeNotFoundException.class})
    public ProblemDetail notFound(ResourceNotFoundException e, HttpServletRequest request) {
        log.info("Resource not found: {}", e.getMessage());        // INFO: not a system failure
        return problem(HttpStatus.NOT_FOUND, "resource-not-found",
                       "Resource not found", e.getMessage(), request);
    }

    // ---------- 409: business rules ----------
    @ExceptionHandler(LoanLimitExceededException.class)
    public ProblemDetail limitExceeded(LoanLimitExceededException e, HttpServletRequest r) {
        ProblemDetail detail = problem(HttpStatus.CONFLICT, "loan-limit",
                "Loan limit exceeded", e.getMessage(), r);
        detail.setProperty("activeLoans", e.getActiveLoanIds());
        detail.setProperty("maxAllowed", e.getMax());
        return detail;
    }

    @ExceptionHandler(MaterialNotAvailableException.class)
    public ProblemDetail notAvailable(MaterialNotAvailableException e, HttpServletRequest r) {
        ProblemDetail detail = problem(HttpStatus.CONFLICT, "material-unavailable",
                "Material not available", e.getMessage(), r);
        e.getExpectedAvailabilityDate()
         .ifPresent(d -> detail.setProperty("expectedAvailableOn", d.toString()));
        return detail;
    }

    // ---------- 409: concurrency conflict (the @Version from 11-03) ----------
    @ExceptionHandler(ObjectOptimisticLockingFailureException.class)
    public ProblemDetail versionConflict(ObjectOptimisticLockingFailureException e,
                                         HttpServletRequest r) {
        log.warn("Optimistic locking conflict on {}", r.getRequestURI());
        return problem(HttpStatus.CONFLICT, "concurrency-conflict",
                "Concurrency conflict",
                "Another user modified this resource while you were editing it. Reload and retry.", r);
    }

    // ---------- 400: body validation ----------
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ProblemDetail validation(MethodArgumentNotValidException e, HttpServletRequest r) {
        List<FieldErrorDto> errors = e.getBindingResult().getFieldErrors().stream()
                .map(f -> new FieldErrorDto(f.getField(), f.getDefaultMessage(), f.getRejectedValue()))
                .toList();

        ProblemDetail detail = problem(HttpStatus.BAD_REQUEST, "validation",
                "Validation error",
                "The request contains %d invalid field(s).".formatted(errors.size()), r);
        detail.setProperty("errors", errors);        // THIS is what makes a 400 useful
        return detail;
    }

    // ---------- 400: parameters and types ----------
    @ExceptionHandler(ConstraintViolationException.class)
    public ProblemDetail invalidParameters(ConstraintViolationException e, HttpServletRequest r) {
        List<FieldErrorDto> errors = e.getConstraintViolations().stream()
                .map(v -> new FieldErrorDto(v.getPropertyPath().toString(), v.getMessage(), v.getInvalidValue()))
                .toList();
        ProblemDetail detail = problem(HttpStatus.BAD_REQUEST, "invalid-parameters",
                "Invalid parameters", "Check the request parameters.", r);
        detail.setProperty("errors", errors);
        return detail;
    }

    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    public ProblemDetail wrongType(MethodArgumentTypeMismatchException e, HttpServletRequest r) {
        String expected = e.getRequiredType() != null ? e.getRequiredType().getSimpleName() : "valid";
        return problem(HttpStatus.BAD_REQUEST, "wrong-type", "Wrong data type",
                "The parameter '%s' with value '%s' is not a %s."
                        .formatted(e.getName(), e.getValue(), expected), r);
    }

    @ExceptionHandler(HttpMessageNotReadableException.class)
    public ProblemDetail unreadableBody(HttpMessageNotReadableException e, HttpServletRequest r) {
        // We do NOT expose e.getMessage(): it reveals the internal structure of the classes
        return problem(HttpStatus.BAD_REQUEST, "invalid-body", "Invalid request body",
                "The body is not valid JSON or does not match the expected format.", r);
    }

    // ---------- 503: external dependency ----------
    @ExceptionHandler(GatewayUnavailableException.class)
    public ResponseEntity<ProblemDetail> serviceDown(GatewayUnavailableException e,
                                                     HttpServletRequest r) {
        log.error("External service unavailable: {}", e.getService(), e);
        ProblemDetail detail = problem(HttpStatus.SERVICE_UNAVAILABLE, "service-unavailable",
                "Service temporarily unavailable",
                "The operation could not be completed. Try again in a few minutes.", r);
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                .header(HttpHeaders.RETRY_AFTER, "60")     // the client knows when to retry
                .body(detail);
    }

    // ---------- 500: the safety net ----------
    @ExceptionHandler(Exception.class)
    public ProblemDetail unexpectedError(Exception e, HttpServletRequest r) {
        String incidentId = UUID.randomUUID().toString().substring(0, 12);
        // The FULL stack trace to the log; to the client, only the identifier (06-07 and 12-07)
        log.error("Unexpected error [id={}] on {} {}", incidentId, r.getMethod(), r.getRequestURI(), e);

        ProblemDetail detail = problem(HttpStatus.INTERNAL_SERVER_ERROR, "internal-error",
                "Internal error",
                "An unexpected error has occurred. If the problem persists, "
                + "contact support quoting the incident identifier.", r);
        detail.setProperty("incidentId", incidentId);
        return detail;
    }

    // ---------- Shared builder ----------
    private ProblemDetail problem(HttpStatus status, String type, String title,
                                  String detailText, HttpServletRequest request) {
        ProblemDetail detail = ProblemDetail.forStatusAndDetail(status, detailText);
        detail.setType(URI.create(TYPE_BASE + type));
        detail.setTitle(title);
        detail.setInstance(URI.create(request.getRequestURI()));
        detail.setProperty("timestamp", Instant.now().toString());
        // The correlation identifier MDC set in 11-07: it ties the response to the log
        detail.setProperty("traceId", MDC.get("traceId"));
        return detail;
    }

    public record FieldErrorDto(String field, String message, Object rejectedValue) { }
}

@GetMapping
public PageResponse<MaterialResponse> list(
        @PageableDefault(size = 20, sort = "title", direction = Sort.Direction.ASC)
        Pageable pageable) {

    Page<Material> page = catalog.search(pageable);
    return PageResponse.from(page.map(MaterialResponse::from));
}

GET /api/materials?page=0&size=20&sort=title,asc
GET /api/materials?page=2&size=50&sort=publicationYear,desc&sort=title,asc

spring:
  data:
    web:
      pageable:
        default-page-size: 20
        max-page-size: 100          # Spring silently trims anything above this
        one-indexed-parameters: false

public record PageResponse<T>(List<T> content, PageMetadata page) {

    public static <T> PageResponse<T> from(Page<T> page) {
        return new PageResponse<>(page.getContent(), new PageMetadata(
                page.getNumber(), page.getSize(), page.getTotalElements(),
                page.getTotalPages(), page.isFirst(), page.isLast()));
    }

    public record PageMetadata(int number, int size, long totalElements,
                               int totalPages, boolean first, boolean last) { }
}

{
  "content": [ { "isbn": "978-0000000001", "title": "Effective Java", "…": "…" } ],
  "page": { "number": 0, "size": 20, "totalElements": 3,
            "totalPages": 1, "first": true, "last": true }
}

public record MaterialCriteriaRequest(
        @Size(min = 2, max = 100) String title,
        @Size(min = 2, max = 100) String author,
        MaterialType type,
        @Min(1450) Integer yearFrom,           // the year of the printing press: a sensible floor
        @Max(2100) Integer yearTo,
        Boolean onlyAvailable) {

    public SearchCriteria toDomain() {
        return SearchCriteria.builder()        // the Builder from 12-02
                .title(title).author(author).type(type)
                .between(yearFrom, yearTo)
                .onlyAvailable(Boolean.TRUE.equals(onlyAvailable))
                .build();
    }
}

@GetMapping
public PageResponse<MaterialResponse> list(@Valid MaterialCriteriaRequest criteria,
                                           @PageableDefault(size = 20) Pageable pageable) {
    Page<Material> results = catalog.search(criteria.toDomain(), pageable);
    return PageResponse.from(results.map(MaterialResponse::from));
}

GET /api/materials?title=java&type=BOOK&onlyAvailable=true&page=0&size=10

public Page<Material> search(SearchCriteria criteria, Pageable pageable) {
    Specification<Material> spec = Specification.where(null);

    if (criteria.title() != null) {
        spec = spec.and((root, query, cb) ->
                cb.like(cb.lower(root.get("title")), "%" + criteria.title().toLowerCase() + "%"));
    }
    if (criteria.type() != null) {
        spec = spec.and((root, query, cb) -> cb.equal(root.get("type"), criteria.type()));
    }
    if (criteria.onlyAvailable()) {
        spec = spec.and((root, query, cb) -> cb.greaterThan(root.get("availableCopies"), 0));
    }
    return repository.findAll(spec, pageable);
}

curl -i -X POST http://localhost:8080/api/loans \
  -H "Content-Type: application/json" \
  -d '{"isbn":"978-0000000001","employeeId":1,"days":15}'

HTTP/1.1 201 Created
Location: http://localhost:8080/api/loans/42
Content-Type: application/json

{
  "id": 42,
  "isbn": "978-0000000001",
  "materialTitle": "Effective Java",
  "employeeName": "Marta Ruiz",
  "loanDate": "2026-08-05",
  "dueDate": "2026-08-20",
  "returnDate": null,
  "status": "ACTIVE",
  "daysRemaining": 15,
  "accruedFine": 0.00
}

curl -i -X POST http://localhost:8080/api/loans \
  -H "Content-Type: application/json" \
  -d '{"isbn":"978-0000000003","employeeId":2,"days":15}'

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://bibliotech.nexussoftware.com/errors/loan-limit",
  "title": "Loan limit exceeded",
  "status": 409,
  "detail": "Employee Diego Alonso already has 3 active loans (maximum: 3).",
  "instance": "/api/loans",
  "timestamp": "2026-08-05T10:23:45Z",
  "traceId": "a7f3e91c4b2d",
  "activeLoans": [12, 27, 38],
  "maxAllowed": 3
}

curl -i -X POST http://localhost:8080/api/loans \
  -H "Content-Type: application/json" \
  -d '{"isbn":"1234","employeeId":null,"days":365}'

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://bibliotech.nexussoftware.com/errors/validation",
  "title": "Validation error",
  "status": 400,
  "detail": "The request contains 3 invalid field(s).",
  "instance": "/api/loans",
  "errors": [
    {"field": "isbn", "message": "The ISBN must start with 978 or 979 and have 13 digits",
     "rejectedValue": "1234"},
    {"field": "employeeId", "message": "The employee identifier is required",
     "rejectedValue": null},
    {"field": "days", "message": "The maximum duration is 90 days", "rejectedValue": 365}
  ]
}

curl -i -X POST http://localhost:8080/api/loans/42/return \
  -H "Content-Type: application/json" -d '{"date":"2026-08-25"}'

HTTP/1.1 200 OK

{
  "loanId": 42,
  "returnDate": "2026-08-25",
  "daysLate": 5,
  "fine": 2.50,
  "status": "RETURNED"
}

curl "http://localhost:8080/api/materials?title=des&type=BOOK&page=0&size=5&sort=title,asc"

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

@RestController
@RequestMapping("/api/loans")
@Tag(name = "Loans", description = "Management of material loans to employees")
public class LoanController {

    @Operation(
        summary = "Creates a loan",
        description = """
                Lends a material to an employee. Checks that there are copies available
                and that the employee does not exceed the active-loan limit.

                If no duration is given, the standard one for the material type is used:
                15 days for books, 7 for magazines and 3 for DVDs.""")
    @ApiResponses({
        @ApiResponse(responseCode = "201", description = "Loan created",
            content = @Content(schema = @Schema(implementation = LoanResponse.class))),
        @ApiResponse(responseCode = "400", description = "Invalid request",
            content = @Content(schema = @Schema(implementation = ProblemDetail.class))),
        @ApiResponse(responseCode = "404", description = "Material or employee does not exist",
            content = @Content(schema = @Schema(implementation = ProblemDetail.class))),
        @ApiResponse(responseCode = "409", description = "No free copies or limit exceeded",
            content = @Content(schema = @Schema(implementation = ProblemDetail.class)))
    })
    @PostMapping
    public ResponseEntity<LoanResponse> create(@Valid @RequestBody CreateLoanRequest request) { … }
}

@Configuration
public class OpenApiConfiguration {

    @Bean
    OpenAPI biblioTechApi(@Value("${bibliotech.version}") String version) {
        return new OpenAPI()
                .info(new Info()
                        .title("BiblioTech API")
                        .version(version)
                        .description("Management of Nexus Software's internal technical library.")
                        .contact(new Contact().name("Platform team")
                                              .email("[email protected]")))
                .servers(List.of(
                        new Server().url("http://localhost:8080").description("Development"),
                        new Server().url("https://bibliotech.nexussoftware.com").description("Production")));
    }
}

springdoc:
  swagger-ui:
    enabled: false        # in prod
  api-docs:
    path: /v3/api-docs

OPTIONS /api/loans HTTP/1.1
Origin: https://intranet.nexussoftware.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://intranet.nexussoftware.com
Access-Control-Allow-Methods: GET,POST,PUT,DELETE
Access-Control-Allow-Headers: content-type
Access-Control-Max-Age: 3600

@Configuration
public class WebCorsConfiguration implements WebMvcConfigurer {

    private final List<String> allowedOrigins;        // from application.yml, per environment

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins(allowedOrigins.toArray(String[]::new))
                .allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE")
                .allowedHeaders("Content-Type", "Authorization")
                .exposedHeaders("Location")            // so the client can read it after a 201
                .allowCredentials(true)
                .maxAge(3600);                         // cache the preflight response for 1 hour
    }
}

# dev
bibliotech:
  cors:
    origins: ["http://localhost:5173", "http://localhost:3000"]
# prod
bibliotech:
  cors:
    origins: ["https://intranet.nexussoftware.com"]

// BAD: the transaction in the controller
@RestController
public class LoanController {
    @PostMapping
    @Transactional                          // ← no
    public LoanResponse create(@RequestBody CreateLoanRequest r) { … }
}

// GOOD: the transaction, in the use case
@Service
public class LoanManager implements ManageLoans {

    @Override
    @Transactional                                  // write
    public Loan lend(Isbn isbn, Long employeeId, Integer days) { … }

    @Override
    @Transactional(readOnly = true)                 // read: Hibernate skips dirty checking
    public Optional<Loan> find(Long id) { … }
}

// And the controller only translates HTTP
@PostMapping
public ResponseEntity<LoanResponse> create(@Valid @RequestBody CreateLoanRequest r) {
    Loan created = manager.lend(r.isbn(), r.employeeId(), r.days());
    return ResponseEntity.created(uriOf(created)).body(LoanResponse.from(created, today()));
}

spring:
  jpa:
    open-in-view: false

@WebMvcTest(LoanController.class)
class LoanControllerTest {

    @Autowired MockMvc mvc;
    @Autowired ObjectMapper json;

    @MockitoBean ManageLoans manager;            // Spring Boot 3.4+; it used to be @MockBean

    @Test
    void returns201AndLocationWhenCreatingALoan() throws Exception {
        var created = aLoan(42L, "978-0000000001", "Marta Ruiz");
        when(manager.lend(any(), eq(1L), eq(15))).thenReturn(created);

        mvc.perform(post("/api/loans")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"isbn":"978-0000000001","employeeId":1,"days":15}"""))
                .andExpect(status().isCreated())
                .andExpect(header().string("Location", endsWith("/api/loans/42")))
                .andExpect(jsonPath("$.id").value(42))
                .andExpect(jsonPath("$.materialTitle").value("Effective Java"))
                .andExpect(jsonPath("$.status").value("ACTIVE"));
    }

    @Test
    void returns400WithTheDetailOfEveryInvalidField() throws Exception {
        mvc.perform(post("/api/loans")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"isbn":"1234","employeeId":null,"days":365}"""))
                .andExpect(status().isBadRequest())
                .andExpect(content().contentTypeCompatibleWith("application/problem+json"))
                .andExpect(jsonPath("$.title").value("Validation error"))
                .andExpect(jsonPath("$.errors", hasSize(3)))
                .andExpect(jsonPath("$.errors[*].field",
                        containsInAnyOrder("isbn", "employeeId", "days")));

        // With invalid data, the use case must NOT have been invoked
        verifyNoInteractions(manager);
    }

    @Test
    void returns409WithDetailWhenTheLimitIsExceeded() throws Exception {
        when(manager.lend(any(), eq(2L), any()))
                .thenThrow(new LoanLimitExceededException(2L, "Diego Alonso", 3,
                                                          List.of(12L, 27L, 38L)));

        mvc.perform(post("/api/loans")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"isbn":"978-0000000003","employeeId":2,"days":15}"""))
                .andExpect(status().isConflict())
                .andExpect(jsonPath("$.type").value(endsWith("/errors/loan-limit")))
                .andExpect(jsonPath("$.detail").value(containsString("Diego Alonso")))
                .andExpect(jsonPath("$.activeLoans", hasSize(3)));
    }

    @Test
    void returns404WhenTheLoanDoesNotExist() throws Exception {
        when(manager.find(9999L)).thenReturn(Optional.empty());

        mvc.perform(get("/api/loans/9999"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.status").value(404));
    }

    @Test
    void returns400WhenTheIsbnInThePathIsInvalid() throws Exception {
        mvc.perform(get("/api/materials/not-an-isbn"))
                .andExpect(status().isBadRequest());
    }
}

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class LoanApiIT {

    @Autowired TestRestTemplate client;
    @Autowired LoanRepository repository;

    @Test
    void fullLoanAndReturnCycle() {
        // 1. Create
        var request = new CreateLoanRequest("978-0000000001", 1L, 15);
        ResponseEntity<LoanResponse> creation =
                client.postForEntity("/api/loans", request, LoanResponse.class);

        assertThat(creation.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        assertThat(creation.getHeaders().getLocation()).isNotNull();
        Long id = creation.getBody().id();

        // 2. Query it through the URI that Location returned
        ResponseEntity<LoanResponse> query =
                client.getForEntity(creation.getHeaders().getLocation(), LoanResponse.class);
        assertThat(query.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(query.getBody().status()).isEqualTo("ACTIVE");

        // 3. Return it
        ResponseEntity<ReturnResponse> returning = client.postForEntity(
                "/api/loans/{id}/return", new ReturnRequest(null),
                ReturnResponse.class, id);
        assertThat(returning.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(returning.getBody().fine()).isEqualByComparingTo("0.00");

        // 4. Check that persistence reflects the change
        assertThat(repository.findById(id))
                .get()
                .extracting(Loan::getStatus)
                .isEqualTo(LoanStatus.RETURNED);
    }

    @Test
    void returningTwiceGives409() {
        Long id = createAndReturn();

        ResponseEntity<ProblemDetail> second = client.postForEntity(
                "/api/loans/{id}/return", new ReturnRequest(null),
                ProblemDetail.class, id);

        assertThat(second.getStatusCode()).isEqualTo(HttpStatus.CONFLICT);
        assertThat(second.getBody().getDetail()).contains("has already been returned");
    }
}

@Controller                                   // NOT @RestController!
@RequestMapping("/catalog")
public class CatalogViewController {

    @GetMapping
    public String list(@RequestParam(required = false) String title, Model model) {
        model.addAttribute("materials", catalog.search(title));
        model.addAttribute("filter", title);
        return "catalog/list";                // resolves to templates/catalog/list.html
    }
}

<!-- src/main/resources/templates/catalog/list.html -->
<table>
  <tr th:each="m : ${materials}">
    <td th:text="${m.isbn}">978-…</td>
    <td th:text="${m.title}">Title</td>
    <td th:text="${m.availableCopies}">0</td>
  </tr>
</table>

spring:
  threads:
    virtual:
      enabled: true

@GetMapping("/api/diagnostics/thread")
public Map<String, Object> currentThread() {
    Thread thread = Thread.currentThread();
    return Map.of("name", thread.getName(),
                  "virtual", thread.isVirtual(),
                  "group", String.valueOf(thread.threadId()));
}

{"name":"","virtual":true,"group":"142"}

public record RenewLoanRequest(
        @Min(value = 1, message = "A renewal must be at least 1 day")
        @Max(value = 30, message = "A renewal cannot exceed 30 days")
        Integer days) {
}

public record RenewalResponse(
        Long loanId,
        String materialTitle,
        LocalDate previousDueDate,
        LocalDate newDueDate,
        int daysAdded,
        boolean canBeRenewedAgain) {

    public static RenewalResponse from(Loan l, LocalDate previous) {
        return new RenewalResponse(
                l.getId(), l.materialTitle(), previous, l.getDueDate(),
                (int) ChronoUnit.DAYS.between(previous, l.getDueDate()),
                l.getStatus().allowsRenewal());
    }
}

@PostMapping("/{id}/renewal")
@Operation(summary = "Renews a loan",
           description = "Extends the due date. Only one renewal per loan is allowed.")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "Renewed"),
    @ApiResponse(responseCode = "404", description = "The loan does not exist"),
    @ApiResponse(responseCode = "409", description = "Already renewed, overdue, or with pending reservations")
})
public RenewalResponse renew(
        @PathVariable Long id,
        @RequestBody(required = false) @Valid RenewLoanRequest request) {

    Integer days = (request != null) ? request.days() : null;
    RenewalResult result = manager.renew(id, days);
    return RenewalResponse.from(result.loan(), result.previousDueDate());
}

@Override
@Transactional
public RenewalResult renew(Long id, Integer days) {
    Loan loan = repository.findById(id)
            .orElseThrow(() -> new LoanNotFoundException(id));

    LocalDate today = LocalDate.now(clock);

    // Rule 1: the status governs (State pattern, 12-02)
    if (!loan.getStatus().allowsRenewal()) {
        throw new RenewalNotAllowedException(id, loan.getStatus(),
                "This loan has already been renewed or does not allow renewal.");
    }

    // Rule 2: overdue
    if (loan.isOverdueOn(today)) {
        throw new RenewalNotAllowedException(id, loan.getStatus(),
                "The loan was due on %s. Return it and take it out again."
                        .formatted(loan.getDueDate()));
    }

    // Rule 3: other people's reservations
    long pending = reservations.countPendingFor(loan.getIsbn());
    if (pending > 0) {
        throw new MaterialHasReservationsException(loan.getIsbn(), pending);
    }

    LocalDate previous = loan.getDueDate();
    int effectiveDays = (days != null) ? days : loan.standardDaysForMaterial();
    loan.renew(effectiveDays);                // validates and transitions the status

    return new RenewalResult(loan, previous);
}

@ExceptionHandler(RenewalNotAllowedException.class)
public ProblemDetail renewalNotAllowed(RenewalNotAllowedException e, HttpServletRequest r) {
    ProblemDetail d = problem(HttpStatus.CONFLICT, "renewal-not-allowed",
            "Renewal not allowed", e.getMessage(), r);
    d.setProperty("loanId", e.getLoanId());
    d.setProperty("currentStatus", e.getStatus().name());
    return d;
}

@ExceptionHandler(MaterialHasReservationsException.class)
public ProblemDetail withReservations(MaterialHasReservationsException e, HttpServletRequest r) {
    ProblemDetail d = problem(HttpStatus.CONFLICT, "material-with-reservations",
            "Material with pending reservations",
            "Cannot renew: %d employee(s) are waiting for this material."
                    .formatted(e.getPendingReservations()), r);
    d.setProperty("pendingReservations", e.getPendingReservations());
    return d;
}

@WebMvcTest(LoanController.class)
class RenewalControllerTest {

    @Autowired MockMvc mvc;
    @MockitoBean ManageLoans manager;

    @Test
    void renewsWithTheGivenNumberOfDays() throws Exception {
        var loan = aLoan(42L).withDueDate(LocalDate.of(2026, 8, 20));
        when(manager.renew(42L, 10)).thenReturn(
                new RenewalResult(loan.renewedUntil(LocalDate.of(2026, 8, 30)),
                                  LocalDate.of(2026, 8, 20)));

        mvc.perform(post("/api/loans/42/renewal")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"days":10}"""))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.previousDueDate").value("2026-08-20"))
                .andExpect(jsonPath("$.newDueDate").value("2026-08-30"))
                .andExpect(jsonPath("$.daysAdded").value(10))
                .andExpect(jsonPath("$.canBeRenewedAgain").value(false));
    }

    @Test
    void renewsWithNoBodyUsingTheStandardDuration() throws Exception {
        when(manager.renew(42L, null)).thenReturn(aRenewalOf(15));

        mvc.perform(post("/api/loans/42/renewal"))          // no body
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.daysAdded").value(15));
    }

    @Test
    void returns404IfTheLoanDoesNotExist() throws Exception {
        when(manager.renew(eq(9999L), any())).thenThrow(new LoanNotFoundException(9999L));

        mvc.perform(post("/api/loans/9999/renewal"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.type").value(endsWith("/errors/resource-not-found")));
    }

    @Test
    void returns409IfItWasAlreadyRenewed() throws Exception {
        when(manager.renew(eq(42L), any())).thenThrow(
                new RenewalNotAllowedException(42L, LoanStatus.RENEWED,
                        "This loan has already been renewed or does not allow renewal."));

        mvc.perform(post("/api/loans/42/renewal"))
                .andExpect(status().isConflict())
                .andExpect(jsonPath("$.currentStatus").value("RENEWED"))
                .andExpect(jsonPath("$.detail").value(containsString("already been renewed")));
    }

    @Test
    void returns409IfThereArePendingReservations() throws Exception {
        when(manager.renew(eq(42L), any()))
                .thenThrow(new MaterialHasReservationsException(Isbn.of("978-0000000001"), 2));

        mvc.perform(post("/api/loans/42/renewal"))
                .andExpect(status().isConflict())
                .andExpect(jsonPath("$.pendingReservations").value(2));
    }

    @ParameterizedTest
    @ValueSource(ints = {0, -5, 31, 100})
    void returns400IfTheDaysAreOutOfRange(int days) throws Exception {
        mvc.perform(post("/api/loans/42/renewal")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("{\"days\":%d}".formatted(days)))
                .andExpect(status().isBadRequest())
                .andExpect(jsonPath("$.errors[0].field").value("days"));

        verifyNoInteractions(manager);     // the use case was not even called
    }
}

@Documented
@Constraint(validatedBy = YearRangeValidator.class)
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface ValidYearRange {
    String message() default "yearFrom cannot be later than yearTo";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

public class YearRangeValidator implements ConstraintValidator<ValidYearRange, SearchRequest> {
    @Override
    public boolean isValid(SearchRequest r, ConstraintValidatorContext ctx) {
        if (r.yearFrom() == null || r.yearTo() == null) return true;   // @NotNull is not our job
        if (r.yearFrom() <= r.yearTo()) return true;

        ctx.disableDefaultConstraintViolation();
        ctx.buildConstraintViolationWithTemplate(
                "yearFrom (%d) cannot be later than yearTo (%d)"
                        .formatted(r.yearFrom(), r.yearTo()))
           .addPropertyNode("yearFrom")         // the error is attached to the right field
           .addConstraintViolation();
        return false;
    }
}

@ValidYearRange
public record SearchRequest(
        @NotBlank(message = "The search text is required")
        @Size(min = 2, max = 100, message = "Between 2 and 100 characters")
        String q,

        List<MaterialType> type,          // repeatable: ?type=BOOK&type=DVD

        Boolean available,

        @Min(1450) @Max(2100) Integer yearFrom,
        @Min(1450) @Max(2100) Integer yearTo) {

    /** Normalisation: null → empty list, so as not to repeat checks downstream. */
    public SearchRequest {
        type = (type == null) ? List.of() : List.copyOf(type);
    }

    public SearchCriteria toDomain() {
        return SearchCriteria.builder()
                .text(q)
                .types(type)
                .onlyAvailable(Boolean.TRUE.equals(available))
                .between(yearFrom, yearTo)
                .build();
    }
}

public record SearchResultResponse(
        List<MaterialResponse> results,
        PageResponse.PageMetadata page,
        Map<String, Long> facetsByType,
        long overallTotal,
        String query) {

    public static SearchResultResponse from(Page<Material> page,
                                            Map<MaterialType, Long> facets,
                                            String query) {
        return new SearchResultResponse(
                page.getContent().stream().map(MaterialResponse::from).toList(),
                new PageResponse.PageMetadata(page.getNumber(), page.getSize(),
                        page.getTotalElements(), page.getTotalPages(),
                        page.isFirst(), page.isLast()),
                facets.entrySet().stream()
                        .collect(Collectors.toMap(e -> e.getKey().name(), Map.Entry::getValue,
                                                  (a, b) -> a, LinkedHashMap::new)),
                facets.values().stream().mapToLong(Long::longValue).sum(),
                query);
    }
}

@GetMapping("/search")
@Operation(summary = "Advanced search with facets by material type")
public SearchResultResponse search(
        @Valid SearchRequest criteria,
        @PageableDefault(size = 20, sort = "title") Pageable pageable) {

    // Defence in depth: even though max-page-size is configured, do not rely on it
    if (pageable.getPageSize() > 50) {
        pageable = PageRequest.of(pageable.getPageNumber(), 50, pageable.getSort());
    }

    SearchCriteria domain = criteria.toDomain();
    Page<Material> page = catalog.search(domain, pageable);
    Map<MaterialType, Long> facets = catalog.countByType(domain);        // aggregation query

    return SearchResultResponse.from(page, facets, criteria.q());
}

@Query("""
       select m.type as type, count(m) as total
       from Material m
       where (lower(m.title) like lower(concat('%', :text, '%'))
              or lower(m.author) like lower(concat('%', :text, '%')))
         and (:onlyAvailable = false or m.availableCopies > 0)
       group by m.type
       """)
List<TypeFacet> countByType(@Param("text") String text,
                            @Param("onlyAvailable") boolean onlyAvailable);

@Test
void returnsResultsWithFacetsByType() throws Exception {
    when(catalog.search(any(), any())).thenReturn(aPageWith(2, "Effective Java", "Refactoring"));
    when(catalog.countByType(any())).thenReturn(
            new LinkedHashMap<>(Map.of(MaterialType.BOOK, 5L, MaterialType.DVD, 2L)));

    mvc.perform(get("/api/materials/search").param("q", "java").param("type", "BOOK"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.results", hasSize(2)))
            .andExpect(jsonPath("$.facetsByType.BOOK").value(5))
            .andExpect(jsonPath("$.overallTotal").value(7))
            .andExpect(jsonPath("$.query").value("java"));
}

@Test
void rejectsQueriesThatAreTooShort() throws Exception {
    mvc.perform(get("/api/materials/search").param("q", "j"))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.errors[0].field").value("q"));
}

@Test
void rejectsAnInvertedYearRange() throws Exception {
    mvc.perform(get("/api/materials/search")
                    .param("q", "java").param("yearFrom", "2020").param("yearTo", "2010"))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.errors[0].field").value("yearFrom"))
            .andExpect(jsonPath("$.errors[0].message").value(containsString("cannot be later")));
}

@Test
void trimsThePageSizeToTheMaximum() throws Exception {
    mvc.perform(get("/api/materials/search").param("q", "java").param("size", "500"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.page.size").value(lessThanOrEqualTo(50)));
}

@Entity
@Table(name = "idempotency_keys",
       indexes = @Index(name = "idx_expiry", columnList = "expiresAt"))
public class IdempotencyKey {

    @Id
    @Column(name = "idempotency_key", length = 100)
    private String key;

    @Column(nullable = false, length = 64)
    private String requestFingerprint;   // hash of the body: detects reuse with different data

    @Enumerated(EnumType.STRING)
    private KeyStatus status;            // IN_PROGRESS, COMPLETED

    private Integer responseStatus;

    @Column(columnDefinition = "text")
    private String responseBody;

    private String location;
    private Instant createdAt;
    private Instant expiresAt;

    public enum KeyStatus { IN_PROGRESS, COMPLETED }
}

@Component
public class IdempotencyInterceptor implements HandlerInterceptor {

    private static final Logger log = LoggerFactory.getLogger(IdempotencyInterceptor.class);
    private static final String HEADER = "Idempotency-Key";
    private static final Duration VALIDITY = Duration.ofHours(24);

    private final IdempotencyKeyRepository repository;
    private final ObjectMapper json;
    private final Clock clock;

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
                             Object handler) throws IOException {

        // Only applies to methods that are not naturally idempotent
        if (!"POST".equals(request.getMethod())) return true;

        String key = request.getHeader(HEADER);
        if (key == null || key.isBlank()) return true;         // the header is optional

        String fingerprint = fingerprintOf(request);

        // Conditional INSERT: the primary-key constraint resolves the race
        // between two simultaneous requests with the same key. Do NOT use "SELECT then INSERT".
        Optional<IdempotencyKey> existing = repository.reserveIfAbsent(
                key, fingerprint, Instant.now(clock), Instant.now(clock).plus(VALIDITY));

        if (existing.isEmpty()) {
            // We reserved it ourselves: carry on with normal processing
            request.setAttribute("idempotency.key", key);
            return true;
        }

        IdempotencyKey previous = existing.get();

        // Same key, different body: the client has made a mistake
        if (!previous.getRequestFingerprint().equals(fingerprint)) {
            writeProblem(response, HttpStatus.UNPROCESSABLE_ENTITY,
                    "The idempotency key was already used with a different body.");
            return false;
        }

        if (previous.getStatus() == KeyStatus.IN_PROGRESS) {
            // Another identical request is being processed right now
            response.setHeader(HttpHeaders.RETRY_AFTER, "2");
            writeProblem(response, HttpStatus.CONFLICT,
                    "There is already a request in flight with this idempotency key.");
            return false;
        }

        // COMPLETED: we replay the original response without executing anything
        log.info("Replaying the idempotent response for key {}", key);
        response.setStatus(previous.getResponseStatus());
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setHeader("Idempotent-Replay", "true");
        if (previous.getLocation() != null) {
            response.setHeader(HttpHeaders.LOCATION, previous.getLocation());
        }
        response.getWriter().write(previous.getResponseBody());
        return false;                       // the controller is NOT called
    }

    private String fingerprintOf(HttpServletRequest request) throws IOException {
        // Requires ContentCachingRequestWrapper: the body can only be read once
        byte[] body = ((ContentCachingRequestWrapper) request).getContentAsByteArray();
        return HexFormat.of().formatHex(
                MessageDigest.getInstance("SHA-256").digest(body));
    }
}

@Component
@Order(Ordered.HIGHEST_PRECEDENCE + 10)
public class IdempotencyFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {

        var cachedRequest = new ContentCachingRequestWrapper(request);
        var cachedResponse = new ContentCachingResponseWrapper(response);

        try {
            chain.doFilter(cachedRequest, cachedResponse);

            String key = (String) request.getAttribute("idempotency.key");
            if (key != null) {
                int status = cachedResponse.getStatus();
                if (status >= 200 && status < 300) {
                    // Only success is memorised: a 500 must remain retryable
                    repository.complete(key, status,
                            new String(cachedResponse.getContentAsByteArray(), UTF_8),
                            cachedResponse.getHeader(HttpHeaders.LOCATION));
                } else {
                    repository.release(key);   // frees the key for a legitimate retry
                }
            }
        } finally {
            cachedResponse.copyBodyToResponse();      // ESSENTIAL: without this nothing reaches the client
        }
    }
}

@Repository
public class IdempotencyKeyRepository {

    private final JdbcTemplate jdbc;

    /**
     * Returns Optional.empty() if the key has just been reserved (we got there first),
     * or the existing row if it was already there.
     *
     * ON CONFLICT DO NOTHING makes the operation ATOMIC in the database:
     * two simultaneous requests with the same key cannot both reserve it.
     * A "SELECT then INSERT" in Java would leave a race window.
     */
    public Optional<IdempotencyKey> reserveIfAbsent(String key, String fingerprint,
                                                    Instant now, Instant expires) {
        int rows = jdbc.update("""
                insert into idempotency_keys
                       (idempotency_key, request_fingerprint, status, created_at, expires_at)
                values (?, ?, 'IN_PROGRESS', ?, ?)
                on conflict (idempotency_key) do nothing
                """, key, fingerprint, Timestamp.from(now), Timestamp.from(expires));

        if (rows == 1) return Optional.empty();       // we reserved it ourselves

        return jdbc.query("select * from idempotency_keys where idempotency_key = ?",
                          this::map, key).stream().findFirst();
    }
}

@Scheduled(cron = "0 0 3 * * *")     // every day at 03:00
@Transactional
public void purgeExpiredKeys() {
    int deleted = repository.deleteExpiredBefore(Instant.now(clock));
    log.info("Idempotency keys purged: {}", deleted);
}

KEY=$(uuidgen)
curl -i -X POST http://localhost:8080/api/loans \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"isbn":"978-0000000001","employeeId":1,"days":15}'
# → 201 Created, Location: /api/loans/42

# A retry with the same key
curl -i -X POST … -H "Idempotency-Key: $KEY" -d '{…}'
# → 201 Created, Location: /api/loans/42, Idempotent-Replay: true
#   (and a second loan has NOT been created)