haveapi 0.31.1 → 0.32.0

data/lib/haveapi/server.rb

@@ -4,13 +4,18 @@ require 'tilt'
 require 'cgi'
 require 'haveapi/hooks'
 require 'haveapi/documentation_clients'
+require 'haveapi/documentation_helpers'
+require 'haveapi/documentation_validators'
+require 'haveapi/documentation_search'
+require 'haveapi/shared_documentation_helpers'
+require 'haveapi/documentation_oauth'
 
 module HaveAPI
   class Server
     attr_accessor :default_version, :action_state, :validation_error_http_status,
                   :default_locale, :parameter_i18n_scope
     attr_reader :root, :routes, :module_name, :auth_chain, :versions, :extensions,
-                :action_state_auth, :locale_header, :available_locales
+                :action_state_auth, :locale_header, :available_locales, :documentation_name
 
     include Hookable
 
@@ -231,13 +236,8 @@ module HaveAPI
         settings.api_server.root
       end
 
-      def logout_url
-        ret = url("#{root}_logout")
-        ret.insert(ret.index('//') + 2, '_log:out@')
-      end
-
       def doc(file)
-        markdown :"../../../doc/#{file}"
+        markdown :"../../../doc/#{file}", with_toc_data: true, tables: true, fenced_code_blocks: true, lax_spacing: true
       end
 
       def base_url
@@ -260,7 +260,17 @@ module HaveAPI
         profile = if client
                     settings.api_server.documentation_client_profiles(@v)[client.code&.to_sym]
                   end
-        @documentation_context.with(profile:, **changes)
+        parent = @documentation_context
+        # Snapshot each selected resource once in this request, before client
+        # profile/detail derivation, and share it across that resource's panels.
+        if changes[:resource] && changes[:resource_path]
+          resource = changes.delete(:resource)
+          path = changes.delete(:resource_path).map { |part| part.to_s.dup.freeze }.freeze
+          @documentation_resource_contexts ||= {}
+          key = [resource.__id__, path]
+          parent = @documentation_resource_contexts[key] ||= parent.with(resource_path: path, resource:)
+        end
+        parent.with(profile:, **changes)
       end
 
       def documentation_clients
@@ -274,6 +284,27 @@ module HaveAPI
         end
       end
 
+      def documentation_example_variants(kind, auth_method: nil, auth_description: nil, **changes)
+        documentation_clients.flat_map do |client|
+          context = documentation_context(client, **changes, detail: :simple)
+          simple = client.render(kind, context:, auth_method:, auth_description:)
+          next [] unless simple
+
+          levels = client.detail_levels_for(kind, context:, result: simple, auth_method:, auth_description:)
+          unless [[:simple], %i[simple thorough]].include?(levels)
+            raise ArgumentError, 'Invalid documentation example detail levels'
+          end
+
+          variants = levels.filter_map do |detail|
+            result = detail == :simple ? simple : client.render(kind, context: context.with(detail:), auth_method:, auth_description:)
+            [client, detail, result] if result
+          end
+          @documentation_page_details ||= {}
+          @documentation_page_details[client.id] = (@documentation_page_details.fetch(client.id, []) | variants.map { |_client, detail, _result| detail })
+          variants
+        end
+      end
+
       def host
         request.env['HTTP_HOST'].split(':').first
       end
@@ -299,27 +330,15 @@ module HaveAPI
       def format_param_type(param)
         return param[:type] if param[:type] != 'Resource'
 
-        "<a href=\"#root-#{param[:resource].join('-')}-show\">#{param[:type]}</a>"
-      end
+        entry = documentation_resources.find { |resource| resource[:path] == param[:resource].map(&:to_s) }
+        return param[:type] unless entry
 
-      def format_validators(validators)
-        ret = ''
-        return ret if validators.nil?
-
-        validators.each do |name, opts|
-          ret += "<h5>#{escape_html(name.to_s.capitalize)}</h5>"
-          ret += '<dl>'
-          if opts.respond_to?(:each_pair)
-            opts.each_pair do |k, v|
-              ret += "<dt>#{escape_html(k)}</dt><dd>#{escape_html(v.to_s)}</dd>"
-            end
-          else
-            ret += "<dt>description</dt><dd>#{escape_html(opts.to_s)}</dd>"
-          end
-          ret += '</dl>'
-        end
+        anchor = entry[:info][:actions].has_key?('show') || entry[:info][:actions].has_key?(:show) ? "#{entry[:id]}-show" : entry[:id]
+        "<a href=\"#{escape_html(documentation_url(resource: entry[:key], anchor:))}\">#{param[:type]}</a>"
+      end
 
