shipeasy-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4eafaff1d5be1131bb55a64dbbb1653ee18f2a5a9e22cd83a45bb92de7bcfcb6
+  data.tar.gz: 4b59ebf58017deb5def949f46235d53f6ca60320400ac72ada320eff92d7e5d5
+SHA512:
+  metadata.gz: cb3f19e0215c65fed6db82a1ef181949ef0cb666a25e02e67103b6840bc79ee3e855e9f784a99f03d9ca54c73a74f431e3d16fd90fca29561317ab4b80b200f0
+  data.tar.gz: 480ac5a6fdeaef418e34488a668e4431bafa392a54d7e8eae7373541a48d401bdb687408e0759f6269c7263c9d38a11b4b4877930df65b4cd7bde859472b0eca

data/README.md

@@ -0,0 +1,61 @@
+# shipeasy-sdk
+
+Ruby SDK for the ShipEasy experiment platform. Evaluates feature flags and A/B experiments locally against blobs polled from the ShipEasy edge worker.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "shipeasy-sdk"
+```
+
+## Quick start
+
+```ruby
+require "shipeasy-sdk"
+
+client = Shipeasy::SDK.new_client(api_key: "sdk_live_xxxxx")
+client.init   # fetches flags/experiments + starts background polling thread
+
+user = { user_id: "usr_123", plan: "pro", country: "US" }
+
+# Feature flag
+if client.get_flag("new_checkout", user)
+  # show new checkout
+end
+
+# Remote config
+color = client.get_config("button_color")   # => "blue" (raw value)
+
+# A/B experiment
+result = client.get_experiment("checkout_cta", user, { label: "Buy now" })
+puts result.in_experiment  # true/false
+puts result.group          # "control" | "treatment"
+puts result.params         # { "label" => "Checkout" }
+
+# Track a metric event (fire-and-forget background thread)
+client.track("usr_123", "checkout_completed", { revenue: 49.99 })
+
+# Shutdown (stops background poll thread)
+client.destroy
+```
+
+## init vs init_once
+
+- `init` — fetches data, marks initialized, starts the background poll thread. Call once at app boot.
+- `init_once` — same as `init` but is a no-op if already initialized. Safe to call multiple times (e.g. in middleware).
+
+## Evaluation details
+
+- **Gates** — rules matched in order; rollout bucket computed as `murmur3("#{salt}:#{uid}") % 10000 < rolloutPct`.
+- **Experiments** — checks `status == "running"`, optional targeting gate, universe holdout range, allocation bucket, then group assignment by weight.
+- **MurmurHash3** — pure Ruby implementation, x86_32 variant, seed 0.
+- **ETag caching** — each poll sends `If-None-Match`; a `304` response skips the JSON parse.
+- **Poll interval** — initial default 30 s; overridden by `X-Poll-Interval` response header from the flags endpoint.
+
+## Configuration
+
+| Parameter  | Default                        | Description                       |
+|------------|--------------------------------|-----------------------------------|
+| `api_key`  | (required)                     | SDK key from the ShipEasy dashboard |
+| `base_url` | `https://edge.shipeasy.dev`    | Override for local dev / staging  |

data/lib/shipeasy/sdk/eval.rb

