stationery 0.9.0 → 0.10.0

data/lib/stationery/layout/image.rb

@@ -4,7 +4,8 @@ module Stationery
   module Layout
     # An image sized by width, height, both, or a box to fit into (aspect
     # preserved), never wider than the space it is given. One pixel is one
-    # point when no size is given. `fit: :cover` fills `width:` × `height:`
+    # point when no size is given; a Float width up to 1 is a fraction of the
+    # space (`width: 0.5`), as for boxes and columns. `fit: :cover` fills `width:` × `height:`
     # instead, scaling up and clipping the excess around the centre.
     # `radius:` clips to rounded corners and `rotate:` (degrees, clockwise)
     # turns the painted image around the centre of its rectangle; neither
@@ -37,14 +38,16 @@ module Stationery
       end
 
       def size(available)
-        width, height = requested
+        width, height = requested(available)
         return [width, height] if width <= available
 
         [available, height * available / width]
       end
 
       def measure(width) = size(width)[1]
-      def fixed_width(available) = size(available)[0]
+      # A fractional width is a share of the space offered here; measuring and
+      # painting are then given the width that came out of it.
+      def fixed_width(available) = fraction? ? tidy(available * @width) : size(available)[0]
       def natural_width = requested[0]
       def min_width = 0
 
@@ -100,19 +103,22 @@ module Stationery
         @image
       end
 
-      def requested
+      def requested(available = nil)
         iw = @image.width.to_f
         ih = @image.height.to_f
+        width = fraction? ? (available || tidy(iw * @width)) : @width
         if @fit.is_a?(Array)
           scale = [@fit[0] / iw, @fit[1] / ih].min
           [iw * scale, ih * scale].map { |v| tidy(v) }
-        elsif @width && @height then [@width, @height]
-        elsif @width then [@width, tidy(ih * @width / iw)]
+        elsif width && @height then [width, @height]
+        elsif width then [width, tidy(ih * width / iw)]
         elsif @height then [tidy(iw * @height / ih), @height]
         else [@image.width, @image.height]
         end
       end
 
+      def fraction? = @width.is_a?(Float) && @width <= 1
+
       def tidy(value) = value.round(6)
     end
   end

data/lib/stationery/layout/mark.rb

@@ -31,6 +31,8 @@ module Stationery
       def fixed_width(available) = @child.fixed_width(available)
       def splittable? = @child.splittable?
       def page_break? = @child.page_break?
+      def breaks? = @child.breaks?
+      def leading_break? = @child.leading_break?
       def avoid_break? = @child.avoid_break?
       def keep_with_next = @child.keep_with_next
 

data/lib/stationery/layout/node.rb

@@ -42,6 +42,10 @@ module Stationery
       # The width this node is laid out at inside a parent of `available`.
       def width_in(available) = fixed_width(available) || available
       def page_break? = false
+      # Whether a page break lies somewhere inside (a flow holding one).
+      def breaks? = false
+      # Whether it starts with a page break (a flow whose first node is one).
+      def leading_break? = false
 
       def split(width, height, **)
         measure(width) <= height + EPSILON ? [self, nil] : [nil, self]

data/lib/stationery/layout/text.rb

@@ -2,21 +2,34 @@
 
 module Stationery
   module Layout
-    # A paragraph of styled runs. Splits between lines.
+    # A paragraph of styled runs. Splits between lines; `orphans:` is the
+    # fewest lines a split leaves at the foot of a page and `widows:` the
+    # fewest it carries to the next (1 and 1: any line). A paragraph that
+    # cannot meet them moves to the next page whole, unless it is already
+    # first on a fresh page, where it splits as best it can.
     class Text < Node
       attr_reader :runs
 
-      def initialize(runs, context:, align: :left, leading: 0, paragraph: nil, tag: Tagging::Element.new(:P))
+      def initialize(runs, context:, align: :left, leading: 0, orphans: 1, widows: 1, paragraph: nil,
+                     tag: Tagging::Element.new(:P))
         super()
         @tag = tag
         @runs = context.book.fallback(runs)
         @context = context
         @align = align
         @leading = leading
