svgpng 0.1.0

data/lib/svgpng/font_inputs.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Svgpng
+  # Shape/size checks only: native metadata validation follows before rendering.
+  class FontInputs
+    attr_reader :fonts, :fallback_fonts
+
+    def initialize(fonts:, fallback_fonts:)
+      raise InputError, "fonts must be a Hash" unless fonts.is_a?(Hash)
+      raise InputError, "fallback_fonts must be an Array" unless fallback_fonts.is_a?(Array)
+
+      check_count!(fonts, fallback_fonts)
+      @fonts = fonts.to_h { |family, faces| normalize_family(family, faces) }.freeze
+      @fallback_fonts = validate_faces(fallback_fonts)
+      check_total_bytes!
+
+      freeze
+    end
+
+    private
+
+    def check_count!(fonts, fallback_fonts)
+      count = fallback_fonts.length
+      fonts.each_value { |faces| count += faces.is_a?(Array) ? faces.length : 1 }
+      raise LimitError, "Too many font faces (maximum #{Limits::FONT_COUNT})" if count > Limits::FONT_COUNT
+    end
+
+    def normalize_family(family, faces)
+      raise InputError, "Font family keys must be nonempty Strings" unless family.is_a?(String) && !family.strip.empty?
+
+      entries = faces.is_a?(Array) ? faces : [faces]
+      raise InputError, "Font family must have at least one face" if entries.empty?
+
+      [family.dup.freeze, validate_faces(entries)]
+    end
+
+    def check_total_bytes!
+      total = @fonts.values.flatten.sum { |face| face.bytes.bytesize } +
+              @fallback_fonts.sum { |face| face.bytes.bytesize }
+      raise LimitError, "Total font bytes exceed #{Limits::TOTAL_FONT_BYTES}" if total > Limits::TOTAL_FONT_BYTES
+    end
+
+    def validate_faces(faces)
+      raise InputError, "Every font must be a Svgpng::FontFace" unless faces.all?(FontFace)
+
+      faces.dup.freeze
+    end
+  end
+end

data/lib/svgpng/font_warnings.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "result"
+
+module Svgpng
+  # Collects ordered substitution diagnostics emitted by a renderer.
+  class FontWarnings
+    def initialize
+      @warnings = []
+      @keys = {}
+    end
+
+    # rubocop:disable-next Metrics/ParameterLists -- Mirrors the native event fields.
+    def add(requested_family:, selected_family:, style:, weight:, stretch:, scalars:)
+      normalized_scalars = normalize_scalars(scalars)
+      warning = FontSubstitutionWarning.new(requested_family: requested_family,
+                                            selected_family: selected_family,
+                                            style: style, weight: weight,
+                                            stretch: stretch, scalars: normalized_scalars)
+      key = [warning.requested_family, warning.selected_family, warning.style,
+             warning.weight, warning.stretch, warning.scalars]
+      @warnings << warning unless @keys.key?(key)
+      @keys[key] = true
+      warning
+    end
+
+    def warnings
+      @warnings.dup.freeze
+    end
+
+    private
+
+    def normalize_scalars(scalars)
+      unless scalars.is_a?(Array) && scalars.all? { |scalar| valid_scalar?(scalar) }
+        raise ArgumentError, "scalars must be Unicode scalar values (0..0x10FFFF, excluding surrogates)"
+      end
+
+      scalars.uniq.sort.freeze
+    end
+
+    def valid_scalar?(scalar)
+      scalar.is_a?(Integer) && scalar.between?(0, 0x10FFFF) && !scalar.between?(0xD800, 0xDFFF)
+    end
+  end
+end

data/lib/svgpng/limits.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Svgpng
+  module Limits
+    SVG_BYTES = 16 * 1024 * 1024
+    FONT_COUNT = 64
+    FONT_BYTES = 32 * 1024 * 1024
+    TOTAL_FONT_BYTES = 128 * 1024 * 1024
+  end
+end

