Class: Quonfig::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/quonfig/client.rb

Overview

Public Quonfig SDK client.

Wires the JSON stack: Quonfig::ConfigStore + Quonfig::Evaluator + Quonfig::Resolver. Three modes are supported:

  1. datadir: (offline) – load a workspace from the local filesystem.

  2. store: (test harness) – caller-supplied ConfigStore, no I/O.

  3. network mode (default) – HTTP fetch from api_urls populates the ConfigStore, then (if enabled) an SSE subscription keeps it live.

Network mode is the happy path for production SDK usage. The protobuf stack was retired in qfg-dk6.32; HTTP + SSE were wired back through Client in qfg-s7h.

Constant Summary collapse

LOG = 
Quonfig::InternalLogger.new(self)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = nil, store: nil, **option_kwargs) ⇒ Client

Returns a new instance of Client.



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/quonfig/client.rb', line 49

def initialize(options = nil, store: nil, **option_kwargs)
  @options =
    if options.is_a?(Quonfig::Options)
      options
    elsif options.is_a?(Hash)
      Quonfig::Options.new(options.merge(option_kwargs))
    else
      Quonfig::Options.new(option_kwargs)
    end
  Quonfig::InternalLogger.user_logger = @options.logger if @options.logger
  @global_context = build_initial_global_context(@options)
  @instance_hash = SecureRandom.uuid
  @store = store || Quonfig::ConfigStore.new
  @evaluator = Quonfig::Evaluator.new(@store, env_id: @options.environment)
  @resolver = Quonfig::Resolver.new(@store, @evaluator)
  @semantic_logger_filters = {}
  @sse_client = nil
  @poll_supervisor = nil
  @stopped = false
  @telemetry_reporter = nil
  @state_mutex = Mutex.new
  @last_successful_refresh = nil
  @sse_state = :idle
  @sse_ever_connected = false
  @fallback_engage_timer = nil
  @sse_terminal_failure = false

  # If the caller injected a store, we're in test/bootstrap mode; skip I/O.
  return if store

  if @options.datadir
    load_datadir_into_store
  else
    initialize_network_mode
  end

  initialize_telemetry

  # Register only for non-store-injected clients (a caller-supplied store
  # is the test/bootstrap path; the fork hook does not apply there).
  self.class.register_instance(self) unless store
end

Instance Attribute Details

#config_loader ⇒ Object (readonly)

Returns the value of attribute config_loader.



46
47
48
 
# File 'lib/quonfig/client.rb', line 46

def config_loader
  @config_loader
end

#evaluator ⇒ Object (readonly)

Returns the value of attribute evaluator.



46
47
48
 
# File 'lib/quonfig/client.rb', line 46

def evaluator
  @evaluator
end

#instance_hash ⇒ Object (readonly)

Returns the value of attribute instance_hash.



46
47
48
 
# File 'lib/quonfig/client.rb', line 46

def instance_hash
  @instance_hash
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



46
47
48
 
# File 'lib/quonfig/client.rb', line 46

def options
  @options
end

#resolver ⇒ Object (readonly)

Returns the value of attribute resolver.



46
47
48
 
# File 'lib/quonfig/client.rb', line 46

def resolver
  @resolver
end

#store ⇒ Object (readonly)

Returns the value of attribute store.



46
47
48
 
# File 'lib/quonfig/client.rb', line 46

def store
  @store
end

#telemetry_reporter ⇒ Object (readonly)

Returns the value of attribute telemetry_reporter.



46
47
48
 
# File 'lib/quonfig/client.rb', line 46

def telemetry_reporter
  @telemetry_reporter
end

Class Method Details

.each_instance(&block) ⇒ Object

Iterate live Client instances. Used by Quonfig::ForkSafety.



37
38
39
 
# File 'lib/quonfig/client.rb', line 37

def each_instance(&block)
  @instances_mutex.synchronize { @instances.keys }.each(&block)
end

