plan_my_stuff 0.2.0 → 0.4.0

data/lib/plan_my_stuff/application_record.rb

@@ -7,6 +7,13 @@ module PlanMyStuff
   # Provides shared persistence predicates and utility helpers.
   class ApplicationRecord
     include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Dirty
+    include ActiveModel::Serializers::JSON
+
+    # @return [Object, nil] raw GitHub API response this record was hydrated from.
+    #   Escape hatch for consuming apps to access fields the gem doesn't expose.
+    attr_reader :github_response
 
     class << self
       # Reads a field from an object that may respond to method calls or hash access.
@@ -19,11 +26,96 @@ module PlanMyStuff
       def read_field(obj, field)
         obj.respond_to?(field) ? obj.public_send(field) : obj[field]
       end
+
+      private
+
+        # @param client [PlanMyStuff::Client]
+        #
+        # @return [Boolean]
+        #
+        def not_modified?(client)
+          response = client.last_response
+          return false if response.nil?
+
+          response.status == 304
+        end
+
+        # Captures the +ETag+ header from the most recent REST response and
+        # forwards it to +cache_writer+.
+        #
+        # @param client [PlanMyStuff::Client]
+        # @param repo [String]
+        # @param id [Integer, nil]
+        # @param body [Object] parsed GitHub response
+        # @param cache_writer [Symbol] +PlanMyStuff::Cache+ method name, e.g. +:write_issue+
+        #
+        # @return [void]
+        #
+        def store_etag_to_cache(client, repo, id, body, cache_writer:)
+          return if id.nil?
+
+          response = client.last_response
+          return if response.nil?
+
+          etag = response.headers && response.headers['etag']
+          return if etag.blank?
+
+          PlanMyStuff::Cache.public_send(cache_writer, repo, id, etag: etag, body: body)
+        end
+
+        # Captures the +ETag+ header from the most recent REST response and
+        # forwards it to +Cache.write_list+.
+        #
+        # @param client [PlanMyStuff::Client]
+        # @param resource [Symbol] :issue or :comment
+        # @param repo [String]
+        # @param params [Hash] query params that identify this list
+        # @param body [Object] parsed GitHub list response
+        #
+        # @return [void]
+        #
+        def store_list_etag_to_cache(client, resource, repo, params, body)
+          response = client.last_response
+          return if response.nil?
+
+          etag = response.headers && response.headers['etag']
+          return if etag.blank?
+
+          PlanMyStuff::Cache.write_list(resource, repo, params, etag: etag, body: body)
+        end
+
+        # Reads a REST resource through the ETag cache.
+        #
+        # On a cache hit sends +If-None-Match+; a 304 returns the cached
+        # body. A 200 stores the new ETag via +cache_writer+ and returns
+        # the fresh result.
+        #
+        # @param client [PlanMyStuff::Client]
+        # @param repo [String]
+        # @param id [Integer]
+        # @param rest_method [Symbol] Octokit method name
+        # @param cache_reader [Symbol] +PlanMyStuff::Cache+ method name, e.g. +:read_issue+
+        # @param cache_writer [Symbol] +PlanMyStuff::Cache+ method name, e.g. +:write_issue+
+        #
+        # @return [Object] parsed GitHub response
+        #
+        def fetch_with_etag_cache(client, repo, id, rest_method:, cache_reader:, cache_writer:)
+          cached = PlanMyStuff::Cache.public_send(cache_reader, repo, id)
+          options = cached ? { headers: { 'If-None-Match' => cached[:etag] } } : {}
+
+          result = client.rest(rest_method, repo, id, **options)
+
+          return cached[:body] if cached && not_modified?(client)
+
+          store_etag_to_cache(client, repo, id, result, cache_writer: cache_writer)
+          result
+        end
     end
 
     def initialize(**)
       super
       @persisted = false
+      @destroyed = false
     end
 
     # @return [Boolean]
@@ -36,8 +128,37 @@ module PlanMyStuff
       !@persisted
     end
 
+    # @return [Boolean]
+    def destroyed?
+      @destroyed
+    end
+
     private
 
