rpdfium 0.4.1

data/lib/rpdfium/annotation/annotation.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  # Wrapper per FPDF_ANNOTATION. Le annotazioni includono link, highlight,
+  # commenti, widget di form. PDFium richiede di chiudere ogni handle con
+  # FPDFPage_CloseAnnot, gestito qui via finalizer.
+  class Annotation
+    SUBTYPES = {
+      Raw::FPDF_ANNOT_UNKNOWN => :unknown,
+      Raw::FPDF_ANNOT_TEXT => :text,
+      Raw::FPDF_ANNOT_LINK => :link,
+      Raw::FPDF_ANNOT_FREETEXT => :free_text,
+      Raw::FPDF_ANNOT_LINE => :line,
+      Raw::FPDF_ANNOT_SQUARE => :square,
+      Raw::FPDF_ANNOT_CIRCLE => :circle,
+      Raw::FPDF_ANNOT_HIGHLIGHT => :highlight,
+      Raw::FPDF_ANNOT_UNDERLINE => :underline,
+      Raw::FPDF_ANNOT_SQUIGGLY => :squiggly,
+      Raw::FPDF_ANNOT_STRIKEOUT => :strikeout,
+      Raw::FPDF_ANNOT_STAMP => :stamp,
+      Raw::FPDF_ANNOT_INK => :ink,
+      Raw::FPDF_ANNOT_POPUP => :popup,
+      Raw::FPDF_ANNOT_FILEATTACHMENT => :file_attachment,
+      Raw::FPDF_ANNOT_WIDGET => :widget,
+      Raw::FPDF_ANNOT_REDACT => :redact
+    }.freeze
+
+    attr_reader :page, :index
+
+    def initialize(page, index)
+      @page   = page
+      @index  = index
+      handle  = Raw.FPDFPage_GetAnnot(page.handle, index)
+      raise Error, "Could not load annotation #{index}" if handle.null?
+
+      @state = { handle: handle, closed: false }
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@state))
+    end
+
+    def self.finalizer(state)
+      proc do
+        next if state[:closed]
+        next if state[:handle].null?
+
+        Raw.FPDFPage_CloseAnnot(state[:handle])
+        state[:closed] = true
+      end
+    end
+
+    def handle
+      @state[:handle]
+    end
+
+    def subtype
+      SUBTYPES[Raw.FPDFAnnot_GetSubtype(@state[:handle])] || :unknown
+    end
+
+    def bbox
+      rect = Raw::FS_RECTF.new
+      return nil if Raw.FPDFAnnot_GetRect(@state[:handle], rect) == 0
+
+      h = @page.height
+      { x0: rect[:left], x1: rect[:right],
+        top: h - rect[:top], bottom: h - rect[:bottom] }
+    end
+
+    # Valore di una chiave del dict di annotazione (UTF-16LE).
+    # Chiavi comuni: "Contents" (testo annotazione), "T" (autore),
+    # "M" (mod date), "NM" (uniq name).
+    def [](key)
+      Raw.read_utf16_string(:FPDFAnnot_GetStringValue, @state[:handle], key.to_s)
+    end
+
+    def has_key?(key)
+      Raw.FPDFAnnot_HasKey(@state[:handle], key.to_s) == 1
+    end
+
+    # Per annotazioni :link → URL di destinazione (se esterno) o nil.
+    def link_uri
+      return nil unless subtype == :link
+
+      link_handle = Raw.FPDFAnnot_GetLink(@state[:handle])
+      return nil if link_handle.null?
+
+      action = Raw.FPDFLink_GetAction(link_handle)
+      return nil if action.null?
+
+      Raw.read_utf16_string(:FPDFAction_GetURIPath, @page.document.handle, action)
+    end
+
+    # Per link interni → indice pagina di destinazione, o nil.
+    def link_dest_page
+      return nil unless subtype == :link
+
+      link_handle = Raw.FPDFAnnot_GetLink(@state[:handle])
+      return nil if link_handle.null?
+
+      dest = Raw.FPDFLink_GetDest(@page.document.handle, link_handle)
+      return nil if dest.null?
+
+      idx = Raw.FPDFDest_GetDestPageIndex(@page.document.handle, dest)
+      idx >= 0 ? idx : nil
+    end
+
+    def close
+      return if @state[:closed]
+
+      Raw.FPDFPage_CloseAnnot(@state[:handle]) unless @state[:handle].null?
+      @state[:handle] = FFI::Pointer::NULL
+      @state[:closed] = true
+      ObjectSpace.undefine_finalizer(self)
+    end
+  end
+end

