brainzlab 0.1.0

data/lib/brainzlab/reflex/provisioner.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "fileutils"
+
+module BrainzLab
+  module Reflex
+    class Provisioner
+      CACHE_DIR = ENV.fetch("BRAINZLAB_CACHE_DIR") { File.join(Dir.home, ".brainzlab") }
+
+      def initialize(config)
+        @config = config
+      end
+
+      def ensure_project!
+        return unless should_provision?
+
+        # Try cached credentials first
+        if (cached = load_cached_credentials)
+          apply_credentials(cached)
+          return cached
+        end
+
+        # Provision new project
+        project = provision_project
+        return unless project
+
+        # Cache and apply credentials
+        cache_credentials(project)
+        apply_credentials(project)
+
+        project
+      end
+
+      private
+
+      def should_provision?
+        return false unless @config.reflex_auto_provision
+        return false unless @config.app_name.to_s.strip.length > 0
+        # Only skip if reflex_api_key is already set (not secret_key, which may be for Recall)
+        return false if @config.reflex_api_key.to_s.strip.length > 0
+        return false unless @config.reflex_master_key.to_s.strip.length > 0
+
+        true
+      end
+
+      def provision_project
+        uri = URI.parse("#{@config.reflex_url}/api/v1/projects/provision")
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["X-Master-Key"] = @config.reflex_master_key
+        request["User-Agent"] = "brainzlab-sdk-ruby/#{BrainzLab::VERSION}"
+        request.body = JSON.generate({ name: @config.app_name })
+
+        response = execute(uri, request)
+        return nil unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body, symbolize_names: true)
+      rescue StandardError => e
+        log_error("Failed to provision Reflex project: #{e.message}")
+        nil
+      end
+
+      def load_cached_credentials
+        path = cache_file_path
+        return nil unless File.exist?(path)
+
+        data = JSON.parse(File.read(path), symbolize_names: true)
+
+        # Validate cached data has required keys
+        return nil unless data[:api_key]
+
+        data
+      rescue StandardError => e
+        log_error("Failed to load cached Reflex credentials: #{e.message}")
+        nil
+      end
+
+      def cache_credentials(project)
+        FileUtils.mkdir_p(CACHE_DIR)
+        File.write(cache_file_path, JSON.generate(project))
+      rescue StandardError => e
+        log_error("Failed to cache Reflex credentials: #{e.message}")
+      end
+
+      def cache_file_path
+        File.join(CACHE_DIR, "#{@config.app_name}.reflex.json")
+      end
+
+      def apply_credentials(project)
+        # Use reflex_api_key for Reflex if we have a separate key
+        # Otherwise fall back to shared secret_key
+        @config.reflex_api_key = project[:api_key]
+
+        # Also set service name from app_name if not already set
+        @config.service ||= @config.app_name
+      end
+
+      def execute(uri, request)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 10
+        http.request(request)
+      end
+
+      def log_error(message)
+        return unless @config.logger
+
+        @config.logger.error("[BrainzLab::Reflex] #{message}")
+      end
+    end
+  end
+end

