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);
}

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;
}