google-cloud-debugger 0.24.0

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

@@ -0,0 +1,217 @@
+# 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/breakpoint"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # BreakpointManager
+      #
+      # Responsible for querying Stackdriver Debugger service for any active
+      # breakpoints and keep an accurate local copies of the breakpoints.
+      #
+      # It correctly remembers which breakpoints are currently active and
+      # watched by the debugger agent, and which breakpoints are already
+      # completed. The BreakpointManager holds the record of truth for debugger
+      # breakpoints
+      #
+      class BreakpointManager
+        include MonitorMixin
+
+        ##
+        # @private The gRPC Service object.
+        attr_reader :service
+
+        ##
+        # Application root directory, in absolute file path form.
+        # @return [String]
+        attr_reader :app_root
+
+        ##
+        # Callback function invoked when new breakpoints are added or removed
+        # @return [Method]
+        attr_accessor :on_breakpoints_change
+
+        ##
+        # @private The wait token from Stackdriver Debugger service used
+        # for breakpoints long polling
+        attr_reader :wait_token
+
+        ##
+        # @private Construct new instance of BreakpointManager
+        def initialize service
+          super()
+
+          @service = service
+
+          @completed_breakpoints = []
+          @active_breakpoints = []
+
+          @wait_token = :init
+        end
+
+        ##
+        # Sync active breakpoints with Stackdriver Debugger service for a given
+        # debuggee application. Each request to the debugger service returns
+        # the full list of all active breakpoints. This method makes sure the
+        # local cache of active breakpoints is consistent with server
+        # breakpoints set.
+        #
+        # @param [String] debuggee_id Debuggee application ID
+        #
+        # @return [Boolean] True if synced successfully; otherwise false.
+        #
+        def sync_active_breakpoints debuggee_id
+          begin
+            response = service.list_active_breakpoints debuggee_id, @wait_token
+          rescue
+            return false
+          end
+
+          return true if response.wait_expired
+
+          @wait_token = response.next_wait_token
+
+          server_breakpoints = response.breakpoints || []
+          server_breakpoints = server_breakpoints.map do |grpc_b|
+            Breakpoint.from_grpc grpc_b
+          end
+
+          update_breakpoints server_breakpoints
+
+          true
+        end
+
+        ##
+        # Update the local breakpoints cache with a list of server active
+        # breakpoints. New breakpoints will be added to local cache, and deleted
+        # breakpoints will be removed from local cache.
+        #
+        # It also correctly identifies evaluated active breakpoints from the
+        # server set of breakpoints, and does not re-add such evaluated
+        # breakpoints to the active list again.
+        #
+        # @param [Array<Google::Cloud::Debugger::Breakpoint>] server_breakpoints
+        #   List of active breakpoints from Stackdriver Debugger service
+        #
+        def update_breakpoints server_breakpoints
+          synchronize do
+            new_breakpoints =
+              server_breakpoints - @active_breakpoints - @completed_breakpoints
+            before_breakpoints_count =
+              @active_breakpoints.size + @completed_breakpoints.size
+
+            # Remember new active breakpoints from server
+            @active_breakpoints += new_breakpoints unless new_breakpoints.empty?
+
+            # Forget old breakpoints
+            @completed_breakpoints &= server_breakpoints
+            @active_breakpoints &= server_breakpoints
+            after_breakpoints_acount =
+              @active_breakpoints.size + @completed_breakpoints.size
+
+            breakpoints_updated =
+              !new_breakpoints.empty? ||
+              (before_breakpoints_count != after_breakpoints_acount)
+
+            on_breakpoints_change.call(@active_breakpoints) if
+              on_breakpoints_change.respond_to?(:call) && breakpoints_updated
+          end
+        end
+
+        ##
+        # Mark a given active breakpoint as completed. Meaning moving it from
+        # list of active breakpoints to completed breakpoints.
+        #
+        # @param [Google::Cloud::Debugger::Breakpoint] breakpoint The breakpoint
+        #   to remove from local cache
+        #
+        # @return [Google::Cloud::Debugger::Breakpoint, NilClass] The same
+        #   breakpoint if successfully marked off as completed. Nil if
+        #   this breakpoint isn't found in the list of active breakpoints or
+        #   failed to mark off as completed.
+        #
+        def mark_off breakpoint
+          synchronize do
+            breakpoint = @active_breakpoints.delete breakpoint
+
+            if breakpoint.nil?
+              nil
+            else
+              @completed_breakpoints << breakpoint
+              breakpoint
+            end
+          end
+        end
+
+        ##
+        # Get a list of all breakpoints, both active and completed.
+        #
+        # @return [Array<Google::Cloud::Debugger::Breakpoint>] A list of all
+        #   breakpoints.
+        def breakpoints
+          synchronize do
+            @active_breakpoints | @completed_breakpoints
+          end
+        end
+
+        ##
+        # Get a list of all completed breakpoints.
+        #
+        # @return [Array<Google::Cloud::Debugger::Breakpoint>] A list of all
+        #   completed breakpoints.
+        def completed_breakpoints
+          synchronize do
+            @completed_breakpoints
+          end
+        end
+
+        ##
+        # Get a list of all active breakpoints.
+        #
+        # @return [Array<Google::Cloud::Debugger::Breakpoint>] A list of all
+        #   active breakpoints.
+        def active_breakpoints
+          synchronize do
+            @active_breakpoints
+          end
+        end
+
+        ##
+        # Check whether any active breakpoints haven't been completed yet.
+        #
+        # @return [Boolean] True if no more active breakpoints are left. False
+        #   otherwise.
+        def all_complete?
+          synchronize do
+            @active_breakpoints.empty?
+          end
+        end
+
+        ##
+        # Clear local breakpoints cache. Remove all active and completed
+        # breakpoints
+        def clear_breakpoints
+          synchronize do
+            @active_breakpoints.clear
+            @completed_breakpoints.clear
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# 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/credentials"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # @private Represents the OAuth 2.0 signing logic for Debugger.
+      class Credentials < Google::Cloud::Credentials
+        SCOPE = ["https://www.googleapis.com/auth/cloud_debugger"]
+        PATH_ENV_VARS = %w(DEBUGGER_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(DEBUGGER_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
+                           GCLOUD_KEYFILE_JSON)
+
+        ##
+        # @private Create credentials with given scope and/or keyfile
+        def self.credentials_with_scope keyfile, scope = nil
+          if keyfile.nil?
+            default(scope: scope)
+          else
+            new(keyfile, scope: scope)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,204 @@
+# 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 "digest/sha1"
+require "google/cloud/debugger/debuggee/app_uniquifier_generator"
+require "google/cloud/debugger/version"
+require "json"
+
+module Google
+  module Cloud
+    module Debugger
+      ##
+      # # Debuggee
+      #
+      # Represent a debuggee application. Contains information that identifies
+      # debuggee applications from each other. Maps to gRPC struct
+      # {Google::Devtools::Clouddebugger::V2::Debuggee}.
+      #
+      # It also automatically loads source context information generated from
+      # Cloud SDK. See [Stackdriver Debugger
+      # doc](https://cloud.google.com/debugger/docs/source-context#app_engine_standard_python)
+      # for more information on how to generate this source context information
+      # when used on Google Container Engine and Google Compute engine. This
+      # step is taken care of if debuggee application is hosted on Google App
+      # Engine Flexibile.
+      #
+      # To ensure the multiple instances of the application are indeed the same
+      # application, the debuggee also compute a "uniquifier" generated from
+      # source context or application source code.
+      #
+      class Debuggee
+        ##
+        # @private The gRPC Service object.
+        attr_reader :service
+
+        ##
+        # Name for the debuggee application
+        # @return [String]
+        attr_reader :module_name
+
+        ##
+        # Version identifier for the debuggee application
+        # @return [String]
+        attr_reader :module_version
+
+        ##
+        # Registered Debuggee ID. Set by Stackdriver Debugger service when
+        # a debuggee application is sucessfully registered.
+        # @return [String]
+        attr_reader :id
+
+        ##
+        # @private Construct a new instance of Debuggee
+        def initialize service, module_name:, module_version:
+          @service = service
+          @module_name = module_name
+          @module_version = module_version
+          @computed_uniquifier = nil
+          @id = nil
+        end
+
+        ##
+        # Register the current application as a debuggee with Stackdriver
+        # Debuggee service.
+        # @return [Boolean] True if registered sucessfully; otherwise false.
+        def register
+          begin
+            response = service.register_debuggee to_grpc
+            @id = response.debuggee.id
+          rescue
+            revoke_registration
+          end
+          registered?
+        end
+
+        ##
+        # Check whether this debuggee is currently registered or not
+        # @return [Boolean] True if debuggee is registered; otherwise false.
+        def registered?
+          !id.nil?
+        end
+
+        ##
+        # Revoke the registration of this debuggee
+        def revoke_registration
+          @id = nil
+        end
+
+        ##
+        # Convert this debuggee into a gRPC
+        # Google::Devtools::Clouddebugger::V2::Debuggee struct.
+        def to_grpc
+          debuggee_args = build_request_arg
+
+          Google::Devtools::Clouddebugger::V2::Debuggee.decode_json \
+            debuggee_args.to_json
+        end
+
+        private
+
+        ##
+        # @private Build the parameters for this debuggee
+        def build_request_arg
+          debuggee_args = {
+            project: project_id,
+            description: description,
+            labels: labels,
+            agent_version: agent_version
+          }
+
+          debuggee_args[:id] = id if id
+
+          source_context = read_app_json_file "source-context.json"
+          debuggee_args[:source_contexts] = [source_context] if source_context
+
+          source_contexts = read_app_json_file "source-contexts.json"
+          if source_contexts
+            debuggee_args[:ext_source_contexts] = source_contexts
+          elsif source_context
+            debuggee_args[:ext_source_contexts] = [{ context: source_context }]
+          end
+
+          debuggee_args[:uniquifier] = compute_uniquifier debuggee_args
+
+          debuggee_args
+        end
+
+        ##
+        # @private Build labels hash for this debuggee
+        def labels
+          {
+            "projectid" => String(project_id),
+            "module" => String(module_name),
+            "version" => String(module_version)
+          }
+        end
+
+        ##
+        # @private Build description string for this debuggee. In
+        # "<module name> - <module version>" format. Or just the module
+        # version if module name is missing.
+        #
+        # @return [String] A compact debuggee description.
+        #
+        def description
+          if module_version.nil? || module_version.empty?
+            module_name
+          else
+            "#{module_name} - #{module_version}"
+          end
+        end
+
+        ##
+        # @private Get debuggee project id
+        def project_id
+          service.project
+        end
+
+        ##
+        # @private Build debuggee agent version identifier
+        def agent_version
+          "google.com/ruby#{RUBY_VERSION}-#{Google::Cloud::Debugger::VERSION}"
+        end
+
+        ##
+        # @private Generate a debuggee uniquifier from source context
+        # information or application source code
+        def compute_uniquifier debuggee_args
+          return @computed_uniquifier if @computed_uniquifier
+
+          sha = Digest::SHA1.new
+          sha << debuggee_args.to_s
+
+          unless debuggee_args.key?(:source_contexts) ||
+                 debuggee_args.key?(:ext_source_contexts)
+            AppUniquifierGenerator.generate_app_uniquifier sha
+          end
+
+          @computed_uniquifier = sha.hexdigest
+        end
+
+        ##
+        # @private Helper method to parse json file
+        def read_app_json_file file_path
+          JSON.parse File.read(file_path), symbolize_names: true
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end