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/beast2
8			//
9
10			#ifndef BOOST_BEAST2_SERVER_ROUTER_STATE_HPP
11			#define BOOST_BEAST2_SERVER_ROUTER_STATE_HPP
12
13			#include <boost/beast2/detail/config.hpp>
14			#include <boost/beast2/detail/except.hpp>
15			#include <boost/system/error_code.hpp>
16			#include <boost/http_proto/method.hpp>
17			#include <boost/core/detail/string_view.hpp>
18			#include <string>
19			#include <type_traits>
20
21			namespace boost {
22			namespace beast2 {
23
24			/** The result type returned by a route handler.
25
26			Route handlers use this type to report errors that prevent
27			normal processing. A handler must never return a non-failing
28			(i.e. `ec.failed() == false`) value. Returning a default-constructed
29			`system::error_code` is disallowed; handlers that complete
30			successfully must instead return a valid @ref route result.
31			*/
32			using route_result = system::error_code;
33
34			/** Route handler return values
35
36			These values determine how the caller proceeds after invoking
37			a route handler. Each enumerator represents a distinct control
38			action�whether the request was handled, should continue to the
39			next route, transfers ownership of the session, or signals that
40			the connection should be closed.
41			*/
42			enum class route
43			{
44			/** The handler requests that the connection be closed.
45
46			No further requests will be processed. The caller should
47			close the connection once the current response, if any,
48			has been sent.
49			*/
50			close = 1,
51
52			/** The handler completed the request.
53
54			The response has been fully transmitted, and no further
55			handlers or routes will be invoked. The caller should continue
56			by either reading the next request on a persistent connection
57			or closing the session if it is not keep-alive.
58			*/
59			complete,
60
61			/** The handler detached from the session.
62
63			Ownership of the session or stream has been transferred to
64			the handler. The caller will not perform further I/O or manage
65			the connection after this return value.
66			*/
67			detach,
68
69			/** The handler declined to process the request.
70
71			The handler chose not to generate a response. The caller
72			continues invoking the remaining handlers in the same route
73			until one returns @ref send. If none do, the caller proceeds
74			to evaluate the next matching route.
75
76			This value is returned by @ref basic_router::dispatch if no
77			handlers in any route handle the request.
78			*/
79			next,
80
81			/** The handler declined the current route.
82
83			The handler wishes to skip any remaining handlers in the
84			current route and move on to the next matching route. The
85			caller stops invoking handlers in this route and resumes
86			evaluation with the next candidate route.
87			*/
88			next_route,
89
90			/** The request was handled.
91
92			The route handler processed the request and prepared
93			the response serializer. The caller will send the response
94			before reading the next request or closing the connection.
95			*/
96			send
97			};
98
99			//------------------------------------------------
100
101			} // beast2
102			namespace system {
103			template<>
104			struct is_error_code_enum<
105			::boost::beast2::route>
106			{
107			static bool const value = true;
108			};
109			} // system
110			namespace beast2 {
111
112			namespace detail {
113			struct BOOST_SYMBOL_VISIBLE route_cat_type
114			: system::error_category
115			{
116			BOOST_BEAST2_DECL const char* name(
117			) const noexcept override;
118			BOOST_BEAST2_DECL std::string message(
119			int) const override;
120			BOOST_BEAST2_DECL char const* message(
121			int, char*, std::size_t
122			) const noexcept override;
123		1966	bool failed( int ) const noexcept override
124		1966	{ return false; }
125		3	BOOST_SYSTEM_CONSTEXPR route_cat_type()
126		3	: error_category(0x51c90d393754ecdf )
127			{
128		3	}
129			};
130			BOOST_BEAST2_DECL extern route_cat_type route_cat;
131			} // detail
132
133			inline
134			BOOST_SYSTEM_CONSTEXPR
135			system::error_code
136		1966	make_error_code(route ev) noexcept
137			{
138			return system::error_code{static_cast<
139			std::underlying_type<route>::type>(ev),
140		1966	detail::route_cat};
141			}
142
143			//------------------------------------------------
144
145			class resumer;
146
147			/** Function to detach a route handler from its session
148
149			This holds an reference to an implementation
150			which detaches the handler from its session.
151			*/
152			class detacher
153			{
154			public:
155			/** Base class of the implementation
156			*/
157			struct owner
158			{
159			virtual resumer do_detach() = 0;
160			virtual void do_resume(route_result const&) = 0;
161			};
162
163		2	detacher() = default;
164			detacher(detacher const&) = default;
165			detacher& operator=(detacher const&) = default;
166
167			explicit
168		✗	detacher(
169			owner& who) noexcept
170		✗	: p_(&who)
171			{
172		✗	}
173
174			/** Detach and invoke the given function
175
176			The function will be invoked with this equivalent signature:
177			@code
178			void( resumer );
179			@endcode
180
181			@return A @ref route_result equal to @ref route::detach
182			*/
183			template<class F>
184			route_result
185			operator()(F&& f);
186
187			private:
188			friend resumer;
189			owner* p_ = nullptr;
190			};
191
192			//------------------------------------------------
193
194			/** Function to resume a route handler's session
195
196			This holds a reference to an implementation
197			which resumes the handler's session. The resume
198			function is returned by calling @ref detach.
199			*/
200			class resumer
201			{
202			public:
203			/** Constructor
204
205			Default constructed resume functions will
206			be empty. Invoking an empty resume function
207			yields undefined behavior.
208			*/
209			resumer() = default;
210
211			/** Constructor
212
213			Copies of resume functions behave the same
214			as the original
215			*/
216			resumer(resumer const&) = default;
217
218			/** Assignment
219
220			Copies of resume functions behave the same
221			as the original
222			*/
223			resumer& operator=(resumer const&) = default;
224
225			/** Constructor
226			*/
227			explicit
228		✗	resumer(
229			detacher::owner& who) noexcept
230		✗	: p_(&who)
231			{
232		✗	}
233
234			/** Resume the session
235
236			A session is resumed as if the detached
237			handler returned the error code in `ec`.
238
239			@param ec The error code to resume with.
240			*/
241			void operator()(
242			system::error_code const& ec = {}) const
243			{
244			p_->do_resume(ec);
245			}
246
247			private:
248			detacher::owner* p_ = nullptr;
249			};
250
251			template<class F>
252			auto
253			detacher::
254			operator()(F&& f) ->
255			route_result
256			{
257			if(! p_)
258			detail::throw_logic_error();
259			std::forward<F>(f)(p_->do_detach());
260			return route::detach;
261			}
262
263			//------------------------------------------------
264
265			namespace detail {
266			class any_router;
267			} // detail
268			template<class, class>
269			class basic_router;
270
271			/** Base class for request objects
272
273			This is a required public base for any `Request`
274			type used with @ref basic_router.
275			*/
276			class basic_request
277			{
278			public:
279			/** The mount path of the current router
280
281			This is the portion of the request path
282			which was matched to select the handler.
283			The remaining portion is available in
284			@ref path.
285			*/
286			core::string_view base_path;
287
288			/** The current pathname, relative to the base path
289			*/
290			core::string_view path;
291
292			private:
293			friend class detail::any_router;
294			struct match_result;
295			http_proto::method verb_ =
296			http_proto::method::unknown;
297			std::string verb_str_;
298			std::string decoded_path_;
299			bool addedSlash_ = false;
300			bool case_sensitive = false;
301			bool strict = false;
302			};
303
304			//-----------------------------------------------
305
306			/** Base class for response objects
307
308			This is a required public base for any `Response`
309			type used with @ref basic_router.
310			*/
311			class basic_response
312			{
313			private:
314			friend class detail::any_router;
315			template<class, class>
316			friend class basic_router;
317
318			std::size_t pos_ = 0;
319			std::size_t resume_ = 0;
320			system::error_code ec_;
321			unsigned int opt_ = 0;
322			};
323
324			} // beast2
325			} // boost
326
327			#endif
328