Merge pull request #49 from bright-room/feat/28-schedule-aware-http-response-with-503-and-retry-after-header

Close #28: Return 503 + Retry-After for schedule-inactive gate denials

Author: kukv

.claude/guidelines/coding.md

@@ -315,3 +315,28 @@ return switch (type) {
 - `if/else if/else` チェーンは分岐の追加漏れや順序依存のバグを招きやすい
 - `enum` に対する `switch` 式はコンパイラが網羅性を検証するため、安全性が高い
 - `if/else if/else` が必要になる状況自体が、型の設計やポリモーフィズムの活用で解消できることが多い
+
+---
+
+## CG-9: `+` 演算子による文字列結合の禁止
+
+文字列結合に `+` 演算子を使用せず、`String.format()` を使用すること。
+
+### NG
+
+```java
+throw new IllegalArgumentException(
+    "Schedule start must not be after end, but start=" + start + " end=" + end);
+```
+
+### OK
+
+```java
+throw new IllegalArgumentException(
+    String.format("Schedule start must not be after end, but start=%s end=%s", start, end));
+```
+
+### 理由
+
+- `+` 演算子による結合はリテラルと変数が混在すると可読性が低下する
+- `String.format()` はテンプレートと引数が分離されるため、メッセージの全体像を把握しやすい

core/src/main/java/net/brightroom/endpointgate/core/evaluation/AccessDecision.java

@@ -1,5 +1,10 @@
 package net.brightroom.endpointgate.core.evaluation;
 
+import java.time.Instant;
+import net.brightroom.endpointgate.core.exception.EndpointGateAccessDeniedException;
+import net.brightroom.endpointgate.core.exception.EndpointGateScheduleInactiveException;
+import org.jspecify.annotations.Nullable;
+
 /**
  * Represents the outcome of an endpoint gate evaluation pipeline.
  *
@@ -11,12 +16,32 @@ public sealed interface AccessDecision {
   record Allowed() implements AccessDecision {}
 
   /**
-   * Indicates that access is denied, with the gate identifier and reason.
+   * Indicates that access is denied, with the gate identifier, reason, and optional retry-after
+   * time.
    *
    * @param gateId the gate identifier that was denied
    * @param reason the reason for denial
+   * @param retryAfter the time after which the client may retry, or {@code null} if not applicable
    */
-  record Denied(String gateId, DeniedReason reason) implements AccessDecision {}
+  record Denied(String gateId, DeniedReason reason, @Nullable Instant retryAfter)
+      implements AccessDecision {
+
+    /**
+     * Converts this denied decision to the appropriate exception type.
+     *
+     * <p>If the reason is {@link DeniedReason#SCHEDULE_INACTIVE}, returns a {@link
+     * EndpointGateScheduleInactiveException}. Otherwise, returns a {@link
+     * EndpointGateAccessDeniedException}.
+     *
+     * @return the exception corresponding to this denial
+     */
+    public EndpointGateAccessDeniedException toException() {
+      if (reason == DeniedReason.SCHEDULE_INACTIVE) {
+        return new EndpointGateScheduleInactiveException(gateId, retryAfter);
+      }
+      return new EndpointGateAccessDeniedException(gateId);
+    }
+  }
 
   /** Reason for denying access in the evaluation pipeline. */
   enum DeniedReason {
@@ -40,13 +65,25 @@ static AccessDecision allowed() {
   }
 
   /**
-   * Returns a {@link Denied} decision.
+   * Returns a {@link Denied} decision with no retry-after time.
    *
    * @param gateId the gate identifier that was denied
    * @param reason the reason for denial
    * @return a new {@code Denied} instance
    */
   static AccessDecision denied(String gateId, DeniedReason reason) {
-    return new Denied(gateId, reason);
+    return new Denied(gateId, reason, null);
+  }
+
+  /**
+   * Returns a {@link Denied} decision with a retry-after time.
+   *
+   * @param gateId the gate identifier that was denied
+   * @param reason the reason for denial
+   * @param retryAfter the time after which the client may retry
+   * @return a new {@code Denied} instance
+   */
+  static AccessDecision denied(String gateId, DeniedReason reason, Instant retryAfter) {
+    return new Denied(gateId, reason, retryAfter);
   }
 }

core/src/main/java/net/brightroom/endpointgate/core/evaluation/ScheduleEvaluationStep.java

@@ -27,6 +27,11 @@ public Optional<AccessDecision> evaluate(EvaluationContext context) {
     return scheduleProvider
         .getSchedule(context.gateId())
         .filter(schedule -> !schedule.isActive(clock.instant()))
-        .map(schedule -> AccessDecision.denied(context.gateId(), DeniedReason.SCHEDULE_INACTIVE));
+        .map(
+            schedule ->
+                AccessDecision.denied(
+                    context.gateId(),
+                    DeniedReason.SCHEDULE_INACTIVE,
+                    schedule.retryAfterInstant(clock)));
   }
 }

