google-cloud-tasks 0.5.0 → 0.6.0

data/lib/google/cloud/tasks/v2/doc/google/protobuf/timestamp.rb

@@ -0,0 +1,109 @@
+# 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 Google
+  module Protobuf
+    # A Timestamp represents a point in time independent of any time zone
+    # or calendar, represented as seconds and fractions of seconds at
+    # nanosecond resolution in UTC Epoch time. It is encoded using the
+    # Proleptic Gregorian Calendar which extends the Gregorian calendar
+    # backwards to year one. It is encoded assuming all minutes are 60
+    # seconds long, i.e. leap seconds are "smeared" so that no leap second
+    # table is needed for interpretation. Range is from
+    # 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.
+    # By restricting to that range, we ensure that we can convert to
+    # and from  RFC 3339 date strings.
+    # See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).
+    #
+    # = Examples
+    #
+    # Example 1: Compute Timestamp from POSIX `time()`.
+    #
+    #     Timestamp timestamp;
+    #     timestamp.set_seconds(time(NULL));
+    #     timestamp.set_nanos(0);
+    #
+    # Example 2: Compute Timestamp from POSIX `gettimeofday()`.
+    #
+    #     struct timeval tv;
+    #     gettimeofday(&tv, NULL);
+    #
+    #     Timestamp timestamp;
+    #     timestamp.set_seconds(tv.tv_sec);
+    #     timestamp.set_nanos(tv.tv_usec * 1000);
+    #
+    # Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.
+    #
+    #     FILETIME ft;
+    #     GetSystemTimeAsFileTime(&ft);
+    #     UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
+    #
+    #     // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
+    #     // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
+    #     Timestamp timestamp;
+    #     timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
+    #     timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));
+    #
+    # Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.
+    #
+    #     long millis = System.currentTimeMillis();
+    #
+    #     Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
+    #         .setNanos((int) ((millis % 1000) * 1000000)).build();
+    #
+    #
+    # Example 5: Compute Timestamp from current time in Python.
+    #
+    #     timestamp = Timestamp()
+    #     timestamp.GetCurrentTime()
+    #
+    # = JSON Mapping
+    #
+    # In JSON format, the Timestamp type is encoded as a string in the
+    # [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the
+    # format is "\\{year}-\\{month}-\\{day}T\\{hour}:\\{min}:\\{sec}[.\\{frac_sec}]Z"
+    # where \\{year} is always expressed using four digits while \\{month}, \\{day},
+    # \\{hour}, \\{min}, and \\{sec} are zero-padded to two digits each. The fractional
+    # seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),
+    # are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone
+    # is required. A proto3 JSON serializer should always use UTC (as indicated by
+    # "Z") when printing the Timestamp type and a proto3 JSON parser should be
+    # able to accept both UTC and other timezones (as indicated by an offset).
+    #
+    # For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past
+    # 01:30 UTC on January 15, 2017.
+    #
+    # In JavaScript, one can convert a Date object to this format using the
+    # standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]
+    # method. In Python, a standard `datetime.datetime` object can be converted
+    # to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime)
+    # with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one
+    # can use the Joda Time's [`ISODateTimeFormat.dateTime()`](
+    # http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--
+    # ) to obtain a formatter capable of generating timestamps in this format.
+    # @!attribute [rw] seconds
+    #   @return [Integer]
+    #     Represents seconds of UTC time since Unix epoch
+    #     1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
+    #     9999-12-31T23:59:59Z inclusive.
+    # @!attribute [rw] nanos
+    #   @return [Integer]
+    #     Non-negative fractions of a second at nanosecond resolution. Negative
+    #     second values with fractions must still have non-negative nanos values
+    #     that count forward in time. Must be from 0 to 999,999,999
+    #     inclusive.
+    class Timestamp; end
+  end
+end

data/lib/google/cloud/tasks/v2/doc/google/rpc/status.rb

