BigW Consortium Gitlab

renderer.rb 6.14 KB
Newer Older
1 2
module Banzai
  module Renderer
3
    module_function
4

5 6 7 8 9 10 11 12 13 14
    # Convert a Markdown String into an HTML-safe String of HTML
    #
    # Note that while the returned HTML will have been sanitized of dangerous
    # HTML, it may post a risk of information leakage if it's not also passed
    # through `post_process`.
    #
    # Also note that the returned String is always HTML, not XHTML. Views
    # requiring XHTML, such as Atom feeds, need to call `post_process` on the
    # result, providing the appropriate `pipeline` option.
    #
15
    # text     - Markdown String
16 17 18
    # context  - Hash of context options passed to our HTML Pipeline
    #
    # Returns an HTML-safe String
19
    def render(text, context = {})
20 21 22
      cache_key = context.delete(:cache_key)
      cache_key = full_cache_key(cache_key, context[:pipeline])

23
      if cache_key
24 25 26 27
        Gitlab::Metrics.measure(:banzai_cached_render) do
          Rails.cache.fetch(cache_key) do
            cacheless_render(text, context)
          end
28
        end
29 30
      else
        cacheless_render(text, context)
31 32 33
      end
    end

34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61
    # Convert a Markdown-containing field on an object into an HTML-safe String
    # of HTML. This method is analogous to calling render(object.field), but it
    # can cache the rendered HTML in the object, rather than Redis.
    #
    # The context to use is learned from the passed-in object by calling
    # #banzai_render_context(field), and cannot be changed. Use #render, passing
    # it the field text, if a custom rendering is needed. The generated context
    # is returned along with the HTML.
    def render_field(object, field)
      html_field = object.markdown_cache_field_for(field)

      html = object.__send__(html_field)
      return html if html.present?

      html = cacheless_render_field(object, field)
      object.update_column(html_field, html) unless object.new_record? || object.destroyed?

      html
    end

    # Same as +render_field+, but without consulting or updating the cache field
    def cacheless_render_field(object, field)
      text = object.__send__(field)
      context = object.banzai_render_context(field)

      cacheless_render(text, context)
    end

62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
    # Perform multiple render from an Array of Markdown String into an
    # Array of HTML-safe String of HTML.
    #
    # As the rendered Markdown String can be already cached read all the data
    # from the cache using Rails.cache.read_multi operation. If the Markdown String
    # is not in the cache or it's not cacheable (no cache_key entry is provided in
    # the context) the Markdown String is rendered and stored in the cache so the
    # next render call gets the rendered HTML-safe String from the cache.
    #
    # For further explanation see #render method comments.
    #
    # texts_and_contexts - An Array of Hashes that contains the Markdown String (:text)
    #                      an options passed to our HTML Pipeline (:context)
    #
    # If on the :context you specify a :cache_key entry will be used to retrieve it
    # and cache the result of rendering the Markdown String.
    #
    # Returns an Array containing HTML-safe String instances.
    #
    # Example:
    #    texts_and_contexts
    #    => [{ text: '### Hello',
    #          context: { cache_key: [note, :note] } }]
85
    def cache_collection_render(texts_and_contexts)
86 87 88 89 90 91 92 93
      items_collection = texts_and_contexts.each_with_index do |item, index|
        context = item[:context]
        cache_key = full_cache_multi_key(context.delete(:cache_key), context[:pipeline])

        item[:cache_key] = cache_key if cache_key
      end

      cacheable_items, non_cacheable_items = items_collection.partition { |item| item.key?(:cache_key) }
94 95 96 97 98 99 100 101 102 103

      items_in_cache = []
      items_not_in_cache = []

      unless cacheable_items.empty?
        items_in_cache = Rails.cache.read_multi(*cacheable_items.map { |item| item[:cache_key] })
        items_not_in_cache = cacheable_items.reject do |item|
          item[:rendered] = items_in_cache[item[:cache_key]]
          items_in_cache.key?(item[:cache_key])
        end
104 105 106 107 108 109 110 111 112 113
      end

      (items_not_in_cache + non_cacheable_items).each do |item|
        item[:rendered] = render(item[:text], item[:context])
        Rails.cache.write(item[:cache_key], item[:rendered]) if item[:cache_key]
      end

      items_collection.map { |item| item[:rendered] }
    end

114
    def render_result(text, context = {})
115
      text = Pipeline[:pre_process].to_html(text, context) if text
116

117
      Pipeline[context[:pipeline]].call(text, context)
118 119
    end

120 121 122 123 124 125 126 127 128 129 130 131 132
    # Perform post-processing on an HTML String
    #
    # This method is used to perform state-dependent changes to a String of
    # HTML, such as removing references that the current user doesn't have
    # permission to make (`RedactorFilter`).
    #
    # html     - String to process
    # context  - Hash of options to customize output
    #            :pipeline  - Symbol pipeline type
    #            :project   - Project
    #            :user      - User object
    #
    # Returns an HTML-safe String
133
    def post_process(html, context)
134 135 136 137 138 139 140 141 142 143
      context = Pipeline[context[:pipeline]].transform_context(context)

      pipeline = Pipeline[:post_process]
      if context[:xhtml]
        pipeline.to_document(html, context).to_html(save_with: Nokogiri::XML::Node::SaveOptions::AS_XHTML)
      else
        pipeline.to_html(html, context)
      end.html_safe
    end

144
    def cacheless_render(text, context = {})
145 146
      Gitlab::Metrics.measure(:banzai_cacheless_render) do
        result = render_result(text, context)
147

148 149 150 151 152 153
        output = result[:output]
        if output.respond_to?(:to_html)
          output.to_html
        else
          output.to_s
        end
154 155 156
      end
    end

157
    def full_cache_key(cache_key, pipeline_name)
158 159 160
      return unless cache_key
      ["banzai", *cache_key, pipeline_name || :full]
    end
161 162 163 164

    # To map Rails.cache.read_multi results we need to know the Rails.cache.expanded_key.
    # Other option will be to generate stringified keys on our side and don't delegate to Rails.cache.expanded_key
    # method.
165
    def full_cache_multi_key(cache_key, pipeline_name)
166 167 168
      return unless cache_key
      Rails.cache.send(:expanded_key, full_cache_key(cache_key, pipeline_name))
    end
169 170
  end
end