file_exchange.proto

syntax = "proto3";

package fileexchange;

// Interface exported by the server.
service FileExchange {
  // Allow file content to be stored on a server and retrieved by supplying an ID.
  // The content of large files will be sent as multiple messages.

  // Send a file to the server, possibly in multiple chunks
  rpc PutFile(stream FileContent) returns (FileId) {}

  // Request the content of a file from the server
  rpc GetFileContent(FileId) returns (stream FileContent) {}

  // TODO: Add RPCs for getting info about the file (e.g. its name and size)
  // without actually retrieving its full content
}

message FileId {
  int32 id = 1;
}

message FileContent {
  int32  id = 1;
  string name = 2;

  // TODO: Consider avoiding copying when initialising the content field by using [ctype = STRING_PIECE]
  // See: https://stackoverflow.com/a/43824243/1268949
  // Note this seems to be available only in the latest public versions of Protobuf from late 2018.
  bytes  content = 3;

  // TODO: Add an optional field with the number of bytes still pending transfer. This will allow several things:
  // * Give the receiving side a chance to check if it has enough space accept the incoming file.
  // * Give the receiving side a chance to optimise the filesystem by allocating the necessary
  //   amount of disk space using an appropriate system call e.g. posix_fallocate() where availale.
  // * Allow the sending side to indicate an error by dropping it to 0 unexpectedly or using a negative value.
}