plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/cache.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # ETag-backed HTTP cache for GitHub REST reads.
+  #
+  # Stores `{ etag:, body: }` pairs in `Rails.cache` keyed by resource.
+  # Readers look up the entry, pass its ETag in `If-None-Match`, and
+  # either (a) get a cheap 304 and serve the cached body, or (b) get a
+  # fresh 200, write the new ETag + body, and return that. Writes from
+  # +.create!+/+.update!+ front-load the cache with the fresh ETag
+  # returned on the mutating response so the next read is cheap too.
+  #
+  # Covers issues, comments, and their list endpoints.
+  #
+  module Cache
+    # Gem-internal cache version. Bump when the cache layout or the
+    # payload shape changes in a backwards-incompatible way so existing
+    # entries are orphaned rather than mis-read.
+    CACHE_VERSION = 'v1'
+
+    class << self
+      # @return [Boolean] whether `Rails.cache` is available and caching is enabled
+      def enabled?
+        return false unless PlanMyStuff.configuration.cache_enabled
+        return false if !defined?(::Rails) || !::Rails.respond_to?(:cache) || ::Rails.cache.nil?
+
+        true
+      end
+
+      # Reads the cached `{etag:, body:}` entry for an issue.
+      #
+      # @param repo [String] resolved full repo name (e.g. "Org/Name")
+      # @param number [Integer]
+      #
+      # @return [Hash{Symbol => Object}, nil]
+      #
+      def read_issue(repo, number)
+        return unless enabled?
+
+        ::Rails.cache.read(issue_key(repo, number))
+      end
+
+      # Writes a cache entry for an issue.
+      #
+      # @param repo [String] resolved full repo name
+      # @param number [Integer]
+      # @param etag [String, nil] value of the `ETag` response header
+      # @param body [Object] parsed GitHub issue response
+      #
+      # @return [void]
+      #
+      def write_issue(repo, number, etag:, body:)
+        return unless enabled?
+        return if etag.blank?
+
+        ::Rails.cache.write(
+          issue_key(repo, number),
+          { etag: etag, body: normalize(body) },
+        )
+      end
+
+      # Removes the cache entry for an issue.
+      #
+      # @param repo [String]
+      # @param number [Integer]
+      #
+      # @return [void]
+      #
+      def delete_issue(repo, number)
+        return unless enabled?
+
+        ::Rails.cache.delete(issue_key(repo, number))
+      end
+
+      # Reads the cached `{etag:, body:}` entry for a comment.
+      #
+      # @param repo [String] resolved full repo name (e.g. "Org/Name")
+      # @param id [Integer]
+      #
+      # @return [Hash{Symbol => Object}, nil]
+      #
+      def read_comment(repo, id)
+        return unless enabled?
+
+        ::Rails.cache.read(comment_key(repo, id))
+      end
+
+      # Writes a cache entry for a comment.
+      #
+      # @param repo [String] resolved full repo name
+      # @param id [Integer]
+      # @param etag [String, nil] value of the `ETag` response header
+      # @param body [Object] parsed GitHub comment response
+      #
+      # @return [void]
+      #
+      def write_comment(repo, id, etag:, body:)
+        return unless enabled?
+        return if etag.blank?
+
+        ::Rails.cache.write(
+          comment_key(repo, id),
+          { etag: etag, body: normalize(body) },
+        )
+      end
+
+      # Removes the cache entry for a comment.
+      #
+      # @param repo [String]
+      # @param id [Integer]
+      #
+      # @return [void]
+      #
+      def delete_comment(repo, id)
+        return unless enabled?
+
+        ::Rails.cache.delete(comment_key(repo, id))
+      end
+
+      # Reads the cached `{etag:, body:}` entry for a list endpoint.
+      #
+      # @param resource [Symbol] :issue or :comment
+      # @param repo [String] resolved full repo name
+      # @param params [Hash] query params that make this list unique
+      #
+      # @return [Hash{Symbol => Object}, nil]
+      #
+      def read_list(resource, repo, params)
+        return unless enabled?
+
+        ::Rails.cache.read(list_key(resource, repo, params))
+      end
+
+      # Writes a cache entry for a list endpoint.
+      #
+      # @param resource [Symbol] :issue or :comment
+      # @param repo [String] resolved full repo name
+      # @param params [Hash] query params that make this list unique
+      # @param etag [String, nil] value of the `ETag` response header
+      # @param body [Object] parsed GitHub list response (array of resources)
+      #
+      # @return [void]
+      #
+      def write_list(resource, repo, params, etag:, body:)
+        return unless enabled?
+        return if etag.blank?
+
+        ::Rails.cache.write(
+          list_key(resource, repo, params),
+          { etag: etag, body: normalize(body) },
+        )
+      end
+
+      private
+
+        # @return [String]
+        def issue_key(repo, number)
+          [key_prefix, 'issue', repo, number].join('/')
+        end
+
+        # @return [String]
+        def comment_key(repo, id)
+          [key_prefix, 'comment', repo, id].join('/')
+        end
+
+        # @return [String]
+        def list_key(resource, repo, params)
+          serialized = params.sort_by { |k, _| k.to_s }.map { |k, v| "#{k}:#{v}" }.join(',')
+          [key_prefix, 'list', resource, repo, serialized].join('/')
+        end
+
+        # Builds the cache key prefix from gem + app cache versions so
+        # that bumping either side orphans all existing entries.
+        #
+        # @return [String]
+        #
+        def key_prefix
+          app_version = PlanMyStuff.configuration.cache_version || '0'
+          ['pms', CACHE_VERSION, app_version].join('/')
+        end
+
+        # Coerces a Sawyer::Resource, Struct, Array, or similar to a
+        # plain Hash (or Array of Hashes) so the cache payload is
+        # portable across stores. Anything else is passed through.
+        #
+        # @return [Object]
+        #
+        def normalize(body)
+          return body.map { |item| normalize(item) } if body.is_a?(Array)
+          return body.to_hash if body.respond_to?(:to_hash)
+          return body.to_h if body.respond_to?(:to_h)
+
+          body
+        end
+    end
+  end
+end

