protoc_plugin/protos/client.proto

// 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.api;

import "descriptor.proto";

option go_package = "google.golang.org/genproto/googleapis/api/annotations;annotations";
option java_multiple_files = true;
option java_outer_classname = "ClientProto";
option java_package = "com.google.api";
option objc_class_prefix = "GAPI";

extend google.protobuf.MethodOptions {
  // A definition of a client library method signature.
  //
  // In client libraries, each proto RPC corresponds to one or more methods
  // which the end user is able to call, and calls the underlying RPC.
  // Normally, this method receives a single argument (a struct or instance
  // corresponding to the RPC request object). Defining this field will
  // add one or more overloads providing flattened or simpler method signatures
  // in some languages.
  //
  // The fields on the method signature are provided as a comma-separated
  // string.
  //
  // For example, the proto RPC and annotation:
  //
  //   rpc CreateSubscription(CreateSubscriptionRequest)
  //       returns (Subscription) {
  //     option (google.api.method_signature) = "name,topic";
  //   }
  //
  // Would add the following Java overload (in addition to the method accepting
  // the request object):
  //
  //   public final Subscription createSubscription(String name, String topic)
  //
  // The following backwards-compatibility guidelines apply:
  //
  //   * Adding this annotation to an unannotated method is backwards
  //     compatible.
  //   * Adding this annotation to a method which already has existing
  //     method signature annotations is backwards compatible if and only if
  //     the new method signature annotation is last in the sequence.
  //   * Modifying or removing an existing method signature annotation is
  //     a breaking change.
  //   * Re-ordering existing method signature annotations is a breaking
  //     change.
  repeated string method_signature = 1051;
}

extend google.protobuf.ServiceOptions {
  // The hostname for this service.
  // This should be specified with no prefix or protocol.
  //
  // Example:
  //
  //   service Foo {
  //     option (google.api.default_host) = "foo.googleapi.com";
  //     ...
  //   }
  string default_host = 1049;

  // OAuth scopes needed for the client.
  //
  // Example:
  //
  //   service Foo {
  //     option (google.api.oauth_scopes) = \
  //       "https://www.googleapis.com/auth/cloud-platform";
  //     ...
  //   }
  //
  // If there is more than one scope, use a comma-separated string:
  //
  // Example:
  //
  //   service Foo {
  //     option (google.api.oauth_scopes) = \
  //       "https://www.googleapis.com/auth/cloud-platform,"
  //       "https://www.googleapis.com/auth/monitoring";
  //     ...
  //   }
  string oauth_scopes = 1050;

  // The API version of this service, which should be sent by version-aware
  // clients to the service. This allows services to abide by the schema and
  // behavior of the service at the time this API version was deployed.
  // The format of the API version must be treated as opaque by clients.
  // Services may use a format with an apparent structure, but clients must
  // not rely on this to determine components within an API version, or attempt
  // to construct other valid API versions. Note that this is for upcoming
  // functionality and may not be implemented for all services.
  //
  // Example:
  //
  //   service Foo {
  //     option (google.api.api_version) = "v1_20230821_preview";
  //   }
  string api_version = 525000001;
}

// Required information for every language.
message CommonLanguageSettings {
  // Link to automatically generated reference documentation.  Example:
  // https://cloud.google.com/nodejs/docs/reference/asset/latest
  string reference_docs_uri = 1 [deprecated = true];

  // The destination where API teams want this client library to be published.
  repeated ClientLibraryDestination destinations = 2;

  // Configuration for which RPCs should be generated in the GAPIC client.
  SelectiveGapicGeneration selective_gapic_generation = 3;
}

// This message configures the settings for publishing [Google Cloud Client
// libraries](https://cloud.google.com/apis/docs/cloud-client-libraries)
// generated from the service config.
message Publishing {
  // Link to a *public* URI where users can report issues.  Example:
  // https://issuetracker.google.com/issues/new?component=190865&template=1161103
  string new_issue_uri = 101;

  // Link to product home page.  Example:
  // https://cloud.google.com/asset-inventory/docs/overview
  string documentation_uri = 102;

  // Used as a tracking tag when collecting data about the APIs developer
  // relations artifacts like docs, packages delivered to package managers,
  // etc.  Example: "speech".
  string api_short_name = 103;

  // GitHub label to apply to issues and pull requests opened for this API.
  string github_label = 104;

  // GitHub teams to be added to CODEOWNERS in the directory in GitHub
  // containing source code for the client libraries for this API.
  repeated string codeowner_github_teams = 105;

  // A prefix used in sample code when demarking regions to be included in
  // documentation.
  string doc_tag_prefix = 106;

  // For whom the client library is being published.
  ClientLibraryOrganization organization = 107;

  // Optional link to proto reference documentation.  Example:
  // https://cloud.google.com/pubsub/lite/docs/reference/rpc
  string proto_reference_documentation_uri = 110;

  // Optional link to REST reference documentation.  Example:
  // https://cloud.google.com/pubsub/lite/docs/reference/rest
  string rest_reference_documentation_uri = 111;
}