+        @orphans = self.class.lines_option(:orphans, orphans)
+        @widows = self.class.lines_option(:widows, widows)
         @paragraph = paragraph
         @paragraphs = {}
       end
 
+      def self.lines_option(name, value)
+        return value if value.is_a?(Integer) && value >= 1
+
+        raise ArgumentError, "#{name}: must be an Integer of at least 1, got #{value.inspect}"
+      end
+
       def splittable? = true
 
       def measure(width) = paragraph(width).height
@@ -25,9 +38,11 @@ module Stationery
         paragraph(width).draw(canvas, x, y, tag: @tag)
       end
 
-      def split(width, height, **)
+      def split(width, height, fresh: false, **)
         head, tail = paragraph(width).split(height)
-        [head && from(head), tail && from(tail)]
+        return [head && from(head), tail && from(tail)] if (@orphans == 1 && @widows == 1) || !(head && tail)
+
+        keep_lines(paragraph(width), head.lines.size, fresh:)
       end
 
       def fit(width, height, overflow:)
@@ -38,19 +53,40 @@ module Stationery
         @natural_width ||= paragraph(Float::INFINITY).lines.map(&:width).max || 0
       end
 
+      # The widest piece that cannot be broken: a word, or one break unit of a
+      # word with CJK characters.
       def min_width
         @min_width ||= @runs.flat_map do |run|
-          style = run.style
-          font = @context.book.resolve(style).first
-          run.text.delete(::Stationery::Text::Wrapper::SOFT_HYPHEN).split(/[ \t\n]+/).map do |word|
-            font.width_of(word, style.render_size, letter_spacing: style.letter_spacing, kerning: style.kerning,
-                                                   ligatures: style.ligatures, features: style.features)
+          font = @context.book.resolve(run.style).first
+          run.text.delete(::Stationery::Text::Wrapper::SOFT_HYPHEN).split(/[ \t\n\u200B]+/).map do |word|
+            next piece_width(font, run.style, word) unless ::Stationery::Text::Breaks.cjk?(word)
+
+            ::Stationery::Text::Breaks.units(word).map { |unit, _| piece_width(font, run.style, unit) }.max
           end
         end.max || 0
       end
 
       private
 
