RubyGems - bug_reports_client - Versions diffs - 0.1.0 - Mend

bug_reports_client 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (58) hide show

data/app/controllers/bug_reports_client/webhooks_controller.rb ADDED Viewed

@@ -0,0 +1,94 @@
+module BugReportsClient
+  # Receives closure notifications from the bug-reports API when a report's
+  # GitHub issue is closed. Deliberately inherits from ActionController::Base
+  # (not the host's ApplicationController) so no host auth chain or callbacks
+  # interfere with machine-to-machine requests. Payloads are verified with a
+  # per-app HMAC-SHA256 signature before anything is touched; when the sender
+  # includes a signed timestamp, stale (replayed) callbacks are rejected too.
+  class WebhooksController < ActionController::Base
+    class SignatureError < StandardError; end
+    # Callback payloads are small JSON documents - anything bigger is bogus.
+    MAX_BODY_BYTES = 1_048_576
+    # How old a timestamped callback may be before it is treated as a replay.
+    TIMESTAMP_TOLERANCE = 5 * 60
+    skip_forgery_protection
+    # POST /webhook
+    def receive
+      return head :content_too_large if request.content_length.to_i > MAX_BODY_BYTES
+      raw_body = request.raw_post
+      verify_signature!(raw_body)
+      payload = JSON.parse(raw_body)
+      Rails.logger.info "BugReportsClient: report closed: ##{payload['bug_report_id']} - #{payload['title']}"
+      # Mark the local record closed so the reporter sees the resolved alert.
+      # A bare column write, not update!: legacy reports (or ones predating a
+      # form-schema change that added required fields) must still be closable.
+      local_report = BugReport.find_by(remote_bug_report_id: payload["bug_report_id"])
+      if local_report
+        local_report.update_columns(status: "closed", updated_at: Time.current)
+      else
+        Rails.logger.warn "BugReportsClient: no local report for remote ID #{payload['bug_report_id']}"
+      end
+      head :ok
+    rescue SignatureError
+      head :unauthorized
+    rescue JSON::ParserError => e
+      Rails.logger.error "BugReportsClient: webhook parse error: #{e.message}"
+      head :unprocessable_entity
+    end
+    private
+    # Verifies the HMAC-SHA256 signature using the per-app webhook secret.
+    # Preferred scheme: X-Timestamp + X-Signature-Timestamped, where the HMAC
+    # covers "<timestamp>.<body>" and the timestamp must be recent (replay
+    # protection). Falls back to the legacy body-only X-Signature when no
+    # timestamp headers are sent.
+    def verify_signature!(raw_body)
+      secret = BugReportsClient.config.webhook_secret
+      if secret.blank?
+        Rails.logger.error "BugReportsClient: webhook secret not configured"
+        raise SignatureError, "Webhook secret not configured"
+      end
+      if request.headers["X-Timestamp"].present?
+        verify_timestamped!(secret, raw_body)
+      else
+        verify_legacy!(secret, raw_body)
+      end
+    end
+    def verify_timestamped!(secret, raw_body)
+      timestamp = request.headers["X-Timestamp"].to_s
+      unless timestamp.match?(/\A\d+\z/) && (Time.current.to_i - timestamp.to_i).abs <= TIMESTAMP_TOLERANCE
+        Rails.logger.warn "BugReportsClient: webhook timestamp stale or malformed"
+        raise SignatureError, "Stale timestamp"
+      end
+      signature = request.headers["X-Signature-Timestamped"].to_s
+      expected = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp}.#{raw_body}")}"
+      unless ActiveSupport::SecurityUtils.secure_compare(signature, expected)
+        Rails.logger.warn "BugReportsClient: webhook timestamped signature mismatch"
+        raise SignatureError, "Invalid signature"
+      end
+    end
+    def verify_legacy!(secret, raw_body)
+      signature = request.headers["X-Signature"].to_s
+      expected = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', secret, raw_body)}"
+      unless ActiveSupport::SecurityUtils.secure_compare(signature, expected)
+        Rails.logger.warn "BugReportsClient: webhook signature mismatch"
+        raise SignatureError, "Invalid signature"
+      end
+    end
+  end
+end

data/app/helpers/bug_reports_client/bug_reports_helper.rb ADDED Viewed

