gapic-common 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9019d4ed6928276ec36fa6e06dd95a3674a30ce24635a087e0ebde6abc43cd91
+  data.tar.gz: abaa4c9666268d28dff68a5e2b4379d11f3f442c4fc2a8034e77d226d6f82365
+SHA512:
+  metadata.gz: b58787f5b5b86b8b146a5c2fed6e7a23f7d7dc1498f53a1a4d75163e51f498b0ccbab88bbdd84b8a3f669f1a218ba674f419758b88e4c7f3c5405e5669f9962b
+  data.tar.gz: a04f15b0d04aced9ad2d9918fb6a75305dea59f05b10985618590c3d85ff211bbb88c1ab5d2a64853721685dcf6919c53c546e0b11652eb39374a9d8dd17f844

data/.yardopts

@@ -0,0 +1,13 @@
+--no-private
+--title=GAPIC common library
+--markup markdown
+--markup-provider redcarpet
+--main README.md
+
+./lib/**/*.rb
+-
+CONTRIBUTING.md
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+LICENSE
+README.md

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+# Release History
+

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,43 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project,
+and in the interest of fostering an open and welcoming community,
+we pledge to respect all people who contribute through reporting issues,
+posting feature requests, updating documentation,
+submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project
+a harassment-free experience for everyone,
+regardless of level of experience, gender, gender identity and expression,
+sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information,
+such as physical or electronic
+addresses, without explicit permission
+* Other unethical or unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct.
+By adopting this Code of Conduct,
+project maintainers commit themselves to fairly and consistently
+applying these principles to every aspect of managing this project.
+Project maintainers who do not follow or enforce the Code of Conduct
+may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior
+may be reported by opening an issue
+or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0,
+available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)

