xref: /aosp_15_r20/external/pigweed/pw_transfer/transfer.proto (revision 61c4878ac05f98d0ceed94b57d316916de578985)
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