smplkit 1.0.5

data/lib/smplkit/management/models.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Management
+    # An environment resource — a customer-defined deploy target (production,
+    # staging, etc.) for which configs and flags can have overrides.
+    class Environment
+      attr_accessor :id, :key, :name, :color, :classification, :description, :created_at, :updated_at
+
+      def initialize(client = nil, key:, id: nil, name: nil, color: nil,
+                     classification: EnvironmentClassification::STANDARD,
+                     description: nil, created_at: nil, updated_at: nil)
+        @client = client
+        @id = id
+        @key = key
+        @name = name
+        @color = color
+        @classification = classification
+        @description = description
+        @created_at = created_at
+        @updated_at = updated_at
+      end
+
+      def save
+        raise "Environment was constructed without a client; cannot save" if @client.nil?
+
+        updated =
+          if @created_at.nil?
+            @client._create_environment(self)
+          else
+            @client._update_environment(self)
+          end
+        _apply(updated)
+        self
+      end
+      alias save! save
+
+      def delete
+        raise "Environment was constructed without a client; cannot delete" if @client.nil?
+
+        @client.delete(@key)
+      end
+      alias delete! delete
+
+      def _apply(other)
+        @id = other.id
+        @key = other.key
+        @name = other.name
+        @color = other.color
+        @classification = other.classification
+        @description = other.description
+        @created_at = other.created_at
+        @updated_at = other.updated_at
+      end
+    end
+
+    # A context type resource (e.g. "user", "account").
+    class ContextType
+      attr_accessor :id, :key, :name, :description, :created_at, :updated_at
+
+      def initialize(client = nil, key:, id: nil, name: nil, description: nil,
+                     created_at: nil, updated_at: nil)
+        @client = client
+        @id = id
+        @key = key
+        @name = name
+        @description = description
+        @created_at = created_at
+        @updated_at = updated_at
+      end
+
+      def save
+        raise "ContextType was constructed without a client; cannot save" if @client.nil?
+
+        updated =
+          if @created_at.nil?
+            @client._create_context_type(self)
+          else
+            @client._update_context_type(self)
+          end
+        _apply(updated)
+        self
+      end
+      alias save! save
+
+      def delete
+        raise "ContextType was constructed without a client; cannot delete" if @client.nil?
+
+        @client.delete(@key)
+      end
+      alias delete! delete
+
+      def _apply(other)
+        @id = other.id
+        @key = other.key
+        @name = other.name
+        @description = other.description
+        @created_at = other.created_at
+        @updated_at = other.updated_at
+      end
+    end
+
+    # An account-wide settings resource.
+    class AccountSettings
+      attr_accessor :id, :environment_order, :default_environment, :updated_at
+
+      def initialize(client = nil, id: nil, environment_order: nil,
+                     default_environment: nil, updated_at: nil)
+        @client = client
+        @id = id
+        @environment_order = environment_order || []
+        @default_environment = default_environment
+        @updated_at = updated_at
+      end
+
+      def save
+        raise "AccountSettings was constructed without a client; cannot save" if @client.nil?
+
+        updated = @client._update_account_settings(self)
+        _apply(updated)
+        self
+      end
+      alias save! save
+
+      def _apply(other)
+        @id = other.id
+        @environment_order = other.environment_order
+        @default_environment = other.default_environment
+        @updated_at = other.updated_at
+      end
+    end
+  end
+end

