We should release our policy types

[dbolduc]

We define policy types like this:

google-cloud-cpp/google/cloud/accessapproval/access_approval_connection.h

Lines 37 to 39 in 8a2efcf

	using AccessApprovalRetryPolicy =
	::google::cloud::internal::TraitBasedRetryPolicy<
	accessapproval_internal::AccessApprovalRetryTraits>;

This is in violation of https://github.com/googleapis/google-cloud-cpp/blob/main/doc/adr/2022-01-21-only-public-types-in-public-APIs.md

There is no way to learn the interface of this type, other than by looking at the code. (Doxygen does not generate documentation for internal::TraitBasedRetryPolicy<T>)

To allow for customer-defined retry policies, I think we need to release RetryPolicy and TraitBasedRetryPolicy.

[coryan]

Consider this for 2023/Q1.

[coryan]

One alternative is to just generate:

class AccessApprovalRetryPolicy : public google::internal::.... {
 public:
  /// Pretty explanations for Doxygen and friends.
  bool OnFailure(Status const& ...) override { return Base::OnFailure(...); }

};

and then manually do the same for the hand-crafted libraries.

We probably need to write a one pager.

[coryan]

We decided to implement something along these lines:

struct EkmServiceRetryPolicy : public google::cloud::RetryPolicy {
 public:
   /// Documented expectations for this function go here
   virtual std::unique_ptr<EkmServiceRetryPolicy> clone() const = 0;
};

class EkmServiceLimitedTimeRetryPolicy : public EkmServiceRetryPolicy {
 public:
  explicit LimitedErrorCountRetryPolicy(int maximum_failures)
      : impl_(maximum_failures) {}

  std::unique_ptr<EkmServiceRetryPolicy> clone() const override {
    return std::make_unique<EkmServiceLimitedTimeRetryPolicy>(impl_.maximum_failures());
  }
  bool OnFailure(Status const& s) override { return impl_.OnFailure(s); }
  bool IsExhausted() const override { return impl_.IsExhausted(); }
  bool IsPermanentFailure(Status const& s) const override {
    return impl_.IsPermanentFailure(s);
  } 
 private:
   google::cloud::internal::LimitedTimeRetryPolicy<
        kms_v1_internal::EkmServiceRetryTraits> impl_;
};

class EkmServiceLimitedErrorCountRetryPolicy : public EkmServiceRetryPolicy {
// Same idea as above.