data/lib/svgpng/native.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "render_profile"
+require "fiddle"
+require "fiddle/struct"
+require_relative "native_render"
+
+module Svgpng
+  # Opens only the artifact belonging to this installed gem, on explicit request.
+  module Native
+    SUPPORTED_TARGETS = %w[arm64-darwin x86_64-darwin x86_64-linux aarch64-linux
+                           x86_64-linux-musl aarch64-linux-musl x64-mingw-ucrt].map(&:freeze).freeze
+    SUFFIXES = { "darwin" => "dylib", "linux" => "so", "mingw" => "dll" }.freeze
+
+    def self.load
+      Library.new
+    end
+
+    def self.packaged_library_path
+      platform = Gem::Platform.local
+      target = SUPPORTED_TARGETS.find { |candidate| candidate == platform.to_s }
+      target ||= compatible_target(platform)
+      raise UnsupportedPlatformError.new(platform: platform.to_s, supported_targets: SUPPORTED_TARGETS) unless target
+
+      suffix = SUFFIXES.fetch(platform.os)
+      File.join(File.realpath(__dir__), "native", target, "svgpng.#{suffix}")
+    end
+    private_class_method :packaged_library_path
+
+    def self.compatible_target(platform)
+      SUPPORTED_TARGETS.find do |name|
+        candidate = Gem::Platform.new(name)
+        next false unless candidate.cpu == platform.cpu && candidate.os == platform.os
+
+        case platform.os
+        when "darwin" then true
+        when "linux" then candidate.version == (platform.version == "gnu" ? nil : platform.version)
+        else false
+        end
+      end
+    end
+    private_class_method :compatible_target
+
+    # This binding is a pixel conversion primitive, not a rendering backend.
+    # Keep the two ownership-related ABI primitives and their guards in one binding.
+    # rubocop:disable-next Metrics/ClassLength
+    class Library
+      include RenderBinding
+
+      SIZE_MAX = (1 << (Fiddle::SIZEOF_SIZE_T * 8)) - 1
+      POINTER_MAX = (1 << (Fiddle::SIZEOF_VOIDP * 8)) - 1
+      STATUS_ERRORS = { 1 => InputError, 2 => LimitError, 3 => LimitError,
+                        4 => InputError, 5 => InputError }.freeze
+      STATUS_NAMES = { 1 => "invalid argument", 2 => "arithmetic overflow", 3 => "limit exceeded",
+                       4 => "buffer too small", 5 => "overlapping buffers" }.freeze
+      PNG_OUTPUT = Fiddle::CStructBuilder.create(Fiddle::CStruct, [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T],
+                                                 %w[bytes length])
+      PNG_STATUS_ERRORS = { 1 => InputError, 2 => LimitError, 3 => LimitError, 4 => InputError,
+                            5 => EncodingError, 6 => EncodingError, 7 => NativeError }.freeze
+      PNG_STATUS_NAMES = { 1 => "invalid argument", 2 => "arithmetic overflow", 3 => "limit exceeded",
+                           4 => "buffer too small", 5 => "allocation failed", 6 => "encoding failed",
+                           7 => "dependency version mismatch" }.freeze
+
+      def initialize
+        path = Native.send(:packaged_library_path)
+        check_packaged_file(path)
+        @handle = Fiddle::Handle.new(path, Fiddle::RTLD_NOW)
+        arguments = [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_SIZE_T,
+                     Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_SIZE_T,
+                     Fiddle::TYPE_SIZE_T, Fiddle::TYPE_SIZE_T]
+        @convert = Fiddle::Function.new(@handle["svgpng_v1_rgba_to_straight"], arguments, Fiddle::TYPE_INT)
+      rescue Fiddle::DLError => e
+        raise NativeError, "Cannot load packaged SVGPNG RGBA ABI: #{e.message}"
+      end
+
+      def rgba_to_straight(source, width:, height:, source_stride: nil, destination_stride: nil)
+        source = snapshot_source(source)
+        source_stride = width.is_a?(Integer) ? width * 4 : nil if source_stride.nil?
+        destination_stride = width.is_a?(Integer) ? width * 4 : nil if destination_stride.nil?
+        source_bytes, destination_bytes = validate_buffers(source, width, height, source_stride, destination_stride)
+        convert(source, width, height, source_stride, destination_stride, source_bytes, destination_bytes)
+      end
+
+      def encode_rgba(source, width:, height:, source_stride: nil)
+        source = snapshot_source(source)
+        source_stride = width.is_a?(Integer) ? width * 4 : nil if source_stride.nil?
+        source_bytes = validate_buffers(source, width, height, source_stride, source_stride).first
+        encode_png(source, source_bytes, source_stride, width, height)
+      end
+
+      private
+
+      def snapshot_source(source)
+        # Class-side checking cannot be overridden by the untrusted source object.
+        # rubocop:disable-next Style/CaseEquality
+        raise InputError, "RGBA source must be bytes" unless String === source
+
+        # Normalize subclass methods and isolate later caller mutation before checking capacity.
+        String.new(source).byteslice(0, RenderProfile::MAX_BUFFER_BYTES).freeze
+      end
+
+      def encoder_functions
+        @encoder_functions ||= begin
+          arguments = [Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_SIZE_T,
+                       Fiddle::TYPE_SIZE_T, Fiddle::TYPE_SIZE_T, Fiddle::TYPE_VOIDP]
+          encode = Fiddle::Function.new(@handle["svgpng_v1_png_encode"], arguments, Fiddle::TYPE_INT)
+          release = Fiddle::Function.new(@handle["svgpng_v1_png_free"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_VOID)
+          [encode, release].freeze
+        end
+      rescue Fiddle::DLError => e
+        raise NativeError, "Cannot load packaged SVGPNG encoder ABI: #{e.message}"
+      end
+
+      # Keep shim release ahead of both Ruby buffer releases on every exit path.
+      # rubocop:disable-next Metrics/MethodLength, Metrics/AbcSize
+      def encode_png(source, source_bytes, source_stride, width, height)
+        encode, release = encoder_functions
+        output = PNG_OUTPUT.malloc(Fiddle::RUBY_FREE)
+        output.bytes = 0
+        output.length = 0
+        input = Fiddle::Pointer.malloc(source_bytes, Fiddle::RUBY_FREE)
+        input[0, source_bytes] = source.byteslice(0, source_bytes)
+        status = encode.call(input, source_bytes, source_stride, width, height, output.to_ptr)
+        check_png_status(status)
+        copy_png(output)
+      ensure
+        begin
+          release.call(output.to_ptr) if output
+        ensure
+          output&.to_ptr&.call_free
+          input&.call_free
+        end
+      end
+
+      def check_png_status(status)
+        return if status.zero?
+
+        message = PNG_STATUS_NAMES.fetch(status, "unknown status #{status}")
+        raise PNG_STATUS_ERRORS.fetch(status, NativeError), "SVGPNG PNG encoding: #{message}"
+      end
+
+      def copy_png(output)
+        length = output.length
+        raise NativeError, "PNG encoder returned an empty output" unless length.positive?
+        raise LimitError, "PNG encoder output exceeds limits" if length > RenderProfile::MAX_BUFFER_BYTES
+
+        address = output.bytes.to_i
+        if !address.positive? || address > POINTER_MAX - length
+          raise NativeError, "PNG encoder returned an invalid output pointer"
+        end
+
+        Fiddle::Pointer.new(address)[0, length].b
+      end
+
+      def check_packaged_file(path)
+        unless File.file?(path) && !File.symlink?(path) && File.realpath(path) == path
+          raise UnsupportedPlatformError.new(platform: Gem::Platform.local.to_s, supported_targets: SUPPORTED_TARGETS)
+        end
+      rescue Errno::ENOENT, Errno::ENOTDIR, Errno::ELOOP
+        raise UnsupportedPlatformError.new(platform: Gem::Platform.local.to_s, supported_targets: SUPPORTED_TARGETS)
+      end
+
+      # Keep all pre-allocation ABI guards together for auditing against rgba.c.
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def validate_buffers(source, width, height, source_stride, destination_stride)
+        values = [width, height, source_stride, destination_stride]
+        unless source.is_a?(String) && values.all? { |value| value.is_a?(Integer) && value.positive? }
+          raise InputError, "RGBA source must be bytes with positive integer dimensions and strides"
+        end
+        raise LimitError, "RGBA integer exceeds size_t" if values.any? { |value| value > SIZE_MAX }
+        if width > RenderProfile::MAX_DIMENSION || height > RenderProfile::MAX_DIMENSION ||
+           width * height > RenderProfile::MAX_PIXELS
+          raise LimitError, "RGBA dimensions exceed limits"
+        end
+        if [source_stride, destination_stride].min < width * 4
+          raise InputError, "RGBA stride is smaller than a pixel row"
+        end
+
+        capacities = [source_stride * height, destination_stride * height]
+        if capacities.any? { |value| value > SIZE_MAX || value > RenderProfile::MAX_BUFFER_BYTES }
+          raise LimitError, "RGBA buffer exceeds limits"
+        end
+        raise InputError, "RGBA source buffer is too small" if source.bytesize < capacities.first
+
+        capacities
+      end
+
+      # Explicit arguments mirror the checked C ABI without a second mutable descriptor.
+      # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength
+      def convert(source, width, height, source_stride, destination_stride, source_bytes, destination_bytes)
+        input = Fiddle::Pointer.malloc(source_bytes, Fiddle::RUBY_FREE)
+        output = Fiddle::Pointer.malloc(destination_bytes, Fiddle::RUBY_FREE)
+        input[0, source_bytes] = source.byteslice(0, source_bytes)
+        output[0, destination_bytes] = "\0".b * destination_bytes
+        status = @convert.call(input, source_bytes, source_stride, output, destination_bytes, destination_stride,
+                               width, height)
+        check_status(status)
+        output[0, destination_bytes].b
+      ensure
+        output&.call_free
+        input&.call_free
+      end
+
+      def check_status(status)
+        return if status.zero?
+
+        message = STATUS_NAMES.fetch(status, "unknown status #{status}")
+        raise STATUS_ERRORS.fetch(status, NativeError), "SVGPNG RGBA conversion: #{message}"
+      end
+    end
+  end
+end

data/lib/svgpng/native_render.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Svgpng
+  module Native
+    # Owns all temporary arguments and copies renderer output before releasing it.
+    module RenderBinding # rubocop:disable Metrics/ModuleLength -- Keep ABI layout and ownership guards together.
+      SIZE = Fiddle::TYPE_SIZE_T
+      PTR = Fiddle::TYPE_VOIDP
+      RENDER_OUTPUT = Fiddle::CStructBuilder.create(Fiddle::CStruct, [PTR, SIZE, PTR, SIZE],
+                                                    %w[pixels pixels_length diagnostics diagnostics_length])
+      FONT = Fiddle::CStructBuilder.create(Fiddle::CStruct, [PTR, SIZE, PTR, SIZE, PTR, SIZE, SIZE],
+                                           %w[bytes length requested_family family_length source_id source_id_length
+                                              fallback_order])
+      OPTIONS = Fiddle::CStructBuilder.create(Fiddle::CStruct,
+                                              ([Fiddle::TYPE_INT32_T] * 4) + ([Fiddle::TYPE_DOUBLE] * 5),
+                                              %w[abi_version width height background_rgba intrinsic_width
+                                                 intrinsic_height fit translate_x translate_y])
+      ERRORS = { 1 => InputError, 2 => LimitError, 3 => FontMetadataError, 4 => DuplicateFontError,
+                 5 => MissingFamilyError, 6 => MissingGlyphError, 7 => ForbiddenReferenceError,
+                 8 => NativeError, 9 => NativeError }.freeze
+      DIAGNOSTIC_LIMIT = 4 * 1024 * 1024
+
+      def root_attributes(source)
+        renderer_call(source) do |input, output, _owned|
+          status = render_functions.fetch(:root).call(input, source.bytesize, output.to_ptr)
+          check_render_status(status, output)
+          attributes = copy_diagnostics(output)
+          unless attributes.is_a?(Hash) && attributes.keys.all?(String) && attributes.values.all?(String)
+            raise NativeError, "Renderer returned invalid root attributes"
+          end
+
+          attributes
+        end
+      end
+
+      # One call owns all buffers until both output copies complete.
+      # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength
+      def render_pixels(source, layout:, fonts:)
+        renderer_call(source) do |input, output, owned|
+          options = render_options(layout, owned)
+          entries, count = render_fonts(fonts, owned)
+          status = render_functions.fetch(:render).call(input, source.bytesize, entries, count,
+                                                        options.to_ptr, output.to_ptr)
+          check_render_status(status, output)
+          unless output.pixels_length == layout.buffer_bytes
+            raise NativeError, "Renderer returned an invalid pixel buffer length"
+          end
+
+          pixels = copy_render_bytes(output.pixels, output.pixels_length, RenderProfile::MAX_BUFFER_BYTES)
+          diagnostics = copy_diagnostics(output)
+          raise NativeError, "Renderer returned invalid diagnostics" unless diagnostics.is_a?(Hash)
+
+          [pixels, diagnostics]
+        end
+      end
+
+      private
+
+      def render_functions
+        @render_functions ||= {
+          root: Fiddle::Function.new(@handle["svgpng_v1_root_attributes"], [PTR, SIZE, PTR], Fiddle::TYPE_INT),
+          render: Fiddle::Function.new(@handle["svgpng_v1_render"], [PTR, SIZE, PTR, SIZE, PTR, PTR], Fiddle::TYPE_INT),
+          free: Fiddle::Function.new(@handle["svgpng_v1_render_free"], [PTR], Fiddle::TYPE_VOID)
+        }.freeze
+      rescue Fiddle::DLError
+        raise NativeError, "Cannot load packaged SVGPNG renderer ABI"
+      end
+
+      # Release the shim descriptor before any caller-owned arguments.
+      # rubocop:disable-next Metrics/MethodLength
+      def renderer_call(source)
+        functions = render_functions
+        owned = []
+        input = own_bytes(source, owned)
+        output = RENDER_OUTPUT.new(own_buffer(RENDER_OUTPUT.size, owned))
+        output.to_ptr[0, RENDER_OUTPUT.size] = "\0" * RENDER_OUTPUT.size
+        yield input, output, owned
+      ensure
+        begin
+          functions.fetch(:free).call(output.to_ptr) if output
+        ensure
+          owned&.reverse_each(&:call_free)
+        end
+      end
+
+      def own_buffer(length, owned)
+        Fiddle::Pointer.malloc([length, 1].max, Fiddle::RUBY_FREE).tap { |pointer| owned << pointer }
+      end
+
+      def own_bytes(bytes, owned)
+        pointer = own_buffer(bytes.bytesize, owned)
+        pointer[0, bytes.bytesize] = bytes
+        pointer
+      end
+
+      # Mirror the C ABI fields directly for alignment auditing.
+      # rubocop:disable-next Metrics/AbcSize
+      def render_options(layout, owned)
+        options = OPTIONS.new(own_buffer(OPTIONS.size, owned))
+        options.abi_version = 1
+        options.width = layout.width
+        options.height = layout.height
+        options.background_rgba = layout.background.inject(0) { |value, channel| (value << 8) | channel }
+        %i[intrinsic_width intrinsic_height translate_x translate_y].each do |key|
+          options[key.to_s] = layout.public_send(key).to_f
+        end
+        options.fit = layout.scale.to_f
+        options
+      end
+
+      # Keep every borrowed font pointer beside its owned allocation.
+      # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength
+      def render_fonts(inputs, owned)
+        faces = inputs.fonts.flat_map { |family, entries| entries.map { |face| [face, family, Library::SIZE_MAX] } }
+        faces.concat(inputs.fallback_fonts.each_with_index.map { |face, order| [face, face.family || "", order] })
+        pointer = own_buffer(FONT.size * faces.length, owned)
+        faces.each_with_index do |(face, family, order), index|
+          entry = FONT.new(pointer + (index * FONT.size))
+          entry.bytes = own_bytes(face.bytes, owned)
+          entry.length = face.bytes.bytesize
+          entry.requested_family = own_bytes(family, owned)
+          entry.family_length = family.bytesize
+          entry.source_id = own_bytes(face.source_id, owned)
+          entry.source_id_length = face.source_id.bytesize
+          entry.fallback_order = order
+        end
+        [pointer, faces.length]
+      end
+
+      def check_render_status(status, output)
+        return if status.zero?
+
+        error = ERRORS.fetch(status, NativeError)
+        details = render_error_details(status, output)
+        raise error.new("SVGPNG rendering failed (status #{status})", **details)
+      end
+
+      # Native prose and unknown fields never cross the public error boundary.
+      def render_error_details(status, output)
+        return {} unless [5, 6, 7].include?(status)
+
+        diagnostics = copy_diagnostics(output)
+        detail = diagnostics["error"] if diagnostics.is_a?(Hash)
+        return {} unless detail.is_a?(Hash)
+        return reference_error_details(detail) if status == 7
+
+        fields = { requested_family: error_family(detail["requested_family"]) }
+        fields[:scalars] = error_scalars(detail["scalars"]) if status == 6
+        fields
+      rescue Error
+        {} # Optional diagnostics cannot replace the native status classification.
+      end
+
+      def error_family(value)
+        return unless value.is_a?(String) && value.bytesize.between?(1, 1024) && value.valid_encoding?
+        return if /[[:cntrl:]]/.match?(value)
+
+        value
+      end
+
+      def error_scalars(value)
+        return unless value.is_a?(Array) && value.length <= 256
+        return unless value.all? do |scalar|
+          scalar.is_a?(Integer) && scalar.between?(0, 0x10FFFF) && !scalar.between?(0xD800, 0xDFFF)
+        end
+
+        value.uniq.sort
+      end
+
+      def reference_error_details(detail)
+        reference_class = detail["reference_class"]
+        location = detail["location"]
+        classes = %w[relative absolute file network scheme css_import doctype]
+        locations = %w[image@href use@href feImage@href svg@href style@url style@import attribute@url document@doctype]
+        { reference_class: classes.include?(reference_class) ? reference_class : nil,
+          location: locations.include?(location) ? location : nil }
+      end
+
+      def copy_diagnostics(output)
+        bytes = copy_render_bytes(output.diagnostics, output.diagnostics_length, DIAGNOSTIC_LIMIT)
+        JSON.parse(bytes, max_nesting: 32)
+      rescue JSON::ParserError
+        raise NativeError, "Renderer returned malformed diagnostics"
+      end
+
+      def copy_render_bytes(pointer, length, limit)
+        raise LimitError, "Renderer output exceeds limits" if length > limit
+        if !length.positive? || !pointer.to_i.positive? || pointer.to_i > Library::POINTER_MAX - length
+          raise NativeError, "Renderer returned an invalid output pointer"
+        end
+
+        Fiddle::Pointer.new(pointer.to_i)[0, length].b
+      end
+    end
+  end
+end