data/lib/smplkit/management/types.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Management
+    # Whether an environment participates in the canonical ordering.
+    #
+    # +STANDARD+ environments are the customer's deploy targets — production,
+    # staging, development, etc.
+    # +AD_HOC+ environments are transient targets (preview branches, individual
+    # developer sandboxes) that should not appear in the standard ordering.
+    module EnvironmentClassification
+      STANDARD = "STANDARD"
+      AD_HOC = "AD_HOC"
+
+      ALL = [STANDARD, AD_HOC].freeze
+    end
+
+    HEX_RE = /\A#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\z/
+
+    # A color, expressed as a CSS hex string.
+    #
+    #   Smplkit::Color.new("#ef4444")        # 6-digit hex
+    #   Smplkit::Color.new("#fff")           # 3-digit shorthand
+    #   Smplkit::Color.new("#ef4444aa")      # 8-digit with alpha
+    #   Smplkit::Color.rgb(239, 68, 68)      # RGB components
+    #
+    # Frozen — construct a fresh +Color+ to change a value.
+    class Color
+      attr_reader :hex
+
+      def initialize(hex)
+        raise TypeError, "Color hex must be a String, got #{hex.class}: #{hex.inspect}" unless hex.is_a?(String)
+        unless HEX_RE.match?(hex)
+          raise ArgumentError,
+                "Invalid color #{hex.inspect}: must be a CSS hex string like '#RGB', '#RRGGBB', or '#RRGGBBAA'"
+        end
+
+        @hex = hex.downcase.freeze
+        freeze
+      end
+
+      def self.rgb(red, green, blue)
+        [%w[red green blue], [red, green, blue]].transpose.each do |name, val|
+          unless val.is_a?(Integer) && !val.is_a?(TrueClass) && !val.is_a?(FalseClass)
+            raise TypeError,
+                  "Color.rgb #{name} must be an Integer, got #{val.class}"
+          end
+          raise ArgumentError, "Color.rgb #{name} must be in range 0-255, got #{val.inspect}" unless val.between?(0,
+                                                                                                                  255)
+        end
+
+        new("##{red.to_s(16).rjust(2, "0")}#{green.to_s(16).rjust(2, "0")}#{blue.to_s(16).rjust(2, "0")}")
+      end
+
+      def to_s = @hex
+      def to_str = @hex
+      def ==(other) = other.is_a?(Color) && other.hex == @hex
+      alias eql? ==
+      def hash = @hex.hash
+    end
+  end
+
+  Color = Management::Color
+  EnvironmentClassification = Management::EnvironmentClassification
+end

data/lib/smplkit/metrics.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Smplkit
+  # Periodically flushes accumulated SDK telemetry to the platform.
+  #
+  # Aggregation runs on a daemon thread. Public methods are thread-safe and
+  # block briefly only to enqueue metrics.
+  #
+  # When +telemetry+ is disabled in resolved config, +Smplkit::Client+ does
+  # not construct a +MetricsReporter+ and the +metrics+ accessor on
+  # sub-clients is +nil+. Sub-clients guard every call with +metrics&.+.
+  class MetricsReporter
+    DEFAULT_FLUSH_INTERVAL = 60.0
+
+    def initialize(http_client:, environment:, service:, flush_interval: DEFAULT_FLUSH_INTERVAL)
+      @http_client = http_client
+      @environment = environment
+      @service = service
+      @flush_interval = flush_interval
+      @counts = {}
+      @gauges = {}
+      @closed = Concurrent::AtomicBoolean.new(false)
+      @lock = Mutex.new
+      schedule_flush
+    end
+
+    def record(metric, unit:, dimensions: nil)
+      return if @closed.true?
+
+      key = [metric, unit, dimensions || {}].freeze
+      @lock.synchronize { @counts[key] = (@counts[key] || 0) + 1 }
+    end
+
+    def record_gauge(metric, value, unit:, dimensions: nil)
+      return if @closed.true?
+
+      key = [metric, unit, dimensions || {}].freeze
+      @lock.synchronize { @gauges[key] = value }
+    end
+
+    def flush
+      counts_snap, gauges_snap = @lock.synchronize do
+        c = @counts.dup
+        g = @gauges.dup
+        @counts.clear
+        @gauges.clear
+        [c, g]
+      end
+      send_payload(counts_snap, gauges_snap) unless counts_snap.empty? && gauges_snap.empty?
+    rescue StandardError => e
+      Smplkit.debug("metrics", "flush failed: #{e.class}: #{e.message}")
+    end
+
+    def close
+      return if @closed.true?
+
+      @closed.make_true
+      @timer&.shutdown
+      flush
+    end
+
+    private
+
+    def schedule_flush
+      @timer = Concurrent::TimerTask.new(execution_interval: @flush_interval) { flush }
+      @timer.execute
+    end
+
+    def send_payload(_counts, _gauges)
+      # Telemetry payload submission is a no-op stub in the initial Ruby SDK
+      # release. The Python SDK posts to /api/metrics/v1; this hook is here so
+      # the same wiring can be filled in once the generated client surface is
+      # finalized.
+    end
+  end
+end