+      # Applies orphans and widows to a split after `fitting` lines: carries
+      # more lines over for the widows, then moves the paragraph whole when
+      # too few would stay. First on a fresh page nothing can move, so the
+      # widows are honoured if a line can still stay and the orphans are not.
+      def keep_lines(paragraph, fitting, fresh:)
+        total = paragraph.lines.size
+        kept = [fitting, total - @widows].min
+        kept = fitting if fresh && kept < 1
+        return [nil, self] if !fresh && (kept < @orphans || total < @orphans + @widows)
+
+        head, tail = paragraph.split_at(kept)
+        [head && from(head), tail && from(tail)]
+      end
+
+      def piece_width(font, style, text)
+        font.width_of(text, style.render_size, letter_spacing: style.letter_spacing, kerning: style.kerning,
+                                               ligatures: style.ligatures, features: style.features)
+      end
+
       def paragraph(width)
         @paragraph || (@paragraphs[width] ||= ::Stationery::Text::Paragraph.new(
           @runs, book: @context.book, width:, align: @align, leading: @leading, fallback_style: @context.style
@@ -58,7 +94,8 @@ module Stationery
       end
 
       def from(paragraph)
-        self.class.new(@runs, context: @context, align: @align, leading: @leading, paragraph:, tag: @tag)
+        self.class.new(@runs, context: @context, align: @align, leading: @leading, orphans: @orphans, widows: @widows,
+                              paragraph:, tag: @tag)
       end
     end
   end

data/lib/stationery/pdf/assembler.rb

@@ -11,10 +11,16 @@ module Stationery
       # with `xmp_extensions:` as further schemas and `xmp_schemas:` describing
       # them to PDF/A (see XMP); `conformance:` (a PDF::Conformance) adds what
       # PDF/A and PDF/UA ask of the file; `signature:` (a PDF::Signature)
-      # signs it.
+      # signs it. `sink:` (anything answering `call(bytes)`) receives the file
+      # in pieces as each page is written, in the order the objects are
+      # flushed, instead of one String at the end; a signature needs the
+      # finished file, so it cannot be streamed.
       def initialize(pages:, resources:, info: {}, outline: [], encryption: nil, tagging: nil, lang: nil,
                      page_labels: nil, attachments: [], xmp: true, xmp_extensions: {}, xmp_schemas: [],
-                     conformance: nil, signature: nil)
+                     conformance: nil, signature: nil, sink: nil)
+        raise ArgumentError, "a signed document cannot be streamed: sign needs the whole file" if signature && sink
+
+        @sink = sink
         @xmp_schemas = xmp_schemas
         @conformance = conformance
         @signature = signature
@@ -31,15 +37,19 @@ module Stationery
         @encryption = encryption
       end
 
+      # The file as a String, or the number of bytes streamed to the sink.
       def render
-        writer = Writer.new(encryption: @encryption)
+        writer = Writer.new(encryption: @encryption, sink: @sink)
         tree = writer.reserve
         refs = @resources.build(writer)
         @form = Forms::AcroForm.new(writer, fonts: refs.fetch(:Font), signature: @signature,
                                             need_appearances: @conformance.nil? && @signature.nil?)
         kids = @kids = @pages.map { writer.reserve }
         @structure = @tagging && Tagging::Writer.new(@tagging, pages: @pages, refs: kids)
-        @pages.each_with_index { |page, index| write_page(writer, page, kids[index], tree, refs) }
+        @pages.each_with_index do |page, index|
+          write_page(writer, page, kids[index], tree, refs)
+          writer.flush
+        end
         writer.set(tree, { Type: :Pages, Kids: kids, Count: kids.size })
         outlines = OutlineWriter.new(writer, @outline, kids).write
         now = Time.now

data/lib/stationery/pdf/signature/cms.rb

@@ -10,6 +10,9 @@ module Stationery
       # signer's certificate; there is no signing-time attribute, a PDF keeps
       # that in the signature dictionary's /M.
       #
+      # A timestamp token over the signature value (see Timestamp) goes into
+      # the unsigned attributes, which makes the signature PAdES baseline B-T.
+      #
       # Ruby's OpenSSL::PKCS7 cannot add signed attributes, so the structure
       # is built with OpenSSL::ASN1. RSA keys sign with PKCS #1 v1.5, EC keys
       # with ECDSA, both over SHA-256.
@@ -18,6 +21,7 @@ module Stationery
           data: "1.2.840.113549.1.7.1", signed_data: "1.2.840.113549.1.7.2",
           content_type: "1.2.840.113549.1.9.3", message_digest: "1.2.840.113549.1.9.4",
           signing_certificate_v2: "1.2.840.113549.1.9.16.2.47", sha256: "2.16.840.1.101.3.4.2.1",
+          signature_timestamp_token: "1.2.840.113549.1.9.16.2.14",
           rsa: "1.2.840.113549.1.1.1", ecdsa_sha256: "1.2.840.10045.4.3.2"
         }.freeze
 
@@ -28,16 +32,18 @@ module Stationery
           @chain = chain
         end
 
-        # The DER of the SignedData signing `data`.
-        def sign(data)
+        # The DER of the SignedData signing `data`. `timestamp:` is a callable
+        # given the signature value and answering a timestamp token (DER).
+        def sign(data, timestamp: nil)
           attributes = attributes(OpenSSL::Digest::SHA256.digest(data))
           signature = @key.sign("SHA256", asn1::Set.new(attributes).to_der)
