Keyset Pagination

import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.Base64;
import java.util.List;

import org.springframework.http.HttpStatus;
import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;

record ArticleSummary(long id, String title, Instant publishedAt) {}

record ArticlePage(List<ArticleSummary> items, String nextCursor) {}

record Cursor(Instant publishedAt, long id) {

    // Full ISO-8601 precision: truncating to milliseconds would skip rows whose
    // microsecond timestamps fall between the truncated value and the real one.
    String encode() {
        String raw = id + ":" + publishedAt;
        return Base64.getUrlEncoder().withoutPadding().encodeToString(raw.getBytes(StandardCharsets.UTF_8));
    }

    static Cursor decode(String value) {
        try {
            String raw = new String(Base64.getUrlDecoder().decode(value), StandardCharsets.UTF_8);
            String[] parts = raw.split(":", 2);
            return new Cursor(Instant.parse(parts[1]), Long.parseLong(parts[0]));
        } catch (RuntimeException e) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Invalid cursor");
        }
    }
}

@RestController
public class ArticleFeedController {

    private final JdbcClient jdbc;

    ArticleFeedController(JdbcClient jdbc) {
        this.jdbc = jdbc;
    }

    @GetMapping("/api/articles")
    ArticlePage list(@RequestParam(required = false) String cursor,
                     @RequestParam(defaultValue = "20") int size) {
        int limit = Math.clamp(size, 1, 100);
        Cursor after = cursor == null ? new Cursor(Instant.parse("9999-12-31T00:00:00Z"), Long.MAX_VALUE)
                                      : Cursor.decode(cursor);

        List<ArticleSummary> rows = jdbc.sql("""
                SELECT id, title, published_at
                FROM article
                WHERE (published_at, id) < (:publishedAt, :id)
                ORDER BY published_at DESC, id DESC
                LIMIT :limit""")
                // The PostgreSQL driver cannot bind Instant; OffsetDateTime maps to timestamptz.
                .param("publishedAt", after.publishedAt().atOffset(ZoneOffset.UTC))
                .param("id", after.id())
                .param("limit", limit + 1)
                .query(ArticleSummary.class)
                .list();

        if (rows.size() <= limit) {
            return new ArticlePage(rows, null);
        }
        List<ArticleSummary> page = rows.subList(0, limit);
        ArticleSummary last = page.getLast();
        return new ArticlePage(page, new Cursor(last.publishedAt(), last.id()).encode());
    }
}