Java,
then Spring.

Use sdkman, the same way the Python page used uv and the Go page used nothing: it installs JDKs side by side, switches between them per shell, and never touches your system packages. Install it, then install a JDK:

$ curl -s "https://get.sdkman.io" | bash
$ source "$HOME/.sdkman/bin/sdkman-init.sh"      # or just open a new terminal
$ sdk install java 21.0.5-tem
Done installing!  Setting java 21.0.5-tem as default.
$ java --version
openjdk 21.0.5 2024-10-15 LTS        ← the LTS suffix is what you want to see
$ sdk list java
Temurin | 21.0.5 | tem | installed   ← one row per vendor and version; sdk use java ... switches

Why 21 and not the newest? Java ships a release every six months and stamps one as LTS (long-term support) every two years. The LTS line runs 8 → 11 → 17 → 21 → 25; the versions in between are real releases that stop getting updates six months later, which is why production skips them. Java 25 is the newest LTS (September 2025); 21 is what most production runs and what every line on this page is written against. Nothing here breaks on 25.

Now run something. Since Java 11 the launcher compiles a single source file in memory, so a beginner never needs to see javac on day one:

public class Hello {
    public static void main(String[] args) {
        String name = args.length > 0 ? args[0] : "world";
        System.out.println("Hello, " + name);
    }
}

$ java Hello.java
Hello, world
$ java Hello.java Ada
Hello, Ada

For anything smaller than a file there is JShell, the REPL that ships with every JDK — the same role the python prompt played on the Python page. Statements do not need a class, a semicolon is optional at the prompt, and every result is bound to $1, $2… for reuse.

$ jshell
jshell> 21 * 2
$1 ==> 42
jshell> "task".repeat(3)
$2 ==> "tasktasktask"
jshell> /exit

Here is the same program grown up: a package, an import, a constant. Read it top to bottom, because each line is a contract with either the compiler or the JVM:

// src/dev/ladder/hello/Greeter.java -- path and package MUST agree
package dev.ladder.hello;

import java.time.LocalTime;      // a compile-time name shorthand -- unlike Python's
                                 // import, it executes nothing at runtime
public class Greeter {

    private static final String FALLBACK = "world";   // a class-level constant

    public static void main(String[] args) {
        String name = args.length > 0 ? args[0] : FALLBACK;
        System.out.println("Hello, " + name + " at " + LocalTime.now());
    }
}

Dissect the one line that does something. System is a class in java.lang (the only package imported automatically); out is a static final field on it, of type PrintStream; println is an overloaded method on that stream. So System.out.println is not an incantation — it is field access followed by a method call, and by the end of part two you can read it that way.

Now compile explicitly and look at the result. javac -d out mirrors the package into a directory tree; java -cp out tells the launcher where that tree starts; javap -c disassembles what the compiler wrote.

$ mkdir -p src/dev/ladder/hello out
$ javac -d out src/dev/ladder/hello/Greeter.java
$ java -cp out dev.ladder.hello.Greeter Ada
Hello, Ada at 09:14:02.113405
$ javap -c -cp out dev.ladder.hello.Greeter
public static void main(java.lang.String[]);
  Code:
     0: aload_0
     1: arraylength
     2: ifle          11        // args.length > 0 became a branch
    ...
    22: getstatic     #22       // Field java/lang/System.out
    25: invokevirtual #28       // Method java/io/PrintStream.println

Eight primitive types exist; four carry almost all production code. They are not objects: no methods, no null, no heap allocation — the value sits in the variable, the way a C or Go value would.

byte, short, float and char complete the set; you will meet them in I/O buffers and old APIs. Everything that is not one of the eight — String, arrays, every class you write — is a reference type: the variable holds a pointer, null means the pointer points at nothing, and copying the variable copies the arrow, never the object.

Collections cannot hold primitives, so Integer, Long and friends exist as boxed wrappers and the compiler autoboxes in both directions. The trap: the JVM caches boxes for −128..127, so == on small boxed values compares two pointers to the same cached box and returns true — then your test data grows past 127 and it silently returns false. Strings have the same shape: literals are pooled and shared, so == works right up until a string arrives from a file, a request, or new String(...). Prove all of it to yourself:

public class Surprises {
    public static void main(String[] args) {
        Integer a = 127, b = 127;             // both autoboxed from the cache
        Integer c = 128, d = 128;             // two fresh boxes on the heap
        System.out.println(a == b);           // true  -- same cached object
        System.out.println(c == d);           // false -- different objects, equal values
        System.out.println(c.equals(d));      // true  -- what you nearly always meant

        String s1 = "task";
        String s2 = "task";                   // same pooled literal as s1
        String s3 = new String("task");       // new forces a fresh object
        System.out.println(s1 == s2);         // true  -- pooling, an accident you cannot rely on
        System.out.println(s1 == s3);         // false -- different objects
        System.out.println(s1.equals(s3));    // true

        String t = s1.toUpperCase();          // Strings are immutable: this is a NEW string
        System.out.println(s1 + " " + t);     // task TASK -- s1 untouched

        int[] xs = {1, 2, 3};                 // arrays are fixed-size, forever
        System.out.println(xs.length);        // 3 -- a field, not a method
    }
}

$ java Surprises.java
true
false
true
true
false
true
task TASK
3

A Money type, the classical way. Note the shape: every field private final (set once, in the constructor, never again), accessors instead of public fields, and the three methods every value type owes the rest of the ecosystem:

import java.util.Objects;

public final class Money {                       // final class: cannot be subclassed
    private final long cents;                    // final field: assigned once, in the constructor
    private final String currency;

    public Money(long cents, String currency) {
        if (cents < 0) throw new IllegalArgumentException("negative amount");
        this.cents = cents;
        this.currency = Objects.requireNonNull(currency);
    }

    public long cents()       { return cents; }
    public String currency()  { return currency; }

    public Money plus(Money other) {             // no mutation: arithmetic returns a NEW Money
        if (!currency.equals(other.currency))
            throw new IllegalArgumentException("currency mismatch");
        return new Money(cents + other.cents, currency);
    }

    @Override public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Money m)) return false;
        return cents == m.cents && currency.equals(m.currency);
    }

    @Override public int hashCode() { return Objects.hash(cents, currency); }

    @Override public String toString() { return cents + " " + currency; }
}

Thirty lines, and every one of them mechanical. Since Java 16 the language writes them for you:

public record Money(long cents, String currency) {}   // the same class, generated

A record declares its state in the header, and the compiler generates the final fields, the canonical constructor, accessors named after the components (cents(), not getCents()), and value-based equals, hashCode and toString. You add back only what is genuinely yours — validation goes in a compact constructor, domain logic is an ordinary method:

record Money(long cents, String currency) {
    Money {                                      // compact constructor: validate, then fields assign
        if (cents < 0) throw new IllegalArgumentException("negative amount");
    }
    Money plus(Money other) {
        if (!currency.equals(other.currency))
            throw new IllegalArgumentException("currency mismatch");
        return new Money(cents + other.cents, currency);
    }
}

public class MoneyDemo {
    static final Money FREE = new Money(0, "GBP");    // static: one per class, shared

    public static void main(String[] args) {
        Money a = new Money(12_50, "GBP");            // instance state: one per object
        Money b = new Money(4_99, "GBP");
        System.out.println(a.plus(b));
        System.out.println(a.equals(new Money(12_50, "GBP")));
        System.out.println(new Money(-1, "GBP"));     // validation fires
    }
}

$ java MoneyDemo.java
Money[cents=1749, currency=GBP]
true
Exception in thread "main" java.lang.IllegalArgumentException: negative amount

static versus instance is the other axis worth fixing now: a static member belongs to the class (one FREE, shared; Math.max, Instant.now()), an instance member to each object (each Money has its own cents). main is static because when the JVM calls it, no object of your class exists yet. And final means “assigned once” for a field or variable, “no subclassing” for a class — it does not make the referenced object immutable.

Three interfaces carry the standard library: List<T> (ordered, indexed, duplicates allowed — usually ArrayList), Map<K, V> (key to value — usually HashMap), and Set<T> (no duplicates — usually HashSet). The angle brackets are generics: List<Task> is a list that only accepts and only returns Task, checked at compile time, where Python’s list[Task] is a hint mypy checks and the runtime ignores. The diamond <> on the right-hand side asks the compiler to repeat the type parameter so you do not have to.

import java.util.ArrayList;
import java.util.Comparator;
import java.util.HashMap;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;

record Task(String title, int priority, boolean done) {}

public class TaskListDemo {
    public static void main(String[] args) {
        List<Task> tasks = new ArrayList<>();          // diamond: compiler fills in <Task>
        tasks.add(new Task("write the Flyway migration", 1, false));
        tasks.add(new Task("wire the /tasks endpoint", 2, false));
        tasks.add(new Task("install a JDK", 1, true));

        tasks.sort(Comparator.comparing(Task::priority)   // sort by priority,
                             .thenComparing(Task::title)); // ties broken by title

        for (Task t : tasks) {                             // for-each: no index bookkeeping
            System.out.println((t.done() ? "[x] " : "[ ] ") + t.title());
        }

        Map<Integer, Long> perPriority = new HashMap<>();
        for (Task t : tasks) {
            perPriority.merge(t.priority(), 1L, Long::sum); // count per key, no if-absent dance
        }
        System.out.println(perPriority);

        Set<String> owners = new HashSet<>(List.of("ana", "ben", "ana"));
        System.out.println(owners.size());                 // deduplicated by equals/hashCode
    }
}

$ java TaskListDemo.java
[x] install a JDK
[ ] write the Flyway migration
[ ] wire the /tasks endpoint
{1=2, 2=1}
2

List.of(...), Map.of(...) and Set.of(...) build compact immutable literals — ideal for constants and test data, with one trap: they reject mutation at runtime, not compile time. The type system cannot see the difference between an ArrayList and an immutable list behind the same List interface:

List<String> tags = List.of("api", "db");   // immutable literal
tags.add("ui");                             // compiles fine...
// Exception in thread "main" java.lang.UnsupportedOperationException

List<String> mutable = new ArrayList<>(List.of("api", "db"));   // the copy that grows

Watch it happen. This key overrides both methods correctly — the bug is purely that it mutates after insertion:

import java.util.HashMap;
import java.util.Map;

class MutableKey {
    int n;
    MutableKey(int n) { this.n = n; }
    @Override public boolean equals(Object o) {
        return o instanceof MutableKey k && k.n == n;
    }
    @Override public int hashCode() { return Integer.hashCode(n); }
}

public class LostEntry {
    public static void main(String[] args) {
        Map<MutableKey, String> m = new HashMap<>();
        MutableKey k = new MutableKey(11);
        m.put(k, "hello");
        k.n = 14;                                       // the key moves AFTER insertion
        System.out.println(m.get(k));                   // null -- looked in the wrong bucket
        System.out.println(m.get(new MutableKey(11)));  // null -- right bucket, equals now fails
        System.out.println(m.size());                   // 1  -- the entry is still in there
    }
}

$ java LostEntry.java
null
null
1

The classic half first. An interface declares what, a class declares how, and implements connects them. Two habits are non-negotiable from day one: declare variables as the interface type, and write @Override on every implementing method so the compiler catches the typo’d signature that would otherwise become a brand-new method:

import java.util.ArrayList;
import java.util.List;

record Task(String title, int priority, boolean done) {}

interface TaskStore {
    void add(Task task);
    List<Task> all();

    default boolean isEmpty() {                // a default method: behaviour ON the contract,
        return all().isEmpty();                // inherited by every implementation for free
    }
}

class InMemoryTaskStore implements TaskStore {
    private final List<Task> tasks = new ArrayList<>();   // composition: HAS a list,
                                                          // does not EXTEND ArrayList
    @Override public void add(Task task) { tasks.add(task); }
    @Override public List<Task> all()    { return List.copyOf(tasks); }
}

public class StoreDemo {
    public static void main(String[] args) {
        TaskStore store = new InMemoryTaskStore();   // the variable is the interface;
        store.add(new Task("learn interfaces", 1, false));   // swap in a JdbcTaskStore later
        System.out.println(store.isEmpty());         // and this line does not change
        List<String> xs = new ArrayList<>();         // the same habit, stdlib edition
        xs.add("program to the interface");
        System.out.println(xs);
    }
}

$ java StoreDemo.java
false
[program to the interface]

InMemoryTaskStore has a list rather than being one — composition over inheritance. Java has single inheritance (extends, one superclass) and it is the most over-used feature in the language’s history: a deep extends chain welds subclasses to a parent’s implementation details, and any hierarchy more than two levels deep is a code-review flag. Interfaces impose no such coupling — a class can implement many — and default methods cover the “shared behaviour” excuse that used to justify base classes.

Now the modern half. By default an interface is open — anyone, anywhere, can implement it. A sealed interface names its complete set of implementations, and that closedness is what turns switch into a proof:

import java.util.List;

sealed interface Payment permits Card, Cash, Transfer {}
record Card(String last4, long cents)    implements Payment {}
record Cash(long cents)                  implements Payment {}
record Transfer(String iban, long cents) implements Payment {}

public class PaymentDemo {
    static String describe(Payment p) {
        return switch (p) {                       // switch as an EXPRESSION: it returns a value
            case Card c     -> "card *" + c.last4() + ", " + c.cents() + " cents";
            case Cash c     -> "cash, " + c.cents() + " cents";
            case Transfer t -> "transfer to " + t.iban();
        };                                        // no default: exhaustiveness is checked
    }

    public static void main(String[] args) {
        List<Payment> day = List.of(
            new Card("4242", 19_99), new Cash(5_00), new Transfer("DE89 3704", 120_00));
        for (Payment p : day) System.out.println(describe(p));
    }
}

$ java PaymentDemo.java
card *4242, 1999 cents
cash, 500 cents
transfer to DE89 3704
# after adding Voucher:
PaymentDemo.java: error: the switch expression does not cover all possible input values

The reactions, family by family. Error means the JVM itself is in trouble — there is no catch block that un-runs-out memory. RuntimeException means your code is wrong: a NullPointerException is fixed by the null check you forgot, not by a catch. Checked exceptions — everything else under Exception — mark environmental failure that a correct program still meets: the file missing, the socket closed. The compiler makes you acknowledge those, and the idiomatic acknowledgement at a boundary is: handle it if you genuinely can, otherwise wrap it in your own unchecked exception with the cause attached and let it fly.

Resource cleanup has one modern answer. Anything AutoCloseable goes in the parentheses of try, and the JVM closes it — on success, on exception, in reverse order for multiple resources. The old try/finally dance, with its own bug where close() throws and eats the real exception, is legacy code you will read but should not write:

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Optional;

class TaskStoreException extends RuntimeException {      // unchecked: extends RuntimeException
    TaskStoreException(String message, Throwable cause) { super(message, cause); }
}

public class ExceptionsDemo {

    static List<String> loadLines(Path file) {
        try (var reader = Files.newBufferedReader(file)) {   // try-with-resources: closed always,
            return reader.lines().toList();                  // even when an exception flies
        } catch (IOException e) {                            // the checked boundary...
            throw new TaskStoreException("could not read " + file, e);   // ...wrapped WITH cause
        }
    }

    static Optional<String> firstMatching(List<String> lines, String needle) {
        return lines.stream()                                // Optional: "maybe absent", in the
                    .filter(l -> l.contains(needle))         // return type where callers see it
                    .findFirst();
    }

    public static void main(String[] args) {
        List<String> lines = List.of("install jdk", "learn records");
        System.out.println(firstMatching(lines, "rec").orElse("no match"));
        System.out.println(firstMatching(lines, "zzz").orElse("no match"));
        loadLines(Path.of("missing.csv"));                   // watch the Caused by chain
    }
}