@@ -0,0 +1,61 @@
+module BugReportsClient
+  # View helpers for the engine's own pages, plus `bug_report_alerts` which is
+  # exposed to host layouts so resolved-report notifications can be rendered
+  # with a single line: <%= bug_report_alerts %>
+  module BugReportsHelper
+    # Renders dismissable "your report has been resolved" alerts for the
+    # signed-in user. Returns nil quickly when signed out or nothing resolved,
+    # so it is safe on every page including public ones.
+    def bug_report_alerts
+      user = alerts_user
+      return if user.nil?
+      resolved = BugReportsClient::BugReport.where(user: user).resolved_and_undismissed.order(created_at: :desc)
+      return if resolved.empty?
+      render "bug_reports_client/shared/alerts", resolved_bug_reports: resolved
+    end
+    # Pill used for the type filter (All types / Bugs / Features). When
+    # active, each type carries its own accent colour to match the row badges.
+    def report_type_pill_class(active, type = nil)
+      base = "inline-flex items-center gap-1 px-3 py-1 rounded-full border text-sm font-medium transition-colors"
+      return "#{base} bg-white text-slate-500 border-slate-200 hover:text-slate-700 hover:border-slate-300" unless active
+      case type
+      when "bug" then "#{base} bg-rose-100 text-rose-700 border-rose-200"
+      when "feature" then "#{base} bg-indigo-100 text-indigo-700 border-indigo-200"
+      else "#{base} bg-slate-700 text-white border-slate-700"
+      end
+    end
+    # Shared input styling for the default form - one place to tweak the look
+    # of every generated field.
+    def brc_input_classes
+      "w-full rounded-lg border border-slate-300 bg-white px-3 py-2 text-sm text-slate-900 " \
+      "placeholder:text-slate-400 focus:border-slate-500 focus:outline-none focus:ring-1 focus:ring-slate-500 " \
+      "disabled:bg-slate-100 disabled:text-slate-500"
+    end
+    def brc_label_classes
+      "block text-xs font-medium text-slate-500 uppercase tracking-wide mb-1"
+    end
+    private
+    # The current user as seen from the HOST's context (this helper runs in
+    # host layouts). Alerts are cosmetic, so ANY failure resolving the user -
+    # a missing method, or e.g. Devise raising outside a real request
+    # (mailer previews, ActionController.renderer) - means "no alerts", never
+    # a broken page.
+    def alerts_user
+      method = BugReportsClient.config.current_user_method
+      return nil unless controller.respond_to?(method, true)
+      controller.send(method)
+    rescue StandardError => e
+      Rails.logger.debug { "BugReportsClient: bug_report_alerts skipped (#{e.class}: #{e.message})" }
+      nil
+    end
+  end
+end

data/app/javascript/bug_reports_client/controllers/error_summary_controller.js ADDED Viewed

@@ -0,0 +1,14 @@
+// Scrolls the validation error box into view when a re-rendered form
+// appears. Turbo preserves scroll position on 422 re-renders, so without
+// this a user who submitted from the bottom of a long form never sees the
+// errors at the top.
+//
+// Registered by the host's Stimulus loader as
+// "bug-reports-client--error-summary".
+import { Controller } from "@hotwired/stimulus"
+export default class extends Controller {
+  connect() {
+    this.element.scrollIntoView({ behavior: "smooth", block: "start" })
+  }
+}

data/app/javascript/bug_reports_client/controllers/file_limit_controller.js ADDED Viewed

@@ -0,0 +1,31 @@
+// Validates the number of files selected in a file input. Shows a
+// native-style validation message if the limit is exceeded.
+//
+// Registered by the host's Stimulus loader as "bug-reports-client--file-limit".
+//
+// Usage:
+//   <div data-controller="bug-reports-client--file-limit"
+//        data-bug-reports-client--file-limit-max-value="5">
+//     <input type="file" multiple
+//            data-bug-reports-client--file-limit-target="input"
+//            data-action="change->bug-reports-client--file-limit#validate">
+//   </div>
+import { Controller } from "@hotwired/stimulus"
+export default class extends Controller {
+  static targets = ["input"]
+  static values = { max: { type: Number, default: 5 } }
+  validate() {
+    const input = this.inputTarget
+    const max = this.maxValue
+    if (input.files.length > max) {
+      input.setCustomValidity(`You can attach a maximum of ${max} images.`)
+      input.reportValidity()
+      input.value = ""
+    } else {
+      input.setCustomValidity("")
+    }
+  }
+}

data/app/javascript/bug_reports_client/controllers/report_type_controller.js ADDED Viewed