core/src/main/java/net/brightroom/endpointgate/core/exception/EndpointGateAccessDeniedException.java

@@ -23,6 +23,17 @@ public EndpointGateAccessDeniedException(String gateId) {
     this.gateId = gateId;
   }
 
+  /**
+   * Constructor for subclasses that need to customize the exception message.
+   *
+   * @param gateId the identifier of the gate that is not available
+   * @param message the detail message
+   */
+  protected EndpointGateAccessDeniedException(String gateId, String message) {
+    super(message);
+    this.gateId = gateId;
+  }
+
   /**
    * Returns the identifier of the gate that is not available.
    *

core/src/main/java/net/brightroom/endpointgate/core/exception/EndpointGateScheduleInactiveException.java

@@ -0,0 +1,54 @@
+package net.brightroom.endpointgate.core.exception;
+
+import java.time.Instant;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Thrown when access to a gate-protected endpoint is denied because the gate's schedule is not
+ * currently active.
+ *
+ * <p>This is a subclass of {@link EndpointGateAccessDeniedException}, so existing
+ * {@code @ControllerAdvice} handlers that catch {@code EndpointGateAccessDeniedException} will also
+ * catch this exception.
+ *
+ * <p>The {@link #retryAfter()} method returns the schedule start time as an {@link Instant}, which
+ * can be used to populate the HTTP {@code Retry-After} header. If the schedule has no configured
+ * start time (only an end time), {@link #retryAfter()} returns {@code null}.
+ */
+public class EndpointGateScheduleInactiveException extends EndpointGateAccessDeniedException {
+
+  private static final long serialVersionUID = 1L;
+
+  private final @Nullable Instant retryAfter;
+
+  /**
+   * Constructor.
+   *
+   * @param gateId the identifier of the gate that is not available
+   * @param retryAfter the schedule start time as an {@link Instant}, or {@code null} if the
+   *     schedule has no start time configured
+   */
+  public EndpointGateScheduleInactiveException(String gateId, @Nullable Instant retryAfter) {
+    super(gateId, buildMessage(gateId, retryAfter));
+    this.retryAfter = retryAfter;
+  }
+
+  /**
+   * Returns the schedule start time as an {@link Instant}, or {@code null} if the schedule has no
+   * start time configured.
+   *
+   * <p>This value can be used to populate the HTTP {@code Retry-After} response header.
+   *
+   * @return the retry-after instant, or {@code null}
+   */
+  public @Nullable Instant retryAfter() {
+    return retryAfter;
+  }
+
+  private static String buildMessage(String gateId, @Nullable Instant retryAfter) {
+    if (retryAfter == null) {
+      return String.format("Gate '%s' is not available", gateId);
+    }
+    return String.format("Gate '%s' is not available until %s", gateId, retryAfter);
+  }
+}

core/src/main/java/net/brightroom/endpointgate/core/provider/Schedule.java

@@ -1,8 +1,10 @@
 package net.brightroom.endpointgate.core.provider;
 
+import java.time.Clock;
 import java.time.Instant;
 import java.time.LocalDateTime;
 import java.time.ZoneId;
