pdf_oxide 0.3.55-aarch64-linux

data/lib/pdf_oxide/auto_extractor.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PdfOxide
+  # v0.3.51 #519 — auto-extraction with typed reasons.
+  #
+  # Mirrors `fyi.oxide.pdf.AutoExtractor`.  Given a {PdfDocument},
+  # returns recoverable text (native or OCR), per-page or
+  # whole-document, with a typed reason naming any degraded outcome.
+  # When OCR is needed but unavailable, returns the native text layer
+  # with `:ocr_requested_but_unavailable` instead of raising —
+  # extraction is **not** a security operation (per
+  # `feedback_extraction_graceful_fallback`).
+  #
+  # @example
+  #   doc = PdfOxide::PdfDocument.open('sample.pdf')
+  #   ax  = PdfOxide::AutoExtractor.new(doc)
+  #   result = ax.extract_page(0)
+  #   puts result[:text]
+  #   warn "degraded: #{result[:reason]}" unless ax.ok?(result[:reason])
+  class AutoExtractor
+    # Typed reasons mirror the Rust serde-emitted snake_case tokens
+    # at the FFI JSON boundary.  Renaming would break cross-binding
+    # parity with PHP / Python / Java.
+    REASONS = %i[
+      ok
+      native_text_high_confidence
+      no_text_layer_present
+      text_layer_below_threshold
+      glyph_mapping_missing
+      encrypted_no_extract_permission
+      image_table_reconstructed
+      image_table_no_structure
+      chart_not_transcribed
+      ocr_requested_but_unavailable
+      ocr_low_confidence_fallback
+      empty
+    ].freeze
+
+    # Per-page kinds from the auto-classifier (Rust's `PageKind` enum).
+    PAGE_KINDS = %i[text_layer scanned image_text mixed empty].freeze
+
+    # @return [PdfDocument]
+    attr_reader :document
+
+    def initialize(document)
+      raise ::PdfOxide::ArgumentError, 'document cannot be nil' if document.nil?
+      raise ::PdfOxide::StateError, 'document has been closed' if document.respond_to?(:closed?) && document.closed?
+
+      @document = document
+    end
+
+    # Cheap per-page classifier — no OCR, no rasterisation.
+    # @return [Hash] { reason:, kind:, confidence:, classification: }
+    def classify_page(page_index)
+      json = call_json('classify_page') do |err|
+        Bindings.pdf_document_classify_page(@document.handle, page_index, err)
+      end
+      build_classification(json)
+    end
+
+    # Whole-document classifier.
+    # @return [Hash] decoded JSON envelope.
+    def classify_document
+      call_json('classify_document') do |err|
+        Bindings.pdf_document_classify_document(@document.handle, err)
+      end
+    end
+
+    # Extract a page's text via the v0.3.51 auto-router (text-vs-OCR
+    # decision with graceful native fallback).  Surfaces a typed
+    # reason describing the quality.
+    # @return [Hash] { text:, reason:, kind:, confidence:, classification: }
+    def extract_text(page_index)
+      text = call_text('extract_text_auto') do |err|
+        Bindings.pdf_document_extract_text_auto(@document.handle, page_index, err)
+      end
+      cls = begin
+        classify_page(page_index)
+      rescue StandardError
+        { reason: :ok, kind: :mixed, confidence: 0.0 }
+      end
+      # Graceful fallback: if classifier wants OCR and the build can't
+      # supply it, surface OCR_REQUESTED_BUT_UNAVAILABLE regardless of
+      # native-side state.
+      cls[:reason] = :ocr_requested_but_unavailable if cls[:kind] == :scanned && !self.class.prefetch_available?
+      cls.merge(text: text)
+    end
+
+    # Rich per-page extraction — returns the full PageExtraction
+    # JSON envelope (text + per-region bbox + reason + confidence)
+    # merged into a Hash.
+    # @param page_index [Integer]
+    # @param options [Hash, nil] auto-extract options serialised to JSON.
+    def extract_page(page_index, options: nil)
+      options_json = options.nil? ? nil : JSON.generate(options)
+      json = call_json('extract_page_auto') do |err|
+        Bindings.pdf_document_extract_page_auto(@document.handle, page_index, options_json, err)
+      end
+      cls = build_classification(json)
+      cls.merge(text: json['text'] || '', classification: json)
+    end
+
+    # @return [Boolean] true when the reason represents a clean extract.
+    def ok?(reason)
+      %i[ok native_text_high_confidence].include?(reason)
+    end
+
+    # @return [Boolean] true when the OCR-unavailable graceful-fallback
+    #   path engaged.
+    def ocr_fallback?(reason)
+      %i[ocr_requested_but_unavailable ocr_low_confidence_fallback].include?(reason)
+    end
+
+    # @return [Boolean] whether the build supports OCR provisioning
+    #   (i.e. the `ocr` feature is compiled in).
+    def self.prefetch_available?
+      Bindings.pdf_oxide_prefetch_available != 0
+    end
+
+    private
+
+    def call_json(operation, &block)
+      raw = call_text(operation, &block)
+      return {} if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def call_text(operation)
+      err = ::FFI::MemoryPointer.new(:int32)
+      ptr = yield(err)
+      code = err.read_int32
+      raise InternalError, "#{operation} failed (#{code})" if code != 0
+      return '' if ptr.nil? || ptr.null?
+
+      StringMarshaller.from_c_string(ptr) || ''
+    end
+
+    def build_classification(json)
+      json = {} unless json.is_a?(Hash)
+      reason = (json['reason'] || 'ok').to_sym
+      reason = :ok unless REASONS.include?(reason)
+      kind = (json['kind'] || 'mixed').to_sym
+      kind = :mixed unless PAGE_KINDS.include?(kind)
+      {
+        reason: reason,
+        kind: kind,
+        confidence: (json['confidence'] || 0.0).to_f,
+        classification: json
+      }
+    end
+  end
+end

