zer0-image-generator 0.6.0 → 0.8.0

data/lib/zer0_image_generator/http.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+require "timeout"
+
+require_relative "logging"
+
+module Zer0ImageGenerator
+  # Non-2xx HTTP response, with parsed body + headers when possible.
+  #
+  # Ported from preview_generator.py `HttpStatusError`. One naming caveat: the
+  # Python class exposes BOTH `str(exc)` (the constructor summary) and a
+  # separate `exc.message()` method (the parsed provider error). Ruby's
+  # `Exception#message` is already the constructor summary, so the parsed
+  # provider error lives under `#error_message` here — renaming `#message`
+  # would break every `raise`/log site that expects the summary string.
+  class HttpStatusError < StandardError
+    attr_reader :status, :body, :url, :headers
+
+    def initialize(status, body, url, headers = nil)
+      @status = status
+      # Keep the body as raw bytes: providers sometimes send non-UTF-8 error
+      # payloads and we must not lose them to an eager transcode.
+      @body = (body || "").b
+      @url = url
+      # Header keys are lower-cased so `retry-after` is found regardless of the
+      # server's casing (mirrors the Python dict comprehension).
+      @headers = {}
+      (headers || {}).each { |key, value| @headers[key.to_s.downcase] = value }
+      super("HTTP #{status} from #{url}: #{error_message[0, 300]}")
+    end
+
+    # Server-requested backoff: the Retry-After header (what Anthropic/OpenAI/
+    # xAI actually send on 429), falling back to a JSON body field.
+    def retry_after
+      header = @headers["retry-after"]
+      unless header.nil? || header.to_s.empty?
+        value = to_float(header)
+        return value unless value.nil?
+      end
+      data = json
+      if data.is_a?(Hash)
+        # Python's `data.get("retry_after", 0) or 0` collapses every falsy value
+        # (missing, null, 0, "") to 0 before the float() call.
+        raw = data["retry_after"]
+        raw = 0 if py_falsy?(raw)
+        value = to_float(raw)
+        return value unless value.nil?
+      end
+      0.0
+    end
+
+    # Parsed JSON body, or nil when the body is not valid JSON. `scrub` gives
+    # us CPython's `bytes.decode("utf-8", "replace")` — invalid bytes become
+    # U+FFFD rather than raising.
+    def json
+      JSON.parse(decoded_body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # The human-readable provider error. This is Python's `HttpStatusError.
+    # message()`, deliberately NOT named `message` (see the class comment).
+    def error_message
+      data = json
+      if data.is_a?(Hash)
+        err = data["error"]
+        return py_str(err["message"]) if err.is_a?(Hash) && py_truthy?(err["message"])
+        # A bare string `error` is returned even when empty — no truthiness
+        # gate here, matching the oracle.
+        return err if err.is_a?(String)
+        return py_str(data["detail"]) if py_truthy?(data["detail"])
+      end
+      decoded_body[0, 500]
+    end
+
+    private
+
+    def decoded_body
+      @body.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    def to_float(value)
+      Float(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    # CPython truthiness over the scalar/collection shapes a JSON value takes.
+    def py_truthy?(value)
+      case value
+      when nil, false then false
+      when String, Array, Hash then !value.empty?
+      when Numeric then value != 0
+      else true
+      end
+    end
+
+    def py_falsy?(value)
+      !py_truthy?(value)
+    end
+
+    # Python f-string interpolation goes through str(): booleans and nil print
+    # capitalized, everything else via to_s.
+    def py_str(value)
+      case value
+      when String then value
+      when true then "True"
+      when false then "False"
+      when nil then "None"
+      else value.to_s
+      end
+    end
+  end
+
+  # HTTP layer — Net::HTTP only, no third-party deps (parity with the Python
+  # engine's urllib-only stance). The AnthropicClient and the image providers
+  # call these as an injectable transport seam; a Rails app fakes `.json` /
+  # `.multipart` the same way the tests do.
+  module Http
+    module_function
+
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 529].freeze
+
+    # urllib.error.URLError + OSError (which covers ConnectionError and
+    # TimeoutError) map onto this set: DNS/socket failures, Errno::*, broken
+    # streams, and read/open timeouts. HttpStatusError is handled separately.
+    TRANSPORT_ERRORS = [
+      SocketError, SystemCallError, IOError, EOFError, Timeout::Error,
+      Net::OpenTimeout, Net::ReadTimeout, Net::HTTPBadResponse, Net::ProtocolError
+    ].freeze
+
+    # urllib follows up to 10 redirects by default; matching that keeps
+    # `download_to` behavior identical for providers that return 3xx image URLs.
+    MAX_REDIRECTS = 10
+    REDIRECT_STATUSES = [301, 302, 303, 307, 308].freeze
+
+    def request(url, method: "GET", headers: nil, data: nil, timeout: 120)
+      uri = URI(url)
+      redirects = 0
+      loop do
+        response = perform(uri, method, headers, data, timeout)
+        code = response.code.to_i
+        location = response["location"]
+        if REDIRECT_STATUSES.include?(code) && location && method.to_s.upcase == "GET" &&
+           redirects < MAX_REDIRECTS
+          redirects += 1
+          uri = URI.join(uri.to_s, location)
+          next
+        end
+        return [code, header_hash(response), (response.body || "").b] if code >= 200 && code < 300
+
+        raise HttpStatusError.new(code, response.body, url, header_hash(response))
+      end
+    end
+
+    def json(url, payload, headers, timeout: 900)
+      body = JSON.generate(payload)
+      # Caller-supplied headers win on conflict, exactly like `{**base, **headers}`.
+      hdrs = { "Content-Type" => "application/json" }.merge(headers)
+      _, _, raw = request(url, method: "POST", headers: hdrs, data: body, timeout: timeout)
+      JSON.parse(raw)
+    end
+
+    # Encode multipart/form-data. `files` entries are [field, filename, content,
+    # mime]. The body is assembled as raw bytes so binary image content survives
+    # untouched; the boundary and layout match the oracle byte for byte.
+    def build_multipart(fields, files)
+      boundary = "----zer0-#{SecureRandom.hex(16)}"
+      buf = +"".b
+      fields.each do |name, value|
+        buf << "--#{boundary}\r\n".b
+        buf << "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n".b
+        buf << value.to_s.b
+        buf << "\r\n".b
+      end
+      files.each do |name, filename, content, mime|
+        buf << "--#{boundary}\r\n".b
+        buf << "Content-Disposition: form-data; name=\"#{name}\"; filename=\"#{filename}\"\r\n".b
+        buf << "Content-Type: #{mime}\r\n\r\n".b
+        buf << content.b
+        buf << "\r\n".b
+      end
+      buf << "--#{boundary}--\r\n".b
+      [buf, "multipart/form-data; boundary=#{boundary}"]
+    end
+
+    def multipart(url, fields, files, headers, timeout: 900)
+      body, content_type = build_multipart(fields, files)
+      hdrs = { "Content-Type" => content_type }.merge(headers)
+      _, _, raw = request(url, method: "POST", headers: hdrs, data: body, timeout: timeout)
+      JSON.parse(raw)
+    end
+
+    def download_to(url, dest, timeout: 120)
+      _, _, raw = request(url, method: "GET", headers: {}, data: nil, timeout: timeout)
+      File.binwrite(dest.to_s, raw)
+      nil
+    end
+
+    # Run the block; retry transport errors and retryable HTTP statuses.
+    # Backoff 2s/4s/8s (or the server's Retry-After when larger, capped 60s).
+    # `sleeper` is injectable so tests observe the wait ladder without sleeping;
+    # it defaults to a real sleep for production callers.
+    def with_retries(what, attempts: 4, sleeper: nil)
+      sleeper ||= ->(seconds) { sleep(seconds) }
+      delay = 2.0
+      1.upto(attempts) do |attempt|
+        begin
+          return yield
+        rescue HttpStatusError => e
+          raise if !RETRYABLE_STATUSES.include?(e.status) || attempt == attempts
+
+          wait = [[delay, e.retry_after].max, 60.0].min
+          Logging.warn("#{what}: HTTP #{e.status}, retrying in #{format('%.0f', wait)}s " \
+                       "(attempt #{attempt}/#{attempts})")
+        rescue *TRANSPORT_ERRORS => e
+          raise if attempt == attempts
+
+          wait = delay
+          Logging.warn("#{what}: #{e.class.name}: #{e.message}; retrying in #{format('%.0f', wait)}s " \
+                       "(attempt #{attempt}/#{attempts})")
+        end
+        sleeper.call(wait)
+        delay *= 2
+      end
+    end
+
+    # --- internals ------------------------------------------------------------
+
+    def perform(uri, method, headers, data, timeout)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      request = request_class(method).new(uri.request_uri)
+      (headers || {}).each { |key, value| request[key] = value }
+      request.body = data unless data.nil?
+      http.start { |conn| conn.request(request) }
+    end
+    private_class_method :perform
+
+    def request_class(method)
+      case method.to_s.upcase
+      when "GET" then Net::HTTP::Get
+      when "POST" then Net::HTTP::Post
+      when "PUT" then Net::HTTP::Put
+      when "DELETE" then Net::HTTP::Delete
+      else Net::HTTP::Get
+      end
+    end
+    private_class_method :request_class
+
+    def header_hash(response)
+      hash = {}
+      response.each_header { |key, value| hash[key] = value }
+      hash
+    end
+    private_class_method :header_hash
+  end
+end

data/lib/zer0_image_generator/library.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Zer0ImageGenerator
+  # Byte-exact re-implementation of CPython's `json.dumps(obj, indent=2)`.
+  #
+  # The example library's MANIFEST.json is a committed artifact produced by
+  # `tools/svg/freesvg.py`'s `_write_json` (json.dump indent=2 + a trailing
+  # newline). Promoting from Ruby has to yield a byte-for-byte identical file so
+  # the git diff is only the new entry — which rules out Ruby's own
+  # JSON.pretty_generate: its empty-container layout, its float rendering and,
+  # above all, its non-ASCII handling all differ from CPython. This encoder
+  # pins every one of those to CPython's, so the manifest round-trips cleanly no
+  # matter which language wrote it last.
+  module PyJson
+    module_function
+
+    def dump(obj)
+      out = +""
+      encode(obj, 0, out)
+      out
+    end
+
+    # `indent` is the column the CURRENT value's closing bracket sits at; child
+    # members are written at indent + 2, matching json.dumps(indent=2).
+    def encode(obj, indent, out)
+      case obj
+      when Hash then encode_object(obj, indent, out)
+      when Array then encode_array(obj, indent, out)
+      when String then out << encode_string(obj)
+      when Integer then out << obj.to_s
+      when Float then out << float_repr(obj)
+      when true then out << "true"
+      when false then out << "false"
+      when nil then out << "null"
+      else
+        # json.dumps would raise TypeError here; keep the failure explicit
+        # rather than silently coercing something the manifest never contains.
+        raise ArgumentError, "PyJson cannot encode #{obj.class}"
+      end
+    end
+
+    def encode_object(hash, indent, out)
+      # json.dumps(indent=2) collapses empty containers to `{}` / `[]` with no
+      # inner newline; every non-empty container opens a newline-delimited block.
+      if hash.empty?
+        out << "{}"
+        return
+      end
+      inner = indent + 2
+      pad = " " * inner
+      out << "{\n"
+      first = true
+      hash.each do |key, value|
+        out << ",\n" unless first
+        first = false
+        out << pad << encode_string(key.to_s) << ": "
+        encode(value, inner, out)
+      end
+      out << "\n" << (" " * indent) << "}"
+    end
+
+    def encode_array(array, indent, out)
+      if array.empty?
+        out << "[]"
+        return
+      end
+      inner = indent + 2
+      pad = " " * inner
+      out << "[\n"
+      first = true
+      array.each do |value|
+        out << ",\n" unless first
+        first = false
+        out << pad
+        encode(value, inner, out)
+      end
+      out << "\n" << (" " * indent) << "]"
+    end
+
+    # The named short escapes json.dumps emits; everything else in the control
+    # range falls through to \u00xx below.
+    ESCAPES = {
+      "\"" => '\\"', "\\" => "\\\\", "\b" => "\\b", "\f" => "\\f",
+      "\n" => "\\n", "\r" => "\\r", "\t" => "\\t"
+    }.freeze
+
+    # Mirrors json.encoder.py_encode_basestring_ascii (ensure_ascii=True): only
+    # 0x20..0x7e survive literally; 0x7f and every non-ASCII codepoint is
+    # escaped, astral characters as a UTF-16 surrogate pair.
+    def encode_string(str)
+      out = +'"'
+      str.each_char do |ch|
+        if (esc = ESCAPES[ch])
+          out << esc
+          next
+        end
+        cp = ch.ord
+        if cp < 0x20
+          out << format("\\u%04x", cp)
+        elsif cp < 0x7f
+          out << ch
+        elsif cp > 0xffff
+          value = cp - 0x10000
+          out << format("\\u%04x\\u%04x", 0xd800 + (value >> 10), 0xdc00 + (value & 0x3ff))
+        else
+          out << format("\\u%04x", cp)
+        end
+      end
+      out << '"'
+      out
+    end
+
+    # json.dumps renders floats via float.__repr__ (shortest round-tripping
+    # form). Ruby's Float#to_s is also shortest-round-trip and agrees with
+    # CPython across the whole non-exponent range the manifest uses (size_kb is
+    # always a small positive value like 0.1 or 148.1). The two disagree only on
+    # exponent formatting (Ruby "1.0e+20" vs CPython "1e+20") and the special
+    # values, which manifest data never contains — guarded here for honesty.
+    def float_repr(value)
+      return "NaN" if value.nan?
+      return value.positive? ? "Infinity" : "-Infinity" if value.infinite?
+
+      value.to_s
+    end
+  end
+
+  # Reader/writer for the SVG example library manifest (tools/svg/library/
+  # MANIFEST.json). One entry per example — first-party samples and vetted
+  # external art alike — each carrying provenance, license and lint status so a
+  # tag search covers the whole library from one place (see library/README.md).
+  #
+  # Writes go through PyJson so a Ruby-authored manifest is byte-identical to
+  # what freesvg.py's `_write_json` produces; reads use stdlib JSON, which is a
+  # faithful stand-in for Python's json.load (both preserve key insertion order
+  # and the Integer/Float distinction that the manifest's size_kb relies on).
+  class Library
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+    end
+
+    # Parsed manifest, or nil when the file is missing or corrupt — mirroring
+    # freesvg.py's `_read_json`, which swallows exactly OSError/ValueError and
+    # returns None so a damaged manifest degrades to "empty" rather than
+    # crashing the caller.
+    def read
+      JSON.parse(File.read(@path))
+    rescue JSON::ParserError, SystemCallError, IOError
+      nil
+    end
+
+    # The `_read_json(...) or {"entries": []}` default freesvg.py falls back to.
+    def load
+      read || { "entries" => [] }
+    end
+
+    def entries
+      Array(load["entries"])
+    end
+
+    def has_file?(file)
+      entries.any? { |entry| entry["file"] == file }
+    end
+
+    def find(file)
+      entries.find { |entry| entry["file"] == file }
+    end
+
+    # Tag search is the library's primary lookup (README: "Search MANIFEST.json
+    # by tags"). Case-insensitive, since manifest tags are stored lowercased.
+    def by_tag(tag)
+      needle = tag.to_s.downcase
+      entries.select do |entry|
+        Array(entry["tags"]).any? { |t| t.to_s.downcase == needle }
+      end
+    end
+
+    # Append one entry, re-sort by file, and rewrite byte-identically. Matches
+    # freesvg.py's promote tail: it reads the manifest fresh, appends, sorts by
+    # the "file" key, and writes with indent=2 + trailing newline. Returns the
+    # entry. Callers guard against duplicates via #has_file? first.
+    def add_entry(entry)
+      manifest = load
+      manifest["entries"] ||= []
+      manifest["entries"] << entry
+      manifest["entries"] = manifest["entries"].sort_by { |e| e["file"] }
+      write(manifest)
+      entry
+    end
+
+    def write(manifest)
+      FileUtils.mkdir_p(File.dirname(@path))
+      # _write_json: json.dump(..., indent=2) then a single trailing newline.
+      File.write(@path, PyJson.dump(manifest) + "\n")
+    end
+  end
+end

data/lib/zer0_image_generator/logging.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Zer0ImageGenerator
+  # Stands in for the Python engine's `sys.exit(1)`. The engine is now driven
+  # by a Rails app as well as a CLI, and a web request must not be able to
+  # take the process down — CLI.main is the only place that turns this back
+  # into a process exit status, so the code path (and the status) is unchanged
+  # for CLI users.
+  class ExitError < StandardError
+    attr_reader :status
+
+    def initialize(message, status = 1)
+      super(message)
+      @status = status
+    end
+  end
+
+  module Colors
+    RED = "\e[0;31m"
+    GREEN = "\e[0;32m"
+    YELLOW = "\e[1;33m"
+    BLUE = "\e[0;34m"
+    CYAN = "\e[0;36m"
+    PURPLE = "\e[0;35m"
+    BOLD = "\e[1m"
+    NC = "\e[0m"
+  end
+
+  # Default log destination: reproduces the Python engine's terminal output
+  # byte for byte (same colors, same stream split, same blank lines). Nothing
+  # in the Runner or the CLI touches $stdout directly, so a web UI can hand in
+  # a sink that streams the very same run to a browser instead.
+  #
+  # Sink contract — three messages:
+  #   log(message, level)  level is one of :info :step :success :warning
+  #                        :error :debug
+  #   say(text)            a bare line (the engine's plain `print` calls)
+  #   header(title)        the boxed section banner
+  class StreamSink
+    LEVEL_COLORS = {
+      info: Colors::BLUE,
+      step: Colors::CYAN,
+      success: Colors::GREEN,
+      warning: Colors::YELLOW,
+      error: Colors::RED,
+      debug: Colors::PURPLE
+    }.freeze
+
+    # The levels the Python engine routes to sys.stderr.
+    STDERR_LEVELS = %i[warning error debug].freeze
+
+    RULE = ("=" * 64).freeze
+
+    def initialize(out: $stdout, err: $stderr)
+      @out = out
+      @err = err
+      @lock = Mutex.new
+    end
+
+    def log(message, level)
+      color = LEVEL_COLORS.fetch(level, Colors::NC)
+      stream = STDERR_LEVELS.include?(level) ? @err : @out
+      emit(stream, "#{color}[#{level.to_s.upcase}]#{Colors::NC} #{message}\n")
+    end
+
+    def say(text)
+      emit(@out, "#{text}\n")
+    end
+
+    def header(title)
+      emit(@out, "\n#{Colors::CYAN}#{RULE}#{Colors::NC}\n" \
+                 "  #{Colors::GREEN}#{title}#{Colors::NC}\n" \
+                 "#{Colors::CYAN}#{RULE}#{Colors::NC}\n\n")
+    end
+
+    private
+
+    # One write per line. Python's GIL gave `print` de-facto line atomicity
+    # that worker threads relied on; Ruby has to ask for it explicitly or
+    # parallel runs shred each other's output.
+    def emit(stream, text)
+      @lock.synchronize { stream.write(text) }
+    end
+  end
+
+  # Holds what the Python engine kept in module globals: the active sink, the
+  # VERBOSE switch that gates debug(), and the optional --log-file mirror.
+  class Logger
+    # Matches the Python's time.strftime("%Y-%m-%d %H:%M:%S").
+    STAMP_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+    attr_accessor :sink, :verbose
+
+    def initialize(sink: nil, verbose: false)
+      @sink = sink || StreamSink.new
+      @verbose = verbose
+      @log_file = nil
+      @file_lock = Mutex.new
+    end
+
+    def log(message, level = :info)
+      text = message.to_s
+      key = level.to_sym
+      @sink.log(text, key)
+      mirror(text, key)
+      nil
+    end
+
+    def info(message)
+      log(message, :info)
+    end
+
+    def step(message)
+      log(message, :step)
+    end
+
+    def success(message)
+      log(message, :success)
+    end
+
+    def warn(message)
+      log(message, :warning)
+    end
+
+    def debug(message)
+      log(message, :debug) if @verbose
+    end
+
+    def error_exit(message, status = 1)
+      log(message, :error)
+      raise ExitError.new(message.to_s, status)
+    end
+
+    # The engine's bare `print(...)` / `print()` calls: plain stdout lines that
+    # deliberately bypass the --log-file mirror.
+    def say(text = "")
+      @sink.say(text.to_s)
+      nil
+    end
+
+    def print_header(title)
+      @sink.header(title.to_s)
+      nil
+    end
+
+    # Returns false after warning (never raises) — the Python catches OSError
+    # here so an unwritable --log-file downgrades to a warning instead of
+    # aborting a run that may already have cost money.
+    def open_log_file(path)
+      @file_lock.synchronize { @log_file = File.open(path, "w:UTF-8") }
+      true
+    rescue SystemCallError => e
+      warn("Cannot open log file: #{e}")
+      false
+    end
+
+    def close_log_file
+      @file_lock.synchronize do
+        return nil if @log_file.nil?
+
+        @log_file.close
+        @log_file = nil
+      end
+    end
+
+    private
+
+    def mirror(message, level)
+      @file_lock.synchronize do
+        return nil if @log_file.nil?
+
+        @log_file.write("#{Time.now.strftime(STAMP_FORMAT)} [#{level.to_s.upcase}] #{message}\n")
+        @log_file.flush
+      end
+    end
+  end
+
+  # Process-wide logger, the direct analogue of the engine's module-level
+  # log()/info()/warn()/VERBOSE. Runner and CLI take an injected logger and
+  # only fall back to this one, so a Rails process can run several jobs with
+  # separate sinks without touching global state.
+  module Logging
+    class << self
+      attr_writer :logger
+
+      def logger
+        @logger ||= Logger.new
+      end
+
+      # The engine's VERBOSE global.
+      def verbose
+        logger.verbose
+      end
+
+      def verbose=(value)
+        logger.verbose = value
+      end
+
+      def log(message, level = :info)
+        logger.log(message, level)
+      end
+
+      def info(message)
+        logger.info(message)
+      end
+
+      def step(message)
+        logger.step(message)
+      end
+
+      def success(message)
+        logger.success(message)
+      end
+
+      def warn(message)
+        logger.warn(message)
+      end
+
+      def debug(message)
+        logger.debug(message)
+      end
+
+      def error_exit(message, status = 1)
+        logger.error_exit(message, status)
+      end
+
+      def say(text = "")
+        logger.say(text)
+      end
+
+      def print_header(title)
+        logger.print_header(title)
+      end
+    end
+  end
+end