HTTP 메서드 속성

package board.http;

import static org.junit.jupiter.api.Assertions.assertAll;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.time.Duration;
import java.time.Instant;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Map;
import java.util.Optional;
import org.junit.jupiter.api.Test;

final class HttpMethodPolicyTest {
    private static final Duration BASE_BACKOFF =
            Duration.ofMillis(200);

    private static final Map<String, MethodTraits> METHODS =
            Map.ofEntries(
                    Map.entry("GET", traits(true, true,
                            CacheRule.ELIGIBLE)),
                    Map.entry("HEAD", traits(true, true,
                            CacheRule.ELIGIBLE)),
                    Map.entry("OPTIONS", traits(true, true,
                            CacheRule.NOT_CACHEABLE)),
                    Map.entry("TRACE", traits(true, true,
                            CacheRule.NOT_CACHEABLE)),
                    Map.entry("PUT", traits(false, true,
                            CacheRule.NOT_CACHEABLE)),
                    Map.entry("DELETE", traits(false, true,
                            CacheRule.NOT_CACHEABLE)),
                    Map.entry("POST", traits(false, false,
                            CacheRule.EXPLICIT_FRESHNESS_AND_CONTENT_LOCATION)),
                    Map.entry("PATCH", traits(false, false,
                            CacheRule.EXPLICIT_FRESHNESS_AND_CONTENT_LOCATION)),
                    Map.entry("CONNECT", traits(false, false,
                            CacheRule.NOT_CACHEABLE)));

    @Test
    void method_matrix_matches_the_registered_contracts() {
        assertAll(
                () -> assertEquals(
                        traits(true, true, CacheRule.ELIGIBLE),
                        METHODS.get("GET")),
                () -> assertEquals(
                        traits(true, true, CacheRule.ELIGIBLE),
                        METHODS.get("HEAD")),
                () -> assertEquals(
                        traits(true, true, CacheRule.NOT_CACHEABLE),
                        METHODS.get("OPTIONS")),
                () -> assertEquals(
                        traits(true, true, CacheRule.NOT_CACHEABLE),
                        METHODS.get("TRACE")),
                () -> assertEquals(
                        traits(false, true, CacheRule.NOT_CACHEABLE),
                        METHODS.get("PUT")),
                () -> assertEquals(
                        traits(false, true, CacheRule.NOT_CACHEABLE),
                        METHODS.get("DELETE")),
                () -> assertEquals(
                        traits(false, false,
                                CacheRule.EXPLICIT_FRESHNESS_AND_CONTENT_LOCATION),
                        METHODS.get("POST")),
                () -> assertEquals(
                        traits(false, false,
                                CacheRule.EXPLICIT_FRESHNESS_AND_CONTENT_LOCATION),
                        METHODS.get("PATCH")),
                () -> assertEquals(
                        traits(false, false,
                                CacheRule.NOT_CACHEABLE),
                        METHODS.get("CONNECT")));
    }

    @Test
    void a_no_response_get_gets_only_one_bounded_retry() {
        var now = Instant.parse("2026-08-26T00:00:00Z");
        var first = decide(context(
                "GET", false, null, 0, now,
                now.plusSeconds(5), null,
                Duration.ofMillis(50)));
        var second = decide(context(
                "GET", false, null, 1, now,
                now.plusSeconds(5), null,
                Duration.ofMillis(50)));

        assertAll(
                () -> assertTrue(first.retry()),
                () -> assertEquals(
                        Duration.ofMillis(250), first.delay()),
                () -> assertFalse(second.retry()));
    }

    @Test
    void a_non_idempotent_method_needs_an_explicit_retry_basis() {
        var now = Instant.parse("2026-08-26T00:00:00Z");

        var ordinaryPost = decide(context(
                "POST", false, null, 0, now,
                now.plusSeconds(5), null, Duration.ZERO));
        var profiledPost = decide(context(
                "POST", true, null, 0, now,
                now.plusSeconds(5), null, Duration.ZERO));
        var knownNotAppliedPost = decide(context(
                "POST", false, true, null, 0, now,
                now.plusSeconds(5), null, Duration.ZERO));

        assertAll(
                () -> assertFalse(ordinaryPost.retry()),
                () -> assertTrue(profiledPost.retry()),
                () -> assertTrue(knownNotAppliedPost.retry()));
    }

