// Copyright (c) HashiCorp, Inc.
// SPDX-License-Identifier: MPL-2.0

syntax = "proto3";

package plugin.v1;

import "controller/api/resources/storagebuckets/v1/storage_bucket.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

option go_package = "github.com/hashicorp/boundary/sdk/pbs/plugin;plugin";

// StoragePluginService describes the service for storage bucket plugins.
service StoragePluginService {
  // OnCreateStorageBucket is a hook that runs when a
  // storage bucket is created.
  rpc OnCreateStorageBucket(OnCreateStorageBucketRequest) returns (OnCreateStorageBucketResponse);

  // OnUpdateStorageBucket is a hook that runs when a storage bucket is
  // updated.
  rpc OnUpdateStorageBucket(OnUpdateStorageBucketRequest) returns (OnUpdateStorageBucketResponse);

  // OnDeleteStorageBucket is a hook that runs when a storage bucket is
  // deleted.
  rpc OnDeleteStorageBucket(OnDeleteStorageBucketRequest) returns (OnDeleteStorageBucketResponse);

  // ValidatePermissions is a hook that checks if the secrets associated with
  // the storage bucket meet the requirements of the plugin.
  rpc ValidatePermissions(ValidatePermissionsRequest) returns (ValidatePermissionsResponse);

  // HeadObject is a hook that retrieves metadata about an object.
  rpc HeadObject(HeadObjectRequest) returns (HeadObjectResponse);

  // GetObject is a hook that retrieves objects.
  rpc GetObject(GetObjectRequest) returns (stream GetObjectResponse);

  // PutObject is a hook that streams chunks of a file to be stored
  // in an external object store.
  rpc PutObject(stream PutObjectRequest) returns (PutObjectResponse);
}

message OnCreateStorageBucketRequest {
  // Required. The storage bucket to create. The request may contain optional
  // secret data to help authenticate the request against a cloud
  // API.
  controller.api.resources.storagebuckets.v1.StorageBucket bucket = 10;
}

message OnCreateStorageBucketResponse {
  // The persisted data represents state persisted between storage bucket calls.
  StorageBucketPersisted persisted = 10;
}

message OnUpdateStorageBucketRequest {
  // Required. The existing state of the storage bucket.
  controller.api.resources.storagebuckets.v1.StorageBucket current_bucket = 10;

  // Required. The requested new state of the storage bucket.
  // This field may contain optional secret data that has been
  // updated from the last returned persisted state.
  controller.api.resources.storagebuckets.v1.StorageBucket new_bucket = 20;

  // Required. The existing persisted secret data.
  StorageBucketPersisted persisted = 30;
}

message OnUpdateStorageBucketResponse {
  // The persisted data represents state persisted between storage bucket calls.
  StorageBucketPersisted persisted = 10;
}

message OnDeleteStorageBucketRequest {
  // Required. The existing state of the storage bucket to delete.
  controller.api.resources.storagebuckets.v1.StorageBucket bucket = 10;

  // Required. The existing persisted secret data.
  StorageBucketPersisted persisted = 20;
}

message OnDeleteStorageBucketResponse {}

message ValidatePermissionsRequest {
  // Required. The existing state of the storage bucket.
  controller.api.resources.storagebuckets.v1.StorageBucket bucket = 10;
}

message ValidatePermissionsResponse {}

message HeadObjectRequest {
  // Required. The existing state of the storage bucket.
  controller.api.resources.storagebuckets.v1.StorageBucket bucket = 10;

  // Required. The path of the object.
  string key = 20;
}

message HeadObjectResponse {
  // The size of the object in bytes.
  int64 content_length = 10;

  // Creation date of the object.
  google.protobuf.Timestamp last_modified = 20;
}

message GetObjectRequest {
  // Required. The existing state of the storage bucket.
  controller.api.resources.storagebuckets.v1.StorageBucket bucket = 10;

  // Required. The path of the object.
  string key = 20;
}

message GetObjectResponse {
  // Object data.
  bytes file_chunk = 10;
}

message PutObjectMetadata {
  // Required. The existing state of the storage bucket.
  controller.api.resources.storagebuckets.v1.StorageBucket bucket = 10;

  // Required. The path of the object.
  string key = 20;
}

message PutObjectRequest {
  oneof data {
    // Object data.
    // Recommended chunk size should be between 16KiB to 64KiB.
    bytes file_chunk = 10;

    PutObjectMetadata request = 20;
  }
}

message PutObjectResponse {
  // 256-bit SHA-256 digest of the object.
  bytes checksum_sha_256 = 10;
}

// StorageBucketPersisted is data that the plugin can read from and write
// to that will always be provided by the host.
message StorageBucketPersisted {
  // Data has no explicit structure other than valid json.
  // Data may contain sensitive information, such as
  // credentials, rotated secrets, or configuration data.
  // Data can be anything that may need to be provided to
  // a series of different method calls.
  // Data is encrypted at-rest by Boundary.
  // Data is never returned to the end user.
  google.protobuf.Struct data = 10;
}