.register_instance(client) ⇒ Object 



41
42
43
 
# File 'lib/quonfig/client.rb', line 41

def register_instance(client)
  @instances_mutex.synchronize { @instances[client] = true }
end

Instance Method Details

#after_fork_in_child ⇒ Object

qfg-ryov: post-fork (in child) hook. Re-establish whatever threaded components the client had pre-fork. No-op if the client was already stopped (the customer asked for it to be dead — do not resurrect), or if the client is in datadir mode (no threaded components to start).



317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
 
# File 'lib/quonfig/client.rb', line 317

def after_fork_in_child
  return if @stopped
  return if @options.datadir
  return if @config_loader.nil? # never finished network init (e.g. invalid key)

  # SSE state machine carries flags that no longer apply in the child
  # (the parent had connected, the parent had errored, etc.). Reset.
  @state_mutex.synchronize do
    @sse_state = :idle
    @sse_ever_connected = false
    @sse_terminal_failure = false
  end

  sse_started = @options.enable_sse && start_sse
  start_polling if @options.enable_polling && !sse_started

  restart_telemetry_in_child
end

#before_fork_in_parent ⇒ Object

qfg-ryov: pre-fork hook. Close the SSE worker, polling supervisor, telemetry reporter, and any fallback-engage timer. Idempotent — calling twice is safe. Does NOT set @stopped: the client is still expected to be usable post-fork via after_fork_in_child.

Why this matters: Ruby threads do not survive fork(2). If we let the child inherit a live Net::HTTP socket, both processes read from the same fd and corrupt each other’s bytes. Closing in the parent before fork is the only safe shape.



307
308
309
310
311
 
# File 'lib/quonfig/client.rb', line 307

def before_fork_in_parent
  return if @stopped

  tear_down_threaded_components!
end

#connection_state ⇒ Object

Aggregate connection state. Returns one of:

  • :initializing — no envelope has been installed and SSE is not yet connected.

  • :connected — SSE is live, or the SDK is delivering configs from a loaded envelope (datadir mode or post-initial-fetch with no SSE).

  • :disconnected — stop was called, or SSE errored and no fallback poller is active.

  • :falling_back — the Layer 2 HTTP polling supervisor is alive and serving as the active update channel.

**Diagnostic only.** Do NOT wire this into a Kubernetes liveness probe — see the README “Diagnostic health signals” section.

Contract: integration-test-data/chaos/supervisor-test-contract.md (Test 6).



383
384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/quonfig/client.rb', line 383

def connection_state
  @state_mutex.synchronize do
    next :disconnected if @stopped
    next :falling_back if @poll_supervisor&.alive?
    next :connected if @sse_state == :connected
    next :disconnected if @sse_state == :error

    # No SSE state change yet: state is driven by whether any envelope
    # has been installed (datadir / initial fetch).
    @last_successful_refresh.nil? ? :initializing : :connected
  end
end

#defined?(key) ⇒ Boolean

Returns:

  • (Boolean) 


177
178
179
 
# File 'lib/quonfig/client.rb', line 177

def defined?(key)
  !@store.get(key).nil?
end

#enabled?(feature_name, jit_context = NO_DEFAULT_PROVIDED) ⇒ Boolean

Returns:

  • (Boolean) 


172
173
174
175
 
# File 'lib/quonfig/client.rb', line 172

def enabled?(feature_name, jit_context = NO_DEFAULT_PROVIDED)
  value = get(feature_name, false, jit_context)
  [true, 'true'].include?(value)
end

#fork ⇒ Object 



396
397
398
 
# File 'lib/quonfig/client.rb', line 396

def fork
  self.class.new(@options.for_fork)
end

#get(key, default = NO_DEFAULT_PROVIDED, jit_context = NO_DEFAULT_PROVIDED) ⇒ Object

—- Lookup ——————————————————–



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

