flare 0.1.0

data/lib/flare/cli/setup_command.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+require "base64"
+require "socket"
+require "net/http"
+require "uri"
+require "json"
+require "fileutils"
+require_relative "output"
+
+module Flare
+  class SetupCommand
+    include CLI::Output
+
+    DEFAULT_HOST = "https://flare.am"
+    TIMEOUT_SECONDS = 300 # 5 minutes
+
+    INITIALIZER_CONTENT = <<~RUBY
+      # frozen_string_literal: true
+
+      Flare.configure do |config|
+        # ── Spans (local development dashboard) ────────────────────────────
+        # Spans capture detailed trace data and are stored in a local SQLite
+        # database. Enabled by default in development only. Visit /flare in
+        # your browser to see the dashboard.
+
+        # Enable or disable spans (default: true in development)
+        # config.spans_enabled = true
+
+        # How long to keep spans in hours (default: 24)
+        # config.retention_hours = 24
+
+        # Maximum number of spans to store (default: 10000)
+        # config.max_spans = 10000
+
+        # Path to the SQLite database (default: db/flare.sqlite3)
+        # config.database_path = Rails.root.join("db", "flare.sqlite3").to_s
+
+        # Ignore specific requests (receives a Rack::Request, return true to ignore)
+        # config.ignore_request = ->(request) {
+        #   request.path.start_with?("/health")
+        # }
+
+        # ── Metrics (remote monitoring) ────────────────────────────────────
+        # Metrics aggregate span data into counts, durations, and error rates.
+        # Enabled by default in development and production (disabled in test).
+        # Sent to flare.am when FLARE_KEY is configured.
+
+        # Enable or disable metrics (default: true except in test)
+        # config.metrics_enabled = true
+
+        # How often to flush metrics in seconds (default: 60)
+        # config.metrics_flush_interval = 60
+
+        # ── Custom Instrumentation ─────────────────────────────────────────
+        # Subscribe to additional notification prefixes (default: ["app."])
+        # config.subscribe_patterns << "mycompany."
+      end
+
+      # ════════════════════════════════════════════════════════════════════════
+      # Custom Instrumentation
+      # ════════════════════════════════════════════════════════════════════════
+      #
+      # Use ActiveSupport::Notifications.instrument with an "app." prefix
+      # anywhere in your code. Flare captures these in development and
+      # displays them in the dashboard.
+      #
+      #   ActiveSupport::Notifications.instrument("app.geocoding", address: address) do
+      #     geocoder.lookup(address)
+      #   end
+      #
+      #   ActiveSupport::Notifications.instrument("app.stripe.charge", amount: 1000) do
+      #     Stripe::Charge.create(amount: 1000, currency: "usd")
+      #   end
+    RUBY
+
+    def initialize(force: false)
+      @force = force
+    end
+
+    def run
+      authenticate
+      create_initializer
+      add_gitignore_entries
+
+      puts
+      puts "#{green("Setup complete!")}"
+      puts
+      puts bold("What's next:")
+      puts "  1. Start your Rails server (#{dim("bin/rails server")})"
+      puts "  2. Make a few requests to your app"
+      puts "  3. Visit #{bold("/flare")} to see the dashboard"
+      puts
+      puts dim("  The dashboard auto-mounts at /flare in development.")
+      puts dim("  Metrics are sent to flare.am when FLARE_KEY is configured.")
+      puts
+      puts "  Run #{bold("flare doctor")} to verify your setup."
+      puts "  Run #{bold("flare status")} to see your configuration."
+    rescue Interrupt
+      puts
+      puts "Setup cancelled."
+      exit 1
+    end
+
+    private
+
+    # --- Auth ---
+
+    def authenticate
+      env_path = File.join(Dir.pwd, ".env")
+
+      if !@force && File.exist?(env_path) && File.read(env_path).match?(/^FLARE_KEY=.+/)
+        puts "#{checkmark} FLARE_KEY already set in .env, skipping auth."
+        puts "  Run with --force to re-authenticate."
+        return
+      end
+
+      server = nil
+      state = SecureRandom.hex(32)
+      code_verifier = SecureRandom.urlsafe_base64(32)
+      code_challenge = Base64.urlsafe_encode64(
+        Digest::SHA256.digest(code_verifier),
+        padding: false
+      )
+
+      server = TCPServer.new("127.0.0.1", 0)
+      port = server.addr[1]
+
+      host = ENV.fetch("FLARE_HOST", DEFAULT_HOST)
+      authorize_url = "#{host}/cli/authorize?state=#{state}&port=#{port}&code_challenge=#{code_challenge}"
+
+      puts "Opening browser to authorize Flare..."
+      open_browser(authorize_url)
+      puts
+      puts "If the browser didn't open, visit:"
+      puts "  #{authorize_url}"
+      puts
+      puts "Waiting for authorization (up to 5 minutes)..."
+
+      auth_code = wait_for_callback(server, state, TIMEOUT_SECONDS)
+
+      unless auth_code
+        puts "Timed out waiting for authorization."
+        exit 1
+      end
+
+      token = exchange_code(auth_code, code_verifier)
+      save_token(token)
+    ensure
+      server&.close
+    end
+
+    def wait_for_callback(server, expected_state, timeout)
+      deadline = Time.now + timeout
+
+      while Time.now < deadline
+        readable = IO.select([server], nil, nil, 1)
+        next unless readable
+
+        client = server.accept
+        request_line = client.gets
+
+        unless request_line&.start_with?("GET /callback")
+          client.print "HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n"
+          client.close
+          next
+        end
+
+        # Read remaining headers (required by HTTP spec)
+        while (line = client.gets) && line != "\r\n"; end
+
+        params = parse_query_string(request_line)
+        returned_state = params["state"]
+        code = params["code"]
+        error = params["error"]
+
+        if error
+          client.print http_response(error_page(error))
+          client.close
+          return nil
+        elsif returned_state != expected_state
+          client.print http_response(error_page("State mismatch. Please try again."))
+          client.close
+          return nil
+        elsif code.nil? || code.empty?
+          client.print http_response(error_page("No authorization code received."))
+          client.close
+          return nil
+        else
+          client.print http_response(success_page)
+          client.close
+          return code
+        end
+      end
+
+      nil
+    end
+
+    def parse_query_string(request_line)
+      return {} unless request_line
+      path = request_line.split(" ")[1]
+      return {} unless path
+      query = URI(path).query
+      return {} unless query
+      URI.decode_www_form(query).to_h
+    end
+
+    def http_response(body)
+      "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\nContent-Length: #{body.bytesize}\r\nConnection: close\r\n\r\n#{body}"
+    end
+
+    def exchange_code(auth_code, code_verifier)
+      host = ENV.fetch("FLARE_HOST", DEFAULT_HOST)
+      uri = URI("#{host}/api/cli/exchange")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/x-www-form-urlencoded"
+      request.set_form_data(code: auth_code, code_verifier: code_verifier)
+
+      response = http.request(request)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        $stderr.puts "Failed to exchange code for token: #{response.code} #{response.message}"
+        $stderr.puts response.body if response.body
+        exit 1
+      end
+
+      data = JSON.parse(response.body)
+      token = data["token"]
+
+      if token.nil? || token.empty?
+        $stderr.puts "No token received from server."
+        exit 1
+      end
+
+      token
+    end
+
+    # --- Token storage ---
+
+    def save_token(token)
+      puts
+      puts "Where would you like to save the token?"
+      puts "  1. .env file"
+      puts "  2. Rails credentials"
+      puts "  3. Print token"
+      print "Choose (1/2/3): "
+
+      choice = $stdin.gets&.strip
+
+      case choice
+      when "1"
+        @saved_to_dotenv = true
+        save_to_dotenv(token)
+      when "2"
+        print_credentials_instructions(token)
+      when "3"
+        print_token(token)
+      else
+        puts "Invalid choice."
+        save_token(token)
+      end
+    end
+
+    def save_to_dotenv(token)
+      env_path = File.join(Dir.pwd, ".env")
+
+      if File.exist?(env_path)
+        contents = File.read(env_path)
+        if contents.match?(/^FLARE_KEY=/)
+          contents.gsub!(/^FLARE_KEY=.*$/, "FLARE_KEY=#{token}")
+        else
+          contents = contents.chomp + "\nFLARE_KEY=#{token}\n"
+        end
+        File.write(env_path, contents)
+        puts "  Token saved to .env"
+      else
+        print "  .env file not found. Create it? (y/n): "
+        answer = $stdin.gets&.strip&.downcase
+        if answer == "y" || answer == "yes"
+          File.write(env_path, "FLARE_KEY=#{token}\n")
+          puts "  Created .env with FLARE_KEY"
+        else
+          print_dotenv_instructions(token)
+        end
+      end
+    end
+
+    def print_dotenv_instructions(token)
+      puts
+      puts "Add the following to your .env file:"
+      puts
+      puts "  FLARE_KEY=#{token}"
+      puts
+      puts "Make sure .env is loaded in your app, for example with the dotenv gem:"
+      puts
+      puts "  # Gemfile"
+      puts "  gem \"dotenv-rails\", groups: [:development, :test]"
+    end
+
+    def print_credentials_instructions(token)
+      puts
+      puts "Add the following to your Rails credentials:"
+      puts
+      puts "  bin/rails credentials:edit"
+      puts
+      puts "  flare:"
+      puts "    key: #{token}"
+      puts
+      puts "Or for a specific environment:"
+      puts
+      puts "  bin/rails credentials:edit --environment production"
+      puts
+      puts "  flare:"
+      puts "    key: #{token}"
+      puts
+    end
+
+    def print_token(token)
+      puts
+      puts "  FLARE_KEY=#{token}"
+    end
+
+    # --- Project setup ---
+
+    def create_initializer
+      path = File.join(Dir.pwd, "config/initializers/flare.rb")
+      existed = File.exist?(path)
+
+      if existed && !@force
+        puts "#{checkmark} config/initializers/flare.rb already exists"
+        puts "  Run with --force to overwrite."
+        return
+      end
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, INITIALIZER_CONTENT)
+
+      if existed
+        puts "#{checkmark} Overwrote config/initializers/flare.rb"
+      else
+        puts "#{checkmark} Created config/initializers/flare.rb"
+      end
+    end
+
+    def add_gitignore_entries
+      gitignore_path = File.join(Dir.pwd, ".gitignore")
+      return unless File.exist?(gitignore_path)
+
+      contents = File.read(gitignore_path)
+      entries_to_add = []
+
+      entries_to_add << ".env" if @saved_to_dotenv && !contents.match?(/^\.env$/)
+      entries_to_add << "flare.sqlite3*" unless contents.include?("flare.sqlite3*")
+
+      return if entries_to_add.empty?
+
+      File.open(gitignore_path, "a") do |f|
+        f.puts "" unless contents.end_with?("\n")
+        entries_to_add.each { |entry| f.puts entry }
+      end
+
+      puts "#{checkmark} Added #{entries_to_add.join(", ")} to .gitignore"
+    end
+
+    # --- Browser ---
+
+    def open_browser(url)
+      case RUBY_PLATFORM
+      when /darwin/ then system("open", url)
+      when /linux/ then system("xdg-open", url)
+      when /mingw|mswin/ then system("start", url)
+      end
+    end
+
+    def success_page
+      page_shell("Authorized!", "You can close this window.")
+    end
+
+    def error_page(message)
+      escaped = message.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
+      page_shell("Error", escaped)
+    end
+
+    def page_shell(title, subtitle)
+      <<~HTML
+        <!DOCTYPE html>
+        <html>
+        <head><title>Flare</title></head>
+        <body style="font-family: system-ui, -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background-color: #f5f3ef;">
+          <div style="text-align: center; background: #fff; border-radius: 16px; padding: 48px 56px; box-shadow: 0 1px 3px rgba(0,0,0,0.04), 0 4px 12px rgba(0,0,0,0.04);">
+            <h1 style="color: #3d3529; font-size: 28px; font-weight: 700; margin: 0 0 8px;">#{title}</h1>
+            <p style="color: #8a8078; font-size: 15px; margin: 0;">#{subtitle}</p>
+          </div>
+        </body>
+        </html>
+      HTML
+    end
+  end
+end