@@ -0,0 +1,117 @@
+require_relative "murmur3"
+
+module Shipeasy
+  module SDK
+    module Eval
+      def self.murmur3(key)
+        Murmur3.hash32(key, 0)
+      end
+
+      def self.enabled?(v)
+        v == 1 || v == true
+      end
+
+      def self.to_num(v)
+        case v
+        when Numeric then v.finite? ? v : nil
+        when String
+          n = Float(v) rescue nil
+          n&.finite? ? n : nil
+        end
+      end
+
+      def self.match_rule(rule, user)
+        attr  = rule["attr"] || rule[:attr]
+        op    = rule["op"]   || rule[:op]
+        value = rule["value"] || rule[:value]
+        actual = user[attr] || user[attr.to_sym]
+
+        case op
+        when "eq"       then actual == value
+        when "neq"      then actual != value
+        when "in"       then Array(value).include?(actual)
+        when "not_in"   then !Array(value).include?(actual)
+        when "contains"
+          if actual.is_a?(String) && value.is_a?(String)
+            actual.include?(value)
+          elsif actual.is_a?(Array)
+            actual.include?(value)
+          else
+            false
+          end
+        when "regex"
+          actual.is_a?(String) && value.is_a?(String) &&
+            Regexp.new(value).match?(actual) rescue false
+        when "gt", "gte", "lt", "lte"
+          a = to_num(actual)
+          b = to_num(value)
+          return false if a.nil? || b.nil?
+          case op
+          when "gt"  then a > b
+          when "gte" then a >= b
+          when "lt"  then a < b
+          when "lte" then a <= b
+          end
+        else
+          false
+        end
+      end
+
+      def self.eval_gate(gate, user)
+        return false if enabled?(gate["killswitch"])
+        return false unless enabled?(gate["enabled"])
+
+        (gate["rules"] || []).each do |rule|
+          return false unless match_rule(rule, user)
+        end
+
+        uid = user["user_id"] || user[:user_id] || user["anonymous_id"] || user[:anonymous_id]
+        return false unless uid
+
+        salt = gate["salt"] || gate[:salt]
+        murmur3("#{salt}:#{uid}") % 10000 < (gate["rolloutPct"] || gate[:rolloutPct] || 0)
+      end
+
+      ExperimentResult = Struct.new(:in_experiment, :group, :params, keyword_init: true)
+
+      def self.eval_experiment(exp, flags_blob, exps_blob, user)
+        not_in = ExperimentResult.new(in_experiment: false, group: "control", params: nil)
+
+        return not_in unless exp && exp["status"] == "running"
+
+        targeting_gate = exp["targetingGate"]
+        if targeting_gate && !targeting_gate.empty?
+          gate = flags_blob&.dig("gates", targeting_gate)
+          return not_in unless gate && eval_gate(gate, user)
+        end
+
+        uid = user["user_id"] || user[:user_id] || user["anonymous_id"] || user[:anonymous_id]
+        return not_in unless uid
+
+        universe_name = exp["universe"]
+        universe = exps_blob&.dig("universes", universe_name)
+        holdout = universe&.dig("holdout_range")
+        if holdout
+          seg = murmur3("#{universe_name}:#{uid}") % 10000
+          return not_in if seg >= holdout[0] && seg <= holdout[1]
+        end
+
+        salt          = exp["salt"]
+        allocation_pct = exp["allocationPct"] || 0
+        return not_in if murmur3("#{salt}:alloc:#{uid}") % 10000 >= allocation_pct
+
+        group_hash = murmur3("#{salt}:group:#{uid}") % 10000
+        cumulative = 0
+        groups = exp["groups"] || []
+        groups.each_with_index do |g, i|
+          cumulative += g["weight"]
+          if group_hash < cumulative || i == groups.length - 1
+            return ExperimentResult.new(in_experiment: true, group: g["name"], params: g["params"])
+          end
+        end
+
+        not_in
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/flags_client.rb

