codekingpro/portable-devtools

1// Copyright 2026 Google LLC2//3// Licensed under the Apache License, Version 2.0 (the "License");4// you may not use this file except in compliance with the License.5// You may obtain a copy of the License at6//7//     http://www.apache.org/licenses/LICENSE-2.08//9// Unless required by applicable law or agreed to in writing, software10// distributed under the License is distributed on an "AS IS" BASIS,11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.12// See the License for the specific language governing permissions and13// limitations under the License.14 15syntax = "proto3";16 17package google.api;18 19import "google/api/launch_stage.proto";20import "google/protobuf/descriptor.proto";21import "google/protobuf/duration.proto";22 23option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations";24option java_multiple_files = true;25option java_outer_classname = "ClientProto";26option java_package = "com.google.api";27option objc_class_prefix = "GAPI";28 29extend google.protobuf.MethodOptions {30  // A definition of a client library method signature.31  //32  // In client libraries, each proto RPC corresponds to one or more methods33  // which the end user is able to call, and calls the underlying RPC.34  // Normally, this method receives a single argument (a struct or instance35  // corresponding to the RPC request object). Defining this field will36  // add one or more overloads providing flattened or simpler method signatures37  // in some languages.38  //39  // The fields on the method signature are provided as a comma-separated40  // string.41  //42  // For example, the proto RPC and annotation:43  //44  //     rpc CreateSubscription(CreateSubscriptionRequest)45  //         returns (Subscription) {46  //       option (google.api.method_signature) = "name,topic";47  //     }48  //49  // Would add the following Java overload (in addition to the method accepting50  // the request object):51  //52  //     public final Subscription createSubscription(String name, String topic)53  //54  // The following backwards-compatibility guidelines apply:55  //56  //   * Adding this annotation to an unannotated method is backwards57  //     compatible.58  //   * Adding this annotation to a method which already has existing59  //     method signature annotations is backwards compatible if and only if60  //     the new method signature annotation is last in the sequence.61  //   * Modifying or removing an existing method signature annotation is62  //     a breaking change.63  //   * Re-ordering existing method signature annotations is a breaking64  //     change.65  repeated string method_signature = 1051;66}67 68extend google.protobuf.ServiceOptions {69  // The hostname for this service.70  // This should be specified with no prefix or protocol.71  //72  // Example:73  //74  //     service Foo {75  //       option (google.api.default_host) = "foo.googleapi.com";76  //       ...77  //     }78  string default_host = 1049;79 80  // OAuth scopes needed for the client.81  //82  // Example:83  //84  //     service Foo {85  //       option (google.api.oauth_scopes) = \86  //         "https://www.googleapis.com/auth/cloud-platform";87  //       ...88  //     }89  //90  // If there is more than one scope, use a comma-separated string:91  //92  // Example:93  //94  //     service Foo {95  //       option (google.api.oauth_scopes) = \96  //         "https://www.googleapis.com/auth/cloud-platform,"97  //         "https://www.googleapis.com/auth/monitoring";98  //       ...99  //     }100  string oauth_scopes = 1050;101 102  // The API version of this service, which should be sent by version-aware103  // clients to the service. This allows services to abide by the schema and104  // behavior of the service at the time this API version was deployed.105  // The format of the API version must be treated as opaque by clients.106  // Services may use a format with an apparent structure, but clients must107  // not rely on this to determine components within an API version, or attempt108  // to construct other valid API versions. Note that this is for upcoming109  // functionality and may not be implemented for all services.110  //111  // Example:112  //113  //     service Foo {114  //       option (google.api.api_version) = "v1_20230821_preview";115  //     }116  string api_version = 525000001;117}118 119// Required information for every language.120message CommonLanguageSettings {121  // Link to automatically generated reference documentation.  Example:122  // https://cloud.google.com/nodejs/docs/reference/asset/latest123  string reference_docs_uri = 1 [deprecated = true];124 125  // The destination where API teams want this client library to be published.126  repeated ClientLibraryDestination destinations = 2;127 128  // Configuration for which RPCs should be generated in the GAPIC client.129  //130  // Note: This field should not be used in most cases.131  SelectiveGapicGeneration selective_gapic_generation = 3;132}133 134// Details about how and where to publish client libraries.135message ClientLibrarySettings {136  // Version of the API to apply these settings to. This is the full protobuf137  // package for the API, ending in the version element.138  // Examples: "google.cloud.speech.v1" and "google.spanner.admin.database.v1".139  string version = 1;140 141  // Launch stage of this version of the API.142  LaunchStage launch_stage = 2;143 144  // When using transport=rest, the client request will encode enums as145  // numbers rather than strings.146  bool rest_numeric_enums = 3;147 148  // Settings for legacy Java features, supported in the Service YAML.149  JavaSettings java_settings = 21;150 151  // Settings for C++ client libraries.152  CppSettings cpp_settings = 22;153 154  // Settings for PHP client libraries.155  PhpSettings php_settings = 23;156 157  // Settings for Python client libraries.158  PythonSettings python_settings = 24;159 160  // Settings for Node client libraries.161  NodeSettings node_settings = 25;162 163  // Settings for .NET client libraries.164  DotnetSettings dotnet_settings = 26;165 166  // Settings for Ruby client libraries.167  RubySettings ruby_settings = 27;168 169  // Settings for Go client libraries.170  GoSettings go_settings = 28;171}172 173// This message configures the settings for publishing [Google Cloud Client174// libraries](https://cloud.google.com/apis/docs/cloud-client-libraries)175// generated from the service config.176message Publishing {177  // A list of API method settings, e.g. the behavior for methods that use the178  // long-running operation pattern.179  repeated MethodSettings method_settings = 2;180 181  // Link to a *public* URI where users can report issues.  Example:182  // https://issuetracker.google.com/issues/new?component=190865&template=1161103183  string new_issue_uri = 101;184 185  // Link to product home page.  Example:186  // https://cloud.google.com/asset-inventory/docs/overview187  string documentation_uri = 102;188 189  // Used as a tracking tag when collecting data about the APIs developer190  // relations artifacts like docs, packages delivered to package managers,191  // etc.  Example: "speech".192  string api_short_name = 103;193 194  // GitHub label to apply to issues and pull requests opened for this API.195  string github_label = 104;196 197  // GitHub teams to be added to CODEOWNERS in the directory in GitHub198  // containing source code for the client libraries for this API.199  repeated string codeowner_github_teams = 105;200 201  // A prefix used in sample code when demarking regions to be included in202  // documentation.203  string doc_tag_prefix = 106;204 205  // For whom the client library is being published.206  ClientLibraryOrganization organization = 107;207 208  // Client library settings.  If the same version string appears multiple209  // times in this list, then the last one wins.  Settings from earlier210  // settings with the same version string are discarded.211  repeated ClientLibrarySettings library_settings = 109;212 213  // Optional link to proto reference documentation.  Example:214  // https://cloud.google.com/pubsub/lite/docs/reference/rpc215  string proto_reference_documentation_uri = 110;216 217  // Optional link to REST reference documentation.  Example:218  // https://cloud.google.com/pubsub/lite/docs/reference/rest219  string rest_reference_documentation_uri = 111;220}221 222// Settings for Java client libraries.223message JavaSettings {224  // The package name to use in Java. Clobbers the java_package option225  // set in the protobuf. This should be used **only** by APIs226  // who have already set the language_settings.java.package_name" field227  // in gapic.yaml. API teams should use the protobuf java_package option228  // where possible.229  //230  // Example of a YAML configuration::231  //232  //     publishing:233  //       library_settings:234  //         java_settings:235  //           library_package: com.google.cloud.pubsub.v1236  string library_package = 1;237 238  // Configure the Java class name to use instead of the service's for its239  // corresponding generated GAPIC client. Keys are fully-qualified240  // service names as they appear in the protobuf (including the full241  // the language_settings.java.interface_names" field in gapic.yaml. API242  // teams should otherwise use the service name as it appears in the243  // protobuf.244  //245  // Example of a YAML configuration::246  //247  //     publishing:248  //       java_settings:249  //         service_class_names:250  //           - google.pubsub.v1.Publisher: TopicAdmin251  //           - google.pubsub.v1.Subscriber: SubscriptionAdmin252  map<string, string> service_class_names = 2;253 254  // Some settings.255  CommonLanguageSettings common = 3;256}257 258// Settings for C++ client libraries.259message CppSettings {260  // Some settings.261  CommonLanguageSettings common = 1;262}263 264// Settings for Php client libraries.265message PhpSettings {266  // Some settings.267  CommonLanguageSettings common = 1;268 269  // The package name to use in Php. Clobbers the php_namespace option270  // set in the protobuf. This should be used **only** by APIs271  // who have already set the language_settings.php.package_name" field272  // in gapic.yaml. API teams should use the protobuf php_namespace option273  // where possible.274  //275  // Example of a YAML configuration::276  //277  //     publishing:278  //       library_settings:279  //         php_settings:280  //           library_package: Google\Cloud\PubSub\V1281  string library_package = 2;282}283 284// Settings for Python client libraries.285message PythonSettings {286  // Experimental features to be included during client library generation.287  // These fields will be deprecated once the feature graduates and is enabled288  // by default.289  message ExperimentalFeatures {290    // Enables generation of asynchronous REST clients if `rest` transport is291    // enabled. By default, asynchronous REST clients will not be generated.292    // This feature will be enabled by default 1 month after launching the293    // feature in preview packages.294    bool rest_async_io_enabled = 1;295 296    // Enables generation of protobuf code using new types that are more297    // Pythonic which are included in `protobuf>=5.29.x`. This feature will be298    // enabled by default 1 month after launching the feature in preview299    // packages.300    bool protobuf_pythonic_types_enabled = 2;301 302    // Disables generation of an unversioned Python package for this client303    // library. This means that the module names will need to be versioned in304    // import statements. For example `import google.cloud.library_v2` instead305    // of `import google.cloud.library`.306    bool unversioned_package_disabled = 3;307  }308 309  // Some settings.310  CommonLanguageSettings common = 1;311 312  // Experimental features to be included during client library generation.313  ExperimentalFeatures experimental_features = 2;314}315 316// Settings for Node client libraries.317message NodeSettings {318  // Some settings.319  CommonLanguageSettings common = 1;320}321 322// Settings for Dotnet client libraries.323message DotnetSettings {324  // Some settings.325  CommonLanguageSettings common = 1;326 327  // Map from original service names to renamed versions.328  // This is used when the default generated types329  // would cause a naming conflict. (Neither name is330  // fully-qualified.)331  // Example: Subscriber to SubscriberServiceApi.332  map<string, string> renamed_services = 2;333 334  // Map from full resource types to the effective short name335  // for the resource. This is used when otherwise resource336  // named from different services would cause naming collisions.337  // Example entry:338  // "datalabeling.googleapis.com/Dataset": "DataLabelingDataset"339  map<string, string> renamed_resources = 3;340 341  // List of full resource types to ignore during generation.342  // This is typically used for API-specific Location resources,343  // which should be handled by the generator as if they were actually344  // the common Location resources.345  // Example entry: "documentai.googleapis.com/Location"346  repeated string ignored_resources = 4;347 348  // Namespaces which must be aliased in snippets due to349  // a known (but non-generator-predictable) naming collision350  repeated string forced_namespace_aliases = 5;351 352  // Method signatures (in the form "service.method(signature)")353  // which are provided separately, so shouldn't be generated.354  // Snippets *calling* these methods are still generated, however.355  repeated string handwritten_signatures = 6;356}357 358// Settings for Ruby client libraries.359message RubySettings {360  // Some settings.361  CommonLanguageSettings common = 1;362}363 364// Settings for Go client libraries.365message GoSettings {366  // Some settings.367  CommonLanguageSettings common = 1;368 369  // Map of service names to renamed services. Keys are the package relative370  // service names and values are the name to be used for the service client371  // and call options.372  //373  // Example:374  //375  //     publishing:376  //       go_settings:377  //         renamed_services:378  //           Publisher: TopicAdmin379  map<string, string> renamed_services = 2;380}381 382// Describes the generator configuration for a method.383message MethodSettings {384  // Describes settings to use when generating API methods that use the385  // long-running operation pattern.386  // All default values below are from those used in the client library387  // generators (e.g.388  // [Java](https://github.com/googleapis/gapic-generator-java/blob/04c2faa191a9b5a10b92392fe8482279c4404803/src/main/java/com/google/api/generator/gapic/composer/common/RetrySettingsComposer.java)).389  message LongRunning {390    // Initial delay after which the first poll request will be made.391    // Default value: 5 seconds.392    google.protobuf.Duration initial_poll_delay = 1;393 394    // Multiplier to gradually increase delay between subsequent polls until it395    // reaches max_poll_delay.396    // Default value: 1.5.397    float poll_delay_multiplier = 2;398 399    // Maximum time between two subsequent poll requests.400    // Default value: 45 seconds.401    google.protobuf.Duration max_poll_delay = 3;402 403    // Total polling timeout.404    // Default value: 5 minutes.405    google.protobuf.Duration total_poll_timeout = 4;406  }407 408  // The fully qualified name of the method, for which the options below apply.409  // This is used to find the method to apply the options.410  //411  // Example:412  //413  //     publishing:414  //       method_settings:415  //       - selector: google.storage.control.v2.StorageControl.CreateFolder416  //         # method settings for CreateFolder...417  string selector = 1;418 419  // Describes settings to use for long-running operations when generating420  // API methods for RPCs. Complements RPCs that use the annotations in421  // google/longrunning/operations.proto.422  //423  // Example of a YAML configuration::424  //425  //     publishing:426  //       method_settings:427  //       - selector: google.cloud.speech.v2.Speech.BatchRecognize428  //         long_running:429  //           initial_poll_delay: 60s # 1 minute430  //           poll_delay_multiplier: 1.5431  //           max_poll_delay: 360s # 6 minutes432  //           total_poll_timeout: 54000s # 90 minutes433  LongRunning long_running = 2;434 435  // List of top-level fields of the request message, that should be436  // automatically populated by the client libraries based on their437  // (google.api.field_info).format. Currently supported format: UUID4.438  //439  // Example of a YAML configuration:440  //441  //     publishing:442  //       method_settings:443  //       - selector: google.example.v1.ExampleService.CreateExample444  //         auto_populated_fields:445  //         - request_id446  repeated string auto_populated_fields = 3;447 448  // Batching configuration for an API method in client libraries.449  //450  // Example of a YAML configuration:451  //452  //     publishing:453  //       method_settings:454  //       - selector: google.example.v1.ExampleService.BatchCreateExample455  //         batching:456  //           element_count_threshold: 1000457  //           request_byte_threshold: 100000000458  //           delay_threshold_millis: 10459  BatchingConfigProto batching = 4;460}461 462// The organization for which the client libraries are being published.463// Affects the url where generated docs are published, etc.464enum ClientLibraryOrganization {465  // Not useful.466  CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED = 0;467 468  // Google Cloud Platform Org.469  CLOUD = 1;470 471  // Ads (Advertising) Org.472  ADS = 2;473 474  // Photos Org.475  PHOTOS = 3;476 477  // Street View Org.478  STREET_VIEW = 4;479 480  // Shopping Org.481  SHOPPING = 5;482 483  // Geo Org.484  GEO = 6;485 486  // Generative AI - https://developers.generativeai.google487  GENERATIVE_AI = 7;488}489 490// To where should client libraries be published?491enum ClientLibraryDestination {492  // Client libraries will neither be generated nor published to package493  // managers.494  CLIENT_LIBRARY_DESTINATION_UNSPECIFIED = 0;495 496  // Generate the client library in a repo under github.com/googleapis,497  // but don't publish it to package managers.498  GITHUB = 10;499 500  // Publish the library to package managers like nuget.org and npmjs.com.501  PACKAGE_MANAGER = 20;502}503 504// This message is used to configure the generation of a subset of the RPCs in505// a service for client libraries.506//507// Note: This feature should not be used in most cases.508message SelectiveGapicGeneration {509  // An allowlist of the fully qualified names of RPCs that should be included510  // on public client surfaces.511  repeated string methods = 1;512 513  // Setting this to true indicates to the client generators that methods514  // that would be excluded from the generation should instead be generated515  // in a way that indicates these methods should not be consumed by516  // end users. How this is expressed is up to individual language517  // implementations to decide. Some examples may be: added annotations,518  // obfuscated identifiers, or other language idiomatic patterns.519  bool generate_omitted_as_internal = 2;520}521 522// `BatchingConfigProto` defines the batching configuration for an API method.523message BatchingConfigProto {524  // The thresholds which trigger a batched request to be sent.525  BatchingSettingsProto thresholds = 1;526 527  // The request and response fields used in batching.528  BatchingDescriptorProto batch_descriptor = 2;529}530 531// `BatchingSettingsProto` specifies a set of batching thresholds, each of532// which acts as a trigger to send a batch of messages as a request. At least533// one threshold must be positive nonzero.534message BatchingSettingsProto {535  // The number of elements of a field collected into a batch which, if536  // exceeded, causes the batch to be sent.537  int32 element_count_threshold = 1;538 539  // The aggregated size of the batched field which, if exceeded, causes the540  // batch to be sent. This size is computed by aggregating the sizes of the541  // request field to be batched, not of the entire request message.542  int64 request_byte_threshold = 2;543 544  // The duration after which a batch should be sent, starting from the addition545  // of the first message to that batch.546  google.protobuf.Duration delay_threshold = 3;547 548  // The maximum number of elements collected in a batch that could be accepted549  // by server.550  int32 element_count_limit = 4;551 552  // The maximum size of the request that could be accepted by server.553  int32 request_byte_limit = 5;554 555  // The maximum number of elements allowed by flow control.556  int32 flow_control_element_limit = 6;557 558  // The maximum size of data allowed by flow control.559  int32 flow_control_byte_limit = 7;560 561  // The behavior to take when the flow control limit is exceeded.562  FlowControlLimitExceededBehaviorProto flow_control_limit_exceeded_behavior =563      8;564}565 566// The behavior to take when the flow control limit is exceeded.567enum FlowControlLimitExceededBehaviorProto {568  // Default behavior, system-defined.569  UNSET_BEHAVIOR = 0;570 571  // Stop operation, raise error.572  THROW_EXCEPTION = 1;573 574  // Pause operation until limit clears.575  BLOCK = 2;576 577  // Continue operation, disregard limit.578  IGNORE = 3;579}580 581// `BatchingDescriptorProto` specifies the fields of the request message to be582// used for batching, and, optionally, the fields of the response message to be583// used for demultiplexing.584message BatchingDescriptorProto {585  // The repeated field in the request message to be aggregated by batching.586  string batched_field = 1;587 588  // A list of the fields in the request message. Two requests will be batched589  // together only if the values of every field specified in590  // `request_discriminator_fields` is equal between the two requests.591  repeated string discriminator_fields = 2;592 593  // Optional. When present, indicates the field in the response message to be594  // used to demultiplex the response into multiple response messages, in595  // correspondence with the multiple request messages originally batched596  // together.597  string subresponse_field = 3;598}599