data/lib/rpdfium/document.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  # Wrapper di livello documento. Espone:
+  # - apertura da path / IO / bytes / pagina by index
+  # - metadata (Title, Author, ecc.)
+  # - permissions
+  # - outline (bookmarks)
+  # - attachments
+  # - form environment (lazy)
+  class Document
+    include Enumerable
+
+    META_KEYS = %w[Title Author Subject Keywords Creator Producer
+                   CreationDate ModDate Trapped].freeze
+
+    attr_reader :source
+
+    def self.open(input, password: nil, &block)
+      doc = new(input, password: password)
+      return doc unless block_given?
+
+      begin
+        yield doc
+      ensure
+        doc.close
+      end
+    end
+
+    def initialize(input, password: nil)
+      Rpdfium.init!
+      @password = password
+      @source   = input
+      handle, retain_buffer = load_handle(input, password)
+      if handle.null?
+        code = Rpdfium.last_error_code
+        msg  = Rpdfium.last_error_message
+        raise PasswordError, msg if code == 4
+
+        raise LoadError, "Failed to load PDF: #{msg}"
+      end
+      # Stato condiviso tra istanza e finalizer. Wrappato in Hash mutabile
+      # perché la closure del finalizer e il close() esplicito devono vedere
+      # lo stesso :closed flag — altrimenti chi arriva secondo richiama
+      # FPDF_CloseDocument su un handle già liberato e PDFium segfaulta.
+      @state = {
+        handle: handle,
+        retain_buffer: retain_buffer,
+        closed: false
+      }
+      @form_env = nil
+      @page_cache = {}
+      # IMPORTANTE: il finalizer cattura @state (Hash), NON self. Catturare
+      # self impedirebbe al GC di raccogliere il Document. Inoltre il
+      # finalizer NON tocca @page_cache: le Page hanno il loro finalizer
+      # individuale, e l'ordine di esecuzione tra finalizer è non
+      # deterministico in Ruby.
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@state))
+    end
+
+    def self.finalizer(state)
+      proc do
+        next if state[:closed]
+        next if state[:handle].null?
+
+        Raw.FPDF_CloseDocument(state[:handle])
+        state[:closed] = true
+        state[:retain_buffer] = nil
+      end
+    end
+
+    def handle
+      @state[:handle]
+    end
+
+    # ===== Pages =====
+
+    def page_count
+      ensure_open!
+      Raw.FPDF_GetPageCount(@state[:handle])
+    end
+    alias size page_count
+    alias length page_count
+
+    def page(index)
+      ensure_open!
+      raise PageError, "Page index #{index} out of range" unless (0...page_count).cover?(index)
+
+      # Le pagine sono cacheable: ricaricarle è costoso e gli oggetti sono
+      # immutabili dal punto di vista applicativo (in modalità read-only).
+      @page_cache[index] ||= Page.new(self, index)
+    end
+    alias [] page
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      page_count.times { |i| yield page(i) }
+    end
+
+    def page_label(index)
+      Raw.read_utf16_string(:FPDF_GetPageLabel, @state[:handle], index)
+    end
+
+    # ===== Metadata =====
+
+    def metadata
+      META_KEYS.each_with_object({}) do |key, h|
+        v = Raw.read_utf16_string(:FPDF_GetMetaText, @state[:handle], key)
+        h[key.downcase.to_sym] = v unless v.empty?
+      end
+    end
+
+    def file_version
+      buf = FFI::MemoryPointer.new(:int)
+      return nil if Raw.FPDF_GetFileVersion(@state[:handle], buf) == 0
+
+      v = buf.read_int
+      # PDFium ritorna 14 → 1.4, 17 → 1.7
+      "#{v / 10}.#{v % 10}"
+    end
+
+    # Permission bits secondo PDF spec (Table 22 §7.6.3.2)
+    PERMISSIONS = {
+      print:       1 << 2,
+      modify:      1 << 3,
+      copy:        1 << 4,
+      annotate:    1 << 5,
+      fill_forms:  1 << 8,
+      extract_acc: 1 << 9,
+      assemble:    1 << 10,
+      print_hq:    1 << 11
+    }.freeze
+
+    def permissions
+      bits = Raw.FPDF_GetDocPermissions(@state[:handle])
+      PERMISSIONS.transform_values { |mask| (bits & mask) == mask }
+    end
+
+    # ===== Form type =====
+
+    FORM_TYPES = {
+      Raw::FORMTYPE_NONE      => :none,
+      Raw::FORMTYPE_ACRO_FORM => :acroform,
+      Raw::FORMTYPE_XFA_FULL  => :xfa_full,
+      Raw::FORMTYPE_XFA_FOREGROUND => :xfa_foreground
+    }.freeze
+
+    def form_type
+      FORM_TYPES[Raw.FPDF_GetFormType(@state[:handle])] || :unknown
+    end
+
+    def has_forms?
+      form_type != :none
+    end
+
+    # Lazy form environment. Necessario per:
+    # - leggere FormFieldType/Value/Name su widget annotations
+    # - renderizzare i form fields sopra la pagina (FFLDraw)
+    def form_env
+      @form_env ||= Form::Environment.new(self) if has_forms?
+    end
+
+    # ===== Outline =====
+
+    def outline
+      Outline.from_document(self)
+    end
+
+    # ===== Attachments =====
+
+    def attachments
+      n = Raw.FPDFDoc_GetAttachmentCount(@state[:handle])
+      Array.new(n) { |i| Attachment.new(self, i) }
+    end
+
+    # ===== Close =====
+
+    def close
+      return if @state[:closed]
+
+      # Ordine: chiudi prima form env e pagine cached, poi documento.
+      @form_env&.close
+      @page_cache.each_value(&:close)
+      @page_cache.clear
+      Raw.FPDF_CloseDocument(@state[:handle]) unless @state[:handle].null?
+      @state[:handle] = FFI::Pointer::NULL
+      @state[:retain_buffer] = nil
+      @state[:closed] = true
+      ObjectSpace.undefine_finalizer(self)
+    end
+
+    def closed?
+      @state[:closed]
+    end
+
+    private
+
+    def ensure_open!
+      raise Error, "Document is closed" if @state[:closed]
+    end
+
+    def load_handle(input, password)
+      case input
+      when String
+        if File.file?(input)
+          [Raw.FPDF_LoadDocument(input, password), nil]
+        else
+          load_from_bytes(input, password)
+        end
+      when IO, StringIO
+        load_from_bytes(input.read, password)
+      else
+        raise ArgumentError, "Unsupported input: #{input.class}"
+      end
+    end
+
+    def load_from_bytes(bytes, password)
+      # CRITICO: PDFium NON copia i bytes — li referenzia. Dobbiamo tenere
+      # vivo il buffer per tutta la vita del documento.
+      buf = FFI::MemoryPointer.new(:uchar, bytes.bytesize)
+      buf.put_bytes(0, bytes)
+      [Raw.FPDF_LoadMemDocument64(buf, bytes.bytesize, password), buf]
+    end
+  end
+end