+          unsigned = timestamp && [attribute(:signature_timestamp_token, asn1.decode(timestamp.call(signature)))]
           content = asn1::Sequence.new([
                                          asn1::Integer.new(1),
                                          asn1::Set.new([algorithm(:sha256)]),
                                          asn1::Sequence.new([oid(:data)]),
                                          implicit(certificates),
-                                         asn1::Set.new([signer(attributes, signature)])
+                                         asn1::Set.new([signer(attributes, signature, unsigned)])
                                        ])
           asn1::Sequence.new([oid(:signed_data), asn1::ASN1Data.new([content], 0, :CONTEXT_SPECIFIC)]).to_der
         end
@@ -46,7 +52,7 @@ module Stationery
 
         def asn1 = OpenSSL::ASN1
         def oid(name) = asn1::ObjectId.new(OIDS.fetch(name))
-        def implicit(items) = asn1::Set.new(items, 0, :IMPLICIT, :CONTEXT_SPECIFIC)
+        def implicit(items, tag = 0) = asn1::Set.new(items, tag, :IMPLICIT, :CONTEXT_SPECIFIC)
         def certificates = [@certificate, *@chain].map { |certificate| asn1.decode(certificate.to_der) }
 
         # RSA and the digests carry an explicit NULL parameter, ECDSA none.
@@ -70,16 +76,18 @@ module Stationery
           asn1::Sequence.new([asn1::Sequence.new([asn1::Sequence.new([hash])])])
         end
 
-        def signer(attributes, signature)
+        def signer(attributes, signature, unsigned)
           issuer = asn1.decode(@certificate.issuer.to_der)
-          asn1::Sequence.new([
-                               asn1::Integer.new(1),
-                               asn1::Sequence.new([issuer, asn1::Integer.new(@certificate.serial)]),
-                               algorithm(:sha256),
-                               implicit(attributes),
-                               @key.is_a?(OpenSSL::PKey::EC) ? algorithm(:ecdsa_sha256, null: false) : algorithm(:rsa),
-                               asn1::OctetString.new(signature)
-                             ])
+          info = [
+            asn1::Integer.new(1),
+            asn1::Sequence.new([issuer, asn1::Integer.new(@certificate.serial)]),
+            algorithm(:sha256),
+            implicit(attributes),
+            @key.is_a?(OpenSSL::PKey::EC) ? algorithm(:ecdsa_sha256, null: false) : algorithm(:rsa),
+            asn1::OctetString.new(signature)
+          ]
+          info << implicit(unsigned, 1) if unsigned
+          asn1::Sequence.new(info)
         end
       end
     end