data/lib/plan_my_stuff/client.rb

@@ -4,18 +4,63 @@ require 'active_support/core_ext/hash/keys'
 require 'octokit'
 
 module PlanMyStuff
-  # Infrastructure wrapper around Octokit. Handles auth, error normalization,
-  # and repo resolution. Domain modules (Issues, Projects, etc.) use this
-  # internally via PlanMyStuff.client.
+  # Infrastructure wrapper around Octokit. Handles auth, error normalization, and repo resolution. Domain modules
+  # (Issues, Projects, etc.) use this internally via PlanMyStuff.client.
   class Client
     # @return [Octokit::Client]
     attr_reader :octokit
 
+    # Returns the Faraday response from the most recent Octokit call. Useful for reading headers (e.g. `ETag`,
+    # `X-RateLimit-Remaining`) that aren't included in the parsed response body.
+    #
+    # @return [Faraday::Response, nil]
+    delegate :last_response, to: :octokit
+
+    class << self
+      # Activates trace mode: every +rest+ and +graphql+ call is recorded into +traced_requests+ until
+      # +exit_trace_mode!+ is called. Useful for debugging which GitHub calls a code path makes.
+      #
+      # @return [void]
+      #
+      def trace_mode!
+        @trace_mode = true
+        @traced_requests = []
+      end
+
+      # Disables trace mode and clears any recorded requests.
+      #
+      # @return [void]
+      #
+      def exit_trace_mode!
+        @trace_mode = false
+        @traced_requests = []
+      end
+
+      # @return [Boolean]
+      def trace_mode?
+        @trace_mode == true
+      end
+
+      # @return [Array<Hash>]
+      def traced_requests
+        @traced_requests ||= []
+      end
+    end
+
+    # @raise [PlanMyStuff::ConfigurationError] if +import_access_token+ is blank when +importing: true+
+    #
     # @return [Client]
-    def initialize
+    #
+    def initialize(importing: false)
       PlanMyStuff.configuration.validate!
 
-      @octokit = Octokit::Client.new(access_token: PlanMyStuff.configuration.access_token)
+      access_token = importing ? PlanMyStuff.configuration.import_access_token : PlanMyStuff.configuration.access_token
+
+      if importing && access_token.blank?
+        raise(PlanMyStuff::ConfigurationError, 'Import access token is required for import client but not configured')
+      end
+
+      @octokit = Octokit::Client.new(access_token: access_token)
     end
 
     # Delegates a REST API call to Octokit, normalizing errors.
@@ -26,16 +71,10 @@ module PlanMyStuff
     #
     # @return [Object] Octokit response
     #
-    def rest(method, *, **kwargs, &)
-      if kwargs.empty?
-        octokit.public_send(method, *, &)
-      else
-        octokit.public_send(method, *, **kwargs, &)
+    def rest(method, *args, **kwargs, &block)
+      trace!(:rest, method: method, args: args, kwargs: kwargs) do
+        execute_rest!(method, *args, **kwargs, &block)
       end
