syntax = "proto3";

package temporal.api.cloud.namespace.v1;

option go_package = "go.temporal.io/api/cloud/namespace/v1;namespace";
option java_package = "io.temporal.api.cloud.namespace.v1";
option java_multiple_files = true;
option java_outer_classname = "MessageProto";
option ruby_package = "Temporalio::Api::Cloud::Namespace::V1";
option csharp_namespace = "Temporalio.Api.Cloud.Namespace.V1";

import "temporal/api/cloud/resource/v1/message.proto";
import "google/protobuf/timestamp.proto";
import "temporal/api/cloud/sink/v1/message.proto";
import "temporal/api/cloud/connectivityrule/v1/message.proto";

message CertificateFilterSpec {
    // The common_name in the certificate.
    // Optional, default is empty.
    string common_name = 1;
    // The organization in the certificate.
    // Optional, default is empty.
    string organization = 2;
    // The organizational_unit in the certificate.
    // Optional, default is empty.
    string organizational_unit = 3;
    // The subject_alternative_name in the certificate.
    // Optional, default is empty.
    string subject_alternative_name = 4;
}

message MtlsAuthSpec {
    // The base64 encoded ca cert(s) in PEM format that the clients can use for authentication and authorization.
    // This must only be one value, but the CA can have a chain.
    //
    // (-- api-linter: core::0140::base64=disabled --)
    // Deprecated: Not supported after v0.2.0 api version. Use accepted_client_ca instead.
    // temporal:versioning:max_version=v0.2.0
    string accepted_client_ca_deprecated = 1 [deprecated = true];
    // The ca cert(s) in PEM format that the clients can use for authentication and authorization.
    // This must only be one value, but the CA can have a chain.
    // temporal:versioning:min_version=v0.2.0
    bytes accepted_client_ca = 4;
    // Certificate filters which, if specified, only allow connections from client certificates whose distinguished name properties match at least one of the filters.
    // This allows limiting access to specific end-entity certificates.
    // Optional, default is empty.
    repeated CertificateFilterSpec certificate_filters = 2;
    // Flag to enable mTLS auth (default: disabled).
    // Note: disabling mTLS auth will cause existing mTLS connections to fail.
    // temporal:versioning:min_version=v0.2.0
    bool enabled = 3;
}

message ApiKeyAuthSpec {
    // Flag to enable API key auth (default: disabled).
    // Note: disabling API key auth will cause existing API key connections to fail.
    bool enabled = 1;
}

message LifecycleSpec {
    // Flag to enable delete protection for the namespace.
    bool enable_delete_protection = 1;
}

message CodecServerSpec {
    // The codec server endpoint.
    string endpoint = 1;
    // Whether to pass the user access token with your endpoint.
    bool pass_access_token = 2;
    // Whether to include cross-origin credentials.
    bool include_cross_origin_credentials = 3;
    // A custom error message to display for remote codec server errors.
    // temporal:versioning:min_version=v0.5.1
    CustomErrorMessage custom_error_message = 4;

    message CustomErrorMessage {
        // The error message to display by default for any remote codec server errors.
        ErrorMessage default = 1;

        message ErrorMessage {
            // A message to display.
            string message = 1;
            // A link that is displayed along side the configured message.
            string link = 2;
        }
    }
}

message HighAvailabilitySpec {
    // Flag to disable managed failover for the namespace.
    bool disable_managed_failover = 1;

    // Flag to disable passive poller forwarding for this namespace.
    // temporal:versioning:min_version=v0.13.0
    bool disable_passive_poller_forwarding = 2;
}

// temporal:versioning:min_version=v0.13.0
message ReplicaSpec {
    // The id of the region where the replica should be placed.
    // The GetRegions API can be used to get the list of valid region ids.
    // All the replicas must adhere to the region's max_in_region_replicas limit and connectable_region_ids.
    // Required. Immutable.
    // Example: "aws-us-west-2".
    string region = 1;
}

// temporal:versioning:min_version=v0.13.0
message Replica {
    // The id of the replica. This is generated by Temporal after a replica is created.
    string id = 1;
    // Whether this replica is currently the primary one.
    bool is_primary = 2;
    // The current state of this replica.
    ReplicaState state = 3;
    // The cloud provider and region of this replica.
    string region = 4;

    enum ReplicaState {
        REPLICA_STATE_UNSPECIFIED = 0;
        REPLICA_STATE_ADDING = 1;     // This replica is currently being added to the namespace.
        REPLICA_STATE_ACTIVE = 2;     // This replica is healthy and active.
        REPLICA_STATE_REMOVING = 3;   // This replica is currently being removed from the namespace.
        REPLICA_STATE_FAILED = 5;     // This replica is in a failed state, reach out to Temporal Cloud support for remediation.
    }
}