data/lib/stationery/pdf/signature/timestamp.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    class Signature
+      # A signature timestamp from an RFC 3161 time-stamping authority (TSA):
+      # the TSA signs the digest of the signature value and the time it saw
+      # it, and the token goes into the signature's unsigned attributes, which
+      # makes it PAdES baseline B-T. A reader can then trust the signing time
+      # even after the signer's certificate expires.
+      #
+      # `sign timestamp: "https://tsa.example/tsr"`, or a Hash with `url:`,
+      # `username:`/`password:` for a TSA that wants HTTP basic auth, `hash:`
+      # (:sha256, the default, :sha384 or :sha512) and `client:`, a callable
+      # given the request DER and answering the response DER, in place of
+      # the built-in HTTP client. Anything short of a token over exactly what
+      # was asked raises SignatureError: a document is never quietly written
+      # without the timestamp it was asked for.
+      class Timestamp
+        OPTIONS = %i[url username password hash client].freeze
+        DIGESTS = { sha256: "SHA256", sha384: "SHA384", sha512: "SHA512" }.freeze
+        # Status values a TSA answers with when it did grant the token
+        # (granted, grantedWithMods).
+        GRANTED = [0, 1].freeze
+        REQUEST_TYPE = "application/timestamp-query"
+        REPLY_TYPE = "application/timestamp-reply"
+
+        attr_reader :url, :hash
+
+        # The timestamp for `spec`: a URL String, a Hash of OPTIONS, or nil.
+        def self.for(spec)
+          return unless spec
+
+          spec = { url: spec.to_s } unless spec.is_a?(Hash)
+          spec = spec.transform_keys(&:to_sym)
+          unknown = spec.keys - OPTIONS
+          unless unknown.empty?
+            raise ArgumentError, "unknown timestamp option: #{unknown.join(", ")} (use #{OPTIONS.join(", ")})"
+          end
+
+          new(**spec)
+        end
+
+        def initialize(url: nil, username: nil, password: nil, hash: :sha256, client: nil)
+          raise ArgumentError, "sign timestamp: needs the TSA's url:" if url.to_s.empty? && client.nil?
+
+          @url = url&.to_s
+          @username = username
+          @password = password
+          @hash = hash.to_sym
+          @client = client
+          return if DIGESTS[@hash]
+
+          raise ArgumentError,
+                "timestamp hash: is #{DIGESTS.keys.join(", ")}, got #{hash.inspect}"
+        end
+
+        # The timestamp token (a ContentInfo, DER) the TSA issued over
+        # `signature`, checked against what was asked.
+        def token(signature)
+          request = request_for(OpenSSL::Digest.digest(DIGESTS.fetch(@hash), signature))
+          response = parse((@client || method(:post)).call(request.to_der))
+          check!(response, request)
+          response.token.to_der
+        end
+
+        private
+
+        def request_for(digest)
+          request = OpenSSL::Timestamp::Request.new
+          request.algorithm = DIGESTS.fetch(@hash)
+          request.message_imprint = digest
+          request.nonce = OpenSSL::BN.rand(64)
+          request.cert_requested = true
+          request
+        end
+
+        def parse(der)
+          OpenSSL::Timestamp::Response.new(der.to_s)
+        rescue OpenSSL::Timestamp::TimestampError, TypeError => e
+          raise SignatureError, "#{tsa} did not answer with a timestamp response: #{e.message}"
+        end
+
+        def check!(response, request)
+          status = response.status.to_i
+          unless GRANTED.include?(status) && response.token
+            text = [*response.status_text, response.failure_info].compact.map(&:to_s).reject(&:empty?)
+            raise SignatureError,
+                  "#{tsa} refused the timestamp (status #{status}#{": #{text.join(", ")}" unless text.empty?})"
+          end
+
+          info = response.token_info
+          raise SignatureError, "#{tsa} answered another request (nonce differs)" unless info.nonce == request.nonce
+          return if info.message_imprint == request.message_imprint
+
+          raise SignatureError, "#{tsa} timestamped something else (message imprint differs)"
+        end
+
+        def tsa = "timestamp: #{@url || "the TSA"}"
+
+        # POSTs the request as RFC 3161 over HTTP asks for it.
+        def post(body)
+          require "net/http"
+          uri = URI.parse(@url)
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = REQUEST_TYPE
+          request["Accept"] = REPLY_TYPE
+          request.basic_auth(@username, @password.to_s) if @username
+          request.body = body
+          response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
+          raise SignatureError, "#{tsa} answered HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+          response.body
+        rescue SystemCallError, IOError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError => e
+          raise SignatureError, "#{tsa} could not be reached: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/stationery/pdf/signature.rb

@@ -8,22 +8,26 @@ module Stationery
     #
     # The file is written once with room for the signature (`contents_size:`
     # bytes) and a placeholder /ByteRange; #apply then fills both in place, so
-    # no offset moves. Timestamps (PAdES-T), long-term validation data and a
-    # second signature need incremental updates, which Stationery does not
-    # write.
+    # no offset moves. `timestamp:` adds a time-stamping authority's token to
+    # the signature (PAdES baseline B-T, see Timestamp). Long-term validation
+    # data and a second signature need incremental updates, which Stationery
+    # does not write.
     #
     # OpenSSL is loaded when the first signature is made, never before.
     class Signature
       SUBFILTER = :"ETSI.CAdES.detached"
       CONTENTS_SIZE = 8192
+      # A timestamp token brings the TSA's certificate chain along.
+      TIMESTAMPED_CONTENTS_SIZE = 16_384
       BYTE_RANGE = "[0 0000000000 0000000000 0000000000]"
