googleapis / gapic-generator-cpp

Generate C++ API client libraries from Protocol Buffers.

API Client Generator for C++

A generator and runtime for protocol buffer described APIs for and in C++.

This repository contains two subprojects:

• An API client library generator, implemented as a protoc plugin
• A runtime library supporting the generated code (known as gax)

The generator takes APIs specified by protocol buffers, such as those inside Google, and generates a client library.

Note: this project has been shelved. See STATUS.md for the current status of various features and designs.

Versioning

This library follows Semantic Versioning. Please note it is currently under active development. Any release versioned 0.x.y is subject to backwards-incompatible changes at any time.

GA: Libraries defined at a GA quality level are expected to be stable and all updates in the libraries are guaranteed to be backwards-compatible. Any backwards-incompatible changes will lead to the major version increment (1.x.y -> 2.0.0).

Beta: Libraries defined at a Beta quality level are expected to be mostly stable and we're working towards their release candidate. We will address issues and requests with a higher priority.

Alpha: Libraries defined at an Alpha quality level are still a work-in-progress and are more likely to get backwards-incompatible updates. Additionally, it's possible for Alpha libraries to get deprecated and deleted before ever being promoted to Beta or GA.

Contributing changes

See CONTRIBUTING.md for details on how to contribute to this project, including how to build and test your changes as well as how to properly format your code.

Licensing

Apache 2.0; see LICENSE for details.

gapic-generator-cpp's Issues

Generate gax::Operation returning client methods

Instead of returning raw google::longrunning::Operation and forcing the user to conduct their own typechecking and deserialization, generated clients will provide methods that return gax::Operation. The concrete types are deduced from API proto annotations.

Partition gRPC aware client library components

Tracking issue: in order to better support transport agnosticism and to prevent potentially unnecessary dependencies on gRPC, move gRPC aware code into separate libraries.

Add OperationsStub abstract class

The OperationsStub is a gax owned abstract class that defines methods GetOperation, DeleteOperation, and CancelOperation that are used as part of the LRO method workflow; in particular, GetOperation takes a name referring to an in-flight operation and returns a new operation with the same name. The new operation may have new metadata and may have finished successfully or represent an error.

Add PollingPolicy

PollingPolicy is an interface primitive used to implement the generic Operation polling loop.

Implement LRO poll loop

As part of the future returning LRO client method implementation, provide a generic polling loop that takes a gax::Operation, a polling policy, and an optional metadata handler function and returns a StatusOr that contains either a response object or a failure status.

Implementing this feature depends on #23 and #27

Add tests, impl, and use gax::IdempotencyPolicy

Method idempotency is important when determining whether it is safe to retry a failed operation. IdempotencyPolicy will be an abstract base class and will expose one interface method, CanRetry, and a Clone method, similar to RetryPolicy and BackoffPolicy.

The proposed method signature is:

bool CanRetry(gax::Status const& status, gax::MethodInfo const& info) const;

The reference concrete child class will take a conservative approach to retryability.

Design, implementation, and use of Idempotency

The idempotency of non-GET based API calls is application specific, and advanced users may want to further customize idempotency.

This issue tracks the design of a per-client idempotency policy type, its generation in the generated client code, and its use in the client retry loop for synchronous, unary rpcs.

Partition gRPC aware gax components into a separate library

Tracking issue: in order to facilitate transport agnosticism and prevent potentially unnecessary dependencies on gRPC, the gRPC aware portions of gax will be partitioned into a separate library.

Perform proto file validation before generation

Perform validation before running the generator to make sure input protos are correctly annotated. In cases that they are not, exit with an error. The validation should be tested against the gapic-config-validator for conformance, see https://github.com/googleapis/gapic-config-validator#conformance-testing

Generate future<gax::Operation> returning client methods

Generated clients with long-running methods will have convenience methods that hide the details of gax::Operation and provide background polling, all hidden inside a future object.

Implementing this issue depends on #26 and #23

GAPIC default stubs provide overrides for OperationsStub methods

In order to actually receive updates to LROs, stubs for clients with LRO methods need to provide concrete overrides for {Get,Delete,Cancel}Operation that issues real gRPC calls.

Implementing this feature depends on #30 and #28

All local includes in user-visible gax headers use the gax/ path

To prevent collision with user owned headers with similar names, all gax headers that reference other gax headers should use the gax path in the include.

E.g.

// StatusOr header, status_or.h
#include "status.h"

becomes

// StatusOr header, status_or.h
#include "gax/status.h"

