Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include <string>
       4             : 
       5             : #include "envoy/buffer/buffer.h"
       6             : #include "envoy/common/pure.h"
       7             : #include "envoy/http/header_map.h"
       8             : #include "envoy/server/admin.h"
       9             : 
      10             : #include "absl/strings/string_view.h"
      11             : 
      12             : namespace Envoy {
      13             : namespace Server {
      14             : 
      15             : class AdminHtmlUtil {
      16             : public:
      17             :   // Overridable mechanism to provide resources for constructing HTML resources.
      18             :   // The default implementation uses files that were imported into C++ constants
      19             :   // via the build system in target //source/server/admin/html:generate_admin_html.
      20             : 
      21             :   // The override can be used to facilitate interactive debugging by dynamically
      22             :   // reading resource contents from the file system.
      23             :   //
      24             :   // Note: rather than creating a new interface here, we could have re-used
      25             :   // Filesystem::Instance, however the current implementation of MemFileSystem
      26             :   // is intended for tests, and it's simpler to create a much leaner new API
      27             :   // rather than make a production-ready version of the full memory-based
      28             :   // filesystem.
      29             :   class ResourceProvider {
      30             :   public:
      31           0 :     virtual ~ResourceProvider() = default;
      32             : 
      33             :     /**
      34             :      * @param buf a buffer that may be used by the implementation to prepare the return value.
      35             :      * @return resource contents
      36             :      */
      37             :     virtual absl::string_view getResource(absl::string_view resource_name, std::string& buf) PURE;
      38             :   };
      39             : 
      40             :   /**
      41             :    * @param buf a buffer that may be used by the implementation to prepare the return value.
      42             :    * @return resource contents
      43             :    */
      44             :   static absl::string_view getResource(absl::string_view resource_name, std::string& buf);
      45             : 
      46             :   /**
      47             :    * Renders the beginning of the help-table into the response buffer provided
      48             :    * in the constructor.
      49             :    */
      50             :   static void renderTableBegin(Buffer::Instance&);
      51             : 
      52             :   /**
      53             :    * Renders the end of the help-table into the response buffer provided in the
      54             :    * constructor.
      55             :    */
      56             :   static void renderTableEnd(Buffer::Instance&);
      57             : 
      58             :   /**
      59             :    * Renders the head of an admin HTML page. This provides shared styling
      60             :    * between the admin home page and endpoints with HTML support. This
      61             :    * must be matched with a call to finalize().
      62             :    */
      63             :   static void renderHead(Http::ResponseHeaderMap& response_headers, Buffer::Instance& response);
      64             : 
      65             :   /**
      66             :    * Renders the end of a web page that has had renderHead called on it.
      67             :    */
      68             :   static void finalize(Buffer::Instance& response);
      69             : 
      70             :   /**
      71             :    * Renders a table row for a URL endpoint, including the name of the endpoint,
      72             :    * entries for each parameter, and help text.
      73             :    *
      74             :    * This must be called after renderTableBegin and before renderTableEnd. Any
      75             :    * number of URL Handlers can be rendered.
      76             :    *
      77             :    * @param response buffer to write the HTML for the handler
      78             :    * @param handler the URL handler.
      79             :    * @param query query params
      80             :    * @param index url handler's index.
      81             :    * @param submit_on_change by default, editing parameters does not cause a
      82             :    *        form-submit -- you have to click on the link or button first. This
      83             :    *        is useful for the admin home page which lays out all the parameters
      84             :    *        so users can tweak them before submitting. Setting to true, the form
      85             :    *        auto-submits when any parameters change, and does not have its own
      86             :    *        explicit submit button. This is used to enable the user to adjust
      87             :    *        query-parameters while visiting an html-rendered endpoint.
      88             :    * @param active indicates
      89             :    */
      90             :   static void renderEndpointTableRow(Buffer::Instance& response, const Admin::UrlHandler& handler,
      91             :                                      OptRef<const Http::Utility::QueryParamsMulti> query, int index,
      92             :                                      bool submit_on_change, bool active);
      93             : 
      94             :   /**
      95             :    * By default, JS, HTML, and CSS files are compiled into the binary. To make it
      96             :    * faster to iterate while debugging, You can override the resource provider to
      97             :    * load these assets from the file-system every time they are rendered.
      98             :    *
      99             :    * This function is thread hostile; it must be called before threads are
     100             :    * started up, e.g. while parsing arguments in main().
     101             :    *
     102             :    * The previous resource provider is provided to make unit-testing easier.
     103             :    *
     104             :    * @return the previous resource provider
     105             :    */
     106             :   static std::unique_ptr<ResourceProvider>
     107             :   setResourceProvider(std::unique_ptr<ResourceProvider> resource_provider);
     108             : 
     109             : private:
     110             :   static void renderHandlerParam(Buffer::Instance& response, absl::string_view id,
     111             :                                  absl::string_view name, absl::string_view path,
     112             :                                  Admin::ParamDescriptor::Type type,
     113             :                                  OptRef<const Http::Utility::QueryParamsMulti> query,
     114             :                                  const std::vector<absl::string_view>& enum_choices,
     115             :                                  bool submit_on_change);
     116             : };
     117             : 
     118             : } // namespace Server
     119             : } // namespace Envoy