-      OPTIONS = %i[certificate key chain passphrase reason location contact name field at contents_size].freeze
+      OPTIONS = %i[certificate key chain passphrase reason location contact name field at contents_size
+                   timestamp].freeze
       # Options a Symbol names a document method for; elsewhere it is a value.
       SECRETS = %i[certificate key chain passphrase].freeze
       # Print and Locked: the widget of a signature that fills no field.
       INVISIBLE = 132
 
-      attr_reader :certificate, :key, :chain, :field, :at, :contents_size
+      attr_reader :certificate, :key, :chain, :field, :at, :contents_size, :timestamp
 
       class << self
         # The signature for `spec` (the options of `sign` and `to_pdf(sign:)`,
@@ -73,14 +77,15 @@ module Stationery
       end
 
       def initialize(certificate: nil, key: nil, chain: [], passphrase: nil, field: nil, at: Time.now,
-                     contents_size: CONTENTS_SIZE, **details)
+                     contents_size: nil, timestamp: nil, **details)
         require "openssl"
         @certificate = certificate_for(certificate, "certificate:")
         @key = key_for(key, passphrase)
         @chain = Array(chain).map { |link| certificate_for(link, "chain:") }
         @field = field&.to_s
         @at = at
-        @contents_size = contents_size
+        @timestamp = Timestamp.for(timestamp)
+        @contents_size = contents_size || (@timestamp ? TIMESTAMPED_CONTENTS_SIZE : CONTENTS_SIZE)
         @details = self.class.check(details)
         match!
       end
@@ -110,7 +115,8 @@ module Stationery
         range, first, last = gap(pdf)
         pdf.bytesplice(range, BYTE_RANGE.bytesize,
                        "[0 #{first} #{last} #{pdf.bytesize - last}]".ljust(BYTE_RANGE.bytesize))
-        signature = CMS.new(@certificate, @key, @chain).sign(pdf.byteslice(0, first) + pdf.byteslice(last..))
+        signed = pdf.byteslice(0, first) + pdf.byteslice(last..)
+        signature = CMS.new(@certificate, @key, @chain).sign(signed, timestamp: @timestamp&.method(:token))
         raise ArgumentError, too_large(signature) if signature.bytesize > @contents_size
 
         pdf.bytesplice(first + 1, @contents_size * 2, signature.unpack1("H*").upcase.ljust(@contents_size * 2, "0"))
@@ -133,7 +139,8 @@ module Stationery
       end
 
       def too_large(signature)
-        "the signature takes #{signature.bytesize} bytes, more than contents_size: #{@contents_size} leaves for it; " \
+        what = @timestamp ? "the signature and its timestamp take" : "the signature takes"
+        "#{what} #{signature.bytesize} bytes, more than contents_size: #{@contents_size} leaves for it; " \
           "pass a larger contents_size:"
       end
 

data/lib/stationery/pdf/writer.rb

@@ -5,15 +5,26 @@ require "digest/md5"
 module Stationery
   module PDF
     # Collects numbered objects and writes them as a PDF file with a classic
-    # cross-reference table.
+    # cross-reference table. `render` returns the file as a String with the
+    # objects in numbered order. With a `sink:` (anything answering
+    # `call(bytes)`) the file goes there in pieces instead: `flush` writes every
+    # object set so far and drops it, so objects leave in the order they were
+    # flushed and the first bytes leave before the last page is assembled.
     class Writer
       HEADER = "%PDF-1.7\n%\xE2\xE3\xCF\xD3\n".b
+      WRITTEN = Object.new.freeze
 
       # `encryption` (an Encryption::StandardSecurity) encrypts every string
       # and stream except those of its own /Encrypt dictionary.
-      def initialize(encryption: nil)
+      def initialize(encryption: nil, sink: nil)
         @objects = []
+        @offsets = []
         @encryption = encryption
+        @sink = sink
+        @buffer = HEADER.dup unless sink
+        @size = HEADER.bytesize
+        @digest = Digest::MD5.new if sink && !encryption
+        announce(HEADER) if sink
       end
 
       # Hands out a reference now and lets the object be set later, so a page
@@ -24,6 +35,8 @@ module Stationery
       end
 
       def set(ref, value)
