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