data/lib/flare/cli/status_command.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "output"
+require_relative "../version"
+
+module Flare
+  class StatusCommand
+    include CLI::Output
+
+    def run
+      puts bold("Flare v#{VERSION}")
+      puts
+
+      puts bold("Environment")
+      puts "  RAILS_ENV:    #{ENV.fetch("RAILS_ENV", dim("not set"))}"
+      puts "  FLARE_KEY:  #{key_status}"
+      puts "  FLARE_URL:  #{ENV.fetch("FLARE_URL", dim("https://flare.am (default)"))}"
+      puts
+
+      puts bold("Files")
+      puts "  Initializer:  #{file_status("config/initializers/flare.rb")}"
+      puts "  .env:         #{file_status(".env")}"
+      puts "  .gitignore:   #{file_status(".gitignore")}"
+      puts "  Database:     #{file_status("db/flare.sqlite3")}"
+    end
+
+    private
+
+    def key_status
+      if ENV["FLARE_KEY"] && !ENV["FLARE_KEY"].empty?
+        green("set via ENV")
+      else
+        env_path = File.join(Dir.pwd, ".env")
+        if File.exist?(env_path) && File.read(env_path).match?(/^FLARE_KEY=.+/)
+          green("set in .env")
+        else
+          red("not configured")
+        end
+      end
+    end
+
+    def file_status(relative_path)
+      path = File.join(Dir.pwd, relative_path)
+      File.exist?(path) ? green("exists") : dim("not found")
+    end
+  end
+end