data/lib/rpdfium/errors.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  class Error < StandardError; end
+  class LoadError    < Error; end
+  class PageError    < Error; end
+  class PasswordError < Error; end
+  class FormError    < Error; end
+
+  PDFIUM_ERRORS = {
+    0 => "Success",
+    1 => "Unknown error",
+    2 => "File not found or could not be opened",
+    3 => "File not in PDF format or corrupted",
+    4 => "Password required or incorrect",
+    5 => "Unsupported security scheme",
+    6 => "Page not found or content error"
+  }.freeze
+
+  class << self
+    def init!
+      @init_mutex ||= Mutex.new
+      @init_mutex.synchronize do
+        return if @initialized
+
+        unless Raw.native_loaded?
+          raise LoadError, <<~MSG.strip
+            PDFium native library not loaded.
+            Set ENV["PDFIUM_LIBRARY_PATH"] to libpdfium.{so,dylib,dll}, or
+            install the rpdfium-binary gem.
+            Original load error: #{Raw.load_error&.message}
+          MSG
+        end
+
+        Raw.FPDF_InitLibrary
+        @initialized = true
+        # Cleanup automatico a process exit. Ordine garantito: tutti i
+        # finalizer Ruby vengono eseguiti prima di at_exit dei nostri blocchi.
+        at_exit { Raw.FPDF_DestroyLibrary if @initialized }
+      end
+    end
+
+    def initialized?
+      @initialized == true
+    end
+
+    def last_error_code
+      Raw.FPDF_GetLastError
+    end
+
+    def last_error_message
+      PDFIUM_ERRORS[last_error_code] || "Unknown PDFium error (#{last_error_code})"
+    end
+  end
+end

