@@ -25,8 +25,104 @@ message PingResponse {
2525 string hostname = 4 ;
2626}
2727
28- // SubmitQueueSpeculator provides the speculator API
28+ // SpeculationRequest is the request for speculating the outcome of a batch (new request)
29+ message SpeculationRequest {
30+ // ID of the batch being speculated
31+ string batch_id = 1 ;
32+ // List of batch IDs that the current batch depends on
33+ repeated string dependencies = 2 ;
34+ }
35+
36+ // SpeculationResponse is the response for the SpeculationRequest, providing speculation results for the batch,
37+ // including possible speculation paths and their associated scores and recommended actions
38+ message SpeculationResponse {
39+ repeated SpeculationPathResult results = 1 ;
40+ }
41+
42+ // SpeculationSignalRequest is the request for sending a speculation signal for a batch in a speculation path,
43+ // providing information about the speculation path and the signal being sent, such as whether a build has succeeded,
44+ // failed, or been cancelled for the batch in this speculation path
45+ message SpeculationSignalRequest {
46+ // path is the speculation path for which the speculation signal is being sent, represented as a list of
47+ // batch IDs that have been triggered as part of this speculation path leading up to the current
48+ SpeculationPath path = 1 ;
49+ // signal is the speculation signal being sent for the batch in this speculation path, such as whether a
50+ // build has succeeded, failed, or been cancelled for the batch in this speculation path
51+ SpeculationSignal signal = 2 ;
52+ }
53+
54+ // SpeculationSignalResponse is the response for the SpeculationSignalRequest,
55+ // providing updated speculation results for the batch based on the received signal,
56+ // including possible speculation paths and their associated scores and recommended actions
57+ message SpeculationSignalResponse {
58+ repeated SpeculationPathResult results = 1 ;
59+ }
60+
61+ // SpeculationSignal represents the signal being sent for a batch in a speculation path, such as whether a build has
62+ // succeeded, failed, or been cancelled for the batch in this speculation path, or whether the batch has been
63+ // finalized (landed) or failed to finalize (failed to land)
64+ enum SpeculationSignal {
65+ SPECULATION_SIGNAL_UNSPECIFIED = 0 ;
66+ // Signal indicating that a build has been triggered for the batch in this speculation path
67+ SPECULATION_SIGNAL_BUILD_SUCCEEDED = 1 ;
68+ // Signal indicating that a build has been cancelled for the batch in this speculation path
69+ SPECULATION_SIGNAL_BUILD_CANCELLED = 2 ;
70+ // Signal indicating that a build has failed for the batch in this speculation path
71+ SPECULATION_SIGNAL_BUILD_FAILED = 3 ;
72+ // Signal indicating that the batch in this speculation path has been finalized, meaning it has been landed
73+ SPECULATION_SIGNAL_FINALIZE_SUCCEEDED = 4 ;
74+ // Signal indicating that the batch in this speculation path has failed to finalize, meaning it failed to land
75+ SPECULATION_SIGNAL_FINALIZE_FAILED = 5 ;
76+ }
77+
78+ // SpeculationAction represents the recommended action to take for a given speculation path,
79+ // such as whether to trigger a build, cancel it, or finalize it
80+ enum SpeculationAction {
81+ SPECULATION_ACTION_UNSPECIFIED = 0 ;
82+ // Trigger a build for the batch in this speculation path
83+ SPECULATION_ACTION_BUILD = 1 ;
84+ // Cancel the build for the batch in this speculation path, if it was previously triggered
85+ SPECULATION_ACTION_CANCEL = 2 ;
86+ // Finalize the batch in this speculation path, meaning land them
87+ SPECULATION_ACTION_FINALIZE = 3 ;
88+ }
89+
90+ // SpeculationPath represents a possible speculation path for a batch, including the batch ID and a list of batch IDs
91+ // representing a possible sequence of batches that could be triggered as a result of the current batch,it's dependencies
92+ message SpeculationPath {
93+ // batch_id is the ID of the batch for which this speculation path is being provided
94+ string batch_id = 1 ;
95+ // batch_ids is a list of batch IDs representing a possible sequence of batches that could be triggered as a result
96+ // of the current batch, based on the dependencies and historical data
97+ repeated string batch_ids = 2 ;
98+ }
99+
100+ // SpeculationPathResult represents the speculation result for a given speculation path, including the speculation path,
101+ // a score representing the likelihood of needing this path for build, and a recommended action to take for this path
102+ // based on the speculation results, such as whether to trigger a build, cancel it, or finalize it
103+ message SpeculationPathResult {
104+ // path is the speculation path for which the speculation result is being provided, represented as a list of
105+ // batch IDs that have been triggered as part of this speculation path leading up
106+ SpeculationPath path = 1 ;
107+ // score is a numerical value representing the likelihood of needing this path for build
108+ // 0.0 >= score <= 1.0, where a higher score indicates a higher likelihood of needing this path for build
109+ float score = 2 ;
110+ // action is the recommended action to take for this path based on the speculation results, s
111+ // uch as whether to trigger a build, cancel it, or finalize it
112+ SpeculationAction action = 3 ;
113+ }
114+
115+ // SubmitQueueSpeculator service provides APIs for speculating, signaling, and receiving speculation results for batches
116+ // in the submit queue, allowing clients to make informed decisions about which batches to trigger builds for, cancel,
117+ // or finalize based on the speculation results and signals received for different speculation paths
29118service SubmitQueueSpeculator {
30119 // Ping returns a response indicating the service is alive
31120 rpc Ping (PingRequest ) returns (PingResponse ) {}
121+ // Speculate takes a SpeculationRequest containing information about a batch and its dependencies
122+ // and returns a SpeculationResponse
123+ rpc Speculate (SpeculationRequest ) returns (SpeculationResponse ) {}
124+ // Signal takes a SpeculationSignalRequest containing a speculation path and a speculation signal for that path,
125+ // and returns a SpeculationSignalResponse containing updated speculation results for the batch based on the
126+ // received signal
127+ rpc Signal (SpeculationSignalRequest ) returns (SpeculationSignalResponse ) {}
32128}
0 commit comments