    @Test
    void the_same_400_401_or_403_request_stops() {
        var now = Instant.parse("2026-08-26T00:00:00Z");

        for (int status : new int[] {400, 401, 403}) {
            var decision = decide(context(
                    "GET", false, status, 0, now,
                    now.plusSeconds(5), null, Duration.ZERO));
            assertFalse(decision.retry(), "status=" + status);
        }
    }

    @Test
    void retry_after_backoff_and_jitter_stay_inside_the_deadline() {
        var now = Instant.parse("2026-01-01T00:00:00Z");
        var retry429 = decide(context(
                "GET", false, 429, 0, now,
                now.plusSeconds(10), "3",
                Duration.ofMillis(100)));
        var retry503 = decide(context(
                "PUT", false, 503, 0, now,
                now.plusSeconds(10),
                "Thu, 1 Jan 2026 00:00:04 GMT",
                Duration.ofMillis(100)));
        var pastDeadline = decide(context(
                "GET", false, 503, 0, now,
                now.plusSeconds(3), "3",
                Duration.ofMillis(100)));

        assertAll(
                () -> assertTrue(retry429.retry()),
                () -> assertEquals(
                        Duration.ofMillis(3100),
                        retry429.delay()),
                () -> assertTrue(retry503.retry()),
                () -> assertEquals(
                        Duration.ofMillis(4100),
                        retry503.delay()),
                () -> assertFalse(pastDeadline.retry()));
    }

    private static RetryDecision decide(RetryContext context) {
        var traits = METHODS.get(context.method());
        if (traits == null) {
            return RetryDecision.stop("unknown method");
        }
        if (context.automaticRetries() >= 1) {
            return RetryDecision.stop("automatic retry exhausted");
        }
        if (context.status() != null
                && (context.status() == 400
                || context.status() == 401
                || context.status() == 403)) {
            return RetryDecision.stop("same request needs correction");
        }
        if (!traits.idempotent()
                && !context.applicationOperationIdempotent()
                && !context.knownNotApplied()) {
            return RetryDecision.stop("unsafe to repeat");
        }
        if (context.status() != null
                && context.status() != 429
                && context.status() != 503) {
            return RetryDecision.stop("status is not retryable");
        }
        if (context.jitter().isNegative()) {
            return RetryDecision.stop("negative jitter");
        }

        var delay = parseRetryAfter(
                context.retryAfter(), context.now())
                .orElse(BASE_BACKOFF)
                .plus(context.jitter());
        if (!context.now().plus(delay)
                .isBefore(context.deadline())) {
            return RetryDecision.stop("overall deadline");
        }
        return new RetryDecision(true, delay, "bounded retry");
    }

    private static Optional<Duration> parseRetryAfter(
            String value, Instant now) {
        if (value == null || value.isBlank()) {
            return Optional.empty();
        }
        try {
            long seconds = Long.parseLong(value);
            return seconds < 0
                    ? Optional.empty()
                    : Optional.of(Duration.ofSeconds(seconds));
        } catch (NumberFormatException ignored) {
            try {
                var retryAt = ZonedDateTime.parse(
                        value,
                        DateTimeFormatter.RFC_1123_DATE_TIME)
                        .toInstant();
                var delay = Duration.between(now, retryAt);
                return Optional.of(
                        delay.isNegative() ? Duration.ZERO : delay);
            } catch (RuntimeException invalidHttpDate) {
                return Optional.empty();
            }
        }
    }

    private static RetryContext context(
            String method,
            boolean applicationOperationIdempotent,
            Integer status,
            int automaticRetries,
            Instant now,
            Instant deadline,
            String retryAfter,
            Duration jitter) {
        return new RetryContext(
                method,
                applicationOperationIdempotent,
                false,
                status,
                automaticRetries,
                now,
                deadline,
                retryAfter,
                jitter);
    }