@@ -0,0 +1,54 @@
+// Swaps the form fields based on the selected report type: bugs and feature
+// requests collect different information, so only the matching group is shown.
+// The hidden group's inputs are disabled so they neither submit nor block
+// `required` validation. Readonly (closed) reports keep their disabled state.
+//
+// Registered by the host's Stimulus loader as "bug-reports-client--report-type".
+//
+// Usage (radio cards - a select or hidden input also works as the target):
+//   <form data-controller="bug-reports-client--report-type"
+//         data-bug-reports-client--report-type-readonly-value="false">
+//     <input type="radio" value="bug" data-bug-reports-client--report-type-target="type"
+//            data-action="change->bug-reports-client--report-type#toggle">
+//     <div data-bug-reports-client--report-type-target="bugFields">...</div>
+//     <div data-bug-reports-client--report-type-target="featureFields">...</div>
+import { Controller } from "@hotwired/stimulus"
+export default class extends Controller {
+  static targets = ["type", "bugFields", "featureFields", "summary"]
+  static values = { readonly: Boolean, bugSummary: String, featureSummary: String }
+  connect() {
+    this.toggle()
+  }
+  toggle() {
+    const isFeature = this.currentType() === "feature"
+    if (this.hasFeatureFieldsTarget) this.applyGroup(this.featureFieldsTarget, isFeature)
+    if (this.hasBugFieldsTarget) this.applyGroup(this.bugFieldsTarget, !isFeature)
+    if (this.hasSummaryTarget) {
+      this.summaryTarget.placeholder = isFeature ? this.featureSummaryValue : this.bugSummaryValue
+    }
+  }
+  // The type targets are either radio cards (one per type) or a single
+  // select/hidden input - support both so hosts can restyle freely.
+  currentType() {
+    const radios = this.typeTargets.filter((input) => input.type === "radio")
+    if (radios.length > 0) {
+      const checked = radios.find((radio) => radio.checked)
+      return checked ? checked.value : "bug"
+    }
+    return this.typeTargets[0]?.value
+  }
+  applyGroup(group, show) {
+    group.classList.toggle("hidden", !show)
+    if (this.readonlyValue) return
+    group.querySelectorAll("input, select, textarea").forEach((input) => {
+      input.disabled = !show
+    })
+  }
+}

data/app/javascript/bug_reports_client/controllers/screenshot_dropzone_controller.js ADDED Viewed

@@ -0,0 +1,151 @@
+// Drag-and-drop screenshot picker with small client-side previews.
+// The hidden multiple file input remains the source of truth for form
+// submission - this controller keeps input.files in sync with an internal
+// DataTransfer store, so the server sees a perfectly normal file upload.
+//
+// Registered by the host's Stimulus loader as
+// "bug-reports-client--screenshot-dropzone".
+//
+// Targets: zone (the drop area), input (hidden file input),
+//          previews (thumbnail container), message (limit warnings)
+// Values:  max (file limit), limitMessage (warning text, from i18n)
+import { Controller } from "@hotwired/stimulus"
+export default class extends Controller {
+  static targets = ["zone", "input", "previews", "message"]
+  static values = {
+    max: { type: Number, default: 5 },
+    maxBytes: { type: Number, default: 10_485_760 },
+    limitMessage: String,
+    sizeMessage: String
+  }
+  connect() {
+    this.store = new DataTransfer()
+  }
+  disconnect() {
+    this.revokePreviewUrls()
+  }
+  browse() {
+    this.inputTarget.click()
+  }
+  keydown(event) {
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault()
+      this.browse()
+    }
+  }
+  // Files chosen via the browse dialog are merged into the current selection
+  // rather than replacing it, matching how dropping behaves.
+  picked() {
+    this.add(this.inputTarget.files)
+  }
+  dragover(event) {
+    event.preventDefault()
+    this.zoneTarget.classList.add("border-slate-500", "bg-slate-100")
+  }
+  dragleave() {
+    this.zoneTarget.classList.remove("border-slate-500", "bg-slate-100")
+  }
+  drop(event) {
+    event.preventDefault()
+    this.dragleave()
+    this.add(event.dataTransfer.files)
+  }
+  add(fileList) {
+    this.clearMessage()
+    for (const file of Array.from(fileList)) {
+      if (!file.type.startsWith("image/")) continue
+      if (this.alreadySelected(file)) continue
+      // Oversized files are refused here, at selection time - far better
+      // than a server-side rejection after the user has submitted.
+      if (file.size > this.maxBytesValue) {
+        this.showMessage(this.sizeMessageValue.replace("%{filename}", file.name))
+        continue
+      }
+      if (this.store.items.length >= this.maxValue) {
+        this.showMessage(this.limitMessageValue)
+        break
+      }
+      this.store.items.add(file)
+    }
+    this.sync()
+  }
+  remove(event) {
+    const index = Number(event.currentTarget.dataset.index)
+    const kept = new DataTransfer()
+    Array.from(this.store.files).forEach((file, i) => {
+      if (i !== index) kept.items.add(file)
+    })
+    this.store = kept
+    this.clearMessage()
+    this.sync()
+  }
+  // Keep input.files as the single submission source, then redraw previews.
+  sync() {
+    this.inputTarget.files = this.store.files
+    this.renderPreviews()
+  }
+  renderPreviews() {
+    this.revokePreviewUrls()
+    this.previewsTarget.innerHTML = ""
+    Array.from(this.store.files).forEach((file, index) => {
+      const tile = document.createElement("div")
+      tile.className = "relative"
+      const img = document.createElement("img")
+      img.src = URL.createObjectURL(file)
+      img.alt = file.name
+      img.className = "h-16 w-16 object-cover rounded-lg border border-slate-200"
+      const removeButton = document.createElement("button")
+      removeButton.type = "button"
+      removeButton.dataset.index = index
+      removeButton.dataset.action = "bug-reports-client--screenshot-dropzone#remove"
+      removeButton.setAttribute("aria-label", `Remove ${file.name}`)
+      removeButton.className = "absolute -top-1.5 -right-1.5 flex h-5 w-5 items-center justify-center rounded-full bg-slate-700 text-xs leading-none text-white hover:bg-slate-900"
+      removeButton.textContent = "×"
+      tile.appendChild(img)
+      tile.appendChild(removeButton)
+      this.previewsTarget.appendChild(tile)
+    })
+  }
+  alreadySelected(file) {
+    return Array.from(this.store.files).some((existing) =>
+      existing.name === file.name && existing.size === file.size && existing.lastModified === file.lastModified
+    )
+  }
+  revokePreviewUrls() {
+    this.previewsTarget.querySelectorAll("img").forEach((img) => URL.revokeObjectURL(img.src))
+  }
+  showMessage(text) {
+    if (this.hasMessageTarget) this.messageTarget.textContent = text
+  }
+  clearMessage() {
+    if (this.hasMessageTarget) this.messageTarget.textContent = ""
+  }
+}