+import java.time.ZonedDateTime;
 import org.jspecify.annotations.Nullable;
 
 /**
@@ -35,11 +37,16 @@
 public record Schedule(
     @Nullable LocalDateTime start, @Nullable LocalDateTime end, @Nullable ZoneId timezone) {
 
-  /** Validates that start is not after end. */
+  /** Validates that start is not after an end. */
   public Schedule {
-    if (start != null && end != null && start.isAfter(end)) {
-      throw new IllegalArgumentException(
-          "Schedule start must not be after end, but start=" + start + " end=" + end);
+    if (start != null) {
+      if (end != null) {
+        if (start.isAfter(end)) {
+          throw new IllegalArgumentException(
+              String.format(
+                  "Schedule start must not be after end, but start=%s end=%s", start, end));
+        }
+      }
     }
   }
 
@@ -50,10 +57,47 @@ public record Schedule(
    * @return {@code true} if {@code now} falls within the configured window, {@code false} otherwise
    */
   public boolean isActive(Instant now) {
-    ZoneId zone = timezone != null ? timezone : ZoneId.systemDefault();
+    ZoneId zone = resolveZone();
     LocalDateTime localNow = now.atZone(zone).toLocalDateTime();
-    if (start != null && localNow.isBefore(start)) return false;
-    if (end != null && localNow.isAfter(end)) return false;
+    if (start != null) {
+      if (localNow.isBefore(start)) {
+        return false;
+      }
+    }
+    if (end != null) {
+      return !localNow.isAfter(end);
+    }
     return true;
   }
+
+  /**
+   * Returns the retry-after {@link Instant} for this schedule, or {@code null} if not applicable.
+   *
+   * <p>Returns the {@link #start()} instant if {@code start} is non-null and in the future relative
+   * to the given {@code clock}. Returns {@code null} if {@code start} is null, or if {@code start}
+   * is already in the past (to avoid sending a stale retry-after hint to clients).
+   *
+   * @param clock the clock used to determine the current time
+   * @return the retry-after instant, or {@code null}
+   */
+  public @Nullable Instant retryAfterInstant(Clock clock) {
+    if (start == null) {
+      return null;
+    }
+    ZoneId zone = resolveZone();
+    ZonedDateTime zonedStart = start.atZone(zone);
+    Instant startInstant = zonedStart.toInstant();
+    Instant now = clock.instant();
+    if (startInstant.isBefore(now)) {
+      return null;
+    }
+    return startInstant;
+  }
+
+  private ZoneId resolveZone() {
+    if (timezone != null) {
+      return timezone;
+    }
+    return ZoneId.systemDefault();
+  }
 }

core/src/test/java/net/brightroom/endpointgate/core/evaluation/AccessDecisionTest.java

@@ -2,7 +2,10 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+import java.time.Instant;
 import net.brightroom.endpointgate.core.evaluation.AccessDecision.DeniedReason;
+import net.brightroom.endpointgate.core.exception.EndpointGateAccessDeniedException;
+import net.brightroom.endpointgate.core.exception.EndpointGateScheduleInactiveException;
 import org.junit.jupiter.api.Test;
 
 class AccessDecisionTest {
@@ -20,6 +23,7 @@ void denied_returnsDeniedInstanceWithGateIdAndReason() {
     AccessDecision.Denied denied = (AccessDecision.Denied) decision;
     assertThat(denied.gateId()).isEqualTo("my-gate");
     assertThat(denied.reason()).isEqualTo(DeniedReason.DISABLED);
+    assertThat(denied.retryAfter()).isNull();
   }
 
   @Test
@@ -29,4 +33,52 @@ void denied_supportsAllReasons() {
       assertThat(((AccessDecision.Denied) decision).reason()).isEqualTo(reason);
     }
   }
+
+  @Test
+  void denied_withRetryAfter_storesInstant() {
+    Instant retryAfter = Instant.parse("2099-01-01T00:00:00Z");
+    AccessDecision decision =
+        AccessDecision.denied("my-gate", DeniedReason.SCHEDULE_INACTIVE, retryAfter);
+    AccessDecision.Denied denied = (AccessDecision.Denied) decision;
+    assertThat(denied.retryAfter()).isEqualTo(retryAfter);
+  }
+
+  @Test
+  void toException_returnsScheduleInactiveException_whenReasonIsScheduleInactive() {
+    Instant retryAfter = Instant.parse("2099-01-01T00:00:00Z");
+    AccessDecision.Denied denied =
+        (AccessDecision.Denied)
+            AccessDecision.denied("my-gate", DeniedReason.SCHEDULE_INACTIVE, retryAfter);
+    EndpointGateAccessDeniedException e = denied.toException();
+    assertThat(e).isInstanceOf(EndpointGateScheduleInactiveException.class);
+    EndpointGateScheduleInactiveException scheduleException =
+        (EndpointGateScheduleInactiveException) e;
+    assertThat(scheduleException.gateId()).isEqualTo("my-gate");
+    assertThat(scheduleException.retryAfter()).isEqualTo(retryAfter);
+  }
+
+  @Test
+  void toException_returnsAccessDeniedException_whenReasonIsDisabled() {
+    AccessDecision.Denied denied =
+        (AccessDecision.Denied) AccessDecision.denied("my-gate", DeniedReason.DISABLED);
+    EndpointGateAccessDeniedException e = denied.toException();
+    assertThat(e).isExactlyInstanceOf(EndpointGateAccessDeniedException.class);
+    assertThat(e.gateId()).isEqualTo("my-gate");
+  }
+
+  @Test
+  void toException_returnsAccessDeniedException_whenReasonIsConditionNotMet() {
+    AccessDecision.Denied denied =
+        (AccessDecision.Denied) AccessDecision.denied("my-gate", DeniedReason.CONDITION_NOT_MET);
+    EndpointGateAccessDeniedException e = denied.toException();
+    assertThat(e).isExactlyInstanceOf(EndpointGateAccessDeniedException.class);
+  }
+
+  @Test
+  void toException_returnsAccessDeniedException_whenReasonIsRolloutExcluded() {
+    AccessDecision.Denied denied =
+        (AccessDecision.Denied) AccessDecision.denied("my-gate", DeniedReason.ROLLOUT_EXCLUDED);
+    EndpointGateAccessDeniedException e = denied.toException();
+    assertThat(e).isExactlyInstanceOf(EndpointGateAccessDeniedException.class);
+  }
 }

