storj/pkg/pb/pointerdb.proto

// Copyright (C) 2019 Storj Labs, Inc.
// See LICENSE for copying information.

syntax = "proto3";
option go_package = "pb";

package pointerdb;

import "google/protobuf/timestamp.proto";
import "gogo.proto";
import "node.proto";
import "piecestore.proto";

// PointerDB defines the interface for interacting with the network state persistence layer
service PointerDB {
  // Put formats and hands off a file path to be saved to boltdb
  rpc Put(PutRequest) returns (PutResponse);
  // Get formats and hands off a file path to get a small value from boltdb
  rpc Get(GetRequest) returns (GetResponse);
  // List calls the bolt client's List function and returns all file paths
  rpc List(ListRequest) returns (ListResponse);
  // Delete formats and hands off a file path to delete from boltdb
  rpc Delete(DeleteRequest) returns (DeleteResponse);
  // PayerBandwidthAllocation returns signed payer bandwidth allocation struct
  rpc PayerBandwidthAllocation(PayerBandwidthAllocationRequest) returns (PayerBandwidthAllocationResponse);
}

message RedundancyScheme {
  enum SchemeType {
    RS = 0;
  }
  SchemeType type = 1;

  // these values apply to RS encoding
  int32 min_req = 2; // minimum required for reconstruction
  int32 total = 3;   // total amount of pieces we generated
  int32 repair_threshold = 4;  // amount of pieces we need to drop to before triggering repair
  int32 success_threshold = 5; // amount of pieces we need to store to call it a success

  int32 erasure_share_size = 6;
}

message RemotePiece {
  int32 piece_num = 1;
  bytes node_id = 2 [(gogoproto.customtype) = "NodeID", (gogoproto.nullable) = false];
  piecestoreroutes.SignedHash hash = 3;
}

message RemoteSegment {
  RedundancyScheme redundancy = 1;
  // TODO: may want to use customtype and fixed-length byte slice
  string piece_id = 2;
  repeated RemotePiece remote_pieces = 3;
  bytes merkle_root = 4; // root hash of the hashes of all of these pieces
}

message Pointer {
  enum DataType {
    INLINE = 0;
    REMOTE = 1;
  }

  DataType type = 1;

  bytes inline_segment = 3;
  RemoteSegment remote = 4;
  int64 segment_size = 5;

  google.protobuf.Timestamp creation_date = 6;
  google.protobuf.Timestamp expiration_date = 7;

  bytes metadata = 8;
}

// PutRequest is a request message for the Put rpc call
message PutRequest {
  string path = 1;
  Pointer pointer = 2;
}

// GetRequest is a request message for the Get rpc call
message GetRequest {
  string path = 1;
}

// ListRequest is a request message for the List rpc call
message ListRequest {
  string prefix = 1;
  string start_after = 2;
  string end_before = 3;
  bool recursive = 4;
  int32 limit = 5;
  fixed32 meta_flags = 6;
}

// PutResponse is a response message for the Put rpc call
message PutResponse {
}

// GetResponse is a response message for the Get rpc call
message GetResponse {
  Pointer pointer = 1;
  repeated node.Node nodes = 2;
  piecestoreroutes.PayerBandwidthAllocation pba = 3;
  piecestoreroutes.SignedMessage authorization = 4;
}

// ListResponse is a response message for the List rpc call
message ListResponse {
  message Item {
    string  path = 1;
    Pointer pointer = 2;
    bool    is_prefix = 3;
  }
  
  repeated Item items = 1;
  bool more = 2;
}

message DeleteRequest {
  string path = 1;
}

// DeleteResponse is a response message for the Delete rpc call
message DeleteResponse {
}

// IterateRequest is a request message for the Iterate rpc call
message IterateRequest {
  string prefix = 1;
  string first = 2;
  bool recurse = 3;
  bool reverse = 4;
}

message PayerBandwidthAllocationRequest {
  piecestoreroutes.BandwidthAction action = 1;
}

message PayerBandwidthAllocationResponse {
  piecestoreroutes.PayerBandwidthAllocation pba = 1;
}