asciidoctor-kroki 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e516cef89499dde5cea46152f3926f6b91c8f81c9e8ff57884dac15d1877fd1c
-  data.tar.gz: 919d391cf9ca8ad118ead138a8338434b7ffa6d6e15e6678a65a084aadbedd15
+  metadata.gz: f7ac5f1586d5aa5a1cf3f3031b0bcc1839e40681913f30722703011e133b6a72
+  data.tar.gz: f10b7edc9d3e1092c35b07028b25255c6c2ae0921795d161dc542bdecc0b814f
 SHA512:
-  metadata.gz: f96a43e66d73647ff2593e74ef695526fa52c6a9cf453c22d34d11bcc035bf8e5bb4256d43eab35f5e8290b32f5f02c0df064a975b7c3164efd83e8d96c320f3
-  data.tar.gz: 1536eb019a5b9fe3bd939ee64b6bd26252dd5096185f919c15536b6405f436baee91ca852a5519c2414b9ceee2215fad1228b28d8995a1da85ac583e7d5b0c86
+  metadata.gz: 613ae500380df383cc2b05720795de55933d5813ebb10f70f9252454727fac61f05d7f9c581641c28be8ed1e9fd42b6dcb9bb86283de455f92e4c41e0e00a78e
+  data.tar.gz: 25e547670dea5f121373ddc402b3740d33a6c1c31a006f3c2dd66dd5a753f4daa9d61aa7b6919543d7ec5c1b641b590a59c95b8de1b9419c6ffba2be7747a938

data/.gitignore

@@ -1 +1,2 @@
 pkg/
+.asciidoctor/kroki

data/.rubocop.yml

@@ -8,7 +8,10 @@ Metrics/MethodLength:
   Max: 50
 
 Metrics/CyclomaticComplexity:
-  Max : 10
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
 
 Metrics/AbcSize:
-  Max: 25
+  Max: 30

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    asciidoctor-kroki (0.1.2)
+    asciidoctor-kroki (0.2.0)
       asciidoctor (~> 2.0)
       asciidoctor-pdf (= 1.5.3)
 

data/asciidoctor-kroki.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = 'asciidoctor-kroki'
-  s.version = '0.1.2'
+  s.version = '0.2.0'
   s.summary = 'Asciidoctor extension to convert diagrams to images using Kroki'
   s.description = 'An extension for Asciidoctor to convert diagrams to images using https://kroki.io'
 

data/lib/asciidoctor/extensions/asciidoctor_kroki.rb

@@ -4,8 +4,7 @@ require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
 require_relative 'asciidoctor_kroki/extension'
 
 Asciidoctor::Extensions.register do
-  names = %w[plantuml ditaa graphviz blockdiag seqdiag actdiag nwdiag packetdiag rackdiag c4plantuml erd mermaid nomnoml svgbob umlet vega vegalite wavedrom]
-  names.each do |name|
+  ::AsciidoctorExtensions::Kroki::SUPPORTED_DIAGRAM_NAMES.each do |name|
     block_macro ::AsciidoctorExtensions::KrokiBlockMacroProcessor, name
     block ::AsciidoctorExtensions::KrokiBlockProcessor, name
   end

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

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
-require 'stringio'
-require 'zlib'
 
 # Asciidoctor extensions
 #
@@ -29,9 +27,11 @@ module AsciidoctorExtensions
   class KrokiBlockMacroProcessor < Asciidoctor::Extensions::BlockMacroProcessor
     use_dsl
 
+    name_positional_attributes 'format'
+
     def process(parent, target, attrs)
       diagram_type = @name
-      target = parent.apply_subs(target, ['attributes'])
+      target = parent.apply_subs(target, [:attributes])
       diagram_text = read(target)
       KrokiProcessor.process(self, parent, attrs, diagram_type, diagram_text)
     end
@@ -46,9 +46,38 @@ module AsciidoctorExtensions
     end
   end
 
+  # Kroki API
+  #
+  module Kroki
+    SUPPORTED_DIAGRAM_NAMES = %w[
+      plantuml
+      ditaa
+      graphviz
+      blockdiag
+      seqdiag
+      actdiag
+      nwdiag
+      packetdiag
+      rackdiag
+      c4plantuml
+      erd
+      mermaid
+      nomnoml
+      svgbob
+      umlet
+      vega
+      vegalite
+      wavedrom
+      bytefield
+      bpmn
+    ].freeze
+  end
+
   # Internal processor
   #
   class KrokiProcessor
+    TEXT_FORMATS = %w[txt atxt utxt].freeze
+
     class << self
       def process(processor, parent, attrs, diagram_type, diagram_text)
         doc = parent.document
@@ -64,11 +93,18 @@ module AsciidoctorExtensions
         role = attrs['role']
         format = get_format(doc, attrs, diagram_type)
         attrs['role'] = get_role(format, role)
-        attrs['alt'] = get_alt(attrs)
-        attrs['target'] = create_image_src(doc, diagram_type, format, diagram_text)
         attrs['format'] = format
-        block = processor.create_image_block(parent, attrs)
-        block.title = title
+        kroki_diagram = KrokiDiagram.new(diagram_type, format, diagram_text)
+        kroki_client = KrokiClient.new(server_url(doc), http_method(doc), KrokiHttpClient)
+        if TEXT_FORMATS.include?(format)
+          text_content = kroki_client.text_content(kroki_diagram)
+          block = processor.create_block(parent, 'literal', text_content, attrs)
+        else
+          attrs['alt'] = get_alt(attrs)
+          attrs['target'] = create_image_src(doc, kroki_diagram, kroki_client)
+          block = processor.create_image_block(parent, attrs)
+        end
+        block.title = title if title
         block.assign_caption(caption, 'figure')
         block
       end
@@ -119,13 +155,168 @@ module AsciidoctorExtensions
         format
       end
 
-      def create_image_src(doc, type, format, text)
-        data = Base64.urlsafe_encode64(Zlib::Deflate.deflate(text, 9))
-        "#{server_url(doc)}/#{type}/#{format}/#{data}"
+      def create_image_src(doc, kroki_diagram, kroki_client)
+        if doc.attr('kroki-fetch-diagram')
+          kroki_diagram.save(output_dir_path(doc), kroki_client)
+        else
+          kroki_diagram.get_diagram_uri(server_url(doc))
+        end
       end
 
       def server_url(doc)
-        doc.attr('kroki-server-url') || 'https://kroki.io'
+        doc.attr('kroki-server-url', 'https://kroki.io')
+      end
+
+      def http_method(doc)
+        doc.attr('kroki-http-method', 'adaptive').downcase
+      end
+
+      def output_dir_path(doc)
+        images_output_dir = doc.attr('imagesoutdir')
+        out_dir = doc.attr('outdir')
+        to_dir = doc.attr('to_dir')
+        base_dir = doc.base_dir
+        images_dir = doc.attr('imagesdir', '')
+        if images_output_dir
+          images_output_dir
+        elsif out_dir
+          File.join(out_dir, images_dir)
+        elsif to_dir
+          File.join(to_dir, images_dir)
+        else
+          File.join(base_dir, images_dir)
+        end
+      end
+    end
+  end
+
+  # Kroki diagram
+  #
+  class KrokiDiagram
+    require 'fileutils'
+    require 'zlib'
+    require 'digest'
+
+    attr_reader :type
+    attr_reader :text
+    attr_reader :format
+
+    def initialize(type, format, text)
+      @text = text
+      @type = type
+      @format = format
+    end
+
+    def get_diagram_uri(server_url)
+      _join_uri_segments(server_url, @type, @format, encode)
+    end
+
+    def encode
+      Base64.urlsafe_encode64(Zlib::Deflate.deflate(@text, 9))
+    end
+
+    def save(output_dir_path, kroki_client)
+      diagram_url = get_diagram_uri(kroki_client.server_url)
+      diagram_name = "diag-#{Digest::SHA256.hexdigest diagram_url}.#{@format}"
+      file_path = File.join(output_dir_path, diagram_name)
+      encoding = if @format == 'txt' || @format == 'atxt' || @format == 'utxt'
+                   'utf8'
+                 elsif @format == 'svg'
+                   'binary'
+                 else
+                   'binary'
+                 end
+      # file is either (already) on the file system or we should read it from Kroki
+      contents = File.exist?(file_path) ? File.open(file_path, &:read) : kroki_client.get_image(self, encoding)
+      FileUtils.mkdir_p(output_dir_path)
+      if encoding == 'binary'
+        File.binwrite(file_path, contents)
+      else
+        File.write(file_path, contents)
+      end
+      diagram_name
+    end
+
+    private
+
+    def _join_uri_segments(base, *uris)
+      segments = []
+      # remove trailing slashes
+      segments.push(base.gsub(%r{[/]+$}, ''))
+      segments.concat(uris.map do |uri|
+        # remove leading and trailing slashes
+        uri.to_s
+          .gsub(%r{^[/]+}, '')
+          .gsub(%r{[/]+$}, '')
+      end)
+      segments.join('/')
+    end
+  end
+
+  # Kroki client
+  #
+  class KrokiClient
+    attr_reader :server_url
+    attr_reader :method
+
+    SUPPORTED_HTTP_METHODS = %w[get post adaptive].freeze
+
+    def initialize(server_url, http_method, http_client)
+      @server_url = server_url
+      @max_uri_length = 4096
+      @http_client = http_client
+      method = (http_method || 'adaptive').downcase
+      if SUPPORTED_HTTP_METHODS.include?(method)
+        @method = method
+      else
+        puts "Invalid value '#{method}' for kroki-http-method attribute. The value must be either: 'get', 'post' or 'adaptive'. Proceeding using: 'adaptive'."
+        @method = 'adaptive'
+      end
+    end
+
+    def text_content(kroki_diagram)
+      get_image(kroki_diagram, 'utf-8')
+    end
+
+    def get_image(kroki_diagram, encoding)
+      type = kroki_diagram.type
+      format = kroki_diagram.format
+      text = kroki_diagram.text
+      if @method == 'adaptive' || @method == 'get'
+        uri = kroki_diagram.get_diagram_uri(server_url)
+        if uri.length > @max_uri_length
+          # The request URI is longer than 4096.
+          if @method == 'get'
+            # The request might be rejected by the server with a 414 Request-URI Too Large.
+            # Consider using the attribute kroki-http-method with the value 'adaptive'.
+            @http_client.get(uri, encoding)
+          else
+            @http_client.post("#{@server_url}/#{type}/#{format}", text, encoding)
+          end
+        else
+          @http_client.get(uri, encoding)
+        end
+      else
+        @http_client.post("#{@server_url}/#{type}/#{format}", text, encoding)
+      end
+    end
+  end
+
+  # Kroki HTTP client
+  #
+  class KrokiHttpClient
+    require 'net/http'
+    require 'uri'
+    require 'json'
+
+    class << self
+      def get(uri, _)
+        ::OpenURI.open_uri(uri, 'r', &:read)
+      end
+
+      def post(uri, data, _)
+        res = ::Net::HTTP.request_post(uri, data)
+        res.body
       end
     end
   end

data/spec/asciidoctor_kroki_client_spec.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'rspec_helper'
+require 'asciidoctor'
+require_relative '../lib/asciidoctor/extensions/asciidoctor_kroki'
+
+describe ::AsciidoctorExtensions::KrokiClient do
+  it 'should use adaptive method when http method is invalid' do
+    kroki_http_client = ::AsciidoctorExtensions::KrokiHttpClient
+    kroki_client = ::AsciidoctorExtensions::KrokiClient.new('http://localhost:8000', 'patch', kroki_http_client)
+    expect(kroki_client.method).to eq('adaptive')
+  end
+  it 'should use post method when http method is post' do
+    kroki_http_client = ::AsciidoctorExtensions::KrokiHttpClient
+    kroki_client = ::AsciidoctorExtensions::KrokiClient.new('http://localhost:8000', 'POST', kroki_http_client)
+    expect(kroki_client.method).to eq('post')
+  end
+  it 'should use get method when http method is get' do
+    kroki_http_client = ::AsciidoctorExtensions::KrokiHttpClient
+    kroki_client = ::AsciidoctorExtensions::KrokiClient.new('http://localhost:8000', 'get', kroki_http_client)
+    expect(kroki_client.method).to eq('get')
+  end
+end

data/spec/asciidoctor_kroki_diagram_spec.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'rspec_helper'
+require 'asciidoctor'
+require_relative '../lib/asciidoctor/extensions/asciidoctor_kroki'
+
+describe ::AsciidoctorExtensions::KrokiDiagram do
+  it 'should compute a diagram URI' do
+    kroki_diagram = ::AsciidoctorExtensions::KrokiDiagram.new('vegalite', 'png', '{}')
+    diagram_uri = kroki_diagram.get_diagram_uri('http://localhost:8000')
+    expect(diagram_uri).to eq('http://localhost:8000/vegalite/png/eNqrrgUAAXUA-Q==')
+  end
+  it 'should compute a diagram URI with a trailing slashes' do
+    kroki_diagram = ::AsciidoctorExtensions::KrokiDiagram.new('vegalite', 'png', '{}')
+    diagram_uri = kroki_diagram.get_diagram_uri('https://my.domain.org/kroki/')
+    expect(diagram_uri).to eq('https://my.domain.org/kroki/vegalite/png/eNqrrgUAAXUA-Q==')
+  end
+  it 'should compute a diagram URI with trailing slashes' do
+    kroki_diagram = ::AsciidoctorExtensions::KrokiDiagram.new('vegalite', 'png', '{}')
+    diagram_uri = kroki_diagram.get_diagram_uri('https://my-server/kroki//')
+    expect(diagram_uri).to eq('https://my-server/kroki/vegalite/png/eNqrrgUAAXUA-Q==')
+  end
+  it 'should encode a diagram text definition' do
+    kroki_diagram = ::AsciidoctorExtensions::KrokiDiagram.new('plantuml', 'txt', ' alice -> bob: hello')
+    diagram_definition_encoded = kroki_diagram.encode
+    expect(diagram_definition_encoded).to eq('eNpTSMzJTE5V0LVTSMpPslLISM3JyQcAQAwGaw==')
+  end
+  it 'should fetch a diagram from Kroki and save it to disk' do
+    kroki_diagram = ::AsciidoctorExtensions::KrokiDiagram.new('plantuml', 'txt', ' alice -> bob: hello')
+    kroki_http_client = ::AsciidoctorExtensions::KrokiHttpClient
+    kroki_client = ::AsciidoctorExtensions::KrokiClient.new('https://kroki.io', 'get', kroki_http_client)
+    output_dir_path = "#{__dir__}/../.asciidoctor/kroki"
+    diagram_name = kroki_diagram.save(output_dir_path, kroki_client)
+    diagram_path = File.join(output_dir_path, diagram_name)
+    expect(File.exist?(diagram_path)).to be_truthy, "expected diagram to be saved at #{diagram_path}"
+    content = <<-TXT.chomp
+     ,-----.          ,---.
+     |alice|          |bob|
+     `--+--'          `-+-'
+        |    hello      |
+        |-------------->|
+     ,--+--.          ,-+-.
+     |alice|          |bob|
+     `-----'          `---'
+    TXT
+    expect(File.read(diagram_path).split("\n").map(&:rstrip).join("\n")).to eq(content)
+  end
+  it 'should fetch a diagram from Kroki with the same definition only once' do
+    kroki_diagram = ::AsciidoctorExtensions::KrokiDiagram.new('plantuml', 'png', ' guillaume -> dan: hello')
+    kroki_http_client = ::AsciidoctorExtensions::KrokiHttpClient
+    kroki_client = ::AsciidoctorExtensions::KrokiClient.new('https://kroki.io', 'get', kroki_http_client)
+    output_dir_path = "#{__dir__}/../.asciidoctor/kroki"
+    # make sure that we are doing only one GET request
+    expect(kroki_http_client).to receive(:get).once
+    diagram_name = kroki_diagram.save(output_dir_path, kroki_client)
+    diagram_path = File.join(output_dir_path, diagram_name)
+    expect(File.exist?(diagram_path)).to be_truthy, "expected diagram to be saved at #{diagram_path}"
+    # calling again... should read the file from disk (and not do a GET request)
+    kroki_diagram.save(output_dir_path, kroki_client)
+  end
+end

data/spec/asciidoctor_kroki_spec.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'rspec_helper'
 require 'asciidoctor'
 require_relative '../lib/asciidoctor/extensions/asciidoctor_kroki'
 
@@ -47,5 +48,47 @@ describe ::AsciidoctorExtensions::KrokiBlockProcessor do
 </div>
 </div>)
     end
+    it 'should create SVG diagram in imagesdir if kroki-fetch-diagram is set' do
+      input = <<~'ADOC'
+        :imagesdir: .asciidoctor/kroki
+
+        plantuml::spec/fixtures/alice.puml[svg,role=sequence]
+      ADOC
+      output = Asciidoctor.convert(input, attributes: { 'kroki-fetch-diagram' => '' }, standalone: false)
+      (expect output).to eql %(<div class="imageblock sequence kroki-format-svg kroki">
+<div class="content">
+<img src=".asciidoctor/kroki/diag-f6acdc206506b6ca7badd3fe722f252af992871426e580c8361ff4d47c2c7d9b.svg" alt="Diagram">
+</div>
+</div>)
+    end
+    it 'should create PNG diagram in imagesdir if kroki-fetch-diagram is set' do
+      input = <<~'ADOC'
+        :imagesdir: .asciidoctor/kroki
+
+        plantuml::spec/fixtures/alice.puml[png,role=sequence]
+      ADOC
+      output = Asciidoctor.convert(input, attributes: { 'kroki-fetch-diagram' => '' }, standalone: false)
+      (expect output).to eql %(<div class="imageblock sequence kroki-format-png kroki">
+<div class="content">
+<img src=".asciidoctor/kroki/diag-d4f314b2d4e75cc08aa4f8c2c944f7bf78321895d8ec5f665b42476d4e67e610.png" alt="Diagram">
+</div>
+</div>)
+    end
+  end
+end
+
+describe ::AsciidoctorExtensions::Kroki do
+  it 'should return the list of supported diagrams' do
+    diagram_names = ::AsciidoctorExtensions::Kroki::SUPPORTED_DIAGRAM_NAMES
+    expect(diagram_names).to include('vegalite', 'plantuml', 'bytefield', 'bpmn')
+  end
+  it 'should register the extension for the list of supported diagrams' do
+    doc = Asciidoctor::Document.new
+    registry = Asciidoctor::Extensions::Registry.new
+    registry.activate doc
+    ::AsciidoctorExtensions::Kroki::SUPPORTED_DIAGRAM_NAMES.each do |name|
+      expect(registry.find_block_extension(name)).to_not be_nil, "expected block extension named '#{name}' to be registered"
+      expect(registry.find_block_macro_extension(name)).to_not be_nil, "expected block macro extension named '#{name}' to be registered "
+    end
   end
 end

data/spec/fixtures/alice.puml

@@ -0,0 +1 @@
+alice -> bob: hello

data/spec/rspec_helper.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+RSpec.configure do |config|
+  config.before(:suite) do
+    FileUtils.rm(Dir.glob("#{__dir__}/../.asciidoctor/kroki/diag-*"))
+  end
+  config.after(:suite) do
+    FileUtils.rm(Dir.glob("#{__dir__}/../.asciidoctor/kroki/diag-*")) unless ENV['DEBUG']
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asciidoctor-kroki
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Guillaume Grossetie
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-06 00:00:00.000000000 Z
+date: 2020-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -87,6 +87,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".asciidoctor/kroki/.gitkeep"
 - ".gitignore"
 - ".rubocop.yml"
 - ".ruby-version"
@@ -98,9 +99,13 @@ files:
 - lib/asciidoctor/extensions/asciidoctor_kroki.rb
 - lib/asciidoctor/extensions/asciidoctor_kroki/extension.rb
 - spec/.rubocop.yml
+- spec/asciidoctor_kroki_client_spec.rb
+- spec/asciidoctor_kroki_diagram_spec.rb
 - spec/asciidoctor_kroki_spec.rb
+- spec/fixtures/alice.puml
 - spec/fixtures/config.puml
 - spec/require_spec.rb
+- spec/rspec_helper.rb
 - tasks/bundler.rake
 - tasks/lint.rake
 - tasks/rspec.rake
@@ -131,9 +136,13 @@ specification_version: 4
 summary: Asciidoctor extension to convert diagrams to images using Kroki
 test_files:
 - spec/.rubocop.yml
+- spec/asciidoctor_kroki_client_spec.rb
+- spec/asciidoctor_kroki_diagram_spec.rb
 - spec/asciidoctor_kroki_spec.rb
+- spec/fixtures/alice.puml
 - spec/fixtures/config.puml
 - spec/require_spec.rb
+- spec/rspec_helper.rb
 - tasks/bundler.rake
 - tasks/lint.rake
 - tasks/rspec.rake