$ java ExceptionsDemo.java
learn records
no match
Exception in thread "main" TaskStoreException: could not read missing.csv
        at ExceptionsDemo.loadLines(ExceptionsDemo.java:16)
        at ExceptionsDemo.main(ExceptionsDemo.java:30)
Caused by: java.nio.file.NoSuchFileException: missing.csv
        ...

Optional<T> deserves its own rules, because it is routinely misused. It exists to make “this might be absent” visible in a return type, so the caller is forced to decide — orElse, orElseThrow, map, ifPresent. That is the whole job. Never make it a field (serialisation and JPA both choke, and it solves nothing there), never a parameter (callers end up writing Optional.of(x) noise — overload instead), and never call bare .get() — that is the old NullPointerException wearing a fancier name.

Two-argument variants exist (BiFunction, BinaryOperator), and the primitive specialisations (IntPredicate, LongFunction) avoid boxing in hot paths — you will meet those again inside streams. Here is the whole family working over tasks; note the composition methods and, or, negate and andThen, which are just default methods on the interfaces.

// Lambdas.java — one file, runnable directly (single-file launch, Java 11+)
import java.time.Instant;
import java.util.List;
import java.util.UUID;
import java.util.function.*;

record Task(UUID id, String title, boolean done, Instant createdAt) {
    static Task of(String title, boolean done) {
        return new Task(UUID.randomUUID(), title, done, Instant.now());
    }
}

public class Lambdas {
    public static void main(String[] args) {
        var tasks = List.of(
            Task.of("write the docs", false),
            Task.of("ship v2", true),
            Task.of("fix the flaky test", false));

        Predicate<Task> open        = t -> !t.done();
        Function<Task, String> name = Task::title;         // method reference
        Supplier<Task> blank        = () -> Task.of("untitled", false);
        Consumer<String> print      = System.out::println;

        Predicate<Task> openAndUrgent =
            open.and(t -> t.title().contains("fix"));      // composition

        for (var t : tasks) {
            if (openAndUrgent.test(t)) print.accept(name.apply(t));
        }
        print.accept(blank.get().title());
    }
}

$ java Lambdas.java
fix the flaky test
untitled

A method reference is a lambda the compiler writes for you, and there are exactly four shapes. Read the left column as “the thing before ::”:

Task::title           // instance method, receiver comes later:  t -> t.title()
System.out::println   // instance method on a captured object:   s -> System.out.println(s)
Task::of              // static method:                          (t, d) -> Task.of(t, d)
ArrayList::new        // constructor:                            () -> new ArrayList<>()

Capture is where Java and Python genuinely differ, not just in syntax. A Java lambda may read local variables from the enclosing method, but only if they are effectively final — assigned exactly once. The lambda gets a copy at creation time, so there is nothing to bind late and nothing to race on. The compile error below is the Python late-binding loop trap, refused at build time:

int seen = 0;
Consumer<Task> count = t -> seen++;
// error: local variables referenced from a lambda expression
// must be final or effectively final

var cell = new int[] { 0 };            // the classic dodge: a mutable box
Consumer<Task> c2 = t -> cell[0]++;    // compiles — and is a design smell;
                                       // prefer a collector or a plain loop

// Python, for contrast: fns = [lambda: i for i in range(3)] gives 2, 2, 2
// because the closure reads i when CALLED. Java cannot express that bug:
// each lambda would need its own effectively-final copy of i.

Finally, var. It is local type inference, not dynamic typing: the compiler writes the exact static type in for you, and it never changes. Use it when the type is already visible on the right-hand side; avoid it when the reader would have to open another file to know what you have.

var tasks = new ArrayList<Task>();   // fine: the type is right there
var byId  = new HashMap<UUID, Task>();

var result = service.process(id);    // avoid: what is result? go look it up
var xs = new ArrayList<>();          // trap: infers ArrayList<Object> — the
                                     // diamond has nothing to infer FROM
// var is locals-only: never fields, parameters or return types.

The collectors are where streams earn their keep for service code: grouping, counting and joining are the three you will write weekly once the task-tracker has an API. All three appear here, plus toMap and a primitive stream for the numeric tail:

// Pipeline.java — run with: java Pipeline.java
import java.time.Instant;
import java.util.*;
import java.util.stream.Collectors;

record Task(UUID id, String title, boolean done, Instant createdAt) {
    static Task of(String title, boolean done) {
        return new Task(UUID.randomUUID(), title, done, Instant.now());
    }
}

public class Pipeline {
    public static void main(String[] args) {
        var tasks = List.of(
            Task.of("write the docs", false),
            Task.of("ship v2", true),
            Task.of("fix the flaky test", false),
            Task.of("review PR 41", false),
            Task.of("rotate the API keys", true));

        Map<Boolean, Long> counts = tasks.stream()
            .collect(Collectors.groupingBy(Task::done, Collectors.counting()));

        String open = tasks.stream()
            .filter(t -> !t.done())
            .map(Task::title)
            .sorted()
            .collect(Collectors.joining(", ", "[", "]"));

        Map<UUID, String> titleById = tasks.stream()
            .collect(Collectors.toMap(Task::id, Task::title));
            // duplicate keys throw IllegalStateException — pass a merge fn if possible

        long titleChars = tasks.stream()
            .mapToLong(t -> t.title().length())   // LongStream: no boxing
            .sum();

        System.out.println(counts);
        System.out.println(open);
        System.out.println("title characters: " + titleChars);
    }
}

$ java Pipeline.java
{false=3, true=2}
[fix the flaky test, review PR 41, write the docs]
title characters: 70

To see the laziness rather than take it on faith, put a print inside the intermediate stages. Nothing appears until the terminal operation, and with limit(1) only the first element is ever touched:

var s = tasks.stream()
    .filter(t -> { System.out.println("filter " + t.title()); return !t.done(); })
    .map(t -> { System.out.println("map    " + t.title()); return t.title(); });
// nothing printed yet — the pipeline is a plan, not a loop

var first = s.limit(1).toList();
// filter write the docs
// map    write the docs
// — and it stops. The other four tasks are never examined.

Install Maven with the same tool that installed your JDK, then lay out a small library — tasklib — by hand once, so the conventions stick. The layout is not a suggestion: the compiler plugin looks in src/main/java, surefire looks in src/test/java, and neither is configurable in any project you should work on.

$ sdk install maven
$ mvn -v
Apache Maven 3.9.9   ← any 3.9.x is fine

tasklib/
  pom.xml
  src/
    main/java/dev/ladder/tasklib/Titles.java    # production code
    test/java/dev/ladder/tasklib/TitlesTest.java # tests, same package, never shipped

The pom below is complete — it builds. Read it top to bottom: the GAV coordinates (group, artifact, version) name the project uniquely; properties hold versions in one place; each dependency carries a scope saying which classpaths it joins; plugins are pinned so the build does not change under you.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>dev.ladder</groupId>        <!-- the GAV: who owns it -->
  <artifactId>tasklib</artifactId>     <!-- what it is called -->
  <version>0.1.0</version>             <!-- which build of it -->
  <packaging>jar</packaging>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <junit.version>5.11.4</junit.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>              <!-- test classpath only -->
    </dependency>
    <dependency>
      <groupId>org.assertj</groupId>
      <artifactId>assertj-core</artifactId>
      <version>3.27.3</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.2</version>       <!-- pin: old defaults miss JUnit 5 -->
      </plugin>
    </plugins>
  </build>
</project>

The library itself is one class, small enough that the point stays the build, not the code:

// src/main/java/dev/ladder/tasklib/Titles.java
package dev.ladder.tasklib;

import java.util.List;

public final class Titles {
    private Titles() {}

    public static String summary(List<String> titles) {
        return titles.size() + " tasks: " + String.join(", ", titles);
    }

    public static void main(String[] args) {
        System.out.println(summary(List.of("write the docs", "ship v2")));
    }
}

$ mkdir -p tasklib/src/main/java/dev/ladder/tasklib
$ mkdir -p tasklib/src/test/java/dev/ladder/tasklib
$ cd tasklib                       # pom.xml from above at the root
$ mvn -q package
$ java -cp target/tasklib-0.1.0.jar dev.ladder.tasklib.Titles
2 tasks: write the docs, ship v2

When a build behaves oddly, the first question is always “what is actually on the classpath?”, and the answer is one command:

$ mvn dependency:tree
[INFO] dev.ladder:tasklib:jar:0.1.0
[INFO] +- org.junit.jupiter:junit-jupiter:jar:5.11.4:test
[INFO] |  +- org.junit.jupiter:junit-jupiter-api:jar:5.11.4:test
[INFO] |  \- org.junit.jupiter:junit-jupiter-engine:jar:5.11.4:test
[INFO] \- org.assertj:assertj-core:jar:3.27.3:test

Test names are documentation that cannot go stale, so write them as behaviour: summary_of_nothing_says_no_tasks reads as a sentence in the failure report, where testSummary2 reads as homework. Inside each test, keep the three phases visible — arrange, act, assert — and let AssertJ’s assertThat(actual).isEqualTo(expected) carry the assertions: it reads left to right, it cannot get expected and actual backwards, and its failure messages show diffs instead of expected: true but was: false.

// src/test/java/dev/ladder/tasklib/TitlesTest.java
package dev.ladder.tasklib;

import java.util.Collections;
import java.util.List;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;

import static org.assertj.core.api.Assertions.assertThat;

class TitlesTest {

    private List<String> titles;

    @BeforeEach
    void freshTitles() {                       // arrange, shared
        titles = List.of("write the docs", "ship v2");
    }

    @Test
    void summary_counts_and_joins() {
        String s = Titles.summary(titles);     // act
        assertThat(s).isEqualTo("2 tasks: write the docs, ship v2");  // assert
    }

    @Test
    void summary_of_nothing_says_no_tasks() {
        assertThat(Titles.summary(List.of())).isEqualTo("no tasks");
    }

    @ParameterizedTest                         // one method, many cases —
    @CsvSource({                               // each row is its own test
        "1, 1 tasks",
        "3, 3 tasks",
        "9, 9 tasks",
    })
    void summary_starts_with_the_count(int n, String prefix) {
        var many = Collections.nCopies(n, "x");
        assertThat(Titles.summary(many)).startsWith(prefix);
    }
}

$ mvn test
[INFO] Running dev.ladder.tasklib.TitlesTest
[ERROR] TitlesTest.summary_of_nothing_says_no_tasks -- Time elapsed: 0.031 s <<< FAILURE!
org.opentest4j.AssertionFailedError:
expected: "no tasks"
 but was: "0 tasks: "
[ERROR] Tests run: 5, Failures: 1, Errors: 0, Skipped: 0
[INFO] BUILD FAILURE

The failure is the specification. Make it pass with the smallest honest change to Titles.summary:

public static String summary(List<String> titles) {
    if (titles.isEmpty()) return "no tasks";     // the fix the test demanded
    return titles.size() + " tasks: " + String.join(", ", titles);
}

$ mvn test
[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

First the disease, then the cure. Without a container, every class constructs its own dependencies, which welds the object graph shut:

// Without a container: each class builds its own world
class TaskController {
    private final TaskService service = new TaskService(new InMemoryStore());
    // - a test cannot hand in a fake TaskService or a fake store
    // - every change to TaskService's constructor edits every class that news it
    // - two controllers construct two stores: two copies of the truth
}

Inversion of control flips the arrow: TaskController says “I need a TaskService” and stops caring where it comes from. The container scans your package for stereotyped classes, works out the dependency graph from constructor signatures, and instantiates each bean exactly once, in dependency order.

$ curl https://start.spring.io/starter.tgz \
    -d dependencies=web,validation,actuator \
    -d javaVersion=21 -d type=maven-project \
    -d groupId=dev.ladder -d artifactId=tasks -d baseDir=tasks | tar -xzf -
$ cd tasks
$ ./mvnw spring-boot:run          # mvnw: the project carries its own Maven
  .   ____          _            __ _ _
 :: Spring Boot ::                (v3.5.5)
...Tomcat started on port 8080 (http) with context path '/'
...Started TasksApplication in 1.84 seconds (process running for 2.1)

Those two log lines are the contract: an embedded servlet container is listening — there is no separate application server to install, the jar is the server — and the context started, meaning every bean constructed and wired without error. The whole application bootstrap is one class:

// src/main/java/dev/ladder/tasks/TasksApplication.java — generated for you
package dev.ladder.tasks;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication      // = @Configuration           (this class may declare beans)
                            // + @EnableAutoConfiguration (react to the classpath)
                            // + @ComponentScan           (scan THIS package and below)
public class TasksApplication {
    public static void main(String[] args) {
        SpringApplication.run(TasksApplication.class, args);
    }
}

The scan starts at the package of this class, which is why your code lives in dev.ladder.tasks or below it — a class in a sibling package is silently invisible to the container, a classic first-week bug. There are three ways a bean comes to exist, and you will use all three:

@Service                                  // stereotype: "scan me in" — @Component
public class TaskService {                // with a role name; @Repository is the third
    private final Clock clock;            // one final field per dependency

    public TaskService(Clock clock) {     // single constructor: no @Autowired needed,
        this.clock = clock;               // Spring uses it automatically
    }
}

@Configuration
class TimeConfig {
    @Bean                                 // @Bean: for types you don't own and can't
    Clock clock() {                       // annotate — the method body is the recipe
        return Clock.systemUTC();
    }
}

If you came from the Go or Python pages: this is the same “accept interfaces at the edges, wire in main” discipline you already know — FastAPI’s Depends plays the same role — except the wiring code you wrote by hand in Go’s main() is derived from constructor signatures here. The trade: you write less plumbing, and in exchange the construction order lives in a framework you must trust and occasionally debug.

Four small files, all in dev.ladder.tasks. The domain record and the two API records first:

// Task.java — the domain record: immutable, equality by value
package dev.ladder.tasks;

import java.time.Instant;
import java.util.UUID;

public record Task(UUID id, String title, boolean done, Instant createdAt) {}

// CreateTaskRequest.java — what a client MAY send
package dev.ladder.tasks;

import jakarta.validation.constraints.NotBlank;

public record CreateTaskRequest(@NotBlank String title) {}

// TaskResponse.java — what a client WILL receive
package dev.ladder.tasks;

import java.time.Instant;
import java.util.UUID;

public record TaskResponse(UUID id, String title, boolean done, Instant createdAt) {
    static TaskResponse from(Task t) {
        return new TaskResponse(t.id(), t.title(), t.done(), t.createdAt());
    }
}

The service owns the store — a ConcurrentHashMap for now; part seven of the series swaps it for Postgres behind the same method signatures, which is the whole reason the controller never touches the map directly. Note markDone replaces the record rather than mutating it: records have no setters, so “update” means “new value, same key”, and computeIfPresent makes the read-modify-write atomic:

// TaskService.java
package dev.ladder.tasks;

import java.time.Instant;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import org.springframework.stereotype.Service;

@Service
public class TaskService {
    private final Map<UUID, Task> store = new ConcurrentHashMap<>();

    public Task create(String title) {
        var task = new Task(UUID.randomUUID(), title, false, Instant.now());
        store.put(task.id(), task);
        return task;
    }

    public List<Task> all() {
        return store.values().stream()
            .sorted(Comparator.comparing(Task::createdAt))   // part two, earning rent
            .toList();
    }

    public Optional<Task> byId(UUID id) {
        return Optional.ofNullable(store.get(id));
    }

    public Optional<Task> markDone(UUID id) {
        return Optional.ofNullable(store.computeIfPresent(id,
            (k, t) -> new Task(t.id(), t.title(), true, t.createdAt())));
    }
}

The controller maps the four endpoints. Where the happy path is the only path (GET /tasks), return the value and let Spring produce the 200; where the status code carries meaning — 201 with a Location, 404 for a missing id — return ResponseEntity and say so explicitly:

// TaskController.java
package dev.ladder.tasks;

import jakarta.validation.Valid;
import java.net.URI;
import java.util.List;
import java.util.UUID;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController                      // @Controller + @ResponseBody: returns become JSON
@RequestMapping("/tasks")
public class TaskController {
    private final TaskService service;

    public TaskController(TaskService service) {   // constructor injection, again
        this.service = service;
    }

    @PostMapping
    ResponseEntity<TaskResponse> create(@Valid @RequestBody CreateTaskRequest req) {
        var task = service.create(req.title());
        return ResponseEntity
            .created(URI.create("/tasks/" + task.id()))   // 201 + Location header
            .body(TaskResponse.from(task));
    }

    @GetMapping
    List<TaskResponse> all() {
        return service.all().stream().map(TaskResponse::from).toList();
    }

    @GetMapping("/{id}")
    ResponseEntity<TaskResponse> byId(@PathVariable UUID id) {
        return service.byId(id)
            .map(TaskResponse::from)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());   // empty Optional → 404
    }

    @PatchMapping("/{id}/done")
    ResponseEntity<TaskResponse> done(@PathVariable UUID id) {
        return service.markDone(id)
            .map(TaskResponse::from)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }
}

