b. Cache-Aside

package boxoffice.catalog;

import io.micrometer.core.instrument.MeterRegistry;
import java.time.Duration;
import java.util.UUID;
import java.util.concurrent.ThreadLocalRandom;
import java.util.function.Supplier;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.dao.DataAccessException;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Component;
import tools.jackson.databind.json.JsonMapper;

/**
 * Cache-aside in Redis. The application asks the cache first; on a miss it loads from
 * the database and writes the JSON into the cache with a TTL. Values are stored as the
 * exact JSON returned to clients, so a hit costs no database access and no serialization.
 */
@Component
public class EventCache {

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

    /** The JSON body and what happened: HIT, MISS or BYPASS (cache disabled). */
    public record Result(String json, String outcome) { }

    private final StringRedisTemplate redis;
    private final JsonMapper mapper;            // Jackson 3 (Spring Boot 4)
    private final MeterRegistry metrics;
    private final boolean enabled;
    private final boolean stampedeProtection;
    private final Duration eventTtl;
    private final Duration listTtl;

    public EventCache(StringRedisTemplate redis, JsonMapper mapper, MeterRegistry metrics,
                      @Value("${catalog.cache.enabled}") boolean enabled,
                      @Value("${catalog.cache.stampede-protection}") boolean stampedeProtection,
                      @Value("${catalog.cache.event-ttl}") Duration eventTtl,
                      @Value("${catalog.cache.list-ttl}") Duration listTtl) {
        this.redis = redis;
        this.mapper = mapper;
        this.metrics = metrics;
        this.enabled = enabled;
        this.stampedeProtection = stampedeProtection;
        this.eventTtl = eventTtl;
        this.listTtl = listTtl;
    }

    public Duration eventTtl() { return eventTtl; }
    public Duration listTtl() { return listTtl; }

    public Result get(String key, Duration ttl, Supplier<?> loader) {
        if (!enabled) {
            return count(new Result(toJson(loader.get()), "BYPASS"));
        }
        var cached = read(key);
        if (cached != null) {
            return count(new Result(cached, "HIT"));
        }
        if (stampedeProtection) {
            var lockKey = key + ":lock";
            var token = UUID.randomUUID().toString();
            if (tryLock(lockKey, token)) {
                try {
                    cached = read(key);               // someone may have filled it meanwhile
                    if (cached != null) {
                        return count(new Result(cached, "HIT"));
                    }
                    return count(load(key, ttl, loader));
                } finally {
                    unlock(lockKey, token);
                }
            }
            // another request is already loading this key: wait for it instead of
            // sending one more identical query to the database
            for (int i = 0; i < 20; i++) {
                sleep(Duration.ofMillis(25));
                cached = read(key);
                if (cached != null) {
                    return count(new Result(cached, "HIT"));
                }
            }
        }
        return count(load(key, ttl, loader));
    }

    public void evict(String key) {
        try {
            redis.delete(key);
        } catch (DataAccessException e) {
            log.warn("cache evict failed for {}: {}", key, e.getMessage());
        }
    }

    // ---- internals --------------------------------------------------------

    private Result load(String key, Duration ttl, Supplier<?> loader) {
        var json = toJson(loader.get());
        try {
            redis.opsForValue().set(key, json, withJitter(ttl));
        } catch (DataAccessException e) {
            log.warn("cache write failed for {}: {}", key, e.getMessage());
        }
        return new Result(json, "MISS");
    }

    private String read(String key) {
        try {
            return redis.opsForValue().get(key);
        } catch (DataAccessException e) {
            // Redis down or slow: the cache is an optimization, not a dependency
            log.warn("cache read failed for {}: {}", key, e.getMessage());
            return null;
        }
    }

    private boolean tryLock(String lockKey, String token) {
        try {
            // SET lockKey token NX PX 2000: only one request in the whole cluster gets it
            return Boolean.TRUE.equals(redis.opsForValue().setIfAbsent(lockKey, token, Duration.ofSeconds(2)));
        } catch (DataAccessException e) {
            return true;                              // no Redis, no lock: just load
        }
    }

    private void unlock(String lockKey, String token) {
        try {
            // delete only our own lock (it may have expired and been taken by someone else);
            // get + delete is not atomic: production code uses a Lua script for this
            if (token.equals(redis.opsForValue().get(lockKey))) {
                redis.delete(lockKey);
            }
        } catch (DataAccessException e) {
            log.debug("unlock failed: {}", e.getMessage());
        }
    }

    /** TTL plus up to 10% random extra, so that keys written together do not expire together. */
    private static Duration withJitter(Duration ttl) {
        long extra = (long) (ttl.toMillis() * 0.10 * ThreadLocalRandom.current().nextDouble());
        return ttl.plusMillis(extra);
    }

    private Result count(Result result) {
        metrics.counter("catalog.cache.requests", "result", result.outcome()).increment();
        return result;
    }

    private String toJson(Object value) {
        return mapper.writeValueAsString(value);    // Jackson 3 exceptions are unchecked
    }

    private static void sleep(Duration d) {
        try {
            Thread.sleep(d);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
    }
}

package boxoffice.catalog;

import jakarta.validation.Valid;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import java.net.URI;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
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.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/catalog/events")
public class EventController {

    private final CatalogService service;
    private final EventCache cache;

    public EventController(CatalogService service, EventCache cache) {
        this.service = service;
        this.cache = cache;
    }

    @GetMapping
    public ResponseEntity<String> list(
            @RequestParam(required = false) String city,
            @RequestParam(defaultValue = "0") @Min(0) int page,
            @RequestParam(defaultValue = "20") @Min(1) @Max(50) int size) {
        var key = "catalog:events:city=" + (city == null ? "" : city) + ":page=" + page + ":size=" + size;
        return json(cache.get(key, cache.listTtl(), () -> service.upcomingEvents(city, page, size)));
    }

    @GetMapping("/{id}")
    public ResponseEntity<String> get(@PathVariable Long id) {
        return json(cache.get(eventKey(id), cache.eventTtl(), () -> service.findEvent(id)));
    }

    @PostMapping
    public ResponseEntity<EventOut> create(@Valid @RequestBody EventIn in) {
        var out = service.createEvent(in);
        return ResponseEntity.created(URI.create("/catalog/events/" + out.id())).body(out);
    }

    @PutMapping("/{id}")
    public EventOut update(@PathVariable Long id, @Valid @RequestBody EventIn in) {
        var out = service.updateEvent(id, in);
        cache.evict(eventKey(id));       // the next read loads the new version
        return out;
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable Long id) {
        service.deleteEvent(id);
        cache.evict(eventKey(id));
    }

    private static String eventKey(Long id) {
        return "catalog:event:" + id;
    }

    private static ResponseEntity<String> json(EventCache.Result result) {
        return ResponseEntity.ok()
                .contentType(MediaType.APPLICATION_JSON)
                .header("X-Cache", result.outcome())
                .body(result.json());
    }
}