asciidoctor-kroki 1.0.1 → 2.0.0.rc.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f18e9ffde3538c375578dce0fee86bff48e8ec402214943afdfd078eda7f4f9
-  data.tar.gz: a3f46683cdc4200a94805ef5308b371c20df3c5514a810ceb78fff3846bbd0e4
+  metadata.gz: a83bcb9eccbf3e0def0e928c6e62c7a054c721b96fc3bf755520f60d9117e48d
+  data.tar.gz: 33698f6396dedc31df4d06a7d410e72fb53feaa2829c100d657b9898764935e8
 SHA512:
-  metadata.gz: 13db244902d8df19c0efa1b8703ac017d86ad8ba4012177e0fdd1ca558b665dcd74bfd9348a54a491733f60839f1a302281f56b5bd9a4f4904957ff031479975
-  data.tar.gz: 6bc5a8e87883a976af9dd7889fedc79f6630453d65f6420717a6c3062c1e999d41d372573ced78fa2311c945d89066633c79392bb26fc655244debf18217d7d9
+  metadata.gz: 4337469119534bd62fd38bb06bedb50958b62302b52868e0e94b747fb19e97d585fb59c2ad18a794a92f0fdd0624cdae00fdec95f5f740a0bc2f439c561a2db1
+  data.tar.gz: 39a922f2c39e331a7756f1034603c4a7e3036ead01b97c5e812c29111bb897ff7fee304e3b35a495f7903e23ca7d29940dcffc6018ea41336b39d419d7df46f9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    asciidoctor-kroki (1.0.1)
+    asciidoctor-kroki (2.0.0.rc.2)
       asciidoctor (~> 2.0)
 
 GEM

data/README.md

