plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/webhook_replayer.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'net/http'
+require 'uri'
+
+module PlanMyStuff
+  # Dev helper: fetch recent GitHub webhook deliveries via the GitHub API
+  # and POST each one to a local endpoint, so a webhook flow can be
+  # reproduced against a running server without waiting for GitHub to
+  # re-deliver.
+  #
+  # Intended for use via +plan_my_stuff:webhooks:replay+, not production
+  # code paths.
+  module WebhookReplayer
+    module_function
+
+    # POST a single webhook delivery to a local endpoint.
+    #
+    # @param headers [Hash]
+    # @param payload [String, Hash, Array]
+    # @param endpoint_url [String] full URL including path
+    #
+    # @return [Net::HTTPResponse]
+    #
+    def post(headers:, payload:, endpoint_url:)
+      uri = URI(endpoint_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = 3_600
+      http.read_timeout = 3_600
+
+      body = payload.is_a?(String) ? JSON.parse(payload).to_json : JSON.generate(payload)
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      headers.each { |key, value| request[key.to_s] = value.to_s }
+      request['Content-Type'] ||= 'application/json'
+      request.body = body
+
+      $stdout.puts("POST #{endpoint_url}")
+      $stdout.puts("Headers: #{headers.keys.join(', ')}")
+      $stdout.puts('---')
+
+      response = http.request(request)
+      $stdout.puts("HTTP #{response.code} #{response.message}")
+      $stdout.puts(response.body) if response.body.present?
+      response
+    end
+
+    # Fetch deliveries for a hook and replay unseen ones.
+    #
+    # @param endpoint_url [String] local URL to POST replays to
+    # @param webhook_url [String] remote config.url used to resolve hook id
+    # @param scope [Symbol, String] :org or :repo
+    # @param repo [String, nil] required when scope is :repo
+    # @param processed_file [String] state file tracking replayed delivery ids
+    # @param interactive [Boolean] prompt after each successful delivery
+    #
+    # @return [void]
+    #
+    def fetch_and_replay(endpoint_url:, webhook_url:, processed_file:, scope: :org, repo: nil, interactive: true)
+      scope = scope.to_sym
+      hook_id = resolve_hook_id(scope: scope, repo: repo, webhook_url: webhook_url)
+      deliveries_path = "#{hooks_base_path(scope: scope, repo: repo)}/#{hook_id}/deliveries"
+      $stdout.puts("Using #{scope} hook #{hook_id} -> #{webhook_url}")
+
+      processed = load_processed(processed_file)
+      $stdout.puts("Already processed: #{processed.size}")
+
+      deliveries = gh_get(deliveries_path, per_page: 50).sort_by { |d| d['delivered_at'].to_s }
+      to_process = deliveries.reject { |d| processed.include?(d['id'].to_s) }
+      $stdout.puts("Fetched #{deliveries.size} deliveries, #{to_process.size} new")
+      if to_process.empty?
+        $stdout.puts('Nothing to do.')
+        return
+      end
+
+      replay_each(to_process, deliveries_path, endpoint_url, processed_file, interactive: interactive)
+    end
+
+    # Polls one or more webhooks on an interval and auto-replays new
+    # deliveries as they arrive. Resolves hook ids once up front, then
+    # loops forever until Ctrl-C.
+    #
+    # @param targets [Array<Hash>] one hash per hook, each with
+    #   +:scope+ (:org / :repo), +:webhook_url+, and +:repo+ (for :repo scope)
+    # @param endpoint_url [String] local URL to POST replays to
+    # @param processed_file_for [#call] lambda taking a target hash,
+    #   returns the state file path for that target
+    # @param interval [Integer] seconds between polls (default 15)
+    #
+    # @return [void]
+    #
+    def listen(targets:, endpoint_url:, processed_file_for:, interval: 30)
+      resolved = targets.map { |t| resolve_target(t, processed_file_for) }
+      $stdout.puts("Listening on #{resolved.size} hook(s) every #{interval}s. Ctrl-C to stop.")
+      resolved.each do |r|
+        $stdout.puts("  #{r[:scope]} hook #{r[:hook_id]} -> #{r[:webhook_url]}")
+      end
+
+      loop do
+        poll_all(resolved, endpoint_url)
+        $stdout.puts('=============')
+        $stdout.puts('  Sleeping...')
+        $stdout.puts('=============')
+        sleep(interval)
+      end
+    rescue Interrupt
+      $stdout.puts("\nStopped.")
+    end
+
+    # Resolves a listen target's hook id and precomputes its deliveries
+    # path + processed-file location.
+    #
+    # @return [Hash]
+    #
+    def resolve_target(target, processed_file_for)
+      scope = target.fetch(:scope).to_sym
+      repo = target[:repo]
+      webhook_url = target.fetch(:webhook_url)
+      hook_id = resolve_hook_id(scope: scope, repo: repo, webhook_url: webhook_url)
+
+      {
+        scope: scope,
+        repo: repo,
+        webhook_url: webhook_url,
+        hook_id: hook_id,
+        deliveries_path: "#{hooks_base_path(scope: scope, repo: repo)}/#{hook_id}/deliveries",
+        processed_file: processed_file_for.call(target),
+      }
+    end
+
+    # Collects unprocessed deliveries across every resolved target,
+    # merges them into a single list sorted by +delivered_at+, then
+    # replays them one-by-one in true chronological order. Transient
+    # API errors per target are logged and swallowed so the listen
+    # loop survives.
+    #
+    # @param resolved [Array<Hash>]
+    # @param endpoint_url [String]
+    #
+    # @return [void]
+    #
+    def poll_all(resolved, endpoint_url)
+      pending = []
+      resolved.each do |target|
+        processed = load_processed(target[:processed_file])
+        deliveries = gh_get(target[:deliveries_path], per_page: 50)
+        deliveries.each do |summary|
+          next if processed.include?(summary['id'].to_s)
+
+          pending << { target: target, summary: summary }
+        end
+      rescue Octokit::Error => e
+        warn("[#{target[:scope]}] poll failed: #{e.message}")
+      end
+
+      return if pending.empty?
+
+      pending.sort_by! { |item| item[:summary]['delivered_at'].to_s }
+      $stdout.puts("Replaying #{pending.size} delivery(ies) in delivered_at order")
+      replay_pending(pending, endpoint_url)
+    end
+
+    # Replays a pre-sorted, multi-target pending list one delivery at
+    # a time. Stops on the first non-success so state can be
+    # investigated without skipping ahead.
+    #
+    # @raise [PlanMyStuff::Error] when the endpoint returns a non-success HTTP status
+    #
+    # @return [void]
+    #
+    def replay_pending(pending, endpoint_url)
+      pending.each.with_index(1) do |item, index|
+        target = item[:target]
+        summary = item[:summary]
+        id = summary['id']
+        delivery = gh_get("#{target[:deliveries_path]}/#{id}")
+        request_data = delivery.fetch('request')
+        github_delivery_id = request_data.dig('headers', 'X-GitHub-Delivery') || id
+
+        event = "#{summary['event']}.#{summary['action']}"
+        $stdout.puts(
+          "[#{index}/#{pending.size}] #{target[:scope]} #{id} #{event} " \
+            "@ #{summary['delivered_at']} - #{github_delivery_id}",
+        )
+
+        response = post(
+          headers: request_data.fetch('headers') || {},
+          payload: request_data.fetch('payload'),
+          endpoint_url: endpoint_url,
+        )
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise(PlanMyStuff::Error, '  ! non-success; stopping so you can investigate')
+        end
+
+        mark_processed(target[:processed_file], id)
+      end
+    end
+
+    # @raise [ArgumentError] when scope is :repo but repo is nil or empty
+    # @raise [ArgumentError] when scope is neither :org nor :repo
+    #
+    # @return [String]
+    #
+    def hooks_base_path(scope:, repo:)
+      case scope
+      when :org
+        "/orgs/#{PlanMyStuff.configuration.organization}/hooks"
+      when :repo
+        raise(ArgumentError, 'repo is required for :repo scope') if repo.nil? || repo.to_s.empty?
+
+        "/repos/#{repo}/hooks"
+      else
+        raise(ArgumentError, "Unknown scope #{scope.inspect}; expected :org or :repo")
+      end
+    end
+
+    # @raise [PlanMyStuff::Error] when no webhook matches the given URL
+    #
+    # @return [Integer]
+    #
+    def resolve_hook_id(scope:, repo:, webhook_url:)
+      hooks = gh_get(hooks_base_path(scope: scope, repo: repo), per_page: 100)
+      match = hooks.find { |h| h.dig('config', 'url') == webhook_url }
+      return match['id'] if match.present?
+
+      available = hooks.map { |h| "  id=#{h['id']} url=#{h.dig('config', 'url')}" }.join("\n")
+      raise(PlanMyStuff::Error, "No #{scope} webhook with config.url == #{webhook_url}. Visible:\n#{available}")
+    end
+
+    # Calls +octokit.get+ and returns the parsed JSON body (string-keyed
+    # Hash/Array) rather than Sawyer::Resource, so delivery payload and
+    # headers are easy to re-serialize.
+    #
+    # @return [Array, Hash]
+    #
+    def gh_get(path, **params)
+      client = PlanMyStuff.client.octokit
+      client.get(path, params)
+      JSON.parse(client.last_response.body)
+    end
+
+    # @return [Set<String>]
+    def load_processed(path)
+      return Set.new unless File.exist?(path)
+
+      File.readlines(path, chomp: true).reject(&:empty?).to_set
+    end
+
+    # @return [void]
+    def mark_processed(path, id)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open(path, 'a') { |f| f.puts(id) }
+    end
+
+    # @raise [PlanMyStuff::Error] when the endpoint returns a non-success HTTP status
+    #
+    # @return [void]
+    #
+    def replay_each(to_process, deliveries_path, endpoint_url, processed_file, interactive:)
+      to_process.each.with_index(1) do |summary, index|
+        id = summary['id']
+        delivery = gh_get("#{deliveries_path}/#{id}")
+        request_data = delivery.fetch('request')
+        github_delivery_id = request_data.dig('headers', 'X-GitHub-Delivery') || id
+
+        event = "#{summary['event']}.#{summary['action']}"
+        $stdout.puts("[#{index}/#{to_process.size}] #{id} #{event} - #{github_delivery_id}")
+
+        response = post(
+          headers: request_data.fetch('headers') || {},
+          payload: request_data.fetch('payload'),
+          endpoint_url: endpoint_url,
+        )
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise(PlanMyStuff::Error, '  ! non-success; stopping so you can investigate')
+        end
+
+        mark_processed(processed_file, id)
+        next unless interactive
+
+        $stdout.puts("Processed #{github_delivery_id} - Continue? (y/n)")
+        answer = $stdin.gets
+        break unless answer&.downcase&.start_with?('y')
+      end
+    end
+  end
+end

data/lib/plan_my_stuff.rb

@@ -1,33 +1,46 @@
 # frozen_string_literal: true
 
+require 'zeitwerk'
+
+require 'date'
+
 require 'active_support/core_ext/array/wrap'
 require 'active_support/core_ext/object/blank'
 
-require_relative 'plan_my_stuff/application_record'
-require_relative 'plan_my_stuff/base_metadata'
-require_relative 'plan_my_stuff/client'
-require_relative 'plan_my_stuff/comment'
-require_relative 'plan_my_stuff/comment_metadata'
-require_relative 'plan_my_stuff/configuration'
-require_relative 'plan_my_stuff/custom_fields'
-require_relative 'plan_my_stuff/engine' if defined?(Rails)
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  'graphql' => 'GraphQL',
+  'version' => 'VERSION',
+)
+loader.ignore(
+  File.join(__dir__, 'generators'),
+  File.join(__dir__, 'tasks'),
+  File.join(__dir__, 'plan_my_stuff', 'aws_sns_simulator.rb'),
+  File.join(__dir__, 'plan_my_stuff', 'engine.rb'),
+  File.join(__dir__, 'plan_my_stuff', 'errors.rb'),
+  File.join(__dir__, 'plan_my_stuff', 'test_helpers.rb'),
+  File.join(__dir__, 'plan_my_stuff', 'webhook_replayer.rb'),
+)
+loader.setup
+
+# errors.rb defines several sibling error classes - load it eagerly rather
+# than rely on autoload-via-lead-constant.
 require_relative 'plan_my_stuff/errors'
