imprimatur 0.4.0-aarch64-linux-gnu → 0.6.0-aarch64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 820b696bf9efd260711282d1ad700b843939f469797577f578db69490d90795c
-  data.tar.gz: a53d88596e77e76cfa13e967ff9a095f7f996d0d21ffb3aa2b1b6bf6bcfcba9a
+  metadata.gz: 60b0c7b03b95799ce827fc16a4c288dc929647e0fc94c6672bac555d75b85140
+  data.tar.gz: 11b2699bbe2481da51deeeeada85731c85d7577d3cfd06551093866edff29ab1
 SHA512:
-  metadata.gz: 0a0bec11ea0fe229a56b729d3c40f8ef8f397d4940780a0460d2772ef5cec8529f7ec97dfcd99759b7b5fd30fa6a026a62d97115a94c113857af06d563616800
-  data.tar.gz: a659697da26c4e7878a17f6d2442bc53403dbb926f91d930e026a9468f00437a4403b14325f00b3d9e6d63580074d8e83e1f4b22ef3a163b4797d80aa2ea9513
+  metadata.gz: e710314613e0b8fde5895a7b751d6458fd52749cd44167828f7a3cee6e9abdebf98befe86c78a832913e3b362e0cbc0b57072ed35742b5bab1dd11e64918623e
+  data.tar.gz: 1a5eeda8859cafa2ae3ac1b3bac3b50954d4bfbcb7b4562d6c0c04280f5195192eb20fa07aaf167f364e7022e9d5b338ceab269852be9bebd0d40bf9ceaf6d11

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## Unreleased
+
+- Add native PDF metadata, bounded page reads with explicit failure states,
+  and optional pure-Rust full-page PNG rendering.
+- Keep scanned and blank page structure available without a text layer.
+- Render PDFs through a bundled Rust worker with time, memory and output limits;
+  cancellation kills and reaps it. macOS uses an RSS watchdog, not a hard cap.
+
+## [0.6.0](https://github.com/seuros/imprimatur/compare/v0.5.0...v0.6.0) (2026-10-25)
+
+
+### Features
+
+* bound PDF reads and rendering; deduplicate Rust ([420e096](https://github.com/seuros/imprimatur/commit/420e096591ef08190427c7b090840dcd761010b4))
+* **doc:** set the body font size ([44f7617](https://github.com/seuros/imprimatur/commit/44f76170fd1ad29f143c1ef22c355fd1c1cbf8e1))
+
+
+### Bug Fixes
+
+* enforce render limits across Unix platforms ([5c7f0ba](https://github.com/seuros/imprimatur/commit/5c7f0bab2076681782c6bfa2de6062ad53c0e7f9))
+
+## [0.5.0](https://github.com/seuros/imprimatur/compare/v0.4.0...v0.5.0) (2026-10-18)
+
+
+### Features
+
+* a binary String is always a document's bytes, a path must name a regular file, and reads stop at max_bytes ([3484a64](https://github.com/seuros/imprimatur/commit/3484a64b791beb2e9f90cd485441fae255e223f0))
+
 ## [0.4.0](https://github.com/seuros/imprimatur/compare/v0.3.0...v0.4.0) (2026-10-18)
 
 

data/README.md

@@ -7,10 +7,9 @@ a 40,000-character cell is refused at the door, not discovered by Excel's
 
 - **A Ruby DSL over a native core.** The core is also published on its own,
   as `imprimatur` on crates.io; the gem wraps it.
-- **No third-party format stack.** The XML writer and the zip container are
-  written here, from ECMA-376 and the zip specification; only deflate
-  (`miniz_oxide`) and CRC-32 (`crc32fast`) come from crates, and QR Code and
-  Data Matrix encoding (`qrcode`, `datamatrix`) for barcodes.
+- **Own readers and writers.** XML, zip and PDF reading/writing live here.
+  Optional full-page PDF rendering uses Hayro, a pure-Rust CPU renderer;
+  no Poppler, PDFium, GPU or system fonts are required.
 - **Deterministic.** The same document always gives the same bytes.
 - **Native only.** CRuby 4.0+. No pure Ruby fallback, no JRuby, no TruffleRuby.
 
@@ -178,7 +177,7 @@ Not yet: merged cells, frozen panes, streaming for very large sheets.
 One document, two formats:
 
 ```ruby
-doc = Imprimatur::Document.new(page_size: :a4, page_numbers: true)
+doc = Imprimatur::Document.new(page_size: :a4, font_size: 10, page_numbers: true)
 doc.heading "Quarterly report"
 doc.heading "Sales", level: 2
 doc.paragraph do |p|
@@ -195,12 +194,14 @@ doc.paragraph "Appendix."
 doc.save_pdf("report.pdf")
 doc.save_docx("report.docx")
 
-Imprimatur.pdf("memo.pdf") { it.paragraph "Or in one go." }    # Imprimatur.docx alike
+Imprimatur.pdf("memo.pdf", font_size: 10) { it.paragraph "Or in one go." } # Imprimatur.docx alike
 Imprimatur.pdf(page_size: [200, 200], margin: 10) { it.image qr_png, width: 180 }
 ```
 
 - Headings 1 to 3 (real Word heading styles in DOCX), paragraphs of runs
   (bold, italic, underline, color), alignment, `\n` line breaks and tabs.
+- Body text at `font_size:` points (1 to 1638, in steps of 0.5; 11 unless
+  set), in both formats; headings keep their own sizes.
 - Tables: equal columns, borders, a shaded header row that repeats on every
   page; cells are converted with `to_s`.
 - Pictures: PNG or JPEG (a path, the bytes or an IO), at `width:` or
@@ -318,6 +319,13 @@ fibers keep running, and `Timeout` or `Thread#raise` cancels it.
 `Imprimatur::PasswordRequired` and `Imprimatur::UnsupportedDocument` (legacy
 `.doc`, `.xlsb`, presentations) are the other errors to expect.
 
+A binary String is always the document's bytes, never a path: an upload
+holding `/etc/passwd` or `/dev/zero` is refused as `UnsupportedDocument`,
+not read from the server. A path (a `Pathname`, or a String that is not
+binary and has no document signature) must name a regular file; devices,
+pipes and directories are refused. An IO or a path is read no further than
+`max_bytes:`, so an endless stream or a huge file stops there.
+
 ### Structure and images
 
 Markdown is one rendering of what a read finds. `Imprimatur.content` gives
@@ -326,6 +334,50 @@ pages of headings and paragraphs with their position, a workbook's typed
 cells and comments, a Word document's blocks with their bold, italic and
 linked stretches.
 
+For a PDF without text, `content` still returns every page, its empty
+`blocks` and its `images` count. `markdown` and the text-oriented CLI commands
+still report `NoTextLayer`;
+OCR callers need the structure of scanned and blank pages too.
+
+### Bounded PDF pages and OCR rendering
+
+```ruby
+Imprimatur.pdf_info(upload.download) # => {page_count: 20, encrypted: false}
+result = Imprimatur.pdf_pages(upload.download, first_page: 2, last_page: 10, max_pages: 5)
+result[:pages].each { |page| puts [page[:page], page[:status], page[:text]] }
+png = Imprimatur.render_pdf_page(upload.download, page: 2, max_side: 1568)
+```
+
+`pdf_info` counts actual pages without interpreting their content. `pdf_pages`
+only interprets the selected streams, at most 500 pages by default. Each page
+has `status` (`text`, `empty`, `failed`, `skipped`), `text`, `images` (nil if
+unknown), `truncated` and `reason`. It keeps healthy pages when another is
+damaged. Unlike the tolerant Markdown reader, corrupt Flate streams fail
+explicitly. Limits are 256 KiB of text per page and 8 MiB total
+(`max_page_bytes:`, `max_output_bytes:`); truncation respects UTF-8.
+
+`render_pdf_page` returns an opaque grayscale PNG of the **whole page**, not
+just its scan image; `grayscale: false` keeps color. It bounds the output surface
+before allocation (`max_pixels:`, 4 million) and encoded output
+(`max_output_bytes:`, 8 MiB). Preflight rejects pages drawing more than 40 million
+source-image pixels. Renderer warnings fail instead of silently dropping content.
+The crate exposes `read::pdf::{info, pages, render_page}` (`render` feature) and
+`read::pdf::isolation::render_page_isolated` (`isolation` feature). The latter
+takes an absolute path to the trusted `imprimatur-render-worker` executable.
+The gem bundles that worker and always uses isolated rendering; it never falls
+back to an in-process render or searches PATH.
+
+All three accept the normal read limits. Rendering also accepts `memory_bytes:`
+(1 GiB by default): Linux/FreeBSD enforce an address-space cap; macOS uses a
+sampled RSS watchdog, which can briefly overshoot. A worker is killed and reaped
+on timeout, cancellation or supervisor failure. Rendering has a mandatory
+60-second process ceiling even with `timeout: nil`; a shorter `timeout:` still
+applies. CPU time, output files and core dumps are also limited.
+
+This is resource containment, **not a filesystem/network security sandbox**.
+The raw crate `render_page` remains in-process and cannot interrupt Hayro.
+`max_inflated` bounds our preflight, not Hayro's internal decoders.
+
 ```ruby
 sheet = Imprimatur.content("sales.xlsx")[:sheets].first
 sheet[:rows][1][:cells]
@@ -434,7 +486,7 @@ The core works without Ruby too; see
 
 ```sh
 bundle install
-rake test:all        # cargo test, then the Ruby suite on the compiled extension
+rake test:all        # core, CLI and Ruby suites on the compiled extension
 rake lint            # dictator, cargo fmt --check, clippy
 rake gems:native     # the precompiled gem for this machine, in pkg/
 ```

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/reader.rb

@@ -12,22 +12,29 @@ module Imprimatur
   # Documents in: Markdown, their structure, their images. See
   # {Imprimatur.markdown}, {Imprimatur.content} and {Imprimatur.images}.
   module Reader
-    # File signatures a document's bytes start with; a String that starts
-    # with neither is taken for a path.
+    # File signatures a document's bytes start with; a String that is not
+    # binary and starts with neither is taken for a path.
     SIGNATURES = ["%PDF-".b, "PK\x03\x04".b, "PK\x05\x06".b, "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b].freeze
     private_constant :SIGNATURES
 
+    # The largest document read in unless told, as the native core's own limit.
+    MAX_BYTES = 512 * 1024 * 1024
+    private_constant :MAX_BYTES
+
     # @see Imprimatur.markdown
-    def self.markdown(document, **) = Native.markdown(read(document), *limits(**))
+    def self.markdown(document, max_bytes: nil, **)
+      Native.markdown(read(document, max_bytes), *limits(max_bytes:, **))
+    end
 
     # @see Imprimatur.content
-    def self.content(document, styles: false, **)
-      JSON.parse(Native.content(read(document), *limits(**), styles ? true : false), symbolize_names: true)
+    def self.content(document, styles: false, max_bytes: nil, **)
+      bytes = read(document, max_bytes)
+      JSON.parse(Native.content(bytes, *limits(max_bytes:, **), styles ? true : false), symbolize_names: true)
     end
 
     # @see Imprimatur.images
-    def self.images(document, **)
-      Native.images(read(document), *limits(**)).map do |data, description|
+    def self.images(document, max_bytes: nil, **)
+      Native.images(read(document, max_bytes), *limits(max_bytes:, **)).map do |data, description|
         found = JSON.parse(description, symbolize_names: true)
         Image.new(data:, **Image.members.drop(1).to_h { [it, found[it]] })
       end
@@ -38,22 +45,52 @@ module Imprimatur
       [max_bytes, max_inflated, timeout && Float(timeout)]
     end
 
+    # A path or an IO is read no further than +max_bytes+ (one byte past it
+    # tells it is passed): an endless stream or a huge file stops there.
+    #
     # @api private
-    def self.read(document)
+    def self.read(document, max_bytes = nil)
+      limit = max_bytes.is_a?(Integer) && max_bytes >= 0 ? max_bytes : MAX_BYTES
       case document
-      when Pathname then File.binread(document)
-      when String then bytes?(document) ? document : File.binread(document)
+      when Pathname then file(document, limit)
+      when String then bytes?(document) ? document : file(document, limit)
       else
         raise TypeError, "expected a path, bytes or an IO, not #{document.class}" unless document.respond_to?(:read)
 
-        document.read.to_s.b
+        within(document.read(limit + 1).to_s.b, limit)
       end
     end
 
+    # A binary String (what +File.binread+, a binary IO or a download give)
+    # is bytes, whatever it holds: uploaded bytes never name a file to read.
+    #
     # @api private
     def self.bytes?(string)
+      return true if string.encoding == Encoding::BINARY
+
       head = string.byteslice(0, 1024).b
       SIGNATURES.any? { head.start_with?(it) } || head.include?("%PDF-") || head.include?("\0")
     end
+
+    # A regular file's bytes. Opened without blocking and checked through
+    # the open file, so a pipe cannot hang the read, a device such as
+    # +/dev/zero+ is refused, and the file cannot be swapped in between.
+    #
+    # @api private
+    def self.file(path, limit)
+      File.open(path, File::RDONLY | File::NONBLOCK | File::BINARY) do |io|
+        stat = io.stat
+        raise UnsupportedDocument, "cannot read this document: #{path} is not a regular file" unless stat.file?
+
+        within(stat.size > limit ? '' : io.read(limit + 1).to_s, limit, stat.size)
+      end
+    end
+
+    # @api private
+    def self.within(bytes, limit, size = bytes.bytesize)
+      raise LimitExceeded, 'the document exceeds the input size limit' if [size, bytes.bytesize].max > limit
+
+      bytes
+    end
   end
 end

data/lib/imprimatur/spreadsheet.rb

@@ -123,7 +123,7 @@ module Imprimatur
     # @raise [UnsupportedDocument] a PDF, a Word document or another format
     # @raise [Imprimatur::Error] a damaged workbook, or past a limit
     def self.open(document, styles: false, **limits)
-      new(Native.sheets(Reader.read(document), *Reader.limits(**limits), styles ? true : false))
+      new(Native.sheets(Reader.read(document, limits[:max_bytes]), *Reader.limits(**limits), styles ? true : false))
     end
 
     # @return [Array<Sheet>] in the workbook's order, hidden ones included

data/lib/imprimatur/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imprimatur
-  VERSION = '0.4.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, &)
 
@@ -66,7 +67,8 @@ module Imprimatur
     #   Imprimatur.markdown(File.open('sales.xlsx'))
     #
     # @param document [String, Pathname, #read] a path, the document's bytes
-    #   (told apart by their signature), or an IO
+    #   (a binary String always is; another String only with a document's
+    #   signature), or an IO. A path must name a regular file.
     # @param timeout [Numeric, nil] seconds the read may take (60), +nil+ for none
     # @param max_bytes [Integer, nil] the largest document accepted (512 MiB)
     # @param max_inflated [Integer, nil] decompressed bytes allowed in all (1 GiB)
@@ -91,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.
@@ -99,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.4.0
+  version: 0.6.0
 platform: aarch64-linux-gnu
 authors:
 - Abdelkader Boudih
@@ -10,9 +10,10 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 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: []
@@ -23,12 +24,14 @@ files:
 - LICENSE.txt
 - README.md
 - lib/imprimatur.rb
+- lib/imprimatur/4.0/imprimatur-render-worker
 - lib/imprimatur/4.0/imprimatur_native.so
 - lib/imprimatur/barcode.rb
 - lib/imprimatur/document.rb
 - 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