def get(key, default = NO_DEFAULT_PROVIDED, jit_context = NO_DEFAULT_PROVIDED)
  ctx = build_context(jit_context)
  record_context_for_telemetry(ctx)
  result =
    begin
      @resolver.get(key, ctx)
    rescue Quonfig::Errors::MissingDefaultError
      # The Resolver raises (matching Quonfig.get_or_raise semantics).
      # The Client's get applies the caller-provided default *or* the
      # configured on_no_default policy via handle_missing.
      nil
    end
  return handle_missing(key, default) if result.nil?

  record_evaluation_for_telemetry(result)
  result.unwrapped_value
end

#get_bool(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED) ⇒ Object 



124
125
126
 
# File 'lib/quonfig/client.rb', line 124

def get_bool(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
  typed_get(key, :bool, default: default, context: context)
end

#get_bool_details(key, context: NO_DEFAULT_PROVIDED) ⇒ Object

—- Details getters ———————————————-

Mirrors the typed getters above but returns a Quonfig::EvaluationDetails carrying the OpenFeature-aligned resolution reason (“STATIC”, “TARGETING_MATCH”, “SPLIT”, “DEFAULT”, or “ERROR”) plus an error_code/error_message on the error path. These methods never raise — exceptions are caught and rendered as ERROR details.



148
149
150
 
# File 'lib/quonfig/client.rb', line 148

def get_bool_details(key, context: NO_DEFAULT_PROVIDED)
  evaluate_details(key, :bool, context)
end

#get_duration(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED) ⇒ Object 



132
133
134
 
# File 'lib/quonfig/client.rb', line 132

def get_duration(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
  typed_get(key, :duration, default: default, context: context)
end

#get_float(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED) ⇒ Object 



120
121
122
 
# File 'lib/quonfig/client.rb', line 120

def get_float(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
  typed_get(key, Float, default: default, context: context)
end

#get_float_details(key, context: NO_DEFAULT_PROVIDED) ⇒ Object 



160
161
162
 
# File 'lib/quonfig/client.rb', line 160

def get_float_details(key, context: NO_DEFAULT_PROVIDED)
  evaluate_details(key, Float, context)
end

#get_int(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED) ⇒ Object 



116
117
118
 
# File 'lib/quonfig/client.rb', line 116

def get_int(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
  typed_get(key, Integer, default: default, context: context)
end

#get_int_details(key, context: NO_DEFAULT_PROVIDED) ⇒ Object 



156
157
158
 
# File 'lib/quonfig/client.rb', line 156

def get_int_details(key, context: NO_DEFAULT_PROVIDED)
  evaluate_details(key, Integer, context)
end

#get_json(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED) ⇒ Object 



136
137
138
 
# File 'lib/quonfig/client.rb', line 136

def get_json(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
  typed_get(key, :json, default: default, context: context)
end

#get_json_details(key, context: NO_DEFAULT_PROVIDED) ⇒ Object 



168
169
170
 
# File 'lib/quonfig/client.rb', line 168

def get_json_details(key, context: NO_DEFAULT_PROVIDED)
  evaluate_details(key, :json, context)
end

#get_string(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED) ⇒ Object 



112
113
114
 
# File 'lib/quonfig/client.rb', line 112

def get_string(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
  typed_get(key, String, default: default, context: context)
end

#get_string_details(key, context: NO_DEFAULT_PROVIDED) ⇒ Object 



152
153
154
 
# File 'lib/quonfig/client.rb', line 152

def get_string_details(key, context: NO_DEFAULT_PROVIDED)
  evaluate_details(key, String, context)
end

#get_string_list(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED) ⇒ Object 



128
129
130
 
# File 'lib/quonfig/client.rb', line 128

def get_string_list(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
  typed_get(key, :string_list, default: default, context: context)
end

#get_string_list_details(key, context: NO_DEFAULT_PROVIDED) ⇒ Object 



164
165
166
 
# File 'lib/quonfig/client.rb', line 164

def get_string_list_details(key, context: NO_DEFAULT_PROVIDED)
  evaluate_details(key, :string_list, context)
end

#in_context(properties) ⇒ Object

—- Context binding ———————————————-



187
188
189
190
 
# File 'lib/quonfig/client.rb', line 187

def in_context(properties)
  bound = Quonfig::BoundClient.new(self, properties)
  block_given? ? yield(bound) : bound
end

#inspect ⇒ Object 



400
401
402
 
# File 'lib/quonfig/client.rb', line 400

def inspect
  "#<Quonfig::Client:#{object_id} environment=#{@options.environment.inspect}>"
end

#keys ⇒ Object 



181
182
183
 
# File 'lib/quonfig/client.rb', line 181

def keys
  @store.keys
end

#last_successful_refresh ⇒ Object

Wall-clock time of the last installed envelope (any source: datadir, initial HTTP fetch, SSE, or polling fallback). nil before the first install. Preserved after stop.

**Diagnostic only.** Do NOT wire this into a Kubernetes liveness probe — a transient network blip will trip any freshness threshold and cause a rolling restart cascade. See the README “Diagnostic health signals” section.

Contract: integration-test-data/chaos/supervisor-test-contract.md (Test 6).



364
365
366
 
# File 'lib/quonfig/client.rb', line 364

def last_successful_refresh
  @state_mutex.synchronize { @last_successful_refresh }
end

#logger_key ⇒ Object

The configured logger_key from Options — the Quonfig config key the higher-level should_log? helper evaluates per-logger. nil if the client was not configured for dynamic log levels.



233
234
235
 
# File 'lib/quonfig/client.rb', line 233

def logger_key
  @options.logger_key
end

#on_update(&block) ⇒ Object 



289
290
291
 
# File 'lib/quonfig/client.rb', line 289

def on_update(&block)
  @on_update = block
end

#semantic_logger_filter(config_key:) ⇒ Object

—- Filters & helpers ——————————————–



202
203
204
205
 
# File 'lib/quonfig/client.rb', line 202

def semantic_logger_filter(config_key:)
  @semantic_logger_filters[config_key] ||=
    Quonfig::SemanticLoggerFilter.new(self, config_key: config_key)
end

#should_log?(logger_path:, desired_level:, contexts: {}) ⇒ Boolean

Higher-level log-level check — a convenience on top of the primitive get. Evaluates the client’s logger_key config and returns whether a message at desired_level should be emitted for logger_path.

The SDK injects logger_path under the quonfig-sdk-logging named context with property key so a single log-level config can drive per-logger overrides via the normal rule engine (e.g. PROP_STARTS_WITH_ONE_OF “MyApp::Services::”).

logger_path is passed through verbatim — the SDK does not normalize it. Callers may pass any identifier shape their host language prefers (dotted, colon, slash, etc.) and author matching rules in the config against that exact shape.

Parallels sdk-node’s shouldLog({loggerPath}) and sdk-go’s ShouldLogPath.

Raises Quonfig::Error if logger_key was not set on the client —use semantic_logger_filter(config_key:) directly if you want to evaluate a specific key without declaring it at init time.

Parameters:

  • logger_path (String) —

    native logger name (typically a class name).

  • desired_level (Symbol, String) —

    the level the caller wants to emit at (:trace, :debug, :info, :warn, :error, :fatal).

  • contexts (Hash) (defaults to: {}) —

    optional extra context to merge with the injected logger context.

Returns:

  • (Boolean) —

    true if the message should be emitted.



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/quonfig/client.rb', line 264

def should_log?(logger_path:, desired_level:, contexts: {})
  unless logger_key
    raise Quonfig::Error,
          'logger_key must be set at init to use should_log?(logger_path:, ...). ' \
          'Pass `logger_key:` to Quonfig::Options.new, or call ' \
          'semantic_logger_filter(config_key:) / get(config_key) directly.'
  end

  logger_context = {
    Quonfig::SemanticLoggerFilter::LOGGER_CONTEXT_NAME => {
      Quonfig::SemanticLoggerFilter::LOGGER_CONTEXT_KEY_PROP => logger_path
    }
  }
  merged = merge_contexts(normalize_context(contexts), logger_context)

  configured = get(logger_key, nil, merged)
  return true if configured.nil?

  desired_severity = Quonfig::SemanticLoggerFilter::LEVELS[normalize_log_level(desired_level)] ||
                     Quonfig::SemanticLoggerFilter::LEVELS[:debug]
  min_severity     = Quonfig::SemanticLoggerFilter::LEVELS[normalize_log_level(configured)] ||
                     Quonfig::SemanticLoggerFilter::LEVELS[:debug]
  desired_severity >= min_severity
end

#stdlib_formatter(logger_name: nil) ⇒ Proc

Build a formatter Proc for Ruby’s built-in ::Logger. The returned proc honors dynamic log levels from the client’s logger_key config: for each log call, it evaluates should_log? and either formats the record or returns an empty string (suppressing output).

Matches ReforgeHQ’s stdlib_formatter API name (snake_case).

Usage:

logger = ::Logger.new($stdout)
logger.formatter = client.stdlib_formatter                       # uses progname
logger.formatter = client.stdlib_formatter(logger_name: 'MyApp') # fixed name

Raises Quonfig::Error if logger_key was not set at init — parallels should_log?‘s behavior.

Parameters:

  • logger_name (String, nil) (defaults to: nil) —

    fallback logger identifier used when progname isn’t supplied by the Logger call site. If both are present, logger_name wins.

Returns:

  • (Proc) —

    a (severity, datetime, progname, msg) -> String proc.



226
227
228
 
# File 'lib/quonfig/client.rb', line 226

def stdlib_formatter(logger_name: nil)
  Quonfig::StdlibFormatter.build(self, logger_name: logger_name)
end

#stop ⇒ Object 



293
294
295
296
 
# File 'lib/quonfig/client.rb', line 293

def stop
  @stopped = true
  tear_down_threaded_components!
end

#terminal_failure? ⇒ Boolean

qfg-i5xv: true once the SSE layer has classified an HTTP response as terminal (401/403/404) — bad SDK key, revoked workspace permission, or wrong endpoint. The classification latches: the SDK will not auto-recover, and a customer-supplied retry must rebuild the client. Surfaced for operator alerting; ‘connection_state` still reports `:disconnected` to honor the documented connection_state vocabulary (supervisor-test-contract.md §“connectionState()” — values fixed).

Returns:

  • (Boolean) 


534
535
536
 
# File 'lib/quonfig/client.rb', line 534

def terminal_failure?
  @state_mutex.synchronize { @sse_terminal_failure }
end

#with_context(properties, &block) ⇒ Object 



192
193
194
195
196
197
198
 
# File 'lib/quonfig/client.rb', line 192

def with_context(properties, &block)
  if block_given?
    in_context(properties, &block)
  else
    Quonfig::BoundClient.new(self, properties)
  end
end

#worker_restart_total(layer: nil) ⇒ Object

quonfig_sdk_worker_restart_total counter (Tier 1 supervisor contract). Layer 1 (SSE) is tracked on Quonfig::SSEConfigClient#restart_total —incremented once per reconnect attempt by the SDK-owned reconnect loop (qfg-35sm). Layer 2 (HTTP polling fallback) is wired through Quonfig::WorkerSupervisor.

Pass layer: (‘1’ or ‘2’) to read a single layer; default returns the sum across both layers so the chaos harness (and operators) can pull per-layer values explicitly while preserving the previous single-number diagnostic surface.



346
347
348
349
350
351
352
 
# File 'lib/quonfig/client.rb', line 346

def worker_restart_total(layer: nil)
  case layer&.to_s
  when '1' then sse_restart_total
  when '2' then poll_restart_total
  else          sse_restart_total + poll_restart_total
  end
end