data/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# How to Contribute
+
+We'd love to accept your patches and contributions to this project. There are
+just a few small guidelines you need to follow.
+
+## Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution;
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult
+[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
+information on using pull requests.
+
+## Community Guidelines
+
+This project follows [Google's Open Source Community
+Guidelines](https://opensource.google.com/conduct/).

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2019 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
+
+    https://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.

data/README.md

@@ -0,0 +1,40 @@
+Google API Extensions for Ruby
+================================
+
+Generated API Client common code (gapic-common) is a set of modules which aids
+the development of APIs for clients and servers based on [gRPC][] and Google API
+conventions.
+
+Application code will rarely need to use most of the classes within this library
+directly, but code generated automatically from the API definition files in
+[Google APIs][] can use services such as page streaming to provide a more
+convenient and idiomatic API surface to callers.
+
+[gRPC]: http://grpc.io
+[Google APIs]: https://github.com/googleapis/googleapis/
+
+## Supported Ruby Versions
+
+This library is supported on Ruby 2.4+.
+
+Google provides official support for Ruby versions that are actively supported
+by Ruby Core—that is, Ruby versions that are either in normal maintenance or in
+security maintenance, and not end of life. Currently, this means Ruby 2.4 and
+later. Older versions of Ruby _may_ still work, but are unsupported and not
+recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
+about the Ruby support schedule.
+
+## Contributing
+
+Contributions to this library are always welcome and highly encouraged.
+
+See the [CONTRIBUTING](CONTRIBUTING.md) documentation for more information on how to get started.
+
+## Versioning
+
+This library is currently a **preview** with no guarantees of stability or support. Please get
+involved and let us know if you find it useful and we'll work towards a stable version.
+
+## Disclaimer
+
+This is not an official Google product.

data/RELEASING.md

@@ -0,0 +1,76 @@
+# Releasing gapic-common
+
+The Google Ruby GAX project uses [semantic versioning](http://semver.org). Replace the `<prev_version>` and `<version>` placeholders shown in the examples below with the appropriate numbers, e.g. `0.1.0` and `0.2.0`.
+
+After all [pull requests](https://github.com/googleapis/gax-ruby/pulls) for a release have been merged and all [Travis builds](https://travis-ci.org/googleapis/gax-ruby) are green, you may create a release as follows:
+
+1. If you haven't already, switch to the master branch, ensure that you have no changes, and pull from origin.
+
+    ```sh
+    $ git checkout master
+    $ git status
+    $ git pull <remote> master --rebase
+    ```
+
+1. Build the gem locally. (Depending on your environment, you may need to `bundle exec` to rake commands; this will be shown.)
+
+    ```sh
+    $ bundle exec rake build
+    ```
+
+1. Install the gem locally.
+
+    ```sh
+    $ bundle exec rake install
+    ```
+
+1. Using IRB (not `rake console`!), manually test the gem that you installed in the previous step.
+
+1. Update the `CHANGELOG.md`. Write bullet-point lists of the major and minor changes. You can also add examples, fixes, thank yous, and anything else helpful or relevant. See google-cloud-node [v0.18.0](https://github.com/GoogleCloudPlatform/google-cloud-node/releases/tag/v0.18.0) for an example with all the bells and whistles.
+
+1. Edit `lib/gapic/version.rb` file, changing the value of `VERSION` to your new version number. This repo requires a PR for all changes so doing this in a branch is best.
+
+1. Run the tests, one last time.
+
+    ```sh
+    $ bundle update
+    $ bundle exec rake spec
+    ```
+
+1. Commit your changes. Copy and paste the significant points from your `CHANGELOG.md` edit as the description in your commit message.
+
+    ```sh
+    $ git commit -am "Release gapic-common <version> ..."
+    ```
+
+1. Tag the version after all changes have been merged.
+
+    ```sh
+    $ git tag gapic-common/v<version>
+    ```
+
+1. Push the tag.
+
+    ```sh
+    $ git push <remote> gapic-common/v<version>
+    ```
+
+1. Wait until the [Travis build](https://travis-ci.org/googleapis/gax-ruby) has passed for the tag.
+
+1. Push the gem to [RubyGems.org](https://rubygems.org/gems/google-cloud).
+
+   ```sh
+   $ gem push gapic-common-<version>.gem
+   ```
+
+1. On the [gax-ruby releases page](https://github.com/googleapis/gax-ruby/releases), click [Draft a new release](https://github.com/googleapis/gax-ruby/releases/new). Complete the form. Include the bullet-point lists of the major and minor changes from the gem's `CHANGELOG.md`. You can also add examples, fixes, thank yous, and anything else helpful or relevant.
+
+1. Click `Publish release`.
+
+1. Wait until the last tag build job has successfully completed on Travis. Then push your commits to the master branch. This will trigger another [Travis](https://travis-ci.org/googleapis/gax-ruby) build on master branch.
+
+    ```sh
+    $ git push <remote> master
+    ```
+
+High fives all around!

data/lib/gapic-common.rb

@@ -0,0 +1,15 @@
+# Copyright 2019 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
+#
+#     https://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.
+
+require "gapic/common"

data/lib/gapic/call_options.rb

@@ -0,0 +1,68 @@
+# Copyright 2019 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
+#
+#     https://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.
+
+require "gapic/call_options/retry_policy"
+
+module Gapic
+  ##
+  # Encapsulates the overridable settings for a particular RPC call.
+  #
+  # @!attribute [r] timeout
+  #   @return [Numeric, nil]
+  # @!attribute [r] metadata
+  #   @return [Hash]
+  # @!attribute [r] retry_policy
+  #   @return [RetryPolicy, Object]
+  #
+  class CallOptions
+    attr_reader :timeout, :metadata, :retry_policy
+
+    ##
+    # Create a new Options object instance.
+    #
+    # @param timeout [Numeric] The client-side timeout for RPC calls.
+    # @param metadata [Hash] The request header params.
+    # @param retry_policy [Hash, RetryPolicy, Proc] The policy for error retry. A Hash can be provided to
+    #   customize the policy object, using keys that match the arguments for {RetryPolicy.new}.
+    #
+    #   A Proc object can also be provided. The Proc should accept an error as an argument, and return `true` if the
+    #   error should be retried or `false` if not. If the error is to be retried, the Proc object must also block
+    #   with an incremental delay before returning `true`.
+    #
+    def initialize timeout: nil, metadata: nil, retry_policy: nil
+      # Converts hash and nil to a policy object
+      retry_policy = RetryPolicy.new retry_policy.to_h if retry_policy.respond_to? :to_h
+
+      @timeout = timeout # allow to be nil so it can be overridden
+      @metadata = metadata.to_h # Ensure always hash, even for nil
+      @retry_policy = retry_policy
+    end
+
+    ##
+    # @private
+    # Apply default values to the options object. This does not replace user-provided values, it only overrides
+    # empty values.
+    #
+    # @param timeout [Numeric] The client-side timeout for RPC calls.
+    # @param metadata [Hash] the request header params.
+    # @param retry_policy [Hash] the policy for error retry.
+    # @param retry_policy [Hash] The policy for error retry. keys must match the arguments for
+    #   {RetryPolicy.new}.
+    def apply_defaults timeout: nil, metadata: nil, retry_policy: nil
+      @timeout ||= timeout
+      @metadata = metadata.merge @metadata if metadata
+      @retry_policy.apply_defaults retry_policy if @retry_policy.respond_to? :apply_defaults
+    end
+  end
+end

data/lib/gapic/call_options/retry_policy.rb

@@ -0,0 +1,106 @@
+# Copyright 2019 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
+#
+#     https://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.
+
+module Gapic
+  class CallOptions
+    ##
+    # The policy for retrying failed RPC calls using an incremental backoff. A new object instance should be used for
+    # every RpcCall invocation.
+    #
+    # Only errors orginating from GRPC will be retried.
+    #
+    class RetryPolicy
+      ##
+      # Create new API Call RetryPolicy.
+      #
+      # @param initial_delay [Numeric] client-side timeout
+      # @param multiplier [Numeric] client-side timeout
+      # @param max_delay [Numeric] client-side timeout
+      #
+      def initialize retry_codes: nil, initial_delay: nil, multiplier: nil, max_delay: nil
+        @retry_codes   = retry_codes
+        @initial_delay = initial_delay
+        @multiplier    = multiplier
+        @max_delay     = max_delay
+        @delay         = nil
+      end
+
+      def retry_codes
+        @retry_codes || []
+      end
+
+      def initial_delay
+        @initial_delay || 1
+      end
+
+      def multiplier
+        @multiplier || 1.3
+      end
+
+      def max_delay
+        @max_delay || 15
+      end
+
+      ##
+      # The current delay value.
+      def delay
+        @delay || initial_delay
+      end
+
+      def call error
+        return false unless retry? error
+
+        delay!
+        increment_delay!
+
+        true
+      end
+
+      ##
+      # @private
+      # Apply default values to the policy object. This does not replace user-provided values, it only overrides empty
+      # values.
+      #
+      # @param retry_policy [Hash] The policy for error retry. keys must match the arguments for
+      #   {RpcCall::RetryPolicy.new}.
+      def apply_defaults retry_policy
+        return unless retry_policy.is_a? Hash
+
+        @retry_codes   ||= retry_policy[:retry_codes]
+        @initial_delay ||= retry_policy[:initial_delay]
+        @multiplier    ||= retry_policy[:multiplier]
+        @max_delay     ||= retry_policy[:max_delay]
+
+        self
+      end
+
+      private
+
+      def retry? error
+        error.is_a?(GRPC::BadStatus) && retry_codes.include?(error.code)
+      end
+
+      def delay!
+        # Call Kernel.sleep so we can stub it.
+        Kernel.sleep delay
+      end
+
+      ##
+      # Calculate and set the next delay value.
+      def increment_delay!
+        @delay = [delay * multiplier, max_delay].min
+      end
+    end
+  end
+end

data/lib/gapic/common.rb

@@ -0,0 +1,32 @@
+# Copyright 2019 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
+#
+#     https://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.
+
+require "grpc/errors"
+require "grpc/core/status_codes"
+
+require "gapic/call_options"
+require "gapic/headers"
+require "gapic/operation"
+require "gapic/paged_enumerable"
+require "gapic/protobuf"
+require "gapic/stream_input"
+require "gapic/common/version"
+
+# Gapic is Google's API client generator
+module Gapic
+  # The gapic-common gem includes various common libraries for clients built
+  # with Gapic.
+  module Common
+  end
+end