2 * nghttp2 - HTTP/2 C Library
4 * Copyright (c) 2015 Tatsuhiro Tsujikawa
6 * Permission is hereby granted, free of charge, to any person obtaining
7 * a copy of this software and associated documentation files (the
8 * "Software"), to deal in the Software without restriction, including
9 * without limitation the rights to use, copy, modify, merge, publish,
10 * distribute, sublicense, and/or sell copies of the Software, and to
11 * permit persons to whom the Software is furnished to do so, subject to
12 * the following conditions:
14 * The above copyright notice and this permission notice shall be
15 * included in all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
21 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
22 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
23 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25 #ifndef ASIO_HTTP2_SERVER_H
26 #define ASIO_HTTP2_SERVER_H
28 #include <nghttp2/asio_http2.h>
32 namespace asio_http2 {
41 // Application must not call this directly.
45 // Returns request header fields. The pusedo header fields, which
46 // start with colon (:), are exluced from this list.
47 const header_map &header() const;
49 // Returns method (e.g., GET).
50 const std::string &method() const;
52 // Returns request URI, split into components.
53 const uri_ref &uri() const;
55 // Sets callback which is invoked when chunk of request body is
57 void on_data(data_cb cb) const;
59 // Application must not call this directly.
60 request_impl &impl() const;
63 std::unique_ptr<request_impl> impl_;
68 // Application must not call this directly.
72 // Write response header using |status_code| (e.g., 200) and
73 // additional header fields in |h|.
74 void write_head(unsigned int status_code, header_map h = header_map{}) const;
76 // Sends |data| as request body. No further call of end() is
78 void end(std::string data = "") const;
80 // Sets callback as a generator of the response body. No further
81 // call of end() is allowed.
82 void end(generator_cb cb) const;
84 // Write trailer part. This must be called after setting both
85 // NGHTTP2_DATA_FLAG_EOF and NGHTTP2_DATA_FLAG_NO_END_STREAM set in
86 // *data_flag parameter in generator_cb passed to end() function.
87 void write_trailer(header_map h) const;
89 // Sets callback which is invoked when this request and response are
90 // finished. After the invocation of this callback, the application
91 // must not access request and response object.
92 void on_close(close_cb cb) const;
94 // Cancels this request and response with given error code.
95 void cancel(uint32_t error_code = NGHTTP2_INTERNAL_ERROR) const;
97 // Resumes deferred response.
100 // Pushes resource denoted by |raw_path_query| using |method|. The
101 // additional header fields can be given in |h|. This function
102 // returns pointer to response object for promised stream, otherwise
103 // nullptr and error code is filled in |ec|. Be aware that the
104 // header field name given in |h| must be lower-cased.
105 const response *push(boost::system::error_code &ec, std::string method,
106 std::string raw_path_query,
107 header_map h = header_map{}) const;
109 // Returns status code.
110 unsigned int status_code() const;
112 // Returns boost::asio::io_service this response is running on.
113 boost::asio::io_service &io_service() const;
115 // Application must not call this directly.
116 response_impl &impl() const;
119 std::unique_ptr<response_impl> impl_;
122 // This is so called request callback. Called every time request is
123 // received. The life time of |request| and |response| objects end
124 // when callback set by response::on_close() is called. After that,
125 // the application must not access to those objects.
126 typedef std::function<void(const request &, const response &)> request_cb;
135 http2(http2 &&other) noexcept;
136 http2 &operator=(http2 &&other) noexcept;
138 // Starts listening connection on given address and port and serves
139 // incoming requests in cleartext TCP connection. If |asynchronous|
140 // is false, this function blocks forever unless there is an error.
141 // If it is true, after server has started, this function returns
142 // immediately, and the caller should call join() to shutdown server
144 boost::system::error_code listen_and_serve(boost::system::error_code &ec,
145 const std::string &address,
146 const std::string &port,
147 bool asynchronous = false);
149 // Starts listening connection on given address and port and serves
150 // incoming requests in SSL/TLS encrypted connection. For
151 // |asynchronous| parameter, see cleartext version
152 // |listen_and_serve|.
153 boost::system::error_code
154 listen_and_serve(boost::system::error_code &ec,
155 boost::asio::ssl::context &tls_context,
156 const std::string &address, const std::string &port,
157 bool asynchronous = false);
159 // Registers request handler |cb| with path pattern |pattern|. This
160 // function will fail and returns false if same pattern has been
161 // already registered or |pattern| is empty string. Otherwise
162 // returns true. The pattern match rule is the same as
163 // net/http/ServeMux in golang. Quoted from golang manual
164 // (http://golang.org/pkg/net/http/#ServeMux):
166 // Patterns name fixed, rooted paths, like "/favicon.ico", or
167 // rooted subtrees, like "/images/" (note the trailing
168 // slash). Longer patterns take precedence over shorter ones, so
169 // that if there are handlers registered for both "/images/" and
170 // "/images/thumbnails/", the latter handler will be called for
171 // paths beginning "/images/thumbnails/" and the former will
172 // receive requests for any other paths in the "/images/" subtree.
174 // Note that since a pattern ending in a slash names a rooted
175 // subtree, the pattern "/" matches all paths not matched by other
176 // registered patterns, not just the URL with Path == "/".
178 // Patterns may optionally begin with a host name, restricting
179 // matches to URLs on that host only. Host-specific patterns take
180 // precedence over general patterns, so that a handler might
181 // register for the two patterns "/codesearch" and
182 // "codesearch.google.com/" without also taking over requests for
183 // "http://www.google.com/".
185 // Just like ServeMux in golang, URL request path is sanitized and
186 // if they contains . or .. elements, they are redirected to an
187 // equivalent .- and ..-free URL.
188 bool handle(std::string pattern, request_cb cb);
190 // Sets number of native threads to handle incoming HTTP request.
192 void num_threads(size_t num_threads);
194 // Sets the maximum length to which the queue of pending
196 void backlog(int backlog);
198 // Gracefully stop http2 server
201 // Join on http2 server and wait for it to fully stop
205 std::unique_ptr<http2_impl> impl_;
208 // Configures |tls_context| for server use. This function sets couple
209 // of OpenSSL options (disables SSLv2 and SSLv3 and compression) and
210 // enables ECDHE ciphers. NPN callback is also configured.
211 boost::system::error_code
212 configure_tls_context_easy(boost::system::error_code &ec,
213 boost::asio::ssl::context &tls_context);
215 // Returns request handler to do redirect to |uri| using
216 // |status_code|. The |uri| appears in "location" header field as is.
217 request_cb redirect_handler(int status_code, std::string uri);
219 // Returns request handler to reply with given |status_code| and HTML
220 // including message about status code.
221 request_cb status_handler(int status_code);
223 } // namespace server
225 } // namespace asio_http2
227 } // namespace nghttp2
229 #endif // ASIO_HTTP2_SERVER_H