/// This proto file is used to define the gRPC service for the cache service.
///
/// The content is provided by github staff in [apache/opendal#5620](https://github.com/apache/opendal/issues/5620)

syntax = "proto3";

package v1;

service CacheService {
  // Generates a SAS URL with write permissions to upload a cache archive
  rpc CreateCacheEntry(CreateCacheEntryRequest) returns (CreateCacheEntryResponse);
  // Indicate the completion of a cache archive upload. Triggers post-upload processing
  rpc FinalizeCacheEntryUpload(FinalizeCacheEntryUploadRequest) returns (FinalizeCacheEntryUploadResponse);
  // Generates a SAS URL with read permissions to download a cache archive
  rpc GetCacheEntryDownloadURL(GetCacheEntryDownloadURLRequest) returns (GetCacheEntryDownloadURLResponse);
}

message CreateCacheEntryRequest {
  // Scope and other metadata for the cache entry
  CacheMetadata metadata = 1;
  // An explicit key for a cache entry
  string key = 2;
  // Hash of the compression tool, runner OS and paths cached
  string version = 3;
}

message CreateCacheEntryResponse {
  bool ok = 1;
  // SAS URL to upload the cache archive
  string signed_upload_url = 2;
}

message FinalizeCacheEntryUploadRequest {
  // Scope and other metadata for the cache entry
  CacheMetadata metadata = 1;
  // An explicit key for a cache entry
  string key = 2;
  // Size of the cache archive in Bytes
  int64 size_bytes = 3;
  // Hash of the compression tool, runner OS and paths cached
  string version = 4;
}

message FinalizeCacheEntryUploadResponse {
  bool ok = 1;
  // Cache entry database ID
  int64 entry_id = 2;
}

message GetCacheEntryDownloadURLRequest {
  // Scope and other metadata for the cache entry
  CacheMetadata metadata = 1;
  // An explicit key for a cache entry
  string key = 2;
  // Restore keys used for prefix searching
  repeated string restore_keys = 3;
  // Hash of the compression tool, runner OS and paths cached
  string version = 4;
}

message GetCacheEntryDownloadURLResponse {
  bool ok = 1;
  // SAS URL to download the cache archive
  string signed_download_url = 2;
  // Key or restore key that matches the lookup
  string matched_key = 3;
}

message CacheMetadata {
  // Backend repository id
  int64 repository_id = 1;
  // Scopes for the cache entry
  repeated CacheScope scope = 2;
}

message CacheScope {
  // Determines the scope of the cache entry
  string scope = 1;
  // None: 0 | Read: 1 | Write: 2 | All: (1|2)
  int64 permission = 2;
}