-    rescue Octokit::TooManyRequests => e
-      raise_rate_limit_error(e)
-    rescue Octokit::ClientError, Octokit::ServerError => e
-      raise(APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
     end
 
     # Executes a GraphQL query against GitHub's /graphql endpoint.
@@ -46,65 +85,101 @@ module PlanMyStuff
     # @return [Hash] parsed response data
     #
     def graphql(query, variables: {})
-      payload = { query: query }
-      payload[:variables] = variables unless variables.empty?
-
-      response = octokit.post('/graphql', payload.to_json)
-      data =
-        if response.is_a?(Hash)
-          response
-        else
-          (response.respond_to?(:to_h) ? response.to_h : response)
-        end
-
-      data = data.deep_symbolize_keys if data.respond_to?(:deep_symbolize_keys)
-
-      check_graphql_errors!(data)
-
-      data[:data]
-    rescue Octokit::TooManyRequests => e
-      raise_rate_limit_error(e)
-    rescue Octokit::ClientError, Octokit::ServerError => e
-      raise(APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
+      trace!(:graphql, query: query, variables: variables) do
+        execute_graphql!(query, variables)
+      end
     end
 
     # Resolves a repo param to a full "Org/Repo" string.
     #
-    # @param repo [Symbol, String, nil] repo key, full string, or nil for default
+    # @param repo [Symbol, String, PlanMyStuff::Repo, nil] repo key, full string, Repo instance, or nil for default
     #
     # @return [String] full repo path (e.g. "BrandsInsurance/Element")
     #
-    # @raise [ArgumentError] if repo cannot be resolved
-    #
-    def resolve_repo(repo = nil)
-      repo ||= PlanMyStuff.configuration.default_repo
-
-      if repo.nil?
-        raise(
-          PlanMyStuff::ConfigurationError,
-          'No repo provided and config.default_repo is not set. ' \
-            'Either pass repo: explicitly or set config.default_repo in your initializer.',
-        )
+    def resolve_repo!(repo = nil)
+      PlanMyStuff::Repo.resolve!(repo).full_name
+    end
+
+    private
+
+      # @raise [PlanMyStuff::APIError] if Octokit call fails with client or server error
+      #
+      # @return [Object]
+      #
+      def execute_rest!(method, *, **kwargs, &)
+        if kwargs.empty?
+          octokit.public_send(method, *, &)
+        else
+          octokit.public_send(method, *, **kwargs, &)
+        end
+      rescue Octokit::TooManyRequests => e
+        raise_rate_limit_error!(e)
+      rescue Octokit::ClientError, Octokit::ServerError => e
+        raise(PlanMyStuff::APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
       end
 
-      case repo
-      when Symbol
-        resolved = PlanMyStuff.configuration.repos[repo]
-        raise(ArgumentError, "Unknown repo key: #{repo.inspect}") if resolved.nil?
+      # @raise [PlanMyStuff::APIError] if Octokit call fails with client or server error
+      #
+      # @return [Hash]
+      #
+      def execute_graphql!(query, variables)
+        payload = { query: query }
+        payload[:variables] = variables unless variables.empty?
+
+        response = octokit.post('/graphql', payload.to_json)
+        data =
+          if response.is_a?(Hash)
+            response
+          else
+            (response.respond_to?(:to_h) ? response.to_h : response)
+          end
+
+        data = data.deep_symbolize_keys if data.respond_to?(:deep_symbolize_keys)
+
+        check_graphql_errors!(data)
+
+        data[:data]
+      rescue Octokit::TooManyRequests => e
+        raise_rate_limit_error!(e)
+      rescue Octokit::ClientError, Octokit::ServerError => e
+        raise(PlanMyStuff::APIError.new(e.message, status: e.respond_to?(:response_status) ? e.response_status : nil))
+      end
 
-        resolved
-      when String
-        repo
-      else
-        raise(ArgumentError, "Cannot resolve repo: #{repo.inspect}")
+      # Records the wrapped call into +Client.traced_requests+ when trace mode is on; otherwise just yields.
+      #
+      # @param kind [Symbol] :rest or :graphql
+      # @param details [Hash] call-specific details (method/args/query/variables)
+      #
+      # @return [Object]
+      #
+      def trace!(kind, **details)
+        return yield unless self.class.trace_mode?
+
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          result = yield
+          record_trace(kind, start, details)
+          result
+        rescue => e
+          record_trace(kind, start, details, error: e)
+          raise
+        end
       end
-    end
 
-    private
+      # @return [void]
+      def record_trace(kind, start, details, error: nil)
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1_000).round(2)
+        entry = { kind: kind, duration_ms: duration_ms, status: octokit.last_response&.status, **details }
+        if error
+          entry[:error] = error.class.name
+          entry[:error_message] = error.message
+        end
+        self.class.traced_requests << entry
+      end
 
-      # @param data [Hash] parsed GraphQL response
+      # @raise [PlanMyStuff::GraphQLError] if response contains errors
       #
-      # @raise [GraphQLError] if response contains errors
+      # @param data [Hash] parsed GraphQL response
       #
       # @return [void]
       #
@@ -113,16 +188,16 @@ module PlanMyStuff
         return if errors.blank?
 
         messages = errors.filter_map { |e| e[:message] }
-        raise(GraphQLError.new(messages.join('; '), errors: errors))
+        raise(PlanMyStuff::GraphQLError.new(messages.join('; '), errors: errors))
       end
 
-      # @param exception [Octokit::TooManyRequests]
+      # @raise [PlanMyStuff::RateLimitError] if GitHub has been rate limited
       #
-      # @raise [RateLimitError]
+      # @param exception [Octokit::TooManyRequests]
       #
-      def raise_rate_limit_error(exception)
+      def raise_rate_limit_error!(exception)
         retry_after = parse_retry_after(exception)
-        raise(RateLimitError.new(exception.message, retry_after: retry_after))
+        raise(PlanMyStuff::RateLimitError.new(exception.message, retry_after: retry_after))
       end
 
       # @param exception [Octokit::TooManyRequests]