-        ret
+      def format_validators(validators, type: nil)
+        DocumentationValidators.render(validators, type:)
       end
 
       def escape_html(v)
@@ -342,6 +361,38 @@ module HaveAPI
       self.locale_header = 'Accept-Language'
     end
 
+    def documentation_name=(value)
+      raise ArgumentError, 'Documentation name must be configured before mount' if @sinatra
+
+      if value.nil?
+        @documentation_name = nil
+        return
+      end
+      unless value.is_a?(String)
+        raise ArgumentError, 'Documentation name must be a UTF-8 string'
+      end
+
+      name = value.dup.force_encoding(Encoding::UTF_8)
+      unless name.valid_encoding? && !name.match?(/[[:cntrl:]]/)
+        raise ArgumentError, 'Documentation name must be a UTF-8 string without control characters'
+      end
+
+      name = name.strip
+      unless name.bytesize.between?(1, 256)
+        raise ArgumentError, 'Documentation name must contain 1 to 256 bytes'
+      end
+
+      @documentation_name = name.freeze
+    end
+
+    def documentation_oauth(**options)
+      return @documentation_oauth if options.empty?
+      raise ArgumentError, 'Documentation OAuth is already configured' if @documentation_oauth
+      raise ArgumentError, 'Documentation OAuth must be configured before mount' if @sinatra
+
+      @documentation_oauth = DocumentationOAuth.new(**options)
+    end
+
     def documentation_clients(version, **profiles)
       @documentation_clients.register(version, **profiles)
     end
@@ -461,6 +512,10 @@ module HaveAPI
         helpers Sinatra::Cookies
         helpers ServerHelpers
         helpers DocHelpers
+        helpers DocumentationHelpers
+        helpers DocumentationSearch::Helpers
+        helpers SharedDocumentationHelpers
+        helpers DocumentationOAuth::Helpers
 
         before do
           setup_request_locale
@@ -496,7 +551,15 @@ module HaveAPI
 
       # Mount root
       @sinatra.get @root do
-        auth_users_by_version = authenticated_versions
+        if documentation_selection?
+          next render_version_documentation(settings.api_server.default_version)
+        end
+
+        headers 'Cache-Control' => 'private, no-store'
+        single_version = settings.api_server.versions.length == 1
+        auth_users_by_version = settings.api_server.versions.to_h do |version|
+          [version, documentation_authenticated?(version)]
+        end
 
         @api = settings.api_server.describe(Context.new(
                                               settings.api_server,
@@ -505,8 +568,16 @@ module HaveAPI
                                               auth_users_by_version:
                                             ))
 
+        if single_version
+          version = settings.api_server.default_version
+          @documentation_index_account = {
+            version:, user: auth_users_by_version[version],
+            authentication: @api[:versions].fetch(version).fetch(:authentication)
+          }
+        end
+
         content_type 'text/html'
-        erb :index, layout: :main_layout
+        render_documentation_index
       end
 
       @sinatra.options @root do
@@ -548,67 +619,51 @@ module HaveAPI
         @formatter.format(true, ret)
       end
 
-      # Doc
+      # Shared documentation keeps the existing content and URL aliases.
       @sinatra.get "#{@root}doc" do
-        content_type 'text/html'
-        erb :main_layout do
-          doc(:index)
-        end
+        render_shared_readme
       end
 
       @sinatra.get "#{@root}doc/readme" do
-        content_type 'text/html'
-
-        erb :main_layout do
-          markdown File.new("#{settings.views}/../../../README.md").read
-        end
+        render_shared_readme
       end
 
       @sinatra.get "#{@root}doc/json-schema" do
