Fix public APIs for kotlin.time.Duration (#8355)

* Fix public APIs for kotlin.time.Duration

Use this as our preferred API for accepting a duration in
OkHttpClient and CacheControl.

Also hide these functions from the Java API.

* Code review feedback

* Spotless

* apiDump

Author: swankjesse

okhttp/api/okhttp.api

@@ -130,11 +130,11 @@ public final class okhttp3/CacheControl$Builder {
 	public final fun build ()Lokhttp3/CacheControl;
 	public final fun immutable ()Lokhttp3/CacheControl$Builder;
 	public final fun maxAge (ILjava/util/concurrent/TimeUnit;)Lokhttp3/CacheControl$Builder;
-	public final fun maxAge (ILkotlin/time/DurationUnit;)Lokhttp3/CacheControl$Builder;
+	public final fun maxAge-LRDsOJo (J)Lokhttp3/CacheControl$Builder;
 	public final fun maxStale (ILjava/util/concurrent/TimeUnit;)Lokhttp3/CacheControl$Builder;
-	public final fun maxStale (ILkotlin/time/DurationUnit;)Lokhttp3/CacheControl$Builder;
+	public final fun maxStale-LRDsOJo (J)Lokhttp3/CacheControl$Builder;
 	public final fun minFresh (ILjava/util/concurrent/TimeUnit;)Lokhttp3/CacheControl$Builder;
-	public final fun minFresh (ILkotlin/time/DurationUnit;)Lokhttp3/CacheControl$Builder;
+	public final fun minFresh-LRDsOJo (J)Lokhttp3/CacheControl$Builder;
 	public final fun noCache ()Lokhttp3/CacheControl$Builder;
 	public final fun noStore ()Lokhttp3/CacheControl$Builder;
 	public final fun noTransform ()Lokhttp3/CacheControl$Builder;

okhttp/src/main/kotlin/okhttp3/CacheControl.kt

@@ -16,15 +16,12 @@
 package okhttp3
 
 import java.util.concurrent.TimeUnit
-import kotlin.time.DurationUnit
+import kotlin.time.Duration
 import okhttp3.internal.commonBuild
 import okhttp3.internal.commonClampToInt
 import okhttp3.internal.commonForceCache
 import okhttp3.internal.commonForceNetwork
 import okhttp3.internal.commonImmutable
-import okhttp3.internal.commonMaxAge
-import okhttp3.internal.commonMaxStale
-import okhttp3.internal.commonMinFresh
 import okhttp3.internal.commonNoCache
 import okhttp3.internal.commonNoStore
 import okhttp3.internal.commonNoTransform
@@ -186,26 +183,29 @@ class CacheControl internal constructor(
      * Sets the maximum age of a cached response. If the cache response's age exceeds [maxAge], it
      * will not be used and a network request will be made.
      *
-     * @param maxAge a non-negative integer. This is stored and transmitted with [TimeUnit.SECONDS]
+     * @param maxAge a non-negative duration. This is stored and transmitted with [TimeUnit.SECONDS]
      *     precision; finer precision will be lost.
      */
-    @ExperimentalOkHttpApi
-    fun maxAge(
-      maxAge: Int,
-      timeUnit: DurationUnit,
-    ) = commonMaxAge(maxAge, timeUnit)
+    fun maxAge(maxAge: Duration) =
+      apply {
+        val maxAgeSeconds = maxAge.inWholeSeconds
+        require(maxAgeSeconds >= 0) { "maxAge < 0: $maxAgeSeconds" }
+        this.maxAgeSeconds = maxAgeSeconds.commonClampToInt()
+      }
 
-    @ExperimentalOkHttpApi
-    fun maxStale(
-      maxStale: Int,
-      timeUnit: DurationUnit,
-    ) = commonMaxStale(maxStale, timeUnit)
+    fun maxStale(maxStale: Duration) =
+      apply {
+        val maxStaleSeconds = maxStale.inWholeSeconds
+        require(maxStaleSeconds >= 0) { "maxStale < 0: $maxStaleSeconds" }
+        this.maxStaleSeconds = maxStaleSeconds.commonClampToInt()
+      }
 
-    @ExperimentalOkHttpApi
-    fun minFresh(
-      minFresh: Int,
-      timeUnit: DurationUnit,
-    ) = commonMinFresh(minFresh, timeUnit)
+    fun minFresh(minFresh: Duration) =
+      apply {
+        val minFreshSeconds = minFresh.inWholeSeconds
+        require(minFreshSeconds >= 0) { "minFresh < 0: $minFreshSeconds" }
+        this.minFreshSeconds = minFreshSeconds.commonClampToInt()
+      }
 
     /**
      * Sets the maximum age of a cached response. If the cache response's age exceeds [maxAge], it

okhttp/src/main/kotlin/okhttp3/internal/-CacheControlCommon.kt

@@ -17,8 +17,7 @@
 
 package okhttp3.internal
 
-import kotlin.time.DurationUnit
-import kotlin.time.toDuration
+import kotlin.time.Duration.Companion.seconds
 import okhttp3.CacheControl
 import okhttp3.Headers
 
@@ -47,33 +46,6 @@ internal fun CacheControl.commonToString(): String {
   return result
 }
 
-internal fun CacheControl.Builder.commonMaxAge(
-  maxAge: Int,
-  timeUnit: DurationUnit,
-) = apply {
-  require(maxAge >= 0) { "maxAge < 0: $maxAge" }
-  val maxAgeSecondsLong = maxAge.toDuration(timeUnit).inWholeSeconds
-  this.maxAgeSeconds = maxAgeSecondsLong.commonClampToInt()
-}
-
-internal fun CacheControl.Builder.commonMaxStale(
-  maxStale: Int,
-  timeUnit: DurationUnit,
-) = apply {
-  require(maxStale >= 0) { "maxStale < 0: $maxStale" }
-  val maxStaleSecondsLong = maxStale.toDuration(timeUnit).inWholeSeconds
-  this.maxStaleSeconds = maxStaleSecondsLong.commonClampToInt()
-}
-
-internal fun CacheControl.Builder.commonMinFresh(
-  minFresh: Int,
-  timeUnit: DurationUnit,
-) = apply {
-  require(minFresh >= 0) { "minFresh < 0: $minFresh" }
-  val minFreshSecondsLong = minFresh.toDuration(timeUnit).inWholeSeconds
-  this.minFreshSeconds = minFreshSecondsLong.commonClampToInt()
-}
-
 internal fun Long.commonClampToInt(): Int {
   return when {
     this > Int.MAX_VALUE -> Int.MAX_VALUE
@@ -89,7 +61,7 @@ internal fun CacheControl.Companion.commonForceNetwork() =
 internal fun CacheControl.Companion.commonForceCache() =
   CacheControl.Builder()
     .onlyIfCached()
-    .maxStale(Int.MAX_VALUE, DurationUnit.SECONDS)
+    .maxStale(Int.MAX_VALUE.seconds)
     .build()
 
 internal fun CacheControl.Builder.commonBuild(): CacheControl {

okhttp/src/test/java/okhttp3/CacheControlTest.kt

@@ -20,7 +20,7 @@ import assertk.assertions.isEqualTo
 import assertk.assertions.isFalse
 import assertk.assertions.isTrue
 import kotlin.test.Test
-import kotlin.time.DurationUnit
+import kotlin.time.Duration.Companion.seconds
 
 class CacheControlTest {
   @Test
@@ -48,9 +48,9 @@ class CacheControlTest {
       CacheControl.Builder()
         .noCache()
         .noStore()
-        .maxAge(1, DurationUnit.SECONDS)
-        .maxStale(2, DurationUnit.SECONDS)
-        .minFresh(3, DurationUnit.SECONDS)
+        .maxAge(1.seconds)
+        .maxStale(2.seconds)
+        .minFresh(3.seconds)
         .onlyIfCached()
         .noTransform()
         .immutable()