Add rpc timeout awareness to LimitedDurationRetryPolicy

RetryPolicy is responsible for setting the deadlines for individual rpcs in the Setup method. This is independent from any deadline on retry.

Request fails with DEADLINE_EXCEEDED

I have created an example using the vision API here: https://github.com/michaelbausor/gapic-generator-cpp/tree/examples/examples/vision

I would expect the example to succeed - instead it fails with DEADLINE_EXCEEDED.

Steps to reproduce:

• Checkout the example linked above (the examples branch of https://github.com/michaelbausor/gapic-generator-cpp).
• cd examples/vision
• bazel run :vision_gapic_helloworld

Note that you will need to have the GOOGLE_APPLICATION_CREDENTIALS environment variable set.

Enable master branch protection

      This repository does not seem to have master branch
      protection enabled, at least in the way I'm expecting.
      I was hoping for:

      - master branch protection
      - requiring at least one code reviewer
      - requiring at least two status checks
      - enforcing rules for admins

      Please turn it on!

Implement gax::CallContext

CallContext provides a programmable wrapper that hides grpc::ClientContext. It is used for setting rpc deadlines, setting idempotency, adding application specific metadata, and setting other options.

Fix the copyright header in source files

The license in many of the source files refers to Google Inc but should refer to Google LLC.

Make an OperationDeadlinePolicy interface

Setting the per-rpc deadline is sufficiently orthogonal to the purview of the RetryPolicy to merit a separate interface. Something like

class OperationDeadlinePolicy {
 public:
  virtual std::unique_ptr<OperationDeadlinePolicy> clone() const = 0;
  virtual std::chrono::system_clock::time_point Deadline() = 0;
};

template<typename Clock = DefaultClock>
class DefaultOperationDeadlinePolicy : public OperationDeadlinePolicy {
 public:
  template<typename Rep = int64_t, Period = std::milli>
  DefaultOperationDeadlinePolicy(std::chrono::duration<Rep, Period> rpc_duration,
                                                      Clock c = Clock{}) : 
                           duration_(std::chrono::duration_cast<std::chrono::milliseconds>(rpc_duration)), 
                           c_(std::move(c)) {}

  std::chrono::system_clock::time_point Deadline() override {
    return c_.now() + duration_;
  }

 private:
  std::chrono::milliseconds const duration_;
  Clock c_;
};

Add generated types for each LRO response

For each LRO rpc e.g.

rpc GetBigFoo(GetBigFooRequest) returns (google.longrunning.Operation)

generate a using statement for the gax::Operation response in the client and use it in the generated method. E.g.:

using GetBigFooOperation = gax::Operation<Foo, FooMeta>;

This turns this code:

gax::StatusOr<gax::Operation<Foo, FooMeta>> res = client.GetBigFoo(getBigFooRequest);
if (res) {
  gax::Operation<Foo, FooMeta> op = *std::move(res);
}

into this:

gax::StatusOr<GetBigFooOperation> res = client.GetBigFoo(getBigFooRequest);
if (res) {
  GetBigFooOperation op = *std::move(res);
}

This is not only a saving of characters typed, but also ties together the two parameters (result and metadata type) into a single type that describes a particular operation. These parameters and not mix-and-matchable, so it makes sense to treat each possible LRO response as a unit.

Implementation of gax::Operation class

The backbone of LRO methods is gax::Operation. It is responsible for providing type-safe wrappers around google.longrunning.Operation.

Implementing this feature depends on #28

Add const&& variants of operator* and operator-> to gax::StatusOr

There are weird corner cases where the const rvalue variants are necessary.

Use inline namespaces in header files to prevent multi-version dependency errors.

Taken from a PR comment by coryan@ on the PageResult template class in #50 :

For a separate design discussion, you should really consider an inline namespace here. Otherwise you will have ODR violations if any application links two versions of these classes.

Remove java and go dependencies in WORKSPACE file

In order to build the operations proto library (provided by the com_google_googleapis repository) and generate a corresponding C++ library (currently provided by gax) the WORKSPACE file needs to load and set up the java and go repositories from com_google_googleapis. This is a hack and adds unnecessary dependencies.

Tracking bug to remove the hack.

Fix unit test file naming scheme

The correct naming scheme is *_test.cc, not *_unitttest.cc

Add useful, disambiguating namespaces to generated client code

Tracker for adding namespaces to the client and client stub headers and cc files.

Harden camel to snake case converter

Either depend on or copy from an external implementation.