haveapi 0.31.1 → 0.32.0

data/lib/haveapi/documentation_search.rb

@@ -0,0 +1,225 @@
+require 'cgi'
+require 'json'
+require 'uri'
+require 'haveapi/documentation_search_index'
+
+module HaveAPI
+  class DocumentationSearch
+    LIMIT = 20
+    KIND_ORDER = { resource: 0, action: 1, parameter: 2 }.freeze
+
+    def self.parameter_anchor(resource_path:, action_name:, direction:, parameter_name:, authentication: nil)
+      tuple = [authentication&.to_s, resource_path.map(&:to_s), action_name.to_s, direction.to_s, parameter_name.to_s]
+      "parameter-#{JSON.generate(tuple).unpack1('H*')}"
+    end
+
+    def initialize(index:, query:)
+      @index = index
+      @query = query
+      @needle = query.downcase
+      @tokens = @needle.split(/[[:space:]]+/)
+    end
+
+    def call
+      @matches = []
+      records unless @tokens.empty?
+      { query: @query, results: @matches.first(LIMIT).map(&:last), more: @matches.length > LIMIT }
+    end
+
+    private
+
+    def field(hash, key, default = nil)
+      return default unless hash.is_a?(Hash)
+
+      hash.fetch(key) { hash.fetch(key.to_s, default) }
+    end
+
+    def records
+      field(@index, :resources).each do |resource|
+        path = field(resource, :path)
+        record = resource_record(resource)
+        match(record, field(resource, :search), [path.last, path.join('.')])
+      end
+      field(@index, :actions).each do |action|
+        resource = field(@index, :resources).fetch(field(action, :resource))
+        record = action_record(resource, action)
+        match(record, action_metadata(resource, action), field(action, :identifiers))
+      end
+      field(@index, :parameters).each do |parameter|
+        action = field(@index, :actions).fetch(field(parameter, :action))
+        resource = field(@index, :resources).fetch(field(action, :resource))
+        record = action_record(resource, action).merge(kind: :parameter, name: field(parameter, :name),
+                                                       label: field(parameter, :label), type: field(parameter, :type),
+                                                       direction: field(parameter, :direction).to_sym)
+        record[:anchor] = self.class.parameter_anchor(resource_path: record[:resource_path], action_name: record[:action_name],
+                                                      direction: record[:direction], parameter_name: record[:name], authentication: record[:authentication])
+        metadata = action_metadata(resource, action) + %i[name label type direction humanized_name].map { |name| field(parameter, name) }
+        match(record, metadata, [record[:name]])
+      end
+    end
+
+    def resource_record(resource)
+      path = field(resource, :path)
+      { kind: :resource, resource_path: path, name: path.last, label: field(resource, :label),
+        resource_label: resource_label(resource),
+        action_name: nil, direction: nil, type: nil, authentication: field(resource, :authentication),
+        anchor: "root-#{path.join('-')}" }
+    end
+
+    def resource_label(resource)
+      @resource_labels ||= field(@index, :resources).to_h do |entry|
+        [[field(entry, :authentication), field(entry, :path)], field(entry, :label)]
+      end
+      path = field(resource, :path)
+      path.each_index.map do |index|
+        @resource_labels.fetch([field(resource, :authentication), path.first(index + 1)], path[index])
+      end.join(' · ')
+    end
+
+    def action_record(resource, action)
+      name = field(action, :name)
+      resource_record(resource).merge(kind: :action, name:, label: field(action, :label), action_name: name,
+                                      anchor: "root-#{field(resource, :path).join('-')}-#{name}")
+    end
+
+    def action_metadata(resource, action)
+      field(resource, :search) + field(action, :identifiers) + field(action, :search)
+    end
+
+    def match(record, metadata, identifiers)
+      searchable = metadata.compact.map { |value| value.to_s.downcase }
+      text = searchable.join(' ')
+      return unless @tokens.all? { |token| text.include?(token) }
+
+      names = identifiers.compact.map { |value| value.to_s.downcase }
+      rank = if names.include?(@needle)
+               0
+             elsif names.any? { |name| name.start_with?(@needle) }
+               1
+             else
+               2
+             end
+      kind = KIND_ORDER.fetch(record[:kind])
+      key = [kind, rank, record[:authentication].to_s, record[:resource_path].join('.'),
+             record[:action_name].to_s, record[:name], record[:direction].to_s]
+      @matches << [key, record]
+      @matches.sort_by!(&:first)
+      @matches.pop if @matches.length > LIMIT + 1
+    end
+
+    module Helpers
+      def documentation_search_query
+        documentation_search_parameters[:query]
+      end
+
+      def documentation_search_parameters
+        return @documentation_search_parameters if defined?(@documentation_search_parameters)
+
+        pairs = request.query_string.split('&').map do |pair|
+          key, value = pair.split('=', 2)
+          [URI.decode_www_form_component(key), URI.decode_www_form_component(value || '')]
+        end
+        selected = pairs.select { |key, _| key.match?(/\Aq(?:\[|\z)/) }
+        unless selected.length <= 1 && selected.all? { |key, value| key == 'q' && value.valid_encoding? }
+          invalid_documentation_search_query
+        end
+        query = selected.empty? ? '' : selected.first.last.strip
+        invalid_documentation_search_query if query.length > 256
+        indices = pairs.select { |key, _| key.match?(/\Asearch_index(?:\[|\z)/) }
+        headers 'Cache-Control' => 'private, no-store' if indices.any?
+        if indices.any? && !(indices.length == 1 && indices.first[0] == 'search_index' &&
+                            indices.first[1].match?(/\A(?:current|[0-9a-f]{64})\z/) && selected.empty? &&
+                            documentation_selection == { 'page' => 'resources' })
+          invalid_documentation_search_query
+        end
+        @documentation_search_parameters = { query:, index: indices.first&.last }
+      rescue ArgumentError
+        invalid_documentation_search_query
+      end
+
+      def invalid_documentation_search_query
+        headers 'Cache-Control' => 'private, no-store'
+        halt 400, 'Invalid documentation search query'
+      end
+
+      def documentation_search_form_options(id:)
+        version = @v || settings.api_server.default_version
+        return unless version
+
+        { id:, action: url(settings.api_server.version_prefix(version), false), version:,
+          query: @documentation_page == 'resources' ? documentation_search_query : '',
+          view_key: @help ? documentation_search_index.key : '',
+          index_url: documentation_search_index_url(version:, key: @help ? documentation_search_index.key : 'current') }
+      end
+
+      def documentation_search_index
+        @documentation_search_index ||= Index.new(description: @help, version: @v,
+                                                  base_path: url(settings.api_server.version_prefix(@v), false),
+                                                  locale: ::I18n.locale, visibility: current_user ? 'authenticated' : 'anonymous')
+      end
+
+      def documentation_search_index_url(version:, key:)
+        "#{url(settings.api_server.version_prefix(version), false)}?page=resources&search_index=#{key}"
+      end
+
+      def documentation_search_index_request?
+        !documentation_search_parameters[:index].nil?
+      end
+
+      def render_documentation_search_index
+        headers 'Cache-Control' => 'private, no-store'
+        index = documentation_search_index
+        requested = documentation_search_parameters[:index]
+        if requested != 'current' && requested != index.key
+          halt 409, 'Search has changed. Reload this page or submit to open current results.'
+        end
+
+        content_type 'text/html', charset: 'utf-8'
+        add_vary_header('Cookie')
+        add_vary_header('Authorization')
+        body = erb :'documentation/search_index', layout: false, locals: { search_index: index }
+        state_changed = response.headers.any? { |name, value| name.downcase == 'set-cookie' && !Array(value).join.empty? }
+        if requested != 'current' && !state_changed
+          tag = %("#{index.key}")
+          headers 'Cache-Control' => 'private, max-age=86400, immutable', 'ETag' => tag
+          conditional = request.env['HTTP_IF_NONE_MATCH'].to_s.split(/\s*,\s*/)
+          halt 304, '' if conditional.any? { |value| [tag, "W/#{tag}", '*'].include?(value) }
+        end
+        body
+      end
+
+      def documentation_parameter_anchor(**)
+        DocumentationSearch.parameter_anchor(**)
+      end
+
+      def documentation_search_results
+        @documentation_search_results ||= DocumentationSearch.new(index: documentation_search_index.payload, query: documentation_search_query).call
+      end
+
+      def documentation_search_result_url(result)
+        if result[:authentication]
+          documentation_url(page: 'authentication', anchor: result[:anchor])
+        else
+          documentation_url(resource: result[:resource_path], anchor: result[:kind] == :resource ? nil : result[:anchor])
+        end
+      end
+
+      def documentation_search_result_title(result)
+        result[:kind] == :resource ? result[:resource_path].join('.') : result[:name]
+      end
+
+      def documentation_search_result_context(result)
+        context = []
+        if result[:kind] == :resource
+          context << result[:resource_label] unless result[:resource_label] == documentation_search_result_title(result)
+        else
+          context << "#{result[:resource_path].join('.')} · #{result[:action_name]}"
+        end
+        context << "#{result[:direction].to_s.capitalize} · #{result[:type]}" if result[:kind] == :parameter
+        context << "Authentication: #{result[:authentication]}" if result[:authentication]
+        context << result[:label] if result[:kind] != :resource && result[:label] && result[:label] != result[:name]
+        context
+      end
+    end
+  end
+end

data/lib/haveapi/documentation_search_index.rb

@@ -0,0 +1,79 @@
+require 'digest'
+require 'json'
+
+module HaveAPI
+  class DocumentationSearch
+    class Index
+      attr_reader :payload, :key
+
+      def initialize(description:, base_path:, version:, locale:, visibility:)
+        @payload = { format: 1, version: text(version), base_path: text(base_path), locale: text(locale),
+                     visibility: text(visibility), resources: [], actions: [], parameters: [] }
+        resources(field(description, :resources, {}))
+        field(description, :authentication, {}).sort_by { |name, _| name.to_s }.each do |provider, info|
+          resources(field(info, :resources, {}), authentication: text(provider))
+        end
+        freeze_data(@payload)
+        @key = Digest::SHA256.hexdigest(JSON.generate(@payload)).freeze
+        freeze
+      end
+
+      private
+
+      def field(hash, name, default = nil)
+        return default unless hash.is_a?(Hash)
+
+        hash.fetch(name) { hash.fetch(name.to_s, default) }
+      end
+
+      def text(value)
+        value.to_s.dup.freeze
+      end
+
+      def strings(values)
+        values.compact.map { |value| text(value) }
+      end
+
+      def resources(tree, path = [], authentication: nil)
+        tree.sort_by { |name, _| name.to_s }.each do |name, resource|
+          selected = path + [text(name)]
+          label = text(field(resource, :label, name.to_s.humanize))
+          index = @payload[:resources].length
+          @payload[:resources] << { path: selected, label:, authentication:,
+                                    search: strings(selected.flat_map { |part| [part, part.humanize] } +
+                                      [selected.join('.'), label, authentication]) }
+          field(resource, :actions, {}).sort_by { |action_name, _| action_name.to_s }.each do |action_name, action|
+            action(index, selected, action_name, action)
+          end
+          resources(field(resource, :resources, {}), selected, authentication:)
+        end
+      end
+
+      def action(resource, path, name, description)
+        name = text(name)
+        index = @payload[:actions].length
+        @payload[:actions] << {
+          resource:, name:, label: text(field(description, :label, name.humanize)),
+          identifiers: strings([name, "#{path.join('.')}.#{name}", *Array(field(description, :aliases)), field(description, :path)]),
+          search: strings([name.humanize, field(description, :method), field(description, :label)])
+        }
+        %i[input output].each do |direction|
+          field(field(description, direction), :parameters, {}).sort_by { |parameter_name, _| parameter_name.to_s }.each do |parameter_name, parameter|
+            @payload[:parameters] << { action: index, name: text(parameter_name),
+                                       label: text(field(parameter, :label, parameter_name.to_s.humanize)),
+                                       type: text(field(parameter, :type)), direction: text(direction),
+                                       humanized_name: text(parameter_name.to_s.humanize) }
+          end
+        end
+      end
+
+      def freeze_data(value)
+        case value
+        when Hash then value.each_value { |entry| freeze_data(entry) }
+        when Array then value.each { |entry| freeze_data(entry) }
+        end
+        value.freeze
+      end
+    end
+  end
+end

data/lib/haveapi/documentation_validators.rb

@@ -0,0 +1,179 @@
+require 'cgi'
+require 'json'
+
+module HaveAPI
+  # Presents already-authorized/localized metadata without changing validation.
+  class DocumentationValidators
+    def self.render(validators, type: nil)
+      return '' if validators.nil? || validators == {}
+      return new(type).data(validators) unless validators.is_a?(Hash)
+
+      renderer = new(type)
+      rules = validators.map { |name, options| renderer.rule(name, options) }.join
+      %(<div class="docs-validators"><table class="docs-validator-table"><caption>Validation rules</caption><thead><tr><th scope="col">Rule</th><th scope="col">Details</th></tr></thead><tbody>#{rules}</tbody></table></div>)
+    end
+
+    def initialize(type)
+      @type = type
+    end
+
+    def rule(name, options)
+      content, used = explanation(name.to_s, options)
+      if content && options.is_a?(Hash)
+        remaining = options.reject { |key, _| used.include?(key.to_s) || key.to_s == 'message' }
+        content += "<p><strong>Validation error message:</strong> #{value(field(options, :message))}</p>" if option?(options, :message)
+        unless remaining.empty?
+          content += "<details><summary>Additional details</summary>#{data(remaining)}</details>"
+        end
+      elsif !content
+        content = "<p>Supplied validator metadata:</p>#{data(options)}"
+      end
+      known = %w[present include exclude accept confirm number length format custom].include?(name.to_s)
+      title = known ? name.to_s.capitalize : name.to_s
+      %(<tr class="docs-validator"><th scope="row">#{html(title)}</th><td>#{content}</td></tr>)
+    end
+
+    def explanation(name, options)
+      return ["<p>Application-specific rule: #{html(options)}</p>", []] if name == 'custom' && options.is_a?(String)
+      return unless options.is_a?(Hash)
+      # Two differently typed keys must not silently collapse to one option.
+      return if options.keys.map(&:to_s).uniq.length != options.length
+
+      case name
+      when 'present' then presence(options)
+      when 'include', 'exclude' then choices(name, options)
+      when 'accept'
+        return unless option?(options, :value)
+
+        ["<p>Must equal #{literal(field(options, :value))}.</p>", ['value']]
+      when 'confirm'
+        return unless field(options, :parameter).is_a?(String) || field(options, :parameter).is_a?(Symbol)
+        return unless boolean?(field(options, :equal))
+
+        relation = field(options, :equal) ? 'Must equal' : 'Must differ from'
+        ["<p>#{relation} parameter <code>#{html(field(options, :parameter))}</code>.</p>", %w[parameter equal]]
+      when 'number' then number(options)
+      when 'length' then length(options)
+      when 'format'
+        return unless field(options, :rx).is_a?(String) && boolean?(field(options, :match))
+
+        relation = field(options, :match) ? 'Must match' : 'Must not match'
+        content = "<p>#{relation} this regular expression:</p><pre><code>#{html(field(options, :rx))}</code></pre>"
+        content += "<p>#{value(field(options, :description))}</p>" if option?(options, :description)
+        [content, %w[rx match description]]
+      end
+    end
+
+    def presence(options)
+      return unless boolean?(field(options, :empty))
+
+      empty = field(options, :empty) ? 'Empty values are allowed.' : 'Must not be empty; strings must contain a non-whitespace character.'
+      ["<p>Must be supplied and cannot be null. #{empty}</p>", ['empty']]
+    end
+
+    def choices(name, options)
+      values = field(options, :values)
+      return unless values.is_a?(Array) || (name == 'include' && values.is_a?(Hash))
+
+      label = name == 'include' ? 'Allowed values' : 'Disallowed values'
+      items = if values.is_a?(Hash)
+                values.map { |machine, label_text| "<li>#{choice_literal(machine)}: #{value(label_text)}</li>" }
+              else
+                values.map { |machine| "<li>#{choice_literal(machine)}</li>" }
+              end
+      body = items.empty? ? '<p>The set is empty.</p>' : %(<ul class="docs-validator-values">#{items.join}</ul>)
+      ["<p>#{label}:</p>#{body}", ['values']]
+    end
+
+    def number(options)
+      numeric = %w[min max step mod]
+      return unless numeric.all? { |key| !option?(options, key) || finite_number?(field(options, key)) }
+      return unless %w[odd even].all? { |key| !option?(options, key) || boolean?(field(options, key)) }
+
+      lines = ['Must be a number after parameter type conversion.']
+      lines << "Minimum: #{literal(field(options, :min))} (inclusive)." if option?(options, :min)
+      lines << "Maximum: #{literal(field(options, :max))} (inclusive)." if option?(options, :max)
+      if option?(options, :step)
+        start = option?(options, :min) ? field(options, :min) : 0
+        lines << "Step: #{literal(field(options, :step))}, measured from #{literal(start)}."
+      end
+      lines << "Must be a multiple of #{literal(field(options, :mod))}, measured from zero." if option?(options, :mod)
+      lines << 'Must be odd.' if field(options, :odd) == true
+      lines << 'Must be even.' if field(options, :even) == true
+      lines << 'Odd-only restriction: disabled.' if option?(options, :odd) && field(options, :odd) == false
+      lines << 'Even-only restriction: disabled.' if option?(options, :even) && field(options, :even) == false
+      ["<ul>#{lines.map { |line| "<li>#{line}</li>" }.join}</ul>", numeric + %w[odd even]]
+    end
+
+    def length(options)
+      keys = %w[equals min max]
+      return unless keys.any? { |key| option?(options, key) }
+      return unless keys.all? { |key| !option?(options, key) || field(options, key).is_a?(Integer) }
+      return if option?(options, :equals) && (option?(options, :min) || option?(options, :max))
+
+      unit = if %w[String Text].include?(@type)
+               ' characters'
+             elsif %w[List Array].include?(@type)
+               ' items'
+             else
+               ''
+             end
+      lines = []
+      lines << "Length must equal #{literal(field(options, :equals))}#{unit}." if option?(options, :equals)
+      lines << "Minimum length: #{literal(field(options, :min))}#{unit} (inclusive)." if option?(options, :min)
+      lines << "Maximum length: #{literal(field(options, :max))}#{unit} (inclusive)." if option?(options, :max)
+      ["<ul>#{lines.map { |line| "<li>#{line}</li>" }.join}</ul>", keys]
+    end
+
+    def option?(options, name)
+      options.has_key?(name.to_sym) || options.has_key?(name.to_s)
+    end
+
+    def field(options, name)
+      options.has_key?(name.to_sym) ? options[name.to_sym] : options[name.to_s]
+    end
+
+    def boolean?(value)
+      [true, false].include?(value)
+    end
+
+    def finite_number?(value)
+      value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)
+    end
+
+    def json_value?(value)
+      case value
+      when String, Integer, true, false, nil then true
+      when Float then value.finite?
+      when Array then value.all? { |item| json_value?(item) }
+      when Hash then value.all? { |key, item| key.is_a?(String) && json_value?(item) }
+      else false
+      end
+    end
+
+    def literal(value)
+      json_value?(value) ? "<code>#{html(JSON.generate(value))}</code>" : "<span>Ruby value: <code>#{html(value.inspect)}</code></span>"
+    end
+
+    def choice_literal(value)
+      value.is_a?(String) ? "<code>#{html(value)}</code>" : literal(value)
+    end
+
+    def value(value)
+      value.is_a?(String) ? html(value) : literal(value)
+    end
+
+    def data(value)
+      label, text = if json_value?(value)
+                      ['JSON', JSON.pretty_generate(value)]
+                    else
+                      ['Ruby value', value.inspect]
+                    end
+      "<p>#{label}:</p><pre><code>#{html(text)}</code></pre>"
+    end
+
+    def html(value)
+      CGI.escapeHTML(value.to_s)
+    end
+  end
+end