Optional jitter for the cache ttl

zio-cache/shared/src/main/scala/zio/cache/Cache.scala

@@ -91,16 +91,23 @@ object Cache {
   )(implicit trace: Trace): URIO[Environment, Cache[Key, Error, Value]] =
     makeWith(capacity, lookup)(_ => timeToLive)
 
+  def makeWith[Key, Environment, Error, Value](
+    capacity: Int,
+    lookup: Lookup[Key, Environment, Error, Value]
+  )(
+    timeToLive: Exit[Error, Value] => Duration
+  )(implicit trace: Trace): URIO[Environment, Cache[Key, Error, Value]] =
+    makeWith(capacity, lookup, TimeToLive { value: Exit[Error, Value] => ZIO.succeed(timeToLive(value)) })
+
   /**
    * Constructs a new cache with the specified capacity, time to live, and
    * lookup function, where the time to live can depend on the `Exit` value
    * returned by the lookup function.
    */
   def makeWith[Key, Environment, Error, Value](
     capacity: Int,
-    lookup: Lookup[Key, Environment, Error, Value]
-  )(
-    timeToLive: Exit[Error, Value] => Duration
+    lookup: Lookup[Key, Environment, Error, Value],
+    timeToLive: TimeToLive[Error, Value]
   )(implicit trace: Trace): URIO[Environment, Cache[Key, Error, Value]] =
     ZIO.clock.flatMap { clock =>
       ZIO.environment[Environment].flatMap { environment =>
@@ -260,11 +267,13 @@ object Cache {
                 .provideEnvironment(environment)
                 .exit
                 .flatMap { exit =>
-                  val now        = Unsafe.unsafeCompat(implicit u => clock.unsafe.instant())
-                  val entryStats = EntryStats(now)
+                  timeToLive.compute(exit).flatMap { duration =>
+                    val now        = Unsafe.unsafeCompat(implicit u => clock.unsafe.instant())
+                    val entryStats = EntryStats(now)
 
-                  map.put(key, MapValue.Complete(new MapKey(key), exit, entryStats, now.plus(timeToLive(exit))))
-                  promise.done(exit) *> ZIO.done(exit)
+                    map.put(key, MapValue.Complete(new MapKey(key), exit, entryStats, now.plus(duration)))
+                    promise.done(exit) *> ZIO.done(exit)
+                  }
                 }
                 .onInterrupt(promise.interrupt *> ZIO.succeed(map.remove(key)))
 

zio-cache/shared/src/main/scala/zio/cache/TimeToLive.scala

@@ -0,0 +1,25 @@
+package zio.cache
+
+import zio.{Duration, Exit, Trace, UIO, ZIO}
+
+/**
+ *  Provides a computation to determine the minimum duration between two cache lookup function evaluations
+ *  for a particular key
+ */
+case class TimeToLive[Error, Value](compute: Exit[Error, Value] => UIO[Duration])
+object TimeToLive {
+  def fixed[Error, Value](duration: Duration)(implicit trace: Trace) = TimeToLive { _: Exit[Error, Value] =>
+    ZIO.succeed(duration)
+  }
+  def infinity[Error, Value](implicit trace: Trace) = fixed(Duration.Infinity)
+  def jittered[Error, Value](duration: Duration)(implicit trace: Trace): TimeToLive[Error, Value] =
+    jittered(0.8, 1.2, duration)
+  def jittered[Error, Value](min: Double, max: Double, duration: Duration)(implicit trace: Trace) = TimeToLive {
+    _: Exit[Error, Value] =>
+      zio.Random.nextDouble.map { random =>
+        val d        = duration.toNanos
+        val jittered = d * min * (1 - random) + d * max * random
+        Duration.fromNanos(jittered.toLong)
+      }
+  }
+}

zio-cache/shared/src/test/scala/zio/cache/CacheSpec.scala

@@ -142,6 +142,33 @@ object CacheSpec extends ZIOSpecDefault {
           size  <- cache.size
         } yield assertTrue(size == 10)
       }
+    },
+    test("time to live using fixed duration") {
+      for {
+        cache <- Cache.makeWith(100, Lookup { n: Int => ZIO.succeed(List(1, 2, 3)) }, TimeToLive.fixed(1.second))
+        v1 <- cache.get(1) // miss
+        v2 <- cache.get(1) // hit
+        _ <- TestClock.adjust(1001.millis)
+        v3 <- cache.get(1) // hit but expired, thus another miss
+        cacheStats <- cache.cacheStats
+        hits        = cacheStats.hits
+        misses      = cacheStats.misses
+      } yield {
+        assertTrue(v1 eq v2) && // v1 and v2 retrieve the same cached object
+        assertTrue(hits == 2L) &&
+        assertTrue(v1 ne v3) && // v3 points to a different object since v1 has expired
+        assertTrue(misses == 2L)
+      }
+    },
+    test("jitter computation") {
+      check(Gen.double(0, 1)) { min =>
+        check(Gen.double(min, 1)) { max =>
+          TimeToLive.jittered(min, max, 1.second).compute(Exit.succeed(())).map { duration =>
+            assertTrue(duration >= 1.second * min) &&
+            assertTrue(duration <= 1.second * max)
+          }
+        }
+      }
     }
   )
 }