rails_error_dashboard 0.8.0 → 0.8.2

data/lib/rails_error_dashboard/services/linear_issue_client.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  module Services
+    # Linear GraphQL API client for issue management.
+    #
+    # API Docs: https://developers.linear.app/docs/graphql/working-with-the-graphql-api
+    # Auth: Personal API key (Settings > Security & access > Personal API keys)
+    # Rate limit: 1,500 requests/hour per API key
+    #
+    # Unlike the git forges, Linear has no "owner/repo" — issues belong to a
+    # team. The `repo` argument holds the team key (e.g. "ENG"), and issues
+    # are addressed by their human identifier ("ENG-123"), reconstructed from
+    # the team key plus the team-scoped issue number we store.
+    #
+    # Linear also has no open/closed binary — issues move between typed
+    # workflow states. Closing maps to the team's first `completed`-type
+    # state, reopening to the first `unstarted` (or `backlog`) state.
+    class LinearIssueClient < IssueTrackerClient
+      REOPEN_STATE_TYPES = [ "unstarted", "backlog", "triage" ].freeze
+
+      def initialize(token:, repo:, api_url: nil)
+        super
+        @api_url = api_url || "https://api.linear.app/graphql"
+      end
+
+      def create_issue(title:, body:, labels: [])
+        return error_response(@last_error || "Linear team '#{@repo}' not found") unless team_id
+
+        input = { teamId: team_id, title: title, description: truncate_body(body) }
+        label_ids = resolve_label_ids(labels)
+        input[:labelIds] = label_ids if label_ids.any?
+
+        data = graphql(<<~GRAPHQL, input: input)
+          mutation($input: IssueCreateInput!) {
+            issueCreate(input: $input) { success issue { identifier number url } }
+          }
+        GRAPHQL
+
+        issue = data&.dig("issueCreate", "issue")
+        if issue
+          success_response(url: issue["url"], number: issue["number"])
+        else
+          error_response(@last_error || "Linear API error: issue creation failed")
+        end
+      end
+
+      def close_issue(number:)
+        update_issue_state(number, "completed")
+      end
+
+      def reopen_issue(number:)
+        update_issue_state(number, REOPEN_STATE_TYPES)
+      end
+
+      def add_comment(number:, body:)
+        issue_id = find_issue_id(number)
+        return error_response(@last_error || "Linear issue #{identifier_for(number)} not found") unless issue_id
+
+        data = graphql(<<~GRAPHQL, input: { issueId: issue_id, body: truncate_body(body) })
+          mutation($input: CommentCreateInput!) {
+            commentCreate(input: $input) { success comment { url } }
+          }
+        GRAPHQL
+
+        comment = data&.dig("commentCreate", "comment")
+        comment ? success_response(url: comment["url"]) : error_response(@last_error || "Linear API error: comment failed")
+      end
+
+      def fetch_comments(number:, per_page: 10)
+        data = graphql(<<~GRAPHQL, id: identifier_for(number), first: per_page)
+          query($id: String!, $first: Int!) {
+            issue(id: $id) {
+              comments(first: $first) {
+                nodes { body createdAt url user { name avatarUrl } }
+              }
+            }
+          }
+        GRAPHQL
+
+        nodes = data&.dig("issue", "comments", "nodes")
+        return error_response(@last_error || "Linear API error: could not fetch comments") unless nodes
+
+        comments = nodes.map { |c|
+          {
+            author: c.dig("user", "name"),
+            avatar_url: c.dig("user", "avatarUrl"),
+            body: c["body"],
+            created_at: c["createdAt"],
+            url: c["url"]
+          }
+        }
+        success_response(comments: comments)
+      end
+
+      def fetch_issue(number:)
+        data = graphql(<<~GRAPHQL, id: identifier_for(number))
+          query($id: String!) {
+            issue(id: $id) {
+              title
+              state { name type }
+              assignee { name avatarUrl }
+              labels { nodes { name color } }
+            }
+          }
+        GRAPHQL
+
+        issue = data&.dig("issue")
+        return error_response(@last_error || "Linear API error: could not fetch issue") unless issue
+
+        assignee = issue["assignee"]
+        success_response(
+          state: closed_state_type?(issue.dig("state", "type")) ? "closed" : "open",
+          title: issue["title"],
+          assignees: assignee ? [ { login: assignee["name"], avatar_url: assignee["avatarUrl"] } ] : [],
+          labels: (issue.dig("labels", "nodes") || []).map { |l|
+            { name: l["name"], color: l["color"]&.delete("#") }
+          }
+        )
+      end
+
+      private
+
+      # Linear issues are addressed by "TEAM-123" — team key + stored number
+      def identifier_for(number)
+        "#{@repo}-#{number}"
+      end
+
+      def closed_state_type?(state_type)
+        [ "completed", "canceled" ].include?(state_type)
+      end
+
+      def update_issue_state(number, state_types)
+        issue_id = find_issue_id(number)
+        return error_response(@last_error || "Linear issue #{identifier_for(number)} not found") unless issue_id
+
+        state_id = workflow_state_id(Array(state_types))
+        return error_response(@last_error || "No matching workflow state for #{Array(state_types).join('/')}") unless state_id
+
+        data = graphql(<<~GRAPHQL, id: issue_id, input: { stateId: state_id })
+          mutation($id: String!, $input: IssueUpdateInput!) {
+            issueUpdate(id: $id, input: $input) { success }
+          }
+        GRAPHQL
+
+        data&.dig("issueUpdate", "success") ? success_response({}) : error_response(@last_error || "Linear API error: state update failed")
+      end
+
+      def find_issue_id(number)
+        data = graphql("query($id: String!) { issue(id: $id) { id } }", id: identifier_for(number))
+        data&.dig("issue", "id")
+      end
+
+      def team_id
+        @team_id ||= begin
+          data = graphql(<<~GRAPHQL, key: @repo)
+            query($key: String!) {
+              teams(filter: { key: { eq: $key } }) { nodes { id } }
+            }
+          GRAPHQL
+          data&.dig("teams", "nodes", 0, "id")
+        end
+      end
+
+      # Pick the first workflow state whose type matches, in preference order
+      def workflow_state_id(preferred_types)
+        states = workflow_states
+        return nil unless states
+
+        preferred_types.each do |type|
+          match = states.find { |s| s["type"] == type }
+          return match["id"] if match
+        end
+        nil
+      end
+
+      def workflow_states
+        @workflow_states ||= begin
+          data = graphql(<<~GRAPHQL, key: @repo)
+            query($key: String!) {
+              workflowStates(filter: { team: { key: { eq: $key } } }) {
+                nodes { id name type position }
+              }
+            }
+          GRAPHQL
+          data&.dig("workflowStates", "nodes")&.sort_by { |s| s["position"].to_f }
+        end
+      end
+
+      # Best-effort: resolve label names to UUIDs, creating missing ones.
+      # Label failures must never block issue creation.
+      def resolve_label_ids(names)
+        names = Array(names).map(&:to_s).reject(&:empty?)
+        return [] if names.empty?
+
+        data = graphql(<<~GRAPHQL, names: names)
+          query($names: [String!]) {
+            issueLabels(filter: { name: { in: $names } }) { nodes { id name } }
+          }
+        GRAPHQL
+        existing = data&.dig("issueLabels", "nodes") || []
+        ids = existing.map { |l| l["id"] }
+
+        missing = names - existing.map { |l| l["name"] }
+        missing.each do |name|
+          created = graphql(<<~GRAPHQL, input: { name: name, teamId: team_id })
+            mutation($input: IssueLabelCreateInput!) {
+              issueLabelCreate(input: $input) { issueLabel { id } }
+            }
+          GRAPHQL
+          id = created&.dig("issueLabelCreate", "issueLabel", "id")
+          ids << id if id
+        end
+
+        ids
+      rescue
+        []
+      end
+
+      # Execute a GraphQL request. Returns the "data" hash, or nil on any
+      # error (with the message stashed in @last_error for the caller).
+      def graphql(query, variables = {})
+        @last_error = nil
+        response = http_post(@api_url, { query: query, variables: variables }, auth_headers)
+
+        if response[:status] != 200
+          message = response.dig(:body, "errors", 0, "message") || response[:error]
+          @last_error = "Linear API error (#{response[:status]}): #{message}"
+          return nil
+        end
+
+        errors = response.dig(:body, "errors")
+        if errors.present?
+          @last_error = "Linear API error: #{errors.first["message"]}"
+          return nil
+        end
+
+        response.dig(:body, "data")
+      end
+
+      def auth_headers
+        # Personal API keys are passed bare; OAuth tokens need a Bearer prefix
+        value = @token.to_s.start_with?("lin_api_") ? @token : "Bearer #{@token}"
+        { "Authorization" => value }
+      end
+    end
+  end
+end

