texd 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c54956eeb977294ed946d8f961d16c15e41eff3eca556d31787174c07852de97
-  data.tar.gz: cd603c3d2e9af5b04c43a8c0f9e542fddd18b815a5a01c3d8483f3729b8dd9f1
+  metadata.gz: 6ac1013a4aa1ebd3b6889f40a3de4b8e48b6b55ea5413f1c997141c3660d8c81
+  data.tar.gz: 5fd52ec7b93abdd53c12276977b13e8c00ca8d16af39659be19128a3e9684860
 SHA512:
-  metadata.gz: 979a9503f9e4c38817d0c54b42c0ae288592819a65d0db1bd9ccf0dcaad81005d27842f35b49fc9b7869bfbb8563817e5e447413a865499d93993b95e0749081
-  data.tar.gz: a9d55ce2394c5bf940360ef4f11c7524c50149a0989da9a4c62ee186ecf6fddfcdba695a753ae9f20db20d55720179acecb4e9f5d6f08cc4dab4ec1f8850a81d
+  metadata.gz: 6522bec685edb067867df07b39b9de12d554b9907c2886e6f72fd53377a9dc5dc87cdc6370f4af4067970aa65b4f4a62415f7eb46aec65dadd1c9f3d65badfae
+  data.tar.gz: 29283c3b8a723f156ae5ce67f79e0cedd2c186b940a831eb7a7fe8a972f50ab5b1bb29017137edbfa87668429f190f5a82bc883b97299c6b8f783c5a678fb944

data/.rubocop.yml

@@ -288,7 +288,9 @@ Style/RedundantAssignment:
   Enabled: true
 
 Style/RedundantFetchBlock:
-  Enabled: true
+  Enabled: false
+  Exclude:
+    - spec/lib/texd/cache_spec.rb # not called on Hash
 
 Style/RedundantFileExtensionInRequire:
   Enabled: true

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    texd (0.2.1)
+    texd (0.3.1)
       multipart-post (~> 2.0)
       rails (>= 6.0, < 8)
 

data/Makefile

@@ -45,10 +45,11 @@ docs:
 .PHONY: texd-docker
 texd-docker:
 	mkdir -p tmp/jobs tmp/refs