core/src/test/java/net/brightroom/endpointgate/core/evaluation/ScheduleEvaluationStepTest.java

@@ -45,7 +45,7 @@ void evaluate_returnsEmpty_whenScheduleIsActive() {
 
   @Test
   void evaluate_returnsDenied_whenScheduleIsInactive_endInPast() {
-    // end in past → inactive
+    // end in past, no start → inactive; retryAfter should be null
     Schedule inactive = new Schedule(null, LocalDateTime.of(2025, 1, 1, 0, 0), ZoneId.of("UTC"));
     when(scheduleProvider.getSchedule("my-gate")).thenReturn(Optional.of(inactive));
 
@@ -54,17 +54,34 @@ void evaluate_returnsDenied_whenScheduleIsInactive_endInPast() {
     AccessDecision.Denied denied = (AccessDecision.Denied) result.get();
     assertThat(denied.gateId()).isEqualTo("my-gate");
     assertThat(denied.reason()).isEqualTo(DeniedReason.SCHEDULE_INACTIVE);
+    assertThat(denied.retryAfter()).isNull();
   }
 
   @Test
   void evaluate_returnsDenied_whenScheduleIsInactive_startInFuture() {
-    // start in future → inactive
-    Schedule inactive = new Schedule(LocalDateTime.of(2025, 12, 1, 0, 0), null, ZoneId.of("UTC"));
+    // start in future → inactive; retryAfter should be the start instant
+    LocalDateTime futureStart = LocalDateTime.of(2025, 12, 1, 0, 0);
+    Schedule inactive = new Schedule(futureStart, null, ZoneId.of("UTC"));
     when(scheduleProvider.getSchedule("my-gate")).thenReturn(Optional.of(inactive));
 
     Optional<AccessDecision> result = step.evaluate(CTX);
     assertThat(result).isPresent();
-    assertThat(((AccessDecision.Denied) result.get()).reason())
-        .isEqualTo(DeniedReason.SCHEDULE_INACTIVE);
+    AccessDecision.Denied denied = (AccessDecision.Denied) result.get();
+    assertThat(denied.reason()).isEqualTo(DeniedReason.SCHEDULE_INACTIVE);
+    assertThat(denied.retryAfter()).isEqualTo(futureStart.atZone(ZoneId.of("UTC")).toInstant());
+  }
+
+  @Test
+  void evaluate_returnsDenied_withTimezoneAwareRetryAfter_whenTimezoneConfigured() {
+    // start in future with Tokyo timezone
+    LocalDateTime futureStart = LocalDateTime.of(2025, 12, 1, 9, 0);
+    ZoneId tokyo = ZoneId.of("Asia/Tokyo");
+    Schedule inactive = new Schedule(futureStart, null, tokyo);
+    when(scheduleProvider.getSchedule("my-gate")).thenReturn(Optional.of(inactive));
+
+    Optional<AccessDecision> result = step.evaluate(CTX);
+    assertThat(result).isPresent();
+    AccessDecision.Denied denied = (AccessDecision.Denied) result.get();
+    assertThat(denied.retryAfter()).isEqualTo(futureStart.atZone(tokyo).toInstant());
   }
 }