data/lib/rails_error_dashboard/services/storm_protection/circuit_breaker.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  module Services
+    module StormProtection
+      # Per-process circuit breaker for the error capture path.
+      #
+      # Counts capture attempts in fixed 10-second buckets and transitions
+      # between states based on the completed bucket's rate:
+      #
+      #   :closed    — normal operation, per-fingerprint buckets decide fidelity
+      #   :shedding  — elevated rate: context shed, notifications suppressed
+      #   :open      — storm: count-only mode, zero per-event I/O
+      #   :half_open — post-cooldown probe: small sample admitted, watching rate
+      #
+      # Hysteresis: opens FAST (a single hot bucket, or mid-bucket fast-trip),
+      # closes SLOW (two consecutive calm buckets) to prevent flapping.
+      #
+      # Concurrency: the hot path is one AtomicFixnum increment plus a float
+      # comparison. The mutex is taken only on bucket roll (once per 10s) and
+      # for state transitions — never per event.
+      class CircuitBreaker
+        BUCKET_SECONDS = 10
+        CALM_BUCKETS_TO_CLOSE = 2
+
+        attr_reader :state
+
+        # @param clock [#call] returns monotonic seconds; injectable for tests
+        def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+          @clock = clock
+          @mutex = Mutex.new
+          reset!
+        end
+
+        def reset!
+          @mutex.synchronize do
+            @state = :closed
+            @bucket_start = @clock.call
+            @bucket_count = Concurrent::AtomicFixnum.new(0)
+            @calm_buckets = 0
+            @opened_at = nil
+            @episode = nil
+          end
+        end
+
+        # Count one capture attempt and return the state that should govern it.
+        # Called on EVERY capture — must stay allocation-free on the fast path.
+        def record!
+          now = @clock.call
+          roll!(now) if now - @bucket_start >= BUCKET_SECONDS
+
+          count = @bucket_count.increment
+
+          # Fast-trip: don't wait for the bucket to complete if it's already
+          # over the open threshold — at 50k errors/min a full 10s bucket
+          # would let ~8k events through before reacting.
+          if count >= open_threshold * BUCKET_SECONDS && @state != :open
+            trip_open!(now, count)
+          end
+
+          @state
+        end
+
+        # Episode metadata for the honesty layer (storm_events row).
+        # @return [Hash, nil] nil when no episode is active or recently closed
+        def episode_snapshot
+          @mutex.synchronize { @episode&.dup }
+        end
+
+        # Forget a closed episode once it has been persisted by the flush job.
+        def clear_closed_episode!
+          @mutex.synchronize do
+            @episode = nil if @episode && @episode[:ended_at]
+          end
+        end
+
+        private
+
+        def roll!(now)
+          @mutex.synchronize do
+            elapsed = now - @bucket_start
+            return if elapsed < BUCKET_SECONDS # another thread already rolled
+
+            rate = @bucket_count.value / elapsed.to_f
+            @bucket_start = now
+            @bucket_count = Concurrent::AtomicFixnum.new(0)
+            transition!(rate, now)
+          end
+        end
+
+        # Transition table — runs inside @mutex, once per bucket roll.
+        # track_peak runs AFTER the case: a transition out of :closed creates
+        # the episode, and the triggering bucket's rate must be its first peak.
+        def transition!(rate, now)
+          case @state
+          when :closed
+            if rate >= open_threshold
+              open!(now)
+            elsif rate >= shedding_threshold
+              enter!(:shedding, now)
+            end
+          when :shedding
+            if rate >= open_threshold
+              open!(now)
+            elsif rate < shedding_threshold / 2.0
+              calm_step!(now)
+            else
+              @calm_buckets = 0
+            end
+          when :open
+            if now - @opened_at >= cooldown_seconds && rate < shedding_threshold
+              @state = :half_open
+              @calm_buckets = 0
+            end
+          when :half_open
+            if rate >= shedding_threshold
+              open!(now)
+            else
+              calm_step!(now)
+            end
+          end
+
+          track_peak(rate)
+        end
+
+        def calm_step!(now)
+          @calm_buckets += 1
+          close!(now) if @calm_buckets >= CALM_BUCKETS_TO_CLOSE
+        end
+
+        def enter!(new_state, _now)
+          begin_episode! if @state == :closed
+          @state = new_state
+          @calm_buckets = 0
+        end
+
+        def open!(now)
+          begin_episode! if @state == :closed
+          @state = :open
+          @opened_at = now
+          @calm_buckets = 0
+          @episode[:reached_open] = true if @episode
+        end
+
+        # Mid-bucket fast trip — takes the mutex (rare: at most once per storm onset).
+        def trip_open!(now, count)
+          @mutex.synchronize do
+            return if @state == :open
+
+            begin_episode! if @state == :closed
+            track_peak(count / [ now - @bucket_start, 1.0 ].max)
+            @state = :open
+            @opened_at = now
+            @calm_buckets = 0
+            @episode[:reached_open] = true if @episode
+          end
+        end
+
+        def close!(_now)
+          @state = :closed
+          @calm_buckets = 0
+          @episode[:ended_at] = Time.current if @episode
+        end
+
+        def begin_episode!
+          @episode = {
+            started_at: Time.current,
+            ended_at: nil,
+            peak_rate_per_minute: 0,
+            reached_open: false
+          }
+        end
+
+        def track_peak(rate_per_second)
+          return unless @episode
+
+          per_minute = (rate_per_second * 60).round
+          @episode[:peak_rate_per_minute] = per_minute if per_minute > @episode[:peak_rate_per_minute]
+        end
+
+        def shedding_threshold
+          RailsErrorDashboard.configuration.storm_shedding_threshold_per_second.to_f
+        end
+
+        def open_threshold
+          RailsErrorDashboard.configuration.storm_open_threshold_per_second.to_f
+        end
+
+        def cooldown_seconds
+          RailsErrorDashboard.configuration.storm_cooldown_seconds.to_i
+        end
+      end
+    end
+  end
+end

