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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
// Copyright 2021 The Pigweed Authors
//
// 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
//
// https://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.
syntax = "proto3";
package pw.transfer;
// The transfer RPC service is used to send data between the client and server.
service Transfer {
// Transfer data from the server to the client; a "download" from the client's
// perspective.
rpc Read(stream Chunk) returns (stream Chunk);
// Transfer data from the client to the server; an "upload" from the client's
// perspective.
rpc Write(stream Chunk) returns (stream Chunk);
}
// Represents a chunk of data sent by the transfer service. Includes fields for
// configuring the transfer parameters.
//
// Notation: (Read|Write) (→|←)
// X → Means client sending data to the server.
// X ← Means server sending data to the client.
message Chunk {
// Represents the source or destination of the data. May be ephemeral or
// stable depending on the implementation. Sent in every request to identify
// the transfer target.
//
// Read → ID of transfer
// Read ← ID of transfer
// Write → ID of transfer
// Write ← ID of transfer
uint32 transfer_id = 1;
// Used by the receiver to indicate how many bytes it can accept. The
// transmitter sends this much data, divided into chunks no larger than
// max_chunk_size_bytes. The receiver then starts another window by sending
// request_bytes again with a new offset.
//
// Read → The client requests this many bytes to be sent.
// Read ← N/A
// Write → N/A
// Write ← The server requests this many bytes to be sent.
optional uint32 pending_bytes = 2;
// Maximum size of an individual chunk. The transmitter may send smaller
// chunks if required.
//
// Read → Set maximum size for subsequent chunks.
// Read ← N/A
// Write → N/A
// Write ← Set maximum size for subsequent chunks.
optional uint32 max_chunk_size_bytes = 3;
// Minimum required delay between chunks. The transmitter may delay longer if
// desired.
//
// Read → Set minimum delay for subsequent chunks.
// Read ← N/A
// Write → N/A
// Write ← Set minimum delay for subsequent chunks.
optional uint32 min_delay_microseconds = 4;
// On writes, the offset of the data. On reads, the offset at which to read.
//
// Read → Read data starting at this offset.
// Read ← Offset of the data.
// Write → Offset of the data.
// Write ← Write data starting at this offset.
uint64 offset = 5;
// The data that was read or the data to write.
//
// Read → N/A
// Read ← Data read
// Write → Data to write
// Write ← N/A
bytes data = 6;
// Estimated bytes remaining to read/write. Optional except for the last data
// chunk, for which remaining_bytes must be set to 0.
//
// The sender can set remaining_bytes at the beginning of a read/write so that
// the receiver can track progress or cancel the transaction if the value is
// too large.
//
// Read → N/A
// Read ← Remaining bytes to read, excluding any data in this chunk. Set to
// 0 for the last chunk.
// Write → Remaining bytes to write, excluding any data in is chunk. Set to
// 0 for the last chunk.
// Write ← N/A
optional uint64 remaining_bytes = 7;
// Pigweed status code indicating the completion of a transfer. This is only
// present in the final packet sent by either the transmitter or receiver.
//
// The possible status codes and their meanings are listed below:
//
// OK: Transfer completed successfully.
// DATA_LOSS: Transfer data could not be read/written (e.g. corruption).
// INVALID_ARGUMENT: Received malformed chunk.
// NOT_FOUND: The requested transfer ID is not registered (read/write).
// OUT_OF_RANGE: The requested offset is larger than the data (read/write).
// RESOURCE_EXHAUSTED: Concurrent transfer limit reached.
// UNIMPLEMENTED: Transfer ID does not support requested operation (e.g.
// trying to write to a read-only transfer).
//
// Read → Transfer complete.
// Read ← Transfer complete.
// Write → Transfer complete.
// Write ← Transfer complete.
optional uint32 status = 8;
// The offset up to which the transmitter can send data before waiting for the
// receiver to acknowledge.
//
// Read → Offset up to which the server can send without blocking.
// Read ← N/A
// Write → N/A
// Write ← Offset up to which the client can send without blocking.
//
// TODO(frolv): This will replace the pending_bytes field. Once all uses of
// transfer are migrated, that field should be removed.
uint32 window_end_offset = 9;
enum Type {
// Chunk containing transfer data.
TRANSFER_DATA = 0;
// First chunk of a transfer (only sent by the client). Currently unused.
TRANSFER_START = 1;
// Transfer parameters indicating that the sender should retransmit from the
// specified offset.
PARAMETERS_RETRANSMIT = 2;
// Transfer parameters telling the sender to continue sending up to index
// `offset + pending_bytes` of data. If the sender is already beyond offset,
// it does not have to rewind.
PARAMETERS_CONTINUE = 3;
};
// The type of this chunk. This field should only be processed when present.
// TODO(frolv): Update all users of pw_transfer and remove the optional
// semantics from this field.
//
// Read → Chunk type (start/parameters).
// Read ← Chunk type (data).
// Write → Chunk type (data).
// Write ← Chunk type (start/parameters).
optional Type type = 10;
}
|
