texd 0.1.0

data/lib/texd/attachment.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Texd
+  # AttachmentList will contain file references used in tex documents.
+  # This class is commonly interacted with in the `attach_file` view
+  # helper:
+  #
+  # @example Name mangling is active by default:
+  #   \input{<%= attach_file "/path/to/reference.tex" %>}
+  #   % might render as:
+  #   \input{att-1234.tex}
+  #
+  # @example Name mangling can be deactivated:
+  #   \input{<%= attach_file "/path/to/reference.tex", rename: false %>}
+  #   % will render as:
+  #   \input{reference.tex}
+  #
+  # @example Some situations require to drop the file extension:
+  #   \usepackage{<%= attach_file "helper.sty", rename: false, extension: false %>}
+  #   % will render as:
+  #   \usepackage{helper}
+  class AttachmentList
+    attr_reader :items
+    attr_reader :lookup_context
+
+    # @param [Texd::LookupContext] lookup_context
+    def initialize(lookup_context)
+      @items          = {}
+      @lookup_context = lookup_context
+    end
+
+    # Adds a file with the given `path` to the list. The file path must
+    # either be an absolute filename or be relative to app/tex/ of the
+    # host application. See `Texd::LookupContext` for details.
+    #
+    # The output file name will be mangled, unless `rename` specifies a
+    # name to use. Setting `rename` to false also disables renaming (the
+    # output will then use the file's basename unaltered).
+    #
+    # Note: Adding the same `path` twice with different arguments will
+    # have no effect: The returned value on the second attempt will be the
+    # same as on the first one.
+    #
+    # @param [String, Pathname] path partial path
+    # @param [Boolean, String] rename affects the output file name. If
+    #   `true`, a random file name is generated for the TeX template,
+    #   `false` will use the basename of path.
+    #   When a string is given, that string is used instead. Be careful
+    #   to avoid name collisions.
+    # @return [Attachment::File]
+    # @api private
+    def attach(path, rename = true) # rubocop:disable Style/OptionalBooleanParameter
+      add(Attachment::File, path, rename)
+    end
+
+    # Adds a file reference with the given path to the list. Similar to #attach,
+    # the file path must either be an absolute filename or be relative to
+    # app/tex/ of the host application.
+    #
+    # File name mangling applies as well, with the same rules as in #attach.
+    #
+    # File references allow to reduce the amount of data sent to the texd server
+    # instance, by initially only sending the file's checksums. If the server
+    # can identify that checksum from an internal store, it'll use the stored
+    # file. Otherwise we receive a list of unknown references, and can retry
+    # the render request with the missing content attached in full.
+    #
+    # References will be stored on the server (for some amount of time), so
+    # you should only attach static files, which change seldomly. Do not add
+    # dynamic content.
+    #
+    # @param [String, Pathname] path partial path
+    # @param [Boolean, String] rename affects the output file name. If
+    #   `true`, a random file name is generated for the TeX template,
+    #   `false` will use the basename of path.
+    #   When a string is given, that string is used instead. Be careful
+    #   to avoid name collisions.
+    # @return [Attachment::Reference]
+    # @api private
+    def reference(path, rename = false) # rubocop:disable Style/OptionalBooleanParameter
+      add(Attachment::Reference, path, rename)
+    end
+
+    # Adds main input file for the render request. The returned name for
+    # this file is either "input.tex", or (if that name already exist)
+    # some alternative. You should add the return value as input parameter
+    # to the client's render call.
+    #
+    # @param [String] contents of main input.
+    # @return [String] a generated name, usually "input.tex"
+    # @api private
+    def main_input(contents)
+      name = "input.tex"
+      i    = 0
+      name = format("doc%05d.tex", i += 1) while items.key?(name)
+      att  = Attachment::Dynamic.new(name, contents)
+
+      items[name] = att
+      items[name]
+    end
+
+    # Transforms this list to UploadIO objects suitable for Texd::Client#render.
+    #
+    # @param [Set|nil] unknown_reference_ids file references to be included fully.
+    # @api private
+    def to_upload_ios(unknown_reference_ids = nil)
+      items.values.each_with_object({}) { |att, ios|
+        ios[att.name] = if unknown_reference_ids && att.is_a?(Attachment::Reference)
+          att.to_upload_io(full: unknown_reference_ids.include?(att.checksum))
+        else
+          att.to_upload_io
+        end
+      }
+    end
+
+    private
+
+    def add(kind, path, rename)
+      att = kind.new(lookup_context.find(path), rename, items.size)
+
+      items[att.name] ||= att
+      items[att.name]
+    end
+  end
+
+  module Attachment
+    class RenameError < ::Texd::Error
+      def initialize(rename)
+        super "invalid renaming: expected true, false, or a string, got #{rename.class} (#{rename})"
+      end
+    end
+
+    Dynamic = Struct.new(:name, :contents) do
+      def to_upload_io(**)
+        UploadIO.new(StringIO.new(contents), nil, name).tap { |io|
+          io.instance_variable_set :@original_filename, name
+        }
+      end
+    end
+
+    class Base
+      # absolute path to attachment on local file system
+      attr_reader :absolute_path
+
+      # @param [Pathname] path see AttachmentList#attach
+      # @param [Boolean, String] rename see AttachmentList#attach
+      # @param [Integer] serial number of files currently in the parent
+      #   AttachmentList (used for renaming purposes)
+      # @api private
+      def initialize(path, rename, serial)
+        @absolute_path = path.expand_path
+
+        @name = case rename
+        when true   then format("att%04d%s", serial, path.extname)
+        when false  then path.basename.to_s
+        when String then rename
+        else raise RenameError, rename
+        end
+      end
+
+      # Returns the (renamed) output file name. When `with_extension` is
+      # `true`, the file extension is chopped.
+      #
+      # @param [Boolean] with_extension
+      # @return [String] output file name
+      def name(with_extension = true) # rubocop:disable Style/OptionalBooleanParameter
+        basename = ::File.basename(@name)
+        return basename if with_extension
+
+        dot = basename.rindex(".")
+        return basename if dot == 0 # file starts with "."
+
+        basename.slice(0, dot)
+      end
+    end
+
+    class File < Base
+      # @api private
+      def to_upload_io(**)
+        UploadIO.new(absolute_path.open("rb"), nil, name).tap { |io|
+          io.instance_variable_set :@original_filename, name
+        }
+      end
+    end
+
+    class Reference < Base
+      # Special Content-Type header to instruct texd server to interpret
+      # contents as reference identifier and re-use persisted file on server.
+      USE_REF = "application/x.texd; ref=use"
+
+      # Special Content-Type header to instruct texd server to store the
+      # content body for later reference.
+      STORE_REF = "application/x.texd; ref=store"
+
+      # @api private
+      def to_upload_io(full: false)
+        f  = full ? absolute_path.open("rb") : StringIO.new(checksum)
+        ct = full ? STORE_REF                : USE_REF
+
+        UploadIO.new(f, ct, name).tap { |io|
+          io.instance_variable_set :@original_filename, name
+        }
+      end
+
+      # @api private
+      def checksum
+        @checksum ||= begin
+          digest  = Digest::SHA256.file(absolute_path).digest
+          encoded = Base64.urlsafe_encode64(digest)
+          "sha256:#{encoded}"
+        end
+      end
+    end
+  end
+end