-        content_type 'text/html'
-        erb :doc_layout, layout: :main_layout do
-          begin
-            @content = File.read(File.join(settings.root, '../../doc/json-schema.html'))
-          rescue Errno::ENOENT
-            halt 404
-          end
-
-          @sidebar = erb :'doc_sidebars/json-schema'
+        begin
+          content = File.read(File.join(settings.root, '../../doc/json-schema.html'))
+        rescue Errno::ENOENT
+          halt 404
         end
+        render_shared_documentation(content:, title: 'JSON schema', sidebar: erb(:'doc_sidebars/json-schema'))
       end
 
-      @sinatra.get %r{#{@root}doc/([^.]+)(\.md)?} do |f, _|
-        content_type 'text/html'
-        erb :doc_layout, layout: :main_layout do
-          begin
-            @content = doc(f)
-          rescue Errno::ENOENT
-            halt 404
-          end
+      @sinatra.get %r{#{@root}doc/([^.]+)(\.md)?} do |file, _|
+        next render_shared_readme if file == 'index'
 
-          begin
-            @sidebar = erb :"doc_sidebars/#{f}"
-          rescue Errno::ENOENT
-            @sidebar = ''
-          end
+        begin
+          content = doc(file)
+        rescue Errno::ENOENT
+          halt 404
         end
-      end
-
-      # Login/logout links
-      @sinatra.get "#{root}_login" do
-        if current_user
-          redirect back
-        else
-          authenticate!(settings.api_server.default_version) # FIXME
+        sidebar = begin
+          erb :"doc_sidebars/#{file}"
+        rescue Errno::ENOENT
+          nil
         end
+        render_shared_documentation(content:, title: file.humanize, sidebar:)
       end
 
-      @sinatra.get "#{root}_logout" do
-        require_auth!
+      # Retain old documentation links without engaging browser credentials.
+      %w[_login _logout].each do |path|
+        @sinatra.get "#{root}#{path}" do
+          headers 'Cache-Control' => 'private, no-store'
+          halt 303, { 'Location' => url(settings.api_server.version_prefix(settings.api_server.default_version), false) }, ''
+        end
       end
 
       @auth_chain << HaveAPI.default_authenticate if @auth_chain.empty?
       @auth_chain.setup(@versions)
+      documentation_oauth&.mount(self, @sinatra)
 
       @extensions.each { |e| e.enabled(self) }
 
@@ -618,6 +673,7 @@ module HaveAPI
       mount_version(@root, @default_version)
 
       @versions.each do |v|
+        mount_documentation_redirect(v)
         mount_version(version_prefix(v), v)
       end
 
@@ -629,26 +685,28 @@ module HaveAPI
       raise
     end
 
+    def mount_documentation_redirect(version)
+      prefix = version_prefix(version)
+      slashless = prefix.chomp('/')
+      @sinatra.get slashless do
+        pass unless request.path_info == slashless
+
+        headers 'Cache-Control' => 'private, no-store'
+        query = request.query_string
+        halt 400, 'Invalid documentation query' if query.bytes.any? { |byte| byte < 32 || byte == 127 }
+        destination = url(prefix, false)
+        destination += "?#{query}" unless query.empty?
+        halt 308, { 'Location' => destination }, ''
+      end
+    end
+    private :mount_documentation_redirect
+
     def mount_version(prefix, v)
       @routes[v] ||= {}
       @routes[v][:resources] = {}
 
       @sinatra.get prefix do
-        authenticated?(v)
-
-        @v = v
-        @help = settings.api_server.describe_version(Context.new(
-                                                       settings.api_server,
-                                                       version: v,
-                                                       user: current_user,
-                                                       params:
-                                                     ))
-
-        content_type 'text/html'
-        erb :doc_layout, layout: :main_layout do
-          @content = erb :version_page
-          @sidebar = erb :version_sidebar
-        end
+        render_version_documentation(v)
       end
 
       @sinatra.options prefix do

data/lib/haveapi/shared_documentation_helpers.rb

@@ -0,0 +1,54 @@
+module HaveAPI
+  module SharedDocumentationHelpers
+    def render_documentation_index
+      render_neutral_documentation(content: erb(:index), title: 'API versions', page: 'versions')
+    end
+
+    def render_shared_documentation(content:, title:, sidebar: nil)
+      render_neutral_documentation(content:, title:, sidebar:, page: 'guide')
+    end
+
+    def render_shared_readme
+      content = markdown(File.read("#{settings.views}/../../../README.md"),
+                         with_toc_data: true, tables: true, fenced_code_blocks: true, lax_spacing: true)
+      render_shared_documentation(content:, title: 'HaveAPI internals')
+    end
+
+    def shared_documentation_url(path = '')
+      url("#{root}#{path}", false)
+    end
+
+    def shared_documentation_reference_url(page: nil)
+      version = settings.api_server.default_version
+      return if version.nil?
+
+      path = settings.api_server.version_prefix(version)
+      path += "?page=#{CGI.escape(page)}" if page
+      url(path, false)
+    end
+
+    private
+
+    def render_neutral_documentation(content:, title:, page:, sidebar: nil)
+      headers 'Cache-Control' => 'private, no-store'
+      @documentation_ui = true
+      @documentation_page = page
+      @documentation_title = title
+      @documentation_resource = nil
+      @v = nil
+      @documentation_toc = sidebar
+      content_type 'text/html'
+      erb :doc_layout, layout: :main_layout do
+        @content = erb :shared_documentation, locals: { content: shared_documentation_tables(content), title: }
+        @sidebar = erb :shared_sidebar
+      end
+    end
+
+    def shared_documentation_tables(content)
+      # Trusted repository HTML is rendered before this presentation-only pass.
+      content.gsub(%r{<table\b[^>]*>.*?</table>}m) do |table|
+        %(<div class="docs-table-scroll" role="region" aria-label="Documentation table" tabindex="0">#{table}</div>)
+      end
+    end
+  end
+end

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
   PROTOCOL_VERSION = '2.0'.freeze
-  VERSION = '0.31.1'.freeze
+  VERSION = '0.32.0'.freeze
 end

data/lib/haveapi/views/doc_layout.erb

@@ -1,4 +1,18 @@
 <% yield %>
+<% if @documentation_ui %>
+<div data-docs data-page="<%= @documentation_page %>" data-resource="<%= escape_html(@documentation_resource && @documentation_resource[:key]) %>">
+  <a class="docs-skip-link" href="#docs-main">Skip to content</a>
+  <div class="docs-mobile-toolbar">
+    <button type="button" data-nav-toggle aria-controls="docs-navigation" aria-expanded="false">Navigation</button>
+  </div>
+  <div class="docs-layout">
+    <aside class="docs-sidebar" id="docs-navigation" data-docs-sidebar><%= @sidebar %></aside>
+    <main class="docs-main" id="docs-main" tabindex="-1"><%= @content %></main>
+  </div>
+  <script type="application/json" data-documentation-clients><%= documentation_json(@help ? documentation_client_metadata : []) %></script>
+  <script type="application/json" data-legacy-anchors><%= documentation_json(@documentation_page == 'overview' ? documentation_legacy_anchors : {}) %></script>
+</div>
+<% else %>
 <div class="row-fluid">
   <div class="col-sm-10">
     <%= @content %>
@@ -25,3 +39,5 @@
         });
     });
 </script>