data/lib/pdf_oxide/document_editor.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module PdfOxide
+  # Write-side counterpart to {PdfDocument}: form-fill, destructive
+  # redaction (v0.3.50 #231), metadata scrubbing, and incremental save.
+  #
+  # Mirrors `fyi.oxide.pdf.DocumentEditor`.  Lifecycle: holds a native
+  # `DocumentEditor*` handle; **must** be closed via {#close} or a
+  # block-form factory.  Close is idempotent.
+  #
+  # Per `feedback_extraction_graceful_fallback`: destructive redaction
+  # is a **security operation** — every non-zero return code raises
+  # rather than silently degrading.
+  #
+  # @example destructive redaction (block-form auto-closes).
+  #   PdfOxide::DocumentEditor.open('source.pdf') do |ed|
+  #     ed.add_redaction(page: 0, rect: [100, 200, 300, 250])
+  #     ed.apply_redactions!
+  #     ed.save_to('redacted.pdf')
+  #   end
+  class DocumentEditor
+    # Open an editor session over a PDF on disk (or in-memory bytes).
+    # @param source [String] file path or raw PDF bytes.
+    # @yield [DocumentEditor]
+    # @return [DocumentEditor, Object]
+    def self.open(source, &block)
+      ed = new(source)
+      return ed unless block_given?
+
+      begin
+        yield ed
+      ensure
+        ed.close
+      end
+    end
+
+    def initialize(source)
+      raise ::PdfOxide::ArgumentError, 'source cannot be nil' if source.nil?
+
+      err = ::FFI::MemoryPointer.new(:int32)
+      @handle =
+        if source.is_a?(String) && File.exist?(source)
+          Bindings.document_editor_open(File.absolute_path(source), err)
+        elsif source.is_a?(String) && !source.empty?
+          binary = source.dup.force_encoding(Encoding::BINARY)
+          buf = ::FFI::MemoryPointer.new(:uint8, binary.bytesize)
+          buf.write_bytes(binary, 0, binary.bytesize)
+          Bindings.document_editor_open_from_bytes(buf, binary.bytesize, err)
+        else
+          raise FileNotFoundError, "file not found: #{source}"
+        end
+
+      code = err.read_int32
+      raise IoError, "document_editor_open failed (#{code})" if code != 0
+      raise IoError, 'document_editor_open returned null' if @handle.nil? || @handle.null?
+
+      @closed  = false
+      @applied = false
+      @tracker = [@handle]
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@tracker))
+    end
+
+    # @api private
+    attr_reader :handle
+
+    # ─────────────── destructive redaction (#231) ───────────────
+
+    # Queue a redaction rectangle for the given page.  The redaction
+    # is not applied until {#apply_redactions!} runs.
+    # @param page [Integer] 0-based page index.
+    # @param rect [Array<Numeric>] `[x1, y1, x2, y2]` in PDF user-space.
+    # @param color [Array<Numeric>] `[r, g, b]` overlay color (0.0–1.0).
+    # @return [self] (fluent chaining).
+    def add_redaction(page:, rect:, color: [0.0, 0.0, 0.0])
+      check_open!
+      raise ::PdfOxide::ArgumentError, 'rect must have 4 numeric values' unless rect.respond_to?(:length) && rect.length == 4
+
+      x1, y1, x2, y2 = rect.map(&:to_f)
+      r, g, b = color.map(&:to_f)
+      err = ::FFI::MemoryPointer.new(:int32)
+      rc = Bindings.pdf_redaction_add(@handle, Integer(page), x1, y1, x2, y2, r, g, b, err)
+      fail_closed!(rc, err.read_int32, 'pdf_redaction_add')
+      self
+    end
+
+    # Total redactions queued for the page.
+    # @param page [Integer]
+    # @return [Integer]
+    def redaction_count(page)
+      check_open!
+      err = ::FFI::MemoryPointer.new(:int32)
+      n = Bindings.pdf_redaction_count(@handle, Integer(page), err)
+      fail_closed!(0, err.read_int32, 'pdf_redaction_count')
+      n
+    end
+
+    # Apply all queued redactions destructively.
+    # @param scrub_metadata [Boolean] also strip /Info, XMP, JS.
+    # @param fill_color [Array<Numeric>] overlay `[r, g, b]`.
+    # @return [self]
+    def apply_redactions!(scrub_metadata: false, fill_color: [0.0, 0.0, 0.0])
+      check_open!
+      r, g, b = fill_color.map(&:to_f)
+      err = ::FFI::MemoryPointer.new(:int32)
+      rc = Bindings.pdf_redaction_apply(@handle, scrub_metadata, r, g, b, err)
+      fail_closed!(rc, err.read_int32, 'pdf_redaction_apply')
+
+      if scrub_metadata
+        err2 = ::FFI::MemoryPointer.new(:int32)
+        rc2 = Bindings.pdf_redaction_scrub_metadata(@handle, err2)
+        fail_closed!(rc2, err2.read_int32, 'pdf_redaction_scrub_metadata')
+      end
+      @applied = true
+      self
+    end
+
+    # Metadata scrubbing without redaction regions.
+    # @return [self]
+    def scrub_metadata
+      check_open!
+      err = ::FFI::MemoryPointer.new(:int32)
+      rc = Bindings.pdf_redaction_scrub_metadata(@handle, err)
+      fail_closed!(rc, err.read_int32, 'pdf_redaction_scrub_metadata')
+      @applied = true
+      self
+    end
+
+    # ─────────────── form-fill ───────────────
+
+    # Set an AcroForm text field.
+    # @param name [String] dot-separated full field name.
+    # @param value [String, Boolean] new value (Boolean = checkbox/radio).
+    # @return [self]
+    def set_form_field(name, value)
+      check_open!
+      raise ::PdfOxide::ArgumentError, 'name cannot be nil' if name.nil?
+
+      err = ::FFI::MemoryPointer.new(:int32)
+      ok = if [true, false].include?(value)
+             Bindings.pdf_form_field_set_value_by_name_boolean(@handle, name, value, err)
+           else
+             Bindings.pdf_form_field_set_value_by_name_string(@handle, name, value.to_s, err)
+           end
+      code = err.read_int32
+      raise InternalError, "set_form_field failed (#{code})" if code != 0
+      raise InternalError, 'set_form_field rejected by cdylib (field missing?)' unless ok
+
+      self
+    rescue ::FFI::NotFoundError
+      # phantom in this cdylib build — leave the field-write a no-op
+      # and surface a clear error rather than crashing.
+      raise UnsupportedFeatureError, 'form-fill not supported by this cdylib build'
+    end
+
+    # ─────────────── save ───────────────
+
+    # Save the edited PDF to the given path.
+    # @return [String] absolute path written.
+    def save_to(path)
+      check_open!
+      raise ::PdfOxide::ArgumentError, 'path cannot be empty' if path.nil? || path.empty?
+
+      check_applied! if @needs_apply
+      err = ::FFI::MemoryPointer.new(:int32)
+      rc = Bindings.document_editor_save(@handle, File.absolute_path(path), err)
+      fail_closed!(rc, err.read_int32, 'document_editor_save')
+      File.absolute_path(path)
+    end
+
+    # @return [String] BINARY-encoded PDF bytes.
+    def to_bytes
+      check_open!
+      len_ptr = ::FFI::MemoryPointer.new(:size_t)
+      err     = ::FFI::MemoryPointer.new(:int32)
+      buf     = Bindings.document_editor_save_to_bytes(@handle, len_ptr, err)
+      fail_closed!(0, err.read_int32, 'document_editor_save_to_bytes')
+      raise InternalError, 'document_editor_save_to_bytes returned null' if buf.nil? || buf.null?
+
+      len = len_ptr.read(:size_t)
+      bytes = buf.read_string(len)
+      Bindings.free_bytes(buf) if Bindings.respond_to?(:free_bytes)
+      bytes.force_encoding(Encoding::BINARY)
+    end
+
+    # ─────────────── lifecycle ───────────────
+
+    # Idempotent close.
+    def close
+      return if @closed
+
+      h = @handle
+      @handle = nil
+      @closed = true
+      @tracker[0] = nil if @tracker
+      Bindings.document_editor_free(h) if h && !h.null?
+    end
+
+    def closed?
+      @closed
+    end
+
+    # @api private
+    def self.finalizer(tracker)
+      proc do
+        h = tracker[0]
+        if h && !h.null?
+          Bindings.document_editor_free(h)
+          tracker[0] = nil
+        end
+      end
+    end
+
+    private
+
+    def check_open!
+      raise InvalidStateError, 'DocumentEditor has been closed' if @closed || @handle.nil?
+    end
+
+    def check_applied!
+      return if @applied
+
+      raise StateError, 'no redactions applied; call apply_redactions! before save'
+    end
+
+    # Security-op fail-closed contract: any non-zero rc OR error_code raises.
+    def fail_closed!(rc, error_code, operation)
+      if error_code != 0
+        raise RedactionError, "#{operation} failed (error code #{error_code}); security op fails closed"
+      end
+      return unless rc.is_a?(Integer) && rc.negative?
+
+      raise RedactionError, "#{operation} returned #{rc}; security op fails closed"
+    end
+  end
+end