data/lib/brainzlab/reflex.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require_relative "reflex/client"
+require_relative "reflex/breadcrumbs"
+require_relative "reflex/provisioner"
+
+module BrainzLab
+  module Reflex
+    FILTERED_PARAMS = %w[password password_confirmation token api_key secret credit_card cvv ssn].freeze
+
+    class << self
+      def capture(exception, **context)
+        return unless enabled?
+        return if capture_disabled?
+        return if excluded?(exception)
+        return if sampled_out?
+
+        # Auto-provision project on first capture if app_name is configured
+        ensure_provisioned!
+
+        return unless BrainzLab.configuration.reflex_valid?
+
+        payload = build_payload(exception, context)
+        payload = run_before_send(payload, exception)
+        return if payload.nil?
+
+        client.send_error(payload)
+      end
+
+      def capture_message(message, level: :error, **context)
+        return unless enabled?
+        return if capture_disabled?
+        return if sampled_out?
+
+        # Auto-provision project on first capture if app_name is configured
+        ensure_provisioned!
+
+        return unless BrainzLab.configuration.reflex_valid?
+
+        payload = build_message_payload(message, level, context)
+        payload = run_before_send(payload, nil)
+        return if payload.nil?
+
+        client.send_error(payload)
+      end
+
+      def ensure_provisioned!
+        return if @provisioned
+
+        @provisioned = true
+        provisioner.ensure_project!
+      end
+
+      def provisioner
+        @provisioner ||= Provisioner.new(BrainzLab.configuration)
+      end
+
+      # Temporarily disable capture within a block
+      def without_capture
+        previous = Thread.current[:brainzlab_capture_disabled]
+        Thread.current[:brainzlab_capture_disabled] = true
+        yield
+      ensure
+        Thread.current[:brainzlab_capture_disabled] = previous
+      end
+
+      def client
+        @client ||= Client.new(BrainzLab.configuration)
+      end
+
+      def reset!
+        @client = nil
+        @provisioner = nil
+        @provisioned = false
+      end
+
+      private
+
+      def enabled?
+        BrainzLab.configuration.reflex_enabled
+      end
+
+      def capture_disabled?
+        Thread.current[:brainzlab_capture_disabled] == true
+      end
+
+      def excluded?(exception)
+        config = BrainzLab.configuration
+        config.reflex_excluded_exceptions.any? do |excluded|
+          case excluded
+          when String
+            exception.class.name == excluded || exception.class.to_s == excluded
+          when Class
+            exception.is_a?(excluded)
+          when Regexp
+            exception.class.name =~ excluded
+          else
+            false
+          end
+        end
+      end
+
+      def sampled_out?
+        rate = BrainzLab.configuration.reflex_sample_rate
+        return false if rate.nil? || rate >= 1.0
+
+        rand > rate
+      end
+
+      def run_before_send(payload, exception)
+        hook = BrainzLab.configuration.reflex_before_send
+        return payload unless hook
+
+        hook.call(payload, exception)
+      end
+
+      def build_payload(exception, context)
+        config = BrainzLab.configuration
+        ctx = Context.current
+
+        payload = {
+          timestamp: Time.now.utc.iso8601(3),
+          error_class: exception.class.name,
+          message: exception.message,
+          backtrace: format_backtrace(exception.backtrace || []),
+
+          # Environment
+          environment: config.environment,
+          commit: config.commit,
+          branch: config.branch,
+          server_name: config.host,
+
+          # Request context
+          request_id: ctx.request_id
+        }
+
+        # Add request info if available
+        add_request_info(payload, ctx)
+
+        # Add user info
+        add_user_info(payload, ctx, context)
+
+        # Add context, tags, extra
+        add_context_data(payload, ctx, context)
+
+        # Add breadcrumbs
+        payload[:breadcrumbs] = ctx.breadcrumbs.to_a
+
+        # Add fingerprint for error grouping
+        payload[:fingerprint] = compute_fingerprint(exception, context, ctx)
+
+        payload
+      end
+
+      def build_message_payload(message, level, context)
+        config = BrainzLab.configuration
+        ctx = Context.current
+
+        payload = {
+          timestamp: Time.now.utc.iso8601(3),
+          error_class: "Message",
+          message: message.to_s,
+          level: level.to_s,
+
+          # Environment
+          environment: config.environment,
+          commit: config.commit,
+          branch: config.branch,
+          server_name: config.host,
+
+          # Request context
+          request_id: ctx.request_id
+        }
+
+        # Add request info if available
+        add_request_info(payload, ctx)
+
+        # Add user info
+        add_user_info(payload, ctx, context)
+
+        # Add context, tags, extra
+        add_context_data(payload, ctx, context)
+
+        # Add breadcrumbs
+        payload[:breadcrumbs] = ctx.breadcrumbs.to_a
+
+        payload
+      end
+
+      def add_request_info(payload, ctx)
+        return unless ctx.request_path
+
+        payload[:request] = {
+          method: ctx.request_method,
+          path: ctx.request_path,
+          url: ctx.request_url,
+          params: filter_params(ctx.request_params),
+          headers: ctx.request_headers,
+          controller: ctx.controller,
+          action: ctx.action
+        }.compact
+      end
+
+      def add_user_info(payload, ctx, context)
+        user = context[:user] || ctx.user
+        return if user.nil? || user.empty?
+
+        payload[:user] = {
+          id: user[:id]&.to_s,
+          email: user[:email],
+          name: user[:name]
+        }.compact
+
+        # Store additional user data
+        extra_user = user.except(:id, :email, :name)
+        payload[:user_data] = extra_user unless extra_user.empty?
+      end
+
+      def add_context_data(payload, ctx, context)
+        # Tags from context + provided tags
+        tags = ctx.tags.merge(context[:tags] || {})
+        payload[:tags] = tags unless tags.empty?
+
+        # Extra data from context + provided extra
+        extra = ctx.data_hash.merge(context[:extra] || {})
+        extra = extra.except(:user, :tags) # Remove user and tags as they're separate
+        payload[:extra] = extra unless extra.empty?
+
+        # General context
+        payload[:context] = context.except(:user, :tags, :extra) unless context.except(:user, :tags, :extra).empty?
+      end
+
+      def format_backtrace(backtrace)
+        backtrace.first(30).map do |line|
+          if line.is_a?(String)
+            parse_backtrace_line(line)
+          else
+            line
+          end
+        end
+      end
+
+      def parse_backtrace_line(line)
+        # Parse "path/to/file.rb:42:in `method_name'"
+        if line =~ /\A(.+):(\d+):in `(.+)'\z/
+          {
+            file: $1,
+            line: $2.to_i,
+            function: $3,
+            in_app: in_app_frame?($1)
+          }
+        else
+          { raw: line }
+        end
+      end
+
+      def in_app_frame?(path)
+        return false if path.nil?
+        return false if path.include?("vendor/")
+        return false if path.include?("/gems/")
+
+        path.start_with?("app/", "lib/", "./app/", "./lib/")
+      end
+
+      def filter_params(params)
+        return nil if params.nil?
+
+        scrub_fields = BrainzLab.configuration.scrub_fields + FILTERED_PARAMS.map(&:to_sym)
+        deep_filter(params, scrub_fields)
+      end
+
+      def deep_filter(obj, fields)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), result|
+            if should_filter?(key, fields)
+              result[key] = "[FILTERED]"
+            else
+              result[key] = deep_filter(value, fields)
+            end
+          end
+        when Array
+          obj.map { |item| deep_filter(item, fields) }
+        else
+          obj
+        end
+      end
+
+      def should_filter?(key, fields)
+        key_str = key.to_s.downcase
+        fields.any? do |field|
+          case field
+          when Regexp
+            key_str.match?(field)
+          else
+            key_str == field.to_s.downcase
+          end
+        end
+      end
+
+      # Compute fingerprint for error grouping
+      # Returns an array of strings that uniquely identify the error type
+      def compute_fingerprint(exception, context, ctx)
+        custom_callback = BrainzLab.configuration.reflex_fingerprint
+
+        if custom_callback
+          # Call user's custom fingerprint callback
+          result = custom_callback.call(exception, context, ctx)
+
+          # Normalize the result
+          case result
+          when Array
+            result.map(&:to_s)
+          when String
+            [result]
+          when nil
+            # nil means use default fingerprinting
+            default_fingerprint(exception)
+          else
+            [result.to_s]
+          end
+        else
+          default_fingerprint(exception)
+        end
+      rescue StandardError => e
+        BrainzLab.debug_log("Custom fingerprint callback failed: #{e.message}")
+        default_fingerprint(exception)
+      end
+
+      # Default fingerprint: error class + first in-app frame (or first frame)
+      def default_fingerprint(exception)
+        parts = [exception.class.name]
+
+        if exception.backtrace&.any?
+          # Try to find the first in-app frame
+          in_app_frame = exception.backtrace.find { |line| in_app_line?(line) }
+          frame = in_app_frame || exception.backtrace.first
+
+          if frame
+            # Normalize the frame (remove line numbers for consistent grouping)
+            normalized = normalize_frame_for_fingerprint(frame)
+            parts << normalized if normalized
+          end
+        end
+
+        parts
+      end
+
+      def in_app_line?(line)
+        return false if line.nil?
+        return false if line.include?("vendor/")
+        return false if line.include?("/gems/")
+
+        line.start_with?("app/", "lib/", "./app/", "./lib/") ||
+          line.include?("/app/") ||
+          line.include?("/lib/")
+      end
+
+      def normalize_frame_for_fingerprint(frame)
+        return nil unless frame.is_a?(String)
+
+        # Extract file and method, normalize out line numbers
+        # "app/models/user.rb:42:in `save'" -> "app/models/user.rb:in `save'"
+        if frame =~ /\A(.+):\d+:in `(.+)'\z/
+          "#{$1}:in `#{$2}'"
+        elsif frame =~ /\A(.+):\d+\z/
+          $1
+        else
+          frame
+        end
+      end
+    end
+  end
+end