data/lib/smplkit/railtie.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Smplkit
+  # Rails integration for the smplkit gem.
+  #
+  # The Railtie is loaded only when +Rails::Railtie+ is defined, so non-Rails
+  # customers pay zero load cost.
+  #
+  # Customers configure smplkit through +config.smplkit.*+ in
+  # +config/initializers/smplkit.rb+, generated by
+  # +rails generate smplkit:install+.
+  class Railtie < ::Rails::Railtie
+    config.smplkit = ActiveSupport::OrderedOptions.new
+
+    initializer "smplkit.configure" do |app|
+      Smplkit.configure_for_rails(app.config.smplkit)
+    end
+
+    generators do
+      require_relative "generators/install_generator"
+    end
+  end
+
+  module_function
+
+  # Construct the global +Smplkit.client+ from a Rails-friendly options
+  # struct. Falls back to +SMPLKIT_*+ env vars + +~/.smplkit+ resolution
+  # for any field the customer left blank.
+  def configure_for_rails(options)
+    client = Client.new(
+      api_key: options.api_key,
+      environment: options.environment || (defined?(::Rails) ? ::Rails.env : nil),
+      service: options.service,
+      profile: options.profile,
+      base_domain: options.base_domain,
+      scheme: options.scheme,
+      debug: options.debug,
+      telemetry: options.telemetry
+    )
+    @client = client
+    @context_provider = options.context_provider
+    client
+  end
+
+  class << self
+    attr_accessor :client, :context_provider
+  end
+end

data/lib/smplkit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Smplkit
+  VERSION = "0.0.0"
+end

data/lib/smplkit/ws.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Smplkit
+  # Manages a single WebSocket connection to the app service event gateway.
+  #
+  # A single +SharedWebSocket+ instance is shared across all product modules
+  # (config, flags) within one +Smplkit::Client+. Product modules register
+  # listeners for specific event types; the shared connection dispatches
+  # incoming events to the appropriate listeners.
+  #
+  # The connection runs on a dedicated SDK-owned thread; public methods are
+  # thread-safe and non-blocking.
+  #
+  # The app service gateway protocol:
+  #   - Connect to +wss://app.<base_domain>/api/ws/v1/events?api_key={key}+
+  #   - Receive +{"type": "connected"}+ on success
+  #   - Receive events: +{"event": "config_changed", ...}+, etc.
+  #   - No subscribe message - the API key determines the account
+  #   - Heartbeat: server sends +"ping"+ (text), client responds with +"pong"+
+  #
+  # NOTE: The actual WebSocket I/O is wired to async-websocket on a worker
+  # thread. The initial Ruby SDK release defers full live-update wiring to a
+  # follow-up because async-websocket interactions need integration testing
+  # against the real platform.
+  class SharedWebSocket
+    BACKOFF_SCHEDULE = [1, 2, 4, 8, 16, 32, 60].freeze
+
+    def initialize(app_base_url:, api_key:, metrics: nil)
+      @app_base_url = app_base_url
+      @api_key = api_key
+      @metrics = metrics
+      @listeners = Concurrent::Hash.new { |h, k| h[k] = [] }
+      @listeners_lock = Mutex.new
+      @connection_status = "disconnected"
+      @closed = false
+    end
+
+    def on(event_name, &callback)
+      @listeners_lock.synchronize { @listeners[event_name] << callback }
+    end
+
+    def off(event_name, callback)
+      @listeners_lock.synchronize { @listeners[event_name].delete(callback) }
+    end
+
+    def dispatch(event_name, data)
+      callbacks = @listeners_lock.synchronize { @listeners[event_name].dup }
+      callbacks.each do |cb|
+        cb.call(data)
+      rescue StandardError => e
+        Smplkit.debug("websocket", "listener for #{event_name} raised: #{e.class}: #{e.message}")
+      end
+    end
+
+    attr_reader :connection_status
+
+    # Marked as connected for in-process testing without a real WS connection.
+    # Production wiring overrides this from the I/O thread once the gateway
+    # confirms the handshake.
+    def mark_connected!
+      @connection_status = "connected"
+    end
+
+    def start
+      Smplkit.debug("websocket", "starting shared WebSocket (Ruby SDK initial release: in-memory only)")
+      # Live wiring is deferred. Behave as if the handshake succeeded so the
+      # rest of the runtime can proceed - listeners still fire for any events
+      # other code dispatches into this instance.
+      mark_connected!
+    end
+
+    def stop
+      @closed = true
+      @connection_status = "disconnected"
+    end
+
+    def build_ws_url
+      url = @app_base_url.dup
+      ws_url = if url.start_with?("https://")
+                 "wss://#{url[("https://".length)..]}"
+               elsif url.start_with?("http://")
+                 "ws://#{url[("http://".length)..]}"
+               else
+                 "wss://#{url}"
+               end
+      ws_url = ws_url.chomp("/")
+      "#{ws_url}/api/ws/v1/events?api_key=#{@api_key}"
+    end
+  end
+end