data/lib/pdf_oxide/errors.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PdfOxide
+  # Base error class for all PdfOxide exceptions.  Mirrors the Java
+  # exception hierarchy at fyi.oxide.pdf.exception.* — every native
+  # error maps to one of the subclasses below.
+  class Error < StandardError; end
+
+  # Raised when the host platform isn't supported by the bundled cdylib.
+  class UnsupportedPlatformError < Error; end
+
+  # Raised when a user-supplied argument fails validation BEFORE the
+  # native call (nil check, range check, etc.).  Wrapper around
+  # ::ArgumentError so it composes with Ruby's standard library.
+  class ArgumentError < Error; end
+
+  # Filesystem / I/O failures (file-not-found, EACCES, EIO, …).
+  class IoError < Error; end
+
+  # `IoError` specialisation for missing files.
+  class FileNotFoundError < IoError; end
+
+  # PDF parse / structure errors (malformed header, corrupt xref, …).
+  class ParseError < Error; end
+
+  # Resource / state errors — closed handle, wrong operation order.
+  class StateError < Error; end
+
+  # Operation called on an already-closed document/editor/Pdf.
+  class InvalidStateError < StateError; end
+
+  # Encryption / wrong-password failures.
+  class EncryptedError < Error; end
+
+  # Permission denied (encrypted PDF lacking extract / sign perm).
+  class PermissionError < Error; end
+
+  # Feature requested but not compiled into this cdylib build
+  # (e.g. signatures without the `signatures` Cargo feature).
+  class UnsupportedFeatureError < Error; end
+
+  # Digital-signature failure (PAdES B/T/LT signing / verifying).
+  class SignatureError < Error; end
+
+  # Destructive-redaction failure (#231).  Security op: fails closed.
+  class RedactionError < Error; end
+
+  # PDF/A · PDF/X · PDF/UA compliance failure.
+  class ComplianceError < Error; end
+
+  # Native text-search operation failed (cdylib error code 7 /
+  # `ERR_SEARCH`). Mirrors C#'s `PdfOxide.Exceptions.SearchException`
+  # and Java's `PdfException(SEARCH)`.
+  class SearchError < Error; end
+
+  # Generic native-side failure that didn't map to a specific subclass.
+  class InternalError < Error; end
+end