    private static RetryContext context(
            String method,
            boolean applicationOperationIdempotent,
            boolean knownNotApplied,
            Integer status,
            int automaticRetries,
            Instant now,
            Instant deadline,
            String retryAfter,
            Duration jitter) {
        return new RetryContext(
                method,
                applicationOperationIdempotent,
                knownNotApplied,
                status,
                automaticRetries,
                now,
                deadline,
                retryAfter,
                jitter);
    }

    private static MethodTraits traits(
            boolean safe,
            boolean idempotent,
            CacheRule cacheRule) {
        return new MethodTraits(safe, idempotent, cacheRule);
    }

    private enum CacheRule {
        ELIGIBLE,
        EXPLICIT_FRESHNESS_AND_CONTENT_LOCATION,
        NOT_CACHEABLE
    }

    private record MethodTraits(
            boolean safe,
            boolean idempotent,
            CacheRule cacheRule) {
    }

    private record RetryContext(
            String method,
            boolean applicationOperationIdempotent,
            boolean knownNotApplied,
            Integer status,
            int automaticRetries,
            Instant now,
            Instant deadline,
            String retryAfter,
            Duration jitter) {
    }

    private record RetryDecision(
            boolean retry,
            Duration delay,
            String reason) {
        private static RetryDecision stop(String reason) {
            return new RetryDecision(false, Duration.ZERO, reason);
        }
    }
}

package board.web;

import static java.nio.charset.StandardCharsets.UTF_8;
import static java.util.concurrent.TimeUnit.SECONDS;
import static org.junit.jupiter.api.Assertions.assertAll;
import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.nio.ByteBuffer;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.ZoneId;
import java.time.ZoneOffset;
import java.util.HexFormat;
import java.util.Objects;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.Executors;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;
import java.util.regex.Pattern;
import org.junit.jupiter.api.Test;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.http.converter.json.ProblemDetailJacksonMixin;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;
import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.bind.MissingRequestHeaderException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestAttribute;
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.RestController;
import org.springframework.web.bind.annotation.RestControllerAdvice;

final class IdempotentRegistrationTest {
    private static final ObjectMapper OBJECT_MAPPER =
            new ObjectMapper().addMixIn(
                    ProblemDetail.class,
                    ProblemDetailJacksonMixin.class);
    private static final String VERIFIED_MEMBER_ID =
            "verifiedMemberId";
    private static final String IDEMPOTENCY_HEADER =
            "Idempotency-Key";
    private static final String OPERATION =
            "POST /api/posts";
    private static final String KEY =
            "\"register-7-001\"";
    private static final String REQUEST_JSON =
            """
            {"title":"HTTP method","content":"safe retry"}
            """;
    private static final String RESPONSE_JSON =
            "{\"id\":1,\"title\":\"HTTP method\","
                    + "\"content\":\"safe retry\"}";
    private static final Instant START =
            Instant.parse("2026-08-26T00:00:00Z");
    private static final Duration RETENTION =
            Duration.ofHours(24);

    @Test
    void first_request_is_created_and_completed_retry_is_replayed()
            throws Exception {
        var service = newService();
        var mvc = mvc(service);

        var first = mvc.perform(
                        postJson(7L, KEY, REQUEST_JSON))
                .andReturn();
        var replay = mvc.perform(
                        postJson(7L, KEY, REQUEST_JSON))
                .andReturn();

        assertAll(
                () -> assertEquals(
                        201, first.getResponse().getStatus()),
                () -> assertEquals(
                        "/api/posts/1",
                        first.getResponse().getHeader(
                                HttpHeaders.LOCATION)),
                () -> assertCompatible(
                        APPLICATION_JSON,
                        first.getResponse().getContentType()),
                () -> assertEquals(
                        RESPONSE_JSON,
                        new String(
                                first.getResponse()
                                        .getContentAsByteArray(),
                                UTF_8)),
                () -> assertEquals(1, service.registrationCount()),
                () -> assertEquals(
                        first.getResponse().getStatus(),
                        replay.getResponse().getStatus()),
                () -> assertEquals(
                        first.getResponse().getHeader("Location"),
                        replay.getResponse().getHeader("Location")),
                () -> assertArrayEquals(
                        first.getResponse().getContentAsByteArray(),
                        replay.getResponse().getContentAsByteArray()));
    }