data/lib/rails_error_dashboard/services/storm_protection/count_buffer.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  module Services
+    module StormProtection
+      # In-memory accumulator for events that are counted but not stored
+      # per-event (Layer 1 overflow and the breaker's count-only mode).
+      #
+      # Stores exact counts plus just enough identity to reconcile onto the
+      # right ErrorLog at flush time: the flush command recomputes the
+      # canonical error_hash from these parts (with application resolved in
+      # the background job, where DB access is allowed) and issues a single
+      # `occurrence_count = occurrence_count + N` UPDATE per fingerprint.
+      # Fingerprints first seen during count-only mode get a minimal ErrorLog
+      # created from the stored exemplar. Counting is exact — no extrapolation.
+      #
+      # Memory: bounded map; beyond the cap events land in a single overflow
+      # counter (still exact in total, anonymous in identity).
+      #
+      # Concurrency: snapshot! atomically swaps the whole map out via
+      # AtomicReference, so flushing never races with recording.
+      class CountBuffer
+        Entry = Struct.new(
+          :error_class, :message, :first_app_frame,
+          :controller_name, :action_name, :custom_hash,
+          :count, :first_seen_at, :last_seen_at
+        )
+
+        def initialize
+          reset!
+        end
+
+        def reset!
+          @map_ref = Concurrent::AtomicReference.new(Concurrent::Map.new)
+          @overflow = Concurrent::AtomicFixnum.new(0)
+        end
+
+        # Record one counted-not-stored event.
+        # @param gate_key [String] cheap in-process bucketing key
+        # @param parts [Hash] identity parts captured at the gate
+        def record(gate_key, parts)
+          map = @map_ref.get
+          entry = map[gate_key]
+
+          unless entry
+            if map.size >= max_tracked
+              @overflow.increment
+              return
+            end
+            entry = map.compute_if_absent(gate_key) do
+              Entry.new(
+                parts[:error_class], parts[:message], parts[:first_app_frame],
+                parts[:controller_name], parts[:action_name], parts[:custom_hash],
+                Concurrent::AtomicFixnum.new(0), Time.current, Time.current
+              )
+            end
+          end
+
+          entry.count.increment
+          entry.last_seen_at = Time.current
+        end
+
+        def any?
+          @overflow.value.positive? || !@map_ref.get.empty?
+        end
+
+        # Atomically swap the buffer out and return serializable entry hashes.
+        # @return [Hash] { entries: Array<Hash>, overflow: Integer }
+        def snapshot!
+          old_map = @map_ref.get_and_set(Concurrent::Map.new)
+          overflow = @overflow.value
+          @overflow.update { |v| v - overflow }
+
+          entries = []
+          old_map.each_pair do |_key, entry|
+            entries << {
+              "error_class" => entry.error_class,
+              "message" => entry.message,
+              "first_app_frame" => entry.first_app_frame,
+              "controller_name" => entry.controller_name,
+              "action_name" => entry.action_name,
+              "custom_hash" => entry.custom_hash,
+              "count" => entry.count.value,
+              "first_seen_at" => entry.first_seen_at.iso8601,
+              "last_seen_at" => entry.last_seen_at.iso8601
+            }
+          end
+
+          { entries: entries, overflow: overflow }
+        end
+
+        private
+
+        def max_tracked
+          RailsErrorDashboard.configuration.storm_max_tracked_fingerprints.to_i
+        end
+      end
+    end
+  end
+end

