GCC Code Coverage Report

Line	Branch	Exec	Source
1			//
2			// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3			// Copyright (c) 2025 Mohammad Nejati
4			//
5			// Distributed under the Boost Software License, Version 1.0. (See accompanying
6			// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7			//
8			// Official repository: https://github.com/cppalliance/http_proto
9			//
10
11			#ifndef BOOST_HTTP_PROTO_SERIALIZER_HPP
12			#define BOOST_HTTP_PROTO_SERIALIZER_HPP
13
14			#include <boost/http_proto/detail/config.hpp>
15			#include <boost/http_proto/detail/workspace.hpp>
16			#include <boost/http_proto/source.hpp>
17
18			#include <boost/buffers/buffer_pair.hpp>
19			#include <boost/core/span.hpp>
20			#include <boost/capy/polystore_fwd.hpp>
21			#include <boost/system/result.hpp>
22
23			#include <type_traits>
24			#include <utility>
25
26			namespace boost {
27			namespace http_proto {
28
29			// Forward declaration
30			class message_base;
31
32			/** A serializer for HTTP/1 messages
33
34			This is used to serialize one or more complete
35			HTTP/1 messages. Each message consists of a
36			required header followed by an optional body.
37
38			Objects of this type operate using an "input area" and an
39			"output area". Callers provide data to the input area
40			using one of the @ref start or @ref start_stream member
41			functions. After input is provided, serialized data
42			becomes available in the serializer's output area in the
43			form of a constant buffer sequence.
44
45			Callers alternate between filling the input area and
46			consuming the output area until all the input has been
47			provided and all the output data has been consumed, or
48			an error occurs.
49
50			After calling @ref start, the caller must ensure that the
51			contents of the associated message are not changed or
52			destroyed until @ref is_done returns true, @ref reset is
53			called, or the serializer is destroyed, otherwise the
54			behavior is undefined.
55			*/
56			class serializer
57			{
58			public:
59			class stream;
60			struct config;
61
62			/** The type used to represent a sequence of
63			constant buffers that refers to the output
64			area.
65			*/
66			using const_buffers_type =
67			boost::span<buffers::const_buffer const>;
68
69			/** Destructor
70			*/
71			BOOST_HTTP_PROTO_DECL
72			~serializer();
73
74			/** Constructor
75			Default-constructed serializers do not reference any implementation;
76			the only valid operations are destruction and assignment.
77			*/
78		3	serializer() = default;
79
80			/** Constructor.
81
82			The states of `other` are transferred
83			to the newly constructed object,
84			which includes the allocated buffer.
85			After construction, the only valid
86			operations on the moved-from object
87			are destruction and assignment.
88
89			Buffer sequences previously obtained
90			using @ref prepare or @ref stream::prepare
91			remain valid.
92
93			@par Postconditions
94			@code
95			other.is_done() == true
96			@endcode
97
98			@par Complexity
99			Constant.
100
101			@param other The serializer to move from.
102			*/
103			BOOST_HTTP_PROTO_DECL
104			serializer(
105			serializer&& other) noexcept;
106
107			/** Assignment.
108			The states of `other` are transferred
109			to this object, which includes the
110			allocated buffer. After assignment,
111			the only valid operations on the
112			moved-from object are destruction and
113			assignment.
114			Buffer sequences previously obtained
115			using @ref prepare or @ref stream::prepare
116			remain valid.
117			@par Complexity
118			Constant.
119			@param other The serializer to move from.
120			@return A reference to this object.
121			*/
122			BOOST_HTTP_PROTO_DECL
123			serializer&
124			operator=(serializer&& other) noexcept;
125
126			/** Constructor.
127
128			Constructs a serializer that uses the @ref
129			config parameters installed on the
130			provided `ctx`.
131
132			The serializer will attempt to allocate
133			the required space on startup, with the
134			amount depending on the @ref config
135			parameters, and will not perform any
136			further allocations, except for Brotli
137			encoder instances, if enabled.
138
139			Depending on which compression algorithms
140			are enabled in the @ref config, the
141			serializer will attempt to access the
142			corresponding encoder services on the same
143			`ctx`.
144
145			@par Example
146			@code
147			serializer sr(ctx);
148			@endcode
149
150			@par Postconditions
151			@code
152			this->is_done() == true
153			@endcode
154
155			@par Complexity
156			Constant.
157
158			@par Exception Safety
159			Calls to allocate may throw.
160
161			@param ctx Context from which the
162			serializer will access registered
163			services. The caller is responsible for
164			ensuring that the provided ctx remains
165			valid for the lifetime of the serializer.
166
167			@see
168			@ref install_serializer_service,
169			@ref config.
170			*/
171			BOOST_HTTP_PROTO_DECL
172			explicit
173			serializer(
174			capy::polystore& ctx);
175
176			/** Reset the serializer for a new message.
177
178			Aborts any ongoing serialization and
179			prepares the serializer to start
180			serialization of a new message.
181			*/
182			BOOST_HTTP_PROTO_DECL
183			void
184			reset() noexcept;
185
186			/** Start serializing a message with an empty body
187
188			This function prepares the serializer to create a message which
189			has an empty body.
190			Ownership of the specified message is not transferred; the caller is
191			responsible for ensuring the lifetime of the object extends until the
192			serializer is done.
193
194			@par Preconditions
195			@code
196			this->is_done() == true
197			@endcode
198
199			@par Postconditions
200			@code
201			this->is_done() == false
202			@endcode
203
204			@par Exception Safety
205			Strong guarantee.
206			Exceptions thrown if there is insufficient internal buffer space
207			to start the operation.
208
209			@throw std::logic_error `this->is_done() == true`.
210
211			@throw std::length_error if there is insufficient internal buffer
212			space to start the operation.
213
214			@param m The request or response headers to serialize.
215
216			@see
217			@ref message_base.
218			*/
219			void
220			BOOST_HTTP_PROTO_DECL
221			start(message_base const& m);
222
223			/** Start serializing a message with a buffer sequence body
224
225			Initializes the serializer with the HTTP start-line and headers from `m`,
226			and the provided `buffers` for reading the message body from.
227
228			Changing the contents of the message after calling this function and
229			before @ref is_done returns `true` results in undefined behavior.
230
231			At least one copy of the specified buffer sequence is maintained until
232			the serializer is done, gets reset, or ios destroyed, after which all
233			of its copies are destroyed. Ownership of the underlying memory is not
234			transferred; the caller must ensure the memory remains valid until the
235			serializer’s copies are destroyed.
236
237			@par Preconditions
238			@code
239			this->is_done() == true
240			@endcode
241
242			@par Postconditions
243			@code
244			this->is_done() == false
245			@endcode
246
247			@par Constraints
248			@code
249			buffers::is_const_buffer_sequence_v<ConstBufferSequence> == true
250			@endcode
251
252			@par Exception Safety
253			Strong guarantee.
254			Exceptions thrown if there is insufficient internal buffer space
255			to start the operation.
256
257			@throw std::logic_error `this->is_done() == true`.
258
259			@throw std::length_error If there is insufficient internal buffer
260			space to start the operation.
261
262			@param m The message to read the HTTP start-line and headers from.
263
264			@param buffers A buffer sequence containing the message body.
265
266			containing the message body data. While
267			the buffers object is copied, ownership of
268			the underlying memory remains with the
269			caller, who must ensure it stays valid
270			until @ref is_done returns `true`.
271
272			@see
273			@ref message_base.
274			*/
275			template<
276			class ConstBufferSequence,
277			class = typename std::enable_if<
278			buffers::is_const_buffer_sequence<
279			ConstBufferSequence>::value>::type
280			>
281			void
282			start(
283			message_base const& m,
284			ConstBufferSequence&& buffers);
285
286			/** Start serializing a message with a @em Source body
287
288			Initializes the serializer with the HTTP start-line and headers from
289			`m`, and constructs a `Source` object to provide the message body.
290
291			Changing the contents of the message
292			after calling this function and before
293			@ref is_done returns `true` results in
294			undefined behavior.
295
296			The serializer destroys Source object when:
297			@li `this->is_done() == true`
298			@li An unrecoverable serialization error occurs
299			@li The serializer is destroyed
300
301			@par Example
302			@code
303			file f("example.zip", file_mode::scan);
304			response.set_payload_size(f.size());
305			serializer.start<file_source>(response, std::move(f));
306			@endcode
307
308			@par Preconditions
309			@code
310			this->is_done() == true
311			@endcode
312
313			@par Postconditions
314			@code
315			this->is_done() == false
316			@endcode
317
318			@par Constraints
319			@code
320			is_source<Source>::value == true
321			@endcode
322
323			@par Exception Safety
324			Strong guarantee.
325			Exceptions thrown if there is insufficient
326			internal buffer space to start the
327			operation.
328
329			@throw std::length_error if there is
330			insufficient internal buffer space to
331			start the operation.
332
333			@param m The message to read the HTTP
334			start-line and headers from.
335
336			@param args Arguments to be passed to the
337			`Source` constructor.
338
339			@return A reference to the constructed Source object.
340
341			@see
342			@ref source,
343			@ref file_source,
344			@ref message_base.
345			*/
346			template<
347			class Source,
348			class... Args,
349			class = typename std::enable_if<
350			is_source<Source>::value>::type>
351			Source&
352			start(
353			message_base const& m,
354			Args&&... args);
355
356			/** Prepare the serializer for a new message using a stream interface.
357
358			Initializes the serializer with the HTTP
359			start-line and headers from `m`, and returns
360			a @ref stream object for writing the body
361			data into the serializer's internal buffer.
362
363			Once the serializer is destroyed, @ref reset
364			is called, or @ref is_done returns true, the
365			only valid operation on the stream is destruction.
366
367			The stream allows inverted control flow: the
368			caller supplies body data to the serializer’s
369			internal buffer while reading from an external
370			source.
371
372			Changing the contents of the message
373			after calling this function and before
374			@ref is_done returns `true` results in
375			undefined behavior.
376
377			@par Example
378			@code
379			serializer::stream st = serializer.start_stream(response);
380			do
381			{
382			if(st.is_open())
383			{
384			std::size_t n = source.read_some(st.prepare());
385
386			if(ec == error::eof)
387			st.close();
388			else
389			st.commit(n);
390			}
391
392			write_some(client, serializer);
393
394			} while(!serializer.is_done());
395			@endcode
396
397			@par Preconditions
398			@code
399			this->is_done() == true
400			@endcode
401
402			@par Postconditions
403			@code
404			this->is_done() == false
405			@endcode
406
407			@par Exception Safety
408			Strong guarantee.
409			Exceptions thrown if there is insufficient
410			internal buffer space to start the
411			operation.
412
413			@throw std::length_error if there is
414			insufficient internal buffer space to
415			start the operation.
416
417			@param m The message to read the HTTP
418			start-line and headers from.
419
420			@return A @ref stream object for writing the body
421			data into the serializer's internal buffer.
422
423			@see
424			@ref stream,
425			@ref message_base.
426			*/
427			BOOST_HTTP_PROTO_DECL
428			stream
429			start_stream(
430			message_base const& m);
431
432			/** Return the output area.
433
434			This function serializes some or all of
435			the message and returns the corresponding
436			output buffers. Afterward, a call to @ref
437			consume is required to report the number
438			of bytes used, if any.
439
440			If the message includes an
441			`Expect: 100-continue` header and the
442			header section of the message has been
443			consumed, the returned result will contain
444			@ref error::expect_100_continue to
445			indicate that the header part of the
446			message is complete. The next call to @ref
447			prepare will produce output.
448
449			When the serializer is used through the
450			@ref stream interface, the result may
451			contain @ref error::need_data to indicate
452			that additional input is required to
453			produce output.
454
455			If a @ref source object is in use and a
456			call to @ref source::read returns an
457			error, the serializer enters a faulted
458			state and propagates the error to the
459			caller. This faulted state can only be
460			cleared by calling @ref reset. This
461			ensures the caller is explicitly aware
462			that the previous message was truncated
463			and that the stream must be terminated.
464
465			@par Preconditions
466			@code
467			this->is_done() == false
468			@endcode
469			No unrecoverable error reported from previous calls.
470
471			@par Exception Safety
472			Strong guarantee.
473			Calls to @ref source::read may throw if in use.
474
475			@throw std::logic_error
476			`this->is_done() == true`.
477
478			@return A result containing @ref
479			const_buffers_type that represents the
480			output area or an error if any occurred.
481
482			@see
483			@ref consume,
484			@ref is_done,
485			@ref const_buffers_type.
486			*/
487			BOOST_HTTP_PROTO_DECL
488			auto
489			prepare() ->
490			system::result<
491			const_buffers_type>;
492
493			/** Consume bytes from the output area.
494
495			This function should be called after one
496			or more bytes contained in the buffers
497			provided in the prior call to @ref prepare
498			have been used.
499
500			After a call to @ref consume, callers
501			should check the return value of @ref
502			is_done to determine if the entire message
503			has been serialized.
504
505			@par Preconditions
506			@code
507			this->is_done() == false
508			@endcode
509
510			@par Exception Safety
511			Strong guarantee.
512
513			@throw std::logic_error
514			`this->is_done() == true`.
515
516			@param n The number of bytes to consume.
517			If `n` is greater than the size of the
518			buffer returned from @ref prepared the
519			entire output sequence is consumed and no
520			error is issued.
521
522			@see
523			@ref prepare,
524			@ref is_done,
525			@ref const_buffers_type.
526			*/
527			BOOST_HTTP_PROTO_DECL
528			void
529			consume(std::size_t n);
530
531			/** Return true if serialization is complete.
532			*/
533			BOOST_HTTP_PROTO_DECL
534			bool
535			is_done() const noexcept;
536
537			private:
538			class impl;
539			class cbs_gen;
540			template<class>
541			class cbs_gen_impl;
542
543			BOOST_HTTP_PROTO_DECL
544			detail::workspace&
545			ws();
546
547			BOOST_HTTP_PROTO_DECL
548			void
549			start_init(
550			message_base const&);
551
552			BOOST_HTTP_PROTO_DECL
553			void
554			start_buffers(
555			message_base const&,
556			cbs_gen&);
557
558			BOOST_HTTP_PROTO_DECL
559			void
560			start_source(
561			message_base const&,
562			source&);
563
564			impl* impl_ = nullptr;
565			};
566
567			/** Serializer configuration settings.
568
569			@see
570			@ref install_serializer_service,
571			@ref serializer.
572			*/
573			struct serializer::config
574			{
575			/** Enable Brotli Content-Encoding.
576
577			Requires `boost::capy::brotli::encode_service` to be
578			installed, otherwise an exception is thrown.
579			*/
580			bool apply_brotli_encoder = false;
581
582			/** Enable Deflate Content-Encoding.
583
584			Requires `boost::zlib::deflate_service` to be
585			installed, otherwise an exception is thrown.
586			*/
587			bool apply_deflate_encoder = false;
588
589			/** Enable Gzip Content-Encoding.
590
591			Requires `boost::zlib::deflate_service` to be
592			installed, otherwise an exception is thrown.
593			*/
594			bool apply_gzip_encoder = false;
595
596			/** Brotli compression quality (0–11).
597
598			Higher values yield better but slower compression.
599			*/
600			std::uint32_t brotli_comp_quality = 5;
601
602			/** Brotli compression window size (10–24).
603
604			Larger windows improve compression but increase
605			memory usage.
606			*/
607			std::uint32_t brotli_comp_window = 18;
608
609			/** Zlib compression level (0–9).
610
611			0 = no compression, 1 = fastest, 9 = best
612			compression.
613			*/
614			int zlib_comp_level = 6;
615
616			/** Zlib window bits (9–15).
617
618			Controls the history buffer size. Larger values
619			improve compression but use more memory.
620			*/
621			int zlib_window_bits = 15;
622
623			/** Zlib memory level (1–9).
624
625			Higher values use more memory, but offer faster
626			and more efficient compression.
627			*/
628			int zlib_mem_level = 8;
629
630			/** Minimum buffer size for payloads (must be > 0). */
631			std::size_t payload_buffer = 8192;
632
633			/** Reserved space for type-erasure storage.
634
635			Used for:
636			@li User-defined @ref source objects.
637			@li User-defined ConstBufferSequence instances.
638			*/
639			std::size_t max_type_erase = 1024;
640			};
641
642			/** Install the serializer service.
643
644			@par Example
645			@code
646			// default configuration settings
647			install_serializer_service(ctx, {});
648
649			serializer sr(ctx);
650			@endcode
651
652			@par Exception Safety
653			Strong guarantee.
654
655			@throw std::invalid_argument If the service is
656			already installed on the context.
657
658			@param ctx Reference to the context on which
659			the service should be installed.
660
661			@param cfg Configuration settings for the
662			serializer.
663
664			@see
665			@ref serializer::config,
666			@ref serializer.
667			*/
668			BOOST_HTTP_PROTO_DECL
669			void
670			install_serializer_service(
671			capy::polystore& ctx,
672			serializer::config const& cfg);
673
674			//------------------------------------------------
675
676			/** Used for streaming body data during serialization.
677
678			Provides an interface for supplying serialized
679			body content from an external source. This
680			object is returned by @ref
681			serializer::start_stream and enables
682			incremental writing of the message body into
683			the serializer's internal buffer.
684
685			The stream supports an inverted control flow
686			model, where the caller pushes body data as
687			needed.
688
689			Valid operations depend on the state of the
690			serializer. Once the serializer is destroyed,
691			reset, or completes, the stream becomes
692			invalid and must only be destroyed.
693
694			@see
695			@ref serializer::start_stream
696			*/
697			class serializer::stream
698			{
699			public:
700			/** The type used to represent a sequence
701			of mutable buffers.
702			*/
703			using mutable_buffers_type =
704			buffers::mutable_buffer_pair;
705
706			/** Constructor.
707
708			A default-constructed stream is
709			considered closed.
710
711			@par Postconditions
712			@code
713			this->is_open() == false
714			@endcode
715			*/
716			stream() noexcept = default;
717
718			/** Constructor.
719
720			After construction, the moved-from
721			object is as if default-constructed.
722
723			@par Postconditions
724			@code
725			other->is_open() == false
726			@endcode
727
728			@param other The object to move from.
729			*/
730			stream(stream&& other) noexcept
731			: impl_(other.impl_)
732			{
733			other.impl_ = nullptr;
734			}
735
736			/** Move assignment.
737
738			After assignment, the moved-from
739			object is as if default-constructed.
740
741			@par Postconditions
742			@code
743			other->is_open() == false
744			@endcode
745
746			@param other The object to assign from.
747			@return A reference to this object.
748			*/
749			stream&
750			operator=(stream&& other) noexcept
751			{
752			std::swap(impl_, other.impl_);
753			return *this;
754			}
755
756			/** Return true if the stream is open.
757			*/
758			bool
759		5046	is_open() const noexcept
760			{
761		5046	return impl_ != nullptr;
762			}
763
764			/** Return the available capacity.
765
766			@par Preconditions
767			@code
768			this->is_open() == true
769			@endcode
770
771			@par Exception Safety
772			Strong guarantee.
773
774			@throw std::logic_error
775			`this->is_open() == false`.
776			*/
777			BOOST_HTTP_PROTO_DECL
778			std::size_t
779			capacity() const;
780
781			/** Prepare a buffer for writing.
782
783			Retuns a mutable buffer sequence representing
784			the writable bytes. Use @ref commit to make the
785			written data available to the serializer.
786
787			All buffer sequences previously obtained
788			using @ref prepare are invalidated.
789
790			@par Preconditions
791			@code
792			this->is_open() == true && n <= this->capacity()
793			@endcode
794
795			@par Exception Safety
796			Strong guarantee.
797
798			@return An instance of @ref mutable_buffers_type
799			the underlying memory is owned by the serializer.
800
801			@throw std::logic_error
802			`this->is_open() == false`
803
804			@see
805			@ref commit,
806			@ref capacity.
807			*/
808			BOOST_HTTP_PROTO_DECL
809			mutable_buffers_type
810			prepare();
811
812			/** Commit data to the serializer.
813
814			Makes `n` bytes available to the serializer.
815
816			All buffer sequences previously obtained
817			using @ref prepare are invalidated.
818
819			@par Preconditions
820			@code
821			this->is_open() == true && n <= this->capacity()
822			@endcode
823
824			@par Exception Safety
825			Strong guarantee.
826			Exceptions thrown on invalid input.
827
828			@param n The number of bytes to append.
829
830			@throw std::invalid_argument
831			`n > this->capacity()`
832
833			@throw std::logic_error
834			`this->is_open() == false`
835
836			@see
837			@ref prepare,
838			@ref capacity.
839			*/
840			BOOST_HTTP_PROTO_DECL
841			void
842			commit(std::size_t n);
843
844			/** Close the stream if open.
845
846			Closes the stream and
847			notifies the serializer that the
848			message body has ended.
849
850			If the stream is already closed this
851			call has no effect.
852
853			@par Postconditions
854			@code
855			this->is_open() == false
856			@endcode
857			*/
858			BOOST_HTTP_PROTO_DECL
859			void
860			close() noexcept;
861
862			/** Destructor.
863
864			Closes the stream if open.
865			*/
866		24	~stream()
867			{
868		24	close();
869		24	}
870
871			private:
872			friend class serializer;
873
874			explicit
875		23	stream(serializer::impl* impl) noexcept
876		23	: impl_(impl)
877			{
878		23	}
879
880			serializer::impl* impl_ = nullptr;
881			};
882
883			} // http_proto
884			} // boost
885
886			#include <boost/http_proto/impl/serializer.hpp>
887
888			#endif
889