1// Copyright 2018 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package waterfall; 18 19option java_package = "com.google.waterfall"; 20option java_outer_classname = "WaterfallProto"; 21 22import "google/protobuf/empty.proto"; 23 24message Message { 25 bytes payload = 1; 26} 27 28// Keep this as lean as possible. We only care about the payload during most 29// of the duration of the session. All other fields are only useful during 30// the beginning/end of the transfer 31message Transfer { 32 // Remote path to for push/pull. Remote path lives in the server fs. 33 // There is no need to send local path, since client has this info. 34 string path = 1; 35 36 // A stream of bytes. Encoded as a tarball. 37 bytes payload = 2; 38 39 // status fields. 40 bool success = 3; 41 bytes err = 4; 42} 43 44message Cmd { 45 // Path to the binary to execute. 46 // Path should be absolute. Otherwise behavior is not specified. 47 // use /system/bin/sh -c to run in a shell. 48 // Interactive shell is not supported. 49 string path = 1; 50 51 // Args to pass to the command 52 repeated string args = 2; 53 54 // Directory to execute the command 55 string dir = 3; 56 57 // Whether to pipe stdin to the command 58 bool pipeIn = 4; 59 60 // Environment to use 61 map<string, string> env = 5; 62 63} 64 65message CmdProgress { 66 67 // Command to execute. Only valid for the initial message of the stream. 68 Cmd cmd = 5; 69 70 // the exit code of the command. 71 // Only populated when the gRPC stream is done. 72 // I.e. the last message before the EOF. 73 uint32 exit_code = 1; 74 75 bytes stdout = 2; 76 bytes stderr = 3; 77 bytes stdin = 4; 78} 79 80message ForwardMessage { 81 enum Kind { 82 UNSET = 0; 83 TCP = 1; 84 UDP = 2; 85 UNIX = 3; 86 } 87 88 enum Op { 89 OPEN = 0; 90 FWD = 1; 91 CLOSE = 2; 92 } 93 94 // Kind of connection to start (tcp|udp|unix) 95 Kind kind = 1; 96 Op op = 2; 97 98 // Address to open and redirect payload to. 99 string addr = 3; 100 // Data to be pushed to connection established on addr. 101 bytes payload = 4; 102 // Whether or not to rebind the port. 103 bool rebind = 5; 104} 105 106message VersionMessage { 107 string version = 1; 108} 109 110service Waterfall { 111 // Echo exists solely for test purposes. 112 rpc Echo(stream Message) returns (stream Message); 113 114 // Push file/dir from host to device. 115 rpc Push(stream Transfer) returns (Transfer); 116 117 // Pull file/dir from device to host. 118 rpc Pull(Transfer) returns (stream Transfer); 119 120 // Exec executes cmd in the device and forward stdout and stderr to client 121 // Exec expects a single initial CmdProgress message if stdin is not 122 // being redirected. Otherwise Exec will read std from the stream. 123 rpc Exec(stream CmdProgress) returns (stream CmdProgress); 124 125 // Forward forwards the stream payload to the requested socket 126 rpc Forward(stream ForwardMessage) returns (stream ForwardMessage); 127 128 // Version gets the version of the server. 129 rpc Version(google.protobuf.Empty) returns (VersionMessage); 130} 131 132message ForwardSession { 133 string src = 1; 134 string dst = 2; 135} 136 137message PortForwardRequest { 138 bool rebind = 3; 139 ForwardSession session = 4; 140} 141 142message ForwardedSessions { 143 repeated ForwardSession sessions = 1; 144} 145 146// PortForwarder service runs a port forwarding session via waterfall. 147// It allows start and stop forwarding connections when the waterfall client 148// is unable to mantains any state (e.g. the waterfall adb binary). 149service PortForwarder { 150 rpc ForwardPort(PortForwardRequest) returns (google.protobuf.Empty); 151 rpc Stop(PortForwardRequest) returns (google.protobuf.Empty); 152 rpc StopAll(google.protobuf.Empty) returns (google.protobuf.Empty); 153 rpc List(google.protobuf.Empty) returns (ForwardedSessions); 154} 155