// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.resourcesettings.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

option cc_enable_arenas = true;
option go_package = "google.golang.org/genproto/googleapis/cloud/resourcesettings/v1;resourcesettings";
option java_multiple_files = true;
option java_outer_classname = "ResourceSettingsProto";
option java_package = "com.google.cloud.resourcesettings.v1";

// An interface to interact with resource settings and setting values throughout
// the resource hierarchy.
//
// Services may surface a number of settings for users to control how their
// resources behave. Setting values applied on a given Cloud resource are
// evaluated hierarchically and inherited by all descendants of that resource.
//
// For all requests, returns a `google.rpc.Status` with
// `google.rpc.Code.PERMISSION_DENIED` if the IAM check fails or the `parent`
// resource is not in a Cloud Organization.
// For all requests, returns a `google.rpc.Status` with
// `google.rpc.Code.INVALID_ARGUMENT` if the request is malformed.
service ResourceSettingsService {
  option (google.api.default_host) = "resourcesettings.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";

  // Lists all the settings that are available on the Cloud resource `parent`.
  rpc ListSettings(ListSettingsRequest) returns (ListSettingsResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=organizations/*}/settings"
      additional_bindings {
        get: "/v1/{parent=folders/*}/settings"
      }
      additional_bindings {
        get: "/v1/{parent=projects/*}/settings"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Searches for all setting values that exist on the resource `parent`. The
  // setting values are not limited to those of a particular setting.
  rpc SearchSettingValues(SearchSettingValuesRequest) returns (SearchSettingValuesResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=organizations/*}/settings:search"
      additional_bindings {
        get: "/v1/{parent=folders/*}/settings:search"
      }
      additional_bindings {
        get: "/v1/{parent=projects/*}/settings:search"
      }
    };
  }

  // Gets a setting value.
  //
  // Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
  // setting value does not exist.
  rpc GetSettingValue(GetSettingValueRequest) returns (SettingValue) {
    option (google.api.http) = {
      get: "/v1/{name=organizations/*/settings/*/value}"
      additional_bindings {
        get: "/v1/{name=folders/*/settings/*/value}"
      }
      additional_bindings {
        get: "/v1/{name=projects/*/settings/*/value}"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Computes the effective setting value of a setting at the Cloud resource
  // `parent`. The effective setting value is the calculated setting value at a
  // Cloud resource and evaluates to one of the following options in the given
  // order (the next option is used if the previous one does not exist):
  //
  // 1. the setting value on the given resource
  // 2. the setting value on the given resource's nearest ancestor
  // 3. the setting's default value
  // 4. an empty setting value, defined as a `SettingValue` with all fields
  // unset
  //
  // Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
  // setting does not exist.
  rpc LookupEffectiveSettingValue(LookupEffectiveSettingValueRequest) returns (SettingValue) {
    option (google.api.http) = {
      get: "/v1/{name=organizations/*/settings/*/value}:lookupEffectiveValue"
      additional_bindings {
        get: "/v1/{name=folders/*/settings/*/value}:lookupEffectiveValue"
      }
      additional_bindings {
        get: "/v1/{name=projects/*/settings/*/value}:lookupEffectiveValue"
      }
    };
  }

  // Creates a setting value.
  //
  // Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
  // setting does not exist.
  // Returns a `google.rpc.Status` with `google.rpc.Code.ALREADY_EXISTS` if the
  // setting value already exists on the given Cloud resource.
  // Returns a `google.rpc.Status` with `google.rpc.Code.FAILED_PRECONDITION` if
  // the setting is flagged as read only.
  rpc CreateSettingValue(CreateSettingValueRequest) returns (SettingValue) {
    option (google.api.http) = {
      post: "/v1/{parent=organizations/*}/settings/*/value"
      body: "setting_value"
      additional_bindings {
        post: "/v1/{parent=folders/*}/settings/*/value"
        body: "setting_value"
      }
      additional_bindings {
        post: "/v1/{parent=projects/*}/settings/*/value"
        body: "setting_value"
      }
    };
    option (google.api.method_signature) = "parent,setting_value";
  }

  // Updates a setting value.
  //
  // Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
  // setting or the setting value does not exist.
  // Returns a `google.rpc.Status` with `google.rpc.Code.FAILED_PRECONDITION` if
  // the setting is flagged as read only.
  // Returns a `google.rpc.Status` with `google.rpc.Code.ABORTED` if the etag
  // supplied in the request does not match the persisted etag of the setting
  // value.
  //
  // Note: the supplied setting value will perform a full overwrite of all
  // fields.
  rpc UpdateSettingValue(UpdateSettingValueRequest) returns (SettingValue) {
    option (google.api.http) = {
      patch: "/v1/{setting_value.name=organizations/*/settings/*/value}"
      body: "setting_value"
      additional_bindings {
        patch: "/v1/{setting_value.name=folders/*/settings/*/value}"
        body: "setting_value"
      }
      additional_bindings {
        patch: "/v1/{setting_value.name=projects/*/settings/*/value}"
        body: "setting_value"
      }
    };
  }

  // Deletes a setting value. If the setting value does not exist, the operation
  // is a no-op.
  //
  // Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
  // setting or the setting value does not exist. The setting value will not
  // exist if a prior call to `DeleteSettingValue` for the setting value already
  // returned a success code.
  // Returns a `google.rpc.Status` with `google.rpc.Code.FAILED_PRECONDITION` if
  // the setting is flagged as read only.
  rpc DeleteSettingValue(DeleteSettingValueRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1/{name=organizations/*/settings/*/value}"
      additional_bindings {
        delete: "/v1/{name=folders/*/settings/*/value}"
      }
      additional_bindings {
        delete: "/v1/{name=projects/*/settings/*/value}"
      }
    };
    option (google.api.method_signature) = "name";
  }
}

// The instantiation of a setting. Every setting value is parented by its
// corresponding setting.
message SettingValue {
  option (google.api.resource) = {
    type: "resourcesettings.googleapis.com/SettingValue"
    pattern: "projects/{project_number}/settings/{setting_name}/value"
    pattern: "folders/{folder}/settings/{setting_name}/value"
    pattern: "organizations/{organization}/settings/{setting_name}/value"
  };

  // The resource name of the setting value. Must be in one of the following
  // forms:
  //
  // * `projects/{project_number}/settings/{setting_name}/value`
  // * `folders/{folder_id}/settings/{setting_name}/value`
  // * `organizations/{organization_id}/settings/{setting_name}/value`
  //
  // For example, "/projects/123/settings/gcp-enableMyFeature/value"
  string name = 1;

  // The value of the setting. The data type of [Value][google.cloud.resourcesettings.v1.Value] must always be
  // consistent with the data type defined by the parent setting.
  Value value = 2;

  // A fingerprint used for optimistic concurrency. See
  // [UpdateSettingValue][google.cloud.resourcesettings.v1.ResourceSettingsService.UpdateSettingValue] for more
  // details.
  string etag = 3;

  // Output only. A flag indicating that this setting value cannot be modified.
  // This flag is inherited from its parent setting and is for
  // convenience purposes. See [Setting.read_only][google.cloud.resourcesettings.v1.Setting.read_only] for more details.
  bool read_only = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The timestamp indicating when the setting value was last
  // updated.
  google.protobuf.Timestamp update_time = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The schema for setting values. At a given Cloud resource, a setting can
// parent at most one setting value.
message Setting {
  option (google.api.resource) = {
    type: "resourcesettings.googleapis.com/Setting"
    pattern: "projects/{project_number}/settings/{setting_name}"
    pattern: "folders/{folder}/settings/{setting_name}"
    pattern: "organizations/{organization}/settings/{setting_name}"
  };

  // The data type for setting values of this setting. See [Value][google.cloud.resourcesettings.v1.Value] for more
  // details on the available data types.
  enum DataType {
    // Unspecified data type.
    DATA_TYPE_UNSPECIFIED = 0;

    // A boolean setting.
    BOOLEAN = 1;

    // A string setting.
    STRING = 2;

    // A string set setting.
    STRING_SET = 3;

    // A Enum setting
    ENUM_VALUE = 4;
  }

  // The resource name of the setting. Must be in one of the following forms:
  //
  // * `projects/{project_number}/settings/{setting_name}`
  // * `folders/{folder_id}/settings/{setting_name}`
  // * `organizations/{organization_id}/settings/{setting_name}`
  //
  // For example, "/projects/123/settings/gcp-enableMyFeature"
  string name = 1;

  // The human readable name for this setting.
  string display_name = 2;

  // A detailed description of what this setting does.
  string description = 3;

  // A flag indicating that values of this setting cannot be modified (see
  // documentation of the specific setting for updates and reasons).
  bool read_only = 4;

  // The data type for this setting.
  DataType data_type = 5;

  // The value received by
  // [LookupEffectiveSettingValue][google.cloud.resourcesettings.v1.ResourceSettingsService.LookupEffectiveSettingValue]
  // if no setting value is explicitly set.
  //
  // Note: not all settings have a default value.
  Value default_value = 6;
}

// The data in a setting value.
message Value {
  // A string set value that can hold a set of strings. The maximum length of
  // each string is 60 characters and there can be a maximum of 50 strings in
  // the string set.
  message StringSet {
    // The strings in the set
    repeated string values = 1;
  }

  // A enum value that can hold any enum type setting values.
  // Each enum type is represented by a number, this representation
  // is stored in the definitions.
  message EnumValue {
    string value = 1;
  }

  // Selects the data type and associated value.
  oneof value {
    // Defines this value as being a boolean value.
    bool boolean_value = 1;

    // Defines this value as being a string value.
    string string_value = 2;

    // Defines this value as being a StringSet.
    StringSet string_set_value = 3;

    // Defines this value as being a Enum.
    EnumValue enum_value = 4;
  }
}

// The request for ListSettings.
message ListSettingsRequest {
  // Required. The Cloud resource that parents the setting. Must be in one of the
  // following forms:
  //
  // * `projects/{project_number}`
  // * `projects/{project_id}`
  // * `folders/{folder_id}`
  // * `organizations/{organization_id}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "*"
    }
  ];

  // Unused. The size of the page to be returned.
  int32 page_size = 2;

  // Unused. A page token used to retrieve the next page.
  string page_token = 3;
}

// The response from ListSettings.
message ListSettingsResponse {
  // A list of settings that are available at the specified Cloud resource.
  repeated Setting settings = 1;

  // Unused. A page token used to retrieve the next page.
  string next_page_token = 2;
}

// The request for SearchSettingValues.
message SearchSettingValuesRequest {
  // Required. The Cloud resource that parents the setting. Must be in one of the
  // following forms:
  //
  // * `projects/{project_number}`
  // * `projects/{project_id}`
  // * `folders/{folder_id}`
  // * `organizations/{organization_id}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Unused. The size of the page to be returned.
  int32 page_size = 2;

  // Unused. A page token used to retrieve the next page.
  string page_token = 3;
}

// The response from SearchSettingValues.
message SearchSettingValuesResponse {
  // All setting values that exist on the specified Cloud resource.
  repeated SettingValue setting_values = 1;

  // Unused. A page token used to retrieve the next page.
  string next_page_token = 2;
}

// The request for GetSettingValue.
message GetSettingValueRequest {
  // Required. The name of the setting value to get. See [SettingValue][google.cloud.resourcesettings.v1.SettingValue] for naming
  // requirements.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "resourcesettings.googleapis.com/SettingValue"
    }
  ];
}

// The request for LookupEffectiveSettingValue.
message LookupEffectiveSettingValueRequest {
  // Required. The setting value for which an effective value will be evaluated.
  // See [SettingValue][google.cloud.resourcesettings.v1.SettingValue] for naming requirements.
  string name = 1 [(google.api.field_behavior) = REQUIRED];
}

// The request for CreateSettingValue.
message CreateSettingValueRequest {
  // Required. The name of the setting for which a value should be created.
  // See [Setting][google.cloud.resourcesettings.v1.Setting] for naming requirements.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "resourcesettings.googleapis.com/Setting"
    }
  ];

  // Required. The setting value to create. See [SettingValue][google.cloud.resourcesettings.v1.SettingValue] for field requirements.
  SettingValue setting_value = 2 [(google.api.field_behavior) = REQUIRED];
}

// The request for UpdateSettingValue.
message UpdateSettingValueRequest {
  // Required. The setting value to update. See [SettingValue][google.cloud.resourcesettings.v1.SettingValue] for field requirements.
  SettingValue setting_value = 1 [(google.api.field_behavior) = REQUIRED];
}

// The request for DeleteSettingValue.
message DeleteSettingValueRequest {
  // Required. The name of the setting value to delete. See [SettingValue][google.cloud.resourcesettings.v1.SettingValue] for naming
  // requirements.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "resourcesettings.googleapis.com/SettingValue"
    }
  ];
}