mirrors-sdk 0.1.0

data/lib/mirrors_sdk/executor.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module MirrorsSDK
+  class Cancellation
+    def initialize
+      @lock = Mutex.new
+      @reason = nil
+      @callbacks = {}
+    end
+
+    def canceled?
+      @lock.synchronize { !@reason.nil? }
+    end
+
+    def reason
+      @lock.synchronize { @reason }
+    end
+
+    def cancel(reason = "canceled")
+      callbacks = @lock.synchronize do
+        return false if @reason
+
+        @reason = reason
+        values = @callbacks.values
+        @callbacks.clear
+        values
+      end
+      callbacks.each { |callback| safely(callback) }
+      true
+    end
+
+    def on_cancel(&callback)
+      key = Object.new
+      canceled = @lock.synchronize do
+        @callbacks[key] = callback unless @reason
+        !@reason.nil?
+      end
+      safely(callback) if canceled
+      -> { @lock.synchronize { @callbacks.delete(key) } }
+    end
+
+    private
+
+    def safely(callback)
+      callback.call
+    rescue StandardError
+      nil
+    end
+  end
+
+  class CanceledError < StandardError
+    attr_reader :reason
+
+    def initialize(reason = "canceled")
+      @reason = reason
+      super(reason)
+    end
+  end
+
+  class Future
+    attr_reader :token
+
+    def initialize
+      @token = Cancellation.new
+      @lock = Mutex.new
+      @condition = ConditionVariable.new
+      @done = false
+      @callbacks = []
+    end
+
+    def done?
+      @lock.synchronize { @done }
+    end
+
+    def wait(timeout = nil)
+      deadline = timeout && monotonic + [timeout, 0].max
+      @lock.synchronize do
+        until @done
+          remaining = deadline && deadline - monotonic
+          return false if remaining && remaining <= 0
+
+          @condition.wait(@lock, remaining)
+        end
+      end
+      true
+    end
+
+    def value
+      wait
+      @lock.synchronize do
+        raise @error if @error
+
+        @value
+      end
+    end
+
+    def cancel(reason = "canceled")
+      @token.cancel(reason)
+      reject(CanceledError.new(reason))
+    end
+
+    def on_complete(&callback)
+      complete = @lock.synchronize do
+        @callbacks << callback unless @done
+        @done
+      end
+      notify(callback) if complete
+      self
+    end
+
+    def resolve(value)
+      settle(value, nil)
+    end
+
+    def reject(error)
+      settle(nil, error)
+    end
+
+    private
+
+    def settle(value, error)
+      callbacks = @lock.synchronize do
+        return false if @done
+
+        @value, @error, @done = value, error, true
+        @condition.broadcast
+        pending = @callbacks
+        @callbacks = []
+        pending
+      end
+      callbacks.each { |callback| notify(callback) }
+      true
+    end
+
+    def notify(callback)
+      callback.call(self)
+    rescue StandardError
+      nil
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+
+  # Physical workers remain occupied until a canceled operation actually returns.
+  # This bounds thread growth even when the operating system stalls DNS resolution.
+  class Executor
+    def initialize(size:, capacity:, name: "mirrors-sdk")
+      raise ArgumentError, "Invalid worker count" unless size.instance_of?(Integer) && size.positive?
+      raise ArgumentError, "Invalid capacity" unless capacity.instance_of?(Integer) && capacity >= size
+
+      @lock = Mutex.new
+      @condition = ConditionVariable.new
+      @capacity = capacity
+      @closed = false
+      @queue = []
+      @jobs = {}
+      @threads = Array.new(size) do |index|
+        Thread.new do
+          Thread.current.name = "#{name}-#{index}" if Thread.current.respond_to?(:name=)
+          work
+        end
+      end
+      @threads.each { |thread| thread.report_on_exception = false }
+    end
+
+    def submit(&block)
+      raise ArgumentError, "Missing work" unless block
+
+      @lock.synchronize do
+        return nil if @closed || @jobs.length >= @capacity || @threads.any? { |thread| !thread.alive? }
+
+        future = Future.new
+        @jobs[future] = true
+        @queue << [future, block]
+        @condition.signal
+        future
+      end
+    end
+
+    def shutdown(reason = "closed")
+      jobs = @lock.synchronize do
+        return if @closed
+
+        @closed = true
+        @queue.each { |future, _block| @jobs.delete(future) }
+        queued = @queue.map(&:first)
+        @queue.clear
+        @condition.broadcast
+        @jobs.keys + queued
+      end
+      jobs.each { |future| future.cancel(reason) }
+      nil
+    end
+
+    def diagnostics
+      @lock.synchronize do
+        { pending: @jobs.length, queued: @queue.length, threads: @threads.count(&:alive?), closed: @closed }
+      end
+    end
+
+    private
+
+    def work
+      loop do
+        job = @lock.synchronize do
+          @condition.wait(@lock) while @queue.empty? && !@closed
+          @queue.shift unless @closed
+        end
+        break unless job
+
+        future, block = job
+        begin
+          future.resolve(block.call(future.token)) unless future.token.canceled?
+        rescue StandardError => error
+          future.reject(error)
+        ensure
+          @lock.synchronize { @jobs.delete(future) }
+        end
+      end
+    end
+  end
+end

