togul-flags 2.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e894def387719430bcc555e33a1a557578d4847fc8d93014a0062dd1cc759d0
+  data.tar.gz: 5167ffb027245c1854b7d3b43e24df401161468486eccd44f20644802873ced5
+SHA512:
+  metadata.gz: 174d9e6926d47e5d2b59e99ce490abe9e1d249f76010be2d6e18232ddd4f17b3c92e5963b9daf1fcfeaaa38d06a574c07cd1aa8944a70cfbdea4520ac9f45fc8
+  data.tar.gz: 125ff020c7bd0d185589f34168292ccae2697b8092e9bb4a53301c30687e0243c0a315c6b76c43d7616661f371d2e66492578184c17ff8c024d27fde12b8c7ac

data/lib/togul/cache.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Togul
+  class Cache
+    def initialize(ttl:)
+      @ttl = ttl
+      @store = {}
+      @mutex = Mutex.new
+    end
+
+    # @return [Boolean, nil] cached value or nil on miss/expiry
+    def get(key)
+      @mutex.synchronize do
+        entry = @store[key]
+        return nil unless entry
+        return nil if Time.now.to_f > entry[:expires_at]
+
+        entry[:value]
+      end
+    end
+
+    def set(key, value)
+      @mutex.synchronize do
+        @store[key] = {
+          value: value,
+          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,125 @@
+# 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 = {})
+      cache_key = build_cache_key(key, context)
+
+      cached = @cache.get(cache_key)
+      return cached unless cached.nil?
+
+      value = evaluate(key, context)
+      @cache.set(cache_key, value)
+      value
+    rescue StandardError
+      case @config.fallback_mode
+      when :fail_open then true
+      else false
+      end
+    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 body['value'] == true
+        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/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,6 @@
+# frozen_string_literal: true
+
+require_relative "togul/config"
+require_relative "togul/cache"
+require_relative "togul/error"
+require_relative "togul/client"

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: togul-flags
+version: !ruby/object:Gem::Version
+  version: 2.3.0
+platform: ruby
+authors:
+- Togul
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-14 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/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: []