data/lib/rails_error_dashboard/services/storm_protection/fingerprint_buckets.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module RailsErrorDashboard
+  module Services
+    module StormProtection
+      # Layer 1: per-fingerprint rate limiting with graceful degradation.
+      #
+      # Each fingerprint gets a 60-second window. Within the window:
+      #   - first N events            → :full  (everything captured)
+      #   - past N, every Mth event   → :lite  (row captured, context shed)
+      #   - everything else           → :count_only (in-memory count, flushed later)
+      #
+      # The first event of every window is ALWAYS at least :lite, so a
+      # melting-down fingerprint still has a fresh exemplar each minute —
+      # deterministic, unlike rand-based sampling.
+      #
+      # Calm-mode adaptive context sampling rides the same entries: after K
+      # full-context captures per fingerprint per day, context is captured
+      # only every Mth time (an error firing 1000×/day doesn't need 1000
+      # breadcrumb trails). Occurrence rows are unaffected in calm mode.
+      #
+      # Concurrency: entries are mutable structs in a Concurrent::Map with
+      # plain (unlocked) field increments — races can miscount by a handful
+      # of events, which is acceptable for rate limiting. No mutex anywhere.
+      #
+      # Memory: the map is bounded. Once full, unseen fingerprints are NOT
+      # tracked and decide as :full — in calm weather that's harmless; in a
+      # storm of unique fingerprints the global breaker (Layer 2) takes over.
+      class FingerprintBuckets
+        WINDOW_SECONDS = 60
+        DAY_SECONDS = 86_400
+
+        Entry = Struct.new(:window_start, :window_count, :day_start, :day_full_context_count)
+
+        def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+          @clock = clock
+          reset!
+        end
+
+        def reset!
+          @entries = Concurrent::Map.new
+        end
+
+        # Decide capture fidelity for one event of this fingerprint.
+        # @return [Symbol] :full, :lite, or :count_only
+        def decide(gate_key)
+          now = @clock.call
+          entry = fetch_entry(gate_key, now)
+          return :full unless entry # map full — Layer 2 owns the storm case
+
+          roll_windows(entry, now)
+          entry.window_count += 1
+          n = entry.window_count
+
+          if n <= full_per_minute
+            decide_calm_context(entry)
+          elsif n == full_per_minute + 1 || ((n - full_per_minute) % keep_every).zero?
+            :lite
+          else
+            :count_only
+          end
+        end
+
+        private
+
+        def fetch_entry(gate_key, now)
+          existing = @entries[gate_key]
+          return existing if existing
+
+          # Bounded: never insert past the cap (size check is approximate
+          # under concurrency — a few entries over the cap is fine)
+          return nil if @entries.size >= max_tracked
+
+          @entries.compute_if_absent(gate_key) { Entry.new(now, 0, now, 0) }
+        end
+
+        def roll_windows(entry, now)
+          if now - entry.window_start >= WINDOW_SECONDS
+            entry.window_start = now
+            entry.window_count = 0
+          end
+          if now - entry.day_start >= DAY_SECONDS
+            entry.day_start = now
+            entry.day_full_context_count = 0
+          end
+        end
+
+        # Under the per-minute cap: full context unless this fingerprint has
+        # already produced plenty of full-context captures today.
+        def decide_calm_context(entry)
+          entry.day_full_context_count += 1
+          k = entry.day_full_context_count
+
+          if k <= context_threshold_per_day || (k % context_keep_every).zero?
+            :full
+          else
+            :lite
+          end
+        end
+
+        def full_per_minute
+          RailsErrorDashboard.configuration.storm_fingerprint_full_per_minute.to_i
+        end
+
+        def keep_every
+          [ RailsErrorDashboard.configuration.storm_occurrence_sample_keep_every.to_i, 1 ].max
+        end
+
+        def context_threshold_per_day
+          RailsErrorDashboard.configuration.context_sampling_threshold_per_day.to_i
+        end
+
+        def context_keep_every
+          [ RailsErrorDashboard.configuration.context_sampling_keep_every.to_i, 1 ].max
+        end
+
+        def max_tracked
+          RailsErrorDashboard.configuration.storm_max_tracked_fingerprints.to_i
+        end
+      end
+    end
+  end
+end