togul 2.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 75fde010ac0c727c425c169bff582437c313ddc71a06e6bd285cd3271848afde
+  data.tar.gz: 3fcf4a81648a4c4bf52538026fa17ef7ac4fda0e5bc2c34bc9caa74bad029a8a
+SHA512:
+  metadata.gz: b13234a1b51798a399e6cb7e9a80274c2ef26db810df4d0f609329c097cf90cd71bddd2a6b11d00dd1b565efc43f6ff75b2f99bd8c5105c4917735dd0ac860e3
+  data.tar.gz: 1723699c586897d12cb4b29a2c8f8bbfd9563daea8ad6e1c598c035eb2efd7cead5d2fd3e823ca7ad97ea416a830100eff7287a149fdaffa26eac79e3ee8f306

data/lib/togul/cache.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Togul
+  class Cache
+    def initialize(ttl:)
+      @ttl = ttl
+      @store = {}
+      @mutex = Mutex.new
+    end
+
+    # @return [EvaluateResult, nil] cached result or nil on miss/expiry/stale
+    def get(key)
+      @mutex.synchronize do
+        entry = @store[key]
+        return nil unless entry
+        return nil if Time.now.to_f > entry[:expires_at]
+
+        result = entry[:value]
+        # Treat entries with blank value_type as stale (legacy/invalid format).
+        return nil if result.value_type.to_s.empty?
+
+        result
+      end
+    end
+
+    def set(key, result)
+      @mutex.synchronize do
+        @store[key] = {
+          value:      result,
+          expires_at: Time.now.to_f + @ttl
+        }
+      end
+    end
+
+    def flush
+      @mutex.synchronize { @store.clear }
+    end
+
+    def invalidate_flag(flag_key)
+      prefix = "#{flag_key}:"
+      @mutex.synchronize do
+        @store.delete_if { |key, _| key.start_with?(prefix) }
+      end
+    end
+  end
+end

