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			/** Return true if headers have been set.
538
539			Returns `true` if @ref set_headers has been
540			called and no @ref start or @ref start_stream
541			function has been called since. This indicates
542			that the serializer is ready to begin
543			serialization with a body style.
544
545			@see
546			@ref set_headers,
547			@ref is_done.
548			*/
549			BOOST_HTTP_PROTO_DECL
550			bool
551			is_headers_set() const noexcept;
552
553			/** Set the message headers for serialization.
554
555			This function prepares the serializer with the
556			HTTP start-line and headers from `m`. After
557			calling this function, one of the @ref start
558			or @ref start_stream overloads that do not
559			take a message parameter must be called to
560			begin serialization.
561
562			Changing the contents of the message after
563			calling this function and before @ref is_done
564			returns `true` results in undefined behavior.
565
566			@par Preconditions
567			@code
568			this->is_done() == true
569			@endcode
570
571			@par Exception Safety
572			Strong guarantee.
573
574			@throw std::logic_error `this->is_done() == false`.
575
576			@param m The request or response headers to serialize.
577
578			@see
579			@ref message_base.
580			*/
581			BOOST_HTTP_PROTO_DECL
582			void
583			set_headers(message_base const& m);
584
585			/** Start serializing a message with an empty body.
586
587			This overload requires @ref set_headers to have
588			been called first.
589
590			@par Preconditions
591			@ref set_headers has been called and no @ref start
592			or @ref start_stream function has been called since.
593
594			@par Postconditions
595			@code
596			this->is_done() == false
597			@endcode
598
599			@par Exception Safety
600			Strong guarantee.
601
602			@throw std::logic_error if @ref set_headers was not called.
603
604			@throw std::length_error if there is insufficient internal buffer
605			space to start the operation.
606
607			@see
608			@ref set_headers.
609			*/
610			BOOST_HTTP_PROTO_DECL
611			void
612			start();
613
614			/** Start serializing a message with a buffer sequence body.
615
616			This overload requires @ref set_headers to have
617			been called first.
618
619			At least one copy of the specified buffer sequence is maintained until
620			the serializer is done, gets reset, or is destroyed, after which all
621			of its copies are destroyed. Ownership of the underlying memory is not
622			transferred; the caller must ensure the memory remains valid until the
623			serializer's copies are destroyed.
624
625			@par Preconditions
626			@ref set_headers has been called and no @ref start
627			or @ref start_stream function has been called since.
628
629			@par Postconditions
630			@code
631			this->is_done() == false
632			@endcode
633
634			@par Constraints
635			@code
636			buffers::is_const_buffer_sequence_v<ConstBufferSequence> == true
637			@endcode
638
639			@par Exception Safety
640			Strong guarantee.
641
642			@throw std::logic_error if @ref set_headers was not called.
643
644			@throw std::length_error If there is insufficient internal buffer
645			space to start the operation.
646
647			@param buffers A buffer sequence containing the message body.
648
649			@see
650			@ref set_headers.
651			*/
652			template<
653			class ConstBufferSequence,
654			class = typename std::enable_if<
655			buffers::is_const_buffer_sequence<
656			ConstBufferSequence>::value>::type
657			>
658			void
659			start(
660			ConstBufferSequence&& buffers);
661
662			/** Start serializing a message with a @em Source body.
663
664			This overload requires @ref set_headers to have
665			been called first.
666
667			The serializer destroys the Source object when:
668			@li `this->is_done() == true`
669			@li An unrecoverable serialization error occurs
670			@li The serializer is destroyed
671
672			@par Example
673			@code
674			file f("example.zip", file_mode::scan);
675			response.set_payload_size(f.size());
676			serializer.set_headers(response);
677			serializer.start<file_source>(std::move(f));
678			@endcode
679
680			@par Preconditions
681			@ref set_headers has been called and no @ref start
682			or @ref start_stream function has been called since.
683
684			@par Postconditions
685			@code
686			this->is_done() == false
687			@endcode
688
689			@par Constraints
690			@code
691			is_source<Source>::value == true
692			@endcode
693
694			@par Exception Safety
695			Strong guarantee.
696
697			@throw std::logic_error if @ref set_headers was not called.
698
699			@throw std::length_error if there is insufficient
700			internal buffer space to start the operation.
701
702			@param args Arguments to be passed to the
703			`Source` constructor.
704
705			@return A reference to the constructed Source object.
706
707			@see
708			@ref set_headers,
709			@ref source,
710			@ref file_source.
711			*/
712			template<
713			class Source,
714			class Arg0,
715			class... Args,
716			class = typename std::enable_if<
717			is_source<Source>::value &&
718			!std::is_convertible<
719			Arg0,
720			message_base const&>::value>::type>
721			Source&
722			start(Arg0&& arg0, Args&&... args);
723
724			/** Start serializing a message with a @em Source body.
725
726			This overload requires @ref set_headers to have
727			been called first. This version takes no arguments
728			and default-constructs the Source.
729
730			@par Preconditions
731			@ref set_headers has been called and no @ref start
732			or @ref start_stream function has been called since.
733
734			@par Postconditions
735			@code
736			this->is_done() == false
737			@endcode
738
739			@par Constraints
740			@code
741			is_source<Source>::value == true
742			@endcode
743
744			@par Exception Safety
745			Strong guarantee.
746
747			@throw std::logic_error if @ref set_headers was not called.
748
749			@throw std::length_error if there is insufficient
750			internal buffer space to start the operation.
751
752			@return A reference to the constructed Source object.
753
754			@see
755			@ref set_headers,
756			@ref source.
757			*/
758			template<
759			class Source,
760			class = typename std::enable_if<
761			is_source<Source>::value>::type>
762			Source&
763			start();
764
765			/** Start serializing a message using a stream interface.
766
767			This overload requires @ref set_headers to have
768			been called first.
769
770			Returns a @ref stream object for writing the body
771			data into the serializer's internal buffer.
772
773			Once the serializer is destroyed, @ref reset
774			is called, or @ref is_done returns true, the
775			only valid operation on the stream is destruction.
776
777			@par Example
778			@code
779			serializer.set_headers(response);
780			serializer::stream st = serializer.start_stream();
781			do
782			{
783			if(st.is_open())
784			{
785			std::size_t n = source.read_some(st.prepare());
786
787			if(ec == error::eof)
788			st.close();
789			else
790			st.commit(n);
791			}
792
793			write_some(client, serializer);
794
795			} while(!serializer.is_done());
796			@endcode
797
798			@par Preconditions
799			@ref set_headers has been called and no @ref start
800			or @ref start_stream function has been called since.
801
802			@par Postconditions
803			@code
804			this->is_done() == false
805			@endcode
806
807			@par Exception Safety
808			Strong guarantee.
809
810			@throw std::logic_error if @ref set_headers was not called.
811
812			@throw std::length_error if there is insufficient
813			internal buffer space to start the operation.
814
815			@return A @ref stream object for writing the body
816			data into the serializer's internal buffer.
817
818			@see
819			@ref set_headers,
820			@ref stream.
821			*/
822			BOOST_HTTP_PROTO_DECL
823			stream
824			start_stream();
825
826			private:
827			class impl;
828			class cbs_gen;
829			template<class>
830			class cbs_gen_impl;
831
832			BOOST_HTTP_PROTO_DECL
833			detail::workspace&
834			ws();
835
836			BOOST_HTTP_PROTO_DECL
837			void
838			start_buffers_impl(
839			cbs_gen&);
840
841			BOOST_HTTP_PROTO_DECL
842			void
843			start_source_impl(
844			source&);
845
846			impl* impl_ = nullptr;
847			};
848
849			/** Serializer configuration settings.
850
851			@see
852			@ref install_serializer_service,
853			@ref serializer.
854			*/
855			struct serializer::config
856			{
857			/** Enable Brotli Content-Encoding.
858
859			Requires `boost::capy::brotli::encode_service` to be
860			installed, otherwise an exception is thrown.
861			*/
862			bool apply_brotli_encoder = false;
863
864			/** Enable Deflate Content-Encoding.
865
866			Requires `boost::zlib::deflate_service` to be
867			installed, otherwise an exception is thrown.
868			*/
869			bool apply_deflate_encoder = false;
870
871			/** Enable Gzip Content-Encoding.
872
873			Requires `boost::zlib::deflate_service` to be
874			installed, otherwise an exception is thrown.
875			*/
876			bool apply_gzip_encoder = false;
877
878			/** Brotli compression quality (0–11).
879
880			Higher values yield better but slower compression.
881			*/
882			std::uint32_t brotli_comp_quality = 5;
883
884			/** Brotli compression window size (10–24).
885
886			Larger windows improve compression but increase
887			memory usage.
888			*/
889			std::uint32_t brotli_comp_window = 18;
890
891			/** Zlib compression level (0–9).
892
893			0 = no compression, 1 = fastest, 9 = best
894			compression.
895			*/
896			int zlib_comp_level = 6;
897
898			/** Zlib window bits (9–15).
899
900			Controls the history buffer size. Larger values
901			improve compression but use more memory.
902			*/
903			int zlib_window_bits = 15;
904
905			/** Zlib memory level (1–9).
906
907			Higher values use more memory, but offer faster
908			and more efficient compression.
909			*/
910			int zlib_mem_level = 8;
911
912			/** Minimum buffer size for payloads (must be > 0). */
913			std::size_t payload_buffer = 8192;
914
915			/** Reserved space for type-erasure storage.
916
917			Used for:
918			@li User-defined @ref source objects.
919			@li User-defined ConstBufferSequence instances.
920			*/
921			std::size_t max_type_erase = 1024;
922			};
923
924			/** Install the serializer service.
925
926			@par Example
927			@code
928			// default configuration settings
929			install_serializer_service(ctx, {});
930
931			serializer sr(ctx);
932			@endcode
933
934			@par Exception Safety
935			Strong guarantee.
936
937			@throw std::invalid_argument If the service is
938			already installed on the context.
939
940			@param ctx Reference to the context on which
941			the service should be installed.
942
943			@param cfg Configuration settings for the
944			serializer.
945
946			@see
947			@ref serializer::config,
948			@ref serializer.
949			*/
950			BOOST_HTTP_PROTO_DECL
951			void
952			install_serializer_service(
953			capy::polystore& ctx,
954			serializer::config const& cfg);
955
956			//------------------------------------------------
957
958			/** Used for streaming body data during serialization.
959
960			Provides an interface for supplying serialized
961			body content from an external source. This
962			object is returned by @ref
963			serializer::start_stream and enables
964			incremental writing of the message body into
965			the serializer's internal buffer.
966
967			The stream supports an inverted control flow
968			model, where the caller pushes body data as
969			needed.
970
971			Valid operations depend on the state of the
972			serializer. Once the serializer is destroyed,
973			reset, or completes, the stream becomes
974			invalid and must only be destroyed.
975
976			@see
977			@ref serializer::start_stream
978			*/
979			class serializer::stream
980			{
981			public:
982			/** The type used to represent a sequence
983			of mutable buffers.
984			*/
985			using mutable_buffers_type =
986			buffers::mutable_buffer_pair;
987
988			/** Constructor.
989
990			A default-constructed stream is
991			considered closed.
992
993			@par Postconditions
994			@code
995			this->is_open() == false
996			@endcode
997			*/
998			stream() noexcept = default;
999
1000			/** Constructor.
1001
1002			After construction, the moved-from
1003			object is as if default-constructed.
1004
1005			@par Postconditions
1006			@code
1007			other->is_open() == false
1008			@endcode
1009
1010			@param other The object to move from.
1011			*/
1012			stream(stream&& other) noexcept
1013			: impl_(other.impl_)
1014			{
1015			other.impl_ = nullptr;
1016			}
1017
1018			/** Move assignment.
1019
1020			After assignment, the moved-from
1021			object is as if default-constructed.
1022
1023			@par Postconditions
1024			@code
1025			other->is_open() == false
1026			@endcode
1027
1028			@param other The object to assign from.
1029			@return A reference to this object.
1030			*/
1031			stream&
1032			operator=(stream&& other) noexcept
1033			{
1034			std::swap(impl_, other.impl_);
1035			return *this;
1036			}
1037
1038			/** Return true if the stream is open.
1039			*/
1040			bool
1041		5062	is_open() const noexcept
1042			{
1043		5062	return impl_ != nullptr;
1044			}
1045
1046			/** Return the available capacity.
1047
1048			@par Preconditions
1049			@code
1050			this->is_open() == true
1051			@endcode
1052
1053			@par Exception Safety
1054			Strong guarantee.
1055
1056			@throw std::logic_error
1057			`this->is_open() == false`.
1058			*/
1059			BOOST_HTTP_PROTO_DECL
1060			std::size_t
1061			capacity() const;
1062
1063			/** Prepare a buffer for writing.
1064
1065			Retuns a mutable buffer sequence representing
1066			the writable bytes. Use @ref commit to make the
1067			written data available to the serializer.
1068
1069			All buffer sequences previously obtained
1070			using @ref prepare are invalidated.
1071
1072			@par Preconditions
1073			@code
1074			this->is_open() == true && n <= this->capacity()
1075			@endcode
1076
1077			@par Exception Safety
1078			Strong guarantee.
1079
1080			@return An instance of @ref mutable_buffers_type
1081			the underlying memory is owned by the serializer.
1082
1083			@throw std::logic_error
1084			`this->is_open() == false`
1085
1086			@see
1087			@ref commit,
1088			@ref capacity.
1089			*/
1090			BOOST_HTTP_PROTO_DECL
1091			mutable_buffers_type
1092			prepare();
1093
1094			/** Commit data to the serializer.
1095
1096			Makes `n` bytes available to the serializer.
1097
1098			All buffer sequences previously obtained
1099			using @ref prepare are invalidated.
1100
1101			@par Preconditions
1102			@code
1103			this->is_open() == true && n <= this->capacity()
1104			@endcode
1105
1106			@par Exception Safety
1107			Strong guarantee.
1108			Exceptions thrown on invalid input.
1109
1110			@param n The number of bytes to append.
1111
1112			@throw std::invalid_argument
1113			`n > this->capacity()`
1114
1115			@throw std::logic_error
1116			`this->is_open() == false`
1117
1118			@see
1119			@ref prepare,
1120			@ref capacity.
1121			*/
1122			BOOST_HTTP_PROTO_DECL
1123			void
1124			commit(std::size_t n);
1125
1126			/** Close the stream if open.
1127
1128			Closes the stream and
1129			notifies the serializer that the
1130			message body has ended.
1131
1132			If the stream is already closed this
1133			call has no effect.
1134
1135			@par Postconditions
1136			@code
1137			this->is_open() == false
1138			@endcode
1139			*/
1140			BOOST_HTTP_PROTO_DECL
1141			void
1142			close() noexcept;
1143
1144			/** Destructor.
1145
1146			Closes the stream if open.
1147			*/
1148		24	~stream()
1149			{
1150		24	close();
1151		24	}
1152
1153			private:
1154			friend class serializer;
1155
1156			explicit
1157		23	stream(serializer::impl* impl) noexcept
1158		23	: impl_(impl)
1159			{
1160		23	}
1161
1162			serializer::impl* impl_ = nullptr;
1163			};
1164
1165			} // http_proto
1166			} // boost
1167
1168			#include <boost/http_proto/impl/serializer.hpp>
1169
1170			#endif
1171