+
+<% end %>

data/lib/haveapi/views/doc_sidebars/create-client.erb

@@ -1,4 +1,4 @@
-<h1>Contents</h1>
+<h2>Contents</h2>
 <ul class="top-level">
   <li><a href="#client-definition">Client definition</a></li>
   <li><a href="#design-rules">Design rules</a></li>
@@ -6,7 +6,7 @@
     <a href="#necessary-features-to-implement">Necessary features to implement</a>
     <ul>
       <li><a href="#resource-tree">Resource tree</a></li>
-      <li><a href="#inputoutput-parameters">Input/output parameters</a></li>
+      <li><a href="#input-output-parameters">Input/output parameters</a></li>
       <li><a href="#authentication">Authentication</a></li>
       <li><a href="#object-like-access">Object-like access</a></li>
     </ul>
@@ -14,7 +14,7 @@
   <li>
     <a href="#supplemental-features">Supplemental features</a>
     <ul>
-      <li><a href="#client-sde-validations">Client-side validations</a></li>
+      <li><a href="#client-side-validations">Client-side validations</a></li>
     </ul>
   </li>
 </ul>

data/lib/haveapi/views/doc_sidebars/json-schema.erb

@@ -1,4 +1,4 @@
-<h1>Contents</h1>
+<h2>Contents</h2>
 <ul class="top-level">
   <li><a href="#envelope">Envelope</a></li>
   <li><a href="#all">OPTIONS /</a></li>