@@ -22,10 +22,11 @@ Register and use the extension:
 
 ```js
 import { convert, Extensions } from '@asciidoctor/core'
-import asciidoctorKroki from 'asciidoctor-kroki'
+import { register } from 'asciidoctor-kroki'
 
-asciidoctorKroki.register(Extensions)
-console.log(await convert('[graphviz]\n....\ndigraph G { Hello->World }\n....'))
+const registry = Extensions.create()
+register(registry)
+console.log(await convert('[graphviz]\n....\ndigraph G { Hello->World }\n....', { extension_registry: registry }))
 ```
 
 For installation instructions for Node.js, Browser, Ruby, and Antora, as well as the full configuration reference, see the [documentation](https://docs.asciidoctor.org/kroki-extension/latest).

data/lib/asciidoctor/extensions/asciidoctor_kroki/cache.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'json'
+
+module AsciidoctorExtensions
+  # Persistent, content-addressed cache for fetched diagrams, independent of the output
+  # directory. Ports src/cache.js so both language bindings behave the same way: the cache
+  # key is derived from the diagram request itself (server URL, type, format, encoded source,
+  # options), not from the output file name, so it also survives builds that wipe the output
+  # directory between runs (e.g. Antora) and correctly detects unchanged content for diagrams
+  # with a stable, user-defined name (see #90, #113).
+  module KrokiCache
+    VALID_CACHE_MODES = ['', 'true', 'false', 'refresh'].freeze
+
+    class << self
+      # Resolves the persistent cache directory.
+      # Uses the `kroki-cache-dir` attribute when set; otherwise defaults to the XDG cache
+      # directory (`$XDG_CACHE_HOME/kroki` or `~/.cache/kroki`).
+      def resolve_cache_dir(doc)
+        configured = doc.attr('kroki-cache-dir')
+        return configured if configured && !configured.empty?
+
+        xdg_cache_home = ENV['XDG_CACHE_HOME'] || File.join(Dir.home, '.cache')
+        File.join(xdg_cache_home, 'kroki')
+      end
+
+      # Resolves the `kroki-cache` attribute into a cache mode.
+      #
+      # Recognised values are: unset (defaults to enabled), `` (set with no value, e.g.
+      # `:kroki-cache:`) and `true` (both enabled), `false` (disabled), and `refresh` (enabled,
+      # but bypasses cached reads and re-fetches + updates the cache). Any other value is
+      # invalid: it is logged and treated as if unset.
+      #
+      # @return [Hash{Symbol => Boolean}] with keys :enabled and :refresh
+      def resolve_cache_mode(doc, logger)
+        raw = doc.attr('kroki-cache')
+        return { enabled: true, refresh: false } if raw.nil?
+
+        value = raw.to_s.strip.downcase
+        unless VALID_CACHE_MODES.include?(value)
+          logger.warn "Invalid value '#{raw}' for kroki-cache attribute. The value must be either: " \
+                      "'true', 'false' or 'refresh'. Proceeding using: 'true'."
+          return { enabled: true, refresh: false }
+        end
+        { enabled: value != 'false', refresh: value == 'refresh' }
+      end
+
+      # Computes the content-addressed cache key for a diagram.
+      #
+      # Deliberately host-dependent: the server URL is part of the key because two Kroki
+      # servers are not guaranteed to render the same source identically (they may run
+      # different versions of the underlying diagram libraries). Options are sorted so the
+      # key does not depend on their insertion order.
+      def content_key(kroki_diagram, server_url)
+        sorted_opts = kroki_diagram.opts.sort_by { |k, _| k.to_s }
+        material = [server_url, kroki_diagram.type, kroki_diagram.format, kroki_diagram.encode, sorted_opts.to_json].join('/')
+        Digest::SHA256.hexdigest(material)
+      end
+
+      # Whether a diagram is already present in the cache.
+      def exists_in_cache?(cache_dir, key, format)
+        File.exist?(cache_file_path(cache_dir, key, format))
+      end
+
+      # Reads a cached diagram.
+      def read_from_cache(cache_dir, key, format)
+        File.read(cache_file_path(cache_dir, key, format), mode: 'rb')
+      end
+
+      # Writes a diagram to the cache, creating the cache directory if needed.
+      def write_to_cache(cache_dir, key, format, contents)
+        FileUtils.mkdir_p(cache_dir)
+        File.write(cache_file_path(cache_dir, key, format), contents, mode: 'wb')
+      end
+
+      private
+
+      def cache_file_path(cache_dir, key, format)
+        File.join(cache_dir, "#{key}.#{format}")
+      end
+    end
+  end
+end

data/lib/asciidoctor/extensions/asciidoctor_kroki/extension.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 require 'cgi'
+require 'pathname'
 require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
+require_relative 'preprocess'
+require_relative 'cache'
 
 # Asciidoctor extensions
 #
@@ -79,7 +82,7 @@ module AsciidoctorExtensions
         logger.error message_with_context "Failed to read #{diagram_type} file: #{path}. #{e}.", source_location: parent.document.reader.cursor_at_mark
         return create_block(parent, 'paragraph', unresolved_block_macro_message(diagram_type, path), {})
       end
-      KrokiProcessor.process(self, parent, attrs, diagram_type, diagram_text, @logger)
+      KrokiProcessor.process(self, parent, attrs, diagram_type, diagram_text, @logger, resource_path: path)
     end
 
     protected
@@ -154,12 +157,14 @@ module AsciidoctorExtensions
 
     TEXT_FORMATS = %w[txt atxt utxt].freeze
     BUILTIN_ATTRIBUTES = %w[target width height format fallback link float align role caption title cloaked-context subs].freeze
+    PLANTUML_TYPES = %i[plantuml c4plantuml].freeze
 
     class << self
       # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
-      def process(processor, parent, attrs, diagram_type, diagram_text, logger)
+      def process(processor, parent, attrs, diagram_type, diagram_text, logger, resource_path: nil)
         doc = parent.document
         diagram_text = prepend_plantuml_config(diagram_text, diagram_type, doc, logger)
+        diagram_text = preprocess_plantuml_includes(diagram_text, diagram_type, doc, resource_path, logger)
         # If "subs" attribute is specified, substitute accordingly.
         # Be careful not to specify "specialcharacters" or your diagram code won't be valid anymore!
         if (subs = attrs['subs'])
@@ -190,7 +195,7 @@ module AsciidoctorExtensions
           block = processor.create_block(parent, 'literal', text_content, attrs)
         else
           attrs['alt'] = alt
-          attrs['target'] = create_image_src(doc, kroki_diagram, kroki_client, logger)
+          apply_image_src(attrs, create_image_src(doc, kroki_diagram, kroki_client, logger))
           block = processor.create_image_block(parent, attrs)
         end
         block.title = title if title
@@ -201,10 +206,13 @@ module AsciidoctorExtensions
 
       private
 
+      # Prepends the kroki-plantuml-include file content to the diagram text. Unlike the
+      # !include directives resolved by preprocess_plantuml_includes below, this path is jailed
+      # to the document's safe-mode boundaries via normalize_system_path, since the attribute
+      # value (unlike an !include target written by the diagram's author) may come from outside
+      # the diagram itself (e.g. a document-wide default set by a build script).
       def prepend_plantuml_config(diagram_text, diagram_type, doc, logger)
-        if diagram_type == :plantuml && doc.safe < ::Asciidoctor::SafeMode::SECURE && doc.attr?('kroki-plantuml-include')
-          # REMIND: this behaves different than the JS version
-          # Once we have a preprocessor for Ruby, the value should be added in the diagram source as "!include #{plantuml_include}"
+        if PLANTUML_TYPES.include?(diagram_type) && doc.safe < ::Asciidoctor::SafeMode::SECURE && doc.attr?('kroki-plantuml-include')
           plantuml_include_path = doc.normalize_system_path(doc.attr('kroki-plantuml-include'))
           if ::File.readable? plantuml_include_path
             config = File.read(plantuml_include_path)
@@ -217,6 +225,18 @@ module AsciidoctorExtensions
         diagram_text
       end
 
+      # Resolves !include/!include_once/!include_many/!includeurl/!includesub directives found in
+      # PlantUML/C4-PlantUML diagram text (including text prepended above), searching resource_path's
+      # own directory and then each directory in kroki-plantuml-include-paths, in order. Unlike
+      # kroki-plantuml-include above, this mirrors the JavaScript extension's preprocessor and is
+      # not jailed to the safe-mode boundary (see src/preprocess.js) — only gated by safe mode itself.
+      def preprocess_plantuml_includes(diagram_text, diagram_type, doc, resource_path, logger)
+        return diagram_text unless PLANTUML_TYPES.include?(diagram_type) && doc.safe < ::Asciidoctor::SafeMode::SECURE
+
+        include_paths = doc.attr('kroki-plantuml-include-paths')
+        PlantUmlPreprocessor.preprocess(diagram_text, resource_path, include_paths, logger)
+      end
+
       def get_alt(attrs)
         if (title = attrs['title'])
           title
@@ -265,11 +285,27 @@ module AsciidoctorExtensions
         format
       end
 
+      def apply_image_src(attrs, image_src)
+        attrs['target'] = image_src[:target]
+        attrs['imagesdir'] = image_src[:imagesdir] if image_src[:imagesdir]
+      end
+
       def create_image_src(doc, kroki_diagram, kroki_client, logger)
         if doc.attr('kroki-fetch-diagram') && doc.safe < ::Asciidoctor::SafeMode::SECURE
-          kroki_diagram.save(output_dir_path(doc), kroki_client, generated_files(doc), logger)
+          images_output_dir = output_dir_path(doc)
+          diagram_name = kroki_diagram.save(images_output_dir, kroki_client, generated_files(doc), logger,
+                                            cache_dir: KrokiCache.resolve_cache_dir(doc), cache_mode: KrokiCache.resolve_cache_mode(doc, logger))
+          # The converter resolves the image target against the document's `imagesdir`
+          # attribute, which only matches where we actually wrote the file when
+          # `imagesoutdir` is unset. Overriding `imagesdir` on this image node (rather
+          # than on the document) tells the converter exactly where to find this one
+          # file, without disturbing other images in the document (asciidoctor/asciidoctor#3660).
+          # As of this writing that core change is merged to `main` but not yet in a
+          # released gem (still absent from 2.0.26); until it ships, Asciidoctor's
+          # `image_uri` ignores the node-level attribute and this is a harmless no-op.
+          { target: diagram_name, imagesdir: relative_images_dir(doc, images_output_dir) }
         else
-          kroki_diagram.get_diagram_uri(server_url(doc))
+          { target: kroki_diagram.get_diagram_uri(server_url(doc)) }
         end
       end
 
@@ -294,15 +330,21 @@ module AsciidoctorExtensions
       end
 
       def output_dir_path(doc)
-        images_dir = doc.attr('imagesdir', '')
-        if (images_output_dir = doc.attr('imagesoutdir'))
-          images_output_dir
-        # the nested document logic will become obsolete once https://github.com/asciidoctor/asciidoctor/commit/7edc9da023522be67b17e2a085d72e056703a438 is released
-        elsif (out_dir = doc.attr('outdir') || (doc.nested? ? doc.parent_document : doc).options[:to_dir])
-          File.join(out_dir, images_dir)
-        else
-          File.join(doc.base_dir, images_dir)
-        end
+        images_output_dir = doc.attr('imagesoutdir')
+        return images_output_dir if images_output_dir
+
+        File.join(output_dir(doc), doc.attr('imagesdir', ''))
+      end
+
+      # the nested document logic will become obsolete once https://github.com/asciidoctor/asciidoctor/commit/7edc9da023522be67b17e2a085d72e056703a438 is released
+      def output_dir(doc)
+        doc.attr('outdir') || (doc.nested? ? doc.parent_document : doc).options[:to_dir] || doc.base_dir
+      end
+
+      def relative_images_dir(doc, images_output_dir)
+        from = Pathname.new(File.expand_path(output_dir(doc)))
+        to = Pathname.new(File.expand_path(images_output_dir))
+        to.relative_path_from(from).to_s
       end
     end
   end
@@ -333,7 +375,10 @@ module AsciidoctorExtensions
       ([Zlib::Deflate.deflate(@text, 9)].pack 'm0').tr '+/', '-_'
     end
 
-    def save(output_dir_path, kroki_client, generated_files = nil, logger = nil)
+    # @param cache_dir [String, nil] persistent cache directory (see KrokiCache.resolve_cache_dir); required when cache_mode[:enabled]
+    # @param cache_mode [Hash] {enabled:, refresh:} (see KrokiCache.resolve_cache_mode); disabled by default so callers that
+    #   don't pass it (e.g. specs exercising #save directly) keep the pre-cache behaviour
+    def save(output_dir_path, kroki_client, generated_files = nil, logger = nil, cache_dir: nil, cache_mode: { enabled: false, refresh: false })
       diagram_url = get_diagram_uri(kroki_client.server_url)
       # An explicit name is used verbatim so links stay stable across content changes;
       # otherwise the name is content-addressed so anonymous diagrams don't collide (see #451).
@@ -341,26 +386,43 @@ module AsciidoctorExtensions
       diagram_name = named ? "#{@target}.#{@format}" : "diag-#{Digest::SHA256.hexdigest diagram_url}.#{@format}"
       file_path = File.join(output_dir_path, diagram_name)
       if named
-        # A stable file may exist from a previous build with stale content, so always
-        # re-fetch and overwrite. Warn when the same name is reused for a different diagram.
+        # A stable file may exist from a previous build with stale content, so it cannot be
+        # trusted by name alone: go through fetch_diagram, which re-fetches only when the
+        # persistent cache doesn't already have this exact content (see #90). Warn when the
+        # same name is reused for a diagram with different content.
         warn_on_name_clash(generated_files, diagram_name, diagram_url, logger)
         generated_files[diagram_name] = diagram_url if generated_files
-        fetch_and_write(output_dir_path, file_path, kroki_client)
+        fetch_and_write(output_dir_path, file_path, kroki_client, cache_dir, cache_mode)
       elsif !File.exist?(file_path)
-        # Content-addressed name: an existing file necessarily has identical content.
-        fetch_and_write(output_dir_path, file_path, kroki_client)
+        # Content-addressed name: an existing output file necessarily has identical content.
+        fetch_and_write(output_dir_path, file_path, kroki_client, cache_dir, cache_mode)
       end
       diagram_name
     end
 
     private
 
-    def fetch_and_write(output_dir_path, file_path, kroki_client)
-      contents = kroki_client.get_image(self, image_encoding)
+    def fetch_and_write(output_dir_path, file_path, kroki_client, cache_dir, cache_mode)
+      contents = fetch_diagram(kroki_client, cache_dir, cache_mode)
       FileUtils.mkdir_p(output_dir_path)
       File.write(file_path, contents, mode: 'wb')
     end
 
+    # Fetches from Kroki, going through the persistent cache (see cache.rb) when enabled. The
+    # cache is keyed on the diagram's actual content, not on the output file name, so it also
+    # survives builds that wipe the output directory (e.g. Antora) and correctly detects
+    # unchanged content for named diagrams (see #90, #113).
+    def fetch_diagram(kroki_client, cache_dir, cache_mode)
+      return kroki_client.get_image(self, image_encoding) unless cache_mode[:enabled]
+
+      key = KrokiCache.content_key(self, kroki_client.server_url)
+      return KrokiCache.read_from_cache(cache_dir, key, @format) if !cache_mode[:refresh] && KrokiCache.exists_in_cache?(cache_dir, key, @format)
+
+      fetched = kroki_client.get_image(self, image_encoding)
+      KrokiCache.write_to_cache(cache_dir, key, @format, fetched)
+      fetched
+    end
+
     def warn_on_name_clash(generated_files, diagram_name, diagram_url, logger)
       return unless generated_files && logger
 

data/lib/asciidoctor/extensions/asciidoctor_kroki/preprocess.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'uri'
+
+module AsciidoctorExtensions
+  # Resolves PlantUML `!include` directives (and friends) in diagram text before it is sent to
+  # the Kroki server, mirroring the JavaScript/Node.js extension's preprocessor (src/preprocess.js)
+  # so both language bindings behave the same way. See http://plantuml.com/en/preprocessing.
+  #
+  # Unlike the JS extension (which also supports Antora resource IDs and a pluggable virtual
+  # filesystem), this Ruby port only needs to resolve plain local paths and http(s) URLs, since
+  # the Ruby gem is not used with Antora.
+  # rubocop:disable Metrics/ModuleLength
+  module PlantUmlPreprocessor
+    PLANTUML_BLOCK_RX = /@startuml\r?\n([\s\S]*?)\r?\n@enduml/.freeze
+    INCLUDE_LINE_RX = /^\s*!(include(?:_many|_once|url|sub)?)\s+(.*)/.freeze
+
+    class << self
+      # @param diagram_text [String] the raw diagram source
+      # @param resource_path [String, nil] absolute path (or URL) of the file the diagram text was
+      #   read from, used to resolve relative !include directives; nil for a diagram written
+      #   directly in the AsciiDoc source (resolved relative to the current working directory,
+      #   like plain !include paths without a match in kroki-plantuml-include-paths)
+      # @param include_paths [String, nil] the kroki-plantuml-include-paths attribute value
+      #   (a list of directories separated by File::PATH_SEPARATOR)
+      # @param logger [#info] logger used to report includes that were skipped, not raised
+      # @return [String] the diagram text with !include directives resolved
+      def preprocess(diagram_text, resource_path, include_paths, logger)
+        resource = resource_path ? parse_resource(resource_path) : { dir: '', path: nil }
+        paths = include_paths.to_s.empty? ? [] : include_paths.split(::File::PATH_SEPARATOR)
+        diagram_text = preprocess_includes(diagram_text, resource, [], [], paths, logger)
+        remove_tags(diagram_text)
+      end
+
+      private
+
+      def preprocess_includes(diagram_text, resource, include_once, include_stack, include_paths, logger)
+        inside_comment_block = false
+        # -1 keeps trailing empty segments (a diagram ending in \n must not lose it), matching
+        # JavaScript's String#split, which (unlike Ruby's default) never drops trailing empties.
+        lines = diagram_text.split("\n", -1).map do |line|
+          result = line
+          if !inside_comment_block && (match = INCLUDE_LINE_RX.match(line))
+            substituted = process_include_line(match, resource, include_once, include_stack, include_paths, logger)
+            result = substituted unless substituted.nil?
+          end
+          inside_comment_block = true if line.include?("/'")
+          inside_comment_block = false if inside_comment_block && line.include?("'/")
+          result
+        end
+        lines.join("\n")
+      end
+
+      def process_include_line(match, resource, include_once, include_stack, include_paths, logger)
+        include_directive = match[1].downcase
+        target = parse_target(match[2])
+        # Intentionally unlimited split (matches the JS split(!) semantics): a second '!' beyond
+        # the sub name is silently discarded, same as upstream.
+        url_sub = target[:url].split('!')
+        trailing_content = target[:comment]
+        url = url_sub[0].gsub('\\ ', ' ').sub(/\s+\z/, '')
+        sub = url_sub[1]
+
+        read_result = read_include(url, resource, include_paths, include_stack, logger)
+        return nil if read_result[:skip]
+
+        check_include_once(read_result[:file_path], include_once) if include_directive == 'include_once'
+
+        text = extract_text(read_result[:text], include_directive, sub)
+        include_stack.push(read_result[:file_path])
+        text = preprocess_includes(text, parse_resource(read_result[:file_path]), include_once, include_stack, include_paths, logger)
+        include_stack.pop
+
+        trailing_content.empty? ? text : "#{text} #{trailing_content}"
+      end
+
+      def extract_text(text, include_directive, sub)
+        return text_or_first_block(text) if sub.nil? || sub.empty?
+        return text_from_sub(text, sub) if include_directive == 'includesub'
+
+        index = /\A\d+\z/.match?(sub) ? sub.to_i : nil
+        index ? text_from_index(text, index) : text_from_id(text, sub)
+      end
+
+      # Splits the rest of an !include line into the target path/URL and any trailing PlantUML
+      # comment (# line comment or /' block comment), which must be preserved verbatim.
+      def parse_target(value)
+        (3...value.length).each do |i|
+          char = value[i]
+          return { url: value[0...(i - 1)].strip, comment: value[i..] } if char == '#' && value[i - 1] == ' ' && value[i - 2] != '\\'
+          return { url: value[0...(i - 1)].strip, comment: value[(i - 1)..] } if char == "'" && value[i - 1] == '/' && value[i - 2] != '\\'
+        end
+        { url: value, comment: '' }
+      end
+
+      def read_include(url, resource, include_paths, include_stack, logger)
+        if url.start_with?('<')
+          # A standard library include cannot be resolved locally but might be resolved by the Kroki server.
+          logger.info("Skipping preprocessing of PlantUML standard library include '#{url}'")
+          return { skip: true, text: '', file_path: url }
+        end
+        raise "Preprocessing of PlantUML include failed, because recursive reading already included referenced file '#{url}'" if include_stack.include?(url)
+
+        if remote_url?(url)
+          read_and_rescue(url, url, 'remote', logger)
+        else
+          file_path = resolve_include_file(url, resource, include_paths)
+          raise "Preprocessing of PlantUML include failed, because recursive reading already included referenced file '#{file_path}'" if include_stack.include?(file_path)
+
+          read_and_rescue(file_path, file_path, 'local', logger)
+        end
+      end
+
+      def read_and_rescue(path, file_path, kind, logger)
+        { skip: false, text: read_resource(path), file_path: file_path }
+      rescue StandardError => e
+        # Includes a file that cannot be found but might be resolved by the Kroki server (see #60).
+        logger.info("Skipping preprocessing of PlantUML include, because reading the referenced #{kind} file '#{file_path}' caused an error:\n#{e}")
+        { skip: true, text: '', file_path: file_path }
+      end
+
+      def resolve_include_file(include_file, resource, include_paths)
+        # When the including file was itself fetched from a remote URL, resolve a relative
+        # include against that URL so it can be fetched remotely as well, instead of being
+        # (incorrectly) looked up on the local file system.
+        return ::URI.join(resource[:path], include_file).to_s if resource[:path].is_a?(::String) && remote_url?(resource[:path])
+
+        ([resource[:dir]] + include_paths).each do |dir|
+          candidate = join_paths(dir, include_file)
+          return candidate if ::File.exist?(candidate)
+        end
+        include_file
+      end
+
+      def check_include_once(file_path, include_once)
+        if include_once.include?(file_path)
+          raise "Preprocessing of PlantUML include failed, because including multiple times referenced file '#{file_path}' with '!include_once' guard"
+        end
+
+        include_once.push(file_path)
+      end
+
+      def text_from_sub(text, sub)
+        regex = /!startsub\s+#{::Regexp.escape(sub)}(?:\r\n|\n)([\s\S]*?)(?:\r\n|\n)!endsub/
+        text.scan(regex).flatten.join("\n")
+      end
+
+      def text_from_id(text, id)
+        regex = /@startuml\(id=#{::Regexp.escape(id)}\)(?:\r\n|\n)([\s\S]*?)(?:\r\n|\n)@enduml/
+        text.scan(regex).flatten.join("\n")
+      end
+
+      def text_from_index(text, index)
+        blocks = text.scan(PLANTUML_BLOCK_RX).flatten
+        blocks[index] || ''
+      end
+
+      def text_or_first_block(text)
+        match = PLANTUML_BLOCK_RX.match(text)
+        match ? match[1] : text
+      end
+
+      # Removes all plantuml tags (@startuml/@enduml) from the diagram. It's possible to have more
+      # than one diagram in a single file in the cli version of plantuml. This does not work for
+      # the server, so recent plantuml versions remove the tags before processing the diagram. We
+      # don't want to rely on the server to handle this, so we remove the tags here before sending
+      # the diagram to the server.
+      #
+      # Some diagrams have special tags (i.e. @startmindmap for mindmap) - these are mandatory, so
+      # we can't do much about them.
+      def remove_tags(diagram_text)
+        return diagram_text if diagram_text.nil? || diagram_text.empty?
+
+        diagram_text.gsub(/^\s*@(?:startuml|enduml).*\n?/, '')
+      end
+
+      def remote_url?(str)
+        str.start_with?('http://', 'https://')
+      end
+
+      def read_resource(path)
+        if remote_url?(path)
+          require 'open-uri'
+          ::OpenURI.open_uri(path, &:read)
+        else
+          ::File.read(path, mode: 'rb:utf-8:utf-8')
+        end
+      end
+
+      def parse_resource(file_path)
+        if remote_url?(file_path)
+          { dir: nil, path: file_path }
+        else
+          { dir: ::File.dirname(file_path), path: file_path }
+        end
+      end
+
+      # Joins path segments the way Node's path.posix.join does: empty segments contribute
+      # nothing (so a blank resource dir doesn't force everything into an absolute path), and the
+      # result is lexically normalized (. and .. segments resolved) so that two different textual
+      # routes to the same file compare equal for cycle detection.
+      def join_paths(*parts)
+        segments = parts.compact.map(&:to_s).reject(&:empty?)
+        return '' if segments.empty?
+
+        ::Pathname.new(segments.join('/')).cleanpath.to_s
+      end
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/asciidoctor/extensions/asciidoctor_kroki/version.rb

@@ -2,6 +2,6 @@
 
 module Asciidoctor
   module AsciidoctorKroki
-    VERSION = '1.0.1'
+    VERSION = '2.0.0.rc.2'
   end
 end

data/lib/asciidoctor/extensions/asciidoctor_kroki.rb

@@ -2,6 +2,8 @@
 
 require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
 require_relative 'asciidoctor_kroki/version'
+require_relative 'asciidoctor_kroki/preprocess'
+require_relative 'asciidoctor_kroki/cache'
 require_relative 'asciidoctor_kroki/extension'
 
 Asciidoctor::Extensions.register do