Class: BetterAuth::Telemetry::NormalizedOptions

Inherits:
Object
  • Object
show all
Defined in:
lib/better_auth/telemetry/options.rb

Overview

Normalized view of the host ‘options` argument supplied to create.

‘NormalizedOptions.from(options)` accepts:

  • a Configuration instance (production path: the value ‘BetterAuth::Auth#initialize` passes in),

  • a ‘Hash` with snake_case or camelCase keys (mirrors the upstream `BetterAuthOptions` shape and the common test seam),

  • or ‘nil` (every reader returns `nil` / a default-fallback logger).

## Telemetry opt-in precedence

‘telemetry_enabled` and `telemetry_debug` use the upstream `nil`/`true`/`false` precedence semantics:

  • ‘nil` means “not configured at the option layer” (the env layer may still opt the process in via `BETTER_AUTH_TELEMETRY`).

  • ‘true` is an explicit opt-in (subject to the test-environment skip unless `skip_test_check` overrides it).

  • ‘false` is an explicit opt-out that overrides every env opt-in.

The readers resolve ‘telemetry` and `telemetry` from either a Configuration or a raw Hash.

## Logger

The #logger reader always returns a usable LoggerAdapter. When the host supplies no logger we fall back to ‘BetterAuth::Logger.create` via LoggerAdapter.from so callers never have to nil-check.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(configuration:, app_name:, base_url:, telemetry_enabled:, telemetry_debug:, raw_logger:) ⇒ NormalizedOptions

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of NormalizedOptions.



146
147
148
149
150
151
152
153
 
# File 'lib/better_auth/telemetry/options.rb', line 146

def initialize(configuration:, app_name:, base_url:, telemetry_enabled:, telemetry_debug:, raw_logger:)
  @configuration = configuration
  @app_name = app_name
  @base_url = base_url
  @telemetry_enabled = telemetry_enabled
  @telemetry_debug = telemetry_debug
  @logger = LoggerAdapter.from(raw_logger)
end

Instance Attribute Details

#app_name ⇒ String? (readonly)

Returns the resolved ‘app_name` from the configuration or hash, or `nil` when not configured.

Returns:

  • (String, nil) —

    the resolved ‘app_name` from the configuration or hash, or `nil` when not configured.



72
73
74
 
# File 'lib/better_auth/telemetry/options.rb', line 72

def app_name
  @app_name
end

#base_url ⇒ String? (readonly)

Returns the resolved ‘base_url` from the configuration or hash, or `nil` when not configured.

Returns:

  • (String, nil) —

    the resolved ‘base_url` from the configuration or hash, or `nil` when not configured.



76
77
78
 
# File 'lib/better_auth/telemetry/options.rb', line 76

def base_url
  @base_url
end

#configuration ⇒ BetterAuth::Configuration? (readonly)

Returns the raw configuration instance when the host passed one, otherwise ‘nil`. Useful for detectors that want to read additional fields without going through this value object.

Returns:

  • (BetterAuth::Configuration, nil) —

    the raw configuration instance when the host passed one, otherwise ‘nil`. Useful for detectors that want to read additional fields without going through this value object.



68
69
70
 
# File 'lib/better_auth/telemetry/options.rb', line 68

def configuration
  @configuration
end

#logger ⇒ LoggerAdapter (readonly)

Returns always-usable logger adapter. Falls back to the default Logger when no logger was supplied.

Returns:

  • (LoggerAdapter) —

    always-usable logger adapter. Falls back to the default Logger when no logger was supplied.



88
89
90
 
# File 'lib/better_auth/telemetry/options.rb', line 88

def logger
  @logger
end

#telemetry_debug ⇒ Boolean? (readonly)

Returns explicit option-layer toggle for debug mode. ‘nil` defers to `BETTER_AUTH_TELEMETRY_DEBUG`.

Returns:

  • (Boolean, nil) —

    explicit option-layer toggle for debug mode. ‘nil` defers to `BETTER_AUTH_TELEMETRY_DEBUG`.



84
85
86
 
# File 'lib/better_auth/telemetry/options.rb', line 84

def telemetry_debug
  @telemetry_debug
end

#telemetry_enabled ⇒ Boolean? (readonly)

Returns explicit option-layer opt-in / opt-out for telemetry. ‘nil` defers to env. See class docs for precedence.

Returns:

  • (Boolean, nil) —

    explicit option-layer opt-in / opt-out for telemetry. ‘nil` defers to env. See class docs for precedence.



80
81
82
 
# File 'lib/better_auth/telemetry/options.rb', line 80

def telemetry_enabled
  @telemetry_enabled
end

Class Method Details

.from(options) ⇒ NormalizedOptions

Build a BetterAuth::Telemetry::NormalizedOptions from a Configuration, a ‘Hash`, or `nil`.

Parameters:

  • options (BetterAuth::Configuration, Hash, nil)

Returns:



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/better_auth/telemetry/options.rb', line 95

def self.from(options)
  if options.is_a?(::BetterAuth::Configuration)
    from_configuration(options)
  elsif options.is_a?(Hash)
    from_hash(options)
  else
    new(
      configuration: nil,
      app_name: nil,
      base_url: nil,
      telemetry_enabled: nil,
      telemetry_debug: nil,
      raw_logger: nil
    )
  end
end

.from_configuration(configuration) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/better_auth/telemetry/options.rb', line 113

def self.from_configuration(configuration)
  telemetry =
    if configuration.respond_to?(:telemetry) && configuration.telemetry.is_a?(Hash)
      configuration.telemetry
    else
      {}
    end
  new(
    configuration: configuration,
    app_name: configuration.app_name,
    base_url: configuration.base_url,
    telemetry_enabled: Options.fetch_key(telemetry, :enabled, :enabled),
    telemetry_debug: Options.fetch_key(telemetry, :debug, :debug),
    raw_logger: configuration.logger
  )
end

.from_hash(hash) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/better_auth/telemetry/options.rb', line 131

def self.from_hash(hash)
  telemetry = Options.fetch_key(hash, :telemetry, :telemetry)
  telemetry = telemetry.is_a?(Hash) ? telemetry : {}

  new(
    configuration: nil,
    app_name: Options.fetch_key(hash, :app_name, :appName),
    base_url: Options.fetch_key(hash, :base_url, :baseURL),
    telemetry_enabled: Options.fetch_key(telemetry, :enabled, :enabled),
    telemetry_debug: Options.fetch_key(telemetry, :debug, :debug),
    raw_logger: Options.fetch_key(hash, :logger, :logger)
  )
end