data/lib/mirrors_sdk/models.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "thread"
+require "securerandom"
+
+module MirrorsSDK
+  # Results are immutable so callers cannot change delivery or freshness bookkeeping.
+  class DeliveryReceipt
+    attr_reader :status, :reason, :ingestion
+
+    def initialize(status, reason = nil, ingestion: nil)
+      @status, @reason = status.freeze, reason&.freeze
+      @ingestion = ingestion&.each_with_object({}) { |(key, value), copy| copy[key.freeze] = value&.freeze }&.freeze
+      freeze
+    end
+  end
+
+  class DeliveryTicket
+    attr_reader :id
+
+    def initialize(identifier = SecureRandom.uuid)
+      @id = identifier.freeze
+      @mutex, @condition = Mutex.new, ConditionVariable.new
+      @receipt = DeliveryReceipt.new("pending")
+    end
+
+    def receipt
+      @mutex.synchronize { @receipt }
+    end
+
+    # Wait explicitly outside the application's model execution path. Seconds, at most 30.
+    def wait(timeout = 0)
+      timeout = 0 unless (timeout.instance_of?(Integer) || timeout.instance_of?(Float)) && timeout.between?(0, 30)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      @mutex.synchronize do
+        while @receipt.status == "pending"
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break if remaining <= 0
+
+          @condition.wait(@mutex, remaining)
+        end
+        @receipt
+      end
+    end
+
+    def settle(receipt)
+      @mutex.synchronize do
+        return false unless @receipt.status == "pending"
+
+        @receipt = receipt
+        @condition.broadcast
+        true
+      end
+    end
+    private :settle
+  end
+
+  class ContextFreshness
+    attr_reader :request_id, :trace_id, :decision_id, :mode_version, :issued_at, :expires_at
+
+    def initialize(request_id:, trace_id:, decision_id:, mode_version:, issued_at:, expires_at:)
+      @request_id, @trace_id, @decision_id = request_id.freeze, trace_id.freeze, decision_id.freeze
+      @mode_version, @issued_at, @expires_at = mode_version.freeze, issued_at.freeze, expires_at.freeze
+      freeze
+    end
+  end
+
+  class ContextResult
+    attr_reader :context, :mode, :delivery, :reason, :elapsed_ms, :freshness
+
+    def initialize(context: "", mode: "shadow", delivery: "unconfirmed", reason: "unavailable", elapsed_ms: 0, freshness: nil)
+      @context, @mode, @delivery, @reason = [context, mode, delivery, reason].map(&:freeze)
+      @elapsed_ms, @freshness = elapsed_ms, freshness
+      freeze
+    end
+  end
+
+  class FlushResult
+    attr_reader :accepted, :dropped, :unconfirmed, :pending
+
+    def initialize(accepted: 0, dropped: 0, unconfirmed: 0, pending: 0)
+      @accepted, @dropped, @unconfirmed, @pending = accepted, dropped, unconfirmed, pending
+      freeze
+    end
+
+    def complete
+      (@dropped + @unconfirmed + @pending).zero?
+    end
+    alias complete? complete
+  end
+
+  class TurnTimer
+    def initialize
+      @started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @mutex = Mutex.new
+    end
+
+    def finish
+      @mutex.synchronize do
+        @duration ||= [(Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started) * 1000, 0].max
+      end
+    end
+  end
+end

