Line data Source code
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
9 : //
10 :
11 : #ifndef BOOST_HTTP_SERIALIZER_HPP
12 : #define BOOST_HTTP_SERIALIZER_HPP
13 :
14 : #include <boost/http/detail/config.hpp>
15 : #include <boost/http/detail/workspace.hpp>
16 : #include <boost/http/source.hpp>
17 :
18 : #include <boost/capy/buffers/buffer_pair.hpp>
19 : #include <boost/core/span.hpp>
20 : #include <boost/capy/core/polystore_fwd.hpp>
21 : #include <boost/system/result.hpp>
22 :
23 : #include <type_traits>
24 : #include <utility>
25 :
26 : namespace boost {
27 : namespace http {
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<capy::const_buffer const>;
68 :
69 : /** Destructor
70 : */
71 : BOOST_HTTP_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_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_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_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_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_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 : capy::const_buffer_sequence<ConstBufferSequence>
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 : capy::const_buffer_sequence<ConstBufferSequence>>::type
279 : >
280 : void
281 : start(
282 : message_base const& m,
283 : ConstBufferSequence&& buffers);
284 :
285 : /** Start serializing a message with a @em Source body
286 :
287 : Initializes the serializer with the HTTP start-line and headers from
288 : `m`, and constructs a `Source` object to provide the message body.
289 :
290 : Changing the contents of the message
291 : after calling this function and before
292 : @ref is_done returns `true` results in
293 : undefined behavior.
294 :
295 : The serializer destroys Source object when:
296 : @li `this->is_done() == true`
297 : @li An unrecoverable serialization error occurs
298 : @li The serializer is destroyed
299 :
300 : @par Example
301 : @code
302 : file f("example.zip", file_mode::scan);
303 : response.set_payload_size(f.size());
304 : serializer.start<file_source>(response, std::move(f));
305 : @endcode
306 :
307 : @par Preconditions
308 : @code
309 : this->is_done() == true
310 : @endcode
311 :
312 : @par Postconditions
313 : @code
314 : this->is_done() == false
315 : @endcode
316 :
317 : @par Constraints
318 : @code
319 : is_source<Source>::value == true
320 : @endcode
321 :
322 : @par Exception Safety
323 : Strong guarantee.
324 : Exceptions thrown if there is insufficient
325 : internal buffer space to start the
326 : operation.
327 :
328 : @throw std::length_error if there is
329 : insufficient internal buffer space to
330 : start the operation.
331 :
332 : @param m The message to read the HTTP
333 : start-line and headers from.
334 :
335 : @param args Arguments to be passed to the
336 : `Source` constructor.
337 :
338 : @return A reference to the constructed Source object.
339 :
340 : @see
341 : @ref source,
342 : @ref file_source,
343 : @ref message_base.
344 : */
345 : template<
346 : class Source,
347 : class... Args,
348 : class = typename std::enable_if<
349 : is_source<Source>::value>::type>
350 : Source&
351 : start(
352 : message_base const& m,
353 : Args&&... args);
354 :
355 : /** Prepare the serializer for a new message using a stream interface.
356 :
357 : Initializes the serializer with the HTTP
358 : start-line and headers from `m`, and returns
359 : a @ref stream object for writing the body
360 : data into the serializer's internal buffer.
361 :
362 : Once the serializer is destroyed, @ref reset
363 : is called, or @ref is_done returns true, the
364 : only valid operation on the stream is destruction.
365 :
366 : The stream allows inverted control flow: the
367 : caller supplies body data to the serializer’s
368 : internal buffer while reading from an external
369 : source.
370 :
371 : Changing the contents of the message
372 : after calling this function and before
373 : @ref is_done returns `true` results in
374 : undefined behavior.
375 :
376 : @par Example
377 : @code
378 : serializer::stream st = serializer.start_stream(response);
379 : do
380 : {
381 : if(st.is_open())
382 : {
383 : std::size_t n = source.read_some(st.prepare());
384 :
385 : if(ec == error::eof)
386 : st.close();
387 : else
388 : st.commit(n);
389 : }
390 :
391 : write_some(client, serializer);
392 :
393 : } while(!serializer.is_done());
394 : @endcode
395 :
396 : @par Preconditions
397 : @code
398 : this->is_done() == true
399 : @endcode
400 :
401 : @par Postconditions
402 : @code
403 : this->is_done() == false
404 : @endcode
405 :
406 : @par Exception Safety
407 : Strong guarantee.
408 : Exceptions thrown if there is insufficient
409 : internal buffer space to start the
410 : operation.
411 :
412 : @throw std::length_error if there is
413 : insufficient internal buffer space to
414 : start the operation.
415 :
416 : @param m The message to read the HTTP
417 : start-line and headers from.
418 :
419 : @return A @ref stream object for writing the body
420 : data into the serializer's internal buffer.
421 :
422 : @see
423 : @ref stream,
424 : @ref message_base.
425 : */
426 : BOOST_HTTP_DECL
427 : stream
428 : start_stream(
429 : message_base const& m);
430 :
431 : /** Return the output area.
432 :
433 : This function serializes some or all of
434 : the message and returns the corresponding
435 : output buffers. Afterward, a call to @ref
436 : consume is required to report the number
437 : of bytes used, if any.
438 :
439 : If the message includes an
440 : `Expect: 100-continue` header and the
441 : header section of the message has been
442 : consumed, the returned result will contain
443 : @ref error::expect_100_continue to
444 : indicate that the header part of the
445 : message is complete. The next call to @ref
446 : prepare will produce output.
447 :
448 : When the serializer is used through the
449 : @ref stream interface, the result may
450 : contain @ref error::need_data to indicate
451 : that additional input is required to
452 : produce output.
453 :
454 : If a @ref source object is in use and a
455 : call to @ref source::read returns an
456 : error, the serializer enters a faulted
457 : state and propagates the error to the
458 : caller. This faulted state can only be
459 : cleared by calling @ref reset. This
460 : ensures the caller is explicitly aware
461 : that the previous message was truncated
462 : and that the stream must be terminated.
463 :
464 : @par Preconditions
465 : @code
466 : this->is_done() == false
467 : @endcode
468 : No unrecoverable error reported from previous calls.
469 :
470 : @par Exception Safety
471 : Strong guarantee.
472 : Calls to @ref source::read may throw if in use.
473 :
474 : @throw std::logic_error
475 : `this->is_done() == true`.
476 :
477 : @return A result containing @ref
478 : const_buffers_type that represents the
479 : output area or an error if any occurred.
480 :
481 : @see
482 : @ref consume,
483 : @ref is_done,
484 : @ref const_buffers_type.
485 : */
486 : BOOST_HTTP_DECL
487 : auto
488 : prepare() ->
489 : system::result<
490 : const_buffers_type>;
491 :
492 : /** Consume bytes from the output area.
493 :
494 : This function should be called after one
495 : or more bytes contained in the buffers
496 : provided in the prior call to @ref prepare
497 : have been used.
498 :
499 : After a call to @ref consume, callers
500 : should check the return value of @ref
501 : is_done to determine if the entire message
502 : has been serialized.
503 :
504 : @par Preconditions
505 : @code
506 : this->is_done() == false
507 : @endcode
508 :
509 : @par Exception Safety
510 : Strong guarantee.
511 :
512 : @throw std::logic_error
513 : `this->is_done() == true`.
514 :
515 : @param n The number of bytes to consume.
516 : If `n` is greater than the size of the
517 : buffer returned from @ref prepared the
518 : entire output sequence is consumed and no
519 : error is issued.
520 :
521 : @see
522 : @ref prepare,
523 : @ref is_done,
524 : @ref const_buffers_type.
525 : */
526 : BOOST_HTTP_DECL
527 : void
528 : consume(std::size_t n);
529 :
530 : /** Return true if serialization is complete.
531 : */
532 : BOOST_HTTP_DECL
533 : bool
534 : is_done() const noexcept;
535 :
536 : private:
537 : class impl;
538 : class cbs_gen;
539 : template<class>
540 : class cbs_gen_impl;
541 :
542 : BOOST_HTTP_DECL
543 : detail::workspace&
544 : ws();
545 :
546 : BOOST_HTTP_DECL
547 : void
548 : start_init(
549 : message_base const&);
550 :
551 : BOOST_HTTP_DECL
552 : void
553 : start_buffers(
554 : message_base const&,
555 : cbs_gen&);
556 :
557 : BOOST_HTTP_DECL
558 : void
559 : start_source(
560 : message_base const&,
561 : source&);
562 :
563 : impl* impl_ = nullptr;
564 : };
565 :
566 : /** Serializer configuration settings.
567 :
568 : @see
569 : @ref install_serializer_service,
570 : @ref serializer.
571 : */
572 : struct serializer::config
573 : {
574 : /** Enable Brotli Content-Encoding.
575 :
576 : Requires `boost::capy::brotli::encode_service` to be
577 : installed, otherwise an exception is thrown.
578 : */
579 : bool apply_brotli_encoder = false;
580 :
581 : /** Enable Deflate Content-Encoding.
582 :
583 : Requires `boost::zlib::deflate_service` to be
584 : installed, otherwise an exception is thrown.
585 : */
586 : bool apply_deflate_encoder = false;
587 :
588 : /** Enable Gzip Content-Encoding.
589 :
590 : Requires `boost::zlib::deflate_service` to be
591 : installed, otherwise an exception is thrown.
592 : */
593 : bool apply_gzip_encoder = false;
594 :
595 : /** Brotli compression quality (0–11).
596 :
597 : Higher values yield better but slower compression.
598 : */
599 : std::uint32_t brotli_comp_quality = 5;
600 :
601 : /** Brotli compression window size (10–24).
602 :
603 : Larger windows improve compression but increase
604 : memory usage.
605 : */
606 : std::uint32_t brotli_comp_window = 18;
607 :
608 : /** Zlib compression level (0–9).
609 :
610 : 0 = no compression, 1 = fastest, 9 = best
611 : compression.
612 : */
613 : int zlib_comp_level = 6;
614 :
615 : /** Zlib window bits (9–15).
616 :
617 : Controls the history buffer size. Larger values
618 : improve compression but use more memory.
619 : */
620 : int zlib_window_bits = 15;
621 :
622 : /** Zlib memory level (1–9).
623 :
624 : Higher values use more memory, but offer faster
625 : and more efficient compression.
626 : */
627 : int zlib_mem_level = 8;
628 :
629 : /** Minimum buffer size for payloads (must be > 0). */
630 : std::size_t payload_buffer = 8192;
631 :
632 : /** Reserved space for type-erasure storage.
633 :
634 : Used for:
635 : @li User-defined @ref source objects.
636 : @li User-defined ConstBufferSequence instances.
637 : */
638 : std::size_t max_type_erase = 1024;
639 : };
640 :
641 : /** Install the serializer service.
642 :
643 : @par Example
644 : @code
645 : // default configuration settings
646 : install_serializer_service(ctx, {});
647 :
648 : serializer sr(ctx);
649 : @endcode
650 :
651 : @par Exception Safety
652 : Strong guarantee.
653 :
654 : @throw std::invalid_argument If the service is
655 : already installed on the context.
656 :
657 : @param ctx Reference to the context on which
658 : the service should be installed.
659 :
660 : @param cfg Configuration settings for the
661 : serializer.
662 :
663 : @see
664 : @ref serializer::config,
665 : @ref serializer.
666 : */
667 : BOOST_HTTP_DECL
668 : void
669 : install_serializer_service(
670 : capy::polystore& ctx,
671 : serializer::config const& cfg);
672 :
673 : //------------------------------------------------
674 :
675 : /** Used for streaming body data during serialization.
676 :
677 : Provides an interface for supplying serialized
678 : body content from an external source. This
679 : object is returned by @ref
680 : serializer::start_stream and enables
681 : incremental writing of the message body into
682 : the serializer's internal buffer.
683 :
684 : The stream supports an inverted control flow
685 : model, where the caller pushes body data as
686 : needed.
687 :
688 : Valid operations depend on the state of the
689 : serializer. Once the serializer is destroyed,
690 : reset, or completes, the stream becomes
691 : invalid and must only be destroyed.
692 :
693 : @see
694 : @ref serializer::start_stream
695 : */
696 : class serializer::stream
697 : {
698 : public:
699 : /** The type used to represent a sequence
700 : of mutable buffers.
701 : */
702 : using mutable_buffers_type =
703 : capy::mutable_buffer_pair;
704 :
705 : /** Constructor.
706 :
707 : A default-constructed stream is
708 : considered closed.
709 :
710 : @par Postconditions
711 : @code
712 : this->is_open() == false
713 : @endcode
714 : */
715 : stream() noexcept = default;
716 :
717 : /** Constructor.
718 :
719 : After construction, the moved-from
720 : object is as if default-constructed.
721 :
722 : @par Postconditions
723 : @code
724 : other->is_open() == false
725 : @endcode
726 :
727 : @param other The object to move from.
728 : */
729 : stream(stream&& other) noexcept
730 : : impl_(other.impl_)
731 : {
732 : other.impl_ = nullptr;
733 : }
734 :
735 : /** Move assignment.
736 :
737 : After assignment, the moved-from
738 : object is as if default-constructed.
739 :
740 : @par Postconditions
741 : @code
742 : other->is_open() == false
743 : @endcode
744 :
745 : @param other The object to assign from.
746 : @return A reference to this object.
747 : */
748 : stream&
749 : operator=(stream&& other) noexcept
750 : {
751 : std::swap(impl_, other.impl_);
752 : return *this;
753 : }
754 :
755 : /** Return true if the stream is open.
756 : */
757 : bool
758 5030 : is_open() const noexcept
759 : {
760 5030 : return impl_ != nullptr;
761 : }
762 :
763 : /** Return the available capacity.
764 :
765 : @par Preconditions
766 : @code
767 : this->is_open() == true
768 : @endcode
769 :
770 : @par Exception Safety
771 : Strong guarantee.
772 :
773 : @throw std::logic_error
774 : `this->is_open() == false`.
775 : */
776 : BOOST_HTTP_DECL
777 : std::size_t
778 : capacity() const;
779 :
780 : /** Prepare a buffer for writing.
781 :
782 : Retuns a mutable buffer sequence representing
783 : the writable bytes. Use @ref commit to make the
784 : written data available to the serializer.
785 :
786 : All buffer sequences previously obtained
787 : using @ref prepare are invalidated.
788 :
789 : @par Preconditions
790 : @code
791 : this->is_open() == true && n <= this->capacity()
792 : @endcode
793 :
794 : @par Exception Safety
795 : Strong guarantee.
796 :
797 : @return An instance of @ref mutable_buffers_type
798 : the underlying memory is owned by the serializer.
799 :
800 : @throw std::logic_error
801 : `this->is_open() == false`
802 :
803 : @see
804 : @ref commit,
805 : @ref capacity.
806 : */
807 : BOOST_HTTP_DECL
808 : mutable_buffers_type
809 : prepare();
810 :
811 : /** Commit data to the serializer.
812 :
813 : Makes `n` bytes available to the serializer.
814 :
815 : All buffer sequences previously obtained
816 : using @ref prepare are invalidated.
817 :
818 : @par Preconditions
819 : @code
820 : this->is_open() == true && n <= this->capacity()
821 : @endcode
822 :
823 : @par Exception Safety
824 : Strong guarantee.
825 : Exceptions thrown on invalid input.
826 :
827 : @param n The number of bytes to append.
828 :
829 : @throw std::invalid_argument
830 : `n > this->capacity()`
831 :
832 : @throw std::logic_error
833 : `this->is_open() == false`
834 :
835 : @see
836 : @ref prepare,
837 : @ref capacity.
838 : */
839 : BOOST_HTTP_DECL
840 : void
841 : commit(std::size_t n);
842 :
843 : /** Close the stream if open.
844 :
845 : Closes the stream and
846 : notifies the serializer that the
847 : message body has ended.
848 :
849 : If the stream is already closed this
850 : call has no effect.
851 :
852 : @par Postconditions
853 : @code
854 : this->is_open() == false
855 : @endcode
856 : */
857 : BOOST_HTTP_DECL
858 : void
859 : close() noexcept;
860 :
861 : /** Destructor.
862 :
863 : Closes the stream if open.
864 : */
865 24 : ~stream()
866 : {
867 24 : close();
868 24 : }
869 :
870 : private:
871 : friend class serializer;
872 :
873 : explicit
874 23 : stream(serializer::impl* impl) noexcept
875 23 : : impl_(impl)
876 : {
877 23 : }
878 :
879 : serializer::impl* impl_ = nullptr;
880 : };
881 :
882 : } // http
883 : } // boost
884 :
885 : #include <boost/http/impl/serializer.hpp>
886 :
887 : #endif
|
