Module: ConvertSdk

Defined in:
lib/convert_sdk.rb,
lib/convert_sdk/client.rb,
lib/convert_sdk/config.rb,
lib/convert_sdk/context.rb,
lib/convert_sdk/version.rb,
lib/convert_sdk/redactor.rb,
lib/convert_sdk/sentinel.rb,
lib/convert_sdk/fork_guard.rb,
lib/convert_sdk/api_manager.rb,
lib/convert_sdk/comparisons.rb,
lib/convert_sdk/http_client.rb,
lib/convert_sdk/log_manager.rb,
lib/convert_sdk/data_manager.rb,
lib/convert_sdk/murmur_hash3.rb,
lib/convert_sdk/rule_manager.rb,
lib/convert_sdk/event_manager.rb,
lib/convert_sdk/visitors_queue.rb,
lib/convert_sdk/enums/log_level.rb,
lib/convert_sdk/feature_manager.rb,
lib/convert_sdk/background_timer.rb,
lib/convert_sdk/bucketed_feature.rb,
lib/convert_sdk/config_validator.rb,
lib/convert_sdk/enums/rule_error.rb,
lib/convert_sdk/segments_manager.rb,
lib/convert_sdk/bucketing_manager.rb,
lib/convert_sdk/bucketed_variation.rb,
lib/convert_sdk/data_store_manager.rb,
lib/convert_sdk/experience_manager.rb,
lib/convert_sdk/stores/redis_store.rb,
lib/convert_sdk/enums/goal_data_key.rb,
lib/convert_sdk/enums/system_events.rb,
lib/convert_sdk/stores/memory_store.rb,
lib/convert_sdk/enums/feature_status.rb,
lib/convert_sdk/enums/bucketing_error.rb

Overview

The Convert Experiences full-stack SDK for Ruby.

ConvertSdk.create is THE public entry point (frozen API name): it builds the validated Config, wires the managers, and returns a ready-to-use Client.

Defined Under Namespace

Modules: BucketingError, Comparisons, FeatureStatus, ForkGuard, GoalDataKey, LogLevel, MurmurHash3, RuleError, Stores, SystemEvents Classes: ApiManager, BackgroundTimer, BucketedFeature, BucketedVariation, BucketingManager, Client, Config, ConfigValidator, Context, DataManager, DataStoreManager, Error, EventManager, ExperienceManager, FeatureManager, HttpClient, LogManager, Redactor, RuleManager, SegmentsManager, Sentinel, VisitorsQueue

Constant Summary collapse

DEFAULT_CONFIG_TTL =

The default config-cache TTL in seconds, used by the timer-off (Lambda/CLI) decision-time staleness check when data_refresh_interval is nil (timer-off ≠ TTL-off). 300s converges on the same cadence the background timer uses, on demand. A Ruby-SDK design constant (PHP on-demand TTL semantics) — the JS SDK has no timer-off TTL concept. See Story 2.7.

300
VERSION =

The gem version string (semantic version).

This is a DEV PLACEHOLDER. The real version is written here at release time by the semantic-release @semantic-release/exec prepareCmd (release.config.mjs), as an UNCOMMITTED working-tree edit — the gem builds carrying the computed version, but main never receives a version-bump commit. The next release derives its version from this run's git tag, not from this file (FR66). Mirrors the Android SDK's 0.0.0 placeholder in gradle/libs.versions.toml.

Returns:

  • (String) 
"0.0.0"

Class Method Summary collapse

Class Method Details

.at_exit_registration_enabled=(value) ⇒ Boolean

Set the at_exit_registration_enabled? flag (test harness only).

Parameters:

  • value (Boolean)

Returns:

  • (Boolean) 


77
78
79
 
# File 'lib/convert_sdk.rb', line 77

def self.at_exit_registration_enabled=(value)
  @at_exit_registration_enabled = value
end

.at_exit_registration_enabled? ⇒ Boolean

Whether Client registers its PID-guarded at_exit flush handler at construction (Story 4.4 AC#5). Always true in production. The TEST HARNESS alone flips this off (a spec/support hook) so unit specs that build clients do NOT register live at_exit handlers — which would fire flush during RSpec suite teardown. The handler BODY is unit-tested directly via Client#run_at_exit_flush; the live-registration path is proven end-to-end in a SUBPROCESS in spec/integration/fork_safety_spec.rb.

Returns:

  • (Boolean) 


69
70
71
72
 
# File 'lib/convert_sdk.rb', line 69

def self.at_exit_registration_enabled?
  @at_exit_registration_enabled = true unless defined?(@at_exit_registration_enabled)
  @at_exit_registration_enabled
end

.create(sdk_key: nil, data: nil, store: nil, clock: nil, sink: nil, **options) ⇒ Client

Build an SDK client from an SDK key (live config fetch) or a pre-fetched data: object (direct data mode). THE public entry point.

Wiring order: a LogManager is built first, then Config (which registers any sdk_key / sdk_key_secret with the manager's Redactor before any log line can carry them and raises ArgumentError on misconfiguration — the SDK's only raising surface), then the HttpClient, DataStoreManager, EventManager, and DataManager ports, then the Client (which fetches / installs config and fires ready). No background threads are started here (NFR4 — lazy start; the refresh / flush timers are wired by their own stories).

Parameters:

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

    the account/project SDK key (fetch mode).

  • data (Hash, nil) (defaults to: nil) —

    a pre-fetched config object (direct data mode); when supplied, no fetch occurs.

  • store (Object, nil) (defaults to: nil) —

    an optional duck-typed data store (get/set); defaults to an in-memory store.

  • clock (#call, nil) (defaults to: nil) —

    an optional monotonic time source (seconds) for the config-cache TTL math (Story 2.7); defaults to the SDK's monotonic clock. Injectable so tests control staleness without real waits. NOT a Config option — extracted here before validation.

  • sink (Object, nil) (defaults to: nil) —

    an optional initial log sink (anything responding to debug/info/warn/error). Forwarded to the internally-built LogManager so the FULL lifecycle — including the construction-time config fetch (+HttpClient#request+ debug line, which carries the sdk_key in the config URL) — is observable through the public entry point. Without this seam a host could only attach a sink AFTER create, missing every init-time line (and therefore the init-time redaction proof). NOT a Config option — extracted here before validation (like clock). Invalid sinks are rejected by ConvertSdk::LogManager#add_sink, not raised.

  • options (Hash{Symbol=>Object}) —

    any other ConvertSdk::Config::DEFAULTS option (+sdk_key_secret+, environment, log_level, timeouts, …).

Returns:

  • (Client) —

    the wired SDK client.

Raises:

  • (ArgumentError) —

    on misconfiguration (missing sdk_key+data, bad types, unknown option) — the only exception create lets escape.



116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/convert_sdk.rb', line 116

def self.create(sdk_key: nil, data: nil, store: nil, clock: nil, sink: nil, **options)
  config_options = options.merge(sdk_key: sdk_key, data: data)
  log_manager = LogManager.new(
    level: options.fetch(:log_level, Config::DEFAULTS[:log_level]), sink: sink
  )
  # Wire the ForkGuard re-arm logger (Story 2.7) so fork-detection debug lines
  # flow through the redacting LogManager. nil-safe before wiring.
  ForkGuard.logger = log_manager
  config = Config.new(log_manager: log_manager, **config_options)

  Client.new(config: config, log_manager: log_manager, **build_managers(config, log_manager, store, clock))
end