+	rm -vf tmp/jobs/* tmp/refs/*
 	docker run --rm \
 		--name texd-dev \
 		-p 127.0.0.1:2201:2201 \
 		-v $$(pwd)/tmp/jobs:/texd \
 		-v $$(pwd)/tmp/refs:/refs \
-		--user=$(id -u):$(id -g) \
-			digineode/texd --reference-store dir:///refs
+		-u $$(id -u):$$(id -g) \
+			digineode/texd --reference-store dir:///refs --keep-jobs always

data/README.md

@@ -2,6 +2,10 @@
 
 texd is a Ruby client for the [texd web service](https://github.com/digineo/texd).
 
+It leverages ActionView's template rendering mechanism to compile `.tex`
+templates to PDF documents. The primary use case is to render documents
+in background jobs.
+
 ## Installation
 
 You need to meet the following requirements for this gem to work:
@@ -34,11 +38,15 @@ end
 
 ```rb
 Texd.configure do |config|
-  config.endpoint     = ENV.fetch("TEXD_ENDPOINT", "http://localhost:2201/")
-  config.error_format = ENV.fetch("TEXD_ERRORS", "full")
-  config.tex_engine   = ENV["TEXD_ENGINE"]
-  config.tex_image    = ENV["TEXD_IMAGE"]
-  config.helpers      = []
+  config.endpoint      = ENV.fetch("TEXD_ENDPOINT", "http://localhost:2201/")
+  config.open_timeout  = ENV.fetch("TEXD_OPEN_TIMEOUT", 60)
+  config.read_timeout  = ENV.fetch("TEXD_READ_TIMEOUT", 180)
+  config.write_timeout = ENV.fetch("TEXD_WRITE_TIMEOUT", 60)
+  config.error_format  = ENV.fetch("TEXD_ERRORS", "full")
+  config.tex_engine    = ENV["TEXD_ENGINE"]
+  config.tex_image     = ENV["TEXD_IMAGE"]
+  config.helpers       = []
+  config.lookup_paths  = [] # Rails.root.join("app/tex") is always inserted as first entry
 end
 ```
 
@@ -56,8 +64,115 @@ about other installation methods.
 
 ## Usage
 
-> TODO. See https://github.com/amagical-net/rails-latex#label-Synopsis
-> in the meantime.
+First, create a few files:
+
+<details><summary><code>app/views/layouts/application.tex.erb</code></summary>
+
+This is the default layout. Here, you should define a `\documentclass`
+and use `yield`. In this example, we're using ERB (Erubi) to include
+dynamic content into a `.tex` file.
+
+```erb
+\documentclass{article}
+\usepackage{graphicx}
+<%= content_for :preamble %>
+
+\begin{document}
+<%= yield %>
+\end{document}
+```
+
+</details>
+<details><summary><code>app/views/document/doc.tex.erb</code></summary>
+
+In `document/doc.tex`, we're specifying some stuff for the preamble,
+render a partial, and add content for the document:
+
+```erb
+<% content_for :preamble do %>
+\usepackage{blindtext}
+
+\title{Demo document}
+\date{\today}
+\author{<%= user.full_name %>}
+<% end %>
+
+<%= render partial: "document/title_page" %>
+
+\Blinddocument
+```
+
+OK, that wasn't true. We're leveraging the `blindtext` package to add
+content for us :)
+
+The `user` variable is passed as local method to `Texd.render` (see below).
+
+</details>
+<details><summary><code>app/views/document/_title_page.tex.erb</code></summary>
+
+This partial embeds an image and creates the title page.
+
+```erb
+\begin{center}
+  \includegraphics[width=0.5\linewidth]{<%= texd_attach "logo.png" %>}
+\end{center}
+
+\titlepage
+```
+
+With `texd_attach`, we're referencing a file *outside* ActionView's lookup
+paths, but in Texd's lookup paths (`RAILS_ROOT/app/tex` by default).
+
+You can use this directory to store and deploy static assets.
+
+Please be aware, that attachments will be renamed (`att00123.png`)
+in the POST body, and `att00123.png` will be returned from `texd_attach`.
+You can skip the renaming, if you want/need to:
+
+```erb
+% attaches RAILS_ROOT/app/tex/logo.png, and inserts "logo.png":
+<%= texd_attach "logo.png", rename: false %>
+
+% attaches RAILS_ROOT/app/tex/logo.png, and inserts "assets/logo.png":
+<%= texd_attach "logo.png", rename: "assets/logo.png" %>
+
+% attaches RAILS_ROOT/app/tex/common.tex, and inserts "att00042" (or similar):
+<%= texd_attach "common.tex", without_extension: true %>
+```
+
+</details>
+<details><summary><code>app/tex/logo.png</code></summary>
+
+*(Imagine your logo here.)*
+
+</details>
+
+With those files in place, you can create a PDF document:
+
+```rb
+begin
+  blob = Texd.render(template: "documents/doc", locals: {
+    user: User.find(1)
+  })
+  Rails.root.join("tmp/doc.pdf").open("wb") { |f|
+    f.write blob
+  }
+rescue Texd::Client::QueueError => err
+  # texd server is busy, please retry in a moment
+rescue Texd::Client::InputError => err
+  # file input processing failed, maybe some file names were invalid
+rescue Texd::Client::CompilationError => err
+  # compilation failed
+  if err.logs
+    # TeX compiler logs, only available if Texd.config.error_format
+    # is "full" or "condensed"
+  end
+end
+```
+
+All errors inherit from `Texd::Client::RenderError` and should have
+a `details` attribute (a Hash) containing the actual error returned
+from the server.
 
 ## Development
 

data/gemfiles/rails-6.0.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    texd (0.2.1)
+    texd (0.3.1)
       multipart-post (~> 2.0)
       rails (>= 6.0, < 8)
 

data/gemfiles/rails-6.1.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    texd (0.2.1)
+    texd (0.3.1)
       multipart-post (~> 2.0)
       rails (>= 6.0, < 8)
 

data/gemfiles/rails-7.0.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    texd (0.2.1)
+    texd (0.3.1)
       multipart-post (~> 2.0)
       rails (>= 6.0, < 8)
 

data/lib/texd/attachment.rb

@@ -202,9 +202,19 @@ module Texd
         }
       end
 
+      def self.cache
+        @cache ||= Cache.new(Texd.config.ref_cache_size)
+      end
+
       # @api private
       def checksum
-        @checksum ||= begin
+        @checksum ||= create_checksum
+      end
+
+      # @api private
+      def create_checksum
+        key = [::File.stat(absolute_path).mtime, absolute_path]
+        self.class.cache.fetch(key) do
           digest  = Digest::SHA256.file(absolute_path).digest
           encoded = Base64.urlsafe_encode64(digest)
           "sha256:#{encoded}"

data/lib/texd/cache.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Texd
+  # Cache is a simple LRU cache with a double linked list.
+  # If the cache is full the last element from the list will be removed.
+  class Cache
+    class LinkedList
+      attr_reader :head
+
+      def add(node)
+        if @head
+          node.next       = @head
+          node.prev       = @head.prev
+          @head.prev.next = node
+          @head.prev      = node
+        else
+          node.next = node
+          node.prev = node
+        end
+
+        @head = node
+      end
+
+      def remove(node)
+        if node.next == node
+          # remove last element, should never happen
+          @head = nil
+        else
+          node.prev.next = node.next
+          node.next.prev = node.prev
+          @head          = node.next if node == @head
+        end
+      end
+    end
+
+    class Node
+      attr_reader :key
+      attr_accessor :value, :prev, :next
+
+      def initialize(key)
+        @key = key
+      end
+    end
+
+    attr_reader :list, :count, :capacity
+    delegate :keys, to: :@hash
+
+    def initialize(capacity)
+      @list     = LinkedList.new
+      @hash     = {}
+      @mtx      = Mutex.new
+      @count    = 0
+      @capacity = capacity
+    end
+
+    def fetch(key)
+      read(key) || write(key, yield)
+    end
+
+    def read(key)
+      @mtx.synchronize do
+        node = @hash[key]
+        return unless node
+
+        list.remove(node)
+        list.add(node)
+        node.value
+      end
+    end
+
+    def write(key, value)
+      @mtx.synchronize do
+        node = @hash[key]
+
+        if node
+          list.remove(node)
+        else
+          node = add_node(key)
+        end
+
+        list.add(node)
+        node.value = value
+      end
+    end
+
+    private
+
+    def add_node(key)
+      node = Node.new(key)
+
+      if count >= capacity
+        last = list.head.prev
+        @hash.delete(last.key)
+        list.remove(last)
+      else
+        @count += 1
+      end
+
+      @hash[key] = node
+      node
+    end
+  end
+end

data/lib/texd/client.rb

@@ -60,24 +60,6 @@ module Texd
       "reference"   => ReferenceError,
     }.freeze
 
-    class ResponseError < Error
-      attr_reader :body, :content_type
-
-      def initialize(code, content_type, body)
-        @body         = body
-        @content_type = content_type
-
-        if json?
-          super format("%s error: %s", body.delete("category"), body.delete("error"))
-        elsif log?
-          tex_errors = body.lines.select { |l| l.start_with?("!") }.map(&:strip)
-          super "Compilation failed:\n\t#{tex_errors.join('\n\t')}"
-        else
-          super "Server responded with status #{code} (#{content_type})"
-        end
-      end
-    end
-
     USER_AGENT = "texd-ruby/#{VERSION} Ruby/#{RUBY_VERSION}"
 
     attr_reader :config

data/lib/texd/config.rb

@@ -22,15 +22,16 @@ module Texd
 
     # This is the default configuration. It is applied in the constructor.
     DEFAULT_CONFIGURATION = {
-      endpoint:      ENV.fetch("TEXD_ENDPOINT", "http://localhost:2201/"),
-      open_timeout:  ENV.fetch("TEXD_OPEN_TIMEOUT", 60),
-      read_timeout:  ENV.fetch("TEXD_READ_TIMEOUT", 180),
-      write_timeout: ENV.fetch("TEXD_WRITE_TIMEOUT", 60),
-      error_format:  ENV.fetch("TEXD_ERRORS", "full"),
-      tex_engine:    ENV["TEXD_ENGINE"],
-      tex_image:     ENV["TEXD_IMAGE"],
-      helpers:       Set.new,
-      lookup_paths:  [], # Rails.root.join("app/tex") is inserted in railtie.rb
+      endpoint:       ENV.fetch("TEXD_ENDPOINT", "http://localhost:2201/"),
+      open_timeout:   ENV.fetch("TEXD_OPEN_TIMEOUT", 60),
+      read_timeout:   ENV.fetch("TEXD_READ_TIMEOUT", 180),
+      write_timeout:  ENV.fetch("TEXD_WRITE_TIMEOUT", 60),
+      error_format:   ENV.fetch("TEXD_ERRORS", "full"),
+      tex_engine:     ENV["TEXD_ENGINE"],
+      tex_image:      ENV["TEXD_IMAGE"],
+      helpers:        Set.new,
+      lookup_paths:   [], # Rails.root.join("app/tex") is inserted in railtie.rb
+      ref_cache_size: 128,
     }.freeze
 
     # Supported endpoint protocols.
@@ -107,6 +108,13 @@ module Texd
     # A Texd::LookupContext is constructed from this set.
     attr_accessor :lookup_paths
 
+    # Cache size for file hashes computed by Texd::Attachment::Reference.
+    # Cannot be changed after the first document (using the `texd_reference`
+    # helper) was renderered.
+    #
+    # By default, the cache keeps hashes of the last 128 reference files.
+    attr_accessor :ref_cache_size
+
     def initialize(**options)
       DEFAULT_CONFIGURATION.each do |key, default_value|
         public_send "#{key}=", options.fetch(key, default_value.dup)

data/lib/texd/document.rb

@@ -6,8 +6,8 @@ module Texd
     attr_reader :attachments
 
     # Shorthand for `new.compile`.
-    def self.compile(*args)
-      new.compile(*args)
+    def self.compile(**kwargs)
+      new.compile(**kwargs)
     end
 
     def initialize
@@ -22,12 +22,15 @@ module Texd
     #   context.
     # @param [Hash, nil] locals will be made available as getter methods in
     #   the template.
+    # @param [String, Boolean] layout to be used. String value name template
+    #   files in `app/views/layouts`, `true` (default) uses the application
+    #   layout, and `false` renders without a layout.
     # @return [Compilation]
-    def compile(template:, locals: {})
+    def compile(template:, locals: {}, layout: true)
       helper_mod = ::Texd.helpers(attachments, locals)
       tex_source = Class.new(ApplicationController) {
         helper helper_mod
-      }.render(template: template, format: :tex)
+      }.render(template: template, format: :tex, layout: layout)
 
       main = attachments.main_input(tex_source)
       Compilation.new(main.name, attachments)

data/lib/texd/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Texd
-  VERSION = "0.2.1"
+  VERSION = "0.3.1"
 end

data/lib/texd.rb

@@ -12,6 +12,7 @@ require "rails"
 require_relative "texd/version"
 require_relative "texd/config"
 require_relative "texd/helpers"
+require_relative "texd/cache"
 require_relative "texd/client"
 require_relative "texd/attachment"
 require_relative "texd/document"
@@ -118,12 +119,15 @@ module Texd
   #   context.
   # @param [Hash, nil] locals will be made available as getter methods in
   #   the template.
+  # @param [String, Boolean] layout to be used. String value name template
+  #   files in `app/views/layouts`, `true` (default) uses the application
+  #   layout, and `false` renders without a layout.
   # @raise [Texd::Client::ResponseError] on input and queue errors. Also on
   #   compilation errors, if Texd.config.error_format is set to JSON.
   # @raise [Texd::Error] on other Texd related errors.
   # @return [String] the PDF object
-  def render(template:, locals: {})
-    doc = Document.compile(template: template, locals: locals)
+  def render(template:, locals: {}, layout: true)
+    doc = Document.compile(template: template, locals: locals, layout: layout)
 
     client.render doc.to_upload_ios,
       input: doc.main_input_name

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: texd
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Dominik Menke
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-03-22 00:00:00.000000000 Z
+date: 2022-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multipart-post
@@ -125,6 +125,7 @@ files:
 - gemfiles/rails-7.0.lock
 - lib/texd.rb
 - lib/texd/attachment.rb
+- lib/texd/cache.rb
 - lib/texd/client.rb
 - lib/texd/config.rb
 - lib/texd/document.rb
@@ -140,7 +141,7 @@ metadata:
   rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/digineo/texd-ruby
   source_code_uri: https://github.com/digineo/texd-ruby
-  changelog_uri: https://github.com/digineo/texd-ruby/blob/v0.2.1/CHANGELOG.md
+  changelog_uri: https://github.com/digineo/texd-ruby/blob/v0.3.1/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths: