stationery 0.12.3 → 0.13.0

data/lib/stationery/pdf/factur_x.rb

@@ -20,7 +20,7 @@ module Stationery
       DEFAULT_FILENAME = "factur-x.xml"
       DESCRIPTION = "Factur-X Invoice"
       ROOTS = ["<?xml", "<rsm:CrossIndustryInvoice"].freeze
-      SCHEMA = {
+      SCHEMA = Stationery.shareable(
         name: "Factur-X PDFA Extension Schema", uri: NAMESPACE, prefix: "fx",
         properties: [
           { name: "DocumentFileName", type: "Text", category: "external",
@@ -32,7 +32,7 @@ module Stationery
           { name: "ConformanceLevel", type: "Text", category: "external",
             description: "The conformance level of the embedded XML document" }
         ].freeze
-      }.freeze
+      )
 
       attr_reader :xml, :profile, :filename, :version
 

data/lib/stationery/pdf/serializer.rb

@@ -14,7 +14,7 @@ module Stationery
     module Serializer
       NAME_ESCAPE = %r{[^\x21-\x7E]|[#%()/<>\[\]{}]}n
       LITERAL_ESCAPE = /[\\()\r]/n
-      UTF16_BOM = "\xFE\xFF".b
+      UTF16_BOM = "\xFE\xFF".b.freeze
       # Below it a Float times 10,000 is off by less than TIE / 8, so which
       # way it rounds is certain unless it is within TIE of a half.
       FAST_BELOW = 100_000.0

data/lib/stationery/pdf/writer.rb

@@ -12,7 +12,7 @@ module Stationery
     # 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
+      HEADER = "%PDF-1.7\n%\xE2\xE3\xCF\xD3\n".b.freeze
       WRITTEN = Object.new.freeze
 
       # `encryption` (an Encryption::StandardSecurity) encrypts every string

data/lib/stationery/pdf/xmp.rb

@@ -11,7 +11,7 @@ module Stationery
     # ids, so two renders of one document are byte-identical.
     module XMP
       PACKET_ID = "W5M0MpCehiHzreSzNTczkc9d"
-      PADDING = "#{" " * 63}\n" * 32 # 2 KB of whitespace, as the spec suggests
+      PADDING = ("#{" " * 63}\n" * 32).freeze # 2 KB of whitespace, as the spec suggests
       DC = "http://purl.org/dc/elements/1.1/"
       XMP_NS = "http://ns.adobe.com/xap/1.0/"
       PDF_NS = "http://ns.adobe.com/pdf/1.3/"

data/lib/stationery/preview.rb

@@ -15,20 +15,30 @@ module Stationery
   #     def around_render(_name, params) = I18n.with_locale(params.fetch("locale", I18n.default_locale)) { yield }
   #   end
   class Preview
-    REGISTRY_LOCK = Mutex.new
     HOOKS = %w[around_render].freeze
 
+    # The subclasses defined in one Ractor (see Store), in the order they
+    # were, behind their own lock.
+    class Registry
+      def initialize
+        @classes = []
+        @lock = Mutex.new
+      end
+
+      def <<(subclass) = @lock.synchronize { @classes << subclass }
+      def to_a = @lock.synchronize { @classes.dup }
+    end
+
     class << self
       def inherited(subclass)
         super
-        REGISTRY_LOCK.synchronize { Preview.registry << subclass }
+        Preview.registry << subclass
       end
 
       # Named subclasses with at least one preview; a name defined again (a
       # reloaded file) keeps its latest class.
       def all
-        classes = REGISTRY_LOCK.synchronize { Preview.registry.dup }
-        classes.select { it.name && it.pdfs.any? }.reverse.uniq(&:name).sort_by(&:preview_name)
+        Preview.registry.to_a.select { it.name && it.pdfs.any? }.reverse.uniq(&:name).sort_by(&:preview_name)
       end
 
       # `load`, not `require`: edited previews show up without a restart.
@@ -48,7 +58,7 @@ module Stationery
 
       protected
 
-      def registry = (@registry ||= []) # rubocop:disable ThreadSafety/ClassInstanceVariable
+      def registry = Store.fetch(:stationery_previews) { Registry.new }
 
       private
 

data/lib/stationery/railtie.rb

@@ -32,6 +32,9 @@ module Stationery
       Railtie.add_previews(app.routes) if app.config.stationery.show_previews
     end
 
+    # Once every initializer has added its font paths: see Stationery.finalize!.
+    config.after_initialize { Stationery.finalize! }
+
     def self.add_font_paths(root, dirs)
       dirs.each do |dir|
         path = root.join(dir).to_s

data/lib/stationery/raster/png.rb

@@ -10,8 +10,8 @@ module Stationery
     # written unfiltered, which deflate squeezes well enough for pages that
     # are mostly flat colour, and much faster in Ruby than a filter.
     module PNG
-      SIGNATURE = "\x89PNG\r\n\x1A\n".b
-      NO_FILTER = "\x00".b
+      SIGNATURE = "\x89PNG\r\n\x1A\n".b.freeze
+      NO_FILTER = "\x00".b.freeze
 
       module_function
 

data/lib/stationery/raster/render.rb

@@ -17,9 +17,9 @@ module Stationery
       # class declares it.
       PDF_ONLY = %i[sign encrypt conformance attachments print tagged page_labels xmp factur_x incremental
                     missing_glyphs object_streams].freeze
-      GREY = "\x01-\xFE".b
-      DARK = "\x00-\x7F".b
-      LIGHT = "\x80-\xFF".b
+      GREY = "\x01-\xFE".b.freeze
+      DARK = "\x00-\x7F".b.freeze
+      LIGHT = "\x80-\xFF".b.freeze
 
       def self.refuse(options, output = "to_png")
         key = options.keys.first

data/lib/stationery/rich/renderer/inlines.rb

@@ -5,7 +5,7 @@ module Stationery
     class Renderer
       # Writes inlines into a Text::RunsBuilder, nesting one builder call per mark.
       class Inlines
-        STYLE_STEPS = {
+        STYLE_STEPS = Stationery.shareable(
           weight: ->(value) { [:b] if value == :bold },
           style: ->(value) { [:i] if value == :italic },
           underline: ->(value) { [:u] if value },
@@ -13,15 +13,15 @@ module Stationery
           color: ->(value) { [:color, value] if value },
           size: ->(value) { [:size, value] if value },
           font: ->(value) { [:font, value] if value }
-        }.freeze
+        )
 
         # A true mark switches the style on, a false one (from CSS) switches it off again.
-        MARK_STEPS = {
+        MARK_STEPS = Stationery.shareable(
           bold: { true => [[:b]], false => [[:with, { weight: :regular }]] },
           italic: { true => [[:i]], false => [[:with, { style: :normal }]] },
           underline: { true => [[:u]], false => [[:with, { underline: false }]] },
           strike: { true => [[:strikethrough]], false => [[:with, { strikethrough: false }]] }
-        }.freeze
+        )
 
         def initialize(runs, styles, links = Links.new(:all, nil))
           @runs = runs

data/lib/stationery/rich/styles.rb

@@ -7,7 +7,7 @@ module Stationery
     module Styles
       HEADING_SCALES = [2.0, 1.6, 1.3, 1.1, 1.0, 0.9].freeze
 
-      DEFAULTS = {
+      DEFAULTS = Stationery.shareable(
         **HEADING_SCALES.each_with_index.to_h do |scale, index|
           [:"h#{index + 1}", { scale:, weight: :bold, keep_with_next: true }]
         end,
@@ -22,7 +22,7 @@ module Stationery
         ol: {},
         li: {},
         img: { max_width: nil, float_margin: 8 }
-      }.freeze
+      )
 
       module_function
 

data/lib/stationery/shareable.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Stationery
+  # `value` deep-frozen, so a constant holding it can be read from any
+  # Ractor: Ractor.make_shareable, which also makes a capture-free Proc
+  # shareable, or a plain freeze on an engine without Ractor (JRuby,
+  # TruffleRuby), where there is nothing to share it with. For the gem's
+  # own constants.
+  def self.shareable(value) = defined?(::Ractor) ? ::Ractor.make_shareable(value) : value.freeze
+
+  # Settings an app gave at boot, frozen as far as they can be without
+  # touching what the app holds: a Hash, an Array or a Data is a frozen copy
+  # of its contents settled in turn, a String or a Time a frozen copy, and a
+  # block is made shareable when it uses nothing unshareable from around it.
+  # Anything else not shareable already (a shaper or an instrumenter that
+  # keeps state, a key, a block that closes over the app's state) is kept as
+  # it is, never frozen: the main Ractor uses it as before, and a Ractor
+  # cannot. Never raises. For Document.finalize!.
+  def self.settled(value)
+    return value if defined?(::Ractor) && ::Ractor.shareable?(value)
+
+    case value
+    when Hash then value.transform_values { settled(it) }.freeze
+    when Array then value.map { settled(it) }.freeze
+    when String, Time then value.frozen? ? value : value.dup.freeze
+    when Data then value.with(**value.to_h.transform_values { settled(it) })
+    when Proc then settled_block(value)
+    else value
+    end
+  end
+
+  # A capture-free block made shareable where it is, which leaves it as it
+  # was when it cannot be: Ractor.make_shareable checks what the block uses
+  # before it changes anything.
+  def self.settled_block(block)
+    defined?(::Ractor) ? ::Ractor.make_shareable(block) : block
+  rescue ::Ractor::Error
+    block
+  end
+  private_class_method :settled_block
+end

data/lib/stationery/skill.rb

@@ -15,8 +15,8 @@ module Stationery
   class Skill
     NAME = "stationery"
     GENERATOR = "stationery skill"
-    TEMPLATES = File.expand_path("skill", __dir__)
-    ROOT = File.expand_path("../..", __dir__)
+    TEMPLATES = File.expand_path("skill", __dir__).freeze
+    ROOT = File.expand_path("../..", __dir__).freeze
     DOCS = "https://stationery.zoolutions.llc"
 
     # The version a SKILL.md was written for, when stationery wrote it.

data/lib/stationery/store.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Where the gem's caches live: one value per key and per Ractor, shared by
+  # that Ractor's threads, built by the block the first time it is asked for.
+  #
+  #   Stationery::Store.fetch(:stationery_fonts) { LRU.new(16) }
+  #
+  # A cache in a constant or a class instance variable cannot be read from a
+  # non-main Ractor, so each Ractor keeps its own here and a cache's lock
+  # lives inside it (see LRU and Memo). On Ruby 3.4+ this is
+  # `Ractor.store_if_absent`, atomic and per Ractor. An engine without it
+  # (JRuby, TruffleRuby: no Ractor at all) has one Hash behind a Mutex,
+  # both made at load. conformance-kit's ConformanceKit::Store is the same
+  # pattern; the gem cannot depend on the kit when it runs.
+  module Store
+    # A Hash whose every read and write holds one Mutex: the store of an
+    # engine without Ractor.store_if_absent.
+    class Locked
+      def initialize
+        @lock = Mutex.new
+        @values = {}
+      end
+
+      def fetch(key)
+        @lock.synchronize { @values.fetch(key) { @values[key] = yield } }
+      end
+    end
+
+    def self.native? = defined?(::Ractor) ? ::Ractor.respond_to?(:store_if_absent) : false
+
+    if native?
+      def self.fetch(key, &) = ::Ractor.store_if_absent(key, &)
+    else
+      # Only where there is no Ractor to read it from: made once, at load.
+      @locked = Locked.new
+
+      # rubocop:disable-next ThreadSafety/ClassInstanceVariable -- written once at load; Locked holds its own Mutex
+      def self.fetch(key, &) = @locked.fetch(key, &)
+    end
+  end
+end

data/lib/stationery/svg/region.rb

@@ -19,7 +19,7 @@ module Stationery
         def trace(path) = Shapes.trace(path, element)
       end
 
-      EMPTY = new([], false, nil).freeze
+      EMPTY = Stationery.shareable(new([], false, nil))
     end
   end
 end

data/lib/stationery/testing/inspector.rb

@@ -14,7 +14,7 @@ module Stationery
     # `password:` opens an encrypted one. Needs the pdf-reader gem, loaded on
     # first use.
     class Inspector
-      UTF16_BOM = "\xFE\xFF".b
+      UTF16_BOM = "\xFE\xFF".b.freeze
       # id-aa-signatureTimeStampToken: a signature's RFC 3161 timestamp.
       TIMESTAMP_TOKEN = "1.2.840.113549.1.9.16.2.14"
       XMP_PROPERTY = %r{^\s*<((?!rdf:)[\w.-]+:[\w.-]+)>(.*?)</\1>$}

data/lib/stationery/testing/marked_text.rb

@@ -19,7 +19,7 @@ module Stationery
                  set_character_spacing set_word_spacing set_text_rise set_horizontal_text_scaling
                  set_text_rendering_mode].freeze
 
-      UTF16_BOM = "\xFE\xFF".b
+      UTF16_BOM = "\xFE\xFF".b.freeze
       # The width of a character in a sequence that moves the pen nowhere, in
       # parts of its size.
       NOMINAL = 0.5

data/lib/stationery/testing/page_reader.rb

@@ -15,7 +15,7 @@ module Stationery
                  set_text_matrix_and_text_line_matrix move_to_start_of_next_line set_text_leading
                  set_character_spacing set_word_spacing set_text_rise set_horizontal_text_scaling
                  set_text_rendering_mode].freeze
-      UTF16_BOM = "\xFE\xFF".b
+      UTF16_BOM = "\xFE\xFF".b.freeze
       SUBSET = /\A[A-Z]{6}\+/
       # A gap wider than this share of the size is a space between words;
       # one wider than the size itself starts a new run.

data/lib/stationery/text/markup.rb

@@ -15,13 +15,13 @@ module Stationery
     class Markup
       TAG = %r{<(/?)([a-zA-Z][a-zA-Z0-9]*)((?:\s+[a-zA-Z_:-]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>"']+))*)\s*/?>}
       ATTRIBUTE = /([a-zA-Z_:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"']+))/
-      STYLES = {
+      STYLES = Stationery.shareable(
         "b" => { weight: :bold }, "strong" => { weight: :bold },
         "i" => { style: :italic }, "em" => { style: :italic },
         "u" => { underline: true },
         "strikethrough" => { strikethrough: true }, "s" => { strikethrough: true }, "del" => { strikethrough: true },
         "sub" => { script: :sub }, "sup" => { script: :sup }
-      }.freeze
+      )
 
       def self.parse(source, style)
         new(source, style).runs

data/lib/stationery/verify/allowlist.rb

@@ -19,7 +19,7 @@ module Stationery
         { engine: "mupdf", pattern: /\Awarning: ICC support is not available\z/,
           why: "Debian's mutool (mupdf-tools, in the verify image) is built without colour management and says so " \
                "before it opens any file, even one that is not a PDF." }
-      ].freeze
+      ].map { Stationery.shareable(it) }.freeze
 
       def self.allows?(entries, engine, message)
         entries.any? { |entry| entry[:engine] == engine && entry[:pattern].match?(message) }

data/lib/stationery/verify/engines/pdfium.rb

@@ -8,7 +8,7 @@ module Stationery
       class Pdfium < Engine
         NAME = "pdfium"
         INSTALL = "pip install pypdfium2 (STATIONERY_PYTHON names the Python that has it)"
-        SCRIPT = File.expand_path("../scripts/pdfium.py", __dir__)
+        SCRIPT = File.expand_path("../scripts/pdfium.py", __dir__).freeze
         VERSION = "import pypdfium2.version as v; print(v.PYPDFIUM_INFO, v.PDFIUM_INFO)"
 
         # -P everywhere: Python loads no module from beside the script or from

data/lib/stationery/verify/engines/pdfjs.rb

@@ -10,7 +10,7 @@ module Stationery
       class Pdfjs < Engine
         NAME = "pdfjs"
         INSTALL = "npm i pdfjs-dist (STATIONERY_PDFJS names its directory)"
-        SCRIPT = File.expand_path("../scripts/pdfjs.mjs", __dir__)
+        SCRIPT = File.expand_path("../scripts/pdfjs.mjs", __dir__).freeze
         RESOLVE = "console.log(require('path').dirname(require.resolve('pdfjs-dist/package.json')))"
 
         def available? = !directory.nil?

data/lib/stationery/verify/engines/pdfkit.rb

@@ -8,7 +8,7 @@ module Stationery
       class Pdfkit < Engine
         NAME = "pdfkit"
         INSTALL = "macOS only: xcode-select --install"
-        SCRIPT = File.expand_path("../scripts/pdfkit.swift", __dir__)
+        SCRIPT = File.expand_path("../scripts/pdfkit.swift", __dir__).freeze
 
         def available? = RUBY_PLATFORM.include?("darwin") && !Command.which("swift").nil?
         def version = "macOS #{run("sw_vers", "-productVersion").stdout.strip}"

data/lib/stationery/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stationery
-  VERSION = "0.12.3"
+  VERSION = "0.13.0"
 end

data/lib/stationery.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "stationery/version"
+require_relative "stationery/shareable"
 require_relative "stationery/errors"
+require_relative "stationery/store"
+require_relative "stationery/lru"
+require_relative "stationery/memo"
 require_relative "stationery/instrumentation"
 require_relative "stationery/pdf/types"
 require_relative "stationery/pdf/serializer"
@@ -202,11 +206,41 @@ require_relative "stationery/document"
 
 # Pure-Ruby PDF documents built from Phlex-style components.
 module Stationery
-  @font_paths = []
+  # Appended to at boot, on the main Ractor (the Railtie, an app's own
+  # setup); finalize! freezes it.
+  @font_paths = [] # rubocop:disable ThreadSafety/MutableClassInstanceVariable
 
   class << self
     # Directories searched for font files; the Railtie appends the app's.
+    # Frozen by finalize!.
     attr_reader :font_paths
+
+    # Ends boot: what the gem holds for every render is frozen, and
+    # Ractor-shareable as far as the app's settings let it be. `font_paths`
+    # is frozen, as a frozen copy of each directory; the instrumenter in use
+    # is kept, so one loaded later is not picked up; and every document class
+    # loaded by then is finalized (Document.finalize!), with its subclasses.
+    # Nothing it cannot make shareable raises: it is kept as it is, for the
+    # main Ractor. Run it once everything that adds a font path or defines a
+    # document class at boot has; the Railtie runs it after the app has
+    # initialized. Answers Stationery; running it again finalizes only the
+    # classes loaded since.
+    def finalize!
+      # rubocop:disable-next ThreadSafety/ClassInstanceVariable -- written at boot on the main Ractor, before any render
+      @font_paths = @font_paths.map { |path| path.to_s.dup.freeze }.freeze
+      Instrumentation.finalize!
+      finalize_documents(Document)
+      self
+    end
+
+    private
+
+    def finalize_documents(parent)
+      parent.subclasses.each do |document|
+        document.finalize!
+        finalize_documents(document)
+      end
+    end
   end
   # Names of the font families shipped inside the gem.
   def self.bundled_fonts = Fonts::Bundled.names

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stationery
 version: !ruby/object:Gem::Version
-  version: 0.12.3
+  version: 0.13.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -224,6 +224,7 @@ files:
 - lib/stationery/layout/text.rb
 - lib/stationery/layout/wrap.rb
 - lib/stationery/list_markers.rb
+- lib/stationery/lru.rb
 - lib/stationery/markdown/block_parser.rb
 - lib/stationery/markdown/block_parser/containers.rb
 - lib/stationery/markdown/block_parser/tables.rb
@@ -232,6 +233,7 @@ files:
 - lib/stationery/markdown/inline_parser/emphasis.rb
 - lib/stationery/markdown/inline_parser/links.rb
 - lib/stationery/markdown/inline_parser/nodes.rb
+- lib/stationery/memo.rb
 - lib/stationery/minitest.rb
 - lib/stationery/monochrome.rb
 - lib/stationery/monochrome/bitmap.rb
@@ -301,6 +303,7 @@ files:
 - lib/stationery/rich/styles.rb
 - lib/stationery/rspec.rb
 - lib/stationery/shaper.rb
+- lib/stationery/shareable.rb
 - lib/stationery/skill.rb
 - lib/stationery/skill/SKILL.md.erb
 - lib/stationery/skill/recipes/flyer.md.erb
@@ -317,6 +320,7 @@ files:
 - lib/stationery/skill/reference/pages.md.erb
 - lib/stationery/skill/reference/printing.md.erb
 - lib/stationery/skill/reference/testing.md.erb
+- lib/stationery/store.rb
 - lib/stationery/structure.rb
 - lib/stationery/svg/arc.rb
 - lib/stationery/svg/bounds.rb