plan_my_stuff 0.3.0 → 0.5.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

@@ -11,6 +11,13 @@ module PlanMyStuff
     # @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
+
     # @return [Client]
     def initialize
       PlanMyStuff.configuration.validate!

data/lib/plan_my_stuff/comment.rb

@@ -9,21 +9,24 @@ module PlanMyStuff
   # - `Comment.create!` / `Comment.list` return persisted instances
   # - `comment.save!` / `comment.update!` / `comment.reload` for persistence
   class Comment < PlanMyStuff::ApplicationRecord
-    # @return [Integer] GitHub comment ID
-    attr_reader :id
-    # @return [String] full body as stored on GitHub
-    attr_reader :raw_body
+    # @return [Integer, nil] GitHub comment ID
+    attribute :id, :big_integer
+    # @return [String, nil] full body as stored on GitHub
+    attribute :raw_body, :string
     # @return [PlanMyStuff::CommentMetadata] parsed metadata (empty when no PMS metadata present)
-    attr_reader :metadata
-
-    # @return [String] comment body without the metadata HTML comment
-    attr_accessor :body
-    # @return [PlanMyStuff::Issue] parent issue
-    attr_accessor :issue
+    attribute :metadata, default: -> { PlanMyStuff::CommentMetadata.new }
+    # @return [String, nil] comment body without the metadata HTML comment
+    attribute :body, :string
+    # @return [PlanMyStuff::Issue, nil] parent issue
+    attribute :issue
     # @return [Time, nil] GitHub's updated_at timestamp
-    attr_reader :updated_at
-    # @param value [Symbol, String, nil]
-    attr_writer :visibility
+    attribute :updated_at
+    # @return [Symbol, nil] :public or :internal (locally set or from metadata)
+    attribute :visibility
+
+    # @return [Boolean, nil] transient flag used by the new-comment form to
+    #   request waiting-on-user state when a support user posts. Not persisted.
+    attr_accessor :waiting_on_reply
 
     class << self
       # Creates a comment on a GitHub issue with PMS metadata and a visible header.
@@ -34,6 +37,9 @@ module PlanMyStuff
       # @param visibility [Symbol] :public or :internal
       # @param custom_fields [Hash]
       # @param issue_body [Boolean] whether this comment holds the issue body
+      # @param waiting_on_reply [Boolean] when true and the author is a
+      #   support user, marks the issue as waiting on an end-user reply.
+      #   Ignored for non-support authors.
       #
       # @return [PlanMyStuff::Comment]
       #
@@ -44,8 +50,11 @@ module PlanMyStuff
         visibility: :public,
         custom_fields: {},
         skip_responded: false,
-        issue_body: false
+        issue_body: false,
+        waiting_on_reply: false
       )
