imprimatur 0.5.0 → 0.6.0

data/ext/imprimatur_native/ffi/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "imprimatur_native"
-version = "0.5.0"
+version = "0.6.0"
 description = "Ruby bindings for the imprimatur crate"
 publish = false
 edition.workspace = true
@@ -16,7 +16,7 @@ workspace = true
 
 [dependencies]
 # Gems ship precompiled, so they carry every feature of the crate.
-imprimatur = { workspace = true, features = ["archive", "fonts", "json"] }
+imprimatur = { workspace = true, features = ["archive", "fonts", "json", "isolation"] }
 serde_json.workspace = true
 magnus.workspace = true
 rb-sys.workspace = true

data/ext/imprimatur_native/ffi/src/document.rs

@@ -66,6 +66,11 @@ impl NativeDocument {
         Ok(())
     }
 
+    fn set_font_size(ruby: &Ruby, rb_self: &Self, points: f64) -> Result<(), Error> {
+        borrow(ruby, &rb_self.0, "document")?.set_font_size(points).or_raise(ruby)?;
+        Ok(())
+    }
+
     /// A PNG or JPEG from its bytes, `width` and `height` in points.
     fn picture(
         ruby: &Ruby,
@@ -201,6 +206,7 @@ pub fn define(ruby: &Ruby, native: RModule) -> Result<(), Error> {
     class.define_method("set_page", method!(NativeDocument::set_page, 2))?;
     class.define_method("set_page_points", method!(NativeDocument::set_page_points, 3))?;
     class.define_method("set_margin", method!(NativeDocument::set_margin, 1))?;
+    class.define_method("set_font_size", method!(NativeDocument::set_font_size, 1))?;
     class.define_method("picture", method!(NativeDocument::picture, 4))?;
     class.define_method("barcode", method!(NativeDocument::barcode, 4))?;
     class.define_method("heading", method!(NativeDocument::heading, 2))?;

data/ext/imprimatur_native/ffi/src/lib.rs

@@ -8,6 +8,7 @@ mod barcode;
 mod blocking;
 mod convert;
 mod document;
+mod pdf;
 mod read;
 mod sheets;
 mod style;
@@ -277,6 +278,9 @@ fn argument_error(ruby: &Ruby, message: impl Into<std::borrow::Cow<'static, str>
 /// Raises `Imprimatur::Error`, or the subclass of it the error has, all
 /// defined in `lib/imprimatur/error.rb`.
 fn domain_error(ruby: &Ruby, error: &imprimatur::Error) -> Error {
+    if let imprimatur::Error::InvalidPdfOption(message) = error {
+        return argument_error(ruby, *message);
+    }
     let name = match error {
         imprimatur::Error::NoTextLayer => "NoTextLayer",
         imprimatur::Error::PasswordRequired => "PasswordRequired",
@@ -322,6 +326,9 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     native.define_singleton_method("markdown", function!(read::markdown_native, 4))?;
     native.define_singleton_method("content", function!(read::content_native, 5))?;
     native.define_singleton_method("images", function!(read::images_native, 4))?;
+    native.define_singleton_method("pdf_info", function!(pdf::info, 2))?;
+    native.define_singleton_method("pdf_pages", function!(pdf::pages, 3))?;
+    native.define_singleton_method("render_pdf_page", function!(pdf::render, 5))?;
     native.define_singleton_method("sheets", function!(sheets::sheets_native, 5))?;
     let zip_writer = native.define_class("ZipWriter", ruby.class_object())?;
     zip_writer.define_singleton_method("new", function!(archive::ZipWriter::new, 1))?;

data/ext/imprimatur_native/ffi/src/pdf.rs

@@ -0,0 +1,73 @@
+//! PDF-specific entry points; all document work stays in the Rust core.
+
+use imprimatur::read::{Limits, pdf};
+use magnus::{Error, RString, Ruby};
+use serde_json::json;
+use std::path::PathBuf;
+
+use crate::read::without_gvl;
+
+type Keywords = (Option<usize>, Option<u64>, Option<f64>);
+
+pub fn info(ruby: &Ruby, document: RString, keywords: Keywords) -> Result<RString, Error> {
+    let value = without_gvl(ruby, document, keywords, |data, limits| {
+        let info = pdf::info(data, limits)?;
+        Ok(json!({ "page_count": info.page_count, "encrypted": info.encrypted }).to_string())
+    })?;
+    Ok(ruby.str_new(&value))
+}
+
+pub fn pages(
+    ruby: &Ruby,
+    document: RString,
+    keywords: Keywords,
+    options: (u32, u32, usize, usize, usize),
+) -> Result<RString, Error> {
+    let (first_page, last_page, max_pages, max_page_bytes, max_output_bytes) = options;
+    let options =
+        pdf::ReadOptions { first_page, last_page, max_pages, max_page_bytes, max_output_bytes };
+    let value = without_gvl(ruby, document, keywords, |data, limits| {
+        let result = pdf::pages(data, &options, limits)?;
+        let pages: Vec<_> = result
+            .pages
+            .into_iter()
+            .map(|page| {
+                json!({
+                    "page": page.number,
+                    "status": page.status.as_str(),
+                    "text": page.text,
+                    "images": page.images,
+                    "truncated": page.truncated,
+                    "reason": page.reason,
+                })
+            })
+            .collect();
+        Ok(json!({
+            "page_count": result.info.page_count,
+            "encrypted": result.info.encrypted,
+            "pages": pages,
+        })
+        .to_string())
+    })?;
+    Ok(ruby.str_new(&value))
+}
+
+pub fn render(
+    ruby: &Ruby,
+    document: RString,
+    keywords: Keywords,
+    options: (u32, u16, u64, usize, bool),
+    worker: String,
+    memory_bytes: u64,
+) -> Result<RString, Error> {
+    let (page, max_side, max_pixels, max_output_bytes, grayscale) = options;
+    let worker = PathBuf::from(worker);
+    let options = pdf::RenderOptions { max_side, max_pixels, max_output_bytes, grayscale };
+    let process =
+        pdf::isolation::ProcessLimits { memory_bytes, ..pdf::isolation::ProcessLimits::default() };
+    let data = without_gvl(ruby, document, keywords, |data: &[u8], limits: &Limits| {
+        pdf::isolation::render_page_isolated(&worker, data, page, &options, limits, &process)
+            .map(|image| image.data)
+    })?;
+    Ok(ruby.str_from_slice(&data))
+}

data/ext/imprimatur_native/ffi/src/read.rs

@@ -16,14 +16,11 @@ use serde_json::Value as Json;
 use crate::blocking::MAX_ATTEMPTS;
 use crate::{argument_error, domain_error};
 
-/// A read of a document's bytes within limits, run without the GVL.
-pub type Job<T> = fn(&[u8], &Limits) -> imprimatur::Result<T>;
-
 /// What crosses into the thread without the GVL, and comes back.
-struct Read<T> {
+struct Read<T, F> {
     document: Vec<u8>,
     limits: Limits,
-    job: Job<T>,
+    job: F,
     result: Option<imprimatur::Result<T>>,
 }
 
@@ -107,17 +104,20 @@ fn limits(
 }
 
 /// Runs `job` on the document's bytes on this thread, the GVL released.
-pub fn without_gvl<T>(
+pub fn without_gvl<T, F>(
     ruby: &Ruby,
     document: RString,
     keywords: (Option<usize>, Option<u64>, Option<f64>),
-    job: Job<T>,
-) -> Result<T, Error> {
+    job: F,
+) -> Result<T, Error>
+where
+    F: Fn(&[u8], &Limits) -> imprimatur::Result<T>,
+{
     let document = crate::bytes(document);
     let cancel = Arc::new(AtomicBool::new(false));
     let limits = limits(ruby, &cancel, keywords)?;
     let mut read = Read { document, limits, job, result: None };
-    let read_pointer: *mut Read<T> = &raw mut read;
+    let read_pointer: *mut Read<T, F> = &raw mut read;
     let flag_pointer = Arc::as_ptr(&cancel).cast_mut();
     for _ in 0..MAX_ATTEMPTS {
         // SAFETY: `read` and `cancel` outlive the call, which returns only
@@ -127,12 +127,15 @@ pub fn without_gvl<T>(
         #[allow(unsafe_code)]
         unsafe {
             rb_sys::rb_thread_call_without_gvl2(
-                Some(run::<T>),
+                Some(run::<T, F>),
                 read_pointer.cast(),
                 Some(stop),
                 flag_pointer.cast(),
             );
         }
+        // In particular, SIGCHLD wakes an isolated render on normal completion.
+        // Deliver real Ruby interrupts even when the native job succeeded.
+        ruby.thread_check_ints()?;
         match read.result.take() {
             Some(Ok(value)) => return Ok(value),
             // Cut short by Ruby: raise what Ruby has to raise (Thread#raise,
@@ -153,10 +156,13 @@ pub fn without_gvl<T>(
 /// The read itself, on the thread without the GVL. A panic would abort
 /// the process at this C boundary; it becomes an error instead.
 #[allow(unsafe_code)]
-unsafe extern "C" fn run<T>(data: *mut c_void) -> *mut c_void {
+unsafe extern "C" fn run<T, F>(data: *mut c_void) -> *mut c_void
+where
+    F: Fn(&[u8], &Limits) -> imprimatur::Result<T>,
+{
     // SAFETY: `data` is the `Read<T>` without_gvl passed, alive and not
     // otherwise borrowed until this returns.
-    let read = unsafe { &mut *data.cast::<Read<T>>() };
+    let read = unsafe { &mut *data.cast::<Read<T, F>>() };
     let result = catch_unwind(AssertUnwindSafe(|| (read.job)(&read.document, &read.limits)));
     read.result = Some(result.unwrap_or_else(|_| {
         Err(imprimatur::Error::Malformed {

data/lib/imprimatur/document.rb

@@ -21,10 +21,11 @@ module Imprimatur
     # @param page_size [:a4, :letter, Array(Numeric, Numeric)] or its width
     #   and height in points, 36 to 1584 a side
     # @param margin [Numeric, nil] points on every side, one inch (72) unless set
+    # @param font_size [Numeric, nil] body text in points, 1 to 1638 in steps of 0.5; 11 unless set
     # @param page_numbers [Boolean] number pages "1 / N" in the footer
     # @raise [ArgumentError] an unknown page size
-    # @raise [Imprimatur::Error] a page size or margin out of range
-    def initialize(page_size: :a4, margin: nil, page_numbers: false)
+    # @raise [Imprimatur::Error] a page size, margin or font size out of range
+    def initialize(page_size: :a4, margin: nil, font_size: nil, page_numbers: false)
       @native = Native::Document.new
       numbers = page_numbers ? true : false
       if page_size.is_a?(Array)
@@ -34,6 +35,7 @@ module Imprimatur
         @native.set_page(page_size.to_s, numbers)
       end
       @native.set_margin(Float(margin)) if margin
+      @native.set_font_size(Float(font_size)) if font_size
     end
 
     # A PNG or JPEG in the flow, at +width+ or +height+ points (the other

data/lib/imprimatur/native.rb

@@ -15,3 +15,10 @@ rescue LoadError => e
   raise LoadError, "imprimatur: the native extension did not load (#{e.message}). " \
                    'Install a platform gem, or build it with `rake compile` (toolchain: https://rustup.rs).'
 end
+
+module Imprimatur
+  # Always use the companion of the loaded extension, never PATH.
+  RENDER_WORKER = File.join(File.dirname($LOADED_FEATURES.find do |path|
+    path.end_with?("/imprimatur_native.#{RbConfig::CONFIG['DLEXT']}")
+  end), 'imprimatur-render-worker').freeze
+end

data/lib/imprimatur/pdf_reader.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Imprimatur
+  # Keyword handling only; parsing, limits and rendering live in the native core.
+  module PdfReader
+    def self.info(document, max_bytes: nil, **limits)
+      JSON.parse(Native.pdf_info(Reader.read(document, max_bytes), Reader.limits(max_bytes:, **limits)),
+                 symbolize_names: true)
+    end
+
+    def self.pages(document, first_page: 1, last_page: 0xFFFFFFFF, max_pages: 500,
+                   max_page_bytes: 256 * 1024, max_output_bytes: 8 * 1024 * 1024,
+                   max_bytes: nil, **limits)
+      options = [first_page, last_page, max_pages, max_page_bytes, max_output_bytes]
+      JSON.parse(Native.pdf_pages(Reader.read(document, max_bytes), Reader.limits(max_bytes:, **limits), options),
+                 symbolize_names: true)
+    end
+
+    def self.render(document, page:, max_side: 1568, max_pixels: 4_000_000,
+                    max_output_bytes: 8 * 1024 * 1024, grayscale: true,
+                    memory_bytes: 1024 * 1024 * 1024, max_bytes: nil, **limits)
+      Native.render_pdf_page(Reader.read(document, max_bytes), Reader.limits(max_bytes:, **limits),
+                            [page, max_side, max_pixels, max_output_bytes, grayscale],
+                            RENDER_WORKER, memory_bytes)
+    end
+  end
+end

data/lib/imprimatur/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imprimatur
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

data/lib/imprimatur.rb

@@ -10,6 +10,7 @@ require_relative 'imprimatur/barcode'
 require_relative 'imprimatur/xlsx'
 require_relative 'imprimatur/document'
 require_relative 'imprimatur/reader'
+require_relative 'imprimatur/pdf_reader'
 require_relative 'imprimatur/spreadsheet'
 require_relative 'imprimatur/zip'
 
@@ -45,7 +46,7 @@ module Imprimatur
     # Builds a {Document} and renders it as PDF. With a path, saves it there
     # and returns the path; without, returns the bytes.
     #
-    # @param options [Hash] +page_size:+ and +page_numbers:+, see {Document#initialize}
+    # @param options [Hash] +page_size:+, +margin:+, +font_size:+ and +page_numbers:+, see {Document#initialize}
     # @yieldparam document [Document]
     def pdf(path = nil, **options, &) = Document.build(:pdf, path, **options, &)
 
@@ -92,7 +93,11 @@ module Imprimatur
     #   sheet = Imprimatur.content('sales.xlsx')[:sheets].first
     #   sheet[:rows][1][:cells]  # => [{cell: "A2", type: "text", value: "North"}, ...]
     #
-    # Takes the arguments of {.markdown}, and raises as it does. With
+    # Unlike {.markdown}, a PDF without text still returns every page, with
+    # empty +:blocks+ and its image count, rather than raising {NoTextLayer}.
+    # This keeps scanned and blank pages visible to OCR callers.
+    #
+    # Takes the arguments of {.markdown}, and raises as it does otherwise. With
     # +styles: true+ each sheet also lists its formatted cells' +:styles+:
     # font, size, bold, italic, underline, ARGB color and fill, alignment,
     # wrap, border and number format.
@@ -100,6 +105,25 @@ module Imprimatur
     # @return [Hash] with symbol keys; +:format+ is +"pdf"+, +"xlsx"+ or +"docx"+
     def content(document, ...) = Reader.content(document, ...)
 
+    # PDF metadata without reading page content.
+    # @return [Hash] +page_count:+ and +encrypted:+
+    def pdf_info(document, ...) = PdfReader.info(document, ...)
+
+    # A bounded, one-based page selection. Each page has its status, text,
+    # image count (nil when unknown), truncation flag and failure reason.
+    # Takes +first_page:+, +last_page:+, +max_pages:+ (500),
+    # +max_page_bytes:+ (256 KiB), +max_output_bytes:+ (8 MiB), and read limits.
+    # @return [Hash] +page_count:+, +encrypted:+ and +pages:+
+    def pdf_pages(document, ...) = PdfReader.pages(document, ...)
+
+    # A full page as an opaque PNG, not just its embedded images.
+    # Takes +page:+ (one-based), +max_side:+ (1568), +max_pixels:+ (4 million),
+    # +max_output_bytes:+ (8 MiB), +grayscale:+ (true), and read limits.
+    # Rendering checks time/cancellation before and after Hayro, not during it.
+    # Untrusted documents still need an externally limited worker process.
+    # @return [String] PNG bytes
+    def render_pdf_page(document, ...) = PdfReader.render(document, ...)
+
     # A workbook's sheets and their values, read from the same documents
     # {.markdown} takes (+.xlsx+, +.xls+, +.ods+); see {Spreadsheet}.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imprimatur
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -24,9 +24,10 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 0.9.130
 description: 'A Ruby DSL over a native core that writes Excel workbooks, and PDF and
-  Word documents from one model, with its own XML, zip and PDF writers: no third-party
-  format stack. It reads PDF, XLSX, XLS, ODS and DOCX back: as Markdown, as typed
-  structure, and their images. Precompiled for Linux, macOS and FreeBSD; CRuby only.'
+  Word documents from one model, with its own XML, zip and PDF readers and writers.
+  It reads PDF, XLSX, XLS, ODS and DOCX back: as Markdown, as typed structure, and
+  their images. Full-page PDF rendering uses the pure-Rust Hayro renderer. Precompiled
+  for Linux, macOS and FreeBSD; CRuby only.'
 email:
 - terminale@gmail.com
 executables: []
@@ -58,9 +59,12 @@ files:
 - ext/imprimatur_native/core/src/barcode/ean.rs
 - ext/imprimatur_native/core/src/barcode/gs1.rs
 - ext/imprimatur_native/core/src/barcode/matrix.rs
+- ext/imprimatur_native/core/src/bin/imprimatur-render-worker.rs
+- ext/imprimatur_native/core/src/bytes.rs
 - ext/imprimatur_native/core/src/doc.rs
 - ext/imprimatur_native/core/src/doc/paragraph.rs
 - ext/imprimatur_native/core/src/doc/picture.rs
+- ext/imprimatur_native/core/src/doc/size.rs
 - ext/imprimatur_native/core/src/doc/symbol.rs
 - ext/imprimatur_native/core/src/doc/table.rs
 - ext/imprimatur_native/core/src/docx.rs
@@ -94,22 +98,30 @@ files:
 - ext/imprimatur_native/core/src/read/ole.rs
 - ext/imprimatur_native/core/src/read/package.rs
 - ext/imprimatur_native/core/src/read/pdf.rs
+- ext/imprimatur_native/core/src/read/pdf/bounded.rs
 - ext/imprimatur_native/core/src/read/pdf/cmap.rs
 - ext/imprimatur_native/core/src/read/pdf/content.rs
 - ext/imprimatur_native/core/src/read/pdf/content/geometry.rs
 - ext/imprimatur_native/core/src/read/pdf/content/operands.rs
+- ext/imprimatur_native/core/src/read/pdf/content/state.rs
 - ext/imprimatur_native/core/src/read/pdf/crypt.rs
 - ext/imprimatur_native/core/src/read/pdf/document.rs
+- ext/imprimatur_native/core/src/read/pdf/document/pages.rs
 - ext/imprimatur_native/core/src/read/pdf/filter.rs
 - ext/imprimatur_native/core/src/read/pdf/font.rs
 - ext/imprimatur_native/core/src/read/pdf/glyphs.rs
 - ext/imprimatur_native/core/src/read/pdf/glyphs.txt
 - ext/imprimatur_native/core/src/read/pdf/images.rs
+- ext/imprimatur_native/core/src/read/pdf/isolation.rs
+- ext/imprimatur_native/core/src/read/pdf/isolation/protocol.rs
+- ext/imprimatur_native/core/src/read/pdf/isolation/system.rs
+- ext/imprimatur_native/core/src/read/pdf/isolation/worker.rs
 - ext/imprimatur_native/core/src/read/pdf/layout.rs
 - ext/imprimatur_native/core/src/read/pdf/layout/bidi.rs
 - ext/imprimatur_native/core/src/read/pdf/lexer.rs
 - ext/imprimatur_native/core/src/read/pdf/object.rs
 - ext/imprimatur_native/core/src/read/pdf/object/name.rs
+- ext/imprimatur_native/core/src/read/pdf/render.rs
 - ext/imprimatur_native/core/src/read/pdf/xref.rs
 - ext/imprimatur_native/core/src/read/span.rs
 - ext/imprimatur_native/core/src/read/xls.rs
@@ -118,6 +130,7 @@ files:
 - ext/imprimatur_native/core/src/read/xlsx/formats.rs
 - ext/imprimatur_native/core/src/script.rs
 - ext/imprimatur_native/core/src/style.rs
+- ext/imprimatur_native/core/src/test_support/font.rs
 - ext/imprimatur_native/core/src/xlsx.rs
 - ext/imprimatur_native/core/src/xlsx/autofit.rs
 - ext/imprimatur_native/core/src/xlsx/cell.rs
@@ -142,6 +155,7 @@ files:
 - ext/imprimatur_native/ffi/src/convert.rs
 - ext/imprimatur_native/ffi/src/document.rs
 - ext/imprimatur_native/ffi/src/lib.rs
+- ext/imprimatur_native/ffi/src/pdf.rs
 - ext/imprimatur_native/ffi/src/read.rs
 - ext/imprimatur_native/ffi/src/sheets.rs
 - ext/imprimatur_native/ffi/src/style.rs
@@ -152,6 +166,7 @@ files:
 - lib/imprimatur/error.rb
 - lib/imprimatur/formula.rb
 - lib/imprimatur/native.rb
+- lib/imprimatur/pdf_reader.rb
 - lib/imprimatur/reader.rb
 - lib/imprimatur/spreadsheet.rb
 - lib/imprimatur/style.rb