billdogeng 1.0.2.pre.beta.3

data/lib/billdogeng/transport.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "zlib"
+require "stringio"
+
+require_relative "errors"
+
+module BilldogEng
+  # Thin HTTP client around Net::HTTP with:
+  #  - per-request timeout
+  #  - optional gzip request bodies (only when large enough to benefit)
+  #  - exponential backoff retry (1s, 2s, 4s …) for 5xx / 429 / network errors
+  #  - unwrapping of the `{ success, data, meta }` envelope (required on 2xx)
+  class Transport
+    GZIP_THRESHOLD_BYTES = 1024 # only compress bodies large enough to benefit
+
+    # @param host            [String]  base URL, e.g. "https://api.billdog.io/v1"
+    # @param request_timeout [Integer] per-request timeout in milliseconds
+    # @param gzip            [Boolean] gzip large request bodies
+    # @param max_retries     [Integer] retry attempts for transient failures
+    # @param enable_logging  [Boolean] emit verbose diagnostics
+    # @param http_adapter    [#call]   optional injectable HTTP fn (for tests):
+    #   `->(method, url, headers, body) { [status_int, body_string] }`
+    def initialize(host:, request_timeout:, gzip:, max_retries:, enable_logging:, http_adapter: nil)
+      @host = host.to_s.sub(%r{/+\z}, "")
+      @request_timeout = request_timeout
+      @gzip = gzip
+      @max_retries = max_retries
+      @enable_logging = enable_logging
+      @http_adapter = http_adapter
+    end
+
+    # Perform a POST (or GET when body is nil) request with retry/backoff.
+    # Returns the parsed JSON body, unwrapped from the standard envelope.
+    # Raises BilldogEng::Error after the final retry fails.
+    #
+    # @param path    [String]  path appended to host, e.g. "/ingest-events"
+    # @param body    [Object]  request body (serialized to JSON), or nil for GET
+    # @param headers [Hash]    extra headers (auth supplied per-call)
+    # @param gzip    [Boolean] override: gzip this request (only if config.gzip)
+    def request(path:, body: nil, headers: {}, gzip: true)
+      url = "#{@host}#{path}"
+      max_attempts = @max_retries + 1
+      last_error = nil
+
+      max_attempts.times do |attempt|
+        if attempt.positive?
+          backoff = 1.0 * (2**(attempt - 1)) # 1s, 2s, 4s …
+          log("retry #{attempt}/#{@max_retries} after #{backoff}s -> #{path}")
+          sleep(backoff)
+        end
+
+        begin
+          return attempt_request(url, body, headers, gzip)
+        rescue BilldogEng::Error => e
+          last_error = e
+          raise e if !retryable?(e.status) || attempt == max_attempts - 1
+
+          log("request failed (status #{e.status}), will retry: #{e.message}")
+        end
+      end
+
+      raise(last_error || BilldogEng::Error.new("request failed", status: 0))
+    end
+
+    private
+
+    def log(*args)
+      warn("[BilldogEng] #{args.join(" ")}") if @enable_logging
+    end
+
+    # Status codes that are safe to retry (transient).
+    def retryable?(status)
+      status.zero? || status == 408 || status == 429 || (status >= 500 && status <= 599)
+    end
+
+    def attempt_request(url, body, headers, gzip_opt)
+      req_headers = {
+        "Content-Type" => "application/json",
+        "User-Agent" => "billdogeng-ruby/#{BilldogEng::VERSION}",
+      }.merge(headers)
+
+      payload = nil
+      unless body.nil?
+        json = JSON.generate(body)
+        use_gzip = @gzip && gzip_opt != false && json.bytesize >= GZIP_THRESHOLD_BYTES
+        if use_gzip
+          req_headers["Content-Encoding"] = "gzip"
+          payload = gzip_compress(json)
+        else
+          payload = json
+        end
+      end
+
+      method = body.nil? ? "GET" : "POST"
+      status, text = perform(method, url, req_headers, payload)
+
+      parsed = parse_body(text)
+
+      unless status >= 200 && status < 300
+        # The nested error envelope: `{ success: false, error: { code, message } }`.
+        error = parsed.is_a?(Hash) && parsed["error"].is_a?(Hash) ? parsed["error"] : nil
+        message = (error && error["message"]) || "HTTP #{status}"
+        code = error && error["code"]
+        raise BilldogEng::Error.new(message, status: status, code: code, body: parsed)
+      end
+
+      unwrap_envelope(parsed, status)
+    end
+
+    # Returns [status_int, body_string].
+    def perform(method, url, headers, payload)
+      return @http_adapter.call(method, url, headers, payload) if @http_adapter
+
+      uri = URI.parse(url)
+      timeout_s = @request_timeout / 1000.0
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout_s
+      http.read_timeout = timeout_s
+      http.write_timeout = timeout_s if http.respond_to?(:write_timeout=)
+
+      request =
+        if method == "GET"
+          Net::HTTP::Get.new(uri.request_uri)
+        else
+          Net::HTTP::Post.new(uri.request_uri)
+        end
+      headers.each { |k, v| request[k] = v }
+      request.body = payload if payload
+
+      begin
+        response = http.request(request)
+      rescue StandardError => e
+        # Network failure / timeout → status 0, retryable.
+        raise BilldogEng::Error.new("network error: #{e.message}", status: 0, code: "NETWORK_ERROR")
+      end
+
+      [response.code.to_i, response.body.to_s]
+    end
+
+    def parse_body(text)
+      return nil if text.nil? || text.empty?
+
+      begin
+        JSON.parse(text)
+      rescue JSON::ParserError
+        text
+      end
+    end
+
+    # Every endpoint answers the standard `{ success, data, meta }` envelope, and
+    # `data` is the payload. Anything else is not a BillDog answer and is refused,
+    # never read as a payload.
+    def unwrap_envelope(parsed, status)
+      # A quota refusal rides at the TOP level of the body, deliberately outside the
+      # envelope and with no `data`, so never unwrap past one: the caller has to see
+      # `quota_limited` to know the 200 it just got discarded its payload.
+      return parsed if parsed.is_a?(Hash) && parsed.key?("quota_limited")
+
+      return parsed["data"] if parsed.is_a?(Hash) && parsed["success"] == true && parsed.key?("data")
+
+      raise BilldogEng::Error.new(
+        "malformed response: expected the { success, data } envelope",
+        status: status, code: "MALFORMED_RESPONSE", body: parsed
+      )
+    end
+
+    def gzip_compress(str)
+      io = StringIO.new
+      io.set_encoding(Encoding::BINARY)
+      gz = Zlib::GzipWriter.new(io)
+      gz.write(str)
+      gz.close
+      io.string
+    end
+  end
+end