// Settings for Java client libraries.
message JavaSettings {
  // The package name to use in Java. Clobbers the java_package option
  // set in the protobuf. This should be used **only** by APIs
  // who have already set the language_settings.java.package_name" field
  // in gapic.yaml. API teams should use the protobuf java_package option
  // where possible.
  //
  // Example of a YAML configuration::
  //
  //  publishing:
  //    java_settings:
  //      library_package: com.google.cloud.pubsub.v1
  string library_package = 1;

  // Configure the Java class name to use instead of the service's for its
  // corresponding generated GAPIC client. Keys are fully-qualified
  // service names as they appear in the protobuf (including the full
  // the language_settings.java.interface_names" field in gapic.yaml. API
  // teams should otherwise use the service name as it appears in the
  // protobuf.
  //
  // Example of a YAML configuration::
  //
  //  publishing:
  //    java_settings:
  //      service_class_names:
  //        - google.pubsub.v1.Publisher: TopicAdmin
  //        - google.pubsub.v1.Subscriber: SubscriptionAdmin
  map<string, string> service_class_names = 2;

  // Some settings.
  CommonLanguageSettings common = 3;
}

// Settings for C++ client libraries.
message CppSettings {
  // Some settings.
  CommonLanguageSettings common = 1;
}

// Settings for Php client libraries.
message PhpSettings {
  // Some settings.
  CommonLanguageSettings common = 1;
}

// Settings for Python client libraries.
message PythonSettings {
  // Experimental features to be included during client library generation.
  // These fields will be deprecated once the feature graduates and is enabled
  // by default.
  message ExperimentalFeatures {
    // Enables generation of asynchronous REST clients if `rest` transport is
    // enabled. By default, asynchronous REST clients will not be generated.
    // This feature will be enabled by default 1 month after launching the
    // feature in preview packages.
    bool rest_async_io_enabled = 1;

    // Enables generation of protobuf code using new types that are more
    // Pythonic which are included in `protobuf>=5.29.x`. This feature will be
    // enabled by default 1 month after launching the feature in preview
    // packages.
    bool protobuf_pythonic_types_enabled = 2;

    // Disables generation of an unversioned Python package for this client
    // library. This means that the module names will need to be versioned in
    // import statements. For example `import google.cloud.library_v2` instead
    // of `import google.cloud.library`.
    bool unversioned_package_disabled = 3;
  }

  // Some settings.
  CommonLanguageSettings common = 1;

  // Experimental features to be included during client library generation.
  ExperimentalFeatures experimental_features = 2;
}

// Settings for Node client libraries.
message NodeSettings {
  // Some settings.
  CommonLanguageSettings common = 1;
}

// Settings for Dotnet client libraries.
message DotnetSettings {
  // Some settings.
  CommonLanguageSettings common = 1;

  // Map from original service names to renamed versions.
  // This is used when the default generated types
  // would cause a naming conflict. (Neither name is
  // fully-qualified.)
  // Example: Subscriber to SubscriberServiceApi.
  map<string, string> renamed_services = 2;

  // Map from full resource types to the effective short name
  // for the resource. This is used when otherwise resource
  // named from different services would cause naming collisions.
  // Example entry:
  // "datalabeling.googleapis.com/Dataset": "DataLabelingDataset"
  map<string, string> renamed_resources = 3;

  // List of full resource types to ignore during generation.
  // This is typically used for API-specific Location resources,
  // which should be handled by the generator as if they were actually
  // the common Location resources.
  // Example entry: "documentai.googleapis.com/Location"
  repeated string ignored_resources = 4;

  // Namespaces which must be aliased in snippets due to
  // a known (but non-generator-predictable) naming collision
  repeated string forced_namespace_aliases = 5;

  // Method signatures (in the form "service.method(signature)")
  // which are provided separately, so shouldn't be generated.
  // Snippets *calling* these methods are still generated, however.
  repeated string handwritten_signatures = 6;
}

// Settings for Ruby client libraries.
message RubySettings {
  // Some settings.
  CommonLanguageSettings common = 1;
}

// Settings for Go client libraries.
message GoSettings {
  // Some settings.
  CommonLanguageSettings common = 1;

  // Map of service names to renamed services. Keys are the package relative
  // service names and values are the name to be used for the service client
  // and call options.
  //
  // publishing:
  //   go_settings:
  //     renamed_services:
  //       Publisher: TopicAdmin
  map<string, string> renamed_services = 2;
}

// The organization for which the client libraries are being published.
// Affects the url where generated docs are published, etc.
enum ClientLibraryOrganization {
  // Not useful.
  CLIENT_LIBRARY_ORGANIZATION_UNSPECIFIED = 0;

  // Google Cloud Platform Org.
  CLOUD = 1;

  // Ads (Advertising) Org.
  ADS = 2;

  // Photos Org.
  PHOTOS = 3;

  // Street View Org.
  STREET_VIEW = 4;

  // Shopping Org.
  SHOPPING = 5;

  // Geo Org.
  GEO = 6;

  // Generative AI - https://developers.generativeai.google
  GENERATIVE_AI = 7;
}

// To where should client libraries be published?
enum ClientLibraryDestination {
  // Client libraries will neither be generated nor published to package
  // managers.
  CLIENT_LIBRARY_DESTINATION_UNSPECIFIED = 0;

  // Generate the client library in a repo under github.com/googleapis,
  // but don't publish it to package managers.
  GITHUB = 10;

  // Publish the library to package managers like nuget.org and npmjs.com.
  PACKAGE_MANAGER = 20;
}

// This message is used to configure the generation of a subset of the RPCs in
// a service for client libraries.
message SelectiveGapicGeneration {
  // An allowlist of the fully qualified names of RPCs that should be included
  // on public client surfaces.
  repeated string methods = 1;

  // Setting this to true indicates to the client generators that methods
  // that would be excluded from the generation should instead be generated
  // in a way that indicates these methods should not be consumed by
  // end users. How this is expressed is up to individual language
  // implementations to decide. Some examples may be: added annotations,
  // obfuscated identifiers, or other language idiomatic patterns.
  bool generate_omitted_as_internal = 2;
}