+        raise Error, "object #{ref.id} is already written" if @objects[ref.id - 1].equal?(WRITTEN)
+
         @objects[ref.id - 1] = value
         ref
       end
@@ -32,43 +45,84 @@ module Stationery
         set(reserve, value)
       end
 
+      # With a sink: writes every object set and not yet written, lowest number
+      # first, and drops it. References to objects still unset stay valid, as
+      # the cross-reference table is written last. Without a sink it does
+      # nothing: the String keeps its objects in numbered order.
+      def flush
+        return unless @sink
+
+        @encrypt ||= reserve if @encryption
+        write_pending
+      end
+
+      # Finishes the file: the remaining objects, the cross-reference table
+      # and the trailer. Returns the whole file as a String when there is no
+      # sink, else the number of bytes handed to it.
       def render(root:, info:)
+        set(@encrypt ||= reserve, @encryption.dictionary) if @encryption
         if (missing = @objects.index(nil))
           raise Error, "object #{missing + 1} reserved but never set"
         end
 
-        @encrypt = @encryption && add(@encryption.dictionary)
-        out = HEADER.dup
-        offsets = @objects.each_with_index.map { |object, index| write_object(out, index + 1, object) }
-        xref = out.bytesize
-        id = HexString.new(@encryption ? @encryption.file_id : Digest::MD5.digest(out))
+        write_pending
+        xref = @size
+        id = HexString.new(file_id)
 
-        out << "xref\n0 #{@objects.size + 1}\n0000000000 65535 f \n"
-        offsets.each { |offset| out << format("%010d 00000 n \n", offset) }
-        out << "trailer\n" << Serializer.dump(trailer(root, info, id))
-        out << "\nstartxref\n#{xref}\n%%EOF\n"
+        emit("xref\n0 #{@objects.size + 1}\n0000000000 65535 f \n")
+        @offsets.each { |offset| emit(format("%010d 00000 n \n", offset)) }
+        emit("trailer\n#{Serializer.dump(trailer(root, info, id))}")
+        emit("\nstartxref\n#{xref}\n%%EOF\n")
+        @buffer || @size
       end
 
       private
 
+      def write_pending
+        @objects.each_with_index do |object, index|
+          next if object.nil? || object.equal?(WRITTEN)
+
+          write_object(index + 1, object)
+          @objects[index] = WRITTEN
+        end
+      end
+
       def trailer(root, info, id)
         trailer = { Size: @objects.size + 1, Root: root, Info: info, ID: [id, id] }
         @encrypt ? trailer.merge(Encrypt: @encrypt) : trailer
       end
 
-      def write_object(out, number, object)
-        offset = out.bytesize
+      def write_object(number, object)
+        @offsets[number - 1] = @size
         crypt = crypt_for(number)
-        out << "#{number} 0 obj\n"
+        emit("#{number} 0 obj\n")
         if object.is_a?(Stream)
           data = crypt ? crypt.call(object.data) : object.data
-          out << Serializer.dump(object.dictionary.merge(Length: data.bytesize), crypt)
-          out << "\nstream\n" << data << "\nendstream"
+          emit(Serializer.dump(object.dictionary.merge(Length: data.bytesize), crypt))
+          emit("\nstream\n")
+          emit(data)
+          emit("\nendstream")
         else
-          out << Serializer.dump(object, crypt)
+          emit(Serializer.dump(object, crypt))
         end
-        out << "\nendobj\n"
-        offset
+        emit("\nendobj\n")
+      end
+
+      def emit(bytes)
+        @size += bytes.bytesize
+        @sink ? announce(bytes) : @buffer << bytes
+      end
+
+      def announce(bytes)
+        @digest&.update(bytes)
+        @sink.call(bytes)
+      end
+
+      # The encryption's own identifier, else a digest of the file so far.
+      def file_id
+        return @encryption.file_id if @encryption
+
+        @digest ? @digest.digest : Digest::MD5.digest(@buffer)
       end
 
       # The Serializer hook: encrypts a string or stream with this object's key.