Skip to content

Commit 78e1e42

Browse files
committed
Merge remote-tracking branch 'refs/remotes/origin/master'
2 parents 49786af + 08bcf60 commit 78e1e42

156 files changed

Lines changed: 9723 additions & 819 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CONTRIBUTING.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,29 @@ In order to protect both you and ourselves, you will need to sign the
1313
[Contributor License Agreement](https://easycla.lfx.linuxfoundation.org/). When
1414
you make a PR, a CLA bot will provide a link for the process.
1515

16+
## Generative AI Policy
17+
18+
AI tools have the ability to produce more code than is possible for the gRPC
19+
team to read, understand, review, and accept into the repository. For this
20+
reason, we request that all contributions adhere to the following rules:
21+
22+
1. **No AI-Generated Interactions:** All communication in the repo must be
23+
authored by a human. _Exception: AIs may be used for directed writing
24+
assistance or translation._ Absolutely no automated agents are allowed to
25+
directly publish to GitHub.
26+
27+
2. **Author Ownership and Accountability:** Code contributions are expected to
28+
be fully owned and understood by the human contributor. If the code was
29+
produced by generative AI, the author is expected to have reviewed and
30+
understood it in its entirety before submitting it for review. This includes
31+
all content: production code, tests, examples, tools, etc.
32+
33+
In addition to the above requirements, any AI-assisted contributions must also
34+
comply with the [Linux Foundation Generative AI
35+
Policy](https://www.linuxfoundation.org/legal/generative-ai). This includes
36+
confirming that all contributions are legally allowed to be contributed to the
37+
gRPC project under the applicable license terms.
38+
1639
## Compiling
1740

1841
See [COMPILING.md](COMPILING.md). Specifically, you'll generally want to set

‎MODULE.bazel‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
module(
22
name = "grpc-java",
3-
version = "1.85.0-SNAPSHOT", # CURRENT_GRPC_VERSION
3+
version = "1.86.0-SNAPSHOT", # CURRENT_GRPC_VERSION
44
repo_name = "io_grpc_grpc_java",
55
)
66

‎api/src/main/java/io/grpc/ClientStreamTracer.java‎

Lines changed: 62 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -58,42 +58,45 @@ public void createPendingStream() {
5858
}
5959

6060
/**
61-
* Called when an attempt-level delay segment (such as waiting for a load balancing pick or
62-
* connection establishment) starts.
61+
* Called when an attempt-level delay (such as waiting for a load balancing pick or connection
62+
* establishment) starts, or when the {@code delayType} of the ongoing delay changes, in which
63+
* case {@link #recordDelayEnd} is called for the previous delay first.
6364
*
64-
* <p>This method is invoked synchronously on the attempt thread. Implementations should start
65-
* internal timers or child tracing spans (named strictly {@code "Attempt Delay"}) carrying the
66-
* canonical {@code grpc.delay_type} attribute.
65+
* <p>Implementations should start a timer and open a child tracing span (named strictly
66+
* {@code "Delay"}) carrying the canonical {@code grpc.delay_type} attribute.
6767
*
6868
* @param delayType canonical low-cardinality label categorizing the delay (e.g., "connecting")
6969
* @param delayReason high-cardinality diagnostic string describing granular runtime conditions
70-
* @since 1.82.0
70+
* @since 1.86.0
7171
*/
72-
public void recordAttemptDelayStart(String delayType, String delayReason) {
72+
public void recordDelayStart(String delayType, String delayReason) {
7373
}
7474

7575
/**
76-
* Called when an attempt-level delay reason changes while the overall delay type remains
77-
* constant (for example, when a priority load balancing policy fails over between tiers).
76+
* Called when an attempt-level delay reason changes while the delay type remains constant (for
77+
* example, when a load balancing policy updates its connection status detail).
7878
*
79-
* <p>Implementations should record structured events (such as {@code "Delay state transition"})
80-
* on the active delay span without recreating the span or resetting cumulative timers.
79+
* <p>Implementations should record a structured event (such as {@code "Delay triggered"}) on
80+
* the active delay span without recreating the span or resetting cumulative timers.
8181
*
82+
* @param delayType canonical low-cardinality label of the ongoing delay
8283
* @param delayReason updated high-cardinality diagnostic string describing new conditions
83-
* @since 1.82.0
84+
* @since 1.86.0
8485
*/
85-
public void recordAttemptDelayReasonChanged(String delayReason) {
86+
public void recordDelayReasonChanged(String delayType, String delayReason) {
8687
}
8788

8889
/**
89-
* Called when an attempt-level delay segment ends upon successful pick or stream creation.
90+
* Called when an attempt-level delay ends upon successful pick or stream creation, or when the
91+
* attempt is cancelled or reaches its deadline while still waiting.
9092
*
91-
* <p>Implementations should simultaneously close active child tracing spans and record elapsed
92-
* duration to the {@code grpc.client.attempt.delay.duration} histogram.
93+
* <p>Implementations should close the active child tracing span and record the elapsed duration
94+
* to the {@code grpc.client.attempt.delay.duration} histogram labeled with {@code delayType}.
9395
*
94-
* @since 1.82.0
96+
* @param delayType canonical low-cardinality label of the delay being ended
97+
* @since 1.86.0
9598
*/
96-
public void recordAttemptDelayEnd() {
99+
public void recordDelayEnd(String delayType) {
97100
}
98101

99102
/**
@@ -156,6 +159,47 @@ public abstract static class Factory {
156159
public ClientStreamTracer newClientStreamTracer(StreamInfo info, Metadata headers) {
157160
throw new UnsupportedOperationException("Not implemented");
158161
}
162+
163+
/**
164+
* Called when a call-level delay (such as waiting for name resolution) starts before any
165+
* individual RPC attempt is created, or when the {@code delayType} of the ongoing delay
166+
* changes, in which case {@link #recordDelayEnd} is called for the previous delay first.
167+
*
168+
* <p>Implementations should start a timer and open a child tracing span (named strictly
169+
* {@code "Delay"}) carrying the canonical {@code grpc.delay_type} attribute.
170+
*
171+
* @param delayType canonical low-cardinality label categorizing the delay (e.g., "resolving")
172+
* @param delayReason high-cardinality diagnostic string describing granular runtime conditions
173+
* @since 1.86.0
174+
*/
175+
public void recordDelayStart(String delayType, String delayReason) {
176+
}
177+
178+
/**
179+
* Called when a call-level delay reason changes while the delay type remains constant.
180+
*
181+
* <p>Implementations should record a structured event (such as {@code "Delay triggered"}) on
182+
* the active call delay span without recreating the span or resetting timers.
183+
*
184+
* @param delayType canonical low-cardinality label of the ongoing delay
185+
* @param delayReason updated high-cardinality diagnostic string describing new conditions
186+
* @since 1.86.0
187+
*/
188+
public void recordDelayReasonChanged(String delayType, String delayReason) {
189+
}
190+
191+
/**
192+
* Called when a call-level delay ends upon successful name resolution, or when the RPC is
193+
* cancelled or reaches its deadline before resolution completes.
194+
*
195+
* <p>Implementations should close the active call delay span and record the elapsed duration
196+
* to the {@code grpc.client.call.delay.duration} histogram labeled with {@code delayType}.
197+
*
198+
* @param delayType canonical low-cardinality label of the delay being ended
199+
* @since 1.86.0
200+
*/
201+
public void recordDelayEnd(String delayType) {
202+
}
159203
}
160204

161205
/**

‎api/src/main/java/io/grpc/Contexts.java‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,16 @@ public void onReady() {
118118
context.detach(previous);
119119
}
120120
}
121+
122+
@Override
123+
public void onEvent(Object event) {
124+
Context previous = context.attach();
125+
try {
126+
super.onEvent(event);
127+
} finally {
128+
context.detach(previous);
129+
}
130+
}
121131
}
122132

123133
/**

‎api/src/main/java/io/grpc/EquivalentAddressGroup.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,12 @@ public final class EquivalentAddressGroup {
6969
@Attr
7070
static final Attributes.Key<Long> ATTR_WEIGHT =
7171
Attributes.Key.create("io.grpc.EquivalentAddressGroup.ATTR_WEIGHT");
72+
/**
73+
* Name associated with individual address, if available (e.g., DNS name).
74+
*/
75+
@Attr
76+
static final Attributes.Key<String> ATTR_ADDRESS_NAME =
77+
Attributes.Key.create("io.grpc.EquivalentAddressGroup.ATTR_ADDRESS_NAME");
7278

7379
private final List<SocketAddress> addrs;
7480
private final Attributes attrs;

‎api/src/main/java/io/grpc/InternalEquivalentAddressGroup.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,4 +32,10 @@ private InternalEquivalentAddressGroup() {}
3232
*/
3333
public static final Attributes.Key<String> ATTR_BACKEND_SERVICE =
3434
EquivalentAddressGroup.ATTR_BACKEND_SERVICE;
35+
36+
/**
37+
* Name associated with individual address, if available (e.g., DNS name).
38+
*/
39+
public static final Attributes.Key<String> ATTR_ADDRESS_NAME =
40+
EquivalentAddressGroup.ATTR_ADDRESS_NAME;
3541
}

‎api/src/main/java/io/grpc/LoadBalancer.java‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -739,21 +739,29 @@ public static PickResult withNoResult() {
739739
*
740740
* @param delayType low-cardinality root cause label (e.g., "connecting")
741741
* @param delayReason high-cardinality diagnostic string for trace events
742-
* @since 1.82.0
742+
* @since 1.86.0
743743
*/
744744
public static PickResult withNoResult(String delayType, String delayReason) {
745745
Preconditions.checkNotNull(delayType, "delayType");
746746
Preconditions.checkNotNull(delayReason, "delayReason");
747747
return new PickResult(null, null, Status.OK, false, null, delayType, delayReason);
748748
}
749749

750-
/** Returns the delay type label if any. */
750+
/**
751+
* Returns the delay type label if any.
752+
*
753+
* @since 1.86.0
754+
*/
751755
@Nullable
752756
public String getDelayType() {
753757
return delayType;
754758
}
755759

756-
/** Returns the diagnostic delay reason if any. */
760+
/**
761+
* Returns the diagnostic delay reason if any.
762+
*
763+
* @since 1.86.0
764+
*/
757765
@Nullable
758766
public String getDelayReason() {
759767
return delayReason;

‎api/src/main/java/io/grpc/PartialForwardingServerCall.java‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,11 @@ public SecurityLevel getSecurityLevel() {
8787
return delegate().getSecurityLevel();
8888
}
8989

90+
@Override
91+
public void triggerEvent(Object event) {
92+
delegate().triggerEvent(event);
93+
}
94+
9095
@Override
9196
public String toString() {
9297
return MoreObjects.toStringHelper(this).add("delegate", delegate()).toString();

‎api/src/main/java/io/grpc/PartialForwardingServerCallListener.java‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,11 @@ public void onReady() {
5050
delegate().onReady();
5151
}
5252

53+
@Override
54+
public void onEvent(Object event) {
55+
delegate().onEvent(event);
56+
}
57+
5358
@Override
5459
public String toString() {
5560
return MoreObjects.toStringHelper(this).add("delegate", delegate()).toString();

‎api/src/main/java/io/grpc/ServerCall.java‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,28 @@ public void onComplete() {}
100100
* <em>another</em> {@code onReady()} callback.
101101
*/
102102
public void onReady() {}
103+
104+
/**
105+
* A custom event has been triggered by the call.
106+
*
107+
* <p>This callback is guaranteed to run on the call's executor, serialized with other
108+
* callbacks (like {@link #onMessage}, {@link #onHalfClose}). This means the implementation
109+
* does not need internal synchronization to access call-specific state.
110+
*
111+
* <p><strong>Deadlock avoidance:</strong> In some transports (such as Binder transport)
112+
* or when using a direct executor, this callback may be invoked while transport-level
113+
* locks are held. Implementations should avoid acquiring locks that are held by callers of
114+
* {@link ServerCall} methods (such as {@link ServerCall#triggerEvent},
115+
* {@link ServerCall#close}, or {@link ServerCall#request}), and should avoid calling
116+
* {@link ServerCall} methods while holding application-level locks, as this can lead to
117+
* deadlocks from lock-order inversion.
118+
*
119+
* @param event the triggered event.
120+
*/
121+
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/12979")
122+
public void onEvent(Object event) {
123+
// Default no-op
124+
}
103125
}
104126

105127
/**
@@ -262,6 +284,31 @@ public String getAuthority() {
262284
return null;
263285
}
264286

287+
/**
288+
* Triggers a custom event to be processed by the listener.
289+
* The event will be delivered to {@link Listener#onEvent(Object)} on the call's executor.
290+
*
291+
* <p>This method is safe to call from multiple threads without external synchronization. No
292+
* events will be delivered after the RPC is cancelled or completed.
293+
*
294+
* <p><strong>Deadlock avoidance:</strong> Callers should avoid holding application-level or
295+
* interceptor locks when calling this method. Depending on the transport and executor
296+
* configuration (such as {@code directExecutor()} or transports like Binder),
297+
* {@code triggerEvent} may acquire transport-level locks and may dispatch
298+
* {@link Listener#onEvent(Object)} synchronously on the calling thread.
299+
* If the caller holds an application lock while calling {@code triggerEvent}, and
300+
* {@code onEvent} or a concurrent transport operation (such as {@link #close} or
301+
* {@link #request}) attempts to acquire that same lock, a deadlock can occur from
302+
* lock-order inversion. Applications should mutate internal state under lock, release
303+
* the lock, and only then invoke {@code triggerEvent}.
304+
*
305+
* @param event the event to trigger.
306+
*/
307+
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/12979")
308+
public void triggerEvent(Object event) {
309+
// Default no-op
310+
}
311+
265312
/**
266313
* The {@link MethodDescriptor} for the call.
267314
*/

0 commit comments

Comments
 (0)