texd 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33d8cf48e8c880611c853f282bc3db47cf5d627022887dd311ff7a895a3f24e9
-  data.tar.gz: c77ab1247262c025cd814d58b22f32f21f241a33fb5d95b15d1d805409546534
+  metadata.gz: 8f90c7123f60872130f0a2c36a6a6fa44154d1e3956c140f45e07e6815761363
+  data.tar.gz: a1c855d5a76517dae7eb2c5a2a9cc9be621236fa59018e62fbeeaa9b31ee0d49
 SHA512:
-  metadata.gz: 398a048ca70ecdb2a65ec3466ea900ebd918f7aacc5d4335ea1099cacf9342729a5e232eaed8af9bed261d4ca1e6d6ceb1e19476acea5ccc5a310b1520157afc
-  data.tar.gz: 7dd01397f2fdc0975dc0e31d8dcc2fb8de21017af585615333ad34a62ffcbce1793e994f6f6ac25eefa70c79779b8edfa1f5fd3d831b581ce826613b477b05c1
+  metadata.gz: ecc5d22800aea0f4b77e76c0c052106cb80bb47c3c3a478696c712957fbc178ac74c7014d3927ff09bd45c4472a167fc8ebd7bcbd9ff154f12c90f2724df319d
+  data.tar.gz: 88dad14c7c7f95fbb53bb12bd9777de8033d8b8aceafe896efabcf8f0c33463ece25b90ef43e2e3108c617586007171c498a969fe7184763d73812cf35ed0cf4

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.2)
+    texd (0.3.0)
       multipart-post (~> 2.0)
       rails (>= 6.0, < 8)
 

data/Makefile

@@ -50,5 +50,5 @@ texd-docker:
 		-p 127.0.0.1:2201:2201 \
 		-v $$(pwd)/tmp/jobs:/texd \
 		-v $$(pwd)/tmp/refs:/refs \
-		--user=$(id -u):$(id -g) \
+		--user=$$(id -u):$$(id -g) \
 			digineode/texd --reference-store dir:///refs

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.2)
+    texd (0.3.0)
       multipart-post (~> 2.0)
       rails (>= 6.0, < 8)
 

data/gemfiles/rails-6.1.lock

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

data/gemfiles/rails-7.0.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    texd (0.2.2)
+    texd (0.3.0)
       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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Texd
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: texd
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 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.2/CHANGELOG.md
+  changelog_uri: https://github.com/digineo/texd-ruby/blob/v0.3.0/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths: