// Copyright 2025 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.maintenance.api.v1beta;

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

option go_package = "cloud.google.com/go/maintenance/api/apiv1beta/apipb;apipb";
option java_multiple_files = true;
option java_outer_classname = "UMMServiceProto";
option java_package = "com.google.cloud.maintenance.api.v1beta";

// Request message for SummarizeMaintenances custom method.
message SummarizeMaintenancesRequest {
  // Required. The parent of the resource maintenance.
  // eg. `projects/123/locations/*`
  string parent = 10006 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "maintenance.googleapis.com/ResourceMaintenance"
    }
  ];

  // The maximum number of resource maintenances to send per page. The default
  // page size is 20 and the maximum is 1000.
  int32 page_size = 10505;

  // The page token: If the next_page_token from a previous response
  // is provided, this request will send the subsequent page.
  string page_token = 10506;

  // Filter the list as specified in https://google.aip.dev/160.
  // Supported fields include:
  // - state
  // - resource.location
  // - resource.resourceName
  // - resource.type
  // - maintenance.maintenanceName
  // - maintenanceStartTime
  // - maintenanceCompleteTime
  // Examples:
  // - state="SCHEDULED"
  // - resource.location="us-central1-c"
  // - resource.resourceName=~"*/instance-20241212-211259"
  // - maintenanceStartTime>"2000-10-11T20:44:51Z"
  // - state="SCHEDULED" OR resource.type="compute.googleapis.com/Instance"
  // - maintenance.maitenanceName="eb3b709c-9ca1-5472-9fb6-800a3849eda1" AND
  // maintenanceCompleteTime>"2000-10-11T20:44:51Z"
  string filter = 10507;

  // Order results as specified in https://google.aip.dev/132.
  string order_by = 10508;
}

// Request message for SummarizeMaintenances custom method.
message SummarizeMaintenancesResponse {
  // The resulting summaries.
  repeated MaintenanceSummary maintenances = 10509;

  // If present, the next page token can be provided to a subsequent
  // SummarizeMaintenances call to list the next page.
  // If empty, there are no more pages.
  string next_page_token = 10510;

  // Unordered list. Locations that could not be reached.
  repeated string unreachable = 10511
      [(google.api.field_behavior) = UNORDERED_LIST];
}

// MaintenanceSummary contains maintenance statistics calculated based on
// ResourceMaintenances within the scope: project and location.
message MaintenanceSummary {
  // Stats indicates the type of aggregate and the corresponding aggregates.
  message Stats {
    // groupBy specifies the type of aggregate.
    // For example a group_by might be `"state"`
    string group_by = 1;

    // Aggregates is a list <group, count> pairs. For example, if the
    // group_by is `"state"` a possible tuple in the aggregates list could be
    // "SCHEDULED" : `11`,
    repeated Aggregate aggregates = 2;
  }

  // Aggregate is a <group, count> pair.
  message Aggregate {
    // Specifies what specific value of the group_by the count represents. For
    // example if group_by is `"state"` its corresponding group could be
    // `"SCHEDULED"`.
    string group = 1;

    // The count of the group.
    int64 count = 2;
  }

  // Output only. The name of the maintenance.
  string maintenance_name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The title of the maintenance.
  string title = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The description of the maintenance.
  string description = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The category of the maintenance event.
  MaintenanceCategory category = 13 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Scheduled start time of the maintenance. The maintenance will
  // start at `maintenanceScheduledStartTime` or later, with best effort to
  // finish before `maintenanceScheduledEndTime`.
  google.protobuf.Timestamp maintenance_scheduled_start_time = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. An estimated (best effort, not guaranteed) end time of the
  // scheduled maintenance.
  google.protobuf.Timestamp maintenance_scheduled_end_time = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Actual date when the maintenance started. Field present only
  // after the state changed to `RUNNING`.
  google.protobuf.Timestamp maintenance_start_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Actual date when the maintenance successfully completed. Field
  // present only after the state changed to `SUCCEEDED`.
  google.protobuf.Timestamp maintenance_end_time = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Indicates whether the user has some control over that
  // maintenance, either proactively before maintenance was scheduled with
  // maintenance policy or with reactive controls after it was scheduled (see
  // controls field).
  bool user_controllable = 10 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Control available for that Maintenance (might not be available
  // for every resource that maintenance is applied to).
  repeated MaintenanceControl controls = 14
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Stats is a field of ResourceMaintenance used to aggregate the
  // stats.
  repeated Stats stats = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// ResourceMaintenance is a resource that represents a maintenance operation
// on a resource.
message ResourceMaintenance {
  option (google.api.resource) = {
    type: "maintenance.googleapis.com/ResourceMaintenance"
    pattern: "projects/{project}/locations/{location}/resourceMaintenances/{resource_maintenance}"
    plural: "resourceMaintenances"
    singular: "resourceMaintenance"
  };

  // Resource contains information about the resource affected by maintenance.
  message Resource {
    // Output only. Name is the reference to the consumer resource affected by
    // the maintenance. Available values can be found here:
    // https://cloud.google.com/asset-inventory/docs/asset-names
    string resource_name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The location of the resource.
    // Format:
    // `us-central1`
    string location = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The type of the resource.
    // Available values can be found here:
    // https://cloud.google.com/asset-inventory/docs/asset-types#supported_resource_types
    // Please note that not all the resource types will have their maintenances
    // reported.
    string type = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Maintenance is the maintenance details of a resource's maintenance.
  message Maintenance {
    // Maintenance is the name of the corresponding maintenance resource
    // following the standard naming scheme: `"{maintenance-id}"`
    string maintenance_name = 1;

    // Output only. The title of the maintenance.
    string title = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The description of the maintenance.
    string description = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The category of the maintenance.
    MaintenanceCategory category = 4
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // State is the state of a resource maintenance.
  enum State {
    // Unspecified state.
    STATE_UNSPECIFIED = 0;

    // Scheduled for a particular window. For disruptive maintenance it should
    // respect maintenance policy, i.e. its available windows, exclusions and
    // notification period.
    SCHEDULED = 1;

    // Maintenance is ongoing.
    RUNNING = 2;

    // No longer planned, typically when other maintenance (e.g. upgrade to
    // newer version) already happened, or the user skipped the maintenance.
    CANCELLED = 3;

    // Successfully completed.
    SUCCEEDED = 4;
  }

  // Identifier. The name of the resource_maintenance resource.
  // Format:
  // `"projects/{project}/locations/{location}/resourceMaintenance/{resource-maintenance-id}"`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. The resource spec of the resource maintenance.
  Resource resource = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The details of the maintenance.
  Maintenance maintenance = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The state of the resource maintenance.
  State state = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The create time of the resource maintenance.
  google.protobuf.Timestamp create_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The update time of the resource maintenance.
  google.protobuf.Timestamp update_time = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time when the resource maintenance has started.
  google.protobuf.Timestamp maintenance_start_time = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time when the resource maintenance has completed.
  google.protobuf.Timestamp maintenance_end_time = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time when the resource maintenance was cancelled.
  google.protobuf.Timestamp maintenance_cancel_time = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time when the maintenance on the resource was scheduled to
  // start.
  google.protobuf.Timestamp maintenance_scheduled_start_time = 10
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time when the maintenance on the resource was scheduled to
  // end.
  google.protobuf.Timestamp maintenance_scheduled_end_time = 11
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Indicates whether the user has some control over that
  // maintenance, either
  //  proactively before maintenance was scheduled with maintenance policy or
  //  with reactive controls after it was scheduled (see controls field)
  bool user_controllable = 12 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The controls of the maintenance.
  repeated MaintenanceControl controls = 13
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The labels on the resource, which can be used for categorization.
  // similar to Kubernetes resource labels.
  map<string, string> labels = 10401 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Annotations is an unstructured key-value map stored with a
  // resource that may be set by external tools to store and retrieve arbitrary
  // metadata. They are not queryable and should be preserved when modifying
  // objects.
  //
  // More info: https://kubernetes.io/docs/user-guide/annotations
  map<string, string> annotations = 10402
      [(google.api.field_behavior) = OPTIONAL];

  // Output only. The unique identifier of the resource. UID is unique in the
  // time and space for this resource within the scope of the service. It is
  // typically generated by the server on successful creation of a resource
  // and must not be changed. UID is used to uniquely identify resources
  // with resource name reuses. This should be a UUID4.
  string uid = 10201 [
    (google.api.field_info).format = UUID4,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Output only. An opaque value that uniquely identifies a version or
  // generation of a resource. It can be used to confirm that the client
  // and server agree on the ordering of a resource being written.
  string etag = 10202 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// The control of the maintenance.
message MaintenanceControl {
  // Sets the type of control supported. comment (as in logs).
  enum Control {
    // Unspecified control.
    CONTROL_UNSPECIFIED = 0;

    // Apply control.
    APPLY = 1;

    // Manage policy control.
    MANAGE_POLICY = 2;

    // Reschedule control.
    RESCHEDULE = 3;
  }

  // The control of the resource maintenance.
  Control control = 1;

  // Indicates whether the control is available only in Service Producer API
  // (not through Unified Maintenance).
  bool is_custom = 2;

  // Link to Service Producer documentation about maintenance control. Provided
  // only when `isCustom` is `true`.
  string documentation = 3;
}

// The request structure for the ListResourceMaintenances method.
message ListResourceMaintenancesRequest {
  // Required. The parent of the resource maintenance.
  string parent = 10006 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "maintenance.googleapis.com/ResourceMaintenance"
    }
  ];

  // The maximum number of resource maintenances to send per page.
  int32 page_size = 10505;

  // The page token: If the next_page_token from a previous response
  // is provided, this request will send the subsequent page.
  string page_token = 10506;

  // Filter the list as specified in https://google.aip.dev/160.
  string filter = 10507;

  // Order results as specified in https://google.aip.dev/132.
  string order_by = 10508;
}

// The response structure for the ListResourceMaintenances method.
message ListResourceMaintenancesResponse {
  // The resulting resource maintenances.
  repeated ResourceMaintenance resource_maintenances = 10509;

  // If present, the next page token can be provided to a subsequent
  // ListResourceMaintenances call to list the next page.
  // If empty, there are no more pages.
  string next_page_token = 10510;

  // Locations that could not be reached.
  repeated string unreachable = 10511;
}

// The request structure for the GetResourceMaintenance method.
message GetResourceMaintenanceRequest {
  // Required. The resource name of the resource within a service.
  string name = 10001 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "maintenance.googleapis.com/ResourceMaintenance"
    }
  ];
}

// The Category of the maintenance.
enum MaintenanceCategory {
  // Unspecified category.
  MAINTENANCE_CATEGORY_UNSPECIFIED = 0;

  // Infrastructure maintenance events are times that Google Cloud performs
  // regular maintenance on network equipment e.g. Google Cloud Interconnect
  // These events are usually scheduled in advance and we provide
  // notification, when possible, so that users can plan for the
  // infrastructure maintenance event and prevent downtime. Infrastructure
  // maintenance events don't have a set interval between occurrences, but
  // generally occur several times a year.
  INFRASTRUCTURE = 1;

  // Updates that can include bug fixes, changes, or new features that are
  // backward compatible with existing versions (including patches).
  // Some SPs allow users to control the scheduling of these maintenance
  // events using maintenance windows and/or deny maintenance features.
  SERVICE_UPDATE = 3;
}

// Unified Maintenance service
service Maintenance {
  option (google.api.default_host) = "maintenance.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Retrieves the statistics of a specific maintenance.
  rpc SummarizeMaintenances(SummarizeMaintenancesRequest)
      returns (SummarizeMaintenancesResponse) {
    option (google.api.http) = {
      get: "/v1beta/{parent=projects/*/locations/*}/resourceMaintenances:summarize"
    };
    option (google.api.method_signature) = "parent";
  }

  // Retrieve a collection of resource maintenances.
  rpc ListResourceMaintenances(ListResourceMaintenancesRequest)
      returns (ListResourceMaintenancesResponse) {
    option (google.api.http) = {
      get: "/v1beta/{parent=projects/*/locations/*}/resourceMaintenances"
    };
    option (google.api.method_signature) = "parent";
  }

  // Retrieve a single resource maintenance.
  rpc GetResourceMaintenance(GetResourceMaintenanceRequest)
      returns (ResourceMaintenance) {
    option (google.api.http) = {
      get: "/v1beta/{name=projects/*/locations/*/resourceMaintenances/*}"
    };
    option (google.api.method_signature) = "name";
  }
}