Skip to content

Commit 0470853

Browse files
swankjesseswankjesse
authored
Add tags to calls, including computable tags (#9168)
Originally I was planning on implementing tags on Request only, but that design broke as soon as any interceptor used Request.newBuilder() to create a copy of the Request - the instance that received the tags might not be the instance that needed them. Instead I'm introducing this behavior on the Call object, which behaves less like a value. I expect that users' expected lifetimes of tags will work naturally this way. It is an API hazard that we have tags on both Requests and Calls. Perhaps if given the opportunity to do it over, I'd omit support for tags on Requests. Co-authored-by: Jesse Wilson <jwilson@squareup.com>
1 parent 2b70b39 commit 0470853

8 files changed

Lines changed: 271 additions & 0 deletions

File tree

‎okhttp-testing-support/src/main/kotlin/okhttp3/FailingCall.kt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
*/
1616
package okhttp3
1717

18+
import kotlin.reflect.KClass
1819
import okio.Timeout
1920

2021
open class FailingCall : Call {
@@ -32,5 +33,19 @@ open class FailingCall : Call {
3233

3334
override fun timeout(): Timeout = error("unexpected")
3435

36+
override fun <T : Any> tag(type: KClass<T>): T? = error("unexpected")
37+
38+
override fun <T> tag(type: Class<out T>): T? = error("unexpected")
39+
40+
override fun <T : Any> tag(
41+
type: KClass<T>,
42+
computeIfAbsent: () -> T,
43+
): T = error("unexpected")
44+
45+
override fun <T : Any> tag(
46+
type: Class<T>,
47+
computeIfAbsent: () -> T,
48+
): T = error("unexpected")
49+
3550
override fun clone(): Call = error("unexpected")
3651
}

‎okhttp/api/android/okhttp.api‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,10 @@ public abstract interface class okhttp3/Call : java/lang/Cloneable {
126126
public abstract fun isCanceled ()Z
127127
public abstract fun isExecuted ()Z
128128
public abstract fun request ()Lokhttp3/Request;
129+
public abstract fun tag (Ljava/lang/Class;)Ljava/lang/Object;
130+
public abstract fun tag (Ljava/lang/Class;Lkotlin/jvm/functions/Function0;)Ljava/lang/Object;
131+
public abstract fun tag (Lkotlin/reflect/KClass;)Ljava/lang/Object;
132+
public abstract fun tag (Lkotlin/reflect/KClass;Lkotlin/jvm/functions/Function0;)Ljava/lang/Object;
129133
public abstract fun timeout ()Lokio/Timeout;
130134
}
131135

‎okhttp/api/jvm/okhttp.api‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,10 @@ public abstract interface class okhttp3/Call : java/lang/Cloneable {
126126
public abstract fun isCanceled ()Z
127127
public abstract fun isExecuted ()Z
128128
public abstract fun request ()Lokhttp3/Request;
129+
public abstract fun tag (Ljava/lang/Class;)Ljava/lang/Object;
130+
public abstract fun tag (Ljava/lang/Class;Lkotlin/jvm/functions/Function0;)Ljava/lang/Object;
131+
public abstract fun tag (Lkotlin/reflect/KClass;)Ljava/lang/Object;
132+
public abstract fun tag (Lkotlin/reflect/KClass;Lkotlin/jvm/functions/Function0;)Ljava/lang/Object;
129133
public abstract fun timeout ()Lokio/Timeout;
130134
}
131135

‎okhttp/src/commonJvmAndroid/kotlin/okhttp3/Call.kt‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
*/
1616
package okhttp3
1717

18+
import kotlin.reflect.KClass
1819
import okio.IOException
1920
import okio.Timeout
2021

@@ -87,9 +88,79 @@ interface Call : Cloneable {
8788
*/
8889
fun timeout(): Timeout
8990

91+
/**
92+
* Returns the tag attached with [type] as a key, or null if no tag is attached with that key.
93+
*
94+
* The tags on a call are seeded from the [request tags][Request.tag]. This set will grow if new
95+
* tags are computed.
96+
*/
97+
fun <T : Any> tag(type: KClass<T>): T?
98+
99+
/**
100+
* Returns the tag attached with [type] as a key, or null if no tag is attached with that key.
101+
*
102+
* The tags on a call are seeded from the [request tags][Request.tag]. This set will grow if new
103+
* tags are computed.
104+
*/
105+
fun <T> tag(type: Class<out T>): T?
106+
107+
/**
108+
* Returns the tag attached with [type] as a key. If it is absent, then [computeIfAbsent] is
109+
* called and that value is both inserted and returned.
110+
*
111+
* If multiple calls to this function are made concurrently with the same [type], multiple values
112+
* may be computed. But only one value will be inserted, and that inserted value will be returned
113+
* to all callers.
114+
*
115+
* If computing multiple values is problematic, use an appropriate concurrency mechanism in your
116+
* [computeIfAbsent] implementation. No locks are held while calling this function.
117+
*/
118+
fun <T : Any> tag(
119+
type: KClass<T>,
120+
computeIfAbsent: () -> T,
121+
): T
122+
123+
/**
124+
* Returns the tag attached with [type] as a key. If it is absent, then [computeIfAbsent] is
125+
* called and that value is both inserted and returned.
126+
*
127+
* If multiple calls to this function are made concurrently with the same [type], multiple values
128+
* may be computed. But only one value will be inserted, and that inserted value will be returned
129+
* to all callers.
130+
*
131+
* If computing multiple values is problematic, use an appropriate concurrency mechanism in your
132+
* [computeIfAbsent] implementation. No locks are held while calling this function.
133+
*/
134+
fun <T : Any> tag(
135+
type: Class<T>,
136+
computeIfAbsent: () -> T,
137+
): T
138+
90139
/**
91140
* Create a new, identical call to this one which can be enqueued or executed even if this call
92141
* has already been.
142+
*
143+
* The tags on the returned call will equal the tags as on [request]. Any tags that were computed
144+
* for this call will not be included on the cloned call. If necessary you may manually copy over
145+
* specific tags by re-computing them:
146+
*
147+
* ```kotlin
148+
* val copy = original.clone()
149+
*
150+
* val myTag = original.tag(MyTag::class)
151+
* if (myTag != null) {
152+
* copy.tag(MyTag::class) { myTag }
153+
* }
154+
* ```
155+
*
156+
* ```java
157+
* Call copy = original.clone();
158+
*
159+
* MyTag myTag = original.tag(MyTag.class);
160+
* if (myTag != null) {
161+
* copy.tag(MyTag.class, () -> myTag);
162+
* }
163+
* ```
93164
*/
94165
public override fun clone(): Call
95166

‎okhttp/src/commonJvmAndroid/kotlin/okhttp3/internal/connection/RealCall.kt‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ import java.util.concurrent.RejectedExecutionException
2525
import java.util.concurrent.TimeUnit.MILLISECONDS
2626
import java.util.concurrent.atomic.AtomicBoolean
2727
import java.util.concurrent.atomic.AtomicInteger
28+
import java.util.concurrent.atomic.AtomicReference
29+
import kotlin.reflect.KClass
2830
import okhttp3.Call
2931
import okhttp3.Callback
3032
import okhttp3.EventListener
@@ -35,6 +37,7 @@ import okhttp3.Response
3537
import okhttp3.internal.assertLockNotHeld
3638
import okhttp3.internal.cache.CacheInterceptor
3739
import okhttp3.internal.closeQuietly
40+
import okhttp3.internal.computeIfAbsent
3841
import okhttp3.internal.concurrent.Lockable
3942
import okhttp3.internal.concurrent.assertLockHeld
4043
import okhttp3.internal.concurrent.assertLockNotHeld
@@ -120,8 +123,24 @@ class RealCall(
120123
@Volatile private var exchange: Exchange? = null
121124
internal val plansToCancel = CopyOnWriteArrayList<RoutePlanner.Plan>()
122125

126+
private val tags = AtomicReference(originalRequest.tags)
127+
123128
override fun timeout(): Timeout = timeout
124129

130+
override fun <T : Any> tag(type: KClass<T>): T? = type.java.cast(tags.get()[type])
131+
132+
override fun <T> tag(type: Class<out T>): T? = tag(type.kotlin)
133+
134+
override fun <T : Any> tag(
135+
type: KClass<T>,
136+
computeIfAbsent: () -> T,
137+
): T = tags.computeIfAbsent(type, computeIfAbsent)
138+
139+
override fun <T : Any> tag(
140+
type: Class<T>,
141+
computeIfAbsent: () -> T,
142+
): T = tags.computeIfAbsent(type.kotlin, computeIfAbsent)
143+
125144
@SuppressWarnings("CloneDoesntCallSuperClone") // We are a final type & this saves clearing state.
126145
override fun clone(): Call = RealCall(client, originalRequest, forWebSocket)
127146

‎okhttp/src/jvmTest/java/okhttp3/CallJavaTest.java‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
/*
2+
* Copyright (C) 2025 Square, Inc.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package okhttp3;
17+
18+
import org.junit.jupiter.api.Test;
19+
import org.junit.jupiter.api.extension.RegisterExtension;
20+
import static org.junit.jupiter.api.Assertions.assertEquals;
21+
22+
public class CallJavaTest {
23+
@RegisterExtension
24+
OkHttpClientTestRule clientTestRule = new OkHttpClientTestRule();
25+
26+
private OkHttpClient client = clientTestRule.newClient();
27+
28+
@Test
29+
public void tagsSeededFromRequest() {
30+
Request request = new Request.Builder()
31+
.url(HttpUrl.get("https://square.com/"))
32+
.tag(Integer.class, 5)
33+
.tag(String.class, "hello")
34+
.build();
35+
Call call = client.newCall(request);
36+
37+
assertEquals(5, call.tag(Integer.class));
38+
assertEquals("hello", call.tag(String.class));
39+
assertEquals(null, call.tag(Boolean.class));
40+
assertEquals(null, call.tag(Object.class));
41+
}
42+
43+
@Test
44+
public void tagsCanBeComputed() {
45+
Request request = new Request.Builder()
46+
.url(HttpUrl.get("https://square.com/"))
47+
.build();
48+
Call call = client.newCall(request);
49+
50+
assertEquals("a", call.tag(String.class, () -> "a"));
51+
assertEquals("a", call.tag(String.class, () -> "b"));
52+
}
53+
}

‎okhttp/src/jvmTest/kotlin/okhttp3/CallTagsTest.kt‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
/*
2+
* Copyright (C) 2025 Square, Inc.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
package okhttp3
17+
18+
import assertk.assertThat
19+
import assertk.assertions.isEqualTo
20+
import assertk.assertions.isNull
21+
import okhttp3.HttpUrl.Companion.toHttpUrl
22+
import org.junit.jupiter.api.Test
23+
import org.junit.jupiter.api.extension.RegisterExtension
24+
25+
class CallTagsTest {
26+
@JvmField @RegisterExtension
27+
val clientTestRule = OkHttpClientTestRule()
28+
29+
private var client = clientTestRule.newClient()
30+
31+
@Test
32+
fun tagsSeededFromRequest() {
33+
val request =
34+
Request
35+
.Builder()
36+
.url("https://square.com/".toHttpUrl())
37+
.tag(Integer::class, 5 as Integer)
38+
.tag(String::class, "hello")
39+
.build()
40+
val call = client.newCall(request)
41+
42+
// Check the Kotlin-focused APIs.
43+
assertThat(call.tag(String::class)).isEqualTo("hello")
44+
assertThat(call.tag(Integer::class)).isEqualTo(5)
45+
assertThat(call.tag(Boolean::class)).isNull()
46+
assertThat(call.tag(Any::class)).isNull()
47+
48+
// Check the Java APIs too.
49+
assertThat(call.tag(String::class.java)).isEqualTo("hello")
50+
assertThat(call.tag(Integer::class.java)).isEqualTo(5)
51+
assertThat(call.tag(Boolean::class.java)).isNull()
52+
assertThat(call.tag(Any::class.java)).isNull()
53+
}
54+
55+
@Test
56+
fun tagsCanBeComputed() {
57+
val request =
58+
Request
59+
.Builder()
60+
.url("https://square.com")
61+
.build()
62+
val call = client.newCall(request)
63+
64+
// Check the Kotlin-focused APIs.
65+
assertThat(call.tag(String::class) { "a" }).isEqualTo("a")
66+
assertThat(call.tag(String::class) { "b" }).isEqualTo("a")
67+
assertThat(call.tag(String::class)).isEqualTo("a")
68+
69+
// Check the Java-focused APIs.
70+
assertThat(call.tag(Integer::class) { 1 as Integer }).isEqualTo(1)
71+
assertThat(call.tag(Integer::class) { 2 as Integer }).isEqualTo(1)
72+
assertThat(call.tag(Integer::class)).isEqualTo(1)
73+
}
74+
75+
@Test
76+
fun computedTagsAreNotRetainedInClone() {
77+
val request =
78+
Request
79+
.Builder()
80+
.url("https://square.com")
81+
.build()
82+
val callA = client.newCall(request)
83+
assertThat(callA.tag(String::class) { "a" }).isEqualTo("a")
84+
assertThat(callA.tag(String::class) { "b" }).isEqualTo("a")
85+
86+
val callB = callA.clone()
87+
assertThat(callB.tag(String::class) { "c" }).isEqualTo("c")
88+
assertThat(callB.tag(String::class) { "d" }).isEqualTo("c")
89+
}
90+
}

‎okhttp/src/jvmTest/kotlin/okhttp3/KotlinSourceModernTest.kt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ import javax.net.ssl.SSLSocket
4646
import javax.net.ssl.SSLSocketFactory
4747
import javax.net.ssl.X509KeyManager
4848
import javax.net.ssl.X509TrustManager
49+
import kotlin.reflect.KClass
4950
import okhttp3.Handshake.Companion.handshake
5051
import okhttp3.Headers.Companion.headersOf
5152
import okhttp3.Headers.Companion.toHeaders
@@ -201,6 +202,20 @@ class KotlinSourceModernTest {
201202

202203
override fun timeout(): Timeout = TODO()
203204

205+
override fun <T : Any> tag(type: KClass<T>): T? = TODO()
206+
207+
override fun <T> tag(type: Class<out T>): T? = TODO()
208+
209+
override fun <T : Any> tag(
210+
type: KClass<T>,
211+
computeIfAbsent: () -> T,
212+
): T = TODO()
213+
214+
override fun <T : Any> tag(
215+
type: Class<T>,
216+
computeIfAbsent: () -> T,
217+
): T = TODO()
218+
204219
override fun clone(): Call = TODO()
205220
}
206221
}

0 commit comments

Comments
 (0)