+        raise(PlanMyStuff::LockedIssueError, "Issue ##{issue.number} is locked") if issue.locked?
+
         resolved_user = UserResolver.resolve(user)
         visibility = resolve_visibility(visibility, resolved_user)
         comment_metadata = CommentMetadata.build(
@@ -60,11 +69,22 @@ module PlanMyStuff
         full_body = "#{header}\n\n#{body}"
         serialized_body = MetadataParser.serialize(comment_metadata.to_h, full_body)
 
-        result = PlanMyStuff.client.rest(:add_comment, issue.repo, issue.number, serialized_body)
+        client = PlanMyStuff.client
+        result = client.rest(:add_comment, issue.repo, issue.number, serialized_body)
+        store_etag_to_cache(
+          client,
+          issue.repo,
+          read_field(result, :id),
+          result,
+          cache_writer: :write_comment,
+        )
 
         mark_issue_responded_if_first_support_comment(issue, resolved_user) unless skip_responded
 
-        build(result, issue: issue)
+        comment = build(result, issue: issue)
+        PlanMyStuff::Notifications.instrument('comment.created', comment, user: resolved_user)
+        apply_waiting_state_transitions(issue, resolved_user, waiting_on_reply, comment)
+        comment
       end
 
       # Updates an existing GitHub comment body.
@@ -76,7 +96,16 @@ module PlanMyStuff
       # @return [Object] Octokit response
       #
       def update!(id:, repo:, body:)
-        PlanMyStuff.client.rest(:update_comment, repo, id, body)
+        client = PlanMyStuff.client
+        result = client.rest(:update_comment, repo, id, body)
+        store_etag_to_cache(
+          client,
+          repo,
+          id,
+          result,
+          cache_writer: :write_comment,
+        )
+        result
       end
 
       # Finds a single comment by ID, given its parent issue.
@@ -87,7 +116,16 @@ module PlanMyStuff
       # @return [PlanMyStuff::Comment]
       #
       def find(id, issue:)
-        github_comment = PlanMyStuff.client.rest(:issue_comment, issue.repo, id)
+        client = PlanMyStuff.client
+        github_comment =
+          fetch_with_etag_cache(
+            client,
+            issue.repo,
+            id,
+            rest_method: :issue_comment,
+            cache_reader: :read_comment,
+            cache_writer: :write_comment,
+          )
         build(github_comment, issue: issue)
       end
 
@@ -99,8 +137,21 @@ module PlanMyStuff
       # @return [Array<PlanMyStuff::Comment>]
       #
       def list(issue:, pms_only: false)
-        github_comments = PlanMyStuff.client.rest(:issue_comments, issue.repo, issue.number)
-        comments = github_comments.map { |gc| build(gc, issue: issue) }
+        client = PlanMyStuff.client
+        params = { issue_number: issue.number }
+
+        cached = PlanMyStuff::Cache.read_list(:comment, issue.repo, params)
+        request_options = cached ? { headers: { 'If-None-Match' => cached[:etag] } } : {}
+
+        github_comments = client.rest(:issue_comments, issue.repo, issue.number, **request_options)
+
+        comments =
+          if cached && not_modified?(client)
+            cached[:body].map { |gc| build(gc, issue: issue) }
+          else
+            store_list_etag_to_cache(client, :comment, issue.repo, params, github_comments)
+            github_comments.map { |gc| build(gc, issue: issue) }
+          end
 
         pms_only ? comments.select(&:pms_comment?) : comments
       end
@@ -177,13 +228,38 @@ module PlanMyStuff
             metadata: { responded_at: Time.now.utc.iso8601 },
           )
         end
-    end
 
-    def initialize(**attrs)
-      @id = attrs.delete(:id)
-      @raw_body = nil
-      @metadata = CommentMetadata.new
-      super
+        # Mutates issue waiting state based on the comment's author.
+        # Support users with +waiting_on_reply: true+ enter the issue
+        # into waiting-on-user state. Non-support users clear any
+        # active waiting-on-user state and auto-reopen issues that
+        # were closed by the inactivity sweep.
+        #
+        # No-ops on non-PMS issues or when no user is resolved.
+        #
+        # @param issue [PlanMyStuff::Issue]
+        # @param user [Object, nil] resolved user
+        # @param waiting_on_reply [Boolean]
+        # @param comment [PlanMyStuff::Comment] the just-created comment
+        #
+        # @return [void]
+        #
+        def apply_waiting_state_transitions(issue, user, waiting_on_reply, comment)
+          return if user.nil?
+
+          return unless issue.pms_issue?
+
+          # Auto-reopen fires only for non-support replies; a support comment on a
+          # +closed_by_inactivity+ issue is treated as a closure note and requires
+          # the explicit Reopen button to bring the issue back.
+          if UserResolver.support?(user)
+            issue.enter_waiting_on_user!(user: user) if waiting_on_reply
+          elsif issue.metadata.closed_by_inactivity
+            issue.reopen_by_reply!(comment: comment, user: user)
+          elsif issue.metadata.waiting_on_user_at.present?
+            issue.clear_waiting_on_user!
+          end
+        end
     end
 
     # Persists the comment. Creates if new, updates if persisted.
@@ -216,9 +292,11 @@ module PlanMyStuff
     #
     # @return [self]
     #
-    def update!(**attrs)
+    def update!(user: nil, **attrs)
       raise_if_stale!
 
+      captured_changes = capture_update_changes(attrs)
+
       new_body = attrs[:body] || body
       new_body = preserve_header(new_body) if attrs.key?(:body)
       meta_hash = metadata.to_h
@@ -232,6 +310,8 @@ module PlanMyStuff
       self.class.update!(id: id, repo: issue.repo, body: serialized)
 
       reload
+      PlanMyStuff::Notifications.instrument('comment.updated', self, user: user, changes: captured_changes)
+      self
     end
 
     # Re-fetches this comment from GitHub and updates all local attributes.
@@ -239,11 +319,29 @@ module PlanMyStuff
     # @return [self]
     #
     def reload