data/lib/rpdfium/form/form.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Form
+    # FPDF_FORMHANDLE è necessario per leggere widget annotations.
+    # In modalità read-only basta inizializzarlo con una FORMFILLINFO minimale
+    # (version=2, callbacks NULL). PDFium chiama i callback solo durante
+    # interazione utente o JavaScript, che noi non usiamo.
+    class Environment
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+        @info = Raw::FPDF_FORMFILLINFO.new
+        @info[:version] = 2
+        # Tutti i puntatori restano NULL (default di FFI::Struct).
+        handle = Raw.FPDFDOC_InitFormFillEnvironment(document.handle, @info)
+        if handle.null?
+          raise FormError,
+                "FPDFDOC_InitFormFillEnvironment failed (form_type=#{document.form_type})"
+        end
+        @state = { handle: handle, closed: false }
+        ObjectSpace.define_finalizer(self, self.class.finalizer(@state))
+      end
+
+      def self.finalizer(state)
+        proc do
+          next if state[:closed]
+          next if state[:handle].null?
+
+          Raw.FPDFDOC_ExitFormFillEnvironment(state[:handle])
+          state[:closed] = true
+        end
+      end
+
+      def handle
+        @state[:handle]
+      end
+
+      def close
+        return if @state[:closed]
+
+        Raw.FPDFDOC_ExitFormFillEnvironment(@state[:handle]) unless @state[:handle].null?
+        @state[:handle] = FFI::Pointer::NULL
+        @info = nil
+        @state[:closed] = true
+        ObjectSpace.undefine_finalizer(self)
+      end
+    end
+
+    # Wrapper per un widget di form. Si costruisce a partire da
+    # un'annotazione di tipo :widget e l'env del documento.
+    class Field
+      TYPES = {
+        Raw::FPDF_FORMFIELD_UNKNOWN     => :unknown,
+        Raw::FPDF_FORMFIELD_PUSHBUTTON  => :pushbutton,
+        Raw::FPDF_FORMFIELD_CHECKBOX    => :checkbox,
+        Raw::FPDF_FORMFIELD_RADIOBUTTON => :radiobutton,
+        Raw::FPDF_FORMFIELD_COMBOBOX    => :combobox,
+        Raw::FPDF_FORMFIELD_LISTBOX     => :listbox,
+        Raw::FPDF_FORMFIELD_TEXTFIELD   => :textfield,
+        Raw::FPDF_FORMFIELD_SIGNATURE   => :signature
+      }.freeze
+
+      attr_reader :env, :annotation
+
+      def initialize(env, annotation)
+        @env = env
+        @annotation = annotation
+      end
+
+      def type
+        TYPES[Raw.FPDFAnnot_GetFormFieldType(@env.handle, @annotation.handle)] || :unknown
+      end
+
+      def name
+        Raw.read_utf16_string(:FPDFAnnot_GetFormFieldName, @env.handle, @annotation.handle)
+      end
+
+      def value
+        Raw.read_utf16_string(:FPDFAnnot_GetFormFieldValue, @env.handle, @annotation.handle)
+      end
+
+      def flags
+        Raw.FPDFAnnot_GetFormFieldFlags(@env.handle, @annotation.handle)
+      end
+
+      # PDF spec §12.7.4.1: bit 1=read-only, bit 2=required, bit 3=no-export
+      def readonly?; (flags & (1 << 0)).positive?; end
+      def required?; (flags & (1 << 1)).positive?; end
+
+      # Per checkbox e radio
+      def checked?
+        return false unless %i[checkbox radiobutton].include?(type)
+
+        Raw.FPDFAnnot_IsChecked(@env.handle, @annotation.handle) == 1
+      end
+
+      # Per combobox/listbox
+      def options
+        n = Raw.FPDFAnnot_GetOptionCount(@env.handle, @annotation.handle)
+        return [] if n <= 0
+
+        Array.new(n) do |i|
+          Raw.read_utf16_string(:FPDFAnnot_GetOptionLabel,
+                                @env.handle, @annotation.handle, i)
+        end
+      end
+
+      def to_h
+        {
+          name: name, type: type, value: value,
+          readonly: readonly?, required: required?,
+          checked: (%i[checkbox radiobutton].include?(type) ? checked? : nil),
+          options: (%i[combobox listbox].include?(type) ? options : nil),
+          bbox: @annotation.bbox
+        }.compact
+      end
+    end
+  end
+end

