imprimatur 0.4.0-aarch64-linux-gnu → 0.5.0-aarch64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 820b696bf9efd260711282d1ad700b843939f469797577f578db69490d90795c
-  data.tar.gz: a53d88596e77e76cfa13e967ff9a095f7f996d0d21ffb3aa2b1b6bf6bcfcba9a
+  metadata.gz: 5a6d6451a7a370921f43b37e27a8edb7d886a4923981afd28a256b424b85234e
+  data.tar.gz: e74c978a45ce43cc0856b186b71f38d3204aea8cb71c4f0ed5d961bd4f0dc874
 SHA512:
-  metadata.gz: 0a0bec11ea0fe229a56b729d3c40f8ef8f397d4940780a0460d2772ef5cec8529f7ec97dfcd99759b7b5fd30fa6a026a62d97115a94c113857af06d563616800
-  data.tar.gz: a659697da26c4e7878a17f6d2442bc53403dbb926f91d930e026a9468f00437a4403b14325f00b3d9e6d63580074d8e83e1f4b22ef3a163b4797d80aa2ea9513
+  metadata.gz: bf5c3cc806be6379e109c335d65e4b1f84662cbdcb569db4ae0e9fd0e028d4185cf0f9f0b4cd7cc37ac00cc8a313878aaddaee276898b5835e4365f25fe0dfb4
+  data.tar.gz: 0ac1716d1208f48001683efafd3bba638ddc134ff1d67c545a7ad123f99213ee9ff83a96eb7603ca3f3f64ba1cdb8a14507128f530adf21c3e6a5ab989ebca95

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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

@@ -318,6 +318,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

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.5.0'
 end

data/lib/imprimatur.rb

@@ -66,7 +66,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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imprimatur
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: aarch64-linux-gnu
 authors:
 - Abdelkader Boudih