// temporal:versioning:min_version=v0.10.0
message CapacitySpec {
    oneof spec {
        // The on-demand capacity mode configuration.
        OnDemand on_demand = 1;
        // The provisioned capacity mode configuration.
        Provisioned provisioned = 2;
    }

    message OnDemand {
    }

    message Provisioned {
        // The units of provisioned capacity in TRU (Temporal Resource Units).
        // Each TRU unit assigned to the namespace will entitle it with additional APS limits as specified in the documentation.
        double value = 1;
    }
}

message Capacity {
    oneof current_mode {
        // The status of on-demand capacity mode.
        OnDemand on_demand = 1;
        // The status of provisioned capacity mode.
        Provisioned provisioned = 2;
    }

    message OnDemand {
    }

    message Provisioned {
        // The current provisioned capacity for the namespace in Temporal Resource Units.
        // Can be different from the requested capacity in latest_request if the request is still in progress.
        double current_value = 1;
    }

    message Request {
        // The current state of the capacity request (e.g. in-progress, completed, failed).
        State state = 1;
        // The date and time when the capacity request was created.
        google.protobuf.Timestamp start_time = 2;
        // The date and time when the capacity request was completed or failed.
        google.protobuf.Timestamp end_time = 3;
        // The id of the async operation that is creating/updating/deleting the capacity, if any.
        string async_operation_id = 4;
        // The requested capacity specification.
        CapacitySpec spec = 5;

        enum State {
            STATE_CAPACITY_REQUEST_UNSPECIFIED = 0;
            STATE_CAPACITY_REQUEST_COMPLETED = 1;
            STATE_CAPACITY_REQUEST_IN_PROGRESS = 2;
            STATE_CAPACITY_REQUEST_FAILED = 3;
        }
    }

    // The latest requested capacity for the namespace, if any.
    Request latest_request = 3;
}

message FairnessSpec {
    // Flag to enable task queue fairness for the namespace (default: disabled).
    bool task_queue_fairness_enabled = 1;
}

message NamespaceSpec {
    // The name to use for the namespace.
    // This will create a namespace that's available at '<name>.<account>.tmprl.cloud:7233'.
    // The name is immutable. Once set, it cannot be changed.
    string name = 1;
    // The ids of the regions where the namespace should be available.
    // The GetRegions API can be used to get the list of valid region ids.
    // Specifying more than one region makes the namespace "global", which is currently a preview only feature with restricted access.
    // Please reach out to Temporal support for more information on global namespaces.
    // When provisioned the global namespace will be active on the first region in the list and passive on the rest.
    // Number of supported regions is 2.
    // The regions is immutable. Once set, it cannot be changed.
    // Example: ["aws-us-west-2"].
    // Deprecated: Use replicas field instead.
    // temporal:versioning:max_version=v0.15.0
    repeated string regions = 2 [deprecated = true];
    // The number of days the workflows data will be retained for.
    // Changes to the retention period may impact your storage costs.
    // Any changes to the retention period will be applied to all new running workflows.
    int32 retention_days = 3;
    // The mTLS auth configuration for the namespace.
    // If unspecified, mTLS will be disabled.
    MtlsAuthSpec mtls_auth = 4;
    // The API key auth configuration for the namespace.
    // If unspecified, API keys will be disabled.
    // temporal:versioning:min_version=v0.2.0
    ApiKeyAuthSpec api_key_auth = 7;
    // The custom search attributes to use for the namespace.
    // The name of the attribute is the key and the type is the value.
    // Supported attribute types: text, keyword, int, double, bool, datetime, keyword_list.
    // NOTE: currently deleting a search attribute is not supported.
    // Optional, default is empty.
    // Deprecated: Not supported after v0.3.0 api version. Use search_attributes instead.
    // temporal:versioning:max_version=v0.3.0
    map<string, string> custom_search_attributes = 5 [deprecated = true];
    // The custom search attributes to use for the namespace.
    // The name of the attribute is the key and the type is the value.
    // Note: currently deleting a search attribute is not supported.
    // Optional, default is empty.
    // temporal:versioning:min_version=v0.3.0
    // temporal:enums:replaces=custom_search_attributes
    map<string, SearchAttributeType> search_attributes = 8;
    // Codec server spec used by UI to decode payloads for all users interacting with this namespace.
    // Optional, default is unset.
    CodecServerSpec codec_server = 6;

    // The lifecycle configuration for the namespace.
    // temporal:versioning:min_version=v0.4.0
    LifecycleSpec lifecycle = 9;

    // The high availability configuration for the namespace.
    // temporal:versioning:min_version=v0.4.0
    HighAvailabilitySpec high_availability = 10;

    // The private connectivity configuration for the namespace.
    // This will apply the connectivity rules specified to the namespace.
    // temporal:versioning:min_version=v0.6.0
    repeated string connectivity_rule_ids = 11;

    // The capacity configuration for the namespace.
    // There are two capacity modes: on-demand and provisioned.
    // On-demand capacity mode allows the namespace to scale automatically based on usage.
    // Provisioned capacity mode allows the user to specify a fixed amount of capacity (in TRUs) for the namespace.
    // Can be changed only when the last capacity request is not in progress.
    // temporal:versioning:min_version=v0.10.0
    CapacitySpec capacity_spec = 12;

    // The replication configuration for the namespace.
    // At least one replica must be specified.
    // Only one replica can be marked to be the desired active one.
    // The status of each replica is available in the Namespace.replicas field.
    // Use HighAvailabilitySpec to set the preferred primary replica ID.
    // If the preferred primary replica ID is not set, the first replica in this replicas list will be the preferred primary.
    // temporal:versioning:min_version=v0.13.0
    repeated ReplicaSpec replicas = 13;

    // The fairness configuration for the namespace.
    // If unspecified, fairness features will be disabled.
    // temporal:versioning:min_version=v0.14.0
    FairnessSpec fairness = 14;

    enum SearchAttributeType {
        SEARCH_ATTRIBUTE_TYPE_UNSPECIFIED = 0;
        SEARCH_ATTRIBUTE_TYPE_TEXT = 1;
        SEARCH_ATTRIBUTE_TYPE_KEYWORD = 2;
        SEARCH_ATTRIBUTE_TYPE_INT = 3;
        SEARCH_ATTRIBUTE_TYPE_DOUBLE = 4;
        SEARCH_ATTRIBUTE_TYPE_BOOL = 5;
        SEARCH_ATTRIBUTE_TYPE_DATETIME = 6;
        SEARCH_ATTRIBUTE_TYPE_KEYWORD_LIST = 7;
    }
}

