blob: 839eb2cd29f317532390e183442f5af3be93a13f [file] [log] [blame]
// Copyright 2022 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;
option java_multiple_files = true;
option java_package = "dev.pigweed.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.
//
// LEGACY FIELD ONLY. Split into resource_id and session_id in transfer v2.
//
// 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 resource 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: Resource 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.
DATA = 0;
// First chunk of a transfer (only sent by the client).
START = 1;
// Transfer parameters indicating that the transmitter should retransmit
// from the specified offset.
PARAMETERS_RETRANSMIT = 2;
// Transfer parameters telling the transmitter to continue sending up to
// index `offset + pending_bytes` of data. If the transmitter is already
// beyond `offset`, it does not have to rewind.
PARAMETERS_CONTINUE = 3;
// Sender of the chunk is terminating the transfer.
COMPLETION = 4;
// Acknowledge the completion of a transfer. Currently unused.
// TODO(konkers): Implement this behavior.
COMPLETION_ACK = 5;
// Acknowledges a transfer start request, assigning a session ID for the
// transfer and optionally negotiating the protocol version. Sent from
// server to client.
START_ACK = 6;
// Confirmation of a START_ACK's assigned session ID and negotiated
// parameters, sent by the client to the server. Initiates the data transfer
// proper.
START_ACK_CONFIRMATION = 7;
};
// 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;
// Unique identifier for the source or destination of transfer data. May be
// stable or ephemeral depending on the implementation. Only sent during the
// initial handshake phase of a version 2 or higher transfer.
//
// Read → ID of transferable resource
// Read ← ID of transferable resource
// Write → ID of transferable resource
// Write ← ID of transferable resource
optional uint32 resource_id = 11;
// Unique identifier for a specific transfer session. Assigned by a transfer
// service during the initial handshake phase, and persists for the remainder
// of that transfer operation.
//
// Read → ID of transfer session
// Read ← ID of transfer session
// Write → ID of transfer session
// Write ← ID of transfer session
optional uint32 session_id = 12;
// The protocol version to use for this transfer. Only sent during the initial
// handshake phase of a version 2 or higher transfer to negotiate a common
// protocol version between the client and server.
//
// Read → Desired (START) or configured (START_ACK_CONFIRMATION) version.
// Read ← Configured protocol version (START_ACK).
// Write → Desired (START) or configured (START_ACK_CONFIRMATION) version.
// Write ← Configured protocol version (START_ACK).
optional uint32 protocol_version = 13;
}