data/lib/togul/client.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Togul
+  class Client
+    # @param config [Togul::Config]
+    def initialize(config)
+      @config = config
+      @cache = Cache.new(ttl: config.cache_ttl)
+      @stream_client = nil
+    end
+
+    # Evaluate a feature flag.
+    #
+    # @param key [String] Flag key
+    # @param context [Hash<String, String>] User/request context
+    # @return [Boolean] Whether the flag is enabled
+    def enabled?(key, context = {})
+      evaluate_result(key, context).enabled?
+    rescue StandardError
+      case @config.fallback_mode
+      when :fail_open then true
+      else false
+      end
+    end
+
+    # Evaluate a feature flag and return the full result with typed value accessors.
+    #
+    # @param key [String] Flag key
+    # @param context [Hash<String, String>] User/request context
+    # @return [Togul::EvaluateResult]
+    def evaluate_result(key, context = {})
+      cache_key = build_cache_key(key, context)
+
+      cached = @cache.get(cache_key)
+      return cached unless cached.nil?
+
+      result = evaluate(key, context)
+      @cache.set(cache_key, result)
+      result
+    end
+
+    # Evaluate a boolean flag.
+    #
+    # @param key [String] Flag key
+    # @param context [Hash<String, String>] User/request context
+    # @param fallback [Boolean] Value to return on error or type mismatch
+    # @return [Boolean]
+    def evaluate_bool(key, context = {}, fallback: false)
+      evaluate_result(key, context).bool_value(fallback)
+    rescue StandardError
+      fallback
+    end
+
+    # Evaluate a string flag.
+    #
+    # @param key [String] Flag key
+    # @param context [Hash<String, String>] User/request context
+    # @param fallback [String] Value to return on error or type mismatch
+    # @return [String]
+    def evaluate_string(key, context = {}, fallback: '')
+      evaluate_result(key, context).string_value(fallback)
+    rescue StandardError
+      fallback
+    end
+
+    # Evaluate a number flag.
+    #
+    # @param key [String] Flag key
+    # @param context [Hash<String, String>] User/request context
+    # @param fallback [Float] Value to return on error or type mismatch
+    # @return [Float]
+    def evaluate_number(key, context = {}, fallback: 0.0)
+      evaluate_result(key, context).number_value(fallback)
+    rescue StandardError
+      fallback
+    end
+
+    # Evaluate a JSON flag.
+    #
+    # @param key [String] Flag key
+    # @param context [Hash<String, String>] User/request context
+    # @param fallback [Object] Value to return on error or type mismatch
+    # @return [Object]
+    def evaluate_json(key, context = {}, fallback: nil)
+      evaluate_result(key, context).json_value(fallback)
+    rescue StandardError
+      fallback
+    end
+
+    # Clear all cached flag values.
+    def invalidate_cache
+      @cache.flush
+    end
+
+    # Clear a specific flag from cache.
+    def invalidate_flag(key)
+      @cache.invalidate_flag(key)
+    end
+
+    # Start SSE stream for real-time cache invalidation.
+    def stream
+      @stream_client ||= StreamClient.new(@config, @cache)
+    end
+
+    # Register a listener for cache invalidation events.
+    def on_cache_invalidated(&block)
+      stream.on_cache_invalidated(&block)
+    end
+
+    private
+
+    def evaluate(key, context)
+      raise Error.new('API key is required') if @config.api_key.empty?
+
+      last_error = nil
+
+      @config.retry_count.times do |attempt|
+        sleep(attempt * 0.1) if attempt > 0
+
+        begin
+          uri = URI("#{@config.base_url}/api/v1/evaluate")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == 'https'
+          http.open_timeout = @config.timeout
+          http.read_timeout = @config.timeout
+
+          request = Net::HTTP::Post.new(uri.path)
+          request['Content-Type'] = 'application/json'
+          request['X-API-Key'] = @config.api_key
+
+          request.body = JSON.generate({
+                                         flag_key: key,
+                                         environment_key: @config.environment,
+                                         context: context
+                                       })
+
+          response = http.request(request)
+
+          unless response.is_a?(Net::HTTPSuccess)
+            last_error = build_api_error(response)
+            raise last_error unless should_retry?(response.code.to_i)
+
+            next
+          end
+
+          body = JSON.parse(response.body)
+          return EvaluateResult.new(
+            flag_key:   body['flag_key'] || key,
+            enabled:    body['enabled'] == true,
+            value_type: body['value_type'].to_s,
+            raw_value:  body['value'],
+            reason:     body['reason'].to_s
+          )
+        rescue Error
+          raise
+        rescue StandardError => e
+          last_error = e
+        end
+      end
+
+      raise Error.new("all retries failed: #{last_error}")
+    end
+
+    def build_cache_key(key, context)
+      serialized_context = context.sort.map { |context_key, value| "#{context_key}=#{value}" }
+      ([key, @config.environment] + serialized_context).join(':')
+    end
+
+    def should_retry?(status_code)
+      status_code == 429 || status_code >= 500
+    end
+
+    def build_api_error(response)
+      body = {}
+      body = JSON.parse(response.body) unless response.body.to_s.empty?
+
+      Error.new(
+        body['message'] || "unexpected status #{response.code}",
+        status_code: response.code.to_i,
+        error_code: body['code']
+      )
+    end
+  end
+end

data/lib/togul/config.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Togul
+  class Config
+    DEFAULT_BASE_URL = 'https://api.togul.io'
+
+    attr_reader :api_key, :environment, :timeout, :cache_ttl, :fallback_mode, :retry_count, :base_url
+
+    # @param environment [String] Environment key (e.g. "production")
+    # @param api_key [String] Environment API key for evaluate/stream requests
+    # @param timeout [Numeric] HTTP timeout in seconds
+    # @param cache_ttl [Integer] Cache TTL in seconds
+    # @param fallback_mode [Symbol] :fail_closed or :fail_open
+    # @param retry_count [Integer] Number of retry attempts
+    # @param base_url [String, nil] Override default base URL (optional)
+    def initialize(
+      environment:,
+      api_key: '',
+      timeout: 5,
+      cache_ttl: 30,
+      fallback_mode: :fail_closed,
+      retry_count: 2,
+      base_url: nil
+    )
+      @base_url = base_url&.chomp('/') || DEFAULT_BASE_URL
+      @api_key = api_key
+      @environment = environment
+      @timeout = timeout
+      @cache_ttl = cache_ttl
+      @fallback_mode = fallback_mode
+      @retry_count = retry_count
+    end
+  end
+end