data/lib/smplkit.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Official Ruby SDK for the smplkit platform.
+#
+#   require "smplkit"
+#
+#   client = Smplkit::Client.new(environment: "production", service: "my-svc")
+#   flag = client.flags.boolean_flag("checkout-v2", default: false)
+#   flag.get
+module Smplkit
+end
+
+require_relative "smplkit/version"
+require_relative "smplkit/errors"
+require_relative "smplkit/debug"
+require_relative "smplkit/helpers"
+require_relative "smplkit/log_level"
+require_relative "smplkit/context"
+require_relative "smplkit/config_resolution"
+require_relative "smplkit/metrics"
+require_relative "smplkit/ws"
+require_relative "smplkit/flags/types"
+require_relative "smplkit/flags/models"
+require_relative "smplkit/flags/helpers"
+require_relative "smplkit/flags/client"
+require_relative "smplkit/config/models"
+require_relative "smplkit/config/helpers"
+require_relative "smplkit/config/client"
+require_relative "smplkit/logging/levels"
+require_relative "smplkit/logging/normalize"
+require_relative "smplkit/logging/sources"
+require_relative "smplkit/logging/models"
+require_relative "smplkit/logging/helpers"
+require_relative "smplkit/logging/adapters/base"
+require_relative "smplkit/logging/adapters/stdlib_logger_adapter"
+require_relative "smplkit/logging/client"
+require_relative "smplkit/management/types"
+require_relative "smplkit/management/models"
+require_relative "smplkit/management/buffer"
+require_relative "smplkit/management/client"
+require_relative "smplkit/client"
+
+require_relative "smplkit/railtie" if defined?(Rails::Railtie)

data/sig/smplkit.rbs

