flipt_client 0.17.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6a5b035934ec3f271e01238a872154920c919c5561b41a98e9b5b853e0bbf90
-  data.tar.gz: 4cb2d36b85215238a791f283426b6e667adbfbb6e9d00d19d42ecaf209eda25a
+  metadata.gz: 02ba6911dc6076bbc0703d4c08a242ba24bb75ce82ce2fbce36822b51981c50e
+  data.tar.gz: fd4810c100d71063d4f61d8c4d752f07b616ac6f6d7ce4b31446d4360b766682
 SHA512:
-  metadata.gz: 65b002cca3c2b89c9588d36b62c13aa9c7ac07396efd207d67b7dea2b588847ad5946febcf4ac0b82180a2e0725030c6bf4ede11e29f3c49e180d2ce1b7956eb
-  data.tar.gz: 1987dd10cc71446fb3bdebc79637eaa9fee0cb4af66febe7afc7b5ad6f8bf619920c14f3c607f8535f54a7ff4e8ca356dd9d4b277e2af524e6de1bf0ee3c3a52
+  metadata.gz: bb5e9dce20daa6f5bb0998a5b0a99635c23ac5d9d8ac76eb111bc7e87de4d9d730754bf9c3cc4be5f89f788c596c254153d0f31bf2137d28d086bc38516bfcd2
+  data.tar.gz: 569fbc3bf3dd29205881aaab465592891f37dbcd3112f12f54dc4e9ac6977c4e111fda0ac1e77474af0f879fc36bcc1ff4f98aaddd5a7ad07e1c4df2641f06b6

data/README.md

@@ -26,9 +26,9 @@ Upon instantiation, the `flipt-client-ruby` library will fetch the flag state fr
 
 By default, the SDK will poll the Flipt server for new flag state at a regular interval. This interval can be configured using the `update_interval` option when constructing a client. The default interval is 120 seconds.
 
-### Streaming (Flipt Cloud Only)
+### Streaming (Flipt Cloud/Flipt v2)
 
