1*61c4878aSAndroid Build Coastguard Worker// Copyright 2022 The Pigweed Authors 2*61c4878aSAndroid Build Coastguard Worker// 3*61c4878aSAndroid Build Coastguard Worker// Licensed under the Apache License, Version 2.0 (the "License"); you may not 4*61c4878aSAndroid Build Coastguard Worker// use this file except in compliance with the License. You may obtain a copy of 5*61c4878aSAndroid Build Coastguard Worker// the License at 6*61c4878aSAndroid Build Coastguard Worker// 7*61c4878aSAndroid Build Coastguard Worker// https://www.apache.org/licenses/LICENSE-2.0 8*61c4878aSAndroid Build Coastguard Worker// 9*61c4878aSAndroid Build Coastguard Worker// Unless required by applicable law or agreed to in writing, software 10*61c4878aSAndroid Build Coastguard Worker// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11*61c4878aSAndroid Build Coastguard Worker// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12*61c4878aSAndroid Build Coastguard Worker// License for the specific language governing permissions and limitations under 13*61c4878aSAndroid Build Coastguard Worker// the License. 14*61c4878aSAndroid Build Coastguard Worker 15*61c4878aSAndroid Build Coastguard Workersyntax = "proto3"; 16*61c4878aSAndroid Build Coastguard Worker 17*61c4878aSAndroid Build Coastguard Workerpackage pw.transfer; 18*61c4878aSAndroid Build Coastguard Worker 19*61c4878aSAndroid Build Coastguard Workeroption java_multiple_files = true; 20*61c4878aSAndroid Build Coastguard Workeroption java_package = "dev.pigweed.pw_transfer"; 21*61c4878aSAndroid Build Coastguard Worker 22*61c4878aSAndroid Build Coastguard Worker// The transfer RPC service is used to send data between the client and server. 23*61c4878aSAndroid Build Coastguard Workerservice Transfer { 24*61c4878aSAndroid Build Coastguard Worker // Transfer data from the server to the client; a "download" from the client's 25*61c4878aSAndroid Build Coastguard Worker // perspective. 26*61c4878aSAndroid Build Coastguard Worker rpc Read(stream Chunk) returns (stream Chunk); 27*61c4878aSAndroid Build Coastguard Worker 28*61c4878aSAndroid Build Coastguard Worker // Transfer data from the client to the server; an "upload" from the client's 29*61c4878aSAndroid Build Coastguard Worker // perspective. 30*61c4878aSAndroid Build Coastguard Worker rpc Write(stream Chunk) returns (stream Chunk); 31*61c4878aSAndroid Build Coastguard Worker 32*61c4878aSAndroid Build Coastguard Worker // Query the status of a resource. Can be used for partially completed 33*61c4878aSAndroid Build Coastguard Worker // transfers 34*61c4878aSAndroid Build Coastguard Worker rpc GetResourceStatus(ResourceStatusRequest) returns (ResourceStatus); 35*61c4878aSAndroid Build Coastguard Worker} 36*61c4878aSAndroid Build Coastguard Worker 37*61c4878aSAndroid Build Coastguard Worker// Represents a chunk of data sent by the transfer service. Includes fields for 38*61c4878aSAndroid Build Coastguard Worker// configuring the transfer parameters. 39*61c4878aSAndroid Build Coastguard Worker// 40*61c4878aSAndroid Build Coastguard Worker// Notation: (Read|Write) (→|←) 41*61c4878aSAndroid Build Coastguard Worker// X → Means client sending data to the server. 42*61c4878aSAndroid Build Coastguard Worker// X ← Means server sending data to the client. 43*61c4878aSAndroid Build Coastguard Workermessage Chunk { 44*61c4878aSAndroid Build Coastguard Worker // Represents the source or destination of the data. May be ephemeral or 45*61c4878aSAndroid Build Coastguard Worker // stable depending on the implementation. Sent in every request to identify 46*61c4878aSAndroid Build Coastguard Worker // the transfer target. 47*61c4878aSAndroid Build Coastguard Worker // 48*61c4878aSAndroid Build Coastguard Worker // LEGACY FIELD ONLY. Split into resource_id and session_id in transfer v2. 49*61c4878aSAndroid Build Coastguard Worker // 50*61c4878aSAndroid Build Coastguard Worker // Read → ID of transfer 51*61c4878aSAndroid Build Coastguard Worker // Read ← ID of transfer 52*61c4878aSAndroid Build Coastguard Worker // Write → ID of transfer 53*61c4878aSAndroid Build Coastguard Worker // Write ← ID of transfer 54*61c4878aSAndroid Build Coastguard Worker uint32 transfer_id = 1; 55*61c4878aSAndroid Build Coastguard Worker 56*61c4878aSAndroid Build Coastguard Worker // Used by the receiver to indicate how many bytes it can accept. The 57*61c4878aSAndroid Build Coastguard Worker // transmitter sends this much data, divided into chunks no larger than 58*61c4878aSAndroid Build Coastguard Worker // max_chunk_size_bytes. The receiver then starts another window by sending 59*61c4878aSAndroid Build Coastguard Worker // request_bytes again with a new offset. 60*61c4878aSAndroid Build Coastguard Worker // 61*61c4878aSAndroid Build Coastguard Worker // Read → The client requests this many bytes to be sent. 62*61c4878aSAndroid Build Coastguard Worker // Read ← N/A 63*61c4878aSAndroid Build Coastguard Worker // Write → N/A 64*61c4878aSAndroid Build Coastguard Worker // Write ← The server requests this many bytes to be sent. 65*61c4878aSAndroid Build Coastguard Worker optional uint32 pending_bytes = 2; 66*61c4878aSAndroid Build Coastguard Worker 67*61c4878aSAndroid Build Coastguard Worker // Maximum size of an individual chunk. The transmitter may send smaller 68*61c4878aSAndroid Build Coastguard Worker // chunks if required. 69*61c4878aSAndroid Build Coastguard Worker // 70*61c4878aSAndroid Build Coastguard Worker // Read → Set maximum size for subsequent chunks. 71*61c4878aSAndroid Build Coastguard Worker // Read ← N/A 72*61c4878aSAndroid Build Coastguard Worker // Write → N/A 73*61c4878aSAndroid Build Coastguard Worker // Write ← Set maximum size for subsequent chunks. 74*61c4878aSAndroid Build Coastguard Worker optional uint32 max_chunk_size_bytes = 3; 75*61c4878aSAndroid Build Coastguard Worker 76*61c4878aSAndroid Build Coastguard Worker // Minimum required delay between chunks. The transmitter may delay longer if 77*61c4878aSAndroid Build Coastguard Worker // desired. 78*61c4878aSAndroid Build Coastguard Worker // 79*61c4878aSAndroid Build Coastguard Worker // Read → Set minimum delay for subsequent chunks. 80*61c4878aSAndroid Build Coastguard Worker // Read ← N/A 81*61c4878aSAndroid Build Coastguard Worker // Write → N/A 82*61c4878aSAndroid Build Coastguard Worker // Write ← Set minimum delay for subsequent chunks. 83*61c4878aSAndroid Build Coastguard Worker optional uint32 min_delay_microseconds = 4; 84*61c4878aSAndroid Build Coastguard Worker 85*61c4878aSAndroid Build Coastguard Worker // On writes, the offset of the data. On reads, the offset at which to read. 86*61c4878aSAndroid Build Coastguard Worker // 87*61c4878aSAndroid Build Coastguard Worker // Read → Read data starting at this offset. 88*61c4878aSAndroid Build Coastguard Worker // Read ← Offset of the data. 89*61c4878aSAndroid Build Coastguard Worker // Write → Offset of the data. 90*61c4878aSAndroid Build Coastguard Worker // Write ← Write data starting at this offset. 91*61c4878aSAndroid Build Coastguard Worker uint64 offset = 5; 92*61c4878aSAndroid Build Coastguard Worker 93*61c4878aSAndroid Build Coastguard Worker // The data that was read or the data to write. 94*61c4878aSAndroid Build Coastguard Worker // 95*61c4878aSAndroid Build Coastguard Worker // Read → N/A 96*61c4878aSAndroid Build Coastguard Worker // Read ← Data read 97*61c4878aSAndroid Build Coastguard Worker // Write → Data to write 98*61c4878aSAndroid Build Coastguard Worker // Write ← N/A 99*61c4878aSAndroid Build Coastguard Worker bytes data = 6; 100*61c4878aSAndroid Build Coastguard Worker 101*61c4878aSAndroid Build Coastguard Worker // Estimated bytes remaining to read/write. Optional except for the last data 102*61c4878aSAndroid Build Coastguard Worker // chunk, for which remaining_bytes must be set to 0. 103*61c4878aSAndroid Build Coastguard Worker // 104*61c4878aSAndroid Build Coastguard Worker // The sender can set remaining_bytes at the beginning of a read/write so that 105*61c4878aSAndroid Build Coastguard Worker // the receiver can track progress or cancel the transaction if the value is 106*61c4878aSAndroid Build Coastguard Worker // too large. 107*61c4878aSAndroid Build Coastguard Worker // 108*61c4878aSAndroid Build Coastguard Worker // Read → N/A 109*61c4878aSAndroid Build Coastguard Worker // Read ← Remaining bytes to read, excluding any data in this chunk. Set to 110*61c4878aSAndroid Build Coastguard Worker // 0 for the last chunk. 111*61c4878aSAndroid Build Coastguard Worker // Write → Remaining bytes to write, excluding any data in is chunk. Set to 112*61c4878aSAndroid Build Coastguard Worker // 0 for the last chunk. 113*61c4878aSAndroid Build Coastguard Worker // Write ← N/A 114*61c4878aSAndroid Build Coastguard Worker optional uint64 remaining_bytes = 7; 115*61c4878aSAndroid Build Coastguard Worker 116*61c4878aSAndroid Build Coastguard Worker // Pigweed status code indicating the completion of a transfer. This is only 117*61c4878aSAndroid Build Coastguard Worker // present in the final packet sent by either the transmitter or receiver. 118*61c4878aSAndroid Build Coastguard Worker // 119*61c4878aSAndroid Build Coastguard Worker // The possible status codes and their meanings are listed below: 120*61c4878aSAndroid Build Coastguard Worker // 121*61c4878aSAndroid Build Coastguard Worker // OK: Transfer completed successfully. 122*61c4878aSAndroid Build Coastguard Worker // DATA_LOSS: Transfer data could not be read/written (e.g. corruption). 123*61c4878aSAndroid Build Coastguard Worker // INVALID_ARGUMENT: Received malformed chunk. 124*61c4878aSAndroid Build Coastguard Worker // NOT_FOUND: The requested resource ID is not registered (read/write). 125*61c4878aSAndroid Build Coastguard Worker // OUT_OF_RANGE: The requested offset is larger than the data (read/write). 126*61c4878aSAndroid Build Coastguard Worker // RESOURCE_EXHAUSTED: Concurrent transfer limit reached. 127*61c4878aSAndroid Build Coastguard Worker // UNIMPLEMENTED: Resource ID does not support requested operation (e.g. 128*61c4878aSAndroid Build Coastguard Worker // trying to write to a read-only transfer). 129*61c4878aSAndroid Build Coastguard Worker // 130*61c4878aSAndroid Build Coastguard Worker // Read → Transfer complete. 131*61c4878aSAndroid Build Coastguard Worker // Read ← Transfer complete. 132*61c4878aSAndroid Build Coastguard Worker // Write → Transfer complete. 133*61c4878aSAndroid Build Coastguard Worker // Write ← Transfer complete. 134*61c4878aSAndroid Build Coastguard Worker optional uint32 status = 8; 135*61c4878aSAndroid Build Coastguard Worker 136*61c4878aSAndroid Build Coastguard Worker // The offset up to which the transmitter can send data before waiting for the 137*61c4878aSAndroid Build Coastguard Worker // receiver to acknowledge. 138*61c4878aSAndroid Build Coastguard Worker // 139*61c4878aSAndroid Build Coastguard Worker // Read → Offset up to which the server can send without blocking. 140*61c4878aSAndroid Build Coastguard Worker // Read ← N/A 141*61c4878aSAndroid Build Coastguard Worker // Write → N/A 142*61c4878aSAndroid Build Coastguard Worker // Write ← Offset up to which the client can send without blocking. 143*61c4878aSAndroid Build Coastguard Worker // 144*61c4878aSAndroid Build Coastguard Worker // TODO(frolv): This will replace the pending_bytes field. Once all uses of 145*61c4878aSAndroid Build Coastguard Worker // transfer are migrated, that field should be removed. 146*61c4878aSAndroid Build Coastguard Worker uint32 window_end_offset = 9; 147*61c4878aSAndroid Build Coastguard Worker 148*61c4878aSAndroid Build Coastguard Worker enum Type { 149*61c4878aSAndroid Build Coastguard Worker // Chunk containing transfer data. 150*61c4878aSAndroid Build Coastguard Worker DATA = 0; 151*61c4878aSAndroid Build Coastguard Worker 152*61c4878aSAndroid Build Coastguard Worker // First chunk of a transfer (only sent by the client). 153*61c4878aSAndroid Build Coastguard Worker START = 1; 154*61c4878aSAndroid Build Coastguard Worker 155*61c4878aSAndroid Build Coastguard Worker // Transfer parameters indicating that the transmitter should retransmit 156*61c4878aSAndroid Build Coastguard Worker // from the specified offset. 157*61c4878aSAndroid Build Coastguard Worker PARAMETERS_RETRANSMIT = 2; 158*61c4878aSAndroid Build Coastguard Worker 159*61c4878aSAndroid Build Coastguard Worker // Transfer parameters telling the transmitter to continue sending up to 160*61c4878aSAndroid Build Coastguard Worker // index `offset + pending_bytes` of data. If the transmitter is already 161*61c4878aSAndroid Build Coastguard Worker // beyond `offset`, it does not have to rewind. 162*61c4878aSAndroid Build Coastguard Worker PARAMETERS_CONTINUE = 3; 163*61c4878aSAndroid Build Coastguard Worker 164*61c4878aSAndroid Build Coastguard Worker // Sender of the chunk is terminating the transfer. 165*61c4878aSAndroid Build Coastguard Worker COMPLETION = 4; 166*61c4878aSAndroid Build Coastguard Worker 167*61c4878aSAndroid Build Coastguard Worker // Acknowledge the completion of a transfer. Currently unused. 168*61c4878aSAndroid Build Coastguard Worker // TODO(konkers): Implement this behavior. 169*61c4878aSAndroid Build Coastguard Worker COMPLETION_ACK = 5; 170*61c4878aSAndroid Build Coastguard Worker 171*61c4878aSAndroid Build Coastguard Worker // Acknowledges a transfer start request, accepting the session ID for the 172*61c4878aSAndroid Build Coastguard Worker // transfer and optionally negotiating the protocol version. Sent from 173*61c4878aSAndroid Build Coastguard Worker // server to client. 174*61c4878aSAndroid Build Coastguard Worker START_ACK = 6; 175*61c4878aSAndroid Build Coastguard Worker 176*61c4878aSAndroid Build Coastguard Worker // Confirmation of a START_ACK's negotiated parameters, sent by the client 177*61c4878aSAndroid Build Coastguard Worker // to the server. Initiates the data transfer proper. 178*61c4878aSAndroid Build Coastguard Worker START_ACK_CONFIRMATION = 7; 179*61c4878aSAndroid Build Coastguard Worker }; 180*61c4878aSAndroid Build Coastguard Worker 181*61c4878aSAndroid Build Coastguard Worker // The type of this chunk. This field should only be processed when present. 182*61c4878aSAndroid Build Coastguard Worker // TODO(frolv): Update all users of pw_transfer and remove the optional 183*61c4878aSAndroid Build Coastguard Worker // semantics from this field. 184*61c4878aSAndroid Build Coastguard Worker // 185*61c4878aSAndroid Build Coastguard Worker // Read → Chunk type (start/parameters). 186*61c4878aSAndroid Build Coastguard Worker // Read ← Chunk type (data). 187*61c4878aSAndroid Build Coastguard Worker // Write → Chunk type (data). 188*61c4878aSAndroid Build Coastguard Worker // Write ← Chunk type (start/parameters). 189*61c4878aSAndroid Build Coastguard Worker optional Type type = 10; 190*61c4878aSAndroid Build Coastguard Worker 191*61c4878aSAndroid Build Coastguard Worker // Unique identifier for the source or destination of transfer data. May be 192*61c4878aSAndroid Build Coastguard Worker // stable or ephemeral depending on the implementation. Only sent during the 193*61c4878aSAndroid Build Coastguard Worker // initial handshake phase of a version 2 or higher transfer. 194*61c4878aSAndroid Build Coastguard Worker // 195*61c4878aSAndroid Build Coastguard Worker // Read → ID of transferable resource 196*61c4878aSAndroid Build Coastguard Worker // Read ← ID of transferable resource 197*61c4878aSAndroid Build Coastguard Worker // Write → ID of transferable resource 198*61c4878aSAndroid Build Coastguard Worker // Write ← ID of transferable resource 199*61c4878aSAndroid Build Coastguard Worker optional uint32 resource_id = 11; 200*61c4878aSAndroid Build Coastguard Worker 201*61c4878aSAndroid Build Coastguard Worker // Unique identifier for a specific transfer session. Chosen by the transfer 202*61c4878aSAndroid Build Coastguard Worker // client during the initial handshake phase, and persists for the remainder 203*61c4878aSAndroid Build Coastguard Worker // of that transfer operation. 204*61c4878aSAndroid Build Coastguard Worker // 205*61c4878aSAndroid Build Coastguard Worker // Read → ID of transfer session 206*61c4878aSAndroid Build Coastguard Worker // Read ← ID of transfer session 207*61c4878aSAndroid Build Coastguard Worker // Write → ID of transfer session 208*61c4878aSAndroid Build Coastguard Worker // Write ← ID of transfer session 209*61c4878aSAndroid Build Coastguard Worker optional uint32 session_id = 12; 210*61c4878aSAndroid Build Coastguard Worker 211*61c4878aSAndroid Build Coastguard Worker // The protocol version to use for this transfer. Only sent during the initial 212*61c4878aSAndroid Build Coastguard Worker // handshake phase of a version 2 or higher transfer to negotiate a common 213*61c4878aSAndroid Build Coastguard Worker // protocol version between the client and server. 214*61c4878aSAndroid Build Coastguard Worker // 215*61c4878aSAndroid Build Coastguard Worker // Read → Desired (START) or configured (START_ACK_CONFIRMATION) version. 216*61c4878aSAndroid Build Coastguard Worker // Read ← Configured protocol version (START_ACK). 217*61c4878aSAndroid Build Coastguard Worker // Write → Desired (START) or configured (START_ACK_CONFIRMATION) version. 218*61c4878aSAndroid Build Coastguard Worker // Write ← Configured protocol version (START_ACK). 219*61c4878aSAndroid Build Coastguard Worker optional uint32 protocol_version = 13; 220*61c4878aSAndroid Build Coastguard Worker 221*61c4878aSAndroid Build Coastguard Worker // Unique identifier for a specific transfer session. Chosen by the transfer 222*61c4878aSAndroid Build Coastguard Worker // client during the initial handshake phase. This field is used to request a 223*61c4878aSAndroid Build Coastguard Worker // session during the handshake, after which the regular session_id field is 224*61c4878aSAndroid Build Coastguard Worker // used. 225*61c4878aSAndroid Build Coastguard Worker // 226*61c4878aSAndroid Build Coastguard Worker // Read → Requested ID of transfer session 227*61c4878aSAndroid Build Coastguard Worker // Read ← N/A 228*61c4878aSAndroid Build Coastguard Worker // Write → Requested ID of transfer session 229*61c4878aSAndroid Build Coastguard Worker // Write ← N/A 230*61c4878aSAndroid Build Coastguard Worker optional uint32 desired_session_id = 14; 231*61c4878aSAndroid Build Coastguard Worker 232*61c4878aSAndroid Build Coastguard Worker // The initial offset to start the transfer from. Can be used for read or 233*61c4878aSAndroid Build Coastguard Worker // write transfers. Set by the client during start handshake. 234*61c4878aSAndroid Build Coastguard Worker // Needs to be accepted by the resource transfer handler in order for the 235*61c4878aSAndroid Build Coastguard Worker // non-zero offset transfer to start from the initial_offset. 236*61c4878aSAndroid Build Coastguard Worker // 237*61c4878aSAndroid Build Coastguard Worker // Read → Requested initial offset for the session 238*61c4878aSAndroid Build Coastguard Worker // Read ← Confirmed (matches) or denied (zero) initial offset 239*61c4878aSAndroid Build Coastguard Worker // Write → Requested initial offset for the session 240*61c4878aSAndroid Build Coastguard Worker // Write ← Confirmed (matches) or denied (zero) initial offset 241*61c4878aSAndroid Build Coastguard Worker uint64 initial_offset = 15; 242*61c4878aSAndroid Build Coastguard Worker} 243*61c4878aSAndroid Build Coastguard Worker 244*61c4878aSAndroid Build Coastguard Worker// Request for GetResourceStatus, indicating the resource to get status from. 245*61c4878aSAndroid Build Coastguard Workermessage ResourceStatusRequest { 246*61c4878aSAndroid Build Coastguard Worker uint32 resource_id = 1; 247*61c4878aSAndroid Build Coastguard Worker} 248*61c4878aSAndroid Build Coastguard Worker 249*61c4878aSAndroid Build Coastguard Worker// Response for GetResourceStatus 250*61c4878aSAndroid Build Coastguard Workermessage ResourceStatus { 251*61c4878aSAndroid Build Coastguard Worker // Resource id, matching request 252*61c4878aSAndroid Build Coastguard Worker uint32 resource_id = 1; 253*61c4878aSAndroid Build Coastguard Worker 254*61c4878aSAndroid Build Coastguard Worker // Status of the resource, returns Unimplemented by default. 255*61c4878aSAndroid Build Coastguard Worker uint32 status = 2; 256*61c4878aSAndroid Build Coastguard Worker // The offset that can be written to (other than 0). 257*61c4878aSAndroid Build Coastguard Worker uint64 writeable_offset = 3; 258*61c4878aSAndroid Build Coastguard Worker // The offset that can be read from (other than 0). 259*61c4878aSAndroid Build Coastguard Worker uint64 readable_offset = 4; 260*61c4878aSAndroid Build Coastguard Worker // The checksum at the given write offset. 261*61c4878aSAndroid Build Coastguard Worker optional uint64 write_checksum = 5; 262*61c4878aSAndroid Build Coastguard Worker // The checksum at the given read offset. 263*61c4878aSAndroid Build Coastguard Worker optional uint64 read_checksum = 6; 264*61c4878aSAndroid Build Coastguard Worker} 265