data/app/jobs/bug_reports_client/report_error_job.rb ADDED Viewed

@@ -0,0 +1,44 @@
+module BugReportsClient
+  # Posts a captured error to the central API in the background, so the
+  # failing request is never slowed down (or broken further) by reporting.
+  # No retries: the API deduplicates by fingerprint and errors tend to recur,
+  # so a lost report costs little - a retry storm during an outage costs more.
+  class ReportErrorJob < ActiveJob::Base
+    queue_as :default
+    def perform(attributes)
+      title = "[Error] #{attributes['exception_class']}: #{attributes['message']}".truncate(150)
+      result = ApiClient.new.create_error_report(
+        title: title,
+        description: build_description(attributes),
+        fingerprint: attributes["fingerprint"],
+        occurred_at: attributes["occurred_at"]
+      )
+      Rails.logger.warn "BugReportsClient: error report not accepted: #{result.message}" unless result.success?
+    end
+    private
+    # Markdown for the GitHub issue: exception, message, fingerprint and a
+    # trimmed application backtrace.
+    def build_description(attributes)
+      <<~MARKDOWN
+        ## #{attributes['exception_class']}
+        ```
+        #{attributes['message']}
+        ```
+        **Fingerprint:** `#{attributes['fingerprint']}` | **First captured:** #{attributes['occurred_at']}
+        ### Application backtrace
+        ```
+        #{Array(attributes['backtrace']).join("\n")}
+        ```
+      MARKDOWN
+    end
+  end
+end

data/app/models/bug_reports_client/application_record.rb ADDED Viewed

@@ -0,0 +1,5 @@
+module BugReportsClient
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/bug_reports_client/bug_report.rb ADDED Viewed