message Endpoints {
    // The web UI address.
    string web_address = 1;
    // The gRPC address for mTLS client connections (may be empty if mTLS is disabled).
    string mtls_grpc_address = 2;
    // The gRPC address for API key client connections (may be empty if API keys are disabled).
    string grpc_address = 3;
}

message Limits {
    // The number of actions per second (APS) that is currently allowed for the namespace.
    // The namespace may be throttled if its APS exceeds the limit.
    int32 actions_per_second_limit = 1;
}

message AWSPrivateLinkInfo {
    // The list of principal arns that are allowed to access the namespace on the private link.
    repeated string allowed_principal_arns = 1;
    // The list of vpc endpoint service names that are associated with the namespace.
    repeated string vpc_endpoint_service_names = 2;
}


message PrivateConnectivity {
    // The id of the region where the private connectivity applies.
    string region = 1;
    // The AWS PrivateLink info.
    // This will only be set for an aws region.
    AWSPrivateLinkInfo aws_private_link = 2;
}

message Namespace {
    // The namespace identifier.
    string namespace = 1;
    // The current version of the namespace specification.
    // The next update operation will have to include this version.
    string resource_version = 2;
    // The namespace specification.
    NamespaceSpec spec = 3;
    // The current state of the namespace.
    // Deprecated: Not supported after v0.3.0 api version. Use state instead.
    // temporal:versioning:max_version=v0.3.0
    string state_deprecated = 4 [deprecated = true];
    // The current state of the namespace.
    // For any failed state, reach out to Temporal Cloud support for remediation.
    // temporal:versioning:min_version=v0.3.0
    // temporal:enums:replaces=state_deprecated
    temporal.api.cloud.resource.v1.ResourceState state = 13;
    // The id of the async operation that is creating/updating/deleting the namespace, if any.
    string async_operation_id = 5;
    // The endpoints for the namespace.
    Endpoints endpoints = 6;
    // The currently active region for the namespace.
    string active_region = 7;
    // The limits set on the namespace currently.
    Limits limits = 8;
    // The private connectivities for the namespace, if any.
    repeated PrivateConnectivity private_connectivities = 9;
    // The date and time when the namespace was created.
    google.protobuf.Timestamp created_time = 10;
    // The date and time when the namespace was last modified.
    // Will not be set if the namespace has never been modified.
    google.protobuf.Timestamp last_modified_time = 11;
    // The status of each region where the namespace is available.
    // The id of the region is the key and the status is the value of the map.
    // deprecated: Use replicas field instead.
    // temporal:versioning:max_version=v0.15.0
    map<string, NamespaceRegionStatus> region_status = 12 [deprecated = true];
    // The connectivity rules that are set on this namespace.
    repeated temporal.api.cloud.connectivityrule.v1.ConnectivityRule connectivity_rules = 14;
    // The tags for the namespace.
    map<string, string> tags = 15;
    // The status of namespace's capacity, if any.
    Capacity capacity = 16;
    // The status of each replica where the namespace is available.
    // temporal:versioning:min_version=v0.13.0
    repeated Replica replicas = 18;
}

