google-cloud-debugger 0.40.0

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

@@ -0,0 +1,110 @@
+# Copyright 2017 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/errors"
+require "google/cloud/debugger/agent"
+require "google/cloud/debugger/credentials"
+require "google/cloud/debugger/middleware"
+require "google/cloud/debugger/service"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # Project
+      #
+      # Projects are top-level containers in Google Cloud Platform. They store
+      # information about billing and authorized users, and they control access
+      # to Stackdriver Debugger resources. Each project has a friendly name and
+      # a unique ID. Projects can be created only in the [Google Developers
+      # Console](https://console.developers.google.com).
+      #
+      # @example
+      #   require "google/cloud/debugger"
+      #
+      #   debugger = Google::Cloud::Debugger.new
+      #   debugger.start
+      #
+      # See Google::Cloud#debugger
+      class Project
+        ##
+        # @private The gRPC Service object.
+        attr_accessor :service
+
+        ##
+        # The Stackdriver Debugger Agent object.
+        attr_reader :agent
+
+        ##
+        # @private Creates a new Project instance.
+        def initialize service, service_name:, service_version:
+          @service = service
+          @agent = Agent.new service, service_name: service_name,
+                                      service_version: service_version
+        end
+
+        ##
+        # The ID of the current project.
+        #
+        # @return [String] the Google Cloud project ID
+        #
+        # @example
+        #   require "google/cloud/debugger"
+        #
+        #   debugger = Google::Cloud::Debugger.new(
+        #     project_id: "my-project",
+        #     credentials: "/path/to/keyfile.json"
+        #   )
+        #
+        #   debugger.project_id #=> "my-project"
+        #
+        def project_id
+          service.project
+        end
+        alias project project_id
+
+        ##
+        # Start the Stackdriver Debugger Agent.
+        #
+        # @example
+        #   require "google/cloud/debugger"
+        #
+        #   debugger = Google::Cloud::Debugger.new
+        #   debugger.start
+        #
+        # See {Agent#start} for more details.
+        def start
+          agent.start
+        end
+        alias attach start
+
+        ##
+        # Stop the Stackdriver Debugger Agent.
+        #
+        # @example
+        #   require "google/cloud/debugger"
+        #
+        #   debugger = Google::Cloud::Debugger.new
+        #   debugger.start
+        #   debugger.stop
+        #
+        # See {Agent#stop} for more details.
+        def stop
+          agent.stop
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,174 @@
+# Copyright 2017 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/debugger"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # Railtie
+      #
+      # Google::Cloud::Debugger::Railtie automatically adds the
+      # Google::Cloud::Debugger::Middleware to Rack in a Rails environment.
+      #
+      # The Middleware is only added when the
+      # `Google::Cloud.configure.use_debugger` setting is true or Rails is
+      # in the production environment.
+      #
+      # When loaded, the Google::Cloud::Debugger::Middleware will be inserted
+      # after the Rack::ETag Middleware, which is top of the Rack stack, closest
+      # to the application code.
+      #
+      # The Railtie should also initialize a debugger to be used by the
+      # Middleware. See the [Configuration
+      # Guide](https://googleapis.dev/ruby/stackdriver/latest/file.INSTRUMENTATION_CONFIGURATION.html)
+      # on how to configure the Railtie and Middleware.
+      #
+      class Railtie < ::Rails::Railtie
+        ##
+        # Inform the Railtie that it is safe to start debugger agents.
+        # This simply calls {Google::Cloud::Debugger::Middleware.start_agents}.
+        # See its documentation for more information.
+        #
+        def self.start_agents
+          Google::Cloud::Debugger::Middleware.start_agents
+        end
+
+        config.google_cloud = ::ActiveSupport::OrderedOptions.new unless
+          config.respond_to? :google_cloud
+        config.google_cloud[:debugger] = ::ActiveSupport::OrderedOptions.new
+        config.google_cloud.define_singleton_method :debugger do
+          self[:debugger]
+        end
+
+        initializer "Stackdriver.Debugger" do |app|
+          self.class.consolidate_rails_config app.config
+
+          self.class.init_middleware app if Cloud.configure.use_debugger
+        end
+
+        ##
+        # @private Init Debugger integration for Rails. Setup configuration and
+        # insert the Middleware.
+        def self.init_middleware app
+          app.middleware.insert_after Rack::ETag,
+                                      Google::Cloud::Debugger::Middleware
+        end
+
+        ##
+        # @private Consolidate Rails configuration into Debugger instrumentation
+        # configuration. Also consolidate the `use_debugger` setting by
+        # verifying credentials and Rails environment. The `use_debugger`
+        # setting will be true if credentials are valid, and the setting is
+        # manually set to true or Rails is in the production environment.
+        #
+        # @param [Rails::Railtie::Configuration] config The
+        #   Rails.application.config
+        #
+        def self.consolidate_rails_config config
+          merge_rails_config config
+
+          init_default_config
+
+          # Done if Google::Cloud.configure.use_debugger is explicitly
+          # false
+          return if Google::Cloud.configure.use_debugger == false
+
+          # Verify credentials and set use_debugger to false if
+          # credentials are invalid
+          unless valid_credentials? Debugger.configure.project_id,
+                                    Debugger.configure.credentials
+            Cloud.configure.use_debugger = false
+            return
+          end
+
+          # Otherwise set use_debugger to true if Rails is running in
+          # the production environment
+          Google::Cloud.configure.use_debugger ||= ::Rails.env.production?
+        end
+
+        # rubocop:disable all
+
+        ##
+        # @private Merge Rails configuration into Debugger instrumentation
+        # configuration.
+        def self.merge_rails_config rails_config
+          gcp_config = rails_config.google_cloud
+          dbg_config = gcp_config.debugger
+
+          if Cloud.configure.use_debugger.nil?
+            Cloud.configure.use_debugger = gcp_config.use_debugger
+          end
+          Debugger.configure do |config|
+            config.project_id ||= begin
+              config.project || dbg_config.project_id || dbg_config.project
+                gcp_config.project_id || gcp_config.project
+            end
+            config.credentials ||= begin
+              config.keyfile || dbg_config.credentials || dbg_config.keyfile
+                gcp_config.credentials || gcp_config.keyfile
+            end
+            config.service_name ||= \
+              (dbg_config.service_name || gcp_config.service_name)
+            config.service_version ||= \
+              (dbg_config.service_version || gcp_config.service_version)
+          end
+        end
+
+        # rubocop:enable all
+
+        ##
+        # Fallback to default config values if config parameters not provided.
+        def self.init_default_config
+          config = Debugger.configure
+          config.project_id ||= Debugger.default_project_id
+          config.service_name ||= Debugger.default_service_name
+          config.service_version ||= Debugger.default_service_version
+        end
+
+        ##
+        # @private Verify credentials
+        def self.valid_credentials? project_id, credentials
+          begin
+            # if credentials is nil, get default
+            credentials ||= Debugger::Credentials.default
+            # only create a new Credentials object if the val isn't one already
+            unless credentials.is_a? Google::Auth::Credentials
+              # if credentials is not a Credentials object, create one
+              Debugger::Credentials.new credentials
+            end
+          rescue StandardError => e
+            STDOUT.puts "Note: Google::Cloud::Debugger is disabled because " \
+              "it failed to authorize with the service. (#{e.message})"
+            return false
+          end
+
+          if project_id.to_s.empty?
+            STDOUT.puts "Note: Google::Cloud::Debugger is disabled because " \
+              "the project ID could not be determined."
+            return false
+          end
+
+          true
+        end
+
+        private_class_method :merge_rails_config,
+                             :init_default_config,
+                             :valid_credentials?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# Copyright 2017 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 Debugger
+      ##
+      # # RequestQuotaManager
+      #
+      # Tracking object used by debugger agent to manage quota in
+      # request-based applications. This class tracks the amount of time
+      # and number of breakpoints to evaluation in a single session.
+      #
+      # The debugger agent doesn't have use a quota manager by default, which
+      # means it will evaluate all breakpoints encountered and takes as much
+      # time as needed. This class is utilized by
+      # {Google::Cloud::Debugger::Middleware} class to limit latency overhead
+      # when used in Rack-based applications.
+      #
+      class RequestQuotaManager
+        # Default Total time allowed to consume, in seconds
+        DEFAULT_TIME_QUOTA = 0.05
+
+        # Default max number of breakpoints to evaluate
+        DEFAULT_COUNT_QUOTA = 10
+
+        ##
+        # The time quota for this manager
+        attr_accessor :time_quota
+
+        ##
+        # The count quota for this manager
+        attr_accessor :count_quota
+
+        ##
+        # The time quota used
+        attr_accessor :time_used
+
+        ##
+        # The count quota used
+        attr_accessor :count_used
+
+        ##
+        # Construct a new RequestQuotaManager instance
+        #
+        # @param [Float] time_quota The max quota for time consumed.
+        # @param [Integer] count_quota The max quota for count usage.
+        def initialize time_quota: DEFAULT_TIME_QUOTA,
+                       count_quota: DEFAULT_COUNT_QUOTA
+          @time_quota = time_quota
+          @time_used = 0
+          @count_quota = count_quota
+          @count_used = 0
+        end
+
+        ##
+        # Check if there's more quota left.
+        #
+        # @return [Boolean] True if there's more quota; false otherwise.
+        def more?
+          (time_used < time_quota) && (count_used < count_quota)
+        end
+
+        ##
+        # Reset all the quota usage.
+        def reset
+          @time_used = 0
+          @count_used = 0
+        end
+
+        ##
+        # Notify the quota manager some resource has been consumed. Each time
+        # called increases the count quota usage.
+        #
+        # @param [Float] time Amount of time to deduct from the time quota.
+        def consume time: 0
+          @time_used += time
+          @count_used += 1
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# Copyright 2017 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/errors"
+require "google/cloud/debugger/version"
+require "google/cloud/debugger/v2"
+require "uri"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # @private Represents the gRPC Debugger service, including all the API
+      # methods.
+      class Service
+        attr_accessor :project, :credentials, :timeout, :host
+
+        ##
+        # Creates a new Service instance.
+        def initialize project, credentials, timeout: nil, host: nil
+          @project = project
+          @credentials = credentials
+          @timeout = timeout
+          @host = host
+        end
+
+        def cloud_debugger
+          return mocked_debugger if mocked_debugger
+          @cloud_debugger ||=
+            V2::Controller::Client.new do |config|
+              config.credentials = credentials if credentials
+              config.timeout = timeout if timeout
+              config.endpoint = host if host
+              config.lib_name = "gccl"
+              config.lib_version = Google::Cloud::Debugger::VERSION
+              config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+            end
+        end
+        attr_accessor :mocked_debugger
+
+        def transmitter
+          return mocked_transmitter if mocked_transmitter
+          @transmitter ||=
+            V2::Controller::Client.new do |config|
+              config.credentials = credentials if credentials
+              config.timeout = timeout if timeout
+              config.endpoint = host if host
+              config.lib_name = "gccl"
+              config.lib_version = Google::Cloud::Debugger::VERSION
+              config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+            end
+        end
+        attr_accessor :mocked_transmitter
+
+        def register_debuggee debuggee_grpc
+          cloud_debugger.register_debuggee debuggee: debuggee_grpc
+        end
+
+        def list_active_breakpoints debuggee_id, wait_token
+          cloud_debugger.list_active_breakpoints debuggee_id: debuggee_id.to_s,
+                                                 wait_token: wait_token.to_s,
+                                                 success_on_timeout: true
+        end
+
+        def update_active_breakpoint debuggee_id, breakpoint
+          transmitter.update_active_breakpoint debuggee_id: debuggee_id.to_s,
+                                               breakpoint: breakpoint.to_grpc
+        end
+
+        def inspect
+          "#{self.class}(#{@project})"
+        end
+      end
+    end
+  end
+end