data/lib/mirrors_sdk/snapshot.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+
+module MirrorsSDK
+  # Copies only ordinary JSON data, without calling application serialization hooks.
+  class Snapshot
+    CLASS = Object.instance_method(:class)
+    OBJECT_ID = BasicObject.instance_method(:__id__)
+    ARRAY_EACH = Array.instance_method(:each)
+    HASH_EACH = Hash.instance_method(:each_pair)
+    ARRAY_LENGTH = Array.instance_method(:length)
+    HASH_LENGTH = Hash.instance_method(:length)
+    STRING_BYTESIZE = String.instance_method(:bytesize)
+    STRING_ENCODING = String.instance_method(:encoding)
+    SAFE_INTEGER = 9_007_199_254_740_991
+
+    def self.check_deadline(deadline)
+      if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+        raise Timeout::Error, "Snapshot deadline exceeded"
+      end
+    end
+
+    def self.copy(value, limit: 1_000_000, deadline: nil)
+      new(limit, deadline).copy(value)
+    end
+
+    def self.encode(value, limit: 1_000_000, deadline: nil)
+      copied = copy(value, limit: limit, deadline: deadline)
+      encoded = JSON.generate(copied)
+      check_deadline(deadline)
+      raise ArgumentError, "Snapshot encoded byte limit exceeded" if encoded.bytesize > limit
+
+      encoded
+    rescue JSON::GeneratorError, EncodingError => error
+      raise ArgumentError, "Invalid JSON encoding: #{error.class}"
+    end
+
+    def initialize(limit, deadline)
+      @remaining = limit
+      @nodes = 50_000
+      @deadline = deadline
+      @ancestors = {}
+    end
+
+    def copy(value)
+      self.class.check_deadline(@deadline)
+      result = visit(value, 0)
+      self.class.check_deadline(@deadline)
+      result
+    end
+
+    private
+
+    def visit(item, depth)
+      @nodes -= 1
+      self.class.check_deadline(@deadline) if (@nodes % 32).zero?
+      spend(1)
+      raise ArgumentError, "Snapshot limit exceeded" if @nodes.negative? || depth > 32
+
+      kind = CLASS.bind(item).call
+      return item if [NilClass, TrueClass, FalseClass].include?(kind)
+      if kind == Integer
+        raise ArgumentError, "JSON integer exceeds the safe integer range" if item.abs > SAFE_INTEGER
+        return item
+      end
+      if kind == Float
+        raise ArgumentError, "Nonfinite JSON number" unless item.finite?
+        return item
+      end
+      return copy_string(item) if kind == String
+      unless [Hash, Array].include?(kind)
+        raise ArgumentError, "Expected ordinary acyclic JSON data"
+      end
+
+      identity = OBJECT_ID.bind(item).call
+      raise ArgumentError, "Cyclic JSON data" if @ancestors[identity]
+
+      length = (kind == Hash ? HASH_LENGTH : ARRAY_LENGTH).bind(item).call
+      raise ArgumentError, "Snapshot collection limit exceeded" if length > 10_000
+
+      @ancestors[identity] = true
+      begin
+        if kind == Array
+          result = []
+          ARRAY_EACH.bind(item).call { |child| result << visit(child, depth + 1) }
+        else
+          result = {}
+          HASH_EACH.bind(item).call do |key, child|
+            raise ArgumentError, "JSON object keys must be strings" unless CLASS.bind(key).call == String
+
+            result[copy_string(key)] = visit(child, depth + 1)
+          end
+        end
+        result
+      ensure
+        @ancestors.delete(identity)
+      end
+    end
+
+    def copy_string(value)
+      self.class.check_deadline(@deadline)
+      source_bytes = STRING_BYTESIZE.bind(value).call
+      encoding = STRING_ENCODING.bind(value).call
+      # A bounded source allowance accommodates UTF-16/32 before UTF-8 conversion.
+      multiplier = [Encoding::UTF_8, Encoding::US_ASCII, Encoding::ASCII_8BIT].include?(encoding) ? 1 : 4
+      if source_bytes > @remaining * multiplier
+        raise ArgumentError, "Snapshot string source limit exceeded"
+      end
+
+      result = String.new(value)
+      self.class.check_deadline(@deadline)
+      result = result.encode(Encoding::UTF_8)
+      self.class.check_deadline(@deadline)
+      raise ArgumentError, "Invalid JSON string encoding" unless result.valid_encoding?
+
+      spend(result.bytesize)
+      result
+    rescue EncodingError
+      raise ArgumentError, "Invalid JSON string encoding"
+    end
+
+    def spend(amount)
+      @remaining -= amount
+      raise ArgumentError, "Snapshot limit exceeded" if @remaining.negative?
+    end
+  end
+end