data/lib/rpdfium/image/embedded.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Image
+    # Wrapper per un image object inserito in una pagina. Permette di:
+    # - leggere metadata (dimensione pixel, DPI, colorspace, BPP)
+    # - ottenere bytes raw (così come stoccati: tipicamente JPEG)
+    # - ottenere bytes decoded (raster post-filtri)
+    # - ottenere bitmap renderizzato (con maschere e matrice applicate)
+    class Embedded
+      COLORSPACES = {
+        0 => :unknown, 1 => :devicegray, 2 => :devicergb, 3 => :devicecmyk,
+        4 => :calgray, 5 => :calrgb, 6 => :lab, 7 => :iccbased,
+        8 => :separation, 9 => :devicen, 10 => :indexed, 11 => :pattern
+      }.freeze
+
+      attr_reader :page, :handle
+
+      def initialize(page, page_object_handle)
+        @page   = page
+        @handle = page_object_handle
+      end
+
+      def metadata
+        meta = Raw::FPDF_IMAGEOBJ_METADATA.new
+        return nil if Raw.FPDFImageObj_GetImageMetadata(@handle, @page.handle, meta) == 0
+
+        {
+          width:           meta[:width],
+          height:          meta[:height],
+          horizontal_dpi:  meta[:horizontal_dpi],
+          vertical_dpi:    meta[:vertical_dpi],
+          bits_per_pixel:  meta[:bits_per_pixel],
+          colorspace:      COLORSPACES[meta[:colorspace]] || :unknown
+        }
+      end
+
+      def pixel_size
+        wbuf = FFI::MemoryPointer.new(:uint)
+        hbuf = FFI::MemoryPointer.new(:uint)
+        return nil if Raw.FPDFImageObj_GetImagePixelSize(@handle, wbuf, hbuf) == 0
+
+        [wbuf.read_uint, hbuf.read_uint]
+      end
+
+      def bbox
+        l = FFI::MemoryPointer.new(:float)
+        r = FFI::MemoryPointer.new(:float)
+        b = FFI::MemoryPointer.new(:float)
+        t = FFI::MemoryPointer.new(:float)
+        return nil if Raw.FPDFPageObj_GetBounds(@handle, l, r, b, t) == 0
+
+        h = @page.height
+        { x0: l.read_float, x1: r.read_float,
+          top: h - t.read_float, bottom: h - b.read_float }
+      end
+
+      # Filtri applicati nell'ordine PDF: es. ["DCTDecode"] → JPEG,
+      # ["FlateDecode"] → zlib, ["DCTDecode","DCTDecode"] → ricodifiche.
+      def filters
+        n = Raw.FPDFImageObj_GetImageFilterCount(@handle)
+        Array.new(n) do |i|
+          # Probe + read
+          len = Raw.FPDFImageObj_GetImageFilter(@handle, i, FFI::Pointer::NULL, 0)
+          if len > 1
+            buf = FFI::MemoryPointer.new(:uchar, len)
+            Raw.FPDFImageObj_GetImageFilter(@handle, i, buf, len)
+            buf.read_bytes(len - 1).force_encoding("UTF-8")
+          else
+            ""
+          end
+        end
+      end
+
+      # Bytes "raw": come sono stoccati nel PDF. Se filters == ["DCTDecode"]
+      # questi bytes sono un JPEG completo che puoi salvare con estensione .jpg.
+      def raw_bytes
+        len = Raw.FPDFImageObj_GetImageDataRaw(@handle, FFI::Pointer::NULL, 0)
+        return "" if len.zero?
+
+        buf = FFI::MemoryPointer.new(:uchar, len)
+        Raw.FPDFImageObj_GetImageDataRaw(@handle, buf, len)
+        buf.read_bytes(len)
+      end
+
+      # Bytes decoded: pixel raster dopo l'applicazione dei filtri.
+      # Layout dipende dal colorspace.
+      def decoded_bytes
+        len = Raw.FPDFImageObj_GetImageDataDecoded(@handle, FFI::Pointer::NULL, 0)
+        return "" if len.zero?
+
+        buf = FFI::MemoryPointer.new(:uchar, len)
+        Raw.FPDFImageObj_GetImageDataDecoded(@handle, buf, len)
+        buf.read_bytes(len)
+      end
+
+      # Bitmap renderizzato applicando matrice e maschere. Ritorna [w, h, bytes(BGRA)].
+      def render_bitmap
+        bitmap = Raw.FPDFImageObj_GetRenderedBitmap(
+          @page.document.handle, @page.handle, @handle
+        )
+        return nil if bitmap.null?
+
+        begin
+          w = Raw.FPDFBitmap_GetWidth(bitmap)
+          h = Raw.FPDFBitmap_GetHeight(bitmap)
+          stride = Raw.FPDFBitmap_GetStride(bitmap)
+          buf = Raw.FPDFBitmap_GetBuffer(bitmap)
+          [w, h, buf.read_bytes(stride * h), stride]
+        ensure
+          Raw.FPDFBitmap_Destroy(bitmap)
+        end
+      end
+
+      # Salva il file. Se i filtri sono DCTDecode → scrive .jpg diretto.
+      # Altrimenti renderizza il bitmap a PNG.
+      def save(path)
+        if filters == ["DCTDecode"]
+          File.binwrite(path, raw_bytes)
+        else
+          w, h, bytes, stride = render_bitmap
+          # I bitmap resi sono BGRA: convertiamo a RGBA per il PNG writer
+          rgba = swap_bgra_to_rgba(bytes, w, h, stride)
+          Rpdfium::IO::PNG.write(path, w, h, rgba, stride: w * 4)
+        end
+        path
+      end
+
+      private
+
+      def swap_bgra_to_rgba(bgra, w, h, stride)
+        out = String.new(capacity: w * h * 4, encoding: Encoding::ASCII_8BIT)
+        h.times do |y|
+          row = bgra.byteslice(y * stride, w * 4)
+          # Scambia B<->R per ogni pixel
+          (0...row.bytesize).step(4) do |i|
+            out << row.getbyte(i + 2) << row.getbyte(i + 1) <<
+                   row.getbyte(i)     << row.getbyte(i + 3)
+          end
+        end
+        out
+      end
+    end
+  end
+end