chore: clarify InFlightTTLExceeded exception (#1169)

Update documentation in the different runtimes
to further clarify when InFlightTTLExceeded is raised.

Co-authored-by: Shubham Chaturvedi <scchatur@amazon.com>
Co-authored-by: seebees <ryanemer@amazon.com>

Author: 3 people

AwsCryptographicMaterialProviders/dafny/AwsCryptographicMaterialProviders/Model/cryptographic-materials-cache.smithy

@@ -51,6 +51,11 @@ structure PutCacheEntryInput {
 operation GetCacheEntry {
   input: GetCacheEntryInput,
   output: GetCacheEntryOutput,
+  errors: [
+    InFlightTTLExceeded
+    EntryDoesNotExist
+    //Technically, numerous other errors, depending on the implementation
+  ]
 }
 
 structure GetCacheEntryInput {
@@ -115,6 +120,7 @@ structure UpdateUsageMetadataInput {
 }
 
 @error("client")
+@documentation("The requested element is not in the cache; AWS Crypto Tools intends to deprecate this for a non-error control scheme.")
 structure EntryDoesNotExist {
   @required
   message: String,
@@ -127,6 +133,19 @@ structure EntryAlreadyExists {
 }
 
 @error("client")
+@documentation(
+"Thrown if a request is waiting for longer than `inflightTTL`.
+The Storm Tracking Cache protects against unbounded parallelism.
+The Storm Tracking Cache will only work `fanOut` number of concurrent requests.
+As requests are completed,
+queued requests are worked.
+If a request is not worked in less than `inflightTTL`,
+this exception is thrown.
+
+Note that this exception does NOT imply that the material requested
+is invalid or unreachable;
+it only implies that the cache had more requests to handle than it could
+with the given `fanOut` and `inflightTTL` constraints.")
 structure InFlightTTLExceeded {
   @required
   message: String,

AwsCryptographicMaterialProviders/runtimes/go/ImplementationFromDafny-go/awscryptographymaterialproviderssmithygeneratedtypes/errors.go

@@ -5,6 +5,9 @@
 
 import java.util.Objects;
 
+/**
+ * The requested element is not in the cache; AWS Crypto Tools intends to deprecate this for a non-error control scheme.
+ */
 public class EntryDoesNotExist extends RuntimeException {
 
   protected EntryDoesNotExist(BuilderImpl builder) {

AwsCryptographicMaterialProviders/runtimes/go/TestsFromDafny-go/awscryptographymaterialproviderssmithygeneratedtypes/errors.go

@@ -5,6 +5,20 @@
 
 import java.util.Objects;
 
+/**
+ * Thrown if a request is waiting for longer than `inflightTTL`.
+ * The Storm Tracking Cache protects against unbounded parallelism.
+ * The Storm Tracking Cache will only work `fanOut` number of concurrent requests.
+ * As requests are completed,
+ * queued requests are worked.
+ * If a request is not worked in less than `inflightTTL`,
+ * this exception is thrown.
+ *
+ * Note that this exception does NOT imply that the material requested
+ * is invalid or unreachable;
+ * it only implies that the cache had more requests to handle than it could
+ * with the given `fanOut` and `inflightTTL` constraints.
+ */
 public class InFlightTTLExceeded extends RuntimeException {
 
   protected InFlightTTLExceeded(BuilderImpl builder) {

AwsCryptographicMaterialProviders/runtimes/java/src/main/smithy-generated/software/amazon/cryptography/materialproviders/model/EntryDoesNotExist.java

@@ -96,6 +96,114 @@ def __eq__(self, other: Any) -> bool:
         return all(getattr(self, a) == getattr(other, a) for a in attributes)
 
 
+class EntryDoesNotExist(ApiError[Literal["EntryDoesNotExist"]]):
+    code: Literal["EntryDoesNotExist"] = "EntryDoesNotExist"
+    message: str
+
+    def __init__(
+        self,
+        *,
+        message: str,
+    ):
+        """The requested element is not in the cache; AWS Crypto Tools intends
+        to deprecate this for a non-error control scheme.
+
+        :param message: A message associated with the specific error.
+        """
+        super().__init__(message)
+
+    def as_dict(self) -> Dict[str, Any]:
+        """Converts the EntryDoesNotExist to a dictionary."""
+        return {
+            "message": self.message,
+            "code": self.code,
+        }
+
+    @staticmethod
+    def from_dict(d: Dict[str, Any]) -> "EntryDoesNotExist":
+        """Creates a EntryDoesNotExist from a dictionary."""
+        kwargs: Dict[str, Any] = {
+            "message": d["message"],
+        }
+
+        return EntryDoesNotExist(**kwargs)
+
+    def __repr__(self) -> str:
+        result = "EntryDoesNotExist("
+        if self.message is not None:
+            result += f"message={repr(self.message)}"
+
+        return result + ")"
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, EntryDoesNotExist):
+            return False
+        attributes: list[str] = [
+            "message",
+            "message",
+        ]
+        return all(getattr(self, a) == getattr(other, a) for a in attributes)
+
+
+class InFlightTTLExceeded(ApiError[Literal["InFlightTTLExceeded"]]):
+    code: Literal["InFlightTTLExceeded"] = "InFlightTTLExceeded"
+    message: str
+
+    def __init__(
+        self,
+        *,
+        message: str,
+    ):
+        """Thrown if a request is waiting for longer than `inflightTTL`. The
+        Storm Tracking Cache protects against unbounded parallelism. The Storm
+        Tracking Cache will only work `fanOut` number of concurrent requests.
+        As requests are completed, queued requests are worked. If a request is
+        not worked in less than `inflightTTL`, this exception is thrown.
+
+        Note that this exception does NOT imply that the material
+        requested
+        is invalid or unreachable;
+        it only implies that the cache had more
+        requests to handle than it could
+        with the given `fanOut` and `inflightTTL`
+        constraints.
+        :param message: A message associated with the specific error.
+        """
+        super().__init__(message)
+
+    def as_dict(self) -> Dict[str, Any]:
+        """Converts the InFlightTTLExceeded to a dictionary."""
+        return {
+            "message": self.message,
+            "code": self.code,
+        }
+
+    @staticmethod
+    def from_dict(d: Dict[str, Any]) -> "InFlightTTLExceeded":
+        """Creates a InFlightTTLExceeded from a dictionary."""
+        kwargs: Dict[str, Any] = {
+            "message": d["message"],
+        }
+
+        return InFlightTTLExceeded(**kwargs)
+
+    def __repr__(self) -> str:
+        result = "InFlightTTLExceeded("
+        if self.message is not None:
+            result += f"message={repr(self.message)}"
+
+        return result + ")"
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, InFlightTTLExceeded):
+            return False
+        attributes: list[str] = [
+            "message",
+            "message",
+        ]
+        return all(getattr(self, a) == getattr(other, a) for a in attributes)
+
+
 class InvalidDecryptionMaterials(ApiError[Literal["InvalidDecryptionMaterials"]]):
     code: Literal["InvalidDecryptionMaterials"] = "InvalidDecryptionMaterials"
     message: str
@@ -466,94 +574,6 @@ def __eq__(self, other: Any) -> bool:
         return all(getattr(self, a) == getattr(other, a) for a in attributes)
 
 
-class EntryDoesNotExist(ApiError[Literal["EntryDoesNotExist"]]):
-    code: Literal["EntryDoesNotExist"] = "EntryDoesNotExist"
-    message: str
-
-    def __init__(
-        self,
-        *,
-        message: str,
-    ):
-        super().__init__(message)
-
-    def as_dict(self) -> Dict[str, Any]:
-        """Converts the EntryDoesNotExist to a dictionary."""
-        return {
-            "message": self.message,
-            "code": self.code,
-        }
-
-    @staticmethod
-    def from_dict(d: Dict[str, Any]) -> "EntryDoesNotExist":
-        """Creates a EntryDoesNotExist from a dictionary."""
-        kwargs: Dict[str, Any] = {
-            "message": d["message"],
-        }
-
-        return EntryDoesNotExist(**kwargs)
-
-    def __repr__(self) -> str:
-        result = "EntryDoesNotExist("
-        if self.message is not None:
-            result += f"message={repr(self.message)}"
-
-        return result + ")"
-
-    def __eq__(self, other: Any) -> bool:
-        if not isinstance(other, EntryDoesNotExist):
-            return False
-        attributes: list[str] = [
-            "message",
-            "message",
-        ]
-        return all(getattr(self, a) == getattr(other, a) for a in attributes)
-
-
-class InFlightTTLExceeded(ApiError[Literal["InFlightTTLExceeded"]]):
-    code: Literal["InFlightTTLExceeded"] = "InFlightTTLExceeded"
-    message: str
-
-    def __init__(
-        self,
-        *,
-        message: str,
-    ):
-        super().__init__(message)
-
-    def as_dict(self) -> Dict[str, Any]:
-        """Converts the InFlightTTLExceeded to a dictionary."""
-        return {
-            "message": self.message,
-            "code": self.code,
-        }
-
-    @staticmethod
-    def from_dict(d: Dict[str, Any]) -> "InFlightTTLExceeded":
-        """Creates a InFlightTTLExceeded from a dictionary."""
-        kwargs: Dict[str, Any] = {
-            "message": d["message"],
-        }
-
-        return InFlightTTLExceeded(**kwargs)
-
-    def __repr__(self) -> str:
-        result = "InFlightTTLExceeded("
-        if self.message is not None:
-            result += f"message={repr(self.message)}"
-
-        return result + ")"
-
-    def __eq__(self, other: Any) -> bool:
-        if not isinstance(other, InFlightTTLExceeded):
-            return False
-        attributes: list[str] = [
-            "message",
-            "message",
-        ]
-        return all(getattr(self, a) == getattr(other, a) for a in attributes)
-
-
 class AwsCryptographicMaterialProvidersException(
     ApiError[Literal["AwsCryptographicMaterialProvidersException"]]
 ):