1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
// Copyright 2016 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// This file contains the protocol used to communicate between the Bazel client
// and the server. At a high level clients may call the CommandServer.run rpc
// to initiates a Bazel command and CommandServer.cancel to cancel an in-flight
// command. CommandServer.ping may be used to check for server liveness without
// executing any commands. See documentation of individual messages for more
// details.
syntax = "proto3";
package command_server;
option java_package = "com.google.devtools.build.lib.server";
option java_outer_classname = "CommandProtos";
// Passed to CommandServer.run to initiate execution of a Bazel command.
message RunRequest {
// Request cookie from the output base of the server. This serves as a
// rudimentary form of mutual authentication.
string cookie = 1;
// Command and command arguments. Does not include startup arguments.
repeated bytes arg = 2;
// Tells the server whether or not the client is willing to wait for any
// concurrent in-flight request to complete (there are many commands which
// may not run concurrently). If false and there are in-flight requests then
// the server will return an error immediately.
bool block_for_lock = 3;
// A simple description of the client for reporting purposes. This value is
// required.
string client_description = 4;
// Invocation policy affects how command arguments are interpreted and should
// be passed separately. This is a proto message, either a human readable
// String or base64-encoded binary-serialized version of the message. It is
// not typed directly as an InvocationPolicy message due to distinctions
// between batch and server mode, so the parsing logic is only in the Java
// code.
string invocation_policy = 5;
// Startup arguments, in the order they were applied, tagged with where they
// came from. These options have already been parsed and already have had
// their effect. This information should only be used for logging.
repeated StartupOption startup_options = 6;
}
// Contains the a startup option with its source file. Uses bytes to preserve
// the way the user inputted the arguments, like the args in RunRequest.
message StartupOption {
// Startup option in --nullaryflag or --unaryflag=value form.
bytes option = 1;
// Where the option came from, such as an rc file or an empty string for the
// command line.
bytes source = 2;
}
// Contains metadata and result data for a command execution.
message RunResponse {
// Request cookie from the output base of the server. This serves as a
// rudimentary form of mutual authentication. Set on every response.
string cookie = 1;
// Standard out of the command, chunked. May be empty.
bytes standard_output = 2;
// Standard error of the command, chunked. May be empty.
bytes standard_error = 3;
// Whether this is the last message of the stream, signals that exit_code is
// valid.
bool finished = 4;
// The exit code of the command, only valid when finished is set.
int32 exit_code = 5;
// Randomly generated command identifier, this may be used to cancel execution
// of the command by issuing a cancel call. This should be sent to the client
// as soon as possible. This is not required to be set (non-empty) on every
// response.
string command_id = 6;
// Whether the command has shut down the server; if set, the client should
// wait until the server process dies before finishing.
bool termination_expected = 7;
}
// Passed to CommandServer.cancel to initiate graceful cancellation of an
// in-flight command.
message CancelRequest {
// The client request cookie (see RunRequest.cookie).
string cookie = 1;
// The id of the command to cancel.
string command_id = 2;
}
message CancelResponse {
// The server response cookie (see RunResponse.cookie).
string cookie = 1;
}
// Passed to CommandServer.ping to initiate a ping request.
message PingRequest {
// The client request cookie (see RunRequest.cookie).
string cookie = 1;
}
message PingResponse {
// The server response cookie (see RunResponse.cookie).
string cookie = 1;
}
service CommandServer {
// Run a Bazel command. See documentation of argument/return messages for
// details.
rpc Run (RunRequest) returns (stream RunResponse) {}
// Cancel a currently running Bazel command. May return before the run command
// actually terminates.
rpc Cancel (CancelRequest) returns (CancelResponse) {}
// Does not do anything. Used for liveness check.
rpc Ping (PingRequest) returns (PingResponse) {}
}
|