@@ -0,0 +1,87 @@
+# 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 Google
+  module Rpc
+    # The `Status` type defines a logical error model that is suitable for
+    # different programming environments, including REST APIs and RPC APIs. It is
+    # used by [gRPC](https://github.com/grpc). The error model is designed to be:
+    #
+    # * Simple to use and understand for most users
+    # * Flexible enough to meet unexpected needs
+    #
+    # = Overview
+    #
+    # The `Status` message contains three pieces of data: error code, error
+    # message, and error details. The error code should be an enum value of
+    # {Google::Rpc::Code}, but it may accept additional error codes
+    # if needed.  The error message should be a developer-facing English message
+    # that helps developers *understand* and *resolve* the error. If a localized
+    # user-facing error message is needed, put the localized message in the error
+    # details or localize it in the client. The optional error details may contain
+    # arbitrary information about the error. There is a predefined set of error
+    # detail types in the package `google.rpc` that can be used for common error
+    # conditions.
+    #
+    # = Language mapping
+    #
+    # The `Status` message is the logical representation of the error model, but it
+    # is not necessarily the actual wire format. When the `Status` message is
+    # exposed in different client libraries and different wire protocols, it can be
+    # mapped differently. For example, it will likely be mapped to some exceptions
+    # in Java, but more likely mapped to some error codes in C.
+    #
+    # = Other uses
+    #
+    # The error model and the `Status` message can be used in a variety of
+    # environments, either with or without APIs, to provide a
+    # consistent developer experience across different environments.
+    #
+    # Example uses of this error model include:
+    #
+    # * Partial errors. If a service needs to return partial errors to the client,
+    #   it may embed the `Status` in the normal response to indicate the partial
+    #   errors.
+    #
+    # * Workflow errors. A typical workflow has multiple steps. Each step may
+    #   have a `Status` message for error reporting.
+    #
+    # * Batch operations. If a client uses batch request and batch response, the
+    #   `Status` message should be used directly inside batch response, one for
+    #   each error sub-response.
+    #
+    # * Asynchronous operations. If an API call embeds asynchronous operation
+    #   results in its response, the status of those operations should be
+    #   represented directly using the `Status` message.
+    #
+    # * Logging. If some API errors are stored in logs, the message `Status` could
+    #   be used directly after any stripping needed for security/privacy reasons.
+    # @!attribute [rw] code
+    #   @return [Integer]
+    #     The status code, which should be an enum value of
+    #     {Google::Rpc::Code}.
+    # @!attribute [rw] message
+    #   @return [String]
+    #     A developer-facing error message, which should be in English. Any
+    #     user-facing error message should be localized and sent in the
+    #     {Google::Rpc::Status#details} field, or localized
+    #     by the client.
+    # @!attribute [rw] details
+    #   @return [Array<Google::Protobuf::Any>]
+    #     A list of messages that carry the error details.  There is a common set of
+    #     message types for APIs to use.
+    class Status; end
+  end
+end

data/lib/google/cloud/tasks/v2/helpers.rb

@@ -0,0 +1,56 @@
+# Copyright 2018 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 Google
+  module Cloud
+    module Tasks
+      module V2
+        class CloudTasksClient
+          # Alias for Google::Cloud::Tasks::V2::CloudTasksClient.location_path.
+          # @param project [String]
+          # @param location [String]
+          # @return [String]
+          def location_path project, location
+            self.class.location_path project, location
+          end
+          
+          # Alias for Google::Cloud::Tasks::V2::CloudTasksClient.project_path.
+          # @param project [String]
+          # @return [String]
+          def project_path project
+            self.class.project_path project
+          end
+          
+          # Alias for Google::Cloud::Tasks::V2::CloudTasksClient.queue_path.
+          # @param project [String]
+          # @param location [String]
+          # @param queue [String]
+          # @return [String]
+          def queue_path project, location, queue
+            self.class.queue_path project, location, queue
+          end
+          
+          # Alias for Google::Cloud::Tasks::V2::CloudTasksClient.task_path.
+          # @param project [String]
+          # @param location [String]
+          # @param queue [String]
+          # @param task [String]
+          # @return [String]
+          def task_path project, location, queue, task
+            self.class.task_path project, location, queue, task
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/tasks/v2/queue_pb.rb

@@ -0,0 +1,51 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: google/cloud/tasks/v2/queue.proto
+
+
+require 'google/protobuf'
+
+require 'google/api/annotations_pb'
+require 'google/cloud/tasks/v2/target_pb'
+require 'google/protobuf/duration_pb'
+require 'google/protobuf/timestamp_pb'
+Google::Protobuf::DescriptorPool.generated_pool.build do
+  add_message "google.cloud.tasks.v2.Queue" do
+    optional :name, :string, 1
+    optional :app_engine_routing_override, :message, 2, "google.cloud.tasks.v2.AppEngineRouting"
+    optional :rate_limits, :message, 3, "google.cloud.tasks.v2.RateLimits"
+    optional :retry_config, :message, 4, "google.cloud.tasks.v2.RetryConfig"
+    optional :state, :enum, 5, "google.cloud.tasks.v2.Queue.State"
+    optional :purge_time, :message, 6, "google.protobuf.Timestamp"
+  end
+  add_enum "google.cloud.tasks.v2.Queue.State" do
+    value :STATE_UNSPECIFIED, 0
+    value :RUNNING, 1
+    value :PAUSED, 2
+    value :DISABLED, 3
+  end
+  add_message "google.cloud.tasks.v2.RateLimits" do
+    optional :max_dispatches_per_second, :double, 1
+    optional :max_burst_size, :int32, 2
+    optional :max_concurrent_dispatches, :int32, 3
+  end
+  add_message "google.cloud.tasks.v2.RetryConfig" do
+    optional :max_attempts, :int32, 1
+    optional :max_retry_duration, :message, 2, "google.protobuf.Duration"
+    optional :min_backoff, :message, 3, "google.protobuf.Duration"
+    optional :max_backoff, :message, 4, "google.protobuf.Duration"
+    optional :max_doublings, :int32, 5
+  end
+end
+
+module Google
+  module Cloud
+    module Tasks
+      module V2
+        Queue = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.tasks.v2.Queue").msgclass
+        Queue::State = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.tasks.v2.Queue.State").enummodule
+        RateLimits = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.tasks.v2.RateLimits").msgclass
+        RetryConfig = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.tasks.v2.RetryConfig").msgclass
+      end
+    end
+  end
+end