data/lib/flare/cli.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "version"
+
+module Flare
+  module CLI
+    COMMANDS = {
+      "setup" => "Authenticate and configure Flare for this project",
+      "doctor" => "Check your Flare setup for issues",
+      "status" => "Show current Flare configuration",
+      "version" => "Print the Flare version",
+      "help" => "Show this help message",
+    }.freeze
+
+    def self.start(argv)
+      command = argv.first
+
+      case command
+      when "setup"
+        require_relative "cli/setup_command"
+        force = argv.include?("--force")
+        SetupCommand.new(force: force).run
+      when "doctor"
+        require_relative "cli/doctor_command"
+        DoctorCommand.new.run
+      when "status"
+        require_relative "cli/status_command"
+        StatusCommand.new.run
+      when "version", "-v", "--version"
+        puts "flare #{Flare::VERSION}"
+      when "help", nil, "-h", "--help"
+        print_help
+      else
+        $stderr.puts "Unknown command: #{command}"
+        $stderr.puts
+        print_help
+        exit 1
+      end
+    end
+
+    def self.print_help
+      puts "Usage: flare <command>"
+      puts
+      puts "Commands:"
+      COMMANDS.each do |name, description|
+        puts "  %-12s %s" % [name, description]
+      end
+    end
+  end
+end

