@namespace("keybase.1")

protocol block {
  import idl "backend_common.avdl";

  enum BlockStatus {
    UNKNOWN_0,
    LIVE_1,
    ARCHIVED_2
  }

  record GetBlockRes {
    string blockKey;
    bytes buf;
    int size;
    BlockStatus status;
  }

  record GetBlockSizesRes {
    array<int> sizes;
    array<BlockStatus> statuses;
  }

  // Fixed-size nonce to identify a reference to a block
  fixed BlockRefNonce(8);

  record BlockReference {
    BlockIdCombo bid;
    BlockRefNonce nonce;
    UserOrTeamID chargedTo;
  }

  record BlockReferenceCount{
    BlockReference ref;
    int liveCount;
  }

  record DowngradeReferenceRes{
    array<BlockReferenceCount> completed;
    BlockReference failed;
  }


  @lint("ignore")
  record BlockIdCount{
    BlockIdCombo id;
    int liveCount;
  }

  record ReferenceCountRes{
    array<BlockIdCount> counts;
  }

  record BlockPingResponse {
    // In the future, we might want to respond with timestamps or
    // ping intervals.
  }


  ChallengeInfo getSessionChallenge();
  void authenticateSession(string signature);

  void putBlock(BlockIdCombo bid, string folder, string blockKey, bytes buf);
  void putBlockAgain(string folder, BlockReference ref, string blockKey, bytes buf);
  GetBlockRes getBlock(BlockIdCombo bid, string folder, boolean sizeOnly);
  GetBlockSizesRes getBlockSizes(array<BlockIdCombo> bids, string folder);

  void addReference(string folder, BlockReference ref);
  void delReference(string folder, BlockReference ref);
  array<BlockReference> archiveReference(string folder, array<BlockReference> refs);

  DowngradeReferenceRes delReferenceWithCount(string folder, array<BlockReference> refs);
  DowngradeReferenceRes archiveReferenceWithCount(string folder, array<BlockReference> refs);
  ReferenceCountRes getReferenceCount(string folder, array<BlockIdCombo> ids, BlockStatus status);

  bytes getUserQuotaInfo();
  bytes getTeamQuotaInfo(TeamID tid);

  BlockPingResponse blockPing();
}