propagate -> do-not-retry + javadoc

Author: Carter Kozak

errors/src/main/java/com/palantir/conjure/java/api/errors/QosReason.java

@@ -150,25 +150,26 @@ public QosReason build() {
         }
     }
 
+    /**
+     * Conveys the servers opinion on whether a QoS failure should be retried, or propagate
+     * back to the caller and result in a failure. There is no guarantee that these values
+     * will be respected by all clients, and should be considered best-effort.
+     */
     public enum RetryHint {
-        // TODO(ckozak): Should we declare the existing default value? Perhaps best if we only
-        // declare the minimal api to opt into new behavior.
-        //        /** Clients should attempt to retry this failure. */
-        //        EAGER,
         /**
          * Clients should not attempt to retry this failure,
          * providing the failure as context back to the initial caller.
          */
-        PROPAGATE;
+        DO_NOT_RETRY;
     }
 
+    /**
+     * Describes the cause of a QoS failure when known to be non-default. By default, we assume that
+     * a 503 Unavailable is the result of a node-wide limit being reached, and that a 429 is specific
+     * to an individual endpoint on a node. These assumptions do not hold true in all cases, so
+     * {@link DueTo} informs relays this intent.
+     */
     public enum DueTo {
-        // TODO(ckozak): should we declare values that align with the default 503 and 429 behavior, which
-        // impact rate limiters for the node and endpoint specifically? If we do, they will be propagated
-        // in ways that don't make sense (despite being the default behavior today). Declaring a user limit
-        // may be more reasonable since the user token is generally passed along, however per-endpoint limits
-        // lose some meaning when rethrown by a calling service.
-
         /**
          * A cause that the RPC system isn't directly aware of, for example a user or user-agent specific limit, or
          * based on a specific resource that's being accessed, as opposed to the target node as a whole, or endpoint.

errors/src/main/java/com/palantir/conjure/java/api/errors/QosReasons.java

@@ -28,7 +28,7 @@ public final class QosReasons {
     private static final String RETRY_HINT_HEADER = "Qos-Retry-Hint";
 
     private static final String DUE_TO_CUSTOM_HEADER_VALUE = "custom";
-    private static final String RETRY_HINT_PROPAGATE_HEADER_VALUE = "propagate";
+    private static final String RETRY_HINT_DO_NOT_RETRY_HEADER_VALUE = "do-not-retry";
 
     public static <T> void encodeToResponse(
             QosReason reason, T response, QosResponseEncodingAdapter<? super T> adapter) {
@@ -76,8 +76,8 @@ static Optional<DueTo> parseDueTo(String dueTo) {
 
     // VisibleForTesting
     static Optional<RetryHint> parseRetryHint(String retryHint) {
-        if (RETRY_HINT_PROPAGATE_HEADER_VALUE.equalsIgnoreCase(retryHint)) {
-            return Optional.of(RetryHint.PROPAGATE);
+        if (RETRY_HINT_DO_NOT_RETRY_HEADER_VALUE.equalsIgnoreCase(retryHint)) {
+            return Optional.of(RetryHint.DO_NOT_RETRY);
         }
         return Optional.empty();
     }
@@ -92,7 +92,7 @@ static String toHeaderValue(DueTo dueTo) {
     // VisibleForTesting
     static String toHeaderValue(RetryHint retryHint) {
         return switch (retryHint) {
-            case PROPAGATE -> RETRY_HINT_PROPAGATE_HEADER_VALUE;
+            case DO_NOT_RETRY -> RETRY_HINT_DO_NOT_RETRY_HEADER_VALUE;
         };
     }
 

errors/src/test/java/com/palantir/conjure/java/api/errors/QosReasonsTest.java

@@ -43,10 +43,10 @@ public void testReasonWithFields() {
         QosReason reason = QosReason.builder()
                 .reason("reason")
                 .dueTo(DueTo.CUSTOM)
-                .retryHint(RetryHint.PROPAGATE)
+                .retryHint(RetryHint.DO_NOT_RETRY)
                 .build();
         QosReasons.encodeToResponse(reason, headers, Encoder.INSTANCE);
-        assertThat(headers).isEqualTo(ImmutableMap.of("Qos-Due-To", "custom", "Qos-Retry-Hint", "propagate"));
+        assertThat(headers).isEqualTo(ImmutableMap.of("Qos-Due-To", "custom", "Qos-Retry-Hint", "do-not-retry"));
     }
 
     @Test
@@ -55,7 +55,7 @@ public void testRoundTrip() {
         QosReason original = QosReason.builder()
                 .reason("reason")
                 .dueTo(DueTo.CUSTOM)
-                .retryHint(RetryHint.PROPAGATE)
+                .retryHint(RetryHint.DO_NOT_RETRY)
                 .build();
         QosReasons.encodeToResponse(original, headers, Encoder.INSTANCE);
         QosReason recreated = QosReasons.parseFromResponse(headers, Decoder.INSTANCE);
@@ -95,8 +95,8 @@ public void retryHintRoundTrip() {
 
     @Test
     public void retryHintCaseSensitivity() {
-        assertThat(QosReasons.parseRetryHint("propagate")).hasValue(RetryHint.PROPAGATE);
-        assertThat(QosReasons.parseRetryHint("PROPAGATE")).hasValue(RetryHint.PROPAGATE);
+        assertThat(QosReasons.parseRetryHint("do-not-retry")).hasValue(RetryHint.DO_NOT_RETRY);
+        assertThat(QosReasons.parseRetryHint("DO-NOT-RETRY")).hasValue(RetryHint.DO_NOT_RETRY);
     }
 
     private enum Encoder implements QosReasons.QosResponseEncodingAdapter<Map<String, String>> {