data/lib/togul/error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Togul
+  class Error < StandardError
+    attr_reader :status_code, :error_code
+
+    def initialize(message = nil, status_code: nil, error_code: nil)
+      super(message)
+      @status_code = status_code
+      @error_code = error_code
+    end
+  end
+end

data/lib/togul/evaluate_result.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Togul
+  class EvaluateResult
+    attr_reader :flag_key, :enabled, :value_type, :reason
+
+    def initialize(flag_key:, enabled:, value_type:, raw_value:, reason:)
+      @flag_key   = flag_key
+      @enabled    = enabled
+      @value_type = value_type
+      @raw_value  = raw_value
+      @reason     = reason
+    end
+
+    def enabled?
+      @enabled == true
+    end
+
+    def bool_value(fallback = false)
+      return fallback unless enabled? && @value_type == 'boolean'
+      return fallback unless @raw_value == true || @raw_value == false
+
+      @raw_value
+    end
+
+    def string_value(fallback = '')
+      return fallback unless enabled? && @value_type == 'string'
+      return fallback unless @raw_value.is_a?(String)
+
+      @raw_value
+    end
+
+    def number_value(fallback = 0.0)
+      return fallback unless enabled? && @value_type == 'number'
+      return fallback unless @raw_value.is_a?(Numeric)
+
+      @raw_value.to_f
+    end
+
+    def json_value(fallback = nil)
+      return fallback unless enabled? && @value_type == 'json'
+
+      @raw_value.nil? ? fallback : @raw_value
+    end
+  end
+end

data/lib/togul/stream_client.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Togul
+  class StreamClient
+    def initialize(config, cache)
+      @config = config
+      @cache = cache
+      @listeners = []
+    end
+
+    def connect
+      backoff = 1
+
+      loop do
+        stream_once
+      rescue Error => e
+        raise if [401, 403].include?(e.status_code)
+
+        sleep(backoff)
+        backoff = [backoff * 2, 30].min
+      end
+    end
+
+    def on_cache_invalidated(&block)
+      @listeners << block
+    end
+
+    private
+
+    def stream_once
+      raise Error.new('API key is required') if @config.api_key.empty?
+
+      uri = URI("#{@config.base_url}/api/v1/stream")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+
+      request = Net::HTTP::Get.new(uri.path)
+      request['Accept'] = 'text/event-stream'
+      request['X-API-Key'] = @config.api_key
+
+      response = http.request(request)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Error.new("stream failed: #{response.code}", status_code: response.code.to_i)
+      end
+
+      response.read_body do |chunk|
+        parse_sse(chunk)
+      end
+    end
+
+    def parse_sse(buffer)
+      buffer.each_line do |line|
+        next unless line.start_with?('data: ')
+
+        data = line[6..].strip
+        event = JSON.parse(data)
+        handle_event(event)
+      end
+    end
+
+    def handle_event(event)
+      flag_key = event['flag_key'] || ''
+
+      if flag_key != ''
+        @cache.invalidate_flag(flag_key)
+        notify_listeners(flag_key)
+      else
+        @cache.flush
+        notify_listeners('')
+      end
+    end
+
+    def notify_listeners(flag_key)
+      @listeners.each { |listener| listener.call(flag_key) }
+    end
+  end
+end

data/lib/togul.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "togul/config"
+require_relative "togul/cache"
+require_relative "togul/error"
+require_relative "togul/evaluate_result"
+require_relative "togul/client"

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: togul
+version: !ruby/object:Gem::Version
+  version: 2.4.0
+platform: ruby
+authors:
+- Togul
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Client library for evaluating feature flags from a Togul server with
+  TTL caching, retry, and fallback support.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/togul.rb
+- lib/togul/cache.rb
+- lib/togul/client.rb
+- lib/togul/config.rb
+- lib/togul/error.rb
+- lib/togul/evaluate_result.rb
+- lib/togul/stream_client.rb
+homepage: https://github.com/togulapp/togul-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/togulapp/togul-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.10
+signing_key:
+specification_version: 4
+summary: Ruby SDK for Togul Feature Flag Service
+test_files: []