data/lib/flare/configuration.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "http_metrics_config"
+
+module Flare
+  class Configuration
+    attr_accessor :enabled
+    attr_accessor :retention_hours
+    attr_accessor :max_spans
+    attr_accessor :ignore_request
+    attr_writer :database_path
+
+    # Spans: detailed trace data stored in SQLite (default: development only)
+    # Metrics: aggregated counters in memory, flushed periodically (default: production only)
+    attr_accessor :spans_enabled
+    attr_accessor :metrics_enabled
+    attr_accessor :metrics_flush_interval # seconds between flushes (default: 60)
+
+    # Metrics HTTP submission settings
+    attr_accessor :url        # URL of the Flare metrics service
+    attr_accessor :key        # API key for authentication
+    attr_accessor :metrics_timeout     # HTTP timeout in seconds (default: 5)
+    attr_accessor :metrics_gzip        # Whether to gzip payloads (default: true)
+
+    # Default patterns to auto-subscribe to for custom instrumentation
+    # Use "app." prefix in your ActiveSupport::Notifications.instrument calls
+    DEFAULT_SUBSCRIBE_PATTERNS = %w[app.].freeze
+
+    attr_accessor :subscribe_patterns
+
+    # HTTP metrics path tracking configuration.
+    # Controls which outgoing HTTP paths are tracked with detail vs collapsed to "*".
+    attr_reader :http_metrics_config
+
+    # Enable debug logging to see what Flare is doing.
+    # Set FLARE_DEBUG=1 or configure debug: true in your initializer.
+    attr_accessor :debug
+
+    def initialize
+      @enabled = true
+      @retention_hours = 24
+      @max_spans = 10_000
+      @database_path = nil
+      @ignore_request = ->(request) { false }
+      @subscribe_patterns = DEFAULT_SUBSCRIBE_PATTERNS.dup
+      @debug = ENV["FLARE_DEBUG"] == "1"
+      @http_metrics_config = HttpMetricsConfig::DEFAULT
+
+      # Environment-based defaults:
+      # - Development: spans ON (detailed debugging), metrics ON
+      # - Production: spans OFF (too expensive), metrics ON
+      # - Test: spans OFF, metrics OFF
+      @spans_enabled = rails_development?
+      @metrics_enabled = !rails_test?
+      @metrics_flush_interval = 60 # seconds
+
+      # Metrics HTTP submission defaults
+      @url = ENV.fetch("FLARE_URL", credentials_url || "https://flare.am")
+      @key = ENV["FLARE_KEY"]
+      @metrics_timeout = 5
+      @metrics_gzip = true
+    end
+
+    # Check if metrics can be submitted (endpoint and API key configured)
+    def metrics_submission_configured?
+      !@url.nil? && !@url.empty? &&
+        !@key.nil? && !@key.empty?
+    end
+
+    def database_path
+      @database_path || default_database_path
+    end
+
+    # Configure HTTP metrics path tracking.
+    #
+    #   config.http_metrics do |http|
+    #     http.host "api.stripe.com" do |h|
+    #       h.allow %r{/v1/customers}
+    #       h.allow %r{/v1/charges}
+    #       h.map %r{/v1/connect/[\w-]+/transfers}, "/v1/connect/:account/transfers"
+    #     end
+    #     http.host "api.github.com", :all
+    #   end
+    def http_metrics(&block)
+      # Clone defaults on first customization so user additions merge with built-in defaults
+      if @http_metrics_config.equal?(HttpMetricsConfig::DEFAULT)
+        @http_metrics_config = @http_metrics_config.dup
+      end
+      yield @http_metrics_config
+    end
+
+    private
+
+    def rails_development?
+      defined?(Rails) && Rails.env.development?
+    rescue StandardError
+      false # Default to false for safety - avoids enabling spans unexpectedly in production
+    end
+
+    def rails_test?
+      defined?(Rails) && Rails.env.test?
+    rescue StandardError
+      false
+    end
+
+    def credentials_url
+      return nil unless defined?(Rails) && Rails.application&.credentials
+      Rails.application.credentials.dig(:flare, :url)
+    rescue StandardError
+      nil
+    end
+
+    def default_database_path
+      if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        Rails.root.join("db", "flare.sqlite3").to_s
+      else
+        "flare.sqlite3"
+      end
+    end
+  end
+end