@@ -0,0 +1,141 @@
+# Top-level RBS signatures for the smplkit Ruby SDK.
+#
+# Per ADR-046 §2.8, sigs ship alongside the gem in +sig/+ for IDE/LSP
+# autocompletion and Steep type-checking. Per-class sigs that go beyond
+# the public surface declared here are deferred — see ISSUES.md.
+
+module Smplkit
+  VERSION: String
+
+  def self.debug: (String, String) -> void
+  def self.enable_debug: () -> void
+  def self.set_request_context: (Array[Context]) -> ContextScope
+  def self.request_context: () -> Array[Context]
+  def self.configure_for_rails: (untyped) -> Client
+
+  class Client
+    def self.open: (**untyped) { (Client) -> void } -> void
+    def initialize: (?api_key: String?, ?environment: String?, ?service: String?,
+                     ?profile: String?, ?base_domain: String?, ?scheme: String?,
+                     ?debug: bool?, ?telemetry: bool?) -> void
+    def manage: () -> ManagementClient
+    def config: () -> Config::ConfigClient
+    def flags: () -> Flags::FlagsClient
+    def logging: () -> Logging::LoggingClient
+    def wait_until_ready: (?timeout: Float) -> void
+    def set_context: (Array[Context]) ?{ (ContextScope) -> void } -> ContextScope?
+    def close: () -> void
+  end
+
+  class ManagementClient
+    def initialize: (?api_key: String?, ?base_domain: String?, ?scheme: String?,
+                     ?profile: String?, ?debug: bool?) -> void
+    def contexts: () -> ManagementClient::ContextsNamespace
+    def context_types: () -> ManagementClient::ContextTypesNamespace
+    def environments: () -> ManagementClient::EnvironmentsNamespace
+    def account_settings: () -> ManagementClient::AccountSettingsNamespace
+    def config: () -> ManagementClient::ConfigNamespace
+    def flags: () -> ManagementClient::FlagsNamespace
+    def loggers: () -> ManagementClient::LoggersNamespace
+    def log_groups: () -> ManagementClient::LogGroupsNamespace
+    def close: () -> void
+  end
+
+  class Context
+    attr_reader type: String
+    attr_reader key: String
+    attr_reader attributes: Hash[String, untyped]
+    attr_accessor name: String?
+    def initialize: (String, String, ?Hash[String | Symbol, untyped]?,
+                     ?name: String?, **untyped) -> void
+    def id: () -> String
+    def save: () -> Context
+    alias save! save
+    def delete: () -> void
+    alias delete! delete
+  end
+
+  class ContextScope
+    def call: () { (ContextScope) -> void } -> void
+    def exit: () -> void
+  end
+
+  module Op
+    EQ: String
+    NEQ: String
+    LT: String
+    LTE: String
+    GT: String
+    GTE: String
+    IN: String
+    CONTAINS: String
+    ALL: Array[String]
+  end
+
+  class Rule
+    def initialize: (String, environment: String) -> void
+    def when: (*untyped) -> Rule
+    def serve: (untyped) -> Hash[String, untyped]
+  end
+
+  class FlagDeclaration
+    attr_reader id: String
+    attr_reader type: String
+    attr_reader default: untyped
+    attr_reader service: String?
+    attr_reader environment: String?
+    def initialize: (id: String, type: String, default: untyped,
+                     ?service: String?, ?environment: String?) -> void
+  end
+
+  class LogLevel
+    include Comparable
+    attr_reader name: String
+    attr_reader ordinal: Integer
+
+    TRACE: LogLevel
+    DEBUG: LogLevel
+    INFO: LogLevel
+    WARN: LogLevel
+    ERROR: LogLevel
+    FATAL: LogLevel
+    SILENT: LogLevel
+    ALL: Array[LogLevel]
+    NAMES: Array[String]
+
+    def self.from_string: (String | Symbol) -> LogLevel
+    def self.coerce: (LogLevel | String) -> LogLevel
+  end
+
+  class Error < StandardError
+    attr_reader errors: Array[ApiErrorDetail]
+    attr_reader status_code: Integer?
+    def initialize: (?String?, ?errors: Array[ApiErrorDetail]?, ?status_code: Integer?) -> void
+  end
+
+  class ConnectionError < Error
+  end
+
+  class TimeoutError < Error
+  end
+
+  class NotFoundError < Error
+  end
+
+  class ConflictError < Error
+  end
+
+  class ValidationError < Error
+  end
+
+  class ApiErrorDetail
+    attr_reader status: String?
+    attr_reader title: String?
+    attr_reader detail: String?
+    attr_reader source: Hash[untyped, untyped]
+    def initialize: (?status: String?, ?title: String?, ?detail: String?,
+                     ?source: Hash[untyped, untyped]?) -> void
+    def to_h: () -> Hash[String, untyped]
+    def to_json: (*untyped) -> String
+  end
+end