-[Flipt Cloud](https://flipt.io/cloud) users can use the `streaming` fetch method to stream flag state changes from the Flipt server to the SDK.
+[Flipt Cloud](https://flipt.io/cloud) and [Flipt v2](https://docs.flipt.io/v2) users can use the `streaming` fetch method to stream flag state changes from the Flipt server to the SDK.
 
 When in streaming mode, the SDK will connect to the Flipt server and open a persistent connection that will remain open until the client is closed. The SDK will then receive flag state changes in real-time.
 
@@ -67,6 +67,21 @@ gem install ffi -- --enable-system-libffi        # to install the gem manually
 bundle config build.ffi --enable-system-libffi   # for bundle install
 ```
 
+## Migration Notes
+
+### Pre-1.0.0 -> 1.0.0
+
+This section is for users who are migrating from a previous (pre-1.0.0) version of the SDK.
+
+- `Flipt::EvaluationClient` has been renamed to `Flipt::Client`. Update all usages and imports accordingly. A deprecation warning is emitted if you use the old class.
+- All evaluation methods now use **keyword arguments** (e.g., `flag_key:`, `entity_id:`, `context:`) instead of a single hash argument. Update your method calls to use keyword arguments.
+- All evaluation methods now return **response model objects** (`VariantEvaluationResponse`, `BooleanEvaluationResponse`, `BatchEvaluationResponse`, `ErrorEvaluationResponse`) instead of raw hashes. Update your code to use attribute readers (e.g., `resp.flag_key`, `resp.enabled`).
+- Batch evaluation responses now contain an array of model objects, not hashes.
+- Error handling is now standardized and idiomatic. All errors inherit from `Flipt::Error` (with subclasses like `ValidationError`, `EvaluationError`). Update your rescue blocks accordingly.
+- The minimum supported Ruby version is now 2.7.0.
+- The client constructor now accepts keyword arguments for configuration (e.g., `url:`, `namespace:`, `authentication:`). The `environment` option is now supported.
+- The API and documentation are more idiomatic and Ruby-like throughout.
+
 ## Usage
 
 In your Ruby code you can import this client and use it as so:
@@ -74,46 +89,143 @@ In your Ruby code you can import this client and use it as so:
 ```ruby
 require 'flipt_client'
 
-# namespace is the first positional argument and is optional here and will have a value of "default" if not specified.
-# opts is the second positional argument and is also optional, the structure is:
-# {
-#   "url": "http://localhost:8080",
-#   "update_interval": 120,
-#   "authentication": {
-#     "client_token": "secret"
-#   }
-# }
-#
-# You can replace the url with where your upstream Flipt instance points to, the update interval for how long you are willing
-# to wait for updated flag state, and the auth token if your Flipt instance requires it.
-client = Flipt::EvaluationClient.new()
-resp = client.evaluate_variant({ flag_key: 'buzz', entity_id: 'someentity', context: { fizz: 'buzz' } })
-
-puts resp
+client = Flipt::Client.new(url: 'http://localhost:8080', authentication: Flipt::ClientTokenAuthentication.new('secret'))
+
+resp = client.evaluate_variant(flag_key: 'buzz', entity_id: 'someentity', context: { fizz: 'buzz' })
+puts resp.flag_key # => 'buzz'
+puts resp.match # => true
+puts resp.reason # => 'MATCH_EVALUATION_REASON'
+
+resp = client.evaluate_boolean(flag_key: 'my-feature', entity_id: 'someentity')
+puts resp.enabled # => true
 ```
 
 ### Constructor Arguments
 
-The `Flipt::EvaluationClient` constructor accepts two optional arguments:
+The `Flipt::Client` constructor accepts the following keyword arguments:
 
+- `environment`: The environment (Flipt v2) to fetch flag state from. If not provided, the client will default to the `default` environment.
 - `namespace`: The namespace to fetch flag state from. If not provided, the client will default to the `default` namespace.
-- `opts`: A hash that supports several options for the client. The structure is:
-  - `url`: The URL of the upstream Flipt instance. If not provided, the client will default to `http://localhost:8080`.
-  - `request_timeout`: The timeout (in seconds) for total request time to the upstream Flipt instance. If not provided, the client will default to no timeout. Note: this only affects polling mode. Streaming mode will have no timeout set.
-  - `update_interval`: The interval (in seconds) in which to fetch new flag state. If not provided, the client will default to 120 seconds.
-  - `authentication`: The authentication strategy to use when communicating with the upstream Flipt instance. If not provided, the client will default to no authentication. See the [Authentication](#authentication) section for more information.
-  - `reference`: The [reference](https://docs.flipt.io/guides/user/using-references) to use when fetching flag state. If not provided, reference will not be used.
-  - `fetch_mode`: The fetch mode to use when fetching flag state. If not provided, the client will default to polling.
-  - `error_strategy`: The error strategy to use when fetching flag state. If not provide, the client will be default to fail. See the [Error Strategies](#error-strategies) section for more information.
+- `url`: The URL of the upstream Flipt instance. Defaults to `http://localhost:8080`.
+- `request_timeout`: Timeout (in seconds) for requests. Defaults to no timeout.
+- `update_interval`: Interval (in seconds) to fetch new flag state. Defaults to 120 seconds.
+- `authentication`: The authentication strategy to use. Defaults to no authentication. See [Authentication](#authentication).
+- `reference`: The [reference](https://docs.flipt.io/guides/user/using-references) to use when fetching flag state.
+- `fetch_mode`: The fetch mode to use. Defaults to polling.
+- `error_strategy`: The error strategy to use. Defaults to fail. See [Error Strategies](#error-strategies).
+- `snapshot`: The snapshot to use when initializing the client. Defaults to no snapshot. See [Snapshotting](#snapshotting).
+- `tls_config`: The TLS configuration for connecting to servers with custom certificates. See [TLS Configuration](#tls-configuration).
 
 ### Authentication
 
-The `FliptEvaluationClient` supports the following authentication strategies:
+The `Flipt::Client` supports the following authentication strategies:
 
 - No Authentication (default)
 - [Client Token Authentication](https://docs.flipt.io/authentication/using-tokens)
 - [JWT Authentication](https://docs.flipt.io/authentication/using-jwts)
 
+### TLS Configuration
+
+The `Flipt::Client` supports configuring TLS settings for secure connections to Flipt servers. This is useful when:
+
+- Connecting to Flipt servers with self-signed certificates
+- Using custom Certificate Authorities (CAs)  
+- Implementing mutual TLS authentication
+- Testing with insecure connections (development only)
+
+#### Basic TLS with Custom CA Certificate
+
+```ruby
+# Using a CA certificate file
+tls_config = Flipt::TlsConfig.with_ca_cert_file('/path/to/ca.pem')
+
+client = Flipt::Client.new(
+  url: 'https://flipt.example.com',
+  tls_config: tls_config
+)
+```
+
+```ruby
+# Using CA certificate data directly
+ca_cert_data = File.read('/path/to/ca.pem')
+tls_config = Flipt::TlsConfig.with_ca_cert_data(ca_cert_data)
+
+client = Flipt::Client.new(
+  url: 'https://flipt.example.com',
+  tls_config: tls_config
+)
+```
+
+#### Mutual TLS Authentication
+
+```ruby
+# Using certificate and key files
+tls_config = Flipt::TlsConfig.with_mutual_tls('/path/to/client.pem', '/path/to/client.key')
+
+client = Flipt::Client.new(
+  url: 'https://flipt.example.com',
+  tls_config: tls_config
+)
+```
+
+```ruby
+# Using certificate and key data directly
+client_cert_data = File.read('/path/to/client.pem')
+client_key_data = File.read('/path/to/client.key')
+
+tls_config = Flipt::TlsConfig.with_mutual_tls_data(client_cert_data, client_key_data)
+
+client = Flipt::Client.new(
+  url: 'https://flipt.example.com',
+  tls_config: tls_config
+)
+```
+
+#### Advanced TLS Configuration
+
+```ruby
+# Full TLS configuration with all options
+tls_config = Flipt::TlsConfig.new(
+  ca_cert_file: '/path/to/ca.pem',
+  client_cert_file: '/path/to/client.pem',
+  client_key_file: '/path/to/client.key',
+  insecure_skip_verify: false
+)
+
+client = Flipt::Client.new(
+  url: 'https://flipt.example.com',
+  tls_config: tls_config
+)
+```
+
+#### Development Mode (Insecure)
+
+**⚠️ WARNING: Only use this in development environments!**
+
+```ruby
+# Skip certificate verification (NOT for production)
+tls_config = Flipt::TlsConfig.insecure
+
+client = Flipt::Client.new(
+  url: 'https://localhost:8443',
+  tls_config: tls_config
+)
+```
+
+#### TLS Configuration Options
+
+The `TlsConfig` class supports the following options:
+
+- `ca_cert_file`: Path to custom CA certificate file (PEM format)
+- `ca_cert_data`: Raw CA certificate content (PEM format) - takes precedence over `ca_cert_file`
+- `insecure_skip_verify`: Skip certificate verification (development only)
+- `client_cert_file`: Client certificate file for mutual TLS (PEM format)
+- `client_key_file`: Client private key file for mutual TLS (PEM format)
+- `client_cert_data`: Raw client certificate content (PEM format) - takes precedence over `client_cert_file`
+- `client_key_data`: Raw client private key content (PEM format) - takes precedence over `client_key_file`
+
+> **Note**: When both file paths and data are provided, the data fields take precedence. For example, if both `ca_cert_file` and `ca_cert_data` are set, `ca_cert_data` will be used.
+
 ### Error Strategies
 
 The client supports the following error strategies:
@@ -121,6 +233,46 @@ The client supports the following error strategies:
 - `fail`: The client will throw an error if the flag state cannot be fetched. This is the default behavior.
 - `fallback`: The client will maintain the last known good state and use that state for evaluation in case of an error.
 
+### Response Models
+
+All evaluation methods return response model objects:
+
+- `evaluate_variant` returns a `Flipt::VariantEvaluationResponse`
+- `evaluate_boolean` returns a `Flipt::BooleanEvaluationResponse`
+- `evaluate_batch` returns a `Flipt::BatchEvaluationResponse`
+
+### Error Handling
+
+All errors inherit from `Flipt::Error`. Common subclasses include:
+
+- `Flipt::ValidationError`
+- `Flipt::EvaluationError`
+
+You can rescue these errors as needed:
+
+```ruby
+begin
+  client.evaluate_variant(flag_key: 'missing', entity_id: 'user')
+rescue Flipt::EvaluationError => e
+  puts "Evaluation failed: #{e.message}"
+end
+```
+
+### Snapshotting
+
+The client supports snapshotting of flag state as well as seeding the client with a snapshot for evaluation. This is helpful if you want to use the client in an environment where the Flipt server is not guaranteed to be available or reachable on startup.
+
+To get the snapshot for the client, you can use the `snapshot` method. This returns a base64 encoded JSON string that represents the flag state for the client.
+
+You can set the snapshot for the client using the `snapshot` option when constructing a client.
+
+**Note:** You most likely will want to also set the `error_strategy` to `fallback` when using snapshots. This will ensure that you wont get an error if the Flipt server is not available or reachable even on the initial fetch.
+
+You also may want to store the snapshot in a local file so that you can use it to seed the client on startup.
+
+> [!IMPORTANT]
+> If the Flipt server becomes reachable after the setting the snapshot, the client will replace the snapshot with the new flag state from the Flipt server.
+
 ## Load Test
 
 1. To run the load test, you'll need to have Flipt running locally. You can do this by running the following command from the root of the repository:

data/flipt-client-ruby.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.description   = 'Flipt Client Evaluation SDK'
   spec.homepage      = 'https://www.flipt.io'
   spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')
 
   # spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
 

data/lib/ext/flipt_engine.h

@@ -8,7 +8,35 @@
  *
  * This function will initialize an Engine and return a pointer back to the caller.
  */
-void *initialize_engine(const char *namespace_, const char *opts);
+void *initialize_engine_ffi(const char *opts);
+
+/**
+ * # Safety
+ *
+ * This function will initialize an Engine and return a pointer back to the caller.
+ */
+void *initialize_engine(const char *opts);
+
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return the current snapshot as a JSON string.
+ */
+const char *get_snapshot_ffi(void *engine_ptr);
+
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return the current snapshot as a JSON string.
+ */
+const char *get_snapshot(void *engine_ptr);
+
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return a variant evaluation response.
+ */
+const char *evaluate_variant_ffi(void *engine_ptr, const char *evaluation_request);
 
 /**
  * # Safety
@@ -17,6 +45,13 @@ void *initialize_engine(const char *namespace_, const char *opts);
  */
 const char *evaluate_variant(void *engine_ptr, const char *evaluation_request);
 
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return a boolean evaluation response.
+ */
+const char *evaluate_boolean_ffi(void *engine_ptr, const char *evaluation_request);
+
 /**
  * # Safety
  *
@@ -24,6 +59,13 @@ const char *evaluate_variant(void *engine_ptr, const char *evaluation_request);
  */
 const char *evaluate_boolean(void *engine_ptr, const char *evaluation_request);
 
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return a batch evaluation response.
+ */
+const char *evaluate_batch_ffi(void *engine_ptr, const char *batch_evaluation_request);
+
 /**
  * # Safety
  *
@@ -34,30 +76,41 @@ const char *evaluate_batch(void *engine_ptr, const char *batch_evaluation_reques
 /**
  * # Safety
  *
- * This function will take in a pointer to the engine and return a list of flags for the given namespace.
+ * This function will take in a pointer to the engine and return a list of flags.
+ */
+const char *list_flags_ffi(void *engine_ptr);
+
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and return a list of flags.
  */
 const char *list_flags(void *engine_ptr);
 
 /**
  * # Safety
  *
- * This function will free the memory occupied by the engine.
+ * This function will take in a pointer to the engine and destroy it.
+ */
+void destroy_engine_ffi(void *engine_ptr);
+
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to the engine and destroy it.
  */
 void destroy_engine(void *engine_ptr);
 
 /**
  * # Safety
  *
- * This function will take in a pointer to the string and free the memory.
- * See Rust the safety section in CString::from_raw.
+ * This function will take in a pointer to a string and destroy it.
  */
-void destroy_string(char *ptr);
+void destroy_string_ffi(char *ptr);
 
-// Add missing external declarations for Rust functions
-extern void* initialize_engine_ffi(const char* namespace, const char* options);
-extern const char* evaluate_boolean_ffi(void* engine, const char* request);
-extern const char* evaluate_variant_ffi(void* engine, const char* request);
-extern const char* evaluate_batch_ffi(void* engine, const char* request);
-extern const char* list_flags_ffi(void* engine);
-extern void destroy_engine_ffi(void* engine);
-extern void destroy_string_ffi(char* str);
+/**
+ * # Safety
+ *
+ * This function will take in a pointer to a string and destroy it.
+ */
+void destroy_string(char *ptr);

data/lib/flipt_client/models.rb

@@ -40,4 +40,167 @@ module Flipt
       }
     end
   end
+
+  # TlsConfig provides configuration for TLS connections to Flipt servers
+  class TlsConfig
+    attr_reader :ca_cert_file, :ca_cert_data, :insecure_skip_verify,
+                :client_cert_file, :client_key_file, :client_cert_data, :client_key_data
+
+    # Initialize TLS configuration
+    #
+    # @param ca_cert_file [String, nil] Path to CA certificate file (PEM format)
+    # @param ca_cert_data [String, nil] Raw CA certificate content (PEM format)
+    # @param insecure_skip_verify [Boolean, nil] Skip certificate verification (development only)
+    # @param client_cert_file [String, nil] Path to client certificate file (PEM format)
+    # @param client_key_file [String, nil] Path to client key file (PEM format)
+    # @param client_cert_data [String, nil] Raw client certificate content (PEM format)
+    # @param client_key_data [String, nil] Raw client key content (PEM format)
+    def initialize(ca_cert_file: nil, ca_cert_data: nil, insecure_skip_verify: nil,
+                   client_cert_file: nil, client_key_file: nil,
+                   client_cert_data: nil, client_key_data: nil)
+      @ca_cert_file = ca_cert_file
+      @ca_cert_data = ca_cert_data
+      @insecure_skip_verify = insecure_skip_verify
+      @client_cert_file = client_cert_file
+      @client_key_file = client_key_file
+      @client_cert_data = client_cert_data
+      @client_key_data = client_key_data
+
+      validate_files!
+    end
+
+    # Create TLS config for insecure connections (development only)
+    # WARNING: Only use this in development environments
+    #
+    # @return [TlsConfig] TLS config with certificate verification disabled
+    def self.insecure
+      new(insecure_skip_verify: true)
+    end
+
+    # Create TLS config with CA certificate file
+    #
+    # @param ca_cert_file [String] Path to CA certificate file
+    # @return [TlsConfig] TLS config with custom CA certificate
+    def self.with_ca_cert_file(ca_cert_file)
+      new(ca_cert_file: ca_cert_file)
+    end
+
+    # Create TLS config with CA certificate data
+    #
+    # @param ca_cert_data [String] CA certificate content in PEM format
+    # @return [TlsConfig] TLS config with custom CA certificate
+    def self.with_ca_cert_data(ca_cert_data)
+      new(ca_cert_data: ca_cert_data)
+    end
+
+    # Create TLS config for mutual TLS with certificate files
+    #
+    # @param client_cert_file [String] Path to client certificate file
+    # @param client_key_file [String] Path to client key file
+    # @return [TlsConfig] TLS config with mutual TLS
+    def self.with_mutual_tls(client_cert_file, client_key_file)
+      new(client_cert_file: client_cert_file, client_key_file: client_key_file)
+    end
+
+    # Create TLS config for mutual TLS with certificate data
+    #
+    # @param client_cert_data [String] Client certificate content in PEM format
+    # @param client_key_data [String] Client key content in PEM format
+    # @return [TlsConfig] TLS config with mutual TLS
+    def self.with_mutual_tls_data(client_cert_data, client_key_data)
+      new(client_cert_data: client_cert_data, client_key_data: client_key_data)
+    end
+
+    # Convert to hash for JSON serialization
+    # @return [Hash] TLS configuration as hash
+    def to_h
+      hash = {}
+      hash[:ca_cert_file] = @ca_cert_file if @ca_cert_file
+      hash[:ca_cert_data] = @ca_cert_data if @ca_cert_data
+      hash[:insecure_skip_verify] = @insecure_skip_verify unless @insecure_skip_verify.nil?
+      hash[:client_cert_file] = @client_cert_file if @client_cert_file
+      hash[:client_key_file] = @client_key_file if @client_key_file
+      hash[:client_cert_data] = @client_cert_data if @client_cert_data
+      hash[:client_key_data] = @client_key_data if @client_key_data
+      hash
+    end
+
+    private
+
+    def validate_files!
+      validate_file_exists(@ca_cert_file, 'CA certificate file') if @ca_cert_file
+      validate_file_exists(@client_cert_file, 'Client certificate file') if @client_cert_file
+      validate_file_exists(@client_key_file, 'Client key file') if @client_key_file
+    end
+
+    def validate_file_exists(file_path, description)
+      return if file_path.nil? || file_path.strip.empty?
+
+      return if File.exist?(file_path)
+
+      raise ValidationError, "#{description} does not exist: #{file_path}"
+    end
+  end
+
+  # VariantEvaluationResponse
+  # @attr_reader [String] flag_key
+  # @attr_reader [Boolean] match
+  # @attr_reader [String] reason
+  # @attr_reader [String] variant_key
+  # @attr_reader [String, nil] variant_attachment
+  # @attr_reader [Array<String>] segment_keys
+  class VariantEvaluationResponse
+    attr_reader :flag_key, :match, :reason, :variant_key, :variant_attachment, :segment_keys
+
+    def initialize(flag_key:, match:, reason:, variant_key:, variant_attachment: nil, segment_keys: [])
+      @flag_key = flag_key
+      @match = match
+      @reason = reason
+      @variant_key = variant_key
+      @variant_attachment = variant_attachment
+      @segment_keys = segment_keys
+    end
+  end
+
+  # BooleanEvaluationResponse
+  # @attr_reader [String] flag_key
+  # @attr_reader [Boolean] enabled
+  # @attr_reader [String] reason
+  # @attr_reader [Array<String>] segment_keys
+  class BooleanEvaluationResponse
+    attr_reader :flag_key, :enabled, :reason, :segment_keys
+
+    def initialize(flag_key:, enabled:, reason:, segment_keys: [])
+      @flag_key = flag_key
+      @enabled = enabled
+      @reason = reason
+      @segment_keys = segment_keys
+    end
+  end
+
+  # ErrorEvaluationResponse
+  # @attr_reader [String] flag_key
+  # @attr_reader [String] namespace_key
+  # @attr_reader [String] reason
+  # @attr_reader [String] error_message
+  class ErrorEvaluationResponse
+    attr_reader :flag_key, :namespace_key, :reason, :error_message
+
+    def initialize(flag_key:, namespace_key:, reason:, error_message:)
+      @flag_key = flag_key
+      @namespace_key = namespace_key
+      @reason = reason
+      @error_message = error_message
+    end
+  end
+
+  # BatchEvaluationResponse
+  # @attr_reader [Array] responses
+  class BatchEvaluationResponse
+    attr_reader :responses
+
+    def initialize(responses: [])
+      @responses = responses
+    end
+  end
 end

data/lib/flipt_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Flipt
-  VERSION = '0.17.0'
+  VERSION = '1.1.0'
 end

data/lib/flipt_client.rb

@@ -7,9 +7,11 @@ require 'json'
 
 module Flipt
   class Error < StandardError; end
+  class ValidationError < Error; end
+  class EvaluationError < Error; end
 
-  # EvaluationClient is a Ruby Client Side Evaluation Library for Flipt
-  class EvaluationClient
+  # Client is a Ruby Client Side Evaluation Library for Flipt
+  class Client
     extend FFI::Library
 
     FLIPTENGINE = 'fliptengine'
@@ -32,8 +34,8 @@ module Flipt
 
     ffi_lib File.expand_path(libfile, __dir__)
 
-    # void *initialize_engine(const char *namespace, const char *opts);
-    attach_function :initialize_engine, %i[string string], :pointer
+    # void *initialize_engine(const char *opts);
+    attach_function :initialize_engine, [:string], :pointer
     # void destroy_engine(void *engine_ptr);
     attach_function :destroy_engine, [:pointer], :void
     # const char *evaluate_variant(void *engine_ptr, const char *evaluation_request);
@@ -46,27 +48,33 @@ module Flipt
     attach_function :list_flags, [:pointer], :strptr
     # void destroy_string(const char *ptr);
     attach_function :destroy_string, [:pointer], :void
+    # const char *get_snapshot(void *engine_ptr);
+    attach_function :get_snapshot, [:pointer], :strptr
 
     # Create a new Flipt client
     #
-    # @param namespace [String] namespace
     # @param opts [Hash] options
+    # @option opts [String] :environment Flipt environment (default: 'default')
+    # @option opts [String] :namespace Flipt namespace (default: 'default')
     # @option opts [String] :url Flipt server url
     # @option opts [AuthenticationStrategy] :authentication strategy to authenticate with Flipt
     # @option opts [Integer] :request_timeout timeout in seconds for the request
     # @option opts [Integer] :update_interval interval in seconds to update the cache
     # @option opts [String] :reference reference to use for namespace data
     # @option opts [Symbol] :fetch_mode fetch mode to use for the client (:polling or :streaming).
-    #   Note: Streaming is currently only supported when using the SDK with Flipt Cloud (https://flipt.io/cloud).
+    #   Note: Streaming is currently only supported when using the SDK with Flipt Cloud or Flipt v2.
     # @option opts [Symbol] :error_strategy error strategy to use for the client (:fail or :fallback).
-    def initialize(namespace = 'default', opts = {})
-      @namespace = namespace
+    # @option opts [String] :snapshot snapshot to use when initializing the client
+    # @option opts [TlsConfig] :tls_config TLS configuration for connecting to servers with custom certificates
+    def initialize(**opts)
+      @namespace = opts.fetch(:namespace, 'default')
 
       opts[:authentication] = validate_authentication(opts.fetch(:authentication, NoAuthentication.new))
       opts[:fetch_mode] = validate_fetch_mode(opts.fetch(:fetch_mode, :polling))
       opts[:error_strategy] = validate_error_strategy(opts.fetch(:error_strategy, :fail))
+      opts[:tls_config] = validate_tls_config(opts.fetch(:tls_config, nil))
 
-      @engine = self.class.initialize_engine(namespace, opts.to_json)
+      @engine = self.class.initialize_engine(opts.to_json)
       ObjectSpace.define_finalizer(self, self.class.finalize(@engine))
     end
 
@@ -76,88 +84,161 @@ module Flipt
 
     # Evaluate a variant flag for a given request
     #
-    # @param evaluation_request [Hash] evaluation request
-    # @option evaluation_request [String] :entity_id entity id
-    # @option evaluation_request [String] :flag_key flag key
-    def evaluate_variant(evaluation_request = {})
-      validate_evaluation_request(evaluation_request)
-      resp, ptr = self.class.evaluate_variant(@engine, evaluation_request.to_json)
-      ptr = FFI::AutoPointer.new(ptr, EvaluationClient.method(:destroy_string))
+    # @param flag_key [String]
+    # @param entity_id [String]
+    # @param context [Hash]
+    def evaluate_variant(flag_key:, entity_id:, context: {})
+      validate_evaluation_request(flag_key, entity_id, context)
+      req = { flag_key: flag_key, entity_id: entity_id, context: context }
+      resp, ptr = self.class.evaluate_variant(@engine, req.to_json)
+      ptr = FFI::AutoPointer.new(ptr, Client.method(:destroy_string))
       data = JSON.parse(resp)
-      raise Error, data['error_message'] if data['status'] != 'success'
-
-      data['result']
+      raise EvaluationError, data['error_message'] if data['status'] != 'success'
+
+      r = data['result']
+      VariantEvaluationResponse.new(
+        flag_key: r['flag_key'],
+        match: r['match'],
+        reason: r['reason'],
+        variant_key: r['variant_key'],
+        variant_attachment: r['variant_attachment'],
+        segment_keys: r['segment_keys'] || []
+      )
     end
 
     # Evaluate a boolean flag for a given request
     #
-    # @param evaluation_request [Hash] evaluation request
-    # @option evaluation_request [String] :entity_id entity id
-    # @option evaluation_request [String] :flag_key flag key
-    def evaluate_boolean(evaluation_request = {})
-      validate_evaluation_request(evaluation_request)
-      resp, ptr = self.class.evaluate_boolean(@engine, evaluation_request.to_json)
-      ptr = FFI::AutoPointer.new(ptr, EvaluationClient.method(:destroy_string))
+    # @param flag_key [String]
+    # @param entity_id [String]
+    # @param context [Hash]
+    def evaluate_boolean(flag_key:, entity_id:, context: {})
+      validate_evaluation_request(flag_key, entity_id, context)
+      req = { flag_key: flag_key, entity_id: entity_id, context: context }
+      resp, ptr = self.class.evaluate_boolean(@engine, req.to_json)
+      ptr = FFI::AutoPointer.new(ptr, Client.method(:destroy_string))
       data = JSON.parse(resp)
-      raise Error, data['error_message'] if data['status'] != 'success'
-
-      data['result']
+      raise EvaluationError, data['error_message'] if data['status'] != 'success'
+
+      r = data['result']
+      BooleanEvaluationResponse.new(
+        flag_key: r['flag_key'],
+        enabled: r['enabled'],
+        reason: r['reason'],
+        segment_keys: r['segment_keys'] || []
+      )
     end
 
     # Evaluate a batch of flags for a given request
     #
-    # @param batch_evaluation_request [Array<Hash>] batch evaluation request
+    # @param requests [Array<Hash>] batch evaluation request
     #   - :entity_id [String] entity id
     #   - :flag_key [String] flag key
-    def evaluate_batch(batch_evaluation_request = [])
-      batch_evaluation_request.each do |request|
-        validate_evaluation_request(request)
+    def evaluate_batch(requests:)
+      unless requests.is_a?(Array)
+        raise ValidationError, 'requests must be an array of evaluation requests'
       end
 
-      resp, ptr = self.class.evaluate_batch(@engine, batch_evaluation_request.to_json)
-      ptr = FFI::AutoPointer.new(ptr, EvaluationClient.method(:destroy_string))
+      requests.each do |request|
+        validate_evaluation_request(request[:flag_key], request[:entity_id], request[:context] || {})
+      end
+      resp, ptr = self.class.evaluate_batch(@engine, requests.to_json)
+      ptr = FFI::AutoPointer.new(ptr, Client.method(:destroy_string))
       data = JSON.parse(resp)
-      raise Error, data['error_message'] if data['status'] != 'success'
-
-      data['result']
+      raise EvaluationError, data['error_message'] if data['status'] != 'success'
+
+      responses = (data['result']['responses'] || []).map do |r|
+        case r['type']
+        when 'VARIANT_EVALUATION_RESPONSE_TYPE'
+          v = r['variant_evaluation_response']
+          VariantEvaluationResponse.new(
+            flag_key: v['flag_key'],
+            match: v['match'],
+            reason: v['reason'],
+            variant_key: v['variant_key'],
+            variant_attachment: v['variant_attachment'],
+            segment_keys: v['segment_keys'] || []
+          )
+        when 'BOOLEAN_EVALUATION_RESPONSE_TYPE'
+          b = r['boolean_evaluation_response']
+          BooleanEvaluationResponse.new(
+            flag_key: b['flag_key'],
+            enabled: b['enabled'],
+            reason: b['reason'],
+            segment_keys: b['segment_keys'] || []
+          )
+        when 'ERROR_EVALUATION_RESPONSE_TYPE'
+          e = r['error_evaluation_response']
+          ErrorEvaluationResponse.new(
+            flag_key: e['flag_key'],
+            namespace_key: e['namespace_key'],
+            reason: e['reason'],
+            error_message: e['error_message']
+          )
+        else
+          raise EvaluationError, "Unknown response type encountered: #{r['type']}"
+        end
+      end
+      BatchEvaluationResponse.new(responses: responses)
     end
 
     # List all flags in the namespace
     def list_flags
       resp, ptr = self.class.list_flags(@engine)
-      ptr = FFI::AutoPointer.new(ptr, EvaluationClient.method(:destroy_string))
+      ptr = FFI::AutoPointer.new(ptr, Client.method(:destroy_string))
       data = JSON.parse(resp)
       raise Error, data['error_message'] if data['status'] != 'success'
 
       data['result']
     end
 
+    # Get the snapshot of the current flag state
+    def snapshot
+      resp, ptr = self.class.get_snapshot(@engine)
+      ptr = FFI::AutoPointer.new(ptr, Client.method(:destroy_string))
+      resp
+    end
+
     private
 
-    def validate_evaluation_request(evaluation_request)
-      if evaluation_request[:entity_id].nil? || evaluation_request[:entity_id].empty?
-        raise ArgumentError, 'entity_id is required'
-      elsif evaluation_request[:flag_key].nil? || evaluation_request[:flag_key].empty?
-        raise ArgumentError, 'flag_key is required'
-      end
+    def validate_evaluation_request(flag_key, entity_id, context)
+      raise ValidationError, 'flag_key is required' if flag_key.nil? || flag_key.empty?
+      raise ValidationError, 'entity_id is required' if entity_id.nil? || entity_id.empty?
+      return if context.is_a?(Hash)
+
+      raise ValidationError, 'context must be a Hash<String, String>'
     end
 
     def validate_authentication(authentication)
       return authentication.strategy if authentication.is_a?(AuthenticationStrategy)
 
-      raise ArgumentError, 'invalid authentication strategy'
+      raise ValidationError, 'invalid authentication strategy'
     end
 
     def validate_fetch_mode(fetch_mode)
       return fetch_mode if %i[polling streaming].include?(fetch_mode)
 
-      raise ArgumentError, 'invalid fetch mode'
+      raise ValidationError, 'invalid fetch mode'
     end
 
     def validate_error_strategy(error_strategy)
       return error_strategy if %i[fail fallback].include?(error_strategy)
 
-      raise ArgumentError, 'invalid error strategy'
+      raise ValidationError, 'invalid error strategy'
+    end
+
+    def validate_tls_config(tls_config)
+      return nil if tls_config.nil?
+      return tls_config.to_h if tls_config.is_a?(TlsConfig)
+
+      raise ValidationError, 'invalid tls_config: must be TlsConfig instance'
+    end
+  end
+
+  # Deprecation shim for EvaluationClient
+  class EvaluationClient < Client
+    def initialize(*args, **kwargs)
+      warn '[DEPRECATION] `EvaluationClient` is deprecated. Please use `Client` instead.'
+      super
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flipt_client
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Flipt Devs
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-19 00:00:00.000000000 Z
+date: 2025-06-30 00:00:00.000000000 Z
 dependencies: []
 description: Flipt Client Evaluation SDK
 email:
@@ -42,7 +42,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="