data/lib/brainzlab/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  VERSION = "0.1.0"
+end

data/lib/brainzlab-sdk.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "brainzlab"

data/lib/brainzlab.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "brainzlab/version"
+require_relative "brainzlab/configuration"
+require_relative "brainzlab/context"
+require_relative "brainzlab/recall"
+require_relative "brainzlab/reflex"
+require_relative "brainzlab/pulse"
+require_relative "brainzlab/instrumentation"
+
+module BrainzLab
+  class << self
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      Recall.reset!
+      Reflex.reset!
+      Pulse.reset!
+    end
+
+    # Context management
+    def set_user(id: nil, email: nil, name: nil, **extra)
+      Context.current.set_user(id: id, email: email, name: name, **extra)
+    end
+
+    def set_context(**data)
+      Context.current.set_context(**data)
+    end
+
+    def set_tags(**data)
+      Context.current.set_tags(**data)
+    end
+
+    def with_context(**data, &block)
+      Context.current.with_context(**data, &block)
+    end
+
+    def clear_context!
+      Context.clear!
+    end
+
+    # Breadcrumb helpers
+    def add_breadcrumb(message, category: "default", level: :info, data: nil)
+      Reflex.add_breadcrumb(message, category: category, level: level, data: data)
+    end
+
+    def clear_breadcrumbs!
+      Reflex.clear_breadcrumbs!
+    end
+
+    # Create a logger that can replace Rails.logger
+    # @param broadcast_to [Logger] Optional logger to also send logs to (e.g., original Rails.logger)
+    # @return [BrainzLab::Recall::Logger]
+    def logger(broadcast_to: nil)
+      Recall::Logger.new(nil, broadcast_to: broadcast_to)
+    end
+
+    # Debug logging helper
+    def debug_log(message)
+      configuration.debug_log(message)
+    end
+
+    # Check if debug mode is enabled
+    def debug?
+      configuration.debug?
+    end
+
+    # Health check - verifies connectivity to all enabled services
+    # @return [Hash] Status of each service
+    def health_check
+      results = { status: 'ok', services: {} }
+
+      # Check Recall
+      if configuration.recall_enabled
+        results[:services][:recall] = check_service_health(
+          url: configuration.recall_url,
+          name: 'Recall'
+        )
+      end
+
+      # Check Reflex
+      if configuration.reflex_enabled
+        results[:services][:reflex] = check_service_health(
+          url: configuration.reflex_url,
+          name: 'Reflex'
+        )
+      end
+
+      # Check Pulse
+      if configuration.pulse_enabled
+        results[:services][:pulse] = check_service_health(
+          url: configuration.pulse_url,
+          name: 'Pulse'
+        )
+      end
+
+      # Overall status
+      has_failure = results[:services].values.any? { |s| s[:status] == 'error' }
+      results[:status] = has_failure ? 'degraded' : 'ok'
+
+      results
+    end
+
+    private
+
+    def check_service_health(url:, name:)
+      require 'net/http'
+      require 'uri'
+
+      uri = URI.parse("#{url}/up")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = 5
+      http.read_timeout = 5
+
+      response = http.get(uri.request_uri)
+
+      if response.is_a?(Net::HTTPSuccess)
+        { status: 'ok', latency_ms: 0 }
+      else
+        { status: 'error', message: "HTTP #{response.code}" }
+      end
+    rescue StandardError => e
+      { status: 'error', message: e.message }
+    end
+  end
+end
+
+# Auto-load Rails integration if Rails is available
+if defined?(Rails::Railtie)
+  require_relative "brainzlab/rails/railtie"
+end