+      # Marks this record as persisted. Subclasses call this after a
+      # successful create/find/update against the underlying GitHub
+      # resource. Also applies any pending dirty changes so the record
+      # is clean after hydration and +#previous_changes+ reflects the
+      # values that were just loaded.
+      #
+      # @return [void]
+      #
+      def persisted!
+        @persisted = true
+        changes_applied
+      end
+
+      # Marks this record as destroyed. Subclasses call this from their
+      # +destroy!+ implementations after the underlying remote resource
+      # has been deleted.
+      #
+      # @return [void]
+      #
+      def destroyed!
+        @destroyed = true
+        @persisted = false
+      end
+
       # Reads a field from an object that may respond to method calls or hash access.
       #
       # @param obj [Object]
@@ -48,5 +169,28 @@ module PlanMyStuff
       def read_field(obj, field)
         self.class.read_field(obj, field)
       end
+
+      # Reads a field from an object, returning nil if the field does not exist.
+      #
+      # @param obj [Object]
+      # @param field [Symbol]
+      #
+      # @return [Object, nil]
+      #
+      def safe_read_field(obj, field)
+        read_field(obj, field)
+      rescue NameError
+        nil
+      end
+
+      # @return [Time, nil]
+      def parse_github_time(value)
+        return if value.nil?
+        return value.utc if value.is_a?(Time)
+
+        Time.parse(value.to_s).utc
+      rescue ArgumentError
+        nil
+      end
   end
 end

data/lib/plan_my_stuff/approval.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'active_model'
+
+module PlanMyStuff
+  # Value object representing a single manager approval on an +Issue+.
+  # Persisted in +IssueMetadata#approvals+ and returned from
+  # +Issue.request_approvals!+, +Issue.approve!+, and
+  # +Issue.revoke_approval!+.
+  #
+  # Mirrors +PlanMyStuff::Link+: +ActiveModel::Attributes+-backed, with
+  # +Serializers::JSON+ for round-trip through the metadata blob.
+  #
+  class Approval
+    STATUSES = %w[pending approved].freeze
+
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Serializers::JSON
+
+    # @return [Integer] app-side user id of the required approver
+    attribute :user_id, :integer
+    # @return [String] +"pending"+ or +"approved"+
+    attribute :status, :string, default: 'pending'
+    # @return [DateTime, nil] timestamp when status flipped to +"approved"+
+    attribute :approved_at, :datetime
+
+    validates :user_id, presence: true, numericality: { greater_than: 0, only_integer: true }
+    validates :status, inclusion: { in: STATUSES }
+
+    # @return [Boolean]
+    def pending?
+      status == 'pending'
+    end
+
+    # @return [Boolean]
+    def approved?
+      status == 'approved'
+    end
+
+    # Lazy-resolves the app-side user for this approval.
+    # Not memoized -- +PlanMyStuff::UserResolver+ owns caching.
+    #
+    # @return [Object, nil]
+    #
+    def user
+      PlanMyStuff::UserResolver.resolve(user_id)
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        user_id: user_id,
+        status: status,
+        approved_at: approved_at&.iso8601,
+      }
+    end
+
+    # Two approvals are equal when they track the same user AND carry the
+    # same status. A pending and an approved record for the same user are
+    # NOT equal -- matters for set arithmetic during state transitions.
+    #
+    # @param other [Object]
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      return false unless other.is_a?(PlanMyStuff::Approval)
+
+      user_id == other.user_id && status == other.status
+    end
+
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      [user_id, status].hash
+    end
+  end
+end

