boundary/internal/proto/plugin/v1/storage_plugin_service.proto

// 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/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 reads a file stored on local disk and
  // stores it to an external object store.
  rpc PutObject(PutObjectRequest) returns (PutObjectResponse);

  // DeleteObjects deletes one or many files in an external object store
  // via a provided key prefix.
  rpc DeleteObjects(DeleteObjectsRequest) returns (DeleteObjectsResponse);
}

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.
  controller.api.resources.storagebuckets.v1.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.
  controller.api.resources.storagebuckets.v1.StorageBucketPersisted persisted = 30;
}

message OnUpdateStorageBucketResponse {
  // The persisted data represents state persisted between storage bucket calls.
  controller.api.resources.storagebuckets.v1.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.
  controller.api.resources.storagebuckets.v1.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;

  // Optional. The maximum size of the stream response message. Defaults to 64KiB.
  uint32 chunk_size = 30;
}

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

message PutObjectRequest {
  // 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;

  // Required. The path of the object on local disk.
  string path = 30;
}

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

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

  // Required. The prefix of object keys to be deleted.
  //
  // Deletes all objects whose keys start with this field. Note that object storage keys
  // use fully qualified names, including the full directory path in the object key. This
  // allows you to delete entire "folders" stored on remote by passing the directory path
  // and setting recursive to true, or only a single object by passing the object's full
  // key and setting recursive to false.
  string key_prefix = 20;

  // Required. Determines whether or not to delete all objects beginning with the prefix
  // or only a single key that matches the prefix in its entirety.
  //
  // Note that this means when recursive = false, key_prefix is not treated as a prefix
  // but as a fully qualified key.
  bool recursive = 30;
}

message DeleteObjectsResponse {
  // The number of objects successfully deleted.
  //
  // Note that when receiving a successful response, the plugin guarantees that all
  // objects beginning with the prefix have been deleted. This response is purely
  // informational and not meant to be used for validation.
  uint32 objects_deleted = 10;
}