-      github_comment = PlanMyStuff.client.rest(:issue_comment, issue.repo, id)
-      hydrate_from_github(github_comment, issue: issue)
+      fresh = self.class.find(id, issue: issue)
+      hydrate_from_comment(fresh)
       self
     end
 
+    # GitHub web URL for this comment, for escape-hatch "View on GitHub" links.
+    #
+    # @return [String, nil]
+    #
+    def html_url
+      safe_read_field(github_response, :html_url)
+    end
+
+    # Serializes the comment to a JSON-safe hash, excluding the back-reference
+    # to the parent issue to prevent recursive serialization cycles.
+    #
+    # @return [Hash]
+    #
+    def as_json(options = {})
+      merged_except = Array.wrap(options[:except]) + ['issue']
+      super(options.merge(except: merged_except)).merge('issue_number' => issue&.number)
+    end
+
     # @return [Boolean]
     def pms_comment?
       metadata.schema_version.present?
@@ -255,7 +353,7 @@ module PlanMyStuff
     # @return [Symbol, nil] :public or :internal
     #
     def visibility
-      @visibility || metadata.visibility&.to_sym
+      super || metadata.visibility&.to_sym
     end
 
     # Checks if the comment is visible to the given user.
@@ -309,6 +407,27 @@ module PlanMyStuff
         "#{existing_header}\n\n#{new_body}"
       end
 
+      # Computes the +ActiveModel::Dirty+-style changes hash from the +update!+
+      # +attrs+ hash vs the current in-memory state. Only includes keys whose
+      # value actually differs.
+      #
+      # @param attrs [Hash]
+      #
+      # @return [Hash{String => Array(Object, Object)}]
+      #
+      def capture_update_changes(attrs)
+        changes = {}
+        if attrs.key?(:body) && attrs[:body] != body
+          changes['body'] = [body, attrs[:body]]
+        end
+        if attrs.key?(:visibility)
+          new_visibility = attrs[:visibility].to_s
+          current_visibility = visibility&.to_s
+          changes['visibility'] = [current_visibility, new_visibility] if current_visibility != new_visibility
+        end
+        changes
+      end
+
       # Populates this instance from a GitHub API response.
       #
       # @param github_comment [Object] Octokit comment response
@@ -317,16 +436,17 @@ module PlanMyStuff
       # @return [void]
       #
       def hydrate_from_github(github_comment, issue:)
-        @id = read_field(github_comment, :id)
-        @raw_body = read_field(github_comment, :body)
-        @updated_at = parse_github_time(safe_read_field(github_comment, :updated_at))
-        @issue = issue
-
-        parsed = MetadataParser.parse(@raw_body)
-        @metadata = CommentMetadata.from_hash(parsed[:metadata])
-        @body = parsed[:body]
-        @visibility = @metadata.visibility&.to_sym
-        @persisted = true
+        @github_response = github_comment
+        self.id = read_field(github_comment, :id)
+        self.raw_body = read_field(github_comment, :body)
+        self.updated_at = parse_github_time(safe_read_field(github_comment, :updated_at))
+        self.issue = issue
+
+        parsed = MetadataParser.parse(raw_body)
+        self.metadata = CommentMetadata.from_hash(parsed[:metadata])
+        self.body = parsed[:body]
+        self.visibility = metadata.visibility&.to_sym
+        persisted!
       end
 
       # Copies attributes from another Comment instance into self.
@@ -336,14 +456,15 @@ module PlanMyStuff
       # @return [void]
       #
       def hydrate_from_comment(other)
-        @id = other.id
-        @body = other.body
-        @raw_body = other.raw_body
-        @updated_at = other.updated_at
-        @issue = other.issue
-        @metadata = other.metadata
-        @visibility = other.visibility
-        @persisted = true
+        @github_response = other.github_response
+        self.id = other.id
+        self.body = other.body
+        self.raw_body = other.raw_body
+        self.updated_at = other.updated_at
+        self.issue = other.issue
+        self.metadata = other.metadata
+        self.visibility = other.visibility
+        persisted!
       end
 
       # Raises StaleObjectError if the remote comment has been modified
@@ -357,8 +478,8 @@ module PlanMyStuff
         return if new_record?
         return if updated_at.nil?
 
-        github_comment = PlanMyStuff.client.rest(:issue_comment, issue.repo, id)
-        remote_time = parse_github_time(safe_read_field(github_comment, :updated_at))
+        remote = self.class.find(id, issue: issue)
+        remote_time = remote.updated_at
         local_time = updated_at
 
         return if remote_time.nil?