data/lib/plan_my_stuff/archive/sweep.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  module Archive
+    # Walks a single repo's closed issues, archiving those that have
+    # aged past +config.archive_closed_after_days+. Excludes issues
+    # auto-closed by +Reminders::Closer+ (+metadata.closed_by_inactivity+)
+    # and any that are already archived (marker timestamp or label).
+    #
+    # Paginates +Issue.list(state: :closed)+ until either an empty page
+    # or the hard +MAX_PAGES+ cap. GitHub's +list_issues+ returns in
+    # created-desc order, so closed_at is not monotonic across pages;
+    # we can't short-circuit on "this page is all within cutoff." Each
+    # subsequent sweep skips already-archived issues cheaply via
+    # +skip?+, so the steady-state walk is bounded in practice.
+    class Sweep
+      PAGE_SIZE = 50
+      MAX_PAGES = 20
+
+      # @param repo [Symbol, String] repo key or full name
+      # @param now [Time] clock reference
+      #
+      def initialize(repo:, now: Time.now.utc)
+        @repo = repo
+        @now = now.utc
+      end
+
+      # Runs the sweep. No-op when +config.archiving_enabled+ is false.
+      #
+      # @return [void]
+      #
+      def call
+        return unless PlanMyStuff.configuration.archiving_enabled
+
+        (1..MAX_PAGES).each do |page|
+          issues = PlanMyStuff::Issue.list(
+            repo: @repo,
+            state: :closed,
+            page: page,
+            per_page: PAGE_SIZE,
+          )
+
+          break if issues.empty?
+
+          process(issues)
+        end
+      end
+
+      private
+
+        # Per-issue exceptions are swallowed so a single bad archive
+        # doesn't halt the whole sweep.
+        #
+        # @param issues [Array<PlanMyStuff::Issue>]
+        #
+        # @return [void]
+        #
+        def process(issues)
+          issues.each do |issue|
+            next if skip?(issue)
+
+            issue.archive!(now: @now)
+          rescue => e
+            warn("[PlanMyStuff::Archive::Sweep] #{issue.repo}##{issue.number} failed: #{e.class}: #{e.message}")
+          end
+        end
+
+        # @param issue [PlanMyStuff::Issue]
+        #
+        # @return [Boolean]
+        #
+        def skip?(issue)
+          return true unless issue.pms_issue?
+
+          return true if issue.metadata.closed_by_inactivity
+          return true if issue.metadata.archived_at.present?
+          return true if issue.labels.include?(PlanMyStuff.configuration.archived_label)
+          return true if issue.closed_at.nil?
+
+          age_days = (@now - issue.closed_at.utc) / 1.day
+          age_days < PlanMyStuff.configuration.archive_closed_after_days
+        end
+    end
+  end
+end

data/lib/plan_my_stuff/archive.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PlanMyStuff
+  # Auto-archive engine. The +Sweep+ class walks closed issues in a repo
+  # and delegates to +Issue#archive!+ for each issue whose +closed_at+
+  # has aged past +config.archive_closed_after_days+.
+  #
+  # Entry point for the sweep lives in +RemindersSweepJob+; this module
+  # holds the POROs so they can be unit-tested without ActiveJob.
+  module Archive
+  end
+end
+
+require_relative 'archive/sweep'

data/lib/plan_my_stuff/aws_sns_simulator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'securerandom'
+require 'time'
+require 'uri'
+
+module PlanMyStuff
+  # Dev helper: build a fake SNS notification wrapping an ECS Deployment
+  # State Change event and POST it to a local +/webhooks/aws+ endpoint.
+  # Used by +plan_my_stuff:webhooks:simulate_aws+ so deployment flows
+  # can be exercised without waiting for a real AWS deployment.
+  #
+  # The consuming app must be configured with a no-op SNS verifier
+  # (see +PlanMyStuff::NullSnsVerifier+) or signature verification will
+  # reject the simulated envelope. Never enable that verifier in
+  # production.
+  #
+  module AwsSnsSimulator
+    DEFAULT_EVENT = 'SERVICE_DEPLOYMENT_COMPLETED'
+
+    module_function
+
+    # POSTs a simulated SNS envelope to the endpoint. Pulls
+    # +sns_topic_arn+, +aws_service_identifier+, and
+    # +production_commit_sha+ from +PlanMyStuff.configuration+ (this
+    # task is dev-only, so there's no reason to parameterize them).
+    #
+    # @param endpoint_url [String] full URL including path
+    # @param event_name [String] ECS eventName (default completed)
+    #
+    # @return [Net::HTTPResponse]
+    #
+    def post(endpoint_url:, event_name: DEFAULT_EVENT)
+      config = PlanMyStuff.configuration
+      raise('PlanMyStuff.configuration.sns_topic_arn is blank') if config.sns_topic_arn.blank?
+      raise('PlanMyStuff.configuration.aws_service_identifier is blank') if config.aws_service_identifier.blank?
+
+      topic_arn = config.sns_topic_arn
+      service_arn = "arn:aws:ecs:us-east-1:000000000000:service/simulated-cluster/#{config.aws_service_identifier}"
+      commit_sha = config.production_commit_sha
+
+      message = build_ecs_message(event_name: event_name, service_arn: service_arn, commit_sha: commit_sha)
+      envelope = build_sns_envelope(message: message, topic_arn: topic_arn)
+      raw_body = JSON.generate(envelope)
+
+      uri = URI(endpoint_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request['Content-Type'] = 'application/json'
+      request['x-amz-sns-message-type'] = 'Notification'
+      request.body = raw_body
+
+      $stdout.puts("POST #{endpoint_url}")
+      $stdout.puts("  event:     #{event_name}")
+      $stdout.puts("  topic:     #{topic_arn}")
+      $stdout.puts("  resources: #{service_arn}")
+      $stdout.puts("  commit:    #{commit_sha || '(none)'}")
+      $stdout.puts('---')
+
+      response = http.request(request)
+      $stdout.puts("HTTP #{response.code} #{response.message}")
+      $stdout.puts(response.body) if response.body.present?
+      response
+    end
+
+    # @return [Hash]
+    def build_ecs_message(event_name:, service_arn:, commit_sha:)
+      detail = {
+        'eventType' => 'INFO',
+        'eventName' => event_name,
+        'deploymentId' => "ecs-svc/#{SecureRandom.hex(8)}",
+        'updatedAt' => Time.now.utc.iso8601,
+      }
+      detail['commitSha'] = commit_sha if commit_sha
+
+      {
+        'version' => '0',
+        'id' => SecureRandom.uuid,
+        'detail-type' => 'ECS Deployment State Change',
+        'source' => 'aws.ecs',
+        'account' => '000000000000',
+        'time' => Time.now.utc.iso8601,
+        'region' => 'us-east-1',
+        'resources' => [service_arn],
+        'detail' => detail,
+      }
+    end
+
+    # @return [Hash]
+    def build_sns_envelope(message:, topic_arn:)
+      now = Time.now.utc.iso8601
+      {
+        'Type' => 'Notification',
+        'MessageId' => SecureRandom.uuid,
+        'TopicArn' => topic_arn,
+        'Subject' => 'ECS Deployment State Change',
+        'Message' => JSON.generate(message),
+        'Timestamp' => now,
+        'SignatureVersion' => '1',
+        'Signature' => 'simulated',
+        'SigningCertURL' => 'https://example.com/cert.pem',
+        'UnsubscribeURL' => 'https://example.com/unsubscribe',
+      }
+    end
+  end
+end

data/lib/plan_my_stuff/base_metadata.rb

@@ -15,10 +15,6 @@ module PlanMyStuff
     attr_accessor :rails_env
     # @return [String, nil] consuming app name from config
     attr_accessor :app_name
-    # @return [Time, nil] timestamp of creation
-    attr_accessor :created_at
-    # @return [Time, nil] timestamp of last update
-    attr_accessor :updated_at
     # @return [Integer, nil] consuming app's user ID of the creator
     attr_accessor :created_by
     # @return [String] "public" or "internal"
@@ -42,8 +38,6 @@ module PlanMyStuff
           metadata.gem_version = hash[:gem_version]
           metadata.rails_env = hash[:rails_env]
           metadata.app_name = hash[:app_name]
-          metadata.created_at = parse_time(hash[:created_at])
-          metadata.updated_at = parse_time(hash[:updated_at])
           metadata.created_by = hash[:created_by]
           metadata.visibility = hash.fetch(:visibility, 'internal')
           metadata.custom_fields = CustomFields.new(
@@ -70,14 +64,11 @@ module PlanMyStuff
           custom_fields_schema: {}
         )
           config = PlanMyStuff.configuration
-          now = Time.now.utc
 
           metadata.schema_version = self::SCHEMA_VERSION
           metadata.gem_version = PlanMyStuff::VERSION::STRING
           metadata.rails_env = (defined?(Rails) && Rails.respond_to?(:env)) ? Rails.env.to_s : nil
           metadata.app_name = config.app_name
-          metadata.created_at = now
-          metadata.updated_at = now
           resolved = UserResolver.resolve(user)
           metadata.created_by = resolved.present? ? UserResolver.user_id(resolved) : nil
           metadata.visibility = visibility
@@ -110,8 +101,6 @@ module PlanMyStuff
         gem_version: gem_version,
         rails_env: rails_env,
         app_name: app_name,
-        created_at: format_time(created_at),
-        updated_at: format_time(updated_at),
         created_by: created_by,
         visibility: visibility,
         custom_fields: custom_fields.to_h,