data/lib/haveapi/views/doc_sidebars/protocol.erb

@@ -1,4 +1,4 @@
-<h1>Contents</h1>
+<h2>Contents</h2>
 <ul class="top-level">
   <li><a href="#protocol-definition">Protocol definition</a></li>
   <li><a href="#self-description">Self-description</a></li>
@@ -6,9 +6,9 @@
   <li>
     <a href="#description-format">Description format</a>
     <ul>
-      <li><a href="#version">Version</a></li>
+      <li><a href="#api-version">Version</a></li>
       <li>
-        <a href="#Authentication">Authentication</a>
+        <a href="#authentication">Authentication</a>
         <ul>
           <li><a href="#http-basic-authentication">HTTP basic authentication</a></li>
           <li><a href="#token-authentication">Token authentication</a></li>
@@ -26,7 +26,7 @@
         <a href="#parameters">Parameters</a>
         <ul>
           <li><a href="#data-types">Data types</a></li>
-          <li><a href="#resource-associations">Resource associations</a></li>
+          <li><a href="#resource-association">Resource associations</a></li>
         </ul>
       </li>
       <li><a href="#examples">Examples</a></li>
@@ -36,7 +36,7 @@
     </ul>
   </li>
   <li><a href="#authorization">Authorization</a></li>
-  <li><a href="#io">Input/output formats</a></li>
+  <li><a href="#input-output-formats">Input/output formats</a></li>
   <li><a href="#request">Request</a></li>
   <li><a href="#response">Response</a></li>
 </ul>

data/lib/haveapi/views/documentation/search_form.erb

@@ -0,0 +1,10 @@
+<form data-documentation-search method="get" action="<%= escape_html(action) %>" data-search-version="<%= escape_html(version) %>" data-search-index-url="<%= escape_html(index_url) %>" data-search-view-key="<%= escape_html(view_key) %>">
+  <input type="hidden" name="page" value="resources">
+  <label for="<%= escape_html(id) %>-query">Search API v<%= escape_html(version) %></label>
+  <input type="search" name="q" data-search-query id="<%= escape_html(id) %>-query" value="<%= escape_html(query) %>" placeholder="Resource..." maxlength="256">
+  <button type="submit">Search</button>
+  <div data-search-suggestions role="region" aria-label="Search suggestions" hidden>
+    <p data-search-status role="status"></p>
+    <div data-search-preview></div>
+  </div>
+</form>

data/lib/haveapi/views/documentation/search_index.erb

@@ -0,0 +1 @@
+<script type="application/json" data-documentation-search-index><%= documentation_json(key: search_index.key, index: search_index.payload) %></script>

data/lib/haveapi/views/documentation/search_results.erb

@@ -0,0 +1,20 @@
+<section data-search-results aria-label="Search results">
+  <h2>Search results for <%= escape_html(search[:query]) %></h2>
+  <p data-search-status role="status">
+    <% if search[:results].empty? %>
+      No matches. Try another resource, action or parameter name.
+    <% elsif search[:more] %>
+      Showing <%= search[:results].length %> results. More matches are available; refine your search.
+    <% else %>
+      <%= search[:results].length %> <%= search[:results].length == 1 ? 'result' : 'results' %>.
+    <% end %>
+  </p>
+  <ol>
+    <% search[:results].each do |result| %>
+      <li>
+        <a href="<%= escape_html(documentation_search_result_url(result)) %>"><%= escape_html(result[:kind].to_s.capitalize) %>: <code><%= escape_html(documentation_search_result_title(result)) %></code></a>
+        <% documentation_search_result_context(result).each do |context| %><span><%= escape_html(context) %></span><% end %>
+      </li>
+    <% end %>
+  </ol>
+</section>

data/lib/haveapi/views/index.erb

@@ -1,12 +1,10 @@
-<h1>API description</h1>
-<h2>Available versions:</h2>
+<h1>API versions</h1>
 <ul>
   <% @api[:versions].each do |v, info| %>
     <% next if v == :default %>
     <li>