$ curl -si -X POST localhost:8080/tasks \
    -H 'Content-Type: application/json' -d '{"title":"write the docs"}'
HTTP/1.1 201
Location: /tasks/8b6c2f1a-6f9d-4c3e-9b1a-2d7e5a4c9f10
{"id":"8b6c2f1a-...","title":"write the docs","done":false,"createdAt":"2026-08-24T09:14:02.113Z"}

$ curl -s localhost:8080/tasks
[{"id":"8b6c2f1a-...","title":"write the docs","done":false,"createdAt":"..."}]

$ curl -s -X PATCH localhost:8080/tasks/8b6c2f1a-6f9d-4c3e-9b1a-2d7e5a4c9f10/done
{"id":"8b6c2f1a-...","title":"write the docs","done":true,"createdAt":"..."}

$ curl -si -X POST localhost:8080/tasks \
    -H 'Content-Type: application/json' -d '{"title":""}'
HTTP/1.1 400
{"timestamp":"...","status":400,"error":"Bad Request","path":"/tasks"}

YAML over properties files, for one reason: nesting reads as structure instead of repeated prefixes. Replace the generated application.properties with application.yml, and add a prod overlay next to it:

# src/main/resources/application.yml — the defaults, committed
tasks:
  max-open: 50
  banner: "task-tracker (dev)"

management:
  endpoints:
    web:
      exposure:
        include: health,info    # expose deliberately — never "*" in prod

# src/main/resources/application-prod.yml — only the differences
tasks:
  max-open: 20
  banner: "task-tracker"
management:
  server:
    port: 9090                  # actuator on its own port, off the public LB

Now the binding. A record plus one annotation turns that YAML subtree into a typed, immutable object; the container constructs it at start-up and fails the boot — with the offending key in the message — if a value is missing or the wrong type. Inject it like any other bean; never read System.getenv from business code:

// TasksProperties.java — kebab-case keys bind to camelCase components
package dev.ladder.tasks;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "tasks")
public record TasksProperties(int maxOpen, String banner) {}

// TasksApplication.java — register it (or use @ConfigurationPropertiesScan)
@SpringBootApplication
@EnableConfigurationProperties(TasksProperties.class)
public class TasksApplication { ... }

// TaskService.java — configuration arrives by constructor, like everything else
@Service
public class TaskService {
    private final Map<UUID, Task> store = new ConcurrentHashMap<>();
    private final TasksProperties props;

    public TaskService(TasksProperties props) {
        this.props = props;
    }

    public Task create(String title) {
        long open = store.values().stream().filter(t -> !t.done()).count();
        if (open >= props.maxOpen()) {
            throw new IllegalStateException("open-task limit reached: " + props.maxOpen());
        }
        var task = new Task(UUID.randomUUID(), title, false, Instant.now());
        store.put(task.id(), task);
        return task;
    }
    // all(), byId(), markDone() unchanged
}

$ SPRING_PROFILES_ACTIVE=prod TASKS_MAX_OPEN=10 ./mvnw spring-boot:run
...The following 1 profile is active: "prod"
...Tomcat started on port 8080 (http)
...Exposing 2 endpoints beneath base path '/actuator'

$ curl -s localhost:9090/actuator/health
{"status":"UP"}
$ curl -s localhost:9090/actuator/info
{}                                  # empty until you add info.* properties
$ curl -s localhost:8080/actuator/health
{"timestamp":"...","status":404,"error":"Not Found","path":"/actuator/health"}
                                  # 8080 still serves the API, but actuator moved — good

Which value of tasks.max-open won? The env var: 10 beats the prod file’s 20, which beat the default file’s 50 — rungs four, three, two of the ladder. Add --tasks.max-open=5 after spring-boot:run (as -Dspring-boot.run.arguments) and rung five wins instead.

Three additions to the pom.xml from part six. The JPA starter brings Hibernate and Spring Data; the driver is runtime scope because you compile against JDBC interfaces, not against Postgres; Flyway needs its Postgres module since Flyway 10 split databases out of core.

<!-- pom.xml, inside <dependencies> -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <scope>runtime</scope>
</dependency>
<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-core</artifactId>
</dependency>
<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-database-postgresql</artifactId>
</dependency>

The database itself is a compose.yaml next to the pom. The healthcheck matters: without it, “the container is up” and “Postgres accepts connections” are two different moments, and your app can boot into the gap.

# compose.yaml, in the project root
services:
  db:
    image: postgres:16
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: tasks
      POSTGRES_PASSWORD: tasks
      POSTGRES_DB: tasks
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U tasks"]
      interval: 2s
      timeout: 2s
      retries: 15

$ docker compose up -d
$ docker compose ps
NAME       IMAGE         STATUS
tasks-db-1 postgres:16   Up 8 seconds (healthy)   ← healthy, not just Up

The datasource goes into application.yml. Two lines here are load-bearing: ddl-auto: validate means Hibernate checks the schema against the entities and refuses to start on a mismatch — it never modifies the database — and open-in-view: false is explained in the next topic.

# src/main/resources/application.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/tasks
    username: tasks
    password: tasks
  jpa:
    hibernate:
      ddl-auto: validate
    open-in-view: false

So who creates the table? Flyway. On startup it scans db/migration, compares against its own history table, and applies whatever is new, in version order, each in a transaction. Schema changes become files in git that review like code, because they are code.

-- src/main/resources/db/migration/V1__create_tasks.sql
create table tasks (
  id         uuid primary key,
  title      text        not null,
  done       boolean     not null default false,
  created_at timestamptz not null
);

create index tasks_done_idx on tasks (done);

Now the entity. It is deliberately a class, not a record: JPA instantiates it through a no-argument constructor and mutates its fields when it loads rows — a record’s finality and single constructor fight that contract. Keep the record Task as the API type and translate at the edge.

// src/main/java/dev/ladder/tasks/TaskEntity.java
package dev.ladder.tasks;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import java.time.Instant;
import java.util.UUID;

@Entity
@Table(name = "tasks")
class TaskEntity {

  @Id
  private UUID id;

  @Column(nullable = false)
  private String title;

  @Column(nullable = false)
  private boolean done;

  @Column(name = "created_at", nullable = false)
  private Instant createdAt;

  protected TaskEntity() { }               // for JPA only; nobody else calls it

  TaskEntity(UUID id, String title, boolean done, Instant createdAt) {
    this.id = id;
    this.title = title;
    this.done = done;
    this.createdAt = createdAt;
  }

  Task toTask() { return new Task(id, title, done, createdAt); }

  UUID id()            { return id; }
  boolean done()       { return done; }
  void markDone()      { this.done = true; }
}

The repository is the whole data-access layer, and you only write its signature. Method names in the findByDoneFalse style are parsed into queries at startup; anything the naming scheme cannot say cleanly gets an explicit @Query later.

// src/main/java/dev/ladder/tasks/TaskRepository.java
package dev.ladder.tasks;

import java.util.List;
import java.util.UUID;
import org.springframework.data.jpa.repository.JpaRepository;

interface TaskRepository extends JpaRepository<TaskEntity, UUID> {

  List<TaskEntity> findByDoneFalse();      // select ... where done = false

  long countByDone(boolean done);          // select count(*) ... where done = ?
}

Rewiring TaskService is mechanical: the map becomes the repository, and the entity-to-record mapping happens in exactly one class. The DTO records and the create/list endpoints from part six do not change — that is the boundary paying for itself. The two lookup methods do change, and get shorter; they are below.

// TaskService.java -- the ConcurrentHashMap is gone
@Service
public class TaskService {

  private final TaskRepository repo;

  public TaskService(TaskRepository repo) {   // constructor injection, as always
    this.repo = repo;
  }

  public Task create(String title) {
    var e = new TaskEntity(UUID.randomUUID(), title, false, Instant.now());
    return repo.save(e).toTask();
  }

  public List<Task> all() {
    return repo.findAll().stream().map(TaskEntity::toTask).toList();
  }

  public Task get(UUID id) {
    return repo.findById(id).map(TaskEntity::toTask)
               .orElseThrow(() -> new TaskNotFoundException(id));
  }

  public Task markDone(UUID id) {
    var e = repo.findById(id).orElseThrow(() -> new TaskNotFoundException(id));
    e.markDone();
    return repo.save(e).toTask();
  }
}

TaskNotFoundException is new — the domain’s way of saying “no such row”, deliberately a RuntimeException so it can cross the service boundary uncaught. Part nine maps it to a proper 404 problem document; until then it surfaces as a 500, which is honest enough for now:

// TaskNotFoundException.java -- two lines, whole file
class TaskNotFoundException extends RuntimeException {
  TaskNotFoundException(UUID id) { super("No task with id " + id); }
}

And the two controller lookup methods stop juggling an Optional — call the service, let the exception fly:

// TaskController.java -- byId and done, after the rewire
@GetMapping("/{id}")
TaskResponse byId(@PathVariable UUID id) {
    return TaskResponse.from(service.get(id));
}

@PatchMapping("/{id}/done")
TaskResponse done(@PathVariable UUID id) {
    return TaskResponse.from(service.markDone(id));
}

$ ./mvnw spring-boot:run
... Flyway ... Successfully applied 1 migration to schema "public"
... Tomcat started on port 8080
$ curl -s -X POST localhost:8080/tasks -H 'content-type: application/json' \
       -d '{"title":"wire up postgres"}'
{"id":"9c7b...","title":"wire up postgres","done":false,"createdAt":"2026-08-24T..."}
$ docker compose exec db psql -U tasks -c 'select title, done from tasks'
      title       | done
 wire up postgres | f          ← a real row; it survives restarts

The working rules, applied to the service. Reads get readOnly = true — it lets Hibernate skip dirty-checking snapshots and hints the driver. Writes get the default. And note markDone no longer calls save: inside a transaction the loaded entity is managed, so mutating it is enough — the flush at commit writes the UPDATE.

@Service
public class TaskService {
  // ... constructor as before ...

  @Transactional(readOnly = true)
  public List<Task> open() {
    return repo.findByDoneFalse().stream().map(TaskEntity::toTask).toList();
  }

  @Transactional
  public Task markDone(UUID id) {
    var e = repo.findById(id).orElseThrow(() -> new TaskNotFoundException(id));
    e.markDone();          // managed entity: the commit flushes the UPDATE
    return e.toTask();     // no save() needed inside a transaction
  }
}

Three rules that are not visible in that code. Rollback happens for unchecked exceptions only — a checked exception commits unless you say @Transactional(rollbackFor = Exception.class). A transaction holds a pooled connection from first query to commit, so keep it short: with Hikari’s default pool of 10, one HTTP call made inside a transaction means ten slow requests can hold every connection while they wait on someone else’s API. And the classic silent failure:

@Service
public class SweepService {

  public void nightly() {
    this.sweep();          // same object, plain call: the proxy never sees it
  }                        // sweep() runs with NO transaction, silently

  @Transactional
  public void sweep() { /* delete old done tasks */ }
}

Now the other trap. Give tasks some tags — a second table, a lazy collection — and watch what a list endpoint does.

-- src/main/resources/db/migration/V2__task_tags.sql
create table task_tags (
  task_id uuid not null references tasks (id),
  tag     text not null
);

// added to TaskEntity -- collections are LAZY by default, correctly
@ElementCollection
@CollectionTable(name = "task_tags", joinColumns = @JoinColumn(name = "task_id"))
@Column(name = "tag")
private List<String> tags = new ArrayList<>();

Lazy means the tags are not loaded until touched. Touch them while mapping 100 tasks to records and you issue 1 query for the tasks plus 100 for the tags — the N+1 problem, invisible at 100 rows on localhost and fatal at 100,000 in production. The log below is the diagnostic; the fix is to tell the one query to fetch the relation.

-- logging.level.org.hibernate.SQL: DEBUG, then GET /tasks:
select t1_0.id,t1_0.created_at,t1_0.done,t1_0.title from tasks t1_0
select t1_0.tag from task_tags t1_0 where t1_0.task_id=?
select t1_0.tag from task_tags t1_0 where t1_0.task_id=?
select t1_0.tag from task_tags t1_0 where t1_0.task_id=?
-- ... once per task. 100 tasks = 101 round trips.

// fix 1: say the join in JPQL
@Query("select distinct t from TaskEntity t left join fetch t.tags where t.done = false")
List<TaskEntity> findOpenWithTags();

// fix 2: keep the derived query, declare what to fetch
@EntityGraph(attributePaths = "tags")
List<TaskEntity> findByDoneFalse();

// fix 3: skip entities entirely when the caller wants two fields
public record TaskSummary(UUID id, String title) { }

@Query("""
    select new dev.ladder.tasks.TaskSummary(t.id, t.title)
    from TaskEntity t where t.done = false""")
List<TaskSummary> openSummaries();       // one query, no entities, nothing lazy

$ ./mvnw spring-boot:run -Dspring-boot.run.arguments=--logging.level.org.hibernate.SQL=DEBUG
$ curl -s localhost:8080/tasks > /dev/null
org.hibernate.SQL : select t1_0.id, ... from tasks t1_0
org.hibernate.SQL : select t1_0.tag from task_tags ... where task_id=?   ← xN
# after the join fetch:
org.hibernate.SQL : select ... from tasks t1_0 left join task_tags ...   ← one query

First the classic toolkit, because most codebases still run on it. An ExecutorService owns the threads; you submit work and hold a Future. CompletableFuture adds composition — run two things, combine the results — and every blocking wait gets a timeout, the same reflex the Go page drilled with contexts.

ExecutorService pool = Executors.newFixedThreadPool(8);  // bounded, always

// submit + Future: fine for one-off background work
Future<Long> open = pool.submit(() -> repo.countByDone(false));
long n = open.get(2, TimeUnit.SECONDS);        // never get() without a timeout

// CompletableFuture: run both counts in parallel, combine, bound the whole thing
var openF = CompletableFuture.supplyAsync(() -> repo.countByDone(false), pool);
var doneF = CompletableFuture.supplyAsync(() -> repo.countByDone(true),  pool);