@@ -0,0 +1,74 @@
+module BugReportsClient
+  # Local record of a report submitted to the central bug-reports API. Stores
+  # the report for user viewing/editing; the schema-driven answers live in the
+  # `responses` JSON column keyed by field name. Closure updates arrive via
+  # the signed webhook and flip status to closed, which surfaces the
+  # resolved-report alert until the user dismisses it.
+  class BugReport < ApplicationRecord
+    self.table_name = "bug_reports"
+    belongs_to :user, class_name: BugReportsClient.config.user_class
+    has_many_attached :screenshots
+    enum :status, { open: "open", closed: "closed" }
+    enum :severity, { low: "low", medium: "medium", high: "high", critical: "critical" }
+    enum :report_type, { bug: "bug", feature: "feature" }
+    validates :title, presence: true
+    validates :report_type, presence: true
+    validates :remote_bug_report_id, uniqueness: true, allow_nil: true
+    # The API requires a severity for bugs. When the host hides the picker
+    # (ask_severity false) the controller fills in the default before saving.
+    validates :severity, presence: true, if: :bug?
+    validate :required_responses_present
+    validate :screenshot_limit
+    scope :undismissed, -> { where(dismissed_at: nil) }
+    scope :resolved_and_undismissed, -> { closed.undismissed }
+    # Reads a single schema-field answer. Keys are always stored as strings.
+    def response(key)
+      (responses || {})[key.to_s]
+    end
+    # Merges new answers in rather than replacing, so partial updates (e.g. a
+    # type switch that only submits the visible fields) keep earlier answers.
+    def responses=(new_responses)
+      super((responses || {}).merge((new_responses || {}).stringify_keys))
+    end
+    # A bug's severity and a feature's `priority` field are the same "how
+    # important is this" rating shown in one list column.
+    def importance
+      feature? ? response("priority").presence || severity : severity
+    end
+    # Human-readable noun for user-facing copy ("bug report" / "feature request").
+    def type_noun
+      I18n.t("bug_reports_client.type_nouns.#{report_type.presence || 'bug'}")
+    end
+    private
+    # Enforces the schema's required fields for the selected report type.
+    # Checkboxes must be ticked; everything else must be present.
+    def required_responses_present
+      return if report_type.blank?
+      BugReportsClient.form_schema.required_fields(report_type).each do |field|
+        value = response(field.key)
+        missing = field.checkbox? ? !ActiveModel::Type::Boolean.new.cast(value) : value.blank?
+        errors.add(:base, I18n.t("bug_reports_client.errors.required_field", field: field.label_text)) if missing
+      end
+    end
+    def screenshot_limit
+      max = BugReportsClient.config.max_screenshots
+      if screenshots.count > max
+        errors.add(:base, I18n.t("bug_reports_client.errors.too_many_screenshots", max: max))
+      end
+    end
+  end
+end

data/app/models/bug_reports_client/error_event.rb ADDED Viewed

@@ -0,0 +1,46 @@
+module BugReportsClient
+  # A captured 500 attributed to the signed-in user who hit it. Surfaced on
+  # the report form ("did your problem relate to this error?") so user bug
+  # reports can reference the automatically-filed error issue by fingerprint.
+  # Events are short-lived working data - old ones are pruned on write.
+  class ErrorEvent < ApplicationRecord
+    self.table_name = "bug_report_error_events"
+    RETENTION = 30 * 24 * 60 * 60 # seconds; errors older than this are pruned
+    belongs_to :user, class_name: BugReportsClient.config.user_class
+    scope :recent_first, -> { order(occurred_at: :desc) }
+    scope :since, ->(time) { where(occurred_at: time..) }
+    # Records an occurrence for a user and prunes their stale events.
+    def self.record!(user_id:, fingerprint:, exception_class:, message:, occurred_at:, activity: nil)
+      where(user_id: user_id).where(occurred_at: ...(Time.current - RETENTION)).delete_all
+      create!(
+        user_id: user_id,
+        fingerprint: fingerprint,
+        exception_class: exception_class,
+        message: message.to_s.truncate(200),
+        activity: activity,
+        occurred_at: occurred_at
+      )
+    end
+    # Technical one-liner for the GitHub issue markdown - never shown to
+    # end users.
+    def summary
+      "#{exception_class}: #{message}".truncate(110)
+    end
+    # What the user sees on the report form: what they were doing, not the
+    # exception ("something went wrong while viewing invoices").
+    def user_facing_description
+      if activity.present?
+        I18n.t("bug_reports_client.form.related_error.option_with_activity", activity: activity)
+      else
+        I18n.t("bug_reports_client.form.related_error.option_generic")
+      end
+    end
+  end
+end

data/app/models/concerns/bug_reports_client/reporter.rb ADDED Viewed

@@ -0,0 +1,15 @@
+module BugReportsClient
+  # Included into the host app's user model (one documented line) to link
+  # users to their submitted reports:
+  #
+  #   class User < ApplicationRecord
+  #     include BugReportsClient::Reporter
+  #   end
+  module Reporter
+    extend ActiveSupport::Concern
+    included do
+      has_many :bug_reports, class_name: "BugReportsClient::BugReport", dependent: :destroy
+    end
+  end
+end