better_auth-telemetry 0.8.0

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

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "etc"
+require "rbconfig"
+require "rubygems"
+require "timeout"
+
+module BetterAuth
+  module Telemetry
+    module Detectors
+      # System info detector. Returns a hash describing the host
+      # platform, container/WSL state, deployment vendor, and a few
+      # cheap host-level signals (cpu count, memory, isTTY).
+      #
+      # This is the Ruby-specific replacement for upstream's
+      # `detect-system-info.ts` (and the Node-specific block inside
+      # `node.ts`). The Ruby port collapses both upstream variants into
+      # a single server-side detector that uses `RbConfig`,
+      # `Gem::Platform.local`, `Etc`, `IO.popen`, and a few `File.exist?`
+      # / `File.read` probes against well-known paths.
+      #
+      # ## Ruby-specific deviations from upstream
+      #
+      # - `cpuModel` is always `nil`. There is no portable Ruby stdlib
+      #   API for the model string, and exposing a partial detection
+      #   (e.g. parsing `/proc/cpuinfo`) would only work on Linux.
+      # - `cpuSpeed` (an upstream key) is **omitted entirely** from the
+      #   returned hash, rather than emitted as `nil`. Including it
+      #   would invite consumers to assume it can ever be populated by
+      #   the Ruby implementation. The README documents this.
+      # - `memory` is read from `/proc/meminfo` on Linux and from
+      #   `sysctl -n hw.memsize` on macOS via {.read_sysctl_memsize}
+      #   under a 1s {Timeout.timeout}. On other platforms (and on
+      #   read failures) it is `nil`.
+      #
+      # ## Failure handling (Requirement 9.11)
+      #
+      # Every probe is invoked through {.safely}, which is just
+      # `yield rescue StandardError; nil`. A surprise from any single
+      # probe degrades that field to `nil` rather than escaping out of
+      # the init payload composition in
+      # {BetterAuth::Telemetry.create}.
+      #
+      # Each helper probe ({.detect_vendor}, {.platform}, {.release},
+      # {.architecture}, {.cpu_count}, {.total_memory_bytes}, {.wsl?},
+      # {.docker?}, {.tty?}) is exposed as a `module_function` so it
+      # can be stubbed with `Minitest::Mock#stub` in the
+      # corresponding test, exercising the per-field rescue path.
+      module SystemInfo
+        # Vendor table. The list and order mirror upstream's
+        # `getVendor` short-circuit chain in
+        # `upstream/better-auth/1.6.9/packages/telemetry/src/detectors/detect-system-info.ts`.
+        # First match wins; a missing match yields `nil`.
+        #
+        # Each entry is `[vendor_name, [marker_env_var, ...]]`. A
+        # vendor matches when any of its marker variables is set to a
+        # non-empty value.
+        VENDORS = [
+          ["cloudflare", %w[CF_PAGES CF_PAGES_URL CF_ACCOUNT_ID]],
+          ["vercel", %w[VERCEL VERCEL_URL VERCEL_ENV]],
+          ["netlify", %w[NETLIFY NETLIFY_URL]],
+          ["render", %w[RENDER RENDER_URL RENDER_INTERNAL_HOSTNAME RENDER_SERVICE_ID]],
+          ["aws", %w[AWS_LAMBDA_FUNCTION_NAME AWS_EXECUTION_ENV LAMBDA_TASK_ROOT]],
+          ["gcp", %w[GOOGLE_CLOUD_FUNCTION_NAME GOOGLE_CLOUD_PROJECT GCP_PROJECT K_SERVICE]],
+          ["azure", %w[AZURE_FUNCTION_NAME FUNCTIONS_WORKER_RUNTIME WEBSITE_INSTANCE_ID WEBSITE_SITE_NAME]],
+          ["deno-deploy", %w[DENO_DEPLOYMENT_ID DENO_REGION]],
+          ["fly-io", %w[FLY_APP_NAME FLY_REGION FLY_ALLOC_ID]],
+          ["railway", %w[RAILWAY_STATIC_URL RAILWAY_ENVIRONMENT_NAME]],
+          ["heroku", %w[DYNO HEROKU_APP_NAME]],
+          ["digitalocean", %w[DO_DEPLOYMENT_ID DO_APP_NAME DIGITALOCEAN]],
+          ["koyeb", %w[KOYEB KOYEB_DEPLOYMENT_ID KOYEB_APP_NAME]]
+        ].freeze
+
+        # Cap on the `sysctl` subprocess reading macOS `hw.memsize`. A
+        # well-behaved `sysctl` returns essentially instantly; the cap
+        # only exists so a hung subprocess cannot block init.
+        SYSCTL_TIMEOUT_SECONDS = 1
+
+        module_function
+
+        # Compose the system-info hash emitted as
+        # `payload[:systemInfo]` in the init event.
+        #
+        # @return [Hash{Symbol => Object, nil}] hash with keys
+        #   `:deploymentVendor`, `:systemPlatform`, `:systemRelease`,
+        #   `:systemArchitecture`, `:cpuCount`, `:cpuModel`, `:memory`,
+        #   `:isWSL`, `:isDocker`, `:isTTY`. Any individual field may
+        #   be `nil` when the underlying probe is unsupported on the
+        #   host or raises. The key `:cpuSpeed` is intentionally
+        #   absent.
+        def call
+          {
+            deploymentVendor: safely { detect_vendor },
+            systemPlatform: safely { platform },
+            systemRelease: safely { release },
+            systemArchitecture: safely { architecture },
+            cpuCount: safely { cpu_count },
+            cpuModel: nil,
+            memory: safely { total_memory_bytes },
+            isWSL: safely { wsl? },
+            isDocker: safely { docker? },
+            isTTY: safely { tty? }
+          }
+        end
+
+        # Run `block` and rescue any `StandardError` to `nil`. The
+        # whole detector composes its return hash by calling each
+        # probe through this helper, so a raising probe degrades only
+        # that field rather than aborting the entire detector.
+        #
+        # @yield the probe to run.
+        # @return [Object, nil] whatever the block returns, or `nil`
+        #   if the block raised a `StandardError`.
+        def safely
+          yield
+        rescue
+          nil
+        end
+
+        # Match the first vendor whose marker variables are present in
+        # `ENV`. Mirrors upstream's `getVendor` short-circuit chain.
+        #
+        # @return [String, nil] the vendor name (`"vercel"`,
+        #   `"cloudflare"`, …) or `nil` when no vendor matches.
+        def detect_vendor
+          VENDORS.each do |(name, keys)|
+            return name if keys.any? { |k| has_env_marker?(k) }
+          end
+          nil
+        end
+
+        # @return [Boolean] whether `ENV[key]` is set to a non-empty
+        #   string. Mirrors upstream's `Boolean(env[k])`.
+        def has_env_marker?(key)
+          value = ENV[key]
+          !value.nil? && !value.empty?
+        end
+
+        # Short platform identifier matching upstream `os.platform()`
+        # style.
+        #
+        # @return [String, nil] one of `"linux"`, `"darwin"`,
+        #   `"windows"`, `"freebsd"`, `"openbsd"`, `"netbsd"`,
+        #   `"sunos"`, `"aix"`. Falls back to
+        #   `Gem::Platform.local.os` (or the raw `host_os`) when the
+        #   `host_os` token does not match a known prefix.
+        def platform
+          host_os = RbConfig::CONFIG["host_os"].to_s.downcase
+          case host_os
+          when /linux/ then "linux"
+          when /darwin/ then "darwin"
+          when /mswin|mingw|cygwin/ then "windows"
+          when /freebsd/ then "freebsd"
+          when /openbsd/ then "openbsd"
+          when /netbsd/ then "netbsd"
+          when /sunos|solaris/ then "sunos"
+          when /aix/ then "aix"
+          else
+            (Gem::Platform.local.os if defined?(::Gem::Platform)) || host_os
+          end
+        end
+
+        # Operating-system release string. Prefers `Etc.uname[:release]`
+        # (e.g. `"5.15.0-92-generic"` on Linux, `"24.6.0"` on macOS).
+        # Falls back to the trailing version digits of
+        # `RbConfig::CONFIG["host_os"]` (e.g. `"darwin25"` → `"25"`)
+        # when `Etc.uname` is unavailable.
+        #
+        # @return [String, nil]
+        def release
+          if defined?(::Etc) && ::Etc.respond_to?(:uname)
+            value = ::Etc.uname[:release]
+            return value if value.is_a?(String) && !value.empty?
+          end
+          host_os = RbConfig::CONFIG["host_os"].to_s
+          tail = host_os[/\d.*\z/]
+          (tail.nil? || tail.empty?) ? nil : tail
+        end
+
+        # Short architecture identifier matching upstream `os.arch()`
+        # style.
+        #
+        # @return [String, nil] e.g. `"x64"`, `"arm64"`, `"ia32"`.
+        #   Falls back to `Gem::Platform.local.cpu` (or the raw
+        #   `host_cpu`) when the value does not match a known token.
+        def architecture
+          host_cpu = RbConfig::CONFIG["host_cpu"].to_s.downcase
+          case host_cpu
+          when "x86_64", "amd64", "x64" then "x64"
+          when "aarch64", "arm64" then "arm64"
+          when "i386", "i686", "x86" then "ia32"
+          when /ppc64/ then "ppc64"
+          when /ppc/ then "ppc"
+          when /arm/ then "arm"
+          else
+            (Gem::Platform.local.cpu if defined?(::Gem::Platform)) || host_cpu
+          end
+        end
+
+        # @return [Integer, nil] the value returned by
+        #   `Etc.nprocessors`, reported verbatim including `0`. The
+        #   outer `safely` wrapper in {.call} maps an `Etc.nprocessors`
+        #   raise to `nil`.
+        def cpu_count
+          ::Etc.nprocessors
+        end
+
+        # Total system memory in bytes when reachable on the host
+        # platform, otherwise `nil`.
+        #
+        # @return [Integer, nil]
+        def total_memory_bytes
+          case platform
+          when "linux"
+            read_meminfo_bytes
+          when "darwin"
+            read_sysctl_memsize
+          end
+        end
+
+        # Read `MemTotal` from `/proc/meminfo`. The field reports
+        # kilobytes; we multiply to bytes to match upstream's
+        # `os.totalmem()` units.
+        #
+        # @return [Integer, nil]
+        def read_meminfo_bytes
+          File.foreach("/proc/meminfo") do |line|
+            if (m = line.match(/\AMemTotal:\s+(\d+)\s+kB/i))
+              return m[1].to_i * 1024
+            end
+          end
+          nil
+        rescue
+          nil
+        end
+
+        # Run `sysctl -n hw.memsize` under a 1s timeout. The
+        # subprocess writes a single integer (bytes) to stdout.
+        #
+        # @return [Integer, nil]
+        def read_sysctl_memsize
+          output = Timeout.timeout(SYSCTL_TIMEOUT_SECONDS) do
+            IO.popen(["sysctl", "-n", "hw.memsize"], err: File::NULL, &:read)
+          end
+          return nil if output.nil? || output.strip.empty?
+          value = output.strip.to_i
+          (value > 0) ? value : nil
+        rescue
+          nil
+        end
+
+        # Detect Docker via well-known sentinels.
+        #
+        # @return [Boolean] `true` when `/.dockerenv` exists OR
+        #   `/proc/self/cgroup` exists and contains the literal
+        #   substring `"docker"`; `false` otherwise.
+        def docker?
+          return true if File.exist?("/.dockerenv")
+          if File.exist?("/proc/self/cgroup")
+            return true if File.read("/proc/self/cgroup").include?("docker")
+          end
+          false
+        rescue
+          false
+        end
+
+        # Detect WSL.
+        #
+        # `true` iff `RUBY_PLATFORM` indicates Linux AND either
+        # `Etc.uname[:release]` or `/proc/version` contains the
+        # case-insensitive substring `"microsoft"`, AND the host is
+        # not detected as inside a non-Docker container (the
+        # `/run/.containerenv` sentinel).
+        #
+        # @return [Boolean]
+        def wsl?
+          return false unless RUBY_PLATFORM.to_s.include?("linux")
+
+          return false unless microsoft_marker?
+          return false if non_docker_container?
+
+          true
+        rescue
+          false
+        end
+
+        # @return [Boolean] whether either `Etc.uname[:release]` or
+        #   `/proc/version` contains `"microsoft"` (case-insensitive).
+        def microsoft_marker?
+          if defined?(::Etc) && ::Etc.respond_to?(:uname)
+            release_str = ::Etc.uname[:release].to_s
+            return true if release_str.downcase.include?("microsoft")
+          end
+
+          if File.exist?("/proc/version")
+            return true if File.read("/proc/version").downcase.include?("microsoft")
+          end
+
+          false
+        rescue
+          false
+        end
+
+        # @return [Boolean] whether the host is detected as a non-Docker
+        #   container — `/run/.containerenv` is present AND
+        #   {.docker?} is `false`.
+        def non_docker_container?
+          File.exist?("/run/.containerenv") && !docker?
+        rescue
+          false
+        end
+
+        # @return [Boolean] `$stdout.tty?`.
+        def tty?
+          $stdout.tty?
+        end
+      end
+    end
+  end
+end

data/lib/better_auth/telemetry/env.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "better_auth/env"
+
+module BetterAuth
+  module Telemetry
+    # Telemetry-side wrapper around {BetterAuth::Env} that exposes the
+    # two helpers the rest of the telemetry pipeline depends on:
+    #
+    # - {.get} — read a `BETTER_AUTH_*` environment variable while
+    #   transparently honoring the `OPEN_AUTH_*` alias prefix.
+    # - {.truthy?} — classify a resolved env string as truthy using the
+    #   same rules upstream applies in
+    #   `packages/core/src/env/env-impl.ts:getBooleanEnvVar`.
+    #
+    # The wrapper is intentionally thin: {BetterAuth::Env.get} already
+    # implements the dual-prefix resolution, so {.get} just delegates.
+    # Wrapping it here gives the telemetry package a single, named seam
+    # the orchestrator code can reach for and the tests can drive against,
+    # without leaking the core env module into every detector.
+    #
+    # ## Truthy semantics
+    #
+    # An environment value is considered a `Truthy_Env_Value`
+    # (Requirement 3.6) when **all three** of these conditions hold for
+    # the resolved string:
+    #
+    # 1. it is not empty,
+    # 2. it is not the literal `"0"`, and
+    # 3. `value.casecmp("false") != 0` (i.e. not `"false"` / `"FALSE"`
+    #    / `"False"` / etc).
+    #
+    # Anything else — including `nil`, `""`, `"0"`, and any casing of
+    # `"false"` — is falsy. This mirrors the upstream behavior so the
+    # Ruby port classifies opt-in toggles identically to the Node port.
+    #
+    # The classifier accepts any input type: non-string values are
+    # coerced via `#to_s` before classification. That makes it safe to
+    # forward boolean defaults straight from option hashes
+    # (`Env.truthy?(options[:telemetry][:debug])`) without callers
+    # having to type-check first.
+    module Env
+      module_function
+
+      # Resolve the value of a telemetry environment variable.
+      #
+      # Accepts the canonical `BETTER_AUTH_*` name and delegates to
+      # {BetterAuth::Env.get}, which checks the `OPEN_AUTH_*` alias
+      # first and falls back to the canonical name. Returns `nil` when
+      # neither variant is set (or both are empty).
+      #
+      # @param name [String, Symbol] canonical `BETTER_AUTH_*`
+      #   environment variable name (e.g. `"BETTER_AUTH_TELEMETRY"`).
+      # @return [String, nil] the resolved value, or `nil` when absent.
+      def get(name)
+        ::BetterAuth::Env.get(name)
+      end
+
+      # Classify an environment value as truthy.
+      #
+      # @param value [Object, nil] typically a `String` returned from
+      #   {.get}, but any value is accepted; non-strings are coerced via
+      #   `#to_s`. `nil` coerces to `""` and is falsy.
+      # @return [Boolean] `true` when the resolved string is non-empty,
+      #   not `"0"`, and not (case-insensitively) `"false"`. `false`
+      #   otherwise.
+      def truthy?(value)
+        string = value.to_s
+        return false if string.empty?
+        return false if string == "0"
+        return false if string.casecmp("false") == 0
+
+        true
+      end
+    end
+  end
+end

data/lib/better_auth/telemetry/http_client.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "version"
+
+module BetterAuth
+  module Telemetry
+    # Synchronous JSON-over-HTTP delivery used by the telemetry publisher
+    # when an endpoint is configured and debug mode is off. Implemented on
+    # top of `Net::HTTP` so the gem ships with zero external HTTP runtime
+    # dependencies (Requirement 1.8).
+    #
+    # Every transport-level failure (DNS errors, refused connections, TLS
+    # errors, JSON encoding errors, malformed URLs, timeouts, non-2xx
+    # responses surfaced as exceptions) is rescued at the `StandardError`
+    # boundary and routed through the supplied logger at error level.
+    # Non-`StandardError` exceptions (`Interrupt`, `SystemExit`,
+    # `SignalException`, `NoMemoryError`) are intentionally allowed to
+    # propagate, matching the "fail closed on signals" convention used by
+    # the rest of the telemetry pipeline.
+    #
+    # The method always returns `nil`, regardless of success, failure, or
+    # response status. Callers MUST treat it strictly as fire-and-forget;
+    # the response body and status are intentionally not exposed because
+    # consumers should never make publish decisions based on transport
+    # outcomes (Requirements 5.3, 5.6, 5.8).
+    #
+    # ## Timeouts
+    #
+    # `open_timeout` and `read_timeout` are both bounded at 5 seconds so
+    # telemetry delivery can never block application initialization for
+    # an unbounded period (Requirement 5.8).
+    #
+    # ## Headers
+    #
+    # - `Content-Type: application/json`
+    # - `User-Agent: better_auth-telemetry/<VERSION>` where `<VERSION>` is
+    #   {BetterAuth::Telemetry::VERSION}.
+    #
+    # @example successful delivery
+    #   BetterAuth::Telemetry::HttpClient.post_json(
+    #     "https://telemetry.example.com/ingest",
+    #     { type: "init", payload: {} },
+    #     logger: logger_adapter
+    #   ) # => nil
+    #
+    # @example unreachable host
+    #   BetterAuth::Telemetry::HttpClient.post_json(
+    #     "http://127.0.0.1:1",
+    #     { type: "init", payload: {} },
+    #     logger: logger_adapter
+    #   ) # => nil; logger.error called once
+    module HttpClient
+      # Bounded `open_timeout` for `Net::HTTP.start`. See Requirement 5.8.
+      OPEN_TIMEOUT_SECONDS = 5
+
+      # Bounded `read_timeout` for `Net::HTTP.start`. See Requirement 5.8.
+      READ_TIMEOUT_SECONDS = 5
+
+      # Issue a synchronous JSON `POST` to `url`. Always returns `nil` and
+      # never raises a `StandardError`.
+      #
+      # @param url [String] the absolute endpoint URL. `https` is treated
+      #   as TLS-enabled (`use_ssl: true`).
+      # @param body [Hash, Array, Object] the payload, encoded via
+      #   `JSON.generate`.
+      # @param logger [#error] a logger-shaped object (typically
+      #   {BetterAuth::Telemetry::LoggerAdapter}) used to record
+      #   transport failures at error level.
+      # @return [nil]
+      def self.post_json(url, body, logger:)
+        uri = URI.parse(url)
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["User-Agent"] = "better_auth-telemetry/#{BetterAuth::Telemetry::VERSION}"
+        request.body = JSON.generate(body)
+
+        Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: OPEN_TIMEOUT_SECONDS,
+          read_timeout: READ_TIMEOUT_SECONDS
+        ) do |http|
+          http.request(request)
+        end
+
+        nil
+      rescue => e
+        logger.error("[better-auth.telemetry] http delivery failed: #{e.class}: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/better_auth/telemetry/logger_adapter.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "better_auth/logger"
+
+module BetterAuth
+  module Telemetry
+    # Thin wrapper that normalizes any logger-shaped object into the two-method
+    # surface the telemetry pipeline depends on: `#info(message)` and
+    # `#error(message)`. Every dispatch is wrapped in a `rescue StandardError`
+    # so a misbehaving logger can never propagate out of telemetry code paths
+    # (Requirements 5.5, 21.1, 21.2, 21.3).
+    #
+    # ## Per-dispatch selection rule
+    #
+    # On every `#info` / `#error` call, in order:
+    #
+    # 1. If the wrapped logger responds to the requested level
+    #    (`:info` or `:error`), call it.
+    # 2. Otherwise, if the wrapped logger responds to `:call`, invoke
+    #    `logger.call(level, message)`.
+    # 3. Otherwise, fall back to `Kernel.warn(message)`.
+    #
+    # Any `StandardError` raised by the chosen step is swallowed and the call
+    # returns `nil`. Non-`StandardError` exceptions (`Interrupt`,
+    # `SystemExit`, `SignalException`, `NoMemoryError`) are intentionally
+    # allowed to propagate.
+    #
+    # ## Construction
+    #
+    # Use {LoggerAdapter.from} to build an adapter from a host-supplied
+    # `options.logger`. When no logger is configured, the factory falls back
+    # to `BetterAuth::Logger.create` so callers always get a usable adapter
+    # that responds to `info` and `error`.
+    #
+    # @example wrap a Ruby stdlib `Logger`
+    #   adapter = BetterAuth::Telemetry::LoggerAdapter.from(Logger.new($stderr))
+    #   adapter.info("opted-in")
+    #
+    # @example wrap a callable logger
+    #   adapter = BetterAuth::Telemetry::LoggerAdapter.from(->(level, msg) { puts "[#{level}] #{msg}" })
+    #
+    # @example default fallback
+    #   adapter = BetterAuth::Telemetry::LoggerAdapter.from(nil)
+    #   adapter.error("boom") # routed through BetterAuth::Logger.create
+    class LoggerAdapter
+      # Build a {LoggerAdapter} from the host-supplied logger, falling back to
+      # the default {BetterAuth::Logger} when none is configured.
+      #
+      # Selection rules:
+      #
+      # - If `options_logger` is non-`nil` and responds to both `:info` and
+      #   `:error`, wrap it as-is.
+      # - Else if `options_logger` is non-`nil` and responds to `:call`, wrap
+      #   the callable.
+      # - Else fall back to `BetterAuth::Logger.create`.
+      #
+      # @param options_logger [Object, nil] the logger to wrap; may be a
+      #   `Logger`-shaped object, a callable (`#call(level, message)`), or
+      #   `nil`.
+      # @return [LoggerAdapter] a fresh adapter with `#info` and `#error`.
+      def self.from(options_logger)
+        return new(options_logger) if logger_shape?(options_logger)
+        return new(options_logger) if callable_shape?(options_logger)
+
+        new(::BetterAuth::Logger.create)
+      end
+
+      # @api private
+      def self.logger_shape?(logger)
+        !logger.nil? && logger.respond_to?(:info) && logger.respond_to?(:error)
+      end
+
+      # @api private
+      def self.callable_shape?(logger)
+        !logger.nil? && logger.respond_to?(:call)
+      end
+
+      # @param logger [Object] any object that responds to `:info`/`:error`,
+      #   or that responds to `:call`, or that responds to neither (in which
+      #   case dispatch falls back to `Kernel.warn`).
+      def initialize(logger)
+        @logger = logger
+      end
+
+      # Dispatch an info-level log entry through the wrapped logger.
+      #
+      # @param message [String] the message to log.
+      # @return [nil]
+      def info(message)
+        log(:info, message)
+      end
+
+      # Dispatch an error-level log entry through the wrapped logger.
+      #
+      # @param message [String] the message to log.
+      # @return [nil]
+      def error(message)
+        log(:error, message)
+      end
+
+      private
+
+      def log(level, message)
+        if @logger.respond_to?(level)
+          @logger.public_send(level, message)
+        elsif @logger.respond_to?(:call)
+          @logger.call(level, message)
+        else
+          Kernel.warn(message)
+        end
+        nil
+      rescue
+        # Requirement 21.3: logger errors must not propagate.
+        nil
+      end
+    end
+  end
+end

data/lib/better_auth/telemetry/noop_publisher.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module BetterAuth
+  module Telemetry
+    # Publisher returned from {BetterAuth::Telemetry.create} when telemetry is
+    # disabled, when no `BETTER_AUTH_TELEMETRY_ENDPOINT` is configured and no
+    # `custom_track` is supplied, or when the soft-load fallback inside
+    # {BetterAuth::Auth#initialize} cannot load the telemetry gem.
+    #
+    # Calling `#publish` on a `NoopPublisher` is always safe: the method
+    # accepts any event-shaped argument, performs no work, raises no error,
+    # and returns `nil`. `#enabled?` always reports `false`. This lets
+    # callers treat `auth.telemetry` as a non-nullable, always-callable
+    # collaborator without having to nil-check before each `publish` call.
+    #
+    # @example
+    #   publisher = BetterAuth::Telemetry::NoopPublisher.new
+    #   publisher.publish(type: "ping", payload: {}) # => nil
+    #   publisher.enabled?                           # => false
+    class NoopPublisher
+      # @param _event [Object] any event payload; ignored.
+      # @return [nil]
+      def publish(_event)
+        nil
+      end
+
+      # @return [Boolean] always `false`.
+      def enabled?
+        false
+      end
+    end
+  end
+end