data/lib/generators/brainzlab/install/install_generator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Brainzlab
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a BrainzLab initializer for your Rails application"
+
+      class_option :key, type: :string, desc: "Your BrainzLab secret key"
+      class_option :replace_logger, type: :boolean, default: false, desc: "Replace Rails.logger with BrainzLab logger"
+
+      def copy_initializer
+        template "brainzlab.rb.tt", "config/initializers/brainzlab.rb"
+      end
+
+      def show_post_install_message
+        say ""
+        say "BrainzLab SDK installed successfully!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Set your environment variables:"
+        say "     BRAINZLAB_SECRET_KEY - Your API key from https://brainzlab.ai/dashboard"
+        say ""
+        say "     Or for auto-provisioning:"
+        say "     RECALL_MASTER_KEY - Master key for Recall auto-provisioning"
+        say "     REFLEX_MASTER_KEY - Master key for Reflex auto-provisioning"
+        say ""
+        say "  2. Start logging:"
+        say "     BrainzLab::Recall.info('Hello from BrainzLab!')"
+        say ""
+        say "  3. Capture errors (automatic with Rails, or manual):"
+        say "     BrainzLab::Reflex.capture(exception)"
+        say ""
+        if options[:replace_logger]
+          say "  Rails.logger is now connected to Recall!", :yellow
+        else
+          say "  To send all Rails logs to Recall, add to your initializer:"
+          say "     Rails.logger = BrainzLab.logger(broadcast_to: Rails.logger)"
+        end
+        say ""
+      end
+
+      private
+
+      def secret_key_value
+        if options[:key].present?
+          %("#{options[:key]}")
+        else
+          'ENV["BRAINZLAB_SECRET_KEY"]'
+        end
+      end
+
+      def app_name
+        Rails.application.class.module_parent_name.underscore rescue "my-app"
+      end
+    end
+  end
+end