data/lib/flare/engine.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Flare
+  class Engine < ::Rails::Engine
+    isolate_namespace Flare
+
+    # Load secrets from Rails credentials if not already set via ENV
+    initializer "flare.defaults", before: :load_config_initializers do |app|
+      ENV["FLARE_KEY"] ||= app.credentials.dig(:flare, :key)
+    end
+
+    # Serve static assets from the engine's public directory
+    initializer "flare.static_assets" do |app|
+      app.middleware.use(
+        Rack::Static,
+        urls: ["/flare-assets"],
+        root: root.join("public"),
+        cascade: true
+      )
+    end
+
+    # Phase 1: Configure OTel SDK and instrumentations before middleware is
+    # built so Rack/ActionPack can insert their middleware.
+    initializer "flare.opentelemetry", before: :build_middleware_stack do
+      Flare.configure_opentelemetry
+    end
+
+    # Phase 2: Start the metrics flusher after all initializers have run
+    # so user config (metrics_enabled, flush_interval, etc.) is applied.
+    config.after_initialize do
+      Flare.start_metrics_flusher
+    end
+
+    # Auto-mount routes in development/test
+    initializer "flare.routes", before: :add_routing_paths do |app|
+      if Rails.env.development? || Rails.env.test?
+        app.routes.prepend do
+          mount Flare::Engine => "/flare"
+        end
+      end
+    end
+  end
+end