better_auth-telemetry 0.8.0

data/lib/better_auth/telemetry/detectors/database.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "rubygems"
+
+module BetterAuth
+  module Telemetry
+    module Detectors
+      # Database detector. Returns a small hash describing the database
+      # backend the host application is using (or `nil` when no signal
+      # is available).
+      #
+      # This is the Ruby-specific replacement for upstream's
+      # `detect-database.ts`, which only walked the Node `package.json`
+      # for known SQL/ORM packages. The Ruby port adds two earlier
+      # precedence rules (a caller-supplied context override and a
+      # `BetterAuth::Configuration` adapter check) so an application
+      # with a configured Better Auth adapter does not fall through to
+      # the generic gem fallback.
+      #
+      # ## Precedence chain (Requirement 10)
+      #
+      # 1. **Context override** — when the caller supplied a non-empty
+      #    `context.database` string, return it verbatim with
+      #    `version: nil`. This is the upstream `context.database`
+      #    seam.
+      # 2. **Configuration adapter** — when `options` is a
+      #    {BetterAuth::Configuration} (or a hash with a `:database`
+      #    key) and the value is a known adapter symbol
+      #    ({ADAPTER_SYMBOLS}) or a `BetterAuth::Adapters::*` instance
+      #    ({ADAPTER_CLASS_MAP}), return its short identifier with
+      #    `version: nil`.
+      # 3. **Gem fallback** — when neither rule above matches, walk
+      #    `Gem.loaded_specs` in {GEM_FALLBACKS} order and return the
+      #    first match as `{name: <gem_name>, version: <spec.version.to_s>}`.
+      # 4. Otherwise — `nil`.
+      #
+      # ## Failure handling
+      #
+      # The whole call is wrapped in `rescue StandardError; nil` so a
+      # surprise from any branch (an exotic `context` shape, a
+      # `Configuration` reader that raises on a partially constructed
+      # instance, a `Gem.loaded_specs` mutation, …) degrades to `nil`
+      # rather than escaping out of the init payload composition in
+      # {BetterAuth::Telemetry.create}.
+      #
+      # @example Context override
+      #   ctx = BetterAuth::Telemetry::NormalizedContext.from(database: "postgresql")
+      #   BetterAuth::Telemetry::Detectors::Database.call(nil, ctx)
+      #   # => {name: "postgresql", version: nil}
+      #
+      # @example Configuration symbol
+      #   config = BetterAuth::Configuration.new(secret: "...", database: :memory)
+      #   BetterAuth::Telemetry::Detectors::Database.call(config, nil)
+      #   # => {name: "memory", version: nil}
+      module Database
+        # Map from `BetterAuth::Adapters::*` class name to the short
+        # identifier reported in the init event. Class names are
+        # matched as strings so loading the telemetry gem does not
+        # autoload every adapter constant.
+        ADAPTER_CLASS_MAP = {
+          "BetterAuth::Adapters::Postgres" => "postgres",
+          "BetterAuth::Adapters::MySQL" => "mysql",
+          "BetterAuth::Adapters::SQLite" => "sqlite",
+          "BetterAuth::Adapters::MSSQL" => "mssql",
+          "BetterAuth::Adapters::Memory" => "memory"
+        }.freeze
+
+        # Map from a known {BetterAuth::Configuration#database} symbol
+        # value to the short identifier reported in the init event.
+        ADAPTER_SYMBOLS = {
+          postgres: "postgres",
+          mysql: "mysql",
+          sqlite: "sqlite",
+          mssql: "mssql",
+          memory: "memory"
+        }.freeze
+
+        # Gems to probe in `Gem.loaded_specs`, in upstream-spec order.
+        # First match wins.
+        GEM_FALLBACKS = %w[sequel pg mysql2 sqlite3 activerecord mongoid mongo rom-sql].freeze
+
+        module_function
+
+        # Resolve the database signal for the host application.
+        #
+        # @param options [BetterAuth::Configuration, Hash, nil] the
+        #   options passed to {BetterAuth::Telemetry.create}. May be a
+        #   {BetterAuth::Configuration} (production path), a raw hash
+        #   with a `:database` key, or `nil`.
+        # @param context [BetterAuth::Telemetry::NormalizedContext, Hash, nil]
+        #   the optional context. When it responds to `:database` (or
+        #   carries a `:database` / `"database"` key) and the value is
+        #   a non-empty string, that string short-circuits the chain.
+        # @return [Hash{Symbol => String, nil}, nil] either
+        #   `{name: String, version: String|nil}` or `nil` when nothing
+        #   matches.
+        def call(options, context)
+          override = context_override(context)
+          return {name: override, version: nil} if override
+
+          identifier = identify_from_options(options)
+          return {name: identifier, version: nil} if identifier
+
+          detect_from_gems
+        rescue
+          nil
+        end
+
+        # Read `database` from a {NormalizedContext}-like or hash-like
+        # context. Returns the raw string when present and non-empty,
+        # otherwise `nil`. Non-string values (e.g. a symbol set
+        # accidentally) are ignored to keep the wire shape stable.
+        #
+        # @param context [#database, Hash, nil]
+        # @return [String, nil]
+        def context_override(context)
+          return nil if context.nil?
+
+          value =
+            if context.respond_to?(:database)
+              context.database
+            elsif context.respond_to?(:[])
+              context[:database] || context["database"]
+            end
+
+          return nil unless value.is_a?(String)
+          return nil if value.empty?
+
+          value
+        end
+
+        # Translate the configuration's `database` value into a short
+        # identifier when it matches a known adapter symbol or a known
+        # `BetterAuth::Adapters::*` class.
+        #
+        # @param options [BetterAuth::Configuration, Hash, nil]
+        # @return [String, nil]
+        def identify_from_options(options)
+          database = configuration_database(options)
+          return nil if database.nil?
+
+          identify_adapter(database)
+        end
+
+        # Read `database` from a {BetterAuth::Configuration} or a raw
+        # hash. Returns `nil` for any other input shape.
+        #
+        # @param options [BetterAuth::Configuration, Hash, nil]
+        # @return [Object, nil]
+        def configuration_database(options)
+          return nil if options.nil?
+
+          if defined?(::BetterAuth::Configuration) && options.is_a?(::BetterAuth::Configuration)
+            return options.database
+          end
+
+          return options[:database] || options["database"] if options.is_a?(Hash)
+
+          nil
+        end
+
+        # Map a known adapter symbol or a `BetterAuth::Adapters::*`
+        # instance to its short identifier. Returns `nil` when the
+        # value is neither a known symbol nor a known adapter class.
+        #
+        # @param value [Symbol, BetterAuth::Adapters::Base, Object]
+        # @return [String, nil]
+        def identify_adapter(value)
+          if value.is_a?(Symbol)
+            return ADAPTER_SYMBOLS[value]
+          end
+
+          ADAPTER_CLASS_MAP[value.class.name]
+        end
+
+        # Walk {GEM_FALLBACKS} in order and return the first
+        # `Gem.loaded_specs` match as `{name:, version:}`. Returns
+        # `nil` when no listed gem is loaded.
+        #
+        # @return [Hash{Symbol => String}, nil]
+        def detect_from_gems
+          GEM_FALLBACKS.each do |name|
+            spec = ::Gem.loaded_specs[name]
+            next if spec.nil?
+
+            version = spec.respond_to?(:version) ? spec.version : nil
+            return {name: name, version: version&.to_s}
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/telemetry/detectors/environment.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Telemetry
+    module Detectors
+      # Environment detector. Classifies the current process as
+      # `"production"`, `"ci"`, `"test"`, or `"development"`, mirroring
+      # the upstream `detect-runtime.ts:detectEnvironment` short-circuit
+      # chain.
+      #
+      # Precedence (top wins):
+      #
+      #   1. `"production"` — when any of `RACK_ENV`, `RAILS_ENV`,
+      #      `APP_ENV` equals the literal string `"production"`.
+      #   2. `"ci"` — when any of the documented CI marker variables
+      #      ({CI_VARS}) is set to a non-empty value that is not the
+      #      case-insensitive string `"false"`.
+      #   3. `"test"` — when any of `RACK_ENV`, `RAILS_ENV`, `APP_ENV`
+      #      equals the literal string `"test"`.
+      #   4. `"development"` — fallback when no rule above matches.
+      #
+      # The CI marker check intentionally skips the literal string
+      # `"false"` (case-insensitive) so a host that exports
+      # `CI=false` (a common pattern in non-CI shells where CI tooling
+      # has been opted out) is not misclassified. Empty values are also
+      # treated as unset.
+      #
+      # @example
+      #   BetterAuth::Telemetry::Detectors::Environment.call
+      #   # => "development"
+      module Environment
+        # CI marker variables, in the upstream-defined order. Any
+        # non-empty / non-`"false"` value flips the classifier to
+        # `"ci"`.
+        CI_VARS = %w[
+          CI
+          BUILD_ID
+          BUILD_NUMBER
+          CI_APP_ID
+          CI_BUILD_ID
+          CI_BUILD_NUMBER
+          CI_NAME
+          CONTINUOUS_INTEGRATION
+          RUN_ID
+        ].freeze
+
+        # Test/production env variable names that get inspected for the
+        # literal `"production"` and `"test"` strings.
+        TEST_VARS = %w[RACK_ENV RAILS_ENV APP_ENV].freeze
+
+        module_function
+
+        # @return [String] one of `"production"`, `"ci"`, `"test"`, or
+        #   `"development"`.
+        def call
+          return "production" if any_env_eq?(TEST_VARS, "production")
+          return "ci" if ci?
+          return "test" if any_env_eq?(TEST_VARS, "test")
+
+          "development"
+        end
+
+        # @return [Boolean] true when at least one CI marker variable
+        #   has a non-empty value that is not (case-insensitive)
+        #   `"false"`.
+        def ci?
+          CI_VARS.any? do |key|
+            value = ENV[key]
+            next false if value.nil? || value.empty?
+            next false if value.casecmp("false").zero?
+
+            true
+          end
+        end
+
+        # @param keys [Array<String>] env var names to inspect.
+        # @param value [String] expected exact value.
+        # @return [Boolean] true when at least one of the named vars
+        #   equals `value`.
+        def any_env_eq?(keys, value)
+          keys.any? { |k| ENV[k] == value }
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/telemetry/detectors/framework.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "rubygems"
+
+module BetterAuth
+  module Telemetry
+    module Detectors
+      # Framework detector. Returns a small hash describing the Ruby
+      # web framework hosting the application (or `nil` when no
+      # supported framework gem is loaded).
+      #
+      # This is the Ruby-specific replacement for upstream's
+      # `detect-framework.ts`, which walked the Node `package.json`
+      # for known JavaScript frameworks. The Ruby port instead probes
+      # `Gem.loaded_specs` for the canonical Ruby web framework gems
+      # in declaration order; the first hit wins.
+      #
+      # ## Probe order (Requirement 11.1)
+      #
+      # 1. `rails`
+      # 2. `sinatra`
+      # 3. `hanami`
+      # 4. `hanami-router`
+      # 5. `roda`
+      # 6. `grape`
+      # 7. `rack`
+      #
+      # `rack` is intentionally last so a Rails or Sinatra app does
+      # not get reported as a "rack" app just because Rack is a
+      # transitive dependency.
+      #
+      # ## Failure handling
+      #
+      # The whole call is wrapped in `rescue StandardError; nil` so a
+      # surprise from `Gem.loaded_specs` (e.g. a mutated registry, a
+      # `respond_to?(:version)` shim that raises) degrades to `nil`
+      # rather than escaping out of the init payload composition in
+      # {BetterAuth::Telemetry.create}.
+      #
+      # Node-only frameworks (`next`, `nuxt`, `astro`, `sveltekit`,
+      # `solid-start`, `tanstack-start`, `hono`, `express`, `elysia`,
+      # `expo`) are intentionally not probed (Requirement 11.4).
+      #
+      # @example Rails app
+      #   BetterAuth::Telemetry::Detectors::Framework.call
+      #   # => {name: "rails", version: "7.1.3"}
+      #
+      # @example No supported framework loaded
+      #   BetterAuth::Telemetry::Detectors::Framework.call
+      #   # => nil
+      module Framework
+        # Gems to probe in `Gem.loaded_specs`, in upstream/spec order.
+        # First match wins.
+        GEMS = %w[rails sinatra hanami hanami-router roda grape rack].freeze
+
+        module_function
+
+        # Resolve the framework signal for the host application by
+        # walking {GEMS} in order against `Gem.loaded_specs`.
+        #
+        # @return [Hash{Symbol => String}, nil] either
+        #   `{name: String, version: String}` for the first matching
+        #   gem, or `nil` when none of the supported framework gems
+        #   are loaded.
+        def call
+          GEMS.each do |name|
+            spec = ::Gem.loaded_specs[name]
+            next if spec.nil?
+
+            version = spec.respond_to?(:version) ? spec.version : nil
+            return {name: name, version: version&.to_s}
+          end
+          nil
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/telemetry/detectors/project_info.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Telemetry
+    module Detectors
+      # ProjectInfo detector. Returns a small hash describing the
+      # project's "package manager" — for the Ruby port, this is
+      # always Bundler (or `nil` when Bundler is not available).
+      #
+      # This is the Ruby-specific replacement for upstream's
+      # `detect-project-info.ts`, which parsed the
+      # `npm_config_user_agent` env var to determine the npm/yarn/pnpm
+      # toolchain. There is no equivalent Ruby env var; Bundler is the
+      # closest semantic match.
+      #
+      # ## Detection rule (Requirements 12.1 / 12.2)
+      #
+      # 1. If `Bundler` is `defined?` AND `Bundler.default_gemfile`
+      #    succeeds (the Gemfile is locatable), return
+      #    `{name: "bundler", version: ::Bundler::VERSION}`.
+      # 2. Otherwise return `nil`.
+      #
+      # ## Failure handling
+      #
+      # The whole call is wrapped in `rescue StandardError; nil` so any
+      # surprise from probing Bundler (e.g. a stubbed/partially-loaded
+      # Bundler module) degrades to `nil` rather than escaping out of
+      # the init payload composition in {BetterAuth::Telemetry.create}.
+      #
+      # No `npm_config_user_agent` or other Node package-manager env
+      # var is read (Requirement 12.3); this Ruby-specific deviation
+      # is intentional.
+      #
+      # @example Inside a Bundler-managed app
+      #   BetterAuth::Telemetry::Detectors::ProjectInfo.call
+      #   # => {name: "bundler", version: "2.5.3"}
+      #
+      # @example Bundler not loaded
+      #   BetterAuth::Telemetry::Detectors::ProjectInfo.call
+      #   # => nil
+      module ProjectInfo
+        module_function
+
+        # Resolve the project-info signal for the host application.
+        #
+        # @return [Hash{Symbol => String}, nil] either
+        #   `{name: "bundler", version: <Bundler::VERSION>}` when
+        #   Bundler is loaded and a Gemfile is locatable, otherwise
+        #   `nil`.
+        def call
+          return nil unless bundler_loaded?
+          return nil unless default_gemfile_locatable?
+
+          {name: "bundler", version: ::Bundler::VERSION}
+        rescue
+          nil
+        end
+
+        # Whether the `Bundler` constant is defined in the current
+        # process. Extracted as a stub seam so tests can simulate the
+        # Bundler-absent case without actually unloading Bundler.
+        #
+        # @return [Boolean]
+        def bundler_loaded?
+          defined?(::Bundler) ? true : false
+        end
+
+        # Whether `Bundler.default_gemfile` resolves successfully.
+        # Bundler raises `Bundler::GemfileNotFound` (a `StandardError`
+        # subclass) when no Gemfile is locatable, so we treat any
+        # raise as "not locatable" rather than letting it escape.
+        #
+        # @return [Boolean]
+        def default_gemfile_locatable?
+          return false unless ::Bundler.respond_to?(:default_gemfile)
+
+          !::Bundler.default_gemfile.nil?
+        rescue
+          false
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/telemetry/detectors/runtime.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Telemetry
+    module Detectors
+      # Runtime detector. Returns a small hash describing the Ruby
+      # interpreter currently executing the host application.
+      #
+      # This is the Ruby-specific replacement for upstream's
+      # `detect-runtime.ts`, which classified Node, Deno, Bun, Cloudflare
+      # Workers, and other JavaScript runtimes. The Ruby port is
+      # server-only, so all of those branches collapse into a single
+      # `"ruby"` case. The `:engine` field preserves enough information
+      # for telemetry consumers to distinguish MRI, JRuby, TruffleRuby,
+      # etc.
+      #
+      # The whole detector is wrapped in `rescue StandardError` so a
+      # surprise from `RUBY_VERSION`/`RUBY_ENGINE` (very unlikely, but
+      # possible under exotic patched interpreters) cannot bubble out
+      # of the init payload composition in
+      # {BetterAuth::Telemetry.create}.
+      #
+      # @example
+      #   BetterAuth::Telemetry::Detectors::Runtime.call
+      #   # => {name: "ruby", version: "3.3.0", engine: "ruby"}
+      module Runtime
+        module_function
+
+        # @return [Hash{Symbol => String, nil}] hash with `:name`,
+        #   `:version`, and `:engine` keys. `:name` is always `"ruby"`.
+        #   `:version` is `RUBY_VERSION`. `:engine` is `RUBY_ENGINE`
+        #   when defined, otherwise the literal string `"ruby"`.
+        def call
+          {
+            name: "ruby",
+            version: RUBY_VERSION,
+            engine: defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby"
+          }
+        rescue
+          {name: "ruby", version: nil, engine: nil}
+        end
+      end
+    end
+  end
+end