data/lib/google/cloud/tasks/v2/target_pb.rb

@@ -0,0 +1,44 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: google/cloud/tasks/v2/target.proto
+
+
+require 'google/protobuf'
+
+require 'google/api/annotations_pb'
+Google::Protobuf::DescriptorPool.generated_pool.build do
+  add_message "google.cloud.tasks.v2.AppEngineHttpRequest" do
+    optional :http_method, :enum, 1, "google.cloud.tasks.v2.HttpMethod"
+    optional :app_engine_routing, :message, 2, "google.cloud.tasks.v2.AppEngineRouting"
+    optional :relative_uri, :string, 3
+    map :headers, :string, :string, 4
+    optional :body, :bytes, 5
+  end
+  add_message "google.cloud.tasks.v2.AppEngineRouting" do
+    optional :service, :string, 1
+    optional :version, :string, 2
+    optional :instance, :string, 3
+    optional :host, :string, 4
+  end
+  add_enum "google.cloud.tasks.v2.HttpMethod" do
+    value :HTTP_METHOD_UNSPECIFIED, 0
+    value :POST, 1
+    value :GET, 2
+    value :HEAD, 3
+    value :PUT, 4
+    value :DELETE, 5
+    value :PATCH, 6
+    value :OPTIONS, 7
+  end
+end
+
+module Google
+  module Cloud
+    module Tasks
+      module V2
+        AppEngineHttpRequest = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.tasks.v2.AppEngineHttpRequest").msgclass
+        AppEngineRouting = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.tasks.v2.AppEngineRouting").msgclass
+        HttpMethod = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.tasks.v2.HttpMethod").enummodule
+      end
+    end
+  end
+end

data/lib/google/cloud/tasks/v2/task_pb.rb

@@ -0,0 +1,50 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: google/cloud/tasks/v2/task.proto
+
+
+require 'google/protobuf'
+
+require 'google/api/annotations_pb'
+require 'google/cloud/tasks/v2/target_pb'
+require 'google/protobuf/duration_pb'
+require 'google/protobuf/timestamp_pb'
+require 'google/rpc/status_pb'
+Google::Protobuf::DescriptorPool.generated_pool.build do
+  add_message "google.cloud.tasks.v2.Task" do
+    optional :name, :string, 1
+    optional :schedule_time, :message, 4, "google.protobuf.Timestamp"
+    optional :create_time, :message, 5, "google.protobuf.Timestamp"
+    optional :dispatch_deadline, :message, 6, "google.protobuf.Duration"
+    optional :dispatch_count, :int32, 7
+    optional :response_count, :int32, 8
+    optional :first_attempt, :message, 9, "google.cloud.tasks.v2.Attempt"
+    optional :last_attempt, :message, 10, "google.cloud.tasks.v2.Attempt"
+    optional :view, :enum, 11, "google.cloud.tasks.v2.Task.View"
+    oneof :message_type do
+      optional :app_engine_http_request, :message, 2, "google.cloud.tasks.v2.AppEngineHttpRequest"
+    end
+  end
+  add_enum "google.cloud.tasks.v2.Task.View" do
+    value :VIEW_UNSPECIFIED, 0
+    value :BASIC, 1
+    value :FULL, 2
+  end
+  add_message "google.cloud.tasks.v2.Attempt" do
+    optional :schedule_time, :message, 1, "google.protobuf.Timestamp"
+    optional :dispatch_time, :message, 2, "google.protobuf.Timestamp"
+    optional :response_time, :message, 3, "google.protobuf.Timestamp"
+    optional :response_status, :message, 4, "google.rpc.Status"
+  end
+end
+
+module Google
+  module Cloud
+    module Tasks
+      module V2
+        Task = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.tasks.v2.Task").msgclass
+        Task::View = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.tasks.v2.Task.View").enummodule
+        Attempt = Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.tasks.v2.Attempt").msgclass
+      end
+    end
+  end
+end

data/lib/google/cloud/tasks/v2.rb

@@ -0,0 +1,139 @@
+# 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 "google/cloud/tasks/v2/cloud_tasks_client"
+require "google/cloud/tasks/v2/helpers"
+
+module Google
+  module Cloud
+    module Tasks
+      # rubocop:disable LineLength
+
+      ##
+      # # Ruby Client for Cloud Tasks API ([Alpha](https://github.com/googleapis/google-cloud-ruby#versioning))
+      #
+      # [Cloud Tasks API][Product Documentation]:
+      # Manages the execution of large numbers of distributed requests.
+      # - [Product Documentation][]
+      #
+      # ## Quick Start
+      # In order to use this library, you first need to go through the following
+      # steps:
+      #
+      # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+      # 2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
+      # 3. [Enable the Cloud Tasks API.](https://console.cloud.google.com/apis/library/tasks.googleapis.com)
+      # 4. [Setup Authentication.](https://googleapis.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
+      #
+      # ### Installation
+      # ```
+      # $ gem install google-cloud-tasks
+      # ```
+      #
+      # ### Next Steps
+      # - Read the [Cloud Tasks API Product documentation][Product Documentation]
+      #   to learn more about the product and see How-to Guides.
+      # - View this [repository's main README](https://github.com/googleapis/google-cloud-ruby/blob/master/README.md)
+      #   to see the full list of Cloud APIs that we cover.
+      #
+      # [Product Documentation]: https://cloud.google.com/tasks
+      #
+      # ## Enabling Logging
+      #
+      # To enable logging for this library, set the logger for the underlying [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library.
+      # The logger that you set may be a Ruby stdlib [`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as shown below,
+      # or a [`Google::Cloud::Logging::Logger`](https://googleapis.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger)
+      # that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/). See [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
+      # and the gRPC [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb) for additional information.
+      #
+      # Configuring a Ruby stdlib logger:
+      #
+      # ```ruby
+      # require "logger"
+      #
+      # module MyLogger
+      #   LOGGER = Logger.new $stderr, level: Logger::WARN
+      #   def logger
+      #     LOGGER
+      #   end
+      # end
+      #
+      # # Define a gRPC module-level logger method before grpc/logconfig.rb loads.
+      # module GRPC
+      #   extend MyLogger
+      # end
+      # ```
+      #
+      module V2
+        # rubocop:enable LineLength
+
+        ##
+        # Cloud Tasks allows developers to manage the execution of background
+        # work in their applications.
+        #
+        # @param credentials [Google::Auth::Credentials, String, Hash, GRPC::Core::Channel, GRPC::Core::ChannelCredentials, Proc]
+        #   Provides the means for authenticating requests made by the client. This parameter can
+        #   be many types.
+        #   A `Google::Auth::Credentials` uses a the properties of its represented keyfile for
+        #   authenticating requests made by this client.
+        #   A `String` will be treated as the path to the keyfile to be used for the construction of
+        #   credentials for this client.
+        #   A `Hash` will be treated as the contents of a keyfile to be used for the construction of
+        #   credentials for this client.
+        #   A `GRPC::Core::Channel` will be used to make calls through.
+        #   A `GRPC::Core::ChannelCredentials` for the setting up the RPC client. The channel credentials
+        #   should already be composed with a `GRPC::Core::CallCredentials` object.
+        #   A `Proc` will be used as an updater_proc for the Grpc channel. The proc transforms the
+        #   metadata for requests, generally, to give OAuth credentials.
+        # @param scopes [Array<String>]
+        #   The OAuth scopes for this service. This parameter is ignored if
+        #   an updater_proc is supplied.
+        # @param client_config [Hash]
+        #   A Hash for call options for each method. See
+        #   Google::Gax#construct_settings for the structure of
+        #   this data. Falls back to the default config if not specified
+        #   or the specified config is missing data points.
+        # @param timeout [Numeric]
+        #   The default timeout, in seconds, for calls made through this client.
+        # @param metadata [Hash]
+        #   Default metadata to be sent with each request. This can be overridden on a per call basis.
+        # @param exception_transformer [Proc]
+        #   An optional proc that intercepts any exceptions raised during an API call to inject
+        #   custom error handling.
+        def self.new \
+            credentials: nil,
+            scopes: nil,
+            client_config: nil,
+            timeout: nil,
+            metadata: nil,
+            exception_transformer: nil,
+            lib_name: nil,
+            lib_version: nil
+          kwargs = {
+            credentials: credentials,
+            scopes: scopes,
+            client_config: client_config,
+            timeout: timeout,
+            metadata: metadata,
+            exception_transformer: exception_transformer,
+            lib_name: lib_name,
+            lib_version: lib_version
+          }.select { |_, v| v != nil }
+          Google::Cloud::Tasks::V2::CloudTasksClient.new(**kwargs)
+        end
+      end
+    end
+  end
+end