data/lib/billdogeng/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BilldogEng
+  VERSION = "1.0.2-beta.3"
+end

data/lib/billdogeng.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# billdogeng — Official BilldogEng server SDK for Ruby.
+#
+# Engagement suite: Analytics + Feature Flags (remote + local eval) + Surveys +
+# Messaging + LLM observability.
+#
+# @example
+#   require "billdogeng"
+#   bd = BilldogEng.new("bd_test_xxx", local_evaluation: true)
+#   bd.capture("user-123", "order_completed", { revenue: 49.99 })
+#   bd.shutdown
+
+require_relative "billdogeng/version"
+require_relative "billdogeng/errors"
+require_relative "billdogeng/quota_limited"
+require_relative "billdogeng/murmur"
+require_relative "billdogeng/targeting"
+require_relative "billdogeng/transport"
+require_relative "billdogeng/analytics"
+require_relative "billdogeng/flags"
+require_relative "billdogeng/surveys"
+require_relative "billdogeng/messaging"
+require_relative "billdogeng/llm"
+require_relative "billdogeng/client"
+
+module BilldogEng
+  # Convenience constructor: `BilldogEng.new(api_key, **opts)` → BilldogEng::Client.
+  def self.new(api_key, opts = {})
+    Client.new(api_key, opts)
+  end
+
+  # Expose the bucketing primitive at the top level for cross-platform parity use.
+  def self.murmurhash3(key, seed = 0)
+    Murmur.murmurhash3(key, seed)
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: billdogeng
+version: !ruby/object:Gem::Version
+  version: 1.0.2.pre.beta.3
+platform: ruby
+authors:
+- BillDog
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: 'BilldogEng engagement suite for server-side Ruby: Analytics, Feature
+  Flags (remote + local evaluation), Surveys (data API), Messaging dispatch, and LLM
+  observability.'
+email:
+- sdk@billdog.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/billdogeng.rb
+- lib/billdogeng/analytics.rb
+- lib/billdogeng/client.rb
+- lib/billdogeng/errors.rb
+- lib/billdogeng/flags.rb
+- lib/billdogeng/llm.rb
+- lib/billdogeng/messaging.rb
+- lib/billdogeng/murmur.rb
+- lib/billdogeng/quota_limited.rb
+- lib/billdogeng/surveys.rb
+- lib/billdogeng/targeting.rb
+- lib/billdogeng/transport.rb
+- lib/billdogeng/version.rb
+homepage: https://billdog.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://billdog.io
+  source_code_uri: https://github.com/billdog/billdogeng-ruby
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official BilldogEng server SDK for Ruby.
+test_files: []