google-cloud-debugger 0.28.2 → 0.29.0

data/lib/google/cloud/debugger/service.rb

@@ -25,37 +25,22 @@ module Google
       # @private Represents the gRPC Debugger service, including all the API
       # methods.
       class Service
-        attr_accessor :project, :credentials, :host, :timeout, :client_config
+        attr_accessor :project, :credentials, :timeout, :client_config
 
         ##
         # Creates a new Service instance.
-        def initialize project, credentials, host: nil, timeout: nil,
-                       client_config: nil
+        def initialize project, credentials, timeout: nil, client_config: nil
           @project = project
           @credentials = credentials
-          @host = host || V2::Controller2Client::SERVICE_ADDRESS
           @timeout = timeout
           @client_config = client_config || {}
         end
 
-        def channel
-          require "grpc"
-          GRPC::Core::Channel.new host, nil, chan_creds
-        end
-
-        def chan_creds
-          return credentials if insecure?
-          require "grpc"
-          GRPC::Core::ChannelCredentials.new.compose \
-            GRPC::Core::CallCredentials.new credentials.client.updater_proc
-        end
-
         def cloud_debugger
           return mocked_debugger if mocked_debugger
           @debugger ||=
             V2::Controller2Client.new(
-              service_path: host,
-              channel: channel,
+              credentials: credentials,
               timeout: timeout,
               client_config: client_config,
               lib_name: "gccl",
@@ -67,8 +52,7 @@ module Google
           return mocked_transmitter if mocked_transmitter
           @transmitter ||=
             V2::Controller2Client.new(
-              service_path: host,
-              channel: channel,
+              credentials: credentials,
               timeout: timeout,
               client_config: client_config,
               lib_name: "gccl",
@@ -76,10 +60,6 @@ module Google
         end
         attr_accessor :mocked_transmitter
 
-        def insecure?
-          credentials == :this_channel_is_insecure
-        end
-
         def register_debuggee debuggee_grpc
           execute do
             cloud_debugger.register_debuggee debuggee_grpc,

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

@@ -1,4 +1,5 @@
 # Copyright 2017, Google Inc. All rights reserved.
+#
 # 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
@@ -13,3 +14,184 @@
 
 require "google/cloud/debugger/v2/debugger2_client"
 require "google/cloud/debugger/v2/controller2_client"
+
+module Google
+  module Cloud
+    # rubocop:disable LineLength
+
+    ##
+    # # Ruby Client for Stackdriver Debugger API ([Alpha](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
+    #
+    # [Stackdriver Debugger API][Product Documentation]:
+    # Examines the call stack and variables of a running application
+    # without stopping or slowing it down.
+    # - [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 the Stackdriver Debugger API.](https://console.cloud.google.com/apis/api/debugger)
+    # 3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
+    #
+    # ### Next Steps
+    # - Read the [Stackdriver Debugger 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/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
+    #   to see the full list of Cloud APIs that we cover.
+    #
+    # [Product Documentation]: https://cloud.google.com/debugger
+    #
+    #
+    module Debugger
+      module V2
+        # rubocop:enable LineLength
+
+        module Debugger2
+          ##
+          # The Debugger service provides the API that allows users to collect run-time
+          # information from a running application, without stopping or slowing it down
+          # and without modifying its state.  An application may include one or
+          # more replicated processes performing the same work.
+          #
+          # A debugged application is represented using the Debuggee concept. The
+          # Debugger service provides a way to query for available debuggees, but does
+          # not provide a way to create one.  A debuggee is created using the Controller
+          # service, usually by running a debugger agent with the application.
+          #
+          # The Debugger service enables the client to set one or more Breakpoints on a
+          # Debuggee and collect the results of the set Breakpoints.
+          #
+          # @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.
+          def self.new \
+              service_path: nil,
+              port: nil,
+              channel: nil,
+              chan_creds: nil,
+              updater_proc: nil,
+              credentials: nil,
+              scopes: nil,
+              client_config: nil,
+              timeout: nil,
+              lib_name: nil,
+              lib_version: nil
+            kwargs = {
+              service_path: service_path,
+              port: port,
+              channel: channel,
+              chan_creds: chan_creds,
+              updater_proc: updater_proc,
+              credentials: credentials,
+              scopes: scopes,
+              client_config: client_config,
+              timeout: timeout,
+              lib_name: lib_name,
+              lib_version: lib_version
+            }.select { |_, v| v != nil }
+            Google::Cloud::Debugger::V2::Debugger2Client.new(**kwargs)
+          end
+        end
+
+        module Controller2
+          ##
+          # The Controller service provides the API for orchestrating a collection of
+          # debugger agents to perform debugging tasks. These agents are each attached
+          # to a process of an application which may include one or more replicas.
+          #
+          # The debugger agents register with the Controller to identify the application
+          # being debugged, the Debuggee. All agents that register with the same data,
+          # represent the same Debuggee, and are assigned the same +debuggee_id+.
+          #
+          # The debugger agents call the Controller to retrieve  the list of active
+          # Breakpoints. Agents with the same +debuggee_id+ get the same breakpoints
+          # list. An agent that can fulfill the breakpoint request updates the
+          # Controller with the breakpoint result. The controller selects the first
+          # result received and discards the rest of the results.
+          # Agents that poll again for active breakpoints will no longer have
+          # the completed breakpoint in the list and should remove that breakpoint from
+          # their attached process.
+          #
+          # The Controller service does not provide a way to retrieve the results of
+          # a completed breakpoint. This functionality is available using the Debugger
+          # service.
+          #
+          # @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.
+          def self.new \
+              service_path: nil,
+              port: nil,
+              channel: nil,
+              chan_creds: nil,
+              updater_proc: nil,
+              credentials: nil,
+              scopes: nil,
+              client_config: nil,
+              timeout: nil,
+              lib_name: nil,
+              lib_version: nil
+            kwargs = {
+              service_path: service_path,
+              port: port,
+              channel: channel,
+              chan_creds: chan_creds,
+              updater_proc: updater_proc,
+              credentials: credentials,
+              scopes: scopes,
+              client_config: client_config,
+              timeout: timeout,
+              lib_name: lib_name,
+              lib_version: lib_version
+            }.select { |_, v| v != nil }
+            Google::Cloud::Debugger::V2::Controller2Client.new(**kwargs)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/debugger/v2/controller2_client.rb

@@ -28,6 +28,7 @@ require "pathname"
 require "google/gax"
 
 require "google/devtools/clouddebugger/v2/controller_pb"
+require "google/cloud/debugger/credentials"
 
 module Google
   module Cloud
@@ -74,21 +75,24 @@ module Google
             "https://www.googleapis.com/auth/cloud_debugger"
           ].freeze
 
-          # @param service_path [String]
-          #   The domain name of the API remote host.
-          # @param port [Integer]
-          #   The port on which to connect to the remote host.
-          # @param channel [Channel]
-          #   A Channel object through which to make calls.
-          # @param chan_creds [Grpc::ChannelCredentials]
-          #   A ChannelCredentials for the setting up the RPC client.
-          # @param updater_proc [Proc]
-          #   A function that transforms the metadata for requests, e.g., to give
-          #   OAuth credentials.
+          # @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]
+          # @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
@@ -101,11 +105,10 @@ module Google
               channel: nil,
               chan_creds: nil,
               updater_proc: nil,
+              credentials: nil,
               scopes: ALL_SCOPES,
               client_config: {},
               timeout: DEFAULT_TIMEOUT,
-              app_name: nil,
-              app_version: nil,
               lib_name: nil,
               lib_version: ""
             # These require statements are intentionally placed here to initialize
@@ -114,14 +117,38 @@ module Google
             require "google/gax/grpc"
             require "google/devtools/clouddebugger/v2/controller_services_pb"
 
+            if channel || chan_creds || updater_proc
+              warn "The `channel`, `chan_creds`, and `updater_proc` parameters will be removed " \
+                "on 2017/09/08"
+              credentials ||= channel
+              credentials ||= chan_creds
+              credentials ||= updater_proc
+            end
+            if service_path != SERVICE_ADDRESS || port != DEFAULT_SERVICE_PORT
+              warn "`service_path` and `port` parameters are deprecated and will be removed"
+            end
+
+            credentials ||= Google::Cloud::Debugger::Credentials.default
 
-            if app_name || app_version
-              warn "`app_name` and `app_version` are no longer being used in the request headers."
+            if credentials.is_a?(String) || credentials.is_a?(Hash)
+              updater_proc = Google::Cloud::Debugger::Credentials.new(credentials).updater_proc
+            end
+            if credentials.is_a?(GRPC::Core::Channel)
+              channel = credentials
+            end
+            if credentials.is_a?(GRPC::Core::ChannelCredentials)
+              chan_creds = credentials
+            end
+            if credentials.is_a?(Proc)
+              updater_proc = credentials
+            end
+            if credentials.is_a?(Google::Auth::Credentials)
+              updater_proc = credentials.updater_proc
             end
 
             google_api_client = "gl-ruby/#{RUBY_VERSION}"
             google_api_client << " #{lib_name}/#{lib_version}" if lib_name
-            google_api_client << " gapic/0.6.8 gax/#{Google::Gax::VERSION}"
+            google_api_client << " gapic/0.1.0 gax/#{Google::Gax::VERSION}"
             google_api_client << " grpc/#{GRPC::VERSION}"
             google_api_client.freeze
 
@@ -168,19 +195,21 @@ module Google
 
           # Registers the debuggee with the controller service.
           #
-          # All agents attached to the same application should call this method with
-          # the same request content to get back the same stable +debuggee_id+. Agents
-          # should call this method again whenever +google.rpc.Code.NOT_FOUND+ is
-          # returned from any controller method.
+          # All agents attached to the same application must call this method with
+          # exactly the same request content to get back the same stable +debuggee_id+.
+          # Agents should call this method again whenever +google.rpc.Code.NOT_FOUND+
+          # is returned from any controller method.
           #
-          # This allows the controller service to disable the agent or recover from any
-          # data loss. If the debuggee is disabled by the server, the response will
-          # have +is_disabled+ set to +true+.
+          # This protocol allows the controller service to disable debuggees, recover
+          # from data loss, or change the +debuggee_id+ format. Agents must handle
+          # +debuggee_id+ value changing upon re-registration.
           #
-          # @param debuggee [Google::Devtools::Clouddebugger::V2::Debuggee]
+          # @param debuggee [Google::Devtools::Clouddebugger::V2::Debuggee | Hash]
           #   Debuggee information to register.
           #   The fields +project+, +uniquifier+, +description+ and +agent_version+
           #   of the debuggee must be set.
+          #   A hash of the same form as `Google::Devtools::Clouddebugger::V2::Debuggee`
+          #   can also be provided.
           # @param options [Google::Gax::CallOptions]
           #   Overrides the default settings for this call, e.g, timeout,
           #   retries, etc.
@@ -189,25 +218,23 @@ module Google
           # @example
           #   require "google/cloud/debugger/v2"
           #
-          #   Controller2Client = Google::Cloud::Debugger::V2::Controller2Client
-          #   Debuggee = Google::Devtools::Clouddebugger::V2::Debuggee
-          #
-          #   controller2_client = Controller2Client.new
-          #   debuggee = Debuggee.new
+          #   controller2_client = Google::Cloud::Debugger::V2::Controller2.new
+          #   debuggee = {}
           #   response = controller2_client.register_debuggee(debuggee)
 
           def register_debuggee \
               debuggee,
               options: nil
-            req = Google::Devtools::Clouddebugger::V2::RegisterDebuggeeRequest.new({
+            req = {
               debuggee: debuggee
-            }.delete_if { |_, v| v.nil? })
+            }.delete_if { |_, v| v.nil? }
+            req = Google::Gax::to_proto(req, Google::Devtools::Clouddebugger::V2::RegisterDebuggeeRequest)
             @register_debuggee.call(req, options)
           end
 
           # Returns the list of all active breakpoints for the debuggee.
           #
-          # The breakpoint specification (location, condition, and expression
+          # The breakpoint specification (+location+, +condition+, and +expressions+
           # fields) is semantically immutable, although the field values may
           # change. For example, an agent may update the location line number
           # to reflect the actual line where the breakpoint was set, but this
@@ -222,16 +249,17 @@ module Google
           # @param debuggee_id [String]
           #   Identifies the debuggee.
           # @param wait_token [String]
-          #   A wait token that, if specified, blocks the method call until the list
-          #   of active breakpoints has changed, or a server selected timeout has
-          #   expired.  The value should be set from the last returned response.
+          #   A token that, if specified, blocks the method call until the list
+          #   of active breakpoints has changed, or a server-selected timeout has
+          #   expired. The value should be set from the +next_wait_token+ field in
+          #   the last response. The initial value should be set to +"init"+.
           # @param success_on_timeout [true, false]
-          #   If set to +true+, returns +google.rpc.Code.OK+ status and sets the
-          #   +wait_expired+ response field to +true+ when the server-selected timeout
-          #   has expired (recommended).
+          #   If set to +true+ (recommended), returns +google.rpc.Code.OK+ status and
+          #   sets the +wait_expired+ response field to +true+ when the server-selected
+          #   timeout has expired.
           #
-          #   If set to +false+, returns +google.rpc.Code.ABORTED+ status when the
-          #   server-selected timeout has expired (deprecated).
+          #   If set to +false+ (deprecated), returns +google.rpc.Code.ABORTED+ status
+          #   when the server-selected timeout has expired.
           # @param options [Google::Gax::CallOptions]
           #   Overrides the default settings for this call, e.g, timeout,
           #   retries, etc.
@@ -240,9 +268,7 @@ module Google
           # @example
           #   require "google/cloud/debugger/v2"
           #
-          #   Controller2Client = Google::Cloud::Debugger::V2::Controller2Client
-          #
-          #   controller2_client = Controller2Client.new
+          #   controller2_client = Google::Cloud::Debugger::V2::Controller2.new
           #   debuggee_id = ''
           #   response = controller2_client.list_active_breakpoints(debuggee_id)
 
@@ -251,29 +277,32 @@ module Google
               wait_token: nil,
               success_on_timeout: nil,
               options: nil
-            req = Google::Devtools::Clouddebugger::V2::ListActiveBreakpointsRequest.new({
+            req = {
               debuggee_id: debuggee_id,
               wait_token: wait_token,
               success_on_timeout: success_on_timeout
-            }.delete_if { |_, v| v.nil? })
+            }.delete_if { |_, v| v.nil? }
+            req = Google::Gax::to_proto(req, Google::Devtools::Clouddebugger::V2::ListActiveBreakpointsRequest)
             @list_active_breakpoints.call(req, options)
           end
 
           # Updates the breakpoint state or mutable fields.
-          # The entire Breakpoint message must be sent back to the controller
-          # service.
+          # The entire Breakpoint message must be sent back to the controller service.
           #
           # Updates to active breakpoint fields are only allowed if the new value
           # does not change the breakpoint specification. Updates to the +location+,
-          # +condition+ and +expression+ fields should not alter the breakpoint
+          # +condition+ and +expressions+ fields should not alter the breakpoint
           # semantics. These may only make changes such as canonicalizing a value
           # or snapping the location to the correct line of code.
           #
           # @param debuggee_id [String]
           #   Identifies the debuggee being debugged.
-          # @param breakpoint [Google::Devtools::Clouddebugger::V2::Breakpoint]
+          # @param breakpoint [Google::Devtools::Clouddebugger::V2::Breakpoint | Hash]
           #   Updated breakpoint information.
-          #   The field 'id' must be set.
+          #   The field +id+ must be set.
+          #   The agent must echo all Breakpoint specification fields in the update.
+          #   A hash of the same form as `Google::Devtools::Clouddebugger::V2::Breakpoint`
+          #   can also be provided.
           # @param options [Google::Gax::CallOptions]
           #   Overrides the default settings for this call, e.g, timeout,
           #   retries, etc.
@@ -282,22 +311,20 @@ module Google
           # @example
           #   require "google/cloud/debugger/v2"
           #
-          #   Breakpoint = Google::Devtools::Clouddebugger::V2::Breakpoint
-          #   Controller2Client = Google::Cloud::Debugger::V2::Controller2Client
-          #
-          #   controller2_client = Controller2Client.new
+          #   controller2_client = Google::Cloud::Debugger::V2::Controller2.new
           #   debuggee_id = ''
-          #   breakpoint = Breakpoint.new
+          #   breakpoint = {}
           #   response = controller2_client.update_active_breakpoint(debuggee_id, breakpoint)
 
           def update_active_breakpoint \
               debuggee_id,
               breakpoint,
               options: nil
-            req = Google::Devtools::Clouddebugger::V2::UpdateActiveBreakpointRequest.new({
+            req = {
               debuggee_id: debuggee_id,
               breakpoint: breakpoint
-            }.delete_if { |_, v| v.nil? })
+            }.delete_if { |_, v| v.nil? }
+            req = Google::Gax::to_proto(req, Google::Devtools::Clouddebugger::V2::UpdateActiveBreakpointRequest)
             @update_active_breakpoint.call(req, options)
           end
         end