google-cloud-debugger 0.24.0

data/lib/google/cloud/debugger/debuggee/app_uniquifier_generator.rb

@@ -0,0 +1,78 @@
+# 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
+#
+#     http://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 "pathname"
+require "set"
+
+module Google
+  module Cloud
+    module Debugger
+      class Debuggee
+        ##
+        # Generates an application debuggee uniquifier by hashing the
+        # application file stats.
+        #
+        module AppUniquifierGenerator
+          ##
+          # Max number of directory levels the generator looks into.
+          MAX_DEPTH = 10
+
+          ##
+          # Computes the application uniquifier by examine the file stats of
+          # the files in the given application root directory. It only looks at
+          # .rb files and Gemfile.lock
+          #
+          # @param [Digest::SHA] sha A digest SHA object used to add the hashing
+          #   values
+          # @param [String] app_path Application root directory where the Ruby
+          #   application is located.
+          #
+          # @return [NilClass]
+          #
+          def self.generate_app_uniquifier sha, app_path = nil
+            app_path ||= if defined?(::Rack::Directory)
+                           Rack::Directory.new("").root
+                         else
+                           Dir.getwd
+                         end
+
+            process_directory sha, app_path
+
+            nil
+          end
+
+          private
+
+          ##
+          # @private Recursively parse files and directories.
+          def self.process_directory sha, path, depth = 1
+            return if depth > MAX_DEPTH
+
+            pathname = Pathname.new path
+            pathname.each_child do |entry|
+              if entry.directory?
+                process_directory sha, entry, depth + 1
+              else
+                next unless entry.extname == ".rb" ||
+                            entry.basename.to_s == "Gemfile.lock"
+                sha << "#{entry.expand_path}:#{entry.stat.size}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# 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
+#
+#     http://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
+      ##
+      # Rack Middleware implementation that supports Stackdriver Debugger Agent
+      # in Rack-based Ruby frameworks. It instantiates a new debugger agent if
+      # one isn't given already. It helps optimize Debugger Agent Tracer
+      # performance by suspend and resume tracer between each request.
+      class Middleware
+        ##
+        # Create a new Debugger Middleware.
+        #
+        # @param [Rack Application] app Rack application
+        # @param [Google::Cloud::Debugger::Project] debugger A debugger to be
+        #   used by this middleware. If not given, will construct a new one
+        #   using the other parameters.
+        # @param [String] project Project identifier for the Stackdriver
+        #   Debugger service. Optional if a debugger is given.
+        # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud:
+        #   either the JSON data or the path to a readable file. Optional if
+        #   a debugger is given.
+        # @param [String] module_name Name for the debuggee application.
+        #   Optional if a debugger is given.
+        # @param [String] module_version Version identifier for the debuggee
+        #   application. Optiona if a debugger is given.
+        #
+        # @return [Google::Cloud::Debugger::Middleware] A new
+        #   Google::Cloud::Debugger::Middleware instance
+        #
+        def initialize app, debugger: nil, module_name:nil, module_version: nil,
+                       project: nil, keyfile: nil
+          @app = app
+          @debugger = debugger || Debugger.new(project: project,
+                                               keyfile: keyfile,
+                                               module_name: module_name,
+                                               module_version: module_version)
+          @debugger.start
+        end
+
+        ##
+        # Rack middleware entry point. In most Rack based frameworks, a request
+        # is served by one thread. It enables/resume the debugger breakpoints
+        # tracing and stops/pauses the tracing afterwards to help improve
+        # debugger performance.
+        #
+        # @param [Hash] env Rack environment hash
+        #
+        # @return [Rack::Response] The response from downstream Rack app
+        #
+        def call env
+          # Enable/resume breakpoints tracing
+          @debugger.agent.tracer.start
+
+          @app.call env
+        ensure
+          # Stop breakpoints tracing beyond this point
+          @debugger.agent.tracer.disable_traces_for_thread
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+# 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
+#
+#     http://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/env"
+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, module_name:, module_version:
+          @service = service
+          @agent = Agent.new service, module_name: module_name,
+                                      module_version: module_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: "my-project",
+        #     keyfile: "/path/to/keyfile.json"
+        #   )
+        #
+        #   debugger.project #=> "my-project"
+        #
+        def project
+          service.project
+        end
+
+        ##
+        # @private Default project.
+        def self.default_project
+          ENV["DEBUGGER_PROJECT"] ||
+            ENV["GOOGLE_CLOUD_PROJECT"] ||
+            ENV["GCLOUD_PROJECT"] ||
+            Google::Cloud.env.project_id
+        end
+
+        ##
+        # @private Default module name identifier.
+        def self.default_module_name
+          ENV["DEBUGGER_MODULE_NAME"] ||
+            Google::Cloud.env.app_engine_service_id ||
+            "ruby-app"
+        end
+
+        ##
+        # @private Default module version identifier.
+        def self.default_module_version
+          ENV["DEBUGGER_MODULE_VERSION"] ||
+            Google::Cloud.env.app_engine_service_version ||
+            ""
+        end
+
+        ##
+        # 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_method :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,141 @@
+# 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
+#
+#     http://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 certain conditions are met. See
+      # {Railtie.use_debugger?} for detail.
+      #
+      # 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. The debugger can be configured using the following Rails
+      # configuration:
+      # @example
+      #   # Explicitly enable or disable Stackdriver Debugger Agent
+      #   config.google_cloud.use_debugger = true
+      #   # Shared Google Cloud Platform project identifier
+      #   config.google_cloud.project_id = "gcloud-project"
+      #   # Google Cloud Platform project identifier for Stackdriver Debugger
+      #   config.google_cloud.debugger.project_id = "debugger-project"
+      #   # Share Google Cloud authentication json file
+      #   config.google_cloud.keyfile = "/path/to/keyfile.json"
+      #   # Google Cloud authentication json file for Stackdriver Debugger only
+      #   config.google_cloud.debugger.keyfile = "/path/to/keyfile.json"
+      #   # Stackdriver Debugger Agent module name identifier
+      #   config.google_cloud.debugger.module_name = "my-ruby-app"
+      #   # Stackdriver Debugger Agent module version identifier
+      #   config.google_cloud.debugger.module_version = "v1"
+      #
+      class Railtie < ::Rails::Railtie
+        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|
+          debugger_config = Railtie.parse_rails_config config
+
+          project_id = debugger_config[:project_id]
+          keyfile = debugger_config[:keyfile]
+          module_name = debugger_config[:module_name]
+          module_version = debugger_config[:module_version]
+
+          debugger = Google::Cloud::Debugger.new project: project_id,
+                                                 keyfile: keyfile,
+                                                 module_name: module_name,
+                                                 module_version: module_version
+
+          if self.class.use_debugger? app.config
+            app.middleware.insert_after Rack::ETag,
+                                        Google::Cloud::Debugger::Middleware,
+                                        debugger: debugger
+          end
+        end
+
+        ##
+        # Determine whether to use Stackdriver Debugger or not.
+        #
+        # Returns true if valid GCP project_id is provided and underneath API is
+        # able to authenticate. Also either Rails needs to be in "production"
+        # environment or config.stackdriver.use_debugger is explicitly true.
+        #
+        # @param [Rails::Railtie::Configuration] config The
+        #   Rails.application.config
+        #
+        # @return [Boolean] Whether to use Stackdriver Debugger
+        #
+        def self.use_debugger? config
+          debugger_config = parse_rails_config config
+
+          # Return false if config.stackdriver.use_debugger is explicitly false
+          use_debugger = debugger_config[:use_debugger]
+          return false if !use_debugger.nil? && !use_debugger
+
+          # Try authenticate authorize client API. Return false if unable to
+          # authorize.
+          begin
+            Google::Cloud::Debugger::Credentials.credentials_with_scope(
+              debugger_config[:keyfile])
+          rescue => e
+            Rails.log "Google::Cloud::Debugger is not activated due to " \
+              "authorization error: #{e.message}"
+            return false
+          end
+
+          project_id = debugger_config[:project_id] ||
+                       Google::Cloud::Debugger::Project.default_project
+          if project_id.to_s.empty?
+            Rails.log "Google::Cloud::Debugger is not activated due to empty " \
+              "project_id"
+            return false
+          end
+
+          # Otherwise default to true if Rails is running in production or
+          # config.stackdriver.use_debugger is true
+          Rails.env.production? || use_debugger
+        end
+
+        ##
+        # @private Helper method to parse rails config into a flattened hash
+        def self.parse_rails_config config
+          gcp_config = config.google_cloud
+          debugger_config = gcp_config[:debugger]
+          use_debugger =
+            gcp_config.key?(:use_debugger) ? gcp_config.use_debugger : nil
+          {
+            project_id: debugger_config.project_id || gcp_config.project_id,
+            keyfile: debugger_config.keyfile || gcp_config.keyfile,
+            module_name: debugger_config.module_name,
+            module_version: debugger_config.module_version,
+            use_debugger: use_debugger
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+# 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
+#
+#     http://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 "google/gax/errors"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # @private Represents the gRPC Debugger service, including all the API
+      # methods.
+      class Service
+        attr_accessor :project, :credentials, :host, :timeout, :client_config
+
+        ##
+        # Creates a new Service instance.
+        def initialize project, credentials, host: nil, 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,
+              timeout: timeout,
+              client_config: client_config,
+              lib_name: "gccl",
+              lib_version: Google::Cloud::Debugger::VERSION)
+        end
+        attr_accessor :mocked_debugger
+
+        def transmitter
+          return mocked_transmitter if mocked_transmitter
+          @transmitter ||=
+            V2::Controller2Client.new(
+              service_path: host,
+              channel: channel,
+              timeout: timeout,
+              client_config: client_config,
+              lib_name: "gccl",
+              lib_version: Google::Cloud::Debugger::VERSION)
+        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,
+                                             options: default_options
+          end
+        end
+
+        def list_active_breakpoints debuggee_id, wait_token
+          execute do
+            cloud_debugger.list_active_breakpoints debuggee_id.to_s,
+                                                   wait_token: wait_token.to_s,
+                                                   success_on_timeout: true,
+                                                   options: default_options
+          end
+        end
+
+        def update_active_breakpoint debuggee_id, breakpoint
+          execute do
+            transmitter.update_active_breakpoint debuggee_id.to_s,
+                                                 breakpoint.to_grpc,
+                                                 options: default_options
+          end
+        end
+
+        def inspect
+          "#{self.class}(#{@project})"
+        end
+
+        protected
+
+        def default_headers
+          { "google-cloud-resource-prefix" => "projects/#{@project}" }
+        end
+
+        def default_options
+          Google::Gax::CallOptions.new kwargs: default_headers
+        end
+
+        def execute
+          yield
+        rescue Google::Gax::GaxError => e
+          # GaxError wraps BadStatus, but exposes it as #cause
+          raise Google::Cloud::Error.from_error(e.cause)
+        end
+      end
+    end
+  end
+end