    @Test
    void the_same_key_with_a_different_payload_is_422()
            throws Exception {
        var service = newService();
        var mvc = mvc(service);

        var first = mvc.perform(
                        postJson(7L, KEY, REQUEST_JSON))
                .andReturn();
        var mismatch = mvc.perform(postJson(
                        7L,
                        KEY,
                        """
                        {"title":"Spring MVC","content":"different"}
                        """))
                .andReturn();

        assertAll(
                () -> assertEquals(
                        201, first.getResponse().getStatus()),
                () -> assertEquals(
                        422, mismatch.getResponse().getStatus()),
                () -> assertCompatible(
                        MediaType.APPLICATION_PROBLEM_JSON,
                        mismatch.getResponse().getContentType()),
                () -> assertEquals(
                        "IDEMPOTENCY_PAYLOAD_MISMATCH",
                        readBody(mismatch).path("code").textValue()),
                () -> assertEquals(1, service.registrationCount()));
    }

    @Test
    void a_retry_while_the_first_request_is_pending_is_409()
            throws Exception {
        var entered = new CountDownLatch(1);
        var release = new CountDownLatch(1);
        Runnable blockFirstCreation = () -> {
            entered.countDown();
            await(release);
        };
        var service = new IdempotentRegistrationService(
                Clock.fixed(START, ZoneOffset.UTC),
                RETENTION,
                blockFirstCreation);
        var mvc = mvc(service);
        var executor = Executors.newFixedThreadPool(2);

        try {
            var first = executor.submit(() -> service.register(
                    7L,
                    KEY,
                    new CreatePostRequest(
                            "HTTP method", "safe retry")));
            assertTrue(entered.await(5, SECONDS));

            var pending = mvc.perform(
                            postJson(7L, KEY, REQUEST_JSON))
                    .andReturn();
            assertAll(
                    () -> assertEquals(
                            409, pending.getResponse().getStatus()),
                    () -> assertEquals(
                            "IDEMPOTENCY_REQUEST_PENDING",
                            readBody(pending)
                                    .path("code").textValue()));

            release.countDown();
            var completed = first.get(5, SECONDS);
            assertAll(
                    () -> assertFalse(completed.replayed()),
                    () -> assertEquals(
                            1L, completed.snapshot().body().id()),
                    () -> assertEquals(
                            1, service.registrationCount()));

            var replay = mvc.perform(
                            postJson(7L, KEY, REQUEST_JSON))
                    .andReturn();
            assertAll(
                    () -> assertEquals(
                            201, replay.getResponse().getStatus()),
                    () -> assertEquals(
                            RESPONSE_JSON,
                            new String(
                                    replay.getResponse()
                                            .getContentAsByteArray(),
                                    UTF_8)));
        } finally {
            release.countDown();
            executor.shutdownNow();
        }
    }

    @Test
    void a_missing_key_is_400_without_creation() throws Exception {
        var service = newService();
        var mvc = mvc(service);

        var missing = mvc.perform(post("/api/posts")
                        .requestAttr(VERIFIED_MEMBER_ID, 7L)
                        .contentType(APPLICATION_JSON)
                        .accept(APPLICATION_JSON)
                        .content(REQUEST_JSON))
                .andReturn();

        assertAll(
                () -> assertEquals(
                        400, missing.getResponse().getStatus()),
                () -> assertEquals(
                        "IDEMPOTENCY_KEY_REQUIRED",
                        readBody(missing).path("code").textValue()),
                () -> assertEquals(0, service.registrationCount()));
    }