data/lib/texd/client.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "net/http/post/multipart"
+require "json"
+
+module Texd
+  class Client
+    # Generic error for execptions caused by the render endpoint.
+    # You will likely receive a subclass of this error, but you may
+    # rescue from this error, if you're not interested in the details.
+    class RenderError < Error
+      # additional details
+      attr_reader :details
+
+      def initialize(message, details: nil)
+        @details = details
+        super(message)
+      end
+    end
+
+    # @!parse
+    #   # Raised if the server is busy.
+    #   class QueueError < RenderError; end
+    QueueError = Class.new RenderError
+
+    # @!parse
+    #   # Raised when input file pocessing failed.
+    #   class InputError < RenderError; end
+    InputError = Class.new RenderError
+
+    # Raised if the TeX compilation process failed.
+    class CompilationError < RenderError
+      # TeX compiler logs. Only available if Texd.config.error_format
+      # is "full" or "condensed".
+      attr_reader :logs
+
+      def initialize(message, details: nil, logs: nil)
+        @logs = logs
+        super(message, details: details)
+      end
+    end
+
+    # Raised when the texd server encountered one or more unknown file
+    # references.
+    class ReferenceError < RenderError
+      # List of unknown file references
+      attr_reader :references
+
+      def initialize(message, references:)
+        @references = Set.new(references)
+        super(message)
+      end
+    end
+
+    ERRORS_BY_CATEGORY = {
+      "input"       => InputError,
+      "compilation" => CompilationError,
+      "queue"       => QueueError,
+      "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
+
+    def initialize(config)
+      @config = config
+    end
+
+    def status
+      http("/status") { |uri| Net::HTTP::Get.new(uri) }
+    end
+
+    def render(upload_ios, **params)
+      params = config.default_render_params.merge(params)
+
+      http("/render", params: params) { |uri|
+        Net::HTTP::Post::Multipart.new uri, upload_ios
+      }
+    end
+
+    private
+
+    def http(path, params: nil)
+      uri = build_request_uri(path, params)
+
+      Net::HTTP.start uri.host, uri.port, **request_options(uri) do |http|
+        req = yield(uri)
+        decode_response http.request(req)
+      end
+    end
+
+    def request_options(uri)
+      {
+        use_ssl:       uri.scheme == "https",
+        open_timeout:  config.open_timeout,
+        write_timeout: config.write_timeout,
+        read_timeout:  config.read_timeout,
+      }
+    end
+
+    def build_request_uri(path, params)
+      uri       = config.endpoint.dup
+      uri.path  = File.join(uri.path, path)
+      uri.query = URI.encode_www_form(params) if params
+      uri
+    end
+
+    def decode_response(res)
+      ct   = res["Content-Type"]
+      body = case ct.split(";").first
+      when "application/json"
+        JSON.parse(res.body)
+      when "application/pdf", "text/plain"
+        res.body
+      else
+        raise RenderError, "unexpected content type: #{ct}"
+      end
+
+      return body if res.is_a?(Net::HTTPOK)
+
+      raise resolve_error(res.code, ct, body)
+    end
+
+    def resolve_error(status, content_type, body)
+      if body.is_a?(Hash)
+        category = body.delete("category")
+        message  = body.delete("error")
+        err      = ERRORS_BY_CATEGORY.fetch(category, RenderError)
+
+        if category == "reference"
+          return err.new(message, references: body.delete("references"))
+        end
+
+        return err.new(message, details: body)
+      end
+
+      if content_type.start_with?("text/plain")
+        return CompilationError.new("compilation failed", logs: body)
+      end
+
+      RenderError.new("Server responded with status #{status} (#{content_type})", details: body)
+    end
+  end
+end

data/lib/texd/config.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "uri"
+require "set"
+
+module Texd
+  class Configuration
+    class InvalidConfig < Texd::Error
+      attr_reader :option, :expected
+
+      def initialize(msg, option:, got:, expected: nil)
+        @option   = option
+        @expected = expected
+
+        message  = [format("Invalid configuration option for %p, got %p", option, got)]
+        message << msg if msg
+        message << format("Valid options are: %p", expected) if expected
+
+        super message.join(" ")
+      end
+    end
+
+    # 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
+    }.freeze
+
+    # Supported endpoint protocols.
+    ENDPOINT_CLASSES = [URI::HTTP, URI::HTTPS].freeze
+
+    # Supported error formats.
+    ERROR_FORMATS = %w[json full condensed].freeze
+
+    # Supported TeX engines.
+    TEX_ENGINES = %w[xelatex lualatex pdflatex].freeze
+
+    # Endpoint is a URI pointing to the texd server instance.
+    #
+    # The default is `http://localhost:2201/` and can be overriden by the
+    # `TEXD_ENDPOINT` environment variable.
+    attr_reader :endpoint
+
+    # Timeout (in seconds) for the initial connect to the endpoint.
+    #
+    # The default is 60 (1 min) and can be overriden by the `TEXD_OPEN_TIMEOUT`
+    # environment variable.
+    attr_reader :open_timeout
+
+    # Timeout (in seconds) for reads from the endpoint. You want this value to
+    # be in the same ballbark as texd's `--compile-timoeut` option.
+    #
+    # The default is 180 (3 min) and can be overriden by the `TEXD_OPEN_TIMEOUT`
+    # environment variable.
+    attr_reader :read_timeout
+
+    # Timeout (in seconds) for writing the request to the endpoint. You want
+    # this value to be in the same ballpark as texd's `--queue-timeout` option.
+    #
+    # The default is 60 (1 min) and can be overriden by the `TEXD_WRITE_TIMEOUT`
+    # environment variable.
+    attr_reader :write_timeout
+
+    # The texd server usually reports errors in JSON format, however, when the
+    # compilation fails, the TeX compiler's output ist often most useful.
+    #
+    # Supported values are described in ERROR_FORMATS.
+    #
+    # The default is "full" and can be overriden by the `TEXD_WRITE_TIMEOUT`
+    # environment variable.
+    attr_reader :error_format
+
+    # This is the selected TeX engine. Supported values are described in
+    # TEX_ENGINES.
+    #
+    # The default is blank (meaning the server shall default to its `--tex-engine`
+    # option), and can be overriden by the `TEXD_ENGINE` environment variable.
+    attr_reader :tex_engine
+
+    # When texd runs in container mode, it may provide multiple Docker images to
+    # select from. This setting selects a specific container image.
+    #
+    # The default value is blank (meaning texd will select an image), and can be
+    # overriden byt the `TEXD_IMAGE` environment variable.
+    attr_accessor :tex_image
+
+    # List of additional helper modules to make available in the template views.
+    # Texd::Helpers is always included, and you may add additional ones.
+    #
+    # This can't be influenced by environment variables.
+    attr_accessor :helpers
+
+    # Set of paths to perform file lookups in. The set is searched in order,
+    # meaning files found in later entries won't be returned if entries with the
+    # same name exist in earlier entries.
+    #
+    # By default, this only contains `Rails.root.join("app/tex")`, however
+    # Rails engines might append additional entries.
+    #
+    # A Texd::LookupContext is constructed from this set.
+    attr_accessor :lookup_paths
+
+    def initialize(**options)
+      DEFAULT_CONFIGURATION.each do |key, default_value|
+        public_send "#{key}=", options.fetch(key, default_value.dup)
+      end
+    end
+
+    def to_h
+      DEFAULT_CONFIGURATION.keys.each_with_object({}) do |key, hash|
+        hash[key] = public_send(key)
+      end
+    end
+
+    # @api private
+    def default_render_params
+      {
+        errors: error_format,
+        engine: tex_engine,
+        image:  tex_image,
+      }.compact
+    end
+
+    def endpoint=(val)
+      uri = val.is_a?(URI::Generic) ? val : URI.parse(val)
+
+      unless ENDPOINT_CLASSES.any? { |klass| uri.is_a? klass }
+        raise InvalidConfig.new("Value must be a URL", :endpoint, got: val, expected: ENDPOINT_CLASSES)
+      end
+
+      @endpoint = uri
+    end
+
+    def open_timeout=(val)
+      set_timeout :open, val
+    end
+
+    def read_timeout=(val)
+      set_timeout :read, val
+    end
+
+    def write_timeout=(val)
+      set_timeout :write, val
+    end
+
+    def error_format=(val)
+      val ||= "json"
+      val   = val.to_s
+
+      unless ERROR_FORMATS.include?(val)
+        raise InvalidConfig.new(nil, got: val, expected: ERROR_FORMATS)
+      end
+
+      @error_format = val
+    end
+
+    def tex_engine=(val)
+      unless val.nil?
+        val = val.to_s
+        unless TEX_ENGINES.include?(val)
+          raise InvalidConfig.new(nil, got: val, expected: TEX_ENGINES)
+        end
+      end
+
+      @tex_engine = val
+    end
+
+    private
+
+    def set_timeout(name, val)
+      val = case val
+      when Numeric  then val
+      when String   then val.to_i
+      when NilClass then 0
+      else
+        msg = "expected Numeric, String or NilClass for #{name}_timout, got #{val}:#{val.class}"
+        raise TypeError, msg
+      end
+
+      instance_variable_set "@#{name}_timeout", val
+    end
+  end
+end