long total = openF.thenCombine(doneF, Long::sum)
                  .orTimeout(2, TimeUnit.SECONDS)
                  .join();

pool.shutdown();   // in Spring: expose the pool as a @Bean so the container closes it

Shared state, in one pass. The demo below is the whole problem: counter++ is a read, an add and a write, and two threads interleaving those three steps overwrite each other’s updates. No exception, no warning — just a wrong number.

// Race.java -- run it, the count is wrong, and differently wrong each time
public class Race {
  static long counter = 0;                      // plain shared field

  public static void main(String[] args) throws InterruptedException {
    Runnable inc = () -> { for (int i = 0; i < 1_000_000; i++) counter++; };
    Thread a = new Thread(inc);
    Thread b = new Thread(inc);
    a.start(); b.start();
    a.join();  b.join();
    System.out.println(counter);                // almost never 2000000
  }
}

// the fixes, smallest hammer first
static final AtomicLong counter = new AtomicLong();
counter.incrementAndGet();                       // lock-free read-modify-write

// per-key atomic updates on a shared map -- no lock around the whole map
ConcurrentHashMap<String, Long> hits = new ConcurrentHashMap<>();
hits.compute("tasks", (k, v) -> v == null ? 1 : v + 1);

// synchronized: mutual exclusion AND visibility, for multi-field invariants
synchronized (lock) { balance -= amount; ledger.add(entry); }

// volatile: visibility only -- a flag one thread writes, others read.
// It does NOT make ++ atomic; that mistake is the race above with extra steps.
volatile boolean shuttingDown = false;

$ javac Race.java && java Race
1274832        ← lost about 725,000 increments
$ java Race
1391246        ← a different wrong answer -- the signature of a race
# after AtomicLong:
$ java Race
2000000        ← every time

Now the Java 21 headline. A virtual thread is a thread whose stack lives on the heap; the JVM mounts it on a carrier (an OS thread) only while it is actually running, and unmounts it the moment it blocks. Creating one is cheap enough that pooling them is an anti-pattern — you create one per task and throw it away.

Thread.ofVirtual().name("enrich-", 0).start(() -> enrich(taskId));

// one virtual thread per task; close() waits for all of them
try (var exec = Executors.newVirtualThreadPerTaskExecutor()) {
  for (UUID id : ids) {
    exec.submit(() -> enrich(id));     // 10,000 submissions: fine
  }
}

# and in Spring Boot -- one line in application.yml:
spring:
  threads:
    virtual:
      enabled: true   # Tomcat serves each request on a virtual thread

With that property on, the blocking repository calls this page just wrote stop costing platform threads while they wait on Postgres — the thread-pool ceiling on concurrent requests effectively disappears, and the next limit is the database pool, which is where you want it.

What the collector is doing with that heap: nearly all objects die young, so the heap is split into a young generation — collected often and cheaply, because collecting means copying the few survivors — and an old generation for whatever survives repeatedly, collected rarely and more expensively. Allocation itself is a thread-local pointer bump, which is why idiomatic Java allocates freely and why the cost model is the opposite of C’s: creating garbage is cheap, keeping objects alive is what costs.

G1, the default collector, does this region by region against a pause target (200 ms by default) and is the right answer until measured otherwise. ZGC (-XX:+UseZGC) trades some throughput for sub-millisecond pauses on heaps up to terabytes — one flag, when p99 latency says so.

# the flags that matter, and the ones to stop using
java -Xms256m -Xmx256m -jar app.jar        # fixed heap: fine on a VM you own

# in a container, size from the cgroup limit instead of hard-coding:
java -XX:MaxRAMPercentage=75 \
     -XX:+HeapDumpOnOutOfMemoryError \
     -XX:HeapDumpPath=/tmp/heap.hprof \
     -jar app.jar

# flight recording: always-on production profiling, ~1% overhead
java -XX:StartFlightRecording=duration=60s,filename=rec.jfr -jar app.jar
jfr print --events jdk.GCPhasePause rec.jfr   # or open rec.jfr in JDK Mission Control

When the heap does run out you get java.lang.OutOfMemoryError — an Error, not an Exception, and not one to catch: the useful move is the flag above, which writes a heap dump on the way down so you can see what filled the heap rather than guessing. And for a JVM that is alive but suspicious, jcmd asks it questions directly — no restart, no agent, nothing installed.

$ ./mvnw -q package -DskipTests
$ java -Xmx16m -jar target/tasks-0.0.1-SNAPSHOT.jar
java.lang.OutOfMemoryError: Java heap space   ← dies during startup
$ java -XX:MaxRAMPercentage=75 -jar target/tasks-0.0.1-SNAPSHOT.jar &
$ jcmd $(pgrep -f tasks-0.0.1) GC.heap_info
 garbage-first heap   total 129024K, used 54012K   ← live heap, right now
$ jcmd $(pgrep -f tasks-0.0.1) Thread.print | grep -c '^"'
41                                            ← every thread, with full stacks
$ jcmd $(pgrep -f tasks-0.0.1) JFR.start duration=60s filename=rec.jfr
Started recording 1.                          ← JFR can also start after the fact

Recall from part six that CreateTaskRequest carries @NotBlank String title and the controller takes @Valid @RequestBody CreateTaskRequest req — that is what raises the validation exception in lane two. The domain exception in lane one is TaskNotFoundException, the two-line class you wrote in part seven. The whole advice class, complete:

// src/main/java/dev/ladder/tasks/ApiExceptionHandler.java
package dev.ladder.tasks;

import java.util.Map;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
class ApiExceptionHandler {

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

  @ExceptionHandler(TaskNotFoundException.class)
  ProblemDetail notFound(TaskNotFoundException ex) {
    var p = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
    p.setTitle("Task not found");
    return p;                          // Spring serialises it as problem+json
  }

  @ExceptionHandler(MethodArgumentNotValidException.class)
  ProblemDetail invalid(MethodArgumentNotValidException ex) {
    var p = ProblemDetail.forStatusAndDetail(
        HttpStatus.BAD_REQUEST, "Request body failed validation");
    p.setTitle("Validation failed");
    p.setProperty("errors", ex.getFieldErrors().stream()
        .map(f -> Map.of("field", f.getField(),
                         "message", String.valueOf(f.getDefaultMessage())))
        .toList());                    // extra members are allowed by RFC 9457
    return p;
  }

  @ExceptionHandler(Exception.class)   // the safety net -- keep it LAST in your head
  ProblemDetail internal(Exception ex) {
    log.error("unhandled exception", ex);          // full trace -> the log
    var p = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
    p.setTitle("Internal error");                  // nothing else -> the client
    return p;
  }
}

$ curl -s localhost:8080/tasks/00000000-0000-0000-0000-000000000000
{"type":"about:blank","title":"Task not found","status":404,
 "detail":"No task with id 00000000-0000-0000-0000-000000000000",
 "instance":"/tasks/00000000-0000-0000-0000-000000000000"}
$ curl -s -X POST localhost:8080/tasks -H 'content-type: application/json' -d '{"title":""}'
{"type":"about:blank","title":"Validation failed","status":400,
 "detail":"Request body failed validation",
 "errors":[{"field":"title","message":"must not be blank"}]}

// src/main/java/dev/ladder/tasks/HttpClients.java
package dev.ladder.tasks;

import java.time.Duration;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.http.client.ClientHttpRequestFactoryBuilder;
import org.springframework.boot.http.client.ClientHttpRequestFactorySettings;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpStatusCode;
import org.springframework.web.client.RestClient;

@Configuration
class HttpClients {

  @Bean
  RestClient auditClient(RestClient.Builder builder,
                         @Value("${audit.base-url}") String baseUrl) {
    var settings = ClientHttpRequestFactorySettings.defaults()
        .withConnectTimeout(Duration.ofSeconds(2))    // reaching the host
        .withReadTimeout(Duration.ofSeconds(3));      // waiting for bytes

    return builder
        .baseUrl(baseUrl)
        .requestFactory(ClientHttpRequestFactoryBuilder.detect().build(settings))
        .defaultStatusHandler(HttpStatusCode::is5xxServerError, (req, res) -> {
          throw new AuditUnavailable(res.getStatusCode().value());   // transient
        })
        .defaultStatusHandler(HttpStatusCode::is4xxClientError, (req, res) -> {
          throw new AuditRejected(res.getStatusCode().value());      // terminal
        })
        .build();
  }
}

class AuditUnavailable extends RuntimeException {   // their problem: 5xx, timeouts
  AuditUnavailable(int status) { super("audit unavailable: " + status); }
}
class AuditRejected extends RuntimeException {      // our problem: 4xx
  AuditRejected(int status) { super("audit rejected the request: " + status); }
}

Using it is deliberately boring — and note the idempotency thinking baked into the payload: the event carries the task id and type, so if a retry does happen after an ambiguous timeout, the audit service can deduplicate. The same reasoning as idempotency keys on the backend-foundations page, spelled in Java.

@Service
public class AuditService {

  private final RestClient client;

  AuditService(RestClient auditClient) { this.client = auditClient; }

  public void recordDone(Task task) {
    client.post()
        .uri("/events")
        .contentType(MediaType.APPLICATION_JSON)
        .body(new AuditEvent("task.done", task.id(), Instant.now()))
        .retrieve()
        .toBodilessEntity();     // throws AuditUnavailable / AuditRejected on error
  }
}

record AuditEvent(String type, UUID taskId, Instant at) { }

Wire it in with one field and one line — TaskService takes an AuditService through its constructor next to the repository, and markDone reports the event after the save:

// TaskService.java -- markDone, after wiring in the audit client
public Task markDone(UUID id) {
    var e = repo.findById(id).orElseThrow(() -> new TaskNotFoundException(id));
    e.markDone();
    var task = repo.save(e).toTask();
    audit.recordDone(task);     // audit is the constructor-injected AuditService
    return task;
}

$ jwebserver -p 9090 &
$ ./mvnw spring-boot:run -Dspring-boot.run.arguments=--audit.base-url=http://localhost:9090
$ curl -s -X PATCH localhost:8080/tasks/<id>/done
... AuditUnavailable: audit unavailable: 501    ← the 5xx handler fired
$ kill %1                         # done with the static server; Ctrl-C the app too
$ ./mvnw spring-boot:run -Dspring-boot.run.arguments=--audit.base-url=http://10.255.255.1:9090
$ time curl -s -X PATCH localhost:8080/tasks/<id>/done
real  0m2.1s    ← packets into a black hole: the 2s connect timeout, not an infinite hang

Two test dependencies join the pom, and then one complete test per rung.

<!-- pom.xml, test scope -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-testcontainers</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>postgresql</artifactId>
  <scope>test</scope>
</dependency>

// rung 1 -- plain JUnit: no Spring anywhere on the classpath of this test’s mind
class TaskEntityTest {

  @Test
  void entityAndRecordRoundTrip() {
    var id = UUID.randomUUID();
    var e = new TaskEntity(id, "buy milk", false, Instant.EPOCH);

    assertEquals(new Task(id, "buy milk", false, Instant.EPOCH), e.toTask());
  }

  @Test
  void markDoneFlipsTheFlagOnly() {
    var e = new TaskEntity(UUID.randomUUID(), "t", false, Instant.EPOCH);
    e.markDone();
    assertTrue(e.done());
  }
}

// rung 2 -- the web slice: controller + advice + validation, service mocked
@WebMvcTest(TaskController.class)
class TaskControllerTest {

  @Autowired MockMvc mvc;
  @MockitoBean TaskService service;      // replaces the real bean in the slice

  @Test
  void missingTaskBecomesA404Problem() throws Exception {
    var id = UUID.randomUUID();
    when(service.get(id)).thenThrow(new TaskNotFoundException(id));

    mvc.perform(get("/tasks/{id}", id))
       .andExpect(status().isNotFound())
       .andExpect(jsonPath("$.title").value("Task not found"));
  }

  @Test
  void blankTitleNeverReachesTheService() throws Exception {
    mvc.perform(post("/tasks")
           .contentType(MediaType.APPLICATION_JSON)
           .content("{\"title\":\"\"}"))
       .andExpect(status().isBadRequest())
       .andExpect(jsonPath("$.errors[0].field").value("title"));

    verifyNoInteractions(service);       // validation rejected it at the door
  }
}

// rung 3 -- the full path, against the same postgres:16 production runs
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@Testcontainers
class TasksEndToEndTest {

  @Container
  @ServiceConnection                     // injects url/user/password automatically
  static PostgreSQLContainer<?> db = new PostgreSQLContainer<>("postgres:16");

  @Autowired TestRestTemplate http;

  @Test
  void createThenFetchAgainstRealPostgres() {
    var created = http.postForObject("/tasks",
        Map.of("title", "prove the whole stack"), Task.class);

    var fetched = http.getForObject("/tasks/" + created.id(), Task.class);

    assertEquals(created, fetched);      // through Flyway, Hibernate, and back
  }
}

@ServiceConnection is the piece worth pausing on: it replaces the datasource properties with the container’s coordinates before the context starts, so Flyway runs your real migrations against the throwaway database. The test proves V1, the entity mapping, the derived queries and the JSON boundary in one pass — which is why a handful of these carries so much weight.

$ ./mvnw verify
[INFO] Tests run: 2 ... TaskEntityTest        ← milliseconds
[INFO] Tests run: 2 ... TaskControllerTest    ← the web slice
[INFO] Tests run: 1 ... TasksEndToEndTest     ← real Postgres, via Docker
[INFO] BUILD SUCCESS

First the production settings, then the image. The probes property gives the health endpoint two sub-paths that mean exactly what the cloud page’s liveness and readiness probes need them to mean — and Boot flips readiness during startup and shutdown automatically.

# application.yml -- the production additions
server:
  shutdown: graceful              # drain in-flight requests on SIGTERM
spring:
  lifecycle:
    timeout-per-shutdown-phase: 20s   # stay under the pod’s 30s grace period
management:
  endpoint:
    health:
      probes:
        enabled: true             # exposes /liveness and /readiness
  endpoints:
    web:
      exposure:
        include: health           # and nothing else, on purpose

# and in the Deployment, from the cloud page:
#   livenessProbe:  httpGet /actuator/health/liveness  :8080
#   readinessProbe: httpGet /actuator/health/readiness :8080

(That block assumes spring-boot-starter-actuator is in the pom — one dependency, no version.) Now the Dockerfile. ./mvnw package produces one fat jar, and the trick is to not copy it into the image as one blob: jarmode=tools extracts it into layers so the 40 MB of dependencies — which change rarely — sit in a different image layer from your classes, which change every commit. Rebuilds and pulls then move kilobytes, not the world.

# Dockerfile
FROM eclipse-temurin:21-jre AS extract
WORKDIR /app
COPY target/tasks-0.0.1-SNAPSHOT.jar app.jar
RUN java -Djarmode=tools -jar app.jar extract --layers --destination extracted

FROM eclipse-temurin:21-jre
WORKDIR /app
RUN useradd --system app
USER app                                  # never root; nothing here needs it

# rarely-changing layers first: cache hits on every rebuild
COPY --from=extract /app/extracted/dependencies/          ./
COPY --from=extract /app/extracted/spring-boot-loader/    ./
COPY --from=extract /app/extracted/snapshot-dependencies/ ./
COPY --from=extract /app/extracted/application/           ./

# the memory lesson from the JVM part, applied
ENV JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=75 -XX:+ExitOnOutOfMemoryError"
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

ExitOnOutOfMemoryError deserves its one sentence: a JVM that has thrown OutOfMemoryError on some thread is a zombie that still answers liveness probes, and it is better to die and be restarted by the kubelet than to limp.

$ ./mvnw -q package -DskipTests
$ docker build -t tasks:1 .
$ docker run --rm --network host --memory 512m tasks:1
$ curl -s localhost:8080/actuator/health/readiness
{"status":"UP"}                              ← K8s would route traffic now
$ curl -s localhost:8080/actuator/health/liveness
{"status":"UP"}
# change one line of TaskService, package, rebuild:
$ docker build -t tasks:2 .
=> CACHED [stage-1 4/8] COPY --from=extract /app/extracted/dependencies/ ./
=> [stage-1 7/8] COPY --from=extract /app/extracted/application/ ./   ← only this moved

$ ./mvnw spotless:check
[ERROR] The following files had format violations: TaskService.java   ← caught
$ ./mvnw spotless:apply && ./mvnw spotless:check
[INFO] Spotless check succeeded.

<!-- pom.xml, inside <build><plugins> -->
<plugin>
  <groupId>com.diffplug.spotless</groupId>
  <artifactId>spotless-maven-plugin</artifactId>
  <version>2.44.0</version>
  <configuration>
    <java><googleJavaFormat/></java>
  </configuration>
  <executions>
    <execution><goals><goal>check</goal></goals></execution>  <!-- fails mvn verify -->
  </executions>
</plugin>

$ ./mvnw spotless:apply                  # format — never argue about it again
$ ./mvnw verify                          # compiles, unit + slice + container tests, coverage
$ ./mvnw versions:display-dependency-updates | grep -A2 spring-boot
# then read your own diff — these catch what the tools do not:
$ git diff --cached | grep -nE '@Autowired|System\.out|printStackTrace'
$ git diff --cached | grep -nE 'catch \(Exception|\.get\(\)|new Thread\('
$ git diff --cached | grep -nE 'password|secret|apikey' # nothing hard-coded, ever

shortlink/
  pom.xml                 the one file in the repository that names a version
  mvnw                    the Maven wrapper. Committed, so CI needs no Maven.
  .mvn/
    wrapper/              the wrapper's properties: which Maven, from where
  .env.example            every variable the app reads, with safe placeholders
  compose.yaml            Postgres and Redis for local work, nothing else
  Dockerfile              multi-stage; the runtime stage has no compiler in it
  Makefile                the four commands everyone needs, named the same way

  src/
    main/
      java/
        info/jaspreet/shortlink/
          ShortlinkApplication.java   the entry point. Three lines, no logic.
          config/
            ShortlinkProperties.java  typed settings, validated at boot
            SecurityConfig.java       the filter chain, and what is public
          domain/
            ShortCode.java            a value object that cannot be malformed
            TargetUrl.java            the parse that keeps javascript: out
            Link.java                 the thing itself. No annotations at all.
            CodeGenerator.java        SecureRandom over a confusable-free set
          persistence/
            LinkStore.java            the four methods the service actually uses
            LinkEntity.java           the table. A class, because JPA needs one.
            LinkRecordRepository.java Spring Data, and two deletes in JPQL
            LinkWriter.java           the insert, in its own transaction
            ApiKeyStore.java          one lookup, by hash, and nothing else
          service/
            LinkService.java          the use cases. Knows no HTTP.
          web/
            LinkController.java       /v1/links: create, read, delete
            RedirectController.java   GET /{code}: the only public route
            LinkDtos.java             the wire contract, with the constraints
            ApiExceptionHandler.java  one advice, one problem+json shape
            RequestIdFilter.java      the id every log line carries
          error/
            ShortlinkException.java   a sealed hierarchy the compiler checks
          security/
            ApiKey.java               who is calling: the principal, a record
            ApiKeyFilter.java         hash, look up, compare in constant time
            RateLimiter.java          Redis, because a HashMap is not one
      resources/
        application.yaml              defaults and the shape of every setting
        application-local.yaml        the profile compose.yaml matches
        db/migration/
          V1__create_links.sql        Flyway. One file per schema change.
    test/
      java/
        info/jaspreet/shortlink/
          ArchitectureTest.java       the layering rule, as a failing build
          domain/ShortCodeTest.java   pure, fast, no Spring context at all
          IntegrationTest.java        the base class that owns the containers
          web/LinkApiTest.java        through the real app, real Postgres
          web/ErrorContractTest.java  the failure shape, which is also an API

  .github/workflows/ci.yaml

Two things in that tree are opinions rather than conventions, and both are worth defending in a review. The packages are named for layers, not for features, because this service has exactly one feature; the moment it has four, the top level becomes links/, owners/, billing/ and each of those gets this same inside. And the domain package sits at the bottom with nothing under it, because the direction of every import in the tree points inward toward it.

That table is the whole architecture, and unlike a diagram it can fail a pull request: ArchitectureTest in the tests topic is those five rows, written once, checked on every build. Now the two files that make the tree buildable.