-      <a href="<%= info[:help] %>">Version <%= v.to_s %></a>
+      <a href="<%= escape_html(url(info[:help], false)) %>">Version <%= escape_html(v) %></a>
       <%= '(default)' if v == @api[:default_version] %>
     </li>
   <% end %>
 </ul>
-<h2><a href="/doc">Documentation</a></h2>

data/lib/haveapi/views/main_layout.erb

@@ -2,7 +2,12 @@
 <html>
 <head>
   <meta charset="utf-8">
-  <title>API v<%= @v %> description</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title><%= escape_html(documentation_document_title) %></title>
+  <% if @documentation_ui %>
+  <script src="<%= escape_html(url('/js/documentation.js', false)) %>" data-highlighter-url="<%= escape_html(url('/js/highlighter.js', false)) %>"></script>
+  <link rel="stylesheet" href="<%= escape_html(url('/css/documentation.css', false)) %>">
+  <% else %>
 
   <link rel="stylesheet" href="/css/bootstrap.min.css">
   <script src="/js/jquery-1.11.1.min.js"></script>
@@ -73,16 +78,17 @@
       white-space: pre;
     }
   </style>
+  <% end %>
 </head>
-<body data-spy="scroll" data-target=".table-of-contents">
-<div class="container-fluid">
+<body<% unless @documentation_ui %> data-spy="scroll" data-target=".table-of-contents"<% end %>>
+<div class="<%= @documentation_ui ? 'docs-container' : 'container-fluid' %>">
   <%= yield %>
 
-  <div class="row-fluid">
-    <div class="col-xs-12">
+  <footer class="docs-footer">
+    <div>
       <p class="text-right">Generated by <a href="https://github.com/vpsfreecz/haveapi">HaveAPI</a> v<%= version %></p>
     </div>
-  </div>
+  </footer>
 </div>
 </body>
 </html>

data/lib/haveapi/views/shared_documentation.erb

@@ -0,0 +1,12 @@
+<% if @documentation_page == 'guide' %>
+  <nav aria-label="Breadcrumb">
+    <ol>
+      <li><a href="<%= escape_html(shared_documentation_url) %>">API versions</a></li>
+      <% unless title == 'HaveAPI internals' %>
+        <li><a href="<%= escape_html(shared_documentation_url('doc')) %>">HaveAPI internals</a></li>
+      <% end %>
+      <li aria-current="page"><%= escape_html(title) %></li>
+    </ol>
+  </nav>
+<% end %>
+<%= content %>

data/lib/haveapi/views/shared_sidebar.erb

@@ -0,0 +1,25 @@
+<%= erb :'version_sidebar/brand', locals: {account: documentation_account_context} %>
+<% if (search_options = documentation_search_form_options(id: 'docs-search-sidebar')) %>
+  <%= erb :'documentation/search_form', locals: search_options %>
+<% end %>
+<nav aria-label="Documentation pages">
+  <ul>
+    <li><a href="<%= escape_html(shared_documentation_url) %>"<% if @documentation_page == 'versions' %> aria-current="page"<% end %>>API versions</a></li>
+    <% if (reference = shared_documentation_reference_url) %>
+      <li><a href="<%= escape_html(reference) %>">API reference</a></li>
+      <li><a href="<%= escape_html(shared_documentation_reference_url(page: 'resources')) %>">Resources</a></li>
+    <% end %>
+  </ul>
+</nav>
+<% if @documentation_toc && !@documentation_toc.empty? %>
+  <nav aria-label="Contents" data-action-nav><%= @documentation_toc %></nav>
+<% end %>
+<nav aria-label="Shared documentation">
+  <h2><a href="<%= escape_html(shared_documentation_url('doc')) %>">HaveAPI internals</a></h2>
+  <ul>
+    <li><a href="<%= escape_html(shared_documentation_url('doc/protocol')) %>">Protocol</a></li>
+    <li><a href="<%= escape_html(shared_documentation_url('doc/json-schema')) %>">JSON schema</a></li>
+    <li><a href="<%= escape_html(shared_documentation_url('doc/create-client')) %>">Create a client</a></li>
+    <li><a href="<%= escape_html(shared_documentation_url('doc/client-examples')) %>">Client examples</a></li>
+  </ul>
+</nav>