jekyll-kroki 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20faf867e0d7257dc109beb7013daffedbed2d90642e3b483d1be42a62220008
-  data.tar.gz: b248eeb60615d9343256b79b1524abe5253c5b02c2f1fa01741f3f2d914cef62
+  metadata.gz: d4c40ec016cd09c83ced71e8ead7559ab2fee1224432efc5bdefa366e363275a
+  data.tar.gz: 4341c9a5fa9891a0397ed167b7c56cc453e77ff8d00aef210819f982205431a5
 SHA512:
-  metadata.gz: 1aa3042410e6a16d5bc1e5519a3f7e1043611d22d404ed7856c943eba4a29dd36d5bab5f0a2a732c9cce77231927855bf464211d7a1ddfe58c54b4e3ed02a448
-  data.tar.gz: e2b86eed2875b0d846955222023102cbd215bbeebe68247debff8f56af2cbe328c28d60c974e9b321927178e09361758172553dcc863404068eaabb574a822a3
+  metadata.gz: 19733f768a5f025ece0eb647a1f3e5f9ef553c1b27aa0b5b0d716d4b329c303af2f77971c5d64d63db2d5be344b834e7f9abc7e6993202bb900206ed49894c6f
+  data.tar.gz: 2df9e238f430dee8787a9fbb96d8ba7b48bf18918c144b7630f9e80baebdff7b07d263956a123a6b9e8d268c05793532634e62b997f8067574badefbc5d0e227

data/.rubocop.yml

@@ -11,3 +11,5 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+Metrics/MethodLength:
+  Max: 12

data/README.md

@@ -29,12 +29,33 @@ Kroki --> Jekyll: Rendered diagram in SVG format
 
 When Jekyll builds your site, the `jekyll-kroki` plugin will encode the diagram, send it to the Kroki server for rendering, then replace the diagram description in the generated HTML with the rendered diagram in SVG format:
 
-![sample-diagram](https://github.com/felixvanoost/jekyll-kroki/assets/10233016/e526864f-c364-49a0-9cca-929a59343af0)
+![sample-diagram](https://github.com/felixvanoost/jekyll-kroki/assets/10233016/244d2ec4-b09b-4a5f-8164-3851574c3dd2)
 
 The site remains truly static as the SVG is directly embedded in the HTML files that Jekyll serves. Jekyll only depends on the Kroki server (which can also be run locally) during the build stage, and all of the client-side processing that is normally used to render diagrams into images is eliminated.
 
 `jekyll-kroki` uses the same Markdown fenced code syntax as the [GitLab Kroki integration](https://docs.gitlab.com/ee/administration/integration/kroki.html), allowing diagram descriptions in Markdown files to be displayed seamlessly in both the GitLab UI and on GitLab Pages sites generated using Jekyll.
 
+### Configuration
+
+You can specify the URL of the Kroki instance to use in the Jekyll `_config.yml` file:
+
+```yaml
+jekyll-kroki:
+  kroki_url: "https://my-kroki.server"
+```
+
+This is useful if you want to run a Kroki instance locally or your organisation maintains its own private Kroki server. `jekyll-kroki` will use the public Kroki instance https://kroki.io by default if a URL is not specified.
+
+### Security
+
+Embedding diagrams as SVGs directly within HTML files can be dangerous. You should only use a Kroki instance that you trust (or run your own!). For additional security, you can configure a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) using custom Webrick headers in the Jekyll `_config.yml` file:
+
+```yaml
+webrick:
+  headers:
+    Content-Security-Policy: "Add a policy here"
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

data/jekyll-kroki.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors = ["Felix van Oost"]
 
   spec.summary = "A Jekyll plugin to convert diagram descriptions into images using Kroki"
-  spec.description = "Replaces diagram descriptions written in any Kroki-supported language in HTML files with their
-                      visual representation in SVG format"
+  spec.description = "Replaces diagram descriptions written in any Kroki-supported language in HTML files generated by
+                      Jekyll with their visual representation in SVG format."
   spec.homepage = "https://github.com/felixvanoost/jekyll-kroki"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 2.6.0"
@@ -28,6 +28,8 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_runtime_dependency "faraday", ["~> 2.7"]
+  spec.add_runtime_dependency "faraday-retry", ["~> 2.2"]
   spec.add_runtime_dependency "jekyll", ["~> 4"]
   spec.add_runtime_dependency "nokogiri", ["~> 1.15"]
 

data/lib/jekyll/kroki/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   class Kroki
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/jekyll/kroki.rb

@@ -3,68 +3,94 @@
 require_relative "kroki/version"
 
 require "base64"
+require "faraday"
+require "faraday/retry"
 require "jekyll"
-require "json"
-require "net/http"
 require "nokogiri"
 require "zlib"
 
 module Jekyll
-  # Jekyll plugin for the Kroki diagram engine
+  # Converts diagram descriptions into images using Kroki
   class Kroki
-    KROKI_INSTANCE_URL = "https://kroki.io"
+    KROKI_DEFAULT_URL = "https://kroki.io"
+    HTTP_MAX_RETRIES = 3
 
     class << self
-      # Renders all diagram descriptions written in a Kroki-supported language in an HTML document.
+      # Renders all diagram descriptions in any Kroki-supported language and embeds them throughout a Jekyll site.
       #
-      # @param [Jekyll::Page or Jekyll::Document] The document to render diagrams in
-      def render(doc)
-        puts "Rendering diagrams using Kroki"
+      # @param [Jekyll::Site] The site to embed diagrams in
+      def embed_site(site)
+        # Get the URL of the Kroki instance
+        kroki_url = kroki_url(site.config)
+        puts "[jekyll-kroki] Rendering diagrams using Kroki instance at '#{kroki_url}'"
 
-        # Parse the HTML document
-        parsed_doc = Nokogiri::HTML.parse(doc.output)
+        # Set up a Faraday connection
+        connection = setup_connection(kroki_url)
 
+        # Parse the page, render and embed the diagrams, then convert it back into HTML
+        site.pages.each do |page|
+          next unless embeddable?(page)
+
+          parsed_page = Nokogiri::HTML(page.output)
+          embed_page(connection, parsed_page)
+          page.output = parsed_page.to_html
+        end
+      end
+
+      # Renders all diagram descriptions in any Kroki-supported language and embeds them in an HTML document.
+      #
+      # @param [Faraday::Connection] The Faraday connection to use
+      # @param [Nokogiri::HTML4::Document] The parsed HTML document
+      def embed_page(connection, parsed_doc)
         # Iterate through every diagram description in each of the supported languages
-        get_supported_languages(KROKI_INSTANCE_URL).each do |language|
+        get_supported_languages(connection).each do |language|
           parsed_doc.css("code[class~='language-#{language}']").each do |diagram_desc|
-            # Get the rendered diagram using Kroki
-            rendered_diagram = render_diagram(KROKI_INSTANCE_URL, diagram_desc, language)
-
-            # Replace the diagram description with the SVG representation
-            diagram_desc.replace(rendered_diagram)
+            # Replace the diagram description with the SVG representation rendered by Kroki
+            diagram_desc.replace(render_diagram(connection, diagram_desc, language))
           end
         end
-
-        # Generate the modified HTML document
-        doc.output = parsed_doc.to_html
       end
 
       # Renders a diagram description using Kroki.
       #
-      # @param [String] The URL of the Kroki instance
+      # @param [Faraday::Connection] The Faraday connection to use
       # @param [String] The diagram description
       # @param [String] The language of the diagram description
       # @return [String] The rendered diagram in SVG format
-      def render_diagram(kroki_url, diagram_desc, language)
-        # Encode the diagram and construct the URI
-        uri = URI("#{kroki_url}/#{language}/svg/#{encode_diagram(diagram_desc.text)}")
-
+      def render_diagram(connection, diagram_desc, language)
         begin
-          response = Net::HTTP.get_response(uri)
-        rescue StandardError => e
-          raise e.message
-        else
-          response.body if response.is_a?(Net::HTTPSuccess)
+          response = connection.get("#{language}/svg/#{encode_diagram(diagram_desc.text)}")
+        rescue Faraday::Error => e
+          raise e.response[:body]
+        end
+        expected_content_type = "image/svg+xml"
+        returned_content_type = response.headers[:content_type]
+        if returned_content_type != expected_content_type
+          raise "Kroki returned an incorrect content type: " \
+                "expected '#{expected_content_type}', received '#{returned_content_type}'"
+
         end
+        sanitise_diagram(response.body)
+      end
+
+      # Sanitises a rendered diagram. Only <script> elements are removed, which is the most minimal / naive
+      # implementation possible and is definitely not secure.
+      #
+      # @param [String] The diagram to santise in SVG format
+      # @return [String] The sanitized diagram in SVG format
+      def sanitise_diagram(diagram_svg)
+        parsed_svg = Nokogiri::XML(diagram_svg)
+        parsed_svg.xpath('//*[name()="script"]').each(&:remove)
+        parsed_svg.to_xml
       end
 
       # Encodes the diagram into Kroki format using deflate + base64.
       # See https://docs.kroki.io/kroki/setup/encode-diagram/.
       #
-      # @param [String, #read] The diagram to encode
+      # @param [String, #read] The diagram description to encode
       # @return [String] The encoded diagram
-      def encode_diagram(diagram)
-        Base64.urlsafe_encode64(Zlib.deflate(diagram))
+      def encode_diagram(diagram_desc)
+        Base64.urlsafe_encode64(Zlib.deflate(diagram_desc))
       end
 
       # Gets an array of supported diagram languages from the Kroki '/health' endpoint.
@@ -73,31 +99,58 @@ module Jekyll
       # configured Kroki instance. For example, Mermaid will still show up as a supported language even if the Mermaid
       # companion container is not running.
       #
-      # @param [String] The URL of the Kroki instance
+      # @param [Faraday::Connection] The Faraday connection to use
       # @return [Array] The supported diagram languages
-      def get_supported_languages(kroki_url)
-        uri = URI("#{kroki_url}/health")
-
+      def get_supported_languages(connection)
         begin
-          response = Net::HTTP.get_response(uri)
-        rescue StandardError => e
-          raise e.message
+          response = connection.get("health")
+        rescue Faraday::Error => e
+          raise e.response[:body]
+        end
+        response.body["version"].keys
+      end
+
+      # Sets up a new Faraday connection.
+      #
+      # @param [URI::HTTP] The URL of the Kroki instance
+      # @return [Faraday::Connection] The Faraday connection
+      def setup_connection(kroki_url)
+        retry_options = { max: HTTP_MAX_RETRIES, interval: 0.1, interval_randomness: 0.5, backoff_factor: 2,
+                          exceptions: [Faraday::RequestTimeoutError, Faraday::ServerError] }
+
+        Faraday.new(url: kroki_url) do |builder|
+          builder.request :retry, retry_options
+          builder.response :json, content_type: /\bjson$/
+          builder.response :raise_error
+        end
+      end
+
+      # Gets the URL of the Kroki instance to use for rendering diagrams.
+      #
+      # @param The Jekyll site configuration
+      # @return [URI::HTTP] The URL of the Kroki instance
+      def kroki_url(config)
+        if config.key?("jekyll-kroki") && config["jekyll-kroki"].key?("kroki_url")
+          url = config["jekyll-kroki"]["kroki_url"]
+          raise TypeError, "'kroki_url' is not a valid HTTP URL" unless URI.parse(url).is_a?(URI::HTTP)
+
+          URI(url)
         else
-          JSON.parse(response.body)["version"].keys if response.is_a?(Net::HTTPSuccess)
+          URI(KROKI_DEFAULT_URL)
         end
       end
 
-      # Determines whether a document may contain renderable diagram descriptions - it is in HTML format and is either
+      # Determines whether a document may contain embeddable diagram descriptions - it is in HTML format and is either
       # a Jekyll::Page or writeable Jekyll::Document.
       #
-      # @param [Jekyll::Page or Jekyll::Document] The document to check for renderability
-      def renderable?(doc)
+      # @param [Jekyll::Page or Jekyll::Document] The document to check for embedability
+      def embeddable?(doc)
         doc.output_ext == ".html" && (doc.is_a?(Jekyll::Page) || doc.write?)
       end
     end
   end
 end
 
-Jekyll::Hooks.register [:pages, :documents], :post_render do |doc|
-  Jekyll::Kroki.render(doc) if Jekyll::Kroki.renderable?(doc)
+Jekyll::Hooks.register :site, :post_render do |doc|
+  Jekyll::Kroki.embed_site(doc)
 end

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-kroki
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Felix van Oost
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-10-20 00:00:00.000000000 Z
+date: 2023-10-23 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: jekyll
   requirement: !ruby/object:Gem::Requirement
@@ -81,15 +109,14 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.21'
 description: |-
-  Replaces diagram descriptions written in any Kroki-supported language in HTML files with their
-                        visual representation in SVG format
+  Replaces diagram descriptions written in any Kroki-supported language in HTML files generated by
+                        Jekyll with their visual representation in SVG format.
 email: 
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
-- ".rubocop_todo.yml"
 - LICENSE
 - README.md
 - Rakefile

data/.rubocop_todo.yml

@@ -1,37 +0,0 @@
-# This configuration was generated by
-# `rubocop --auto-gen-config`
-# on 2023-10-18 03:15:03 UTC using RuboCop version 1.57.1.
-# The point is for the user to remove these configuration records
-# one by one as the offenses are removed from the code base.
-# Note that changes in the inspected code, or installation of new
-# versions of RuboCop, may require this file to be generated again.
-
-# Offense count: 4
-Lint/ShadowedException:
-  Exclude:
-    - 'lib/jekyll-kroki.rb'
-    - 'site/_plugins/jekyll-kroki.rb'
-
-# Offense count: 2
-Naming/AccessorMethodName:
-  Exclude:
-    - 'lib/jekyll-kroki.rb'
-    - 'site/_plugins/jekyll-kroki.rb'
-
-# Offense count: 2
-# Configuration parameters: ExpectMatchingDefinition, CheckDefinitionPathHierarchy, CheckDefinitionPathHierarchyRoots, Regex, IgnoreExecutableScripts, AllowedAcronyms.
-# CheckDefinitionPathHierarchyRoots: lib, spec, test, src
-# AllowedAcronyms: CLI, DSL, ACL, API, ASCII, CPU, CSS, DNS, EOF, GUID, HTML, HTTP, HTTPS, ID, IP, JSON, LHS, QPS, RAM, RHS, RPC, SLA, SMTP, SQL, SSH, TCP, TLS, TTL, UDP, UI, UID, UUID, URI, URL, UTF8, VM, XML, XMPP, XSRF, XSS
-Naming/FileName:
-  Exclude:
-    - 'lib/jekyll-kroki.rb'
-    - 'site/_plugins/jekyll-kroki.rb'
-
-# Offense count: 2
-# Configuration parameters: AllowedConstants.
-Style/Documentation:
-  Exclude:
-    - 'spec/**/*'
-    - 'test/**/*'
-    - 'lib/jekyll-kroki.rb'
-    - 'site/_plugins/jekyll-kroki.rb'