Appendix B: gRPC API Protobufs

This appendix contains the full Protocol Buffers definition (.proto) for all of Anvil's gRPC services. This file is the canonical source of truth for the API's structure, and you can use it with protoc to generate client libraries for any supported language.

anvil.proto

syntax = "proto3";

package anvil;

// Bucket Service
service BucketService {
  rpc CreateBucket(CreateBucketRequest) returns (CreateBucketResponse);
  rpc DeleteBucket(DeleteBucketRequest) returns (DeleteBucketResponse);
  rpc ListBuckets(ListBucketsRequest) returns (ListBucketsResponse);
  rpc GetBucketPolicy(GetBucketPolicyRequest) returns (GetBucketPolicyResponse);
  rpc PutBucketPolicy(PutBucketPolicyRequest) returns (PutBucketPolicyResponse);
}

message CreateBucketRequest {
  string bucket_name = 1;
  string region = 2;
}

message CreateBucketResponse {}

message DeleteBucketRequest {
  string bucket_name = 1;
}

message DeleteBucketResponse {}

message ListBucketsRequest {}

message Bucket {
    string name = 1;
    string creation_date = 2;
}

message ListBucketsResponse {
    repeated Bucket buckets = 1;
}

message GetBucketPolicyRequest {
    string bucket_name = 1;
}

message GetBucketPolicyResponse {
    string policy_json = 1;
}

message PutBucketPolicyRequest {
    string bucket_name = 1;
    string policy_json = 2;
}

message PutBucketPolicyResponse {}


// Object Service
service ObjectService {
  rpc PutObject(stream PutObjectRequest) returns (PutObjectResponse);
  rpc GetObject(GetObjectRequest) returns (stream GetObjectResponse);
  rpc DeleteObject(DeleteObjectRequest) returns (DeleteObjectResponse);
  rpc HeadObject(HeadObjectRequest) returns (HeadObjectResponse);
  rpc ListObjects(ListObjectsRequest) returns (ListObjectsResponse);
  rpc InitiateMultipartUpload(InitiateMultipartRequest) returns (InitiateMultipartResponse);
  rpc CompleteMultipartUpload(CompleteMultipartRequest) returns (CompleteMultipartResponse);
}

message PutObjectRequest {
    oneof data {
        ObjectMetadata metadata = 1;
        bytes chunk = 2;
    }
}

message ObjectMetadata {
    string bucket_name = 1;
    string object_key = 2;
}

message PutObjectResponse {
    string etag = 1;
    string version_id = 2;
}

message GetObjectRequest {
    string bucket_name = 1;
    string object_key = 2;
  optional   string version_id = 3;
}

message GetObjectResponse {
    oneof data {
        ObjectInfo metadata = 1;
        bytes chunk = 2;
    }
}

message ObjectInfo {
    string content_type = 1;
    int64 content_length = 2;
}


message DeleteObjectRequest {
    string bucket_name = 1;
    string object_key = 2;
   optional string version_id = 3;
}

message DeleteObjectResponse {}

message HeadObjectRequest {
    string bucket_name = 1;
    string object_key = 2;
  optional  string version_id = 3; 
}

message HeadObjectResponse {
    string etag = 1;
    int64 size = 2;
    string last_modified = 3;
}

message ListObjectsRequest {
    string bucket_name = 1;
    string prefix = 2;
    string delimiter = 3;
    string start_after = 4;
    int32 max_keys = 5;
}

message ObjectSummary {
    string key = 1;
    int64 size = 2;
    string etag = 3;
    string last_modified = 4;
}

message ListObjectsResponse {
    repeated ObjectSummary objects = 1;
    repeated string common_prefixes = 2;
}

message InitiateMultipartRequest {
    string bucket_name = 1;
    string object_key = 2;
}

message InitiateMultipartResponse {
    string upload_id = 1;
}

message CompleteMultipartRequest {
    string bucket_name = 1;
    string object_key = 2;
    string upload_id = 3;
}

message CompleteMultipartResponse {
    string etag = 1;
    string version_id = 2;
}

// Internal Service for node-to-node communication
service InternalAnvilService {
  rpc PutShard(stream PutShardRequest) returns (PutShardResponse);
  rpc GetShard(GetShardRequest) returns (stream GetShardResponse);
  rpc CommitShard(CommitShardRequest) returns (CommitShardResponse);
  rpc DeleteShard(DeleteShardRequest) returns (DeleteShardResponse);
}

service AuthService {
  rpc GetAccessToken(GetAccessTokenRequest) returns (GetAccessTokenResponse);
  rpc GrantAccess(GrantAccessRequest) returns (GrantAccessResponse);
  rpc RevokeAccess(RevokeAccessRequest) returns (RevokeAccessResponse);
  rpc SetPublicAccess(SetPublicAccessRequest) returns (SetPublicAccessResponse);
}

message GetAccessTokenRequest {
  string client_id = 1;
  string client_secret = 2;
  repeated string scopes = 3;
}

message GetAccessTokenResponse {
  string access_token = 1;
  int64 expires_in = 2;
}

message GrantAccessRequest {
  string grantee_app_id = 1;
  string resource = 2;
  string action = 3;
}

message GrantAccessResponse {}

message RevokeAccessRequest {
  string grantee_app_id = 1;
  string resource = 2;
  string action = 3;
}

message RevokeAccessResponse {}

message SetPublicAccessRequest {
  string bucket = 1;
  bool allow_public_read = 2;
}

message SetPublicAccessResponse {}


message PutShardRequest {
    string upload_id = 1;
    uint32 shard_index = 2;
    bytes data = 3;
}

message PutShardResponse {}

message CommitShardRequest {
    string upload_id = 1;
    uint32 shard_index = 2;
    string final_object_hash = 3;
}

message CommitShardResponse {}

message GetShardRequest {
    string object_hash = 1;
    uint32 shard_index = 2;
}

message GetShardResponse {
    bytes data = 1;
}

message DeleteShardRequest {
    string object_hash = 1;
    uint32 shard_index = 2;
}

message DeleteShardResponse {}