    @Test
    void an_invalid_unquoted_key_is_400_without_creation()
            throws Exception {
        var service = newService();
        var mvc = mvc(service);

        var invalid = mvc.perform(postJson(
                        7L, "register-7-001", REQUEST_JSON))
                .andReturn();

        assertAll(
                () -> assertEquals(
                        400, invalid.getResponse().getStatus()),
                () -> assertEquals(
                        "IDEMPOTENCY_KEY_INVALID",
                        readBody(invalid).path("code").textValue()),
                () -> assertEquals(0, service.registrationCount()));
    }

    @Test
    void the_key_scope_uses_the_verified_member() throws Exception {
        var service = newService();
        var mvc = mvc(service);

        var member7 = mvc.perform(
                        postJson(7L, KEY, REQUEST_JSON))
                .andReturn();
        var member8 = mvc.perform(
                        postJson(8L, KEY, REQUEST_JSON))
                .andReturn();

        assertAll(
                () -> assertEquals(
                        201, member7.getResponse().getStatus()),
                () -> assertEquals(
                        "/api/posts/1",
                        member7.getResponse().getHeader(
                                HttpHeaders.LOCATION)),
                () -> assertEquals(
                        201, member8.getResponse().getStatus()),
                () -> assertEquals(
                        "/api/posts/2",
                        member8.getResponse().getHeader(
                                HttpHeaders.LOCATION)),
                () -> assertEquals(2, service.registrationCount()));
    }

    @Test
    void an_expired_completed_record_no_longer_guarantees_replay() {
        var clock = new MutableClock(START, ZoneOffset.UTC);
        var service = new IdempotentRegistrationService(
                clock, RETENTION, () -> { });
        var request = new CreatePostRequest(
                "HTTP method", "safe retry");

        var first = service.register(7L, KEY, request);
        clock.advance(RETENTION);
        var afterExpiry = service.register(7L, KEY, request);

        assertAll(
                () -> assertNotEquals(
                        first.snapshot().body().id(),
                        afterExpiry.snapshot().body().id()),
                () -> assertEquals(2, service.registrationCount()));
    }

    private static IdempotentRegistrationService newService() {
        return new IdempotentRegistrationService(
                Clock.fixed(START, ZoneOffset.UTC),
                RETENTION,
                () -> { });
    }

    private static MockMvc mvc(
            IdempotentRegistrationService service) {
        return MockMvcBuilders
                .standaloneSetup(new RegistrationController(service))
                .setControllerAdvice(new RegistrationAdvice())
                .setMessageConverters(
                        new MappingJackson2HttpMessageConverter(
                                OBJECT_MAPPER))
                .build();
    }

    private static JsonNode readBody(MvcResult result)
            throws Exception {
        return OBJECT_MAPPER.readTree(
                result.getResponse().getContentAsByteArray());
    }

    private static void assertCompatible(
            MediaType expected, String actual) {
        assertTrue(actual != null);
        assertTrue(expected.isCompatibleWith(
                MediaType.parseMediaType(actual)));
    }

    private static MockHttpServletRequestBuilder postJson(
            long memberId, String key, String json) {
        return post("/api/posts")
                .requestAttr(VERIFIED_MEMBER_ID, memberId)
                .header(IDEMPOTENCY_HEADER, key)
                .contentType(APPLICATION_JSON)
                .accept(APPLICATION_JSON)
                .content(json);
    }

