smplkit 1.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c6abfbfd0bf9044cafd8358b4c94e41b6b9e41586f8b4ee24aae08ea9f21d1c
+  data.tar.gz: 685a279e1eb56669618de0c016d84c0e408a616171120b7316ee187036920feb
+SHA512:
+  metadata.gz: c1578d33740b18f05d94f329d81798986b7c499ff0d1343125c50a9876a93ca6f1938c5475bc54f9c540aa71756e912b3984cba542f065dc21f61e3d2d823c14
+  data.tar.gz: e0c4953edf27c8bda7fc83524b233b4bd0011d830d44677034a29823e38a2cb621697ca9d1a1053b13ffac3dfb9eb4128565a6ddb51b7caf4087d233ea3c9d4f

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [Unreleased]
+
+Initial Ruby SDK implementation. See README.md and ADR-046 for scope.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Smpl Solutions LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# smplkit Ruby SDK
+
+[![Gem Version](https://badge.fury.io/rb/smplkit.svg)](https://rubygems.org/gems/smplkit)
+[![CI](https://github.com/smplkit/ruby-sdk/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/smplkit/ruby-sdk/actions/workflows/ci-cd.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Ruby SDK for the [smplkit](https://www.smplkit.com) platform — flags, config, and logging APIs with runtime evaluation, live updates, and management operations.
+
+The Ruby SDK mirrors the [Python SDK](https://github.com/smplkit/python-sdk) class-for-class. Ruby-specific deviations are documented in [ADR-046](https://github.com/smplkit/app/blob/main/docs/adrs/ADR-046-ruby-sdk.md).
+
+## Installation
+
+```bash
+gem install smplkit
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "smplkit"
+```
+
+Requires Ruby 3.3+.
+
+## Quick start
+
+### Runtime
+
+```ruby
+require "smplkit"
+
+Smplkit::Client.open(environment: "production", service: "my-svc") do |client|
+  checkout_v2 = client.flags.boolean_flag("checkout-v2", default: false)
+  client.wait_until_ready
+
+  client.set_context([Smplkit::Context.new("user", "u-1", plan: "enterprise")]) do
+    if checkout_v2.get
+      # show new checkout
+    end
+  end
+end
+```
+
+### Management
+
+```ruby
+manage = Smplkit::ManagementClient.new
+
+flag = manage.flags.new_boolean_flag(
+  "checkout-v2", default: false, description: "Controls rollout"
+)
+flag.add_rule(
+  Smplkit::Rule.new("Enable for enterprise users", environment: "staging")
+               .when("user.plan", Smplkit::Op::EQ, "enterprise")
+               .serve(true)
+)
+flag.save
+```
+
+## Configuration
+
+Resolution order, lowest to highest priority:
+
+1. SDK hardcoded defaults
+2. `~/.smplkit` config file (with `[common]` and profile sections)
+3. `SMPLKIT_*` environment variables
+4. Constructor arguments
+
+See [ADR-021](https://github.com/smplkit/app/blob/main/docs/adrs/ADR-021-client-strategy.md) for details.
+
+## Logging adapters
+
+Two adapters ship at launch (per ADR-046 §2.3):
+
+| Adapter           | Covers                                                                  |
+|-------------------|-------------------------------------------------------------------------|
+| `stdlib-logger`   | Ruby stdlib `Logger` (and Rails via `ActiveSupport::Logger`)            |
+| `semantic-logger` | The [`semantic_logger` gem](https://github.com/reidmorrison/semantic_logger) |
+
+Custom adapters subclass `Smplkit::Logging::Adapters::Base`.
+
+## Rails integration
+
+Add the gem and run:
+
+```bash
+rails generate smplkit:install
+```
+
+This creates `config/initializers/smplkit.rb` with documented examples for the per-request context provider and standard configuration knobs.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec        # unit tests
+bundle exec rubocop      # lint
+make generate            # regenerate clients (requires Node.js + npx)
+```
+
+The repository follows the standard smplkit "every commit lands on `main`" workflow — see CLAUDE.md.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/smplkit/client.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Smplkit
+  # Synchronous entry point for the smplkit SDK.
+  #
+  #   client = Smplkit::Client.new(environment: "production", service: "my-svc")
+  #   checkout_v2 = client.flags.boolean_flag("checkout-v2", default: false)
+  #   if checkout_v2.get
+  #     # ...
+  #   end
+  #   client.close
+  #
+  # Block form:
+  #
+  #   Smplkit::Client.open(environment: "production", service: "my-svc") do |client|
+  #     # ...
+  #   end
+  #
+  # All parameters are optional. When omitted, the SDK resolves them from
+  # environment variables (+SMPLKIT_*+) or the +~/.smplkit+ configuration file.
+  # See ADR-021 for the full resolution algorithm.
+  #
+  # +Smplkit::Client+ is thread-safe by construction. Background work runs on
+  # internal SDK-owned threads; public methods block the calling thread and
+  # return values directly.
+  class Client
+    PERIODIC_FLUSH_INTERVAL = 60.0
+
+    attr_reader :manage, :config, :flags, :logging
+
+    # Construct, yield to the block, and close on exit.
+    def self.open(**)
+      client = new(**)
+      begin
+        yield client
+      ensure
+        client.close
+      end
+    end
+
+    def initialize(api_key: nil, environment: nil, service: nil, profile: nil,
+                   base_domain: nil, scheme: nil, debug: nil, telemetry: nil)
+      cfg = ConfigResolution.resolve_config(
+        profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme,
+        environment: environment, service: service, debug: debug, telemetry: telemetry
+      )
+      Smplkit.enable_debug if cfg.debug
+
+      @api_key = cfg.api_key
+      @environment = cfg.environment
+      @service = cfg.service
+      @base_domain = cfg.base_domain
+      @scheme = cfg.scheme
+
+      masked_key = cfg.api_key.length > 10 ? "#{cfg.api_key[0, 10]}..." : cfg.api_key
+      Smplkit.debug(
+        "lifecycle",
+        "Client init: api_key=#{masked_key} env=#{cfg.environment.inspect} service=#{cfg.service.inspect} " \
+        "base_domain=#{cfg.base_domain.inspect} scheme=#{cfg.scheme.inspect} " \
+        "debug=#{cfg.debug} telemetry=#{cfg.telemetry}"
+      )
+
+      mgmt_cfg = ConfigResolution::ResolvedManagementConfig.new(
+        api_key: cfg.api_key, base_domain: cfg.base_domain, scheme: cfg.scheme, debug: cfg.debug
+      )
+      @manage = ManagementClient.from_resolved(mgmt_cfg)
+
+      app_url = ConfigResolution.service_url(cfg.scheme, "app", cfg.base_domain)
+      flags_url = ConfigResolution.service_url(cfg.scheme, "flags", cfg.base_domain)
+      logging_url = ConfigResolution.service_url(cfg.scheme, "logging", cfg.base_domain)
+      @app_base_url = app_url
+
+      @metrics = if cfg.telemetry
+                   MetricsReporter.new(http_client: @manage._app_http,
+                                       environment: cfg.environment,
+                                       service: cfg.service)
+                 end
+
+      @ws_manager = nil
+      @config = Config::ConfigClient.new(self, manage: @manage, metrics: @metrics)
+      @flags = Flags::FlagsClient.new(self, manage: @manage, metrics: @metrics,
+                                            flags_base_url: flags_url, app_base_url: app_url)
+      @logging = Logging::LoggingClient.new(self, manage: @manage, metrics: @metrics,
+                                                  logging_base_url: logging_url, app_base_url: app_url)
+
+      @closed = false
+      schedule_periodic_flush
+
+      @init_thread = Thread.new(@manage, @environment, @service, @app_base_url) do |mgmt, env, svc, app_url|
+        register_service_context(mgmt, env, svc, app_url)
+      end
+    end
+
+    # Eagerly initialize the SDK and block until it is fully ready.
+    #
+    # Pre-fetches all flags and configs into the local cache, opens the
+    # live-updates WebSocket, and waits for the handshake to complete.
+    # After this returns, +flag.get+ / +client.config.get+ hit cache (no
+    # first-request connect tax) and any +on_change+ listeners receive every
+    # server event from this point forward.
+    #
+    # Logging integration is *not* installed here — call
+    # +client.logging.install+ separately if you want it.
+    def wait_until_ready(timeout: 10.0)
+      @flags.start
+      @config.start
+      ws = _ensure_ws
+      deadline = monotonic_now + timeout
+      while ws.connection_status != "connected"
+        if monotonic_now >= deadline
+          raise TimeoutError, "Live-updates websocket did not connect within #{timeout}s " \
+                              "(status: #{ws.connection_status.inspect})"
+        end
+
+        sleep(0.05)
+      end
+    end
+
+    # Stash +contexts+ as the current request's evaluation context.
+    #
+    # Two usage shapes:
+    #
+    #   # Fire-and-forget (typical middleware)
+    #   client.set_context([Smplkit::Context.new("user", "u-123")])
+    #
+    #   # Scoped block (impersonation or one-off override)
+    #   client.set_context([Smplkit::Context.new("user", "impersonated")]) do
+    #     # ...
+    #   end
+    #   # original context restored here
+    #
+    # Each unique +(type, key)+ is also queued for bulk registration on the
+    # management API.
+    def set_context(contexts, &block)
+      @manage.contexts.register(contexts) if contexts && !contexts.empty?
+
+      scope = Smplkit.set_request_context(contexts || [])
+      if block
+        scope.call(&block)
+      else
+        scope
+      end
+    end
+
+    def close
+      Smplkit.debug("lifecycle", "Client.close called")
+      @closed = true
+      @flush_timer&.shutdown
+      final_flush
+      @metrics&.close
+      @logging._close
+      @flags._close
+      @config._close
+      @ws_manager&.stop
+      @ws_manager = nil
+      @manage.close
+    end
+
+    # Internal accessors used by sub-clients --------------------------------
+
+    def _service = @service
+    def _environment = @environment
+    def _api_key = @api_key
+    def _app_base_url = @app_base_url
+    def _metrics = @metrics
+
+    def _ensure_ws
+      @_ensure_ws ||= begin
+        ws = SharedWebSocket.new(app_base_url: @app_base_url, api_key: @api_key, metrics: @metrics)
+        ws.start
+        ws
+      end
+    end
+
+    def _flags_transport = @manage.flags
+    def _config_transport = @manage.config
+
+    private
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def schedule_periodic_flush
+      @flush_timer = Concurrent::TimerTask.new(execution_interval: PERIODIC_FLUSH_INTERVAL) do
+        next if @closed
+
+        begin
+          @manage.contexts.flush
+          @manage.flags.flush
+          @manage.loggers.flush
+        rescue StandardError => e
+          Smplkit.debug("registration", "periodic flush failed: #{e.class}: #{e.message}")
+        end
+      end
+      @flush_timer.execute
+    end
+
+    def final_flush
+      [@manage.contexts, @manage.flags, @manage.loggers].each do |ns|
+        ns.flush
+      rescue StandardError => e
+        Smplkit.debug("registration", "final flush failed: #{e.class}: #{e.message}")
+      end
+    end
+
+    def register_service_context(_mgmt, _env, _svc, _app_url)
+      # No-op stub: bulk-registers the service + environment with the platform.
+      # Wired up via the contexts buffer once the generated client layer is
+      # committed. Until then, the in-process buffer captures these and the
+      # next periodic flush attempts to send them.
+    rescue StandardError => e
+      Smplkit.debug("lifecycle", "register service context failed: #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/smplkit/config/client.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Config
+    # Describes a config change event delivered to +on_change+ listeners.
+    class ConfigChangeEvent
+      attr_reader :key, :source, :deleted
+
+      def initialize(key:, source:, deleted: false)
+        @key = key
+        @source = source
+        @deleted = deleted
+        freeze
+      end
+
+      def deleted? = @deleted
+
+      def ==(other)
+        other.is_a?(ConfigChangeEvent) && key == other.key && source == other.source && deleted == other.deleted
+      end
+      alias eql? ==
+
+      def hash = [key, source, deleted].hash
+    end
+
+    # A live, dot-accessible view over a resolved configuration.
+    #
+    # Backed by the most-recent resolved Hash for a config key. +#get+ /
+    # +#[]+ return the resolved value at the time of access; +#refresh+
+    # rebuilds the snapshot from the underlying client.
+    class LiveConfigProxy
+      def initialize(client, key)
+        @client = client
+        @key = key
+        @snapshot = client._resolve_now(key)
+      end
+
+      def get(item_key, default = nil)
+        return @snapshot if item_key.nil?
+
+        keys = item_key.to_s.split(".")
+        keys.reduce(@snapshot) do |scope, k|
+          break default if scope.nil?
+
+          scope.is_a?(Hash) ? scope[k] : default
+        end || default
+      end
+
+      def [](item_key)
+        get(item_key)
+      end
+
+      def to_h
+        @snapshot.dup
+      end
+
+      def refresh
+        @snapshot = @client._resolve_now(@key)
+        self
+      end
+    end
+
+    # Synchronous config runtime namespace.
+    #
+    # Obtained via +Smplkit::Client#config+. Exposes typed accessors
+    # (+get_string+, +get_number+, +get_boolean+, +get_json+) and runtime
+    # control (+refresh+, +on_change+).
+    class ConfigClient
+      def initialize(parent, manage:, metrics:)
+        @parent = parent
+        @manage = manage
+        @metrics = metrics
+        @environment = parent._environment
+        @service = parent._service
+
+        @snapshots = {}
+        @raw_chains = {}
+        @global_listeners = []
+        @key_listeners = Hash.new { |h, k| h[k] = [] }
+        @connected = false
+        @lock = Mutex.new
+      end
+
+      def start
+        return if @connected
+
+        @environment = @parent._environment
+        @ws_manager = @parent._ensure_ws
+        @ws_manager.on("config_changed") { |data| handle_config_changed(data) }
+        @ws_manager.on("config_deleted") { |data| handle_config_deleted(data) }
+        @connected = true
+      end
+
+      def get(config_key, model_class = nil)
+        start unless @connected
+
+        snapshot = resolve(config_key)
+        return snapshot if model_class.nil?
+
+        model_class.new(snapshot)
+      end
+
+      def get_string(item_key, default: nil, config: nil)
+        typed_get(item_key, default, config) { |v| v.is_a?(String) ? v : v.to_s }
+      end
+
+      def get_number(item_key, default: nil, config: nil)
+        typed_get(item_key, default, config) do |v|
+          v.is_a?(Numeric) ? v : Float(v)
+        rescue StandardError
+          default
+        end
+      end
+
+      def get_boolean(item_key, default: nil, config: nil)
+        typed_get(item_key, default, config) { |v| !!v }
+      end
+
+      def get_json(item_key, default: nil, config: nil)
+        typed_get(item_key, default, config) { |v| v }
+      end
+
+      def live(config_key)
+        start unless @connected
+
+        LiveConfigProxy.new(self, config_key)
+      end
+
+      def on_change(config_key = nil, &block)
+        raise ArgumentError, "on_change requires a block" unless block
+
+        if config_key.nil?
+          @global_listeners << block
+        else
+          @key_listeners[config_key] << block
+        end
+        block
+      end
+
+      def refresh
+        @lock.synchronize do
+          @snapshots.clear
+          @raw_chains.clear
+        end
+        fire_change_listeners_all("manual")
+      end
+
+      def _resolve_now(config_key)
+        resolve(config_key)
+      end
+
+      def _close
+        # No durable resources; symmetry stub.
+      end
+
+      private
+
+      def typed_get(item_key, default, config_key)
+        snapshot = config_key ? resolve(config_key) : merged_snapshot
+        keys = item_key.to_s.split(".")
+        value = keys.reduce(snapshot) do |scope, k|
+          break default unless scope.is_a?(Hash)
+
+          scope[k]
+        end
+        return default if value.nil?
+
+        block_given? ? yield(value) : value
+      end
+
+      def merged_snapshot
+        @lock.synchronize do
+          @snapshots.values.reduce({}) { |acc, snap| Helpers.deep_merge(acc, snap) }
+        end
+      end
+
+      def resolve(config_key)
+        @lock.synchronize do
+          return @snapshots[config_key].dup if @snapshots.key?(config_key)
+        end
+
+        chain = fetch_chain(config_key)
+        snapshot = Helpers.resolve_chain(chain, @environment)
+        @lock.synchronize do
+          @raw_chains[config_key] = chain
+          @snapshots[config_key] = snapshot
+        end
+        snapshot.dup
+      end
+
+      def fetch_chain(config_key)
+        # Stub: in the absence of a generated client, the runtime returns an
+        # empty chain. ManagementClient wires this up properly once the
+        # generated layer is committed.
+        @parent._config_transport.fetch_chain(config_key)
+      rescue Smplkit::Error
+        raise
+      rescue StandardError => e
+        raise Smplkit::ConnectionError, "Failed to fetch config #{config_key.inspect}: #{e.message}"
+      end
+
+      def handle_config_changed(data)
+        key = data["key"] || data["id"]
+        return unless key
+
+        @lock.synchronize do
+          @snapshots.delete(key)
+          @raw_chains.delete(key)
+        end
+        fire_change_listeners(key, "websocket")
+      end
+
+      def handle_config_deleted(data)
+        key = data["key"] || data["id"]
+        return unless key
+
+        @lock.synchronize do
+          @snapshots.delete(key)
+          @raw_chains.delete(key)
+        end
+        fire_change_listeners(key, "websocket", deleted: true)
+      end
+
+      def fire_change_listeners(config_key, source, deleted: false)
+        event = ConfigChangeEvent.new(key: config_key, source: source, deleted: deleted)
+        (@global_listeners + @key_listeners[config_key]).each do |cb|
+          cb.call(event)
+        rescue StandardError => e
+          Smplkit.debug("config", "listener raised: #{e.class}: #{e.message}")
+        end
+      end
+
+      def fire_change_listeners_all(source)
+        (@snapshots.keys | @key_listeners.keys).each { |key| fire_change_listeners(key, source) }
+      end
+    end
+  end
+end

data/lib/smplkit/config/helpers.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Config
+    module Helpers
+      module_function
+
+      # Translate a JSON:API resource Hash into a Config domain model.
+      def config_from_json(client, resource)
+        attrs = resource["attributes"] || {}
+        items = (attrs["items"] || {}).map do |name, item|
+          if item.is_a?(Hash) && item.key?("value")
+            ConfigItem.new(
+              name: name,
+              value: item["value"],
+              type: item["type"],
+              description: item["description"]
+            )
+          else
+            ConfigItem.new(name: name, value: item, type: ItemType::JSON)
+          end
+        end
+
+        environments = (attrs["environments"] || {}).each_with_object({}) do |(env, env_data), out|
+          env_values = env_data.is_a?(Hash) ? (env_data["values"] || {}) : {}
+          out[env] = ConfigEnvironment.new(values: env_values)
+        end
+
+        Config.new(
+          client,
+          id: resource["id"] || attrs["id"],
+          key: attrs["key"] || resource["id"],
+          name: attrs["name"],
+          description: attrs["description"],
+          parent_id: attrs["parent_id"],
+          items: items,
+          environments: environments,
+          created_at: attrs["created_at"],
+          updated_at: attrs["updated_at"]
+        )
+      end
+
+      def build_config_request_body(config)
+        items = {}
+        config.items.each do |item|
+          items[item.name] = {
+            "value" => item.value,
+            "type" => item.type,
+            "description" => item.description
+          }.compact
+        end
+
+        environments = config.environments.each_with_object({}) do |(env, env_obj), out|
+          out[env] = { "values" => env_obj.values_raw }
+        end
+
+        attributes = {
+          "key" => config.key,
+          "name" => config.name,
+          "description" => config.description,
+          "parent_id" => config.parent_id,
+          "items" => items,
+          "environments" => environments
+        }.compact
+        { "data" => { "type" => "config", "id" => config.key, "attributes" => attributes } }
+      end
+
+      # Deep-merge two Hashes, with +override+ winning. Mirrors the Python
+      # +deep_merge+ helper used by the resolver.
+      def deep_merge(base, override)
+        result = base.dup
+        override.each do |key, value|
+          result[key] = if result[key].is_a?(Hash) && value.is_a?(Hash)
+                          deep_merge(result[key], value)
+                        else
+                          value
+                        end
+        end
+        result
+      end
+
+      # Unwrap typed items +{ key => { value, type, desc } }+ to +{ key => raw }+.
+      def unwrap_items(items)
+        items.each_with_object({}) do |(k, v), out|
+          out[k] = v.is_a?(Hash) && v.key?("value") ? v["value"] : v
+        end
+      end
+
+      # Resolve the full configuration for an environment given a config chain.
+      #
+      # Walks from root (last element) to child (first element), accumulating
+      # values via deep merge so child configs override parent configs.
+      def resolve_chain(chain, environment)
+        accumulated = {}
+        chain.reverse_each do |config_data|
+          raw_items = config_data["items"] || config_data["values"] || {}
+          base_values = unwrap_items(raw_items)
+          env_data = (config_data["environments"] || {})[environment] || {}
+          env_raw = env_data.is_a?(Hash) ? (env_data["values"] || {}) : {}
+          env_values = unwrap_items(env_raw)
+          config_resolved = deep_merge(base_values, env_values)
+          accumulated = deep_merge(accumulated, config_resolved)
+        end
+        accumulated
+      end
+    end
+  end
+end