feat: Make sure that storm caching settings are resonable (#285)

* feat: Make sure that storm caching settings are reasonable

It was possible to configure a hierarchical keyring
with storm tracking settings that resulted in
poor caching performance.

If the grace period is greater than the TTL,
this results in items being immediately retried.

Author: seebees

framework/aws-kms/aws-kms-hierarchical-keyring.md

@@ -13,7 +13,7 @@
   - [Update Cache Entry Identifier Formulas to shared cache across multiple Hierarchical Keyrings](../../changes/2024-09-13_cache-across-hierarchical-keyrings/change.md)
   - New optional parameter `Partition ID` used to distinguish Cryptographic Material Providers (i.e: Hierarchical Keyrings) writing to a cache
 - 0.1.0
-  - Initital record
+  - Initial record
 
 ## Implementations
 
@@ -56,6 +56,20 @@ On initialization, the caller:
 - MAY provide a [Cache Type](#cache-type)
 - MAY provide a [Partition ID](#partition-id)
 
+If the cache to initialize is a [Storm Tracking Cryptographic Materials Cache](../storm-tracking-cryptographic-materials-cache.md#overview)
+then the settings on the storm tracking cache need to be rational with respect to the settings for the keyring.
+For example, a TTL that is less than the storm tracking grace period will result poor caching behavior.
+This is because all entries would be immediately within the grace period.
+
+For most purposes, the TTL should be much much greater than the grace period.
+
+If the cache to initialize is a [Storm Tracking Cryptographic Materials Cache](../storm-tracking-cryptographic-materials-cache.md#overview)
+then the [Grace Period](../storm-tracking-cryptographic-materials-cache.md#grace-period) MUST be less than the [cache limit TTL](#cache-limit-ttl).
+
+On initialization the Hierarchical Keyring MUST initialize a [cryptographic-materials-cache](../local-cryptographic-materials-cache.md) with the configured cache limit TTL and the max cache size.
+If no max cache size is provided, the cryptographic materials cache MUST be configured to a
+max cache size of 1000.
+
 If the Hierarchical Keyring does NOT get a `Shared` cache on initialization,
 it MUST initialize a [cryptographic-materials-cache](../local-cryptographic-materials-cache.md)
 with the user provided cache limit TTL and the entry capacity.

framework/storm-tracking-cryptographic-materials-cache.md

@@ -38,11 +38,11 @@ Initialization MUST also provide
 - [Grace Period](#grace-period)
 - [Grace Interval](#grace-interval)
 - [FanOut](#fanout)
-- [Inflight TTL](#inflight-ttl).
-- [sleepMilli](#sleepmilli).
+- [Inflight TTL](#inflight-ttl)
+- [sleepMilli](#sleepmilli)
 
 The implementation MUST instantiate a [Local CMC](local-cryptographic-materials-cache.md)
-to do the actual cacheing.
+to do the actual caching.
 
 ### Grace Period
 
@@ -80,6 +80,24 @@ If the implementation must block, and no more intelligent signaling is used,
 then the implementation should sleep for this many milliseconds before
 reexamining the state of the cache.
 
+## Consistency
+
+The settings need to be consistent.
+
+Here are examples of ambiguous or inconsistent settings:
+
+- A grace interval that exceeds the grace period is inconsistent because only one attempt is made per grace interval and the grace period will end before the next interval.
+- An in flight TTL that exceeds the grace period is inconsistent because the grace period will expire before the in flight TTL.
+- An in flight TTL that is less than the grace interval is inconsistent because only one attempt is made per grace interval and even if the in flight TTL expires before the interval another attempt should not start.
+
+Therefore
+
+- The [Grace Interval](#grace-interval) MUST be less than or equal to the [Grace Period](#grace-period).
+- The [Inflight TTL](#inflight-ttl) MUST be less than or equal to the [Grace Period](#grace-period).
+- The [Grace Interval](#grace-interval) MUST be less than or equal to the [Inflight TTL](#inflight-ttl).
+
+For most purposes, the [Grace Period](#grace-period) should be several times larger than the [Grace Interval](#grace-interval).
+
 ## Behaviors
 
 The interface MUST be exactly the same as a [Local CMC](local-cryptographic-materials-cache.md),