@@ -0,0 +1,169 @@
+require "net/http"
+require "uri"
+require "json"
+require "thread"
+require_relative "eval"
+
+module Shipeasy
+  module SDK
+    class FlagsClient
+      DEFAULT_BASE_URL = "https://edge.shipeasy.dev"
+
+      def initialize(api_key:, base_url: nil)
+        @api_key     = api_key
+        @base_url    = (base_url || DEFAULT_BASE_URL).chomp("/")
+        @flags_blob  = nil
+        @exps_blob   = nil
+        @flags_etag  = nil
+        @exps_etag   = nil
+        @poll_interval = 30
+        @mutex       = Mutex.new
+        @timer       = nil
+        @initialized = false
+      end
+
+      def init
+        fetch_all
+        @initialized = true
+        start_poll
+      end
+
+      def init_once
+        return if @initialized
+        fetch_all
+        @initialized = true
+      end
+
+      def destroy
+        @timer&.kill
+        @timer = nil
+      end
+
+      def get_flag(name, user)
+        gate = @mutex.synchronize { @flags_blob&.dig("gates", name) }
+        return false unless gate
+        Eval.eval_gate(gate, user.transform_keys(&:to_s))
+      end
+
+      def get_config(name, decode = nil)
+        entry = @mutex.synchronize { @flags_blob&.dig("configs", name) }
+        return nil unless entry
+        value = entry["value"]
+        decode ? decode.call(value) : value
+      end
+
+      def get_experiment(name, user, default_params, decode = nil)
+        flags_blob, exps_blob = @mutex.synchronize { [@flags_blob, @exps_blob] }
+        exp = exps_blob&.dig("experiments", name)
+        result = Eval.eval_experiment(exp, flags_blob, exps_blob, user.transform_keys(&:to_s))
+        result.params ||= default_params
+
+        if result.in_experiment && decode
+          begin
+            result = Eval::ExperimentResult.new(
+              in_experiment: true,
+              group: result.group,
+              params: decode.call(result.params),
+            )
+          rescue => e
+            warn "[shipeasy] get_experiment('#{name}') decode failed: #{e.message}"
+            return Eval::ExperimentResult.new(in_experiment: false, group: "control", params: default_params)
+          end
+        end
+
+        result
+      end
+
+      def track(user_id, event_name, props = {})
+        payload = JSON.generate({
+          events: [{
+            type: "metric",
+            event_name: event_name,
+            user_id: user_id.to_s,
+            ts: (Time.now.to_f * 1000).to_i,
+            **(props.empty? ? {} : { properties: props }),
+          }],
+        })
+
+        Thread.new do
+          post("/collect", payload)
+        rescue => e
+          warn "[shipeasy] track failed: #{e.message}"
+        end
+      end
+
+      private
+
+      def start_poll
+        @timer = Thread.new do
+          loop do
+            sleep(@poll_interval)
+            begin
+              fetch_all
+            rescue => e
+              warn "[shipeasy] background poll failed: #{e.message}"
+            end
+          end
+        end
+        @timer.abort_on_exception = false
+      end
+
+      def fetch_all
+        flags_thread = Thread.new { fetch_flags }
+        fetch_exps
+        interval = flags_thread.value
+        if interval && interval != @poll_interval
+          @poll_interval = interval
+        end
+      end
+
+      def fetch_flags
+        headers = { "X-SDK-Key" => @api_key }
+        headers["If-None-Match"] = @flags_etag if @flags_etag
+        res = http_get("/sdk/flags", headers)
+        interval = (res["X-Poll-Interval"] || "30").to_i
+        return interval if res.code == "304"
+        raise "GET /sdk/flags returned #{res.code}" unless res.is_a?(Net::HTTPSuccess)
+        etag = res["ETag"]
+        blob = JSON.parse(res.body)
+        @mutex.synchronize do
+          @flags_etag = etag if etag
+          @flags_blob = blob
+        end
+        interval
+      end
+
+      def fetch_exps
+        headers = { "X-SDK-Key" => @api_key }
+        headers["If-None-Match"] = @exps_etag if @exps_etag
+        res = http_get("/sdk/experiments", headers)
+        return if res.code == "304"
+        raise "GET /sdk/experiments returned #{res.code}" unless res.is_a?(Net::HTTPSuccess)
+        etag = res["ETag"]
+        blob = JSON.parse(res.body)
+        @mutex.synchronize do
+          @exps_etag = etag if etag
+          @exps_blob = blob
+        end
+      end
+
+      def http_get(path, headers = {})
+        uri  = URI.parse("#{@base_url}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl     = (uri.scheme == "https")
+        http.open_timeout = 5
+        http.read_timeout = 10
+        http.get(uri.request_uri, headers)
+      end
+
+      def post(path, body)
+        uri  = URI.parse("#{@base_url}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl      = (uri.scheme == "https")
+        http.open_timeout = 5
+        http.read_timeout = 10
+        http.post(uri.request_uri, body, { "X-SDK-Key" => @api_key, "Content-Type" => "text/plain" })
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/murmur3.rb

@@ -0,0 +1,54 @@
+module Shipeasy
+  module SDK
+    module Murmur3
+      C1 = 0xcc9e2d51
+      C2 = 0x1b873593
+      MASK32 = 0xFFFFFFFF
+
+      def self.hash32(key, seed = 0)
+        bytes = key.encode("UTF-8").bytes
+        len   = bytes.length
+        h1    = seed
+
+        (len / 4).times do |i|
+          off = i * 4
+          k1 = bytes[off] | (bytes[off + 1] << 8) | (bytes[off + 2] << 16) | (bytes[off + 3] << 24)
+          k1 = (k1 & MASK32)
+          k1 = ((k1 * C1) & MASK32)
+          k1 = ((k1 << 15) | (k1 >> 17)) & MASK32
+          k1 = ((k1 * C2) & MASK32)
+          h1 ^= k1
+          h1 = ((h1 << 13) | (h1 >> 19)) & MASK32
+          h1 = ((h1 * 5) & MASK32)
+          h1 = (h1 + 0xe6546b64) & MASK32
+        end
+
+        tail   = (len / 4) * 4
+        k1     = 0
+        remain = len & 3
+        k1 ^= (bytes[tail + 2] << 16) if remain >= 3
+        k1 ^= (bytes[tail + 1] << 8)  if remain >= 2
+        k1 ^= bytes[tail]              if remain >= 1
+        if remain > 0
+          k1 = (k1 * C1) & MASK32
+          k1 = ((k1 << 15) | (k1 >> 17)) & MASK32
+          k1 = (k1 * C2) & MASK32
+          h1 ^= k1
+        end
+
+        h1 ^= len
+        h1  = fmix32(h1)
+        h1
+      end
+
+      def self.fmix32(h)
+        h ^= (h >> 16)
+        h  = (h * 0x85ebca6b) & MASK32
+        h ^= (h >> 13)
+        h  = (h * 0xc2b2ae35) & MASK32
+        h ^= (h >> 16)
+        h
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/version.rb

@@ -0,0 +1,5 @@
+module Shipeasy
+  module SDK
+    VERSION = "1.0.0"
+  end
+end

data/lib/shipeasy-sdk.rb

@@ -0,0 +1,12 @@
+require_relative "shipeasy/sdk/version"
+require_relative "shipeasy/sdk/murmur3"
+require_relative "shipeasy/sdk/eval"
+require_relative "shipeasy/sdk/flags_client"
+
+module Shipeasy
+  module SDK
+    def self.new_client(api_key:, base_url: nil)
+      FlagsClient.new(api_key: api_key, base_url: base_url)
+    end
+  end
+end

metadata

@@ -0,0 +1,47 @@
+--- !ruby/object:Gem::Specification
+name: shipeasy-sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- ShipEasy
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Server SDK for ShipEasy — polls /sdk/flags and /sdk/experiments, evaluates
+  flags and experiments locally.
+email:
+- sdk@shipeasy.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/shipeasy-sdk.rb
+- lib/shipeasy/sdk/eval.rb
+- lib/shipeasy/sdk/flags_client.rb
+- lib/shipeasy/sdk/murmur3.rb
+- lib/shipeasy/sdk/version.rb
+homepage: https://github.com/shipeasy/sdk-ruby
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: ShipEasy feature flag and experimentation SDK for Ruby
+test_files: []