GCC Code Coverage Report

Line	Branch	Exec	Source
1			//
2			// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)
3			//
4			// Distributed under the Boost Software License, Version 1.0. (See accompanying
5			// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6			//
7			// Official repository: https://github.com/cppalliance/http_proto
8			//
9
10			#ifndef BOOST_HTTP_PROTO_SERVER_ROUTER_TYPES_HPP
11			#define BOOST_HTTP_PROTO_SERVER_ROUTER_TYPES_HPP
12
13			#include <boost/http_proto/detail/config.hpp>
14			#include <boost/http_proto/method.hpp>
15			#include <boost/http_proto/detail/except.hpp>
16			#include <boost/core/detail/string_view.hpp>
17			#include <boost/system/error_code.hpp>
18			#include <exception>
19			#include <string>
20			#include <type_traits>
21
22			namespace boost {
23			namespace http_proto {
24
25			/** The result type returned by a route handler.
26
27			Route handlers use this type to report errors that prevent
28			normal processing. A handler must never return a non-failing
29			(i.e. `ec.failed() == false`) value. Returning a default-constructed
30			`system::error_code` is disallowed; handlers that complete
31			successfully must instead return a valid @ref route result.
32			*/
33			using route_result = system::error_code;
34
35			/** Route handler return values
36
37			These values determine how the caller proceeds after invoking
38			a route handler. Each enumerator represents a distinct control
39			action�whether the request was handled, should continue to the
40			next route, transfers ownership of the session, or signals that
41			the connection should be closed.
42			*/
43			enum class route
44			{
45			/** The handler requests that the connection be closed.
46
47			No further requests will be processed. The caller should
48			close the connection once the current response, if any,
49			has been sent.
50			*/
51			close = 1,
52
53			/** The handler completed the request.
54
55			The response has been fully transmitted, and no further
56			handlers or routes will be invoked. The caller should continue
57			by either reading the next request on a persistent connection
58			or closing the session if it is not keep-alive.
59			*/
60			complete,
61
62			/** The handler is suspending the route.
63
64			When the handler returns this value, the router is placed into
65			a suspended state which can later be reactivated by invoking
66			@ref basic_router::resume. Depending on the implementation,
67			this might detach the handler from the session until it is
68			resumed.
69			*/
70			suspend,
71
72			/** The handler declined to process the request.
73
74			The handler chose not to generate a response. The caller
75			continues invoking the remaining handlers in the same route
76			until one returns @ref send. If none do, the caller proceeds
77			to evaluate the next matching route.
78
79			This value is returned by @ref basic_router::dispatch if no
80			handlers in any route handle the request.
81			*/
82			next,
83
84			/** The handler declined the current route.
85
86			The handler wishes to skip any remaining handlers in the
87			current route and move on to the next matching route. The
88			caller stops invoking handlers in this route and resumes
89			evaluation with the next candidate route.
90			*/
91			next_route,
92
93			/** The request was handled.
94
95			The route handler processed the request and prepared
96			the response serializer. The caller will send the response
97			before reading the next request or closing the connection.
98			*/
99			send
100			};
101
102			//------------------------------------------------
103
104			} // http_proto
105			namespace system {
106			template<>
107			struct is_error_code_enum<
108			::boost::http_proto::route>
109			{
110			static bool const value = true;
111			};
112			} // system
113			namespace http_proto {
114
115			namespace detail {
116			struct BOOST_HTTP_PROTO_SYMBOL_VISIBLE route_cat_type
117			: system::error_category
118			{
119			BOOST_HTTP_PROTO_DECL const char* name() const noexcept override;
120			BOOST_HTTP_PROTO_DECL std::string message(int) const override;
121			BOOST_HTTP_PROTO_DECL char const* message(
122			int, char*, std::size_t) const noexcept override;
123		43	BOOST_SYSTEM_CONSTEXPR route_cat_type()
124		43	: error_category(0x51c90d393754ecdf )
125			{
126		43	}
127			};
128			BOOST_HTTP_PROTO_DECL extern route_cat_type route_cat;
129			} // detail
130
131			inline
132			BOOST_SYSTEM_CONSTEXPR
133			system::error_code
134		2357	make_error_code(route ev) noexcept
135			{
136			return system::error_code{static_cast<
137			std::underlying_type<route>::type>(ev),
138		2357	detail::route_cat};
139			}
140
141			/** Return true if `rv` is a route result.
142
143			A @ref route_result can hold any error code,
144			and this function returns `true` only if `rv`
145			holds a value from the @ref route enumeration.
146			*/
147		223	inline bool is_route_result(
148			route_result rv) noexcept
149			{
150		223	return &rv.category() == &detail::route_cat;
151			}
152
153			//------------------------------------------------
154
155			class resumer;
156
157			/** Function to suspend a route handler from its session
158
159			This holds an reference to an implementation
160			which suspends the router which dispatched the handler.
161			*/
162			class suspender
163			{
164			public:
165			/** Base class of the implementation
166			*/
167			struct BOOST_HTTP_PROTO_SYMBOL_VISIBLE
168			owner
169			{
170			BOOST_HTTP_PROTO_DECL
171			virtual resumer do_suspend();
172			virtual void do_resume(route_result const&) = 0;
173			virtual void do_resume(std::exception_ptr) = 0;
174			};
175
176		1	suspender() = default;
177			suspender(suspender const&) = default;
178			suspender& operator=(suspender const&) = default;
179
180			explicit
181			suspender(
182			owner& who) noexcept
183			: p_(&who)
184			{
185			}
186
187			/** Suspend and invoke the given function
188
189			The function will be invoked with this equivalent signature:
190			@code
191			void( resumer );
192			@endcode
193
194			@return A @ref route_result equal to @ref route::suspend
195			*/
196			template<class F>
197			route_result
198			operator()(F&& f);
199
200			private:
201			friend resumer;
202			// Clang doesn't consider uninstantiated templates
203			// when checking for unused private fields.
204			owner* p_
205			#if defined(__clang__)
206			__attribute__((unused))
207			#endif
208			= nullptr;
209			};
210
211			//------------------------------------------------
212
213			/** Function to resume a suspended route.
214
215			This holds a reference to an implementation which resumes the handler's
216			session. The resume function is typically obtained at the time the
217			route is suspended.
218			*/
219			class resumer
220			{
221			public:
222			/** Constructor
223
224			Default constructed resume functions will
225			be empty. An exception is thrown when
226			attempting to invoke an empty object.
227			*/
228			resumer() = default;
229
230			/** Constructor
231
232			Copies of resume functions behave the same
233			as the original
234			*/
235			resumer(resumer const&) = default;
236
237			/** Assignment
238
239			Copies of resume functions behave the same
240			as the original
241			*/
242			resumer& operator=(resumer const&) = default;
243
244			/** Constructor
245			*/
246			explicit
247			resumer(
248			suspender::owner& who) noexcept
249			: p_(&who)
250			{
251			}
252
253			/** Resume the session
254
255			When a session is resumed, routing continues as if the handler
256			had returned the @ref route_result contained in @p rv.
257
258			@param rv The route result to resume with.
259
260			@throw std::invalid_argument If the object is empty.
261			*/
262			void operator()(
263			route_result const& rv) const
264			{
265			if(! p_)
266			detail::throw_invalid_argument();
267			p_->do_resume(rv);
268			}
269
270			/** Resume the session with an exception
271
272			When a session is resumed with an exception, the exception
273			is propagated through the router's error handling mechanism.
274
275			@param ep The exception to propagate.
276
277			@throw std::invalid_argument If the object is empty.
278			*/
279			void operator()(
280			std::exception_ptr ep) const
281			{
282			if(! p_)
283			detail::throw_invalid_argument();
284			p_->do_resume(ep);
285			}
286
287			private:
288			suspender::owner* p_
289			#if defined(__clang__)
290			__attribute__((unused))
291			#endif
292			= nullptr;
293			};
294
295			template<class F>
296			auto
297			suspender::
298			operator()(F&& f) ->
299			route_result
300			{
301			if(! p_)
302			detail::throw_logic_error();
303			std::forward<F>(f)(p_->do_suspend());
304			return route::suspend;
305			}
306
307			//------------------------------------------------
308
309			namespace detail {
310			class any_router;
311			} // detail
312			template<class>
313			class basic_router;
314
315			/** Base class for request objects
316
317			This is a required public base for any `Request`
318			type used with @ref basic_router.
319			*/
320			class route_params_base
321			{
322			public:
323			/** Return true if the request method matches `m`
324			*/
325		2	bool is_method(
326			http_proto::method m) const noexcept
327			{
328		2	return verb_ == m;
329			}
330
331			/** Return true if the request method matches `s`
332			*/
333			BOOST_HTTP_PROTO_DECL
334			bool is_method(
335			core::string_view s) const noexcept;
336
337			/** The mount path of the current router
338
339			This is the portion of the request path
340			which was matched to select the handler.
341			The remaining portion is available in
342			@ref path.
343			*/
344			core::string_view base_path;
345
346			/** The current pathname, relative to the base path
347			*/
348			core::string_view path;
349
350			private:
351			friend class /*detail::*/any_router;
352			template<class>
353			friend class basic_router;
354			struct match_result;
355			route_params_base& operator=(
356			route_params_base const&) = delete;
357
358			std::string verb_str_;
359			std::string decoded_path_;
360			system::error_code ec_;
361			std::exception_ptr ep_;
362			std::size_t pos_ = 0;
363			std::size_t resume_ = 0;
364			http_proto::method verb_ =
365			http_proto::method::unknown;
366			bool addedSlash_ = false;
367			bool case_sensitive = false;
368			bool strict = false;
369			};
370
371			} // http_proto
372			} // boost
373
374			#endif
375