data/lib/mirrors_sdk/transport.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "net/http"
+require "timeout"
+require "uri"
+require "zlib"
+require_relative "circuit"
+require_relative "executor"
+
+module MirrorsSDK
+  # Error messages are fixed codes and never include credentials or evidence.
+  class TransportError < StandardError
+    attr_reader :reason, :permanent
+
+    def initialize(reason, permanent: false)
+      @reason, @permanent = reason, permanent
+      super(reason)
+    end
+  end
+
+  class Transport
+    RESPONSE_LIMIT = 65_536
+    DeadlineExceeded = Class.new(StandardError)
+    private_constant :DeadlineExceeded
+
+    # JSON's default parser silently accepts duplicate keys.
+    class StrictObject < Hash
+      def []=(key, value)
+        raise JSON::ParserError, "Duplicate key" if key?(key)
+
+        super
+      end
+    end
+    private_constant :StrictObject
+
+    def initialize(config)
+      @config = config
+      @base = "#{config.api_url.sub(%r{/+\z}, '')}/v1/agents/#{config.agent_id}/runtime"
+      @lock = Mutex.new
+      @enabled = config.enabled
+      @closed = false
+      @active = {}
+      @circuits = {}
+      %w[trace trace-final mode retrieve-context].each do |name|
+        @circuits[name] = Circuit.new(config.failure_threshold, config.cooldown_ms)
+      end
+    end
+
+    def set_enabled(enabled)
+      active = @lock.synchronize do
+        @enabled = enabled
+        enabled ? [] : @active.keys
+      end
+      active.each { |token| token.cancel("disabled") }
+      nil
+    end
+
+    def close
+      active = @lock.synchronize do
+        @closed = true
+        @enabled = false
+        @active.keys
+      end
+      active.each { |token| token.cancel("closed") }
+      nil
+    end
+
+    def request(endpoint, body, deadline:, cancel: nil, final_recovery: false)
+      validate_request(endpoint, body)
+      raise TransportError.new("timeout") if deadline <= monotonic
+
+      token = Cancellation.new
+      @lock.synchronize do
+        raise TransportError.new("disabled") if @closed || !@enabled
+
+        @active[token] = true
+      end
+      unsubscribe = cancel && cancel.on_cancel { token.cancel(cancel.reason) }
+      check_canceled(token)
+      circuit_name = endpoint
+      if endpoint == "trace" && (final_recovery || JSON.parse(body)["final"] == true)
+        circuit_name = "trace-final"
+      end
+      finish = @circuits.fetch(circuit_name).acquire
+      raise TransportError.new("circuit_open") unless finish
+
+      remaining = deadline - monotonic
+      raise TransportError.new("timeout") if remaining <= 0
+
+      result = Timeout.timeout(remaining, DeadlineExceeded) do
+        value = read_response(endpoint, body, remaining, token)
+        unless value.instance_of?(Hash) && (!block_given? || yield(value))
+          raise TransportError.new("invalid_response")
+        end
+        check_canceled(token)
+        value
+      end
+      finish.call(true)
+      result
+    rescue CanceledError
+      finish.call(nil) if finish
+      raise TransportError.new(token.reason || "canceled"), cause: nil
+    rescue DeadlineExceeded, Timeout::Error
+      finish.call(token && token.canceled? ? nil : false) if finish
+      raise TransportError.new(token && token.canceled? ? token.reason : "timeout"), cause: nil
+    rescue TransportError => error
+      finish.call(token && token.canceled? ? nil : false) if finish
+      raise TransportError.new(token.reason), cause: nil if token && token.canceled?
+
+      raise error, cause: nil
+    rescue StandardError
+      finish.call(token && token.canceled? ? nil : false) if finish
+      raise TransportError.new(token && token.canceled? ? token.reason : "transport"), cause: nil
+    ensure
+      unsubscribe.call if unsubscribe
+      @lock.synchronize { @active.delete(token) } if token
+    end
+
+    private
+
+    def validate_request(endpoint, body)
+      valid = %w[trace mode retrieve-context].include?(endpoint) && ((endpoint == "mode") == body.nil?)
+      valid &&= body.nil? || (body.instance_of?(String) && body.bytesize <= 1_048_576)
+      if valid && endpoint == "trace"
+        begin
+          valid = JSON.parse(body).instance_of?(Hash)
+        rescue JSON::ParserError
+          valid = false
+        end
+      end
+      raise TransportError.new("invalid_request", permanent: true) unless valid
+    end
+
+    def read_response(endpoint, body, timeout, token)
+      uri = URI.parse("#{@base}/#{endpoint}")
+      # Explicit nil disables environment proxy discovery and credential forwarding.
+      http = Net::HTTP.new(uri.hostname, uri.port, nil)
+      http.use_ssl = uri.scheme == "https"
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+      http.max_retries = 0
+      request = (body.nil? ? Net::HTTP::Get : Net::HTTP::Post).new(uri.request_uri)
+      request["authorization"] = "Bearer #{@config.api_key}"
+      request["content-type"] = "application/json"
+      request["accept-encoding"] = "identity"
+      request["x-mirrors-protocol"] = endpoint == "trace" ? "3" : "1"
+      request["idempotency-key"] = Digest::SHA256.hexdigest("#{endpoint}\n#{body}")
+      request.body = body unless body.nil?
+      unsubscribe = token.on_cancel { http.finish if http.started? }
+      check_canceled(token)
+      http.start do
+        check_canceled(token)
+        http.request(request) do |response|
+          status = response.code.to_i
+          unless (200...300).cover?(status)
+            permanent = (400...500).cover?(status) && ![408, 429].include?(status)
+            raise TransportError.new(permanent ? "rejected" : "transport", permanent: permanent)
+          end
+          return parse_body(response, token)
+        end
+      end
+    ensure
+      unsubscribe.call if unsubscribe
+    end
+
+    def parse_body(response, token)
+      encoding = (response["content-encoding"] || "identity").downcase
+      unless %w[identity gzip deflate].include?(encoding)
+        raise TransportError.new("invalid_response")
+      end
+      raw = String.new(encoding: Encoding::BINARY)
+      response.read_body do |chunk|
+        check_canceled(token)
+        raise TransportError.new("response_too_large") if raw.bytesize + chunk.bytesize > RESPONSE_LIMIT
+
+        raw << chunk
+      end
+      bytes = encoding == "identity" ? raw : inflate(raw, encoding)
+      bytes.force_encoding(Encoding::UTF_8)
+      raise TransportError.new("invalid_response") unless bytes.valid_encoding?
+
+      plain(JSON.parse(bytes, object_class: StrictObject, max_nesting: 64, allow_nan: false, create_additions: false))
+    rescue JSON::ParserError, Zlib::Error, EncodingError
+      raise TransportError.new("invalid_response"), cause: nil
+    end
+
+    def inflate(raw, encoding)
+      decoder = Zlib::Inflate.new(encoding == "gzip" ? Zlib::MAX_WBITS + 16 : Zlib::MAX_WBITS)
+      output = String.new(encoding: Encoding::BINARY)
+      decoder.inflate(raw) do |chunk|
+        raise TransportError.new("response_too_large") if output.bytesize + chunk.bytesize > RESPONSE_LIMIT
+
+        output << chunk
+      end
+      unless decoder.finished? && decoder.total_in == raw.bytesize
+        raise TransportError.new("invalid_response")
+      end
+      output
+    ensure
+      decoder.close if decoder
+    end
+
+    def plain(value)
+      case value
+      when Hash then value.each_with_object({}) { |(key, item), output| output[key] = plain(item) }
+      when Array then value.map { |item| plain(item) }
+      else value
+      end
+    end
+
+    def check_canceled(token)
+      raise CanceledError.new(token.reason) if token.canceled?
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/mirrors_sdk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MirrorsSDK
+  VERSION = "0.1.0"
+end