message NamespaceRegionStatus {
    // The current state of the namespace region.
    // Possible values: adding, active, passive, removing, failed.
    // For any failed state, reach out to Temporal Cloud support for remediation.
    // Deprecated: Not supported after v0.3.0 api version. Use state instead.
    // temporal:versioning:max_version=v0.3.0
    string state_deprecated = 1 [deprecated = true];
    // The current state of the namespace region.
    // temporal:versioning:min_version=v0.3.0
    // temporal:enums:replaces=state_deprecated
    State state = 3;
    // The id of the async operation that is making changes to where the namespace is available, if any.
    string async_operation_id = 2;

    enum State {
        STATE_UNSPECIFIED = 0;
        STATE_ADDING= 1;     	// The region is being added to the namespace.
        STATE_ACTIVE= 2;        // The namespace is active in this region.
        STATE_PASSIVE = 3;      // The namespace is passive in this region.
        STATE_REMOVING = 4;     // The region is being removed from the namespace.
        STATE_FAILED = 5;       // The region failed to be added/removed, check failure_reason in the last async_operation status for more details.
    }
}

message ExportSinkSpec {
    // The unique name of the export sink, it can't be changed once set.
    string name = 1;

    // A flag indicating whether the export sink is enabled or not.
    bool enabled = 2;

    // The S3 configuration details when destination_type is S3.
    temporal.api.cloud.sink.v1.S3Spec s3 = 3;

    // This is a feature under development. We will allow GCS sink support for GCP Namespaces.
    // The GCS configuration details when destination_type is GCS.
    temporal.api.cloud.sink.v1.GCSSpec gcs = 4;
}

message ExportSink {
    // The unique name of the export sink, once set it can't be changed
    string name = 1;

    // The version of the export sink resource.
    string resource_version = 2;

    // The current state of the export sink.
    temporal.api.cloud.resource.v1.ResourceState state = 3;

    // The specification details of the export sink.
    ExportSinkSpec spec = 4;

    // The health status of the export sink.
    Health health = 5;

    // An error message describing any issues with the export sink, if applicable.
    string error_message = 6;

    // The timestamp of the latest successful data export.
    google.protobuf.Timestamp latest_data_export_time = 7;

    // The timestamp of the last health check performed on the export sink.
    google.protobuf.Timestamp last_health_check_time = 8;

    enum Health {
        HEALTH_UNSPECIFIED = 0;
        HEALTH_OK = 1;
        HEALTH_ERROR_INTERNAL = 2;
        HEALTH_ERROR_USER_CONFIGURATION = 3;
    }
}

// NamespaceCapacityInfo contains detailed capacity information for a namespace.
message NamespaceCapacityInfo {
  // The namespace identifier.
  string namespace = 1;

  // Whether the namespace's APS limit was set by Temporal Support.
  // When true, adjusting the namespace's capacity will reset this limit.
  bool has_legacy_limits = 2;

  // The current capacity of the namespace.
  // Includes the current mode (on-demand or provisioned) and latest request status.
  Capacity current_capacity = 3;

  // Available capacity mode options for this namespace.
  // Contains configuration limits for both provisioned and on-demand modes.
  CapacityModeOptions mode_options = 4;

  // Usage statistics for the namespace over the last 7 days.
  // Used to calculate On-Demand capacity limits, also useful for capacity planning.
  Stats stats = 5;

  message CapacityModeOptions {
    // Provisioned capacity options and entitlements.
    Provisioned provisioned = 1;

    // On-Demand capacity information.
    OnDemand on_demand = 2;

    message Provisioned {
      // The valid TRU (Temporal Resource Unit) values that can be set.
      // These are the discrete capacity tiers available for selection.
      repeated double valid_tru_values = 1;

      // The maximum TRU value that can currently be set for this namespace.
      // This may be lower than the highest value in valid_tru_values due to
      // inventory constraints.
      double max_available_tru_value = 2;
    }

    message OnDemand {
      // The APS limit that would apply to this namespace in on-demand mode.
      // See: https://docs.temporal.io/cloud/limits#actions-per-second
      double aps_limit = 1;
    }
  }

  message Stats {
    // Actions-per-second measurements summarized over the last 7 days.
    Summary aps = 1;

    message Summary {
      double mean = 1;
      double p90 = 2;
      double p99 = 3;
    }
  }
}