<!-- pom.xml -- the only place a version number appears. -->
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>

  <!-- The parent supplies a curated version for every Spring dependency
       and for a hundred others. Its version is the single upgrade lever
       for this repository: bump it deliberately, on purpose, and read the
       release notes. Nothing below states a version of its own. -->
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.5</version>
    <relativePath/>
  </parent>

  <groupId>info.jaspreet</groupId>
  <artifactId>shortlink</artifactId>
  <version>0.1.0</version>

  <properties>
    <java.version>21</java.version>
    <archunit.version>1.3.0</archunit.version>
  </properties>

  <dependencies>
    <!-- The web starter brings Tomcat, Jackson and the MVC stack. -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Validation is a separate starter since Boot 2.3. Without it,
         @Valid on a controller argument silently does nothing. -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-redis</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
      <groupId>org.flywaydb</groupId>
      <artifactId>flyway-database-postgresql</artifactId>
    </dependency>
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <scope>runtime</scope>
    </dependency>
    <dependency>
      <groupId>io.micrometer</groupId>
      <artifactId>micrometer-registry-prometheus</artifactId>
      <scope>runtime</scope>
    </dependency>

    <!-- Test scope. None of this is in the shipped jar. -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.security</groupId>
      <artifactId>spring-security-test</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-testcontainers</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.testcontainers</groupId>
      <artifactId>postgresql</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>com.tngtech.archunit</groupId>
      <artifactId>archunit-junit5</artifactId>
      <version>${archunit.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
      <!-- Surefire runs *Test; failsafe runs *IT in the integration-test
           phase, after the app is packaged. Keeping them apart is what
           lets `mvn test` stay fast enough to run on every save. -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-failsafe-plugin</artifactId>
        <executions>
          <execution>
            <goals><goal>integration-test</goal><goal>verify</goal></goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

# Makefile -- four verbs, the same four in every repository you own.
# CI runs these exact targets, so "works on my machine" has one less place to hide.
.PHONY: up check test run image

up:                     ## Postgres and Redis, nothing else
	docker compose up -d

check:                  ## compile, and fail on anything a human would comment on
	./mvnw -B -ntp verify -DskipTests

test:                   ## unit tests, then the ones that start containers
	./mvnw -B -ntp verify

run: up                 ## the local profile, against the compose services
	SPRING_PROFILES_ACTIVE=local ./mvnw -B -ntp spring-boot:run

image:                  ## exactly what CI builds, byte for byte
	docker build -t shortlink:$(shell git rev-parse --short HEAD) .

// src/main/java/info/jaspreet/shortlink/config/ShortlinkProperties.java
package info.jaspreet.shortlink.config;

import jakarta.validation.Valid;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotNull;
import java.net.URI;
import java.time.Duration;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

/**
 * Every setting this service has, in one type. A record gets constructor
 * binding for free, which means the object is immutable and complete or it
 * does not exist -- there is no half-configured instance for a bean to hold.
 *
 * @Validated is what turns a bad value into a failed startup rather than a
 * NullPointerException at 3am. Boot fails the context, prints the property
 * name and the constraint that rejected it, and exits non-zero, so the
 * orchestrator never routes traffic here at all.
 */
@Validated
@ConfigurationProperties(prefix = "shortlink")
public record ShortlinkProperties(

    /** Where the short links point. Used to build the Location header. */
    @NotNull URI publicBaseUrl,

    /** Characters in a generated code. Seven is ~34 billion codes. */
    @Min(4) @Max(32) int codeLength,

    /** How long a link lives when the caller does not say. */
    @NotNull Duration defaultTtl,

    @Valid @NotNull RateLimit rateLimit) {

  public record RateLimit(@Min(1) int perMinute, @NotNull Duration window) {}
}

// Relaxed binding means public-base-url, PUBLIC_BASE_URL and publicBaseUrl
// all reach publicBaseUrl. Write kebab-case in YAML and SCREAMING_SNAKE in
// the environment; both are conventional and both arrive at the same field.
//
// Nothing enables this by hand: @ConfigurationPropertiesScan on the
// application class finds every @ConfigurationProperties in the package tree.
// Inject the record where you need it. Never inject Environment.

# application.yaml -- the defaults, and the shape of every setting.
# Anything genuinely secret has no default at all: the ${...} placeholder
# with no fallback is deliberate, so an unset variable fails the context
# instead of quietly connecting to something that happens to be listening.
spring:
  application:
    name: shortlink
  threads:
    virtual:
      enabled: true             # Boot 3.2+: one virtual thread per request
  datasource:
    url: ${DATABASE_URL}
    username: ${DATABASE_USER}
    password: ${DATABASE_PASSWORD}
    hikari:
      maximum-pool-size: 10     # the real concurrency limit. See the note.
      minimum-idle: 10          # same as max: a fixed pool has no warm-up
      connection-timeout: 2000  # milliseconds. HikariConfig takes longs,
      validation-timeout: 1000  # not Durations, so "2s" will not bind here.
      max-lifetime: 1500000     # 25 min, under any proxy's idle timeout
  jpa:
    open-in-view: false         # see the warning. Default is true. It is wrong.
    hibernate:
      ddl-auto: validate        # Flyway owns the schema. Hibernate checks it.
    properties:
      hibernate:
        jdbc:
          batch_size: 50
  flyway:
    enabled: true
    validate-on-migrate: true
  data:
    redis:
      url: ${REDIS_URL}
      timeout: 250ms            # a slow limiter must not become a slow API
  mvc:
    problemdetails:
      enabled: true             # Spring's own 4xx become application/problem+json

server:
  shutdown: graceful
  forward-headers-strategy: framework   # honour X-Forwarded-* behind the LB

shortlink:
  public-base-url: ${SHORTLINK_PUBLIC_BASE_URL}
  code-length: 7
  default-ttl: 90d
  rate-limit:
    per-minute: 60
    window: 1m

management:
  endpoints:
    web:
      exposure:
        include: health,prometheus     # and nothing else, on purpose
  endpoint:
    health:
      probes:
        enabled: true
      show-details: never              # a health page is not a debug console

logging:
  structured:
    format:
      console: ecs                     # Boot 3.4+: JSON logs, no encoder XML

# .env.example -- committed. The real .env is not, and .gitignore says so.
# The point of this file is that a new engineer can diff it against their
# own .env and see exactly what they are missing.
DATABASE_URL=jdbc:postgresql://localhost:5432/shortlink
DATABASE_USER=shortlink
DATABASE_PASSWORD=local-only-not-a-secret
REDIS_URL=redis://localhost:6379
SHORTLINK_PUBLIC_BASE_URL=http://localhost:8080
# In production none of these come from a file. They come from the
# platform's secret store, injected as environment variables, and the
# application cannot tell the difference -- which is the whole point.

$ SHORTLINK_PUBLIC_BASE_URL= ./mvnw -q spring-boot:run
***************************
APPLICATION FAILED TO START
***************************

Description:

Binding to target info.jaspreet.shortlink.config.ShortlinkProperties failed:

    Property: shortlink.publicBaseUrl
    Value: ""
    Reason: must not be null

Action:

Update your application's configuration
$ echo $?
1
# Twelve seconds after the deploy started, not on the tenth request.

// src/main/java/info/jaspreet/shortlink/domain/ShortCode.java
package info.jaspreet.shortlink.domain;

import java.util.Locale;
import java.util.Objects;
import java.util.regex.Pattern;

/**
 * The code in the short URL. A record over a single String, which sounds
 * like ceremony until you count the methods that take two Strings and can
 * be called with them the wrong way round.
 */
public record ShortCode(String value) {

  private static final Pattern SHAPE = Pattern.compile("[a-z0-9]{4,32}");

  // A compact constructor may reassign the parameter before it is written
  // to the field, so normalising and validating happen in one place and
  // there is no way to construct an instance that skips them.
  public ShortCode {
    Objects.requireNonNull(value, "value");
    value = value.trim().toLowerCase(Locale.ROOT);
    if (!SHAPE.matcher(value).matches()) {
      throw new IllegalArgumentException("not a short code: " + value);
    }
  }

  @Override
  public String toString() {
    return value;
  }
}

// src/main/java/info/jaspreet/shortlink/domain/TargetUrl.java
package info.jaspreet.shortlink.domain;

import java.net.URI;
import java.net.URISyntaxException;
import java.util.Locale;
import java.util.Set;

/** The URL a code points at. Parsing it is a security control, not a format check. */
public record TargetUrl(URI value) {

  private static final Set<String> SCHEMES = Set.of("http", "https");
  private static final int MAX_LENGTH = 2048;

  public static TargetUrl parse(String raw) {
    if (raw == null || raw.isBlank()) {
      throw new IllegalArgumentException("url is required");
    }
    if (raw.length() > MAX_LENGTH) {
      throw new IllegalArgumentException("url longer than " + MAX_LENGTH);
    }
    URI uri;
    try {
      uri = new URI(raw.trim()).normalize();
    } catch (URISyntaxException e) {
      throw new IllegalArgumentException("url is not a valid URI", e);
    }
    // The one that matters: without this, "javascript:alert(1)" is a link
    // you will happily hand a browser a 302 to, from your own domain.
    String scheme = uri.getScheme() == null ? "" : uri.getScheme().toLowerCase(Locale.ROOT);
    if (!uri.isAbsolute() || !SCHEMES.contains(scheme)) {
      throw new IllegalArgumentException("only http and https can be shortened");
    }
    if (uri.getHost() == null || uri.getHost().isBlank()) {
      throw new IllegalArgumentException("url has no host");
    }
    // http://user:pass@host is a credential in a database column.
    if (uri.getUserInfo() != null) {
      throw new IllegalArgumentException("credentials in a url are not stored");
    }
    return new TargetUrl(uri);
  }
}

// src/main/java/info/jaspreet/shortlink/domain/Link.java
package info.jaspreet.shortlink.domain;

import java.time.Instant;

/**
 * The thing itself. Note what is absent: no @Entity, no @Id, no getters
 * generated by a library, and no identifier column -- the database's
 * primary key is the database's business, and this record is what the rest
 * of the application passes around.
 *
 * ownerId is a String here for brevity; in a service with more than one
 * kind of id, make it a record too. Two adjacent Strings in a signature is
 * a bug waiting for someone to reorder the arguments.
 */
public record Link(
    ShortCode code,
    TargetUrl target,
    String ownerId,
    Instant createdAt,
    Instant expiresAt) {

  public boolean isExpired(Instant now) {
    return expiresAt != null && !now.isBefore(expiresAt);
  }
}

// src/main/java/info/jaspreet/shortlink/domain/CodeGenerator.java
package info.jaspreet.shortlink.domain;

import java.security.SecureRandom;

/**
 * Codes are random, not sequential. A sequential code leaks how many links
 * exist and lets anyone walk every link you have ever made by counting.
 *
 * The alphabet has 32 characters, not 36: 0/o, 1/l and their friends are
 * removed so a code read aloud or copied off a slide survives the trip.
 */
public final class CodeGenerator {

  private static final char[] ALPHABET = "23456789abcdefghijkmnpqrstuvwxyz".toCharArray();

  private final SecureRandom random = new SecureRandom();
  private final int length;

  public CodeGenerator(int length) {
    this.length = length;
  }

  public ShortCode next() {
    char[] out = new char[length];
    for (int i = 0; i < out.length; i++) {
      out[i] = ALPHABET[random.nextInt(ALPHABET.length)];
    }
    return new ShortCode(new String(out));
  }
}

// 32^7 is about 34 billion codes. With ten million links already stored, a
// fresh code collides roughly once every 3,400 inserts -- rare, but not
// never, and "rare" is the failure mode that reaches production untested.
// The unique index catches it and the repository retries; see the next
// topic. The generator does not have to be perfect, it has to be random.

// src/main/java/info/jaspreet/shortlink/web/LinkDtos.java
package info.jaspreet.shortlink.web;

import com.fasterxml.jackson.annotation.JsonInclude;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import java.time.Instant;

/**
 * The wire contract. Three shapes now exist for one concept -- this DTO,
 * the domain record, and the JPA entity -- and that is the design, not an
 * accident. They change for different reasons: the DTO when the API's
 * consumers need something, the entity when the schema does, the domain
 * record when the rules do. Collapsing them into one class couples all
 * three, and the first person to add a column discovers they have changed
 * the public API.
 */
final class LinkDtos {

  record CreateLinkRequest(
      @NotBlank @Size(max = 2048) String url,
      @Size(max = 64) String alias,          // optional: a vanity code
      Integer ttlDays) {}                    // optional: null means default

  @JsonInclude(JsonInclude.Include.NON_NULL)
  record LinkResponse(
      String code,
      String shortUrl,
      String url,
      Instant createdAt,
      Instant expiresAt) {}

  private LinkDtos() {}
}

// The constraints are on the DTO rather than in the domain because they
// are the API's promise about its inputs -- a 400 with a field name is a
// different thing from an invariant the domain refuses to break. The
// domain checks the same facts again, in the constructor, and always will:
// the service has callers that never came through HTTP.

-- V1__create_links.sql -- Flyway runs this once, in order, and records it.
-- Once this file has run anywhere but your laptop it is immutable. A fix
-- is V2, always, because Flyway checksums what it has already applied and
-- will refuse to start against a file that changed underneath it.

CREATE TABLE links (
    id              BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    code            TEXT        NOT NULL,
    target_url      TEXT        NOT NULL,
    owner_id        TEXT        NOT NULL,
    idempotency_key TEXT,
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    expires_at      TIMESTAMPTZ,

    -- Named, not auto-generated. The service switches on this name to tell
    -- "that code is taken" apart from "that request already happened", and
    -- a name Postgres invented is a name someone will change by accident.
    CONSTRAINT links_code_key UNIQUE (code)
);

-- Idempotency, as a constraint rather than as a check in application code.
-- Partial, because most links have no key and NULLs are not equal to each
-- other -- without the WHERE clause this index would be pointless on
-- Postgres and wrong on a database where NULLs do compare equal.
CREATE UNIQUE INDEX links_owner_idempotency_key
    ON links (owner_id, idempotency_key)
    WHERE idempotency_key IS NOT NULL;

-- The list endpoint's query, in the order it reads.
CREATE INDEX links_owner_created_at ON links (owner_id, created_at DESC);

CREATE TABLE api_keys (
    id         BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    owner_id   TEXT NOT NULL,
    label      TEXT NOT NULL,
    key_hash   TEXT NOT NULL,   -- sha-256 hex. Never the key itself.
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    revoked_at TIMESTAMPTZ,

    CONSTRAINT api_keys_key_hash_key UNIQUE (key_hash)
);

// src/main/java/info/jaspreet/shortlink/persistence/LinkEntity.java
package info.jaspreet.shortlink.persistence;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import java.time.Instant;
import java.util.Objects;

/**
 * The table, as Hibernate needs to see it: a class with a no-arg
 * constructor and mutable fields. This is the one place in the service
 * where "make it a record" is not the answer -- Hibernate constructs
 * instances reflectively and populates them afterwards, and a record has
 * nothing to populate.
 *
 * It stays package-private to the persistence layer as far as the compiler
 * allows, and nothing outside this package ever sees one: the repository
 * hands back domain records.
 */
@Entity
@Table(name = "links")
public class LinkEntity {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;

  @Column(nullable = false, updatable = false)
  private String code;

  @Column(name = "target_url", nullable = false)
  private String targetUrl;

  @Column(name = "owner_id", nullable = false, updatable = false)
  private String ownerId;

  @Column(name = "idempotency_key", updatable = false)
  private String idempotencyKey;

  @Column(name = "created_at", nullable = false, updatable = false)
  private Instant createdAt;

  @Column(name = "expires_at")
  private Instant expiresAt;

  protected LinkEntity() {
    // for Hibernate, and for nobody else
  }

  LinkEntity(String code, String targetUrl, String ownerId,
             String idempotencyKey, Instant createdAt, Instant expiresAt) {
    this.code = code;
    this.targetUrl = targetUrl;
    this.ownerId = ownerId;
    this.idempotencyKey = idempotencyKey;
    this.createdAt = createdAt;
    this.expiresAt = expiresAt;
  }

  // equals and hashCode over the natural key, not over the id. The id is
  // null until the row is flushed, so an entity added to a HashSet before
  // the flush and looked up after it would be gone -- the hash changed
  // while the object was in the bucket. code is assigned before persist
  // and never updated, so it is stable for the object's whole life, which
  // is exactly what the collections topic said the contract requires.
  @Override
  public boolean equals(Object other) {
    return other instanceof LinkEntity that && Objects.equals(code, that.code);
  }

  @Override
  public int hashCode() {
    return Objects.hashCode(code);
  }

  Long getId() { return id; }
  String getCode() { return code; }
  String getTargetUrl() { return targetUrl; }
  String getOwnerId() { return ownerId; }
  String getIdempotencyKey() { return idempotencyKey; }
  Instant getCreatedAt() { return createdAt; }
  Instant getExpiresAt() { return expiresAt; }

  void setTargetUrl(String targetUrl) { this.targetUrl = targetUrl; }
  void setExpiresAt(Instant expiresAt) { this.expiresAt = expiresAt; }
}

// src/main/java/info/jaspreet/shortlink/persistence/LinkRecordRepository.java
package info.jaspreet.shortlink.persistence;

import java.time.Instant;
import java.util.List;
import java.util.Optional;
import org.springframework.data.domain.Limit;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Modifying;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

interface LinkRecordRepository extends JpaRepository<LinkEntity, Long> {

  // Derived queries. The method name is the query, which means renaming
  // the method is a schema-level change and not a refactor -- one reason
  // to keep this interface small and its names boring.
  Optional<LinkEntity> findByCode(String code);

  Optional<LinkEntity> findByOwnerIdAndIdempotencyKey(String ownerId, String idempotencyKey);

  List<LinkEntity> findByOwnerIdOrderByCreatedAtDesc(String ownerId, Limit limit);

  // Written out, because the derived form of "delete only if it is yours"
  // reads worse than the JPQL and this one has to be exactly right.
  @Modifying
  @Query("delete from LinkEntity l where l.code = :code and l.ownerId = :ownerId")
  int deleteOwnedByCode(@Param("code") String code, @Param("ownerId") String ownerId);

  @Modifying
  @Query("delete from LinkEntity l where l.expiresAt < :cutoff")
  int deleteExpiredBefore(@Param("cutoff") Instant cutoff);
}

// src/main/java/info/jaspreet/shortlink/persistence/LinkWriter.java
package info.jaspreet.shortlink.persistence;

import info.jaspreet.shortlink.error.ShortlinkException.CodeTaken;
import info.jaspreet.shortlink.error.ShortlinkException.IdempotencyClash;
import java.time.Instant;
import org.hibernate.exception.ConstraintViolationException;
import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.stereotype.Component;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

/**
 * The insert, alone, in a transaction of its own -- and this is the whole
 * point of the class existing rather than being a method on the service.
 *
 * A constraint violation marks the current transaction rollback-only. You
 * cannot catch it and carry on inside the same transaction: the next
 * statement fails with "Transaction silently rolled back" and the real
 * cause is three frames further back. So the attempt that might fail gets
 * its own boundary, and the caller's catch block sits outside it, where
 * there is nothing broken to continue.
 *
 * REQUIRES_NEW rather than the default, so this stays true on the day
 * somebody annotates the service. And a separate bean rather than a
 * private method, because @Transactional is a proxy and a call to this.x()
 * never touches it.
 */
@Component
public class LinkWriter {

  private static final String CODE_UNIQUE = "links_code_key";
  private static final String IDEMPOTENCY_UNIQUE = "links_owner_idempotency_key";

  private final LinkRecordRepository rows;

  LinkWriter(LinkRecordRepository rows) {
    this.rows = rows;
  }

  @Transactional(propagation = Propagation.REQUIRES_NEW)
  public LinkEntity insert(String code, String targetUrl, String ownerId,
                           String idempotencyKey, Instant createdAt, Instant expiresAt) {
    var row = new LinkEntity(code, targetUrl, ownerId, idempotencyKey, createdAt, expiresAt);
    try {
      // saveAndFlush, not save. save() only queues the insert; without the
      // flush the violation surfaces when the transaction commits, which
      // is after this method returns and outside this try block.
      return rows.saveAndFlush(row);
    } catch (DataIntegrityViolationException e) {
      // Translate infrastructure into domain here, so that nothing above
      // this package has to know Hibernate exists. Java 21's switch over
      // a String with a null label makes the three cases explicit.
      throw switch (constraintOf(e)) {
        case CODE_UNIQUE -> new CodeTaken(code);
        case IDEMPOTENCY_UNIQUE -> new IdempotencyClash(idempotencyKey);
        case null, default -> e;   // some other constraint: not ours to explain
      };
    }
  }

  private static String constraintOf(DataIntegrityViolationException e) {
    return e.getCause() instanceof ConstraintViolationException violation
        ? violation.getConstraintName()
        : null;
  }
}

// src/main/java/info/jaspreet/shortlink/service/LinkService.java
package info.jaspreet.shortlink.service;

import info.jaspreet.shortlink.domain.CodeGenerator;
import info.jaspreet.shortlink.domain.Link;
import info.jaspreet.shortlink.domain.ShortCode;
import info.jaspreet.shortlink.domain.TargetUrl;
import info.jaspreet.shortlink.error.ShortlinkException.AliasTaken;
import info.jaspreet.shortlink.error.ShortlinkException.CodeTaken;
import info.jaspreet.shortlink.error.ShortlinkException.IdempotencyClash;
import info.jaspreet.shortlink.error.ShortlinkException.LinkExpired;
import info.jaspreet.shortlink.error.ShortlinkException.LinkNotFound;
import info.jaspreet.shortlink.error.ShortlinkException.NoCodeAvailable;
import info.jaspreet.shortlink.persistence.LinkStore;
import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.util.List;

/**
 * The use cases, and the only place the business rules are sequenced.
 * No HttpServletRequest, no ResponseEntity, no status codes -- everything
 * here would work unchanged from a message consumer or a CLI, which is the
 * test for whether a service layer is worth having at all.
 *
 * There is no @Service on it either, and no Spring import in this file at
 * all. It is a plain object with four constructor arguments; the
 * configuration class decides what those are. That costs four lines there
 * and buys a rule ArchUnit can state without exceptions -- the service
 * package does not depend on the framework -- plus a constructor a test
 * can call with a fake clock and no context at all.
 */
public class LinkService {

  private static final int MAX_CODE_ATTEMPTS = 5;

  private final LinkStore links;
  private final CodeGenerator codes;
  private final Clock clock;
  private final Duration defaultTtl;

  public LinkService(LinkStore links, CodeGenerator codes, Clock clock, Duration defaultTtl) {
    this.links = links;
    this.codes = codes;
    this.clock = clock;          // injected, so a test can freeze time
    this.defaultTtl = defaultTtl;
  }

  /** Everything one create needs, so the signature cannot be called wrong. */
  public record NewLink(String ownerId, TargetUrl target,
                        ShortCode alias, Duration ttl, String idempotencyKey) {}

  public Link shorten(NewLink request) {
    // The fast path: a client retrying after a timeout, seconds later.
    if (request.idempotencyKey() != null) {
      var existing = links.findByIdempotencyKey(request.ownerId(), request.idempotencyKey());
      if (existing.isPresent()) {
        return existing.get();
      }
    }

    Instant now = clock.instant();
    Instant expiresAt = now.plus(request.ttl() == null ? defaultTtl : request.ttl());

    for (int attempt = 1; attempt <= MAX_CODE_ATTEMPTS; attempt++) {
      ShortCode code = request.alias() != null ? request.alias() : codes.next();
      try {
        return links.insert(code, request, now, expiresAt);
      } catch (IdempotencyClash clash) {
        // The slow path: a genuine race. The other request won, and its
        // link is the correct answer to both of them.
        return links.findByIdempotencyKey(request.ownerId(), request.idempotencyKey())
            .orElseThrow(() -> new IllegalStateException("clash with no winner", clash));
      } catch (CodeTaken taken) {
        // A caller's chosen alias is a 409 they can act on. A generated
        // code that collided is our problem, and the fix is another code.
        if (request.alias() != null) {
          throw new AliasTaken(code);
        }
      }
    }
    throw new NoCodeAvailable(MAX_CODE_ATTEMPTS);
  }

  public Link resolve(ShortCode code) {
    Link link = links.findByCode(code).orElseThrow(() -> new LinkNotFound(code));
    if (link.isExpired(clock.instant())) {
      // Deliberately not 404: a client that gets "gone" can stop retrying,
      // and an operator reading the logs can tell the two apart.
      throw new LinkExpired(code);
    }
    return link;
  }

  public Link readOwned(String ownerId, ShortCode code) {
    return links.findByCode(code)
        .filter(link -> link.ownerId().equals(ownerId))
        .orElseThrow(() -> new LinkNotFound(code));
  }

  public List<Link> listOwned(String ownerId, int limit) {
    return links.listOwned(ownerId, Math.clamp(limit, 1, 500));
  }

  public void delete(String ownerId, ShortCode code) {
    if (links.deleteOwned(ownerId, code) == 0) {
      // Zero rows means it does not exist or it is not yours, and the API
      // says the same thing for both. Telling an unauthorised caller that
      // a code exists is how you enumerate a database.
      throw new LinkNotFound(code);
    }
  }
}

LinkStore is a small interface in the persistence package — findByCode, findByIdempotencyKey, insert, deleteOwned — implemented by a class that owns the repository and the writer and does the entity-to-domain mapping. It exists so that the service depends on four methods it defined rather than on the twenty JpaRepository supplies, and so that ArchitectureTest can say the service package does not import Spring Data at all.

// src/main/java/info/jaspreet/shortlink/web/LinkController.java
package info.jaspreet.shortlink.web;

import info.jaspreet.shortlink.domain.Link;
import info.jaspreet.shortlink.domain.ShortCode;
import info.jaspreet.shortlink.config.ShortlinkProperties;
import info.jaspreet.shortlink.domain.TargetUrl;
import info.jaspreet.shortlink.security.ApiKey;
import info.jaspreet.shortlink.service.LinkService;
import info.jaspreet.shortlink.service.LinkService.NewLink;
import info.jaspreet.shortlink.web.LinkDtos.CreateLinkRequest;
import info.jaspreet.shortlink.web.LinkDtos.LinkResponse;
import jakarta.validation.Valid;
import java.net.URI;
import java.time.Duration;
import java.util.List;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/v1/links")
class LinkController {

  private final LinkService links;
  private final URI publicBaseUrl;

  LinkController(LinkService links, ShortlinkProperties properties) {
    this.links = links;
    this.publicBaseUrl = properties.publicBaseUrl();
  }

  // 201 with a Location header, because the request created a resource and
  // the caller should not have to build its URL by string concatenation.
  @PostMapping
  ResponseEntity<LinkResponse> create(
      @Valid @RequestBody CreateLinkRequest body,
      @RequestHeader(name = "Idempotency-Key", required = false) String idempotencyKey,
      @AuthenticationPrincipal ApiKey caller) {

    // The two parses are the layer boundary made concrete: strings arrive,
    // value objects go on. Both throw IllegalArgumentException, which the
    // advice turns into a 400 with the message -- see the next topic.
    var request = new NewLink(
        caller.ownerId(),
        TargetUrl.parse(body.url()),
        body.alias() == null ? null : new ShortCode(body.alias()),
        body.ttlDays() == null ? null : Duration.ofDays(body.ttlDays()),
        idempotencyKey);

    Link link = links.shorten(request);
    return ResponseEntity.created(shortUrl(link)).body(toResponse(link));
  }

  @GetMapping("/{code}")
  LinkResponse read(@PathVariable String code, @AuthenticationPrincipal ApiKey caller) {
    return toResponse(links.readOwned(caller.ownerId(), new ShortCode(code)));
  }

  @GetMapping
  List<LinkResponse> list(@AuthenticationPrincipal ApiKey caller) {
    return links.listOwned(caller.ownerId(), 100).stream()
        .map(this::toResponse)
        .toList();
  }

  // 204: it is gone, there is nothing to say about it, and a body on a
  // delete is a thing clients start depending on.
  @DeleteMapping("/{code}")
  @ResponseStatus(HttpStatus.NO_CONTENT)
  void delete(@PathVariable String code, @AuthenticationPrincipal ApiKey caller) {
    links.delete(caller.ownerId(), new ShortCode(code));
  }

  private URI shortUrl(Link link) {
    return publicBaseUrl.resolve("/" + link.code().value());
  }

  private LinkResponse toResponse(Link link) {
    return new LinkResponse(
        link.code().value(),
        shortUrl(link).toString(),
        link.target().value().toString(),
        link.createdAt(),
        link.expiresAt());
  }
}

// src/main/java/info/jaspreet/shortlink/web/RedirectController.java
package info.jaspreet.shortlink.web;

import info.jaspreet.shortlink.domain.Link;
import info.jaspreet.shortlink.domain.ShortCode;
import info.jaspreet.shortlink.service.LinkService;
import org.springframework.http.CacheControl;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

/**
 * The only unauthenticated route in the service, and the only one that
 * gets any real traffic. It is a separate controller from the management
 * API because it has a different audience, a different security rule and a
 * different failure budget -- and because "/{code}" at the root would be a
 * frightening thing to find in a class also mapped to /v1/links.
 */
@RestController
class RedirectController {

  private final LinkService links;

  RedirectController(LinkService links) {
    this.links = links;
  }

  // The regex in the path variable is load-bearing: without it this maps
  // every single-segment path in the application, including ones a future
  // route wants. With it, only things shaped like a code get here.
  @GetMapping("/{code:[a-z0-9]{4,32}}")
  ResponseEntity<Void> follow(@PathVariable String code) {
    Link link = links.resolve(new ShortCode(code));
    return ResponseEntity.status(HttpStatus.FOUND)
        .location(link.target().value())
        .cacheControl(CacheControl.noStore())
        .build();
  }
}

// src/main/java/info/jaspreet/shortlink/ShortlinkApplication.java
package info.jaspreet.shortlink;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;

@SpringBootApplication
@ConfigurationPropertiesScan
public class ShortlinkApplication {

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

// src/main/java/info/jaspreet/shortlink/config/ShortlinkConfig.java
package info.jaspreet.shortlink.config;

import info.jaspreet.shortlink.domain.CodeGenerator;
import info.jaspreet.shortlink.persistence.LinkStore;
import info.jaspreet.shortlink.service.LinkService;
import java.time.Clock;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * The four lines that pay for a framework-free service package. Every bean
 * here is a plain object whose dependencies are explicit at the call site,
 * which is also the reason this file is worth reading first when you are
 * new: it is the whole object graph on one screen.
 */
@Configuration
class ShortlinkConfig {

  // Never Instant.now() inside a method. A clock you can inject is a test
  // that can be about expiry without being about sleeping.
  @Bean
  Clock clock() {
    return Clock.systemUTC();
  }

  @Bean
  CodeGenerator codeGenerator(ShortlinkProperties properties) {
    return new CodeGenerator(properties.codeLength());
  }

  @Bean
  LinkService linkService(LinkStore links, CodeGenerator codes,
                          Clock clock, ShortlinkProperties properties) {
    return new LinkService(links, codes, clock, properties.defaultTtl());
  }
}

// src/main/java/info/jaspreet/shortlink/error/ShortlinkException.java
package info.jaspreet.shortlink.error;

import info.jaspreet.shortlink.domain.ShortCode;

/**
 * Every failure this service raises on purpose, in one sealed hierarchy.
 *
 * Sealed is the point. The handler switches over this type, and because
 * the compiler knows the complete list of subclasses it will reject the
 * switch the moment somebody adds a seventh -- so a new failure mode
 * cannot reach a client as an unmapped 500 six weeks later. That is the
 * same guarantee the sealed-interfaces topic promised, applied to the one
 * place in a service where "I forgot a case" is most expensive.
 *
 * Note what is not here: no status codes, no HTTP. This package is
 * importable from a batch job.
 */
public abstract sealed class ShortlinkException extends RuntimeException {

  protected ShortlinkException(String message) {
    // No cause, no stack trace filled in for the expected ones: these are
    // control flow, not incidents, and a stack trace per 404 is a bill.
    super(message, null, false, false);
  }

  public static final class LinkNotFound extends ShortlinkException {
    public LinkNotFound(ShortCode code) {
      super("no link with code " + code.value());
    }
  }

  public static final class LinkExpired extends ShortlinkException {
    public LinkExpired(ShortCode code) {
      super("link " + code.value() + " has expired");
    }
  }

  public static final class AliasTaken extends ShortlinkException {
    public AliasTaken(ShortCode code) {
      super("the alias " + code.value() + " is already in use");
    }
  }

  public static final class CodeTaken extends ShortlinkException {
    public CodeTaken(String code) {
      super("code " + code + " is already in use");
    }
  }

  public static final class IdempotencyClash extends ShortlinkException {
    public IdempotencyClash(String key) {
      super("concurrent request with idempotency key " + key);
    }
  }

  public static final class NoCodeAvailable extends ShortlinkException {
    public NoCodeAvailable(int attempts) {
      super("no free code after " + attempts + " attempts");
    }
  }
}

A sealed class whose subclasses are nested inside it needs no permits clause — the compiler takes the enclosing file as the permitted set, which is exactly the boundary you want here. Now the one place that knows these are HTTP.

// src/main/java/info/jaspreet/shortlink/web/ApiExceptionHandler.java
package info.jaspreet.shortlink.web;

import info.jaspreet.shortlink.error.ShortlinkException;
import info.jaspreet.shortlink.error.ShortlinkException.AliasTaken;
import info.jaspreet.shortlink.error.ShortlinkException.CodeTaken;
import info.jaspreet.shortlink.error.ShortlinkException.IdempotencyClash;
import info.jaspreet.shortlink.error.ShortlinkException.LinkExpired;
import info.jaspreet.shortlink.error.ShortlinkException.LinkNotFound;
import info.jaspreet.shortlink.error.ShortlinkException.NoCodeAvailable;
import java.net.URI;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

/**
 * One advice, one media type, one shape. RFC 9457 problem+json, which is
 * what Spring's ProblemDetail already produces, so the framework's own
 * 404s and 415s match the ones written here instead of being a second,
 * undocumented error format the client also has to parse.
 */
@RestControllerAdvice
class ApiExceptionHandler {

  private static final Logger log = LoggerFactory.getLogger(ApiExceptionHandler.class);
  private static final String TYPES = "https://study.jaspreet.info/problems/";

  @ExceptionHandler(ShortlinkException.class)
  ProblemDetail onDomainFailure(ShortlinkException failure) {
    // Exhaustive over a sealed type: no default branch, and adding a
    // subclass to the hierarchy breaks this build rather than production.
    ProblemDetail problem = switch (failure) {
      case LinkNotFound e -> of(HttpStatus.NOT_FOUND, "Link not found", e, "link-not-found");
      case LinkExpired e -> of(HttpStatus.GONE, "Link expired", e, "link-expired");
      case AliasTaken e -> of(HttpStatus.CONFLICT, "Alias taken", e, "alias-taken");
      case CodeTaken e -> of(HttpStatus.CONFLICT, "Code taken", e, "code-taken");
      case IdempotencyClash e -> of(HttpStatus.CONFLICT, "Request in flight", e, "in-flight");
      case NoCodeAvailable e -> of(HttpStatus.SERVICE_UNAVAILABLE, "Try again", e, "no-code");
    };
    return problem;
  }

  // Bean validation failures: 400, and say which field, because "invalid
  // request" costs the caller an hour and costs you a support ticket.
  @ExceptionHandler(MethodArgumentNotValidException.class)
  ProblemDetail onInvalidBody(MethodArgumentNotValidException invalid) {
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(
        HttpStatus.BAD_REQUEST, "One or more fields are invalid");
    problem.setTitle("Invalid request");
    problem.setType(URI.create(TYPES + "invalid-request"));
    problem.setProperty("errors", invalid.getBindingResult().getFieldErrors().stream()
        .map(field -> java.util.Map.of(
            "field", field.getField(),
            "message", String.valueOf(field.getDefaultMessage())))
        .toList());
    return problem;
  }

  // The value objects reject bad input by throwing this, and a rejected
  // URL is the caller's mistake, not ours.
  @ExceptionHandler(IllegalArgumentException.class)
  ProblemDetail onIllegalArgument(IllegalArgumentException bad) {
    ProblemDetail problem =
        ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, bad.getMessage());
    problem.setTitle("Invalid request");
    problem.setType(URI.create(TYPES + "invalid-request"));
    return problem;
  }

  // The catch-all. Log everything, tell the client nothing: a stack trace
  // in a response body is a map of your dependencies and their versions.
  @ExceptionHandler(Exception.class)
  ProblemDetail onUnexpected(Exception unexpected) {
    log.error("unhandled exception", unexpected);
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(
        HttpStatus.INTERNAL_SERVER_ERROR, "Unexpected error");
    problem.setTitle("Internal server error");
    problem.setType(URI.create(TYPES + "internal"));
    return problem;
  }

  private static ProblemDetail of(HttpStatus status, String title,
                                  ShortlinkException failure, String type) {
    ProblemDetail problem = ProblemDetail.forStatusAndDetail(status, failure.getMessage());
    problem.setTitle(title);
    problem.setType(URI.create(TYPES + type));
    return problem;
  }
}

$ curl -sS -i -X POST localhost:8080/v1/links \
    -H 'Authorization: Bearer sl_live_notarealkey' \
    -H 'Content-Type: application/json' \
    -d '{"url":"javascript:alert(1)"}'
HTTP/1.1 400
Content-Type: application/problem+json

{
  "type": "https://study.jaspreet.info/problems/invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "only http and https can be shortened",
  "instance": "/v1/links"
}

# and the one every client actually codes against:
$ curl -sS -o /dev/null -w '%{http_code}\n' localhost:8080/gone4evr
410

// src/main/java/info/jaspreet/shortlink/config/SecurityConfig.java
package info.jaspreet.shortlink.config;

import info.jaspreet.shortlink.security.ApiKeyFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.http.MediaType;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@Configuration
@EnableWebSecurity
class SecurityConfig {

  @Bean
  SecurityFilterChain filterChain(HttpSecurity http, ApiKeyFilter apiKeys) throws Exception {
    return http
        // No cookies, no sessions, no browser form anywhere in this service,
        // so there is no credential a browser attaches automatically and
        // therefore nothing for CSRF to forge. Disabling it here is correct
        // and disabling it in a cookie-session app is a vulnerability; the
        // difference is the whole reason to write this comment rather than
        // copy the line.
        .csrf(csrf -> csrf.disable())
        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .httpBasic(AbstractHttpConfigurer::disable)
        .formLogin(AbstractHttpConfigurer::disable)

        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/actuator/health/**").permitAll()
            .requestMatchers(HttpMethod.GET, "/{code:[a-z0-9]{4,32}}").permitAll()
            .requestMatchers("/v1/**").authenticated()
            // Everything not named above is denied. The alternative,
            // anyRequest().permitAll(), means the next route somebody adds
            // is public until they remember it should not be.
            .anyRequest().denyAll())

        .addFilterBefore(apiKeys, UsernamePasswordAuthenticationFilter.class)

        .exceptionHandling(e -> e
            .authenticationEntryPoint((request, response, failure) -> {
              response.setStatus(401);
              response.setHeader("WWW-Authenticate", "Bearer");
              response.setContentType(MediaType.APPLICATION_PROBLEM_JSON_VALUE);
              response.getWriter().write("""
                  {"type":"https://study.jaspreet.info/problems/unauthorized",\
                  "title":"Unauthorized","status":401,\
                  "detail":"a valid API key is required"}""");
            }))

        .headers(Customizer.withDefaults())
        .build();
  }
}

Note what the filter does not do below: it never rejects a request. A missing or unusable key leaves the security context empty and the chain carries on, and the rule in authorizeHttpRequests is what produces the 401 through the entry point above. Filters that write their own 401s end up with two answers for the same question, and the one they write is always the one that forgets the WWW-Authenticate header.

// src/main/java/info/jaspreet/shortlink/security/ApiKey.java
package info.jaspreet.shortlink.security;

/** Who is calling. A record, so nothing downstream can edit it. */
public record ApiKey(String ownerId, String label) {}


// src/main/java/info/jaspreet/shortlink/security/ApiKeyFilter.java
package info.jaspreet.shortlink.security;

import info.jaspreet.shortlink.persistence.ApiKeyStore;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;
import java.util.List;
import org.springframework.http.MediaType;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

@Component
public class ApiKeyFilter extends OncePerRequestFilter {

  private static final String SCHEME = "Bearer ";

  private final ApiKeyStore keys;
  private final RateLimiter limiter;

  ApiKeyFilter(ApiKeyStore keys, RateLimiter limiter) {
    this.keys = keys;
    this.limiter = limiter;
  }

  @Override
  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                  FilterChain chain) throws ServletException, IOException {
    String header = request.getHeader("Authorization");
    if (header != null && header.startsWith(SCHEME)) {
      String presented = header.substring(SCHEME.length()).trim();
      String digest = sha256Hex(presented);

      // The lookup is by hash, so a database that leaks tells an attacker
      // nothing usable: they get the digests, and a 256-bit random key is
      // not coming back out of one.
      keys.findActiveByHash(digest)
          // Redundant on its face -- we found the row by this hash -- and
          // kept anyway, because it is the line that stays correct if the
          // lookup ever becomes a prefix scan or a cache. Constant time,
          // so no attacker learns anything from how long a miss took.
          .filter(stored -> MessageDigest.isEqual(
              stored.keyHash().getBytes(StandardCharsets.UTF_8),
              digest.getBytes(StandardCharsets.UTF_8)))
          .ifPresent(stored -> authenticate(new ApiKey(stored.ownerId(), stored.label())));
    }

    // No key, or a key we do not know: the context stays empty and the
    // authorization rules decide. This filter has no opinion about 401.
    var caller = SecurityContextHolder.getContext().getAuthentication();
    if (caller != null && caller.getPrincipal() instanceof ApiKey key
        && !limiter.tryAcquire(key.ownerId())) {
      tooManyRequests(response);
      return;
    }
    try {
      chain.doFilter(request, response);
    } finally {
      // A pooled thread outlives the request. Clearing is not optional.
      SecurityContextHolder.clearContext();
    }
  }

  private static void authenticate(ApiKey key) {
    var token = new UsernamePasswordAuthenticationToken(
        key, null, List.of(new SimpleGrantedAuthority("ROLE_API")));
    SecurityContextHolder.getContext().setAuthentication(token);
  }

  private void tooManyRequests(HttpServletResponse response) throws IOException {
    response.setStatus(429);
    response.setHeader("Retry-After", "60");   // seconds, and mean it
    response.setContentType(MediaType.APPLICATION_PROBLEM_JSON_VALUE);
    response.getWriter().write("""
        {"type":"https://study.jaspreet.info/problems/rate-limited",\
        "title":"Too many requests","status":429,\
        "detail":"the per-minute quota for this key is spent"}""");
  }

  private static String sha256Hex(String value) {
    try {
      var sha256 = MessageDigest.getInstance("SHA-256");
      return HexFormat.of().formatHex(sha256.digest(value.getBytes(StandardCharsets.UTF_8)));
    } catch (NoSuchAlgorithmException impossible) {
      throw new IllegalStateException("every JVM has SHA-256", impossible);
    }
  }
}

// src/main/java/info/jaspreet/shortlink/security/RateLimiter.java
package info.jaspreet.shortlink.security;

import info.jaspreet.shortlink.config.ShortlinkProperties;
import java.time.Duration;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.data.redis.core.script.DefaultRedisScript;
import org.springframework.data.redis.core.script.RedisScript;
import org.springframework.stereotype.Component;

/**
 * A fixed window counter in Redis. Not a HashMap: four replicas each with
 * their own map give a caller four times the quota, and a deploy resets
 * everyone's limit to zero -- which is exactly when you least want it.
 */
@Component
public class RateLimiter {

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

  // Two commands as one round trip and one atomic step. INCR then EXPIRE
  // as separate calls has a window where the process dies in between and
  // leaves a key with no TTL -- which bans that caller permanently.
  private static final RedisScript<Long> INCREMENT = new DefaultRedisScript<>("""
      local hits = redis.call('INCR', KEYS[1])
      if hits == 1 then
        redis.call('PEXPIRE', KEYS[1], ARGV[1])
      end
      return hits
      """, Long.class);

  private final StringRedisTemplate redis;
  private final int permitted;
  private final Duration window;

  RateLimiter(StringRedisTemplate redis, ShortlinkProperties properties) {
    this.redis = redis;
    this.permitted = properties.rateLimit().perMinute();
    this.window = properties.rateLimit().window();
  }

  public boolean tryAcquire(String ownerId) {
    // The key carries the window, so the old window's key expires on its
    // own and there is nothing to clean up.
    long bucket = System.currentTimeMillis() / window.toMillis();
    String key = "rl:" + ownerId + ":" + bucket;
    try {
      Long hits = redis.execute(INCREMENT, List.of(key), String.valueOf(window.toMillis()));
      return hits == null || hits <= permitted;
    } catch (RuntimeException redisIsDown) {
      // Fail open, and say so loudly. A limiter that fails closed turns a
      // Redis blip into a total outage, which is a worse day than a minute
      // of unlimited traffic. If the limit is protecting something that
      // cannot survive that -- a payment endpoint, a third-party quota --
      // then fail closed instead, on purpose, and write that down.
      log.warn("rate limiter unavailable, allowing request", redisIsDown);
      return true;
    }
  }
}

// A fixed window lets a caller spend 2x the quota across a boundary: sixty
// at 11:59:59 and sixty more at 12:00:00. For an API key that is fine and
// the simplicity is worth it. When it is not, the next step is a sliding
// window log or a token bucket -- both are the same INCR-in-Lua shape with
// more arithmetic, and both still live in Redis for the same reason.

// src/main/java/info/jaspreet/shortlink/web/RequestIdFilter.java
package info.jaspreet.shortlink.web;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.util.UUID;
import java.util.regex.Pattern;
import org.slf4j.MDC;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class RequestIdFilter extends OncePerRequestFilter {

  private static final String HEADER = "X-Request-Id";
  // An id from outside goes into every log line. Unvalidated, that is a
  // log injection: a newline in the header writes a fake log entry.
  private static final Pattern SAFE = Pattern.compile("[A-Za-z0-9._-]{1,64}");

  @Override
  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                  FilterChain chain) throws ServletException, IOException {
    String inbound = request.getHeader(HEADER);
    String requestId = inbound != null && SAFE.matcher(inbound).matches()
        ? inbound
        : UUID.randomUUID().toString();

    MDC.put("requestId", requestId);
    // Echo it, so support can paste the header from a customer's HAR file
    // straight into the log search.
    response.setHeader(HEADER, requestId);
    try {
      chain.doFilter(request, response);
    } finally {
      // Mandatory. MDC is a ThreadLocal, threads are reused, and an id left
      // behind attaches somebody else's request to this customer's trace.
      MDC.remove("requestId");
    }
  }
}

# application.yaml -- the observability half, and the one distinction
# in this file that people get wrong more often than any other.
management:
  endpoint:
    health:
      probes:
        enabled: true
      group:
        # Liveness answers: is this JVM broken beyond recovery? Only a
        # restart fixes that, and a restart is what a failed liveness probe
        # causes. So it checks nothing external. Put the database in here
        # and a thirty-second Postgres failover restarts every pod you own,
        # simultaneously, which turns a blip into an outage.
        liveness:
          include: livenessState
        # Readiness answers: should traffic come here right now? A pod with
        # no database cannot serve, but it will recover on its own, so the
        # right response is to stop routing to it -- not to kill it.
        readiness:
          include: readinessState,db,redis
  endpoints:
    web:
      exposure:
        include: health,prometheus
  metrics:
    tags:
      application: shortlink        # every metric, one tag, free grouping

{
  "@timestamp": "2026-08-31T14:32:07.418Z",
  "log.level": "WARN",
  "service.name": "shortlink",
  "process.thread.name": "VirtualThread[#742]/runnable",
  "log.logger": "info.jaspreet.shortlink.security.RateLimiter",
  "message": "rate limiter unavailable, allowing request",
  "requestId": "6f1c2a94-3d55-4c1e-9f0a-2b7e6d4a1c33",
  "trace.id": "0af7651916cd43dd8448eb211c80319c",
  "span.id": "b7ad6b7169203331"
}

That is one line of logging.structured.format.console: ecs from the configuration topic — Boot 3.4 and later emit JSON with no encoder XML and no logback-spring.xml at all. requestId is there because the filter put it in the MDC; trace.id and span.id are there because Micrometer Tracing is on the classpath and propagates W3C traceparent headers between services. The rule that makes this worth having: never build a log message with string concatenation. log.warn("link {} expired for owner {}", code, ownerId) keeps code and ownerId as fields you can filter on; log.warn("link " + code + " expired") produces a sentence you can only grep.

// src/test/java/info/jaspreet/shortlink/ArchitectureTest.java
package info.jaspreet.shortlink;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.Architectures.layeredArchitecture;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

/** The table from the layout topic, as a test. This is the whole point of it. */
@AnalyzeClasses(packages = "info.jaspreet.shortlink",
                importOptions = ImportOption.DoNotIncludeTests.class)
class ArchitectureTest {

  @ArchTest
  static final ArchRule layers = layeredArchitecture().consideringAllDependencies()
      .layer("web").definedBy("..web..")
      .layer("service").definedBy("..service..")
      .layer("persistence").definedBy("..persistence..")
      .layer("domain").definedBy("..domain..")
      .layer("config").definedBy("..config..")

      .whereLayer("web").mayNotBeAccessedByAnyLayer()
      .whereLayer("service").mayOnlyBeAccessedByLayers("web", "config")
      .whereLayer("persistence").mayOnlyBeAccessedByLayers("service", "config", "security");

  // The rule that pays for itself: the domain stays plain Java. Every one
  // of these packages arriving in ..domain.. is somebody solving a problem
  // in the wrong place, and it is much cheaper to say so at compile time
  // than in a code review six months from now.
  @ArchTest
  static final ArchRule domainIsPlainJava = noClasses()
      .that().resideInAPackage("..domain..")
      .should().dependOnClassesThat().resideInAnyPackage(
          "org.springframework..", "jakarta..", "org.hibernate..", "com.fasterxml..");

  @ArchTest
  static final ArchRule serviceKnowsNoFramework = noClasses()
      .that().resideInAPackage("..service..")
      .should().dependOnClassesThat().resideInAnyPackage(
          "org.springframework..", "jakarta.servlet..");

  // Entities do not leave the persistence package. If one ever appears in
  // a controller signature, the API's shape is now the schema's shape.
  @ArchTest
  static final ArchRule entitiesStayHome = noClasses()
      .that().resideOutsideOfPackage("..persistence..")
      .should().dependOnClassesThat().areAnnotatedWith(jakarta.persistence.Entity.class);
}

$ ./mvnw -q test -Dtest=ArchitectureTest
[ERROR] domainIsPlainJava
Architecture Violation [Priority: MEDIUM] - Rule 'no classes that reside in a
package '..domain..' should depend on classes that reside in any package
['org.springframework..', 'jakarta..', ...]' was violated (1 times):

  Class <info.jaspreet.shortlink.domain.Link> depends on
  <jakarta.persistence.Entity> in (Link.java:0)

# Somebody put @Entity on the domain record because it was convenient.
# It took four seconds to find out, and the fix is still cheap.

// src/test/java/info/jaspreet/shortlink/IntegrationTest.java
package info.jaspreet.shortlink;

import org.junit.jupiter.api.BeforeEach;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.jdbc.core.simple.JdbcClient;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.PostgreSQLContainer;

/**
 * The containers are static and started in a static initialiser rather than
 * with @Container, on purpose: @Container ties a container's life to one
 * test class, so eight test classes start and stop Postgres eight times and
 * your suite takes four minutes instead of forty seconds. Started this way
 * they live for the JVM and Testcontainers' reaper stops them at the end.
 *
 * Every subclass shares this exact configuration, which also means Spring
 * caches one application context for the whole suite. Both halves matter:
 * an @MockitoBean in one test class would fork the cache and start a second
 * context, and that is usually where a slow suite's time actually went.
 */
@SpringBootTest
@AutoConfigureMockMvc
abstract class IntegrationTest {

  @ServiceConnection
  static final PostgreSQLContainer<?> POSTGRES =
      new PostgreSQLContainer<>("postgres:16-alpine");

  @ServiceConnection(name = "redis")
  static final GenericContainer<?> REDIS =
      new GenericContainer<>("redis:7-alpine").withExposedPorts(6379);

  static {
    POSTGRES.start();
    REDIS.start();
  }

  // Not @Transactional. A transactional test rolls back at the end, which
  // is fast and convenient and would quietly break the most important test
  // in this file: LinkWriter uses REQUIRES_NEW, so its insert commits in a
  // transaction the test does not own and cannot roll back. Truncating is
  // honest, and it tests the code that actually runs in production.
  @BeforeEach
  void emptyTheTables(@Autowired JdbcClient jdbc) {
    jdbc.sql("truncate table links, api_keys restart identity cascade").update();
  }
}

// Flyway runs against the container on context start, so the schema under
// test is the schema the migration produces -- not one Hibernate invented
// from the entities, which is the version of this that passes while
// production fails.

// src/test/java/info/jaspreet/shortlink/web/LinkApiTest.java
package info.jaspreet.shortlink.web;

import static org.assertj.core.api.Assertions.assertThat;

import info.jaspreet.shortlink.IntegrationTest;
import info.jaspreet.shortlink.domain.TargetUrl;
import info.jaspreet.shortlink.service.LinkService;
import info.jaspreet.shortlink.service.LinkService.NewLink;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.stream.IntStream;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.test.web.servlet.assertj.MockMvcTester;

class LinkApiTest extends IntegrationTest {

  // The plaintext key never exists in production; here it is a constant so
  // the test can send it and store only its digest, exactly as the real
  // key-issuing path does.
  private static final String KEY = "sl_live_thisisatestkeyonly";

  @Autowired MockMvcTester mvc;
  @Autowired JdbcClient jdbc;
  @Autowired LinkService links;

  @BeforeEach
  void issueAKey() throws Exception {
    // Hashed here exactly as the filter hashes it, so the test exercises
    // the real comparison rather than a fixture that agrees with itself.
    String digest = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256")
        .digest(KEY.getBytes(StandardCharsets.UTF_8)));
    jdbc.sql("insert into api_keys (owner_id, label, key_hash) values (?, ?, ?)")
        .params("owner-1", "test", digest)
        .update();
  }

  @Test
  void creates_a_link_and_answers_with_its_public_url() {
    assertThat(mvc.post().uri("/v1/links")
        .header("Authorization", "Bearer " + KEY)
        .contentType(MediaType.APPLICATION_JSON)
        .content("""
            {"url": "https://example.com/a/very/long/path?utm_source=x"}"""))
        .hasStatus(HttpStatus.CREATED)
        .bodyJson().extractingPath("$.shortUrl").asString()
        .startsWith("http://localhost:8080/");
  }

  @Test
  void refuses_a_scheme_that_is_not_http() {
    assertThat(mvc.post().uri("/v1/links")
        .header("Authorization", "Bearer " + KEY)
        .contentType(MediaType.APPLICATION_JSON)
        .content("""
            {"url": "javascript:alert(1)"}"""))
        .hasStatus(HttpStatus.BAD_REQUEST);
  }

  @Test
  void refuses_a_request_with_no_key_and_says_how_to_fix_it() {
    assertThat(mvc.get().uri("/v1/links"))
        .hasStatus(HttpStatus.UNAUTHORIZED)
        .headers().containsKey("WWW-Authenticate");
  }

  // The one a mocked repository cannot express. Sixteen threads released
  // at the same instant with one idempotency key between them; the answer
  // has to be one link, and it has to be the same link for all sixteen.
  @Test
  void the_same_idempotency_key_creates_exactly_one_link() throws Exception {
    var request = new NewLink("owner-1", TargetUrl.parse("https://example.com"),
                              null, null, "key-42");
    var releaseThemAll = new CountDownLatch(1);

    List<Future<String>> attempts;
    try (var pool = Executors.newVirtualThreadPerTaskExecutor()) {
      attempts = IntStream.range(0, 16)
          .mapToObj(i -> pool.submit(() -> {
            releaseThemAll.await();
            return links.shorten(request).code().value();
          }))
          .toList();
      releaseThemAll.countDown();
    }

    assertThat(attempts.stream().map(LinkApiTest::get).distinct().toList())
        .as("every caller got the same code")
        .hasSize(1);
    assertThat(jdbc.sql("select count(*) from links").query(Integer.class).single())
        .as("and the database has one row, not sixteen")
        .isEqualTo(1);
  }

  private static String get(Future<String> future) {
    try {
      return future.get();
    } catch (Exception e) {
      throw new AssertionError("a caller failed instead of sharing the link", e);
    }
  }
}