    private static void await(CountDownLatch latch) {
        try {
            if (!latch.await(5, SECONDS)) {
                throw new IllegalStateException("latch timeout");
            }
        } catch (InterruptedException exception) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException(
                    "interrupted while waiting", exception);
        }
    }

    @RestController
    @RequestMapping("/api/posts")
    public static final class RegistrationController {
        private final IdempotentRegistrationService service;

        public RegistrationController(
                IdempotentRegistrationService service) {
            this.service = service;
        }

        @PostMapping(
                consumes = MediaType.APPLICATION_JSON_VALUE,
                produces = MediaType.APPLICATION_JSON_VALUE)
        public ResponseEntity<PostResponse> register(
                @RequestAttribute(VERIFIED_MEMBER_ID)
                long memberId,
                @RequestHeader(IDEMPOTENCY_HEADER)
                String rawKey,
                @RequestBody CreatePostRequest request) {
            var snapshot = service
                    .register(memberId, rawKey, request)
                    .snapshot();
            return ResponseEntity
                    .status(snapshot.status())
                    .location(URI.create(snapshot.location()))
                    .body(snapshot.body());
        }
    }

    @RestControllerAdvice
    public static final class RegistrationAdvice {
        @ExceptionHandler(MissingRequestHeaderException.class)
        public ResponseEntity<ProblemDetail> missingKey(
                MissingRequestHeaderException exception) {
            return problem(
                    HttpStatus.BAD_REQUEST,
                    "Idempotency key is required",
                    "Send a documented Idempotency-Key value.",
                    "IDEMPOTENCY_KEY_REQUIRED");
        }

        @ExceptionHandler(InvalidIdempotencyKeyException.class)
        public ResponseEntity<ProblemDetail> invalidKey(
                InvalidIdempotencyKeyException exception) {
            return problem(
                    HttpStatus.BAD_REQUEST,
                    "Idempotency key is invalid",
                    exception.getMessage(),
                    "IDEMPOTENCY_KEY_INVALID");
        }

        @ExceptionHandler(PayloadMismatchException.class)
        public ResponseEntity<ProblemDetail> payloadMismatch(
                PayloadMismatchException exception) {
            return problem(
                    HttpStatus.UNPROCESSABLE_ENTITY,
                    "Idempotency key was reused",
                    exception.getMessage(),
                    "IDEMPOTENCY_PAYLOAD_MISMATCH");
        }

        @ExceptionHandler(RequestPendingException.class)
        public ResponseEntity<ProblemDetail> requestPending(
                RequestPendingException exception) {
            return problem(
                    HttpStatus.CONFLICT,
                    "The first request is still pending",
                    exception.getMessage(),
                    "IDEMPOTENCY_REQUEST_PENDING");
        }

        private static ResponseEntity<ProblemDetail> problem(
                HttpStatus status,
                String title,
                String detail,
                String code) {
            var problem = ProblemDetail.forStatusAndDetail(
                    status, detail);
            problem.setType(URI.create(
                    "https://api.example.test/problems/idempotency"));
            problem.setTitle(title);
            problem.setProperty("code", code);
            return ResponseEntity
                    .status(status)
                    .contentType(MediaType.APPLICATION_PROBLEM_JSON)
                    .body(problem);
        }
    }

    public static final class IdempotentRegistrationService {
        private static final Pattern KEY_CONTENT =
                Pattern.compile("[A-Za-z0-9._:-]{1,64}");

        private final Clock clock;
        private final Duration retention;
        private final Runnable beforeCreate;
        private final ConcurrentHashMap<Scope, Entry> entries =
                new ConcurrentHashMap<>();
        private final AtomicLong sequence = new AtomicLong();
        private final AtomicInteger creations = new AtomicInteger();

        public IdempotentRegistrationService(
                Clock clock,
                Duration retention,
                Runnable beforeCreate) {
            this.clock = Objects.requireNonNull(clock);
            this.retention = Objects.requireNonNull(retention);
            this.beforeCreate = Objects.requireNonNull(beforeCreate);
            if (retention.isZero() || retention.isNegative()) {
                throw new IllegalArgumentException(
                        "retention must be positive");
            }
        }

        public RegistrationResult register(
                long memberId,
                String rawKey,
                CreatePostRequest request) {
            var key = parseKey(rawKey);
            var scope = new Scope(memberId, OPERATION, key);
            var fingerprint = fingerprint(request);

            while (true) {
                var now = clock.instant();
                var existing = entries.get(scope);
                if (existing == null) {
                    var candidate = new Entry(fingerprint);
                    if (entries.putIfAbsent(
                            scope, candidate) == null) {
                        return create(
                                scope, candidate, request);
                    }
                    continue;
                }
                if (existing.isExpired(now)) {
                    entries.remove(scope, existing);
                    continue;
                }
                if (!existing.matches(fingerprint)) {
                    throw new PayloadMismatchException(
                            "The key belongs to another payload.");
                }
                var snapshot = existing.snapshot();
                if (snapshot == null) {
                    throw new RequestPendingException(
                            "A request with this key is in progress.");
                }
                return new RegistrationResult(snapshot, true);
            }
        }

        public int registrationCount() {
            return creations.get();
        }

        private RegistrationResult create(
                Scope scope,
                Entry entry,
                CreatePostRequest request) {
            try {
                beforeCreate.run();
                long id = sequence.incrementAndGet();
                creations.incrementAndGet();
                var response = new PostResponse(
                        id, request.title(), request.content());
                var snapshot = new ResponseSnapshot(
                        HttpStatus.CREATED.value(),
                        "/api/posts/" + id,
                        response);
                entry.complete(
                        snapshot,
                        clock.instant().plus(retention));
                return new RegistrationResult(snapshot, false);
            } catch (RuntimeException | Error failure) {
                entries.remove(scope, entry);
                throw failure;
            }
        }

        private static String parseKey(String rawKey) {
            if (rawKey == null
                    || rawKey.length() < 3
                    || rawKey.charAt(0) != '"'
                    || rawKey.charAt(rawKey.length() - 1) != '"') {
                throw new InvalidIdempotencyKeyException(
                        "Use a quoted key from the documented profile.");
            }
            var value = rawKey.substring(1, rawKey.length() - 1);
            if (!KEY_CONTENT.matcher(value).matches()) {
                throw new InvalidIdempotencyKeyException(
                        "The key content is outside the allowed profile.");
            }
            return value;
        }

        private static String fingerprint(
                CreatePostRequest request) {
            try {
                var digest = MessageDigest.getInstance("SHA-256");
                addField(digest, request.title());
                addField(digest, request.content());
                return HexFormat.of().formatHex(digest.digest());
            } catch (NoSuchAlgorithmException impossible) {
                throw new IllegalStateException(
                        "SHA-256 is required by Java", impossible);
            }
        }

        private static void addField(
                MessageDigest digest, String value) {
            var bytes = Objects.requireNonNull(value)
                    .getBytes(UTF_8);
            digest.update(ByteBuffer
                    .allocate(Integer.BYTES)
                    .putInt(bytes.length)
                    .array());
            digest.update(bytes);
        }
    }

    public record CreatePostRequest(
            String title,
            String content) {
    }

    public record PostResponse(
            long id,
            String title,
            String content) {
    }

    public record ResponseSnapshot(
            int status,
            String location,
            PostResponse body) {
    }

    public record RegistrationResult(
            ResponseSnapshot snapshot,
            boolean replayed) {
    }

    private record Scope(
            long memberId,
            String operation,
            String key) {
    }

    private static final class Entry {
        private final String fingerprint;
        private volatile ResponseSnapshot snapshot;
        private volatile Instant expiresAt;

        private Entry(String fingerprint) {
            this.fingerprint = fingerprint;
        }

        private boolean matches(String candidate) {
            return fingerprint.equals(candidate);
        }

        private ResponseSnapshot snapshot() {
            return snapshot;
        }

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

        private void complete(
                ResponseSnapshot response,
                Instant expiry) {
            snapshot = response;
            expiresAt = expiry;
        }
    }

    public static final class InvalidIdempotencyKeyException
            extends RuntimeException {
        public InvalidIdempotencyKeyException(String message) {
            super(message);
        }
    }

    public static final class PayloadMismatchException
            extends RuntimeException {
        public PayloadMismatchException(String message) {
            super(message);
        }
    }

    public static final class RequestPendingException
            extends RuntimeException {
        public RequestPendingException(String message) {
            super(message);
        }
    }

    private static final class MutableClock extends Clock {
        private volatile Instant current;
        private final ZoneId zone;

        private MutableClock(Instant current, ZoneId zone) {
            this.current = current;
            this.zone = zone;
        }

        private void advance(Duration duration) {
            current = current.plus(duration);
        }

        @Override
        public ZoneId getZone() {
            return zone;
        }

        @Override
        public Clock withZone(ZoneId newZone) {
            return new MutableClock(current, newZone);
        }

        @Override
        public Instant instant() {
            return current;
        }
    }
}