Apache Mesos
help.hpp
Go to the documentation of this file.
1 // Licensed under the Apache License, Version 2.0 (the "License");
2 // you may not use this file except in compliance with the License.
3 // You may obtain a copy of the License at
4 //
5 // http://www.apache.org/licenses/LICENSE-2.0
6 //
7 // Unless required by applicable law or agreed to in writing, software
8 // distributed under the License is distributed on an "AS IS" BASIS,
9 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
10 // See the License for the specific language governing permissions and
11 // limitations under the License
12 
13 #ifndef __PROCESS_HELP_HPP__
14 #define __PROCESS_HELP_HPP__
15 
16 #include <string>
17 
18 #include <process/future.hpp>
19 #include <process/http.hpp>
20 #include <process/process.hpp>
21 
22 #include <stout/foreach.hpp>
23 #include <stout/json.hpp>
24 #include <stout/option.hpp>
25 #include <stout/preprocessor.hpp>
26 #include <stout/stringify.hpp>
27 #include <stout/strings.hpp>
28 
29 namespace process {
30 
31 // Constructs a Markdown based help "page" for a route with the
32 // following template:
33 //
34 // ### USAGE ###
35 // usage
36 //
37 // ### TL;DR; ###
38 // tldr
39 //
40 // ### DESCRIPTION ###
41 // description
42 //
43 // ### AUTHENTICATION ###
44 // authentication requirements
45 //
46 // ### AUTHORIZATION ###
47 // authorization requirements and granularity
48 //
49 // references
50 //
51 // See the 'USAGE', 'TLDR', 'DESCRIPTION', 'AUTHENTICATION', and
52 // 'REFERENCES' helpers below to more easily construct your help pages.
53 std::string HELP(
54  const std::string& tldr,
55  const Option<std::string>& description = None(),
56  const Option<std::string>& authentication = None(),
57  const Option<std::string>& authorization = None(),
58  const Option<std::string>& references = None());
59 
60 // Helper for single-line usage that puts it in a blockquote as code
61 // and adds a newline.
62 inline std::string USAGE(const std::string& usage)
63 {
64  return "> " + usage + "\n";
65 }
66 
67 
68 // Helper for single-line TL;DR; that adds a newline.
69 inline std::string TLDR(const std::string& tldr)
70 {
71  return tldr + "\n";
72 }
73 
74 
75 template <typename... T>
76 inline std::string DESCRIPTION(T&&... args)
77 {
78  return strings::join("\n", std::forward<T>(args)..., "\n");
79 }
80 
81 
82 // Helper for description of Authentication requirements.
83 inline std::string AUTHENTICATION(bool required)
84 {
85  if (required) {
86  return "This endpoint requires authentication iff HTTP authentication is\n"
87  "enabled.\n";
88  }
89  return "This endpoint does not require authentication.\n";
90 }
91 
92 
93 // Helper for description of Authorization requirements.
94 template <typename... T>
95 inline std::string AUTHORIZATION(T&&... args)
96 {
97  return strings::join("\n", std::forward<T>(args)..., "\n");
98 }
99 
100 
101 template <typename... T>
102 inline std::string REFERENCES(T&&... args)
103 {
104  return strings::join("\n", std::forward<T>(args)..., "\n");
105 }
106 
107 
108 // Help process for serving /help, /help/id, and /help/id/name (see
109 // Help::help below for more information).
110 class Help : public Process<Help>
111 {
112 public:
113  Help(const Option<std::string>& delegate);
114 
115  // Adds 'help' for the route 'name' of the process with the
116  // specified 'id' (i.e., 'http://ip:port/id/name'). It's expected
117  // that 'help' is written using Markdown. When serving help to a
118  // browser the Markdown will be rendered into HTML while a tool like
119  // 'curl' or 'http' will just be given the Markdown directly (thus
120  // making it easy to get help without opening a browser).
121  // NOTE: There is no need to dispatch this directly; this gets
122  // automagically dispatched by 'ProcessBase::route'.
123  void add(const std::string& id,
124  const std::string& name,
125  const Option<std::string>& help);
126 
127  // Remove a previously installed 'help' string for '/id/name'.
128  bool remove(const std::string& id, const std::string& name);
129 
130  // Remove all previously installed 'help' strings for '/id/*'.
131  bool remove(const std::string& id);
132 
133  // Allow the global json function to dump this object to its
134  // canonical JSON representation.
135  friend void json(JSON::ObjectWriter* writer, const Help& help);
136 
137 protected:
138  void initialize() override;
139 
140 private:
141  // Handles the following:
142  //
143  // (1) http://ip:port/help
144  // (2) http://ip:port/help/id
145  // (3) http://ip:port/help/id/name
146  //
147  // Where 'id' and 'name' are replaced with a process ID and route
148  // name respectively. (1) provides a "table of contents" for all
149  // available processes while (2) provides a "table of contents" for
150  // all endpoints associated with a particular process and (3)
151  // provides the help associated with a particular endpoint of a
152  // process.
154 
155  // Helper function to get usage path by process id and endpoint name.
156  std::string getUsagePath(const std::string& id, const std::string& name);
157 
158  // Delegate process name to receive root HTTP requests.
159  const Option<std::string> delegate;
160 
161  std::map<std::string, std::map<std::string, std::string>> helps;
162 };
163 
164 } // namespace process {
165 
166 #endif // __PROCESS_HELP_HPP__
std::string AUTHENTICATION(bool required)
Definition: help.hpp:83
Future< Response > request(const Request &request, bool streamedResponse=false)
Asynchronously sends an HTTP request to the process and returns the HTTP response once the entire res...
std::stringstream & join(std::stringstream &stream, const std::string &separator, T &&...args)
Definition: strings.hpp:307
Definition: http.hpp:533
Try< ResourceStatistics > usage(pid_t pid, bool mem=true, bool cpus=true)
std::string TLDR(const std::string &tldr)
Definition: help.hpp:69
void add(const std::string &id, const std::string &name, const Option< std::string > &help)
Definition: jsonify.hpp:326
Help(const Option< std::string > &delegate)
std::string HELP(const std::string &tldr, const Option< std::string > &description=None(), const Option< std::string > &authentication=None(), const Option< std::string > &authorization=None(), const Option< std::string > &references=None())
std::string REFERENCES(T &&...args)
Definition: help.hpp:102
Definition: none.hpp:27
Definition: help.hpp:110
Definition: executor.hpp:48
std::string USAGE(const std::string &usage)
Definition: help.hpp:62
friend void json(JSON::ObjectWriter *writer, const Help &help)
Definition: process.hpp:505
constexpr const char * name
Definition: shell.hpp:41
std::string AUTHORIZATION(T &&...args)
Definition: help.hpp:95
void initialize() override
Invoked when a process gets spawned.
std::string DESCRIPTION(T &&...args)
Definition: help.hpp:76