data/lib/texd/document.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Texd
+  # Document handles compiling of templates into TeX sources.
+  class Document
+    attr_reader :attachments
+
+    # Shorthand for `new.compile`.
+    def self.compile(*args)
+      new.compile(*args)
+    end
+
+    def initialize
+      context      = LookupContext.new(Texd.config.lookup_paths)
+      @attachments = AttachmentList.new(context)
+    end
+
+    # Compile converts templates into TeX sources and collects file
+    # references (created with `texd_attach` and `texd_reference` helpers).
+    #
+    # @param args are forwarded to ApplicationController#render (which in turn
+    #   forwards to ActionView::Renderer#render).
+    # @return [Compilation]
+    def compile(*args)
+      helper_mod = ::Texd.helpers(attachments)
+      tex_source = Class.new(ApplicationController) {
+        helper helper_mod
+      }.render(*args)
+
+      main = attachments.main_input(tex_source)
+      Compilation.new(main.name, attachments)
+    end
+
+    Compilation = Struct.new(:main_input_name, :attachments) do
+      def to_upload_ios(missing_refs: Set.new)
+        attachments.to_upload_ios(missing_refs)
+      end
+    end
+  end
+end

data/lib/texd/helpers.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Texd
+  module Helpers
+    ESCAPE_RE = /([{}_$&%#])|([\\^~|<>])/.freeze
+    ESC_MAP   = {
+      "\\" => "backslash",
+      "^"  => "asciicircum",
+      "~"  => "asciitilde",
+      "|"  => "bar",
+      "<"  => "less",
+      ">"  => "greater",
+    }.freeze
+
+    TYPOGRAPHIC_REPLACEMENTS = [
+      # nested quotes
+      [/(^|\W)"'\b/, '\1\\glqq{}\\glq{}'],
+      [/\b'"(\W|$)/, '\\grq{}\\grqq{}\1'],
+      # double quotes
+      [/(^|\W)"\b/, '\1\\glqq{}'],
+      [/\b"(\W|$)/, '\\grqq{}\1'],
+      # single quotes
+      [/(^|\W)'\b/, '\1\\glq{}'],
+      [/\b'(\W|$)/, '\\grq{}\1'],
+      # proper hyphenation
+      [/(\w)-(\w)/, '\1"=\2'],
+    ].freeze
+
+    # Escapes the given text, making it safe for use in TeX documents.
+    def escape(text, line_break = "\\\\\\", typographic: true)
+      text = +text
+      text.to_s.tap do |str|
+        str.gsub!(ESCAPE_RE) do |m|
+          if Regexp.last_match(1)
+            "\\#{m}"
+          else
+            "\\text#{ESC_MAP[m]}{}"
+          end
+        end
+
+        if typographic
+          TYPOGRAPHIC_REPLACEMENTS.each do |re, replacement|
+            str.gsub!(re, replacement)
+          end
+        end
+
+        str.gsub!(/\r?\n/, line_break)
+      end.freeze
+    end
+  end
+end