-require_relative 'plan_my_stuff/issue'
-require_relative 'plan_my_stuff/issue_metadata'
-require_relative 'plan_my_stuff/label'
-require_relative 'plan_my_stuff/markdown'
-require_relative 'plan_my_stuff/metadata_parser'
-require_relative 'plan_my_stuff/project'
-require_relative 'plan_my_stuff/project_item'
-require_relative 'plan_my_stuff/user_resolver'
-require_relative 'plan_my_stuff/verifier'
-require_relative 'plan_my_stuff/version'
+
+# Engine must register with Rails at load time, so eagerly require it
+# (and only when Rails is defined - otherwise Rails::Engine is undefined).
+require_relative 'plan_my_stuff/engine' if defined?(Rails)
 
 module PlanMyStuff
   class << self
     # @return [PlanMyStuff::Configuration]
     def configuration
-      @configuration ||= Configuration.new
+      @configuration ||= PlanMyStuff::Configuration.new
+    end
+
+    # @return [ActiveSupport::Deprecation]
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new('1.0', 'PlanMyStuff')
     end
 
     # @return [PlanMyStuff::Configuration]
@@ -37,7 +50,12 @@ module PlanMyStuff
 
     # @return [PlanMyStuff::Client]
     def client
-      @client ||= Client.new
+      @client ||= PlanMyStuff::Client.new
+    end
+
+    # @return [PlanMyStuff::Client]
+    def import_client
+      @import_client ||= PlanMyStuff::Client.new(importing: true)
     end
 
     # Returns the appropriate HTTP 422 status symbol for the current Rails version.
@@ -53,13 +71,30 @@ module PlanMyStuff
       end
     end
 
+    # Formats a time-ish value as an ISO 8601 string. +Time+ and
+    # +DateTime+ are normalized to UTC; +Date+ is serialized as-is.
+    #
+    # @param value [Time, DateTime, Date, String, nil]
+    #
+    # @return [String, nil]
+    #
+    def format_time(value)
+      return if value.nil?
+      return value if value.is_a?(String)
+      return value.iso8601 if value.is_a?(Date) && !value.is_a?(DateTime)
+
+      value.utc.iso8601
+    end
+
     # Resets the memoized client and configuration. Useful for testing.
     #
     # @return [void]
     #
     def reset!
       exit_test_mode! if defined?(@_test_mode) && @_test_mode
+      PlanMyStuff::Client.exit_trace_mode!
       @client = nil
+      @import_client = nil
       @configuration = nil
     end
   end