MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Framing.hpp
Go to the documentation of this file.
1#pragma once
2
4
5/**
6 * @brief One complete message. Valid only while the sink runs.
7 */
8using Message = std::span<const uint8_t>;
9
10/**
11 * @brief A callable that receives each complete message.
12 *
13 * It must not push into the framer that is calling it. If it throws, the
14 * exception propagates, the rest of that push is discarded and the framer
15 * stays valid.
16 */
17template <typename Sink>
18concept MessageSink = std::invocable<Sink&, Message>;
19
20inline constexpr size_t default_max_line = size_t { 1 } << 20;
21inline constexpr size_t default_max_frame = size_t { 64 } << 20;
22
23/**
24 * @enum FrameFault
25 * @brief Why input was refused.
26 *
27 * Oversized: a line, block or declared length exceeded its limit.
28 * Invalid: a zero length where empty messages are not allowed, or a malformed encoding.
29 */
30enum class FrameFault : uint8_t {
34};
35
36/**
37 * @struct FrameReport
38 * @brief What one push did.
39 *
40 * messages counts messages delivered to the sink. discarded counts lines or
41 * blocks dropped for size, which a framer recovers from. fault is the last
42 * fault seen. A terminal fault (LengthPrefixFramer only) also reports on every
43 * later push until reset().
44 */
45struct [[nodiscard]] FrameReport {
46 size_t messages {};
47 size_t discarded {};
49
50 [[nodiscard]] bool ok() const noexcept { return fault == FrameFault::None; }
51};
52
53/**
54 * @brief View a message as text without copying.
55 */
56[[nodiscard]] inline std::string_view as_text(Message message) noexcept
57{
58 return { reinterpret_cast<const char*>(message.data()), message.size() };
59}
60
61namespace detail {
62
64 public:
65 explicit ClearOnExit(std::vector<uint8_t>& buffer) noexcept
66 : m_buffer(buffer)
67 {
68 }
69
70 ClearOnExit(const ClearOnExit&) = delete;
74
75 ~ClearOnExit() { m_buffer.clear(); }
76
77 private:
78 std::vector<uint8_t>& m_buffer;
79 };
80
81 [[nodiscard]] inline uint32_t load_be_u32(const uint8_t* src) noexcept
82 {
83 return (uint32_t { src[0] } << 24) | (uint32_t { src[1] } << 16)
84 | (uint32_t { src[2] } << 8) | uint32_t { src[3] };
85 }
86
87 inline void append_be_u32(std::vector<uint8_t>& out, uint32_t value)
88 {
89 out.push_back(static_cast<uint8_t>(value >> 24));
90 out.push_back(static_cast<uint8_t>(value >> 16));
91 out.push_back(static_cast<uint8_t>(value >> 8));
92 out.push_back(static_cast<uint8_t>(value));
93 }
94
95}
96
97/**
98 * @class LineFramer
99 * @brief Splits a byte stream into lines, whatever the chunking.
100 *
101 * A message is the bytes before each LF with one trailing CR removed. Empty
102 * lines are delivered as empty messages. A line longer than max_line, counted
103 * raw before the LF and including any CR, is dropped and the framer resumes
104 * after the next LF. A line that sits whole inside one push is delivered as a
105 * view into the input with no copy.
106 *
107 * A payload that contains LF cannot be carried, so multi-line text needs
108 * LengthPrefixFramer.
109 *
110 * Not thread safe: one thread at a time per framer.
111 */
113public:
114 explicit LineFramer(size_t max_line = default_max_line) noexcept
115 : m_max_line(max_line)
116 {
117 }
118
119 template <MessageSink Sink>
120 FrameReport push(Message bytes, Sink&& sink)
121 {
122 FrameReport report;
123
124 while (!bytes.empty()) {
125 const auto end = std::ranges::find(bytes, static_cast<uint8_t>('\n'));
126 const bool complete = end != bytes.end();
127 const auto length = static_cast<size_t>(end - bytes.begin());
128 const Message segment = bytes.first(length);
129 bytes = complete ? bytes.subspan(length + 1) : bytes.subspan(length);
130
131 if (m_discarding) {
132 m_discarding = !complete;
133 continue;
134 }
135
136 if (m_pending.size() + segment.size() > m_max_line) {
137 m_pending.clear();
138 ++report.discarded;
140 m_discarding = !complete;
141 continue;
142 }
143
144 if (!complete) {
145 m_pending.insert(m_pending.end(), segment.begin(), segment.end());
146 continue;
147 }
148
149 if (m_pending.empty()) {
150 deliver(segment, sink, report);
151 } else {
152 m_pending.insert(m_pending.end(), segment.begin(), segment.end());
153 const detail::ClearOnExit guard { m_pending };
154 deliver(Message { m_pending }, sink, report);
155 }
156 }
157
158 return report;
159 }
160
161 /** @brief Drop any partial line and any discard in progress. */
162 void reset() noexcept
163 {
164 m_pending.clear();
165 m_discarding = false;
166 }
167
168 /** @brief Bytes held for a line that has not ended. */
169 [[nodiscard]] size_t buffered() const noexcept { return m_pending.size(); }
170
171private:
172 template <typename Sink>
173 static void deliver(Message line, Sink& sink, FrameReport& report)
174 {
175 if (!line.empty() && line.back() == '\r') {
176 line = line.first(line.size() - 1);
177 }
178 sink(line);
179 ++report.messages;
180 }
181
182 std::vector<uint8_t> m_pending;
184 bool m_discarding { false };
185};
186
187/**
188 * @class LengthPrefixFramer
189 * @brief Messages with a four byte big-endian length before each payload.
190 *
191 * A zero length is an empty message, unless reject_empty is set and it becomes
192 * a fault. A length above max_payload is a fault. Faults are terminal: the
193 * stream cannot be resynchronised, so the framer delivers nothing more and
194 * reports the fault on every push until reset(). Messages completed earlier in
195 * the same push are still delivered. Nothing is reserved from the declared
196 * length, so a hostile length costs memory only as bytes actually arrive.
197 *
198 * A frame that sits whole inside one push is delivered as a view into the input
199 * with no copy.
200 *
201 * Not thread safe: one thread at a time per framer.
202 */
204public:
205 explicit LengthPrefixFramer(size_t max_payload = default_max_frame, bool reject_empty = false) noexcept
206 : m_max_payload(std::min<size_t>(max_payload, std::numeric_limits<uint32_t>::max()))
207 , m_reject_empty(reject_empty)
208 {
209 }
210
211 template <MessageSink Sink>
212 FrameReport push(Message bytes, Sink&& sink)
213 {
214 FrameReport report;
215 if (m_fault != FrameFault::None) {
216 report.fault = m_fault;
217 return report;
218 }
219
220 while (!bytes.empty()) {
221 if (!m_in_payload) {
222 const size_t take = std::min(header_size - m_header_size, bytes.size());
223 std::copy_n(bytes.begin(), take, m_header.begin() + static_cast<std::ptrdiff_t>(m_header_size));
224 m_header_size += take;
225 bytes = bytes.subspan(take);
227 break;
228 }
229 m_header_size = 0;
230
231 const uint32_t length = detail::load_be_u32(m_header.data());
232 if (length == 0 && m_reject_empty) {
233 return fail(report, FrameFault::Invalid);
234 }
235 if (length > m_max_payload) {
236 return fail(report, FrameFault::Oversized);
237 }
238 if (length == 0) {
239 sink(Message {});
240 ++report.messages;
241 continue;
242 }
243 m_expected = length;
244 m_in_payload = true;
245 }
246
247 if (m_payload.empty() && bytes.size() >= m_expected) {
248 const Message frame = bytes.first(m_expected);
249 bytes = bytes.subspan(m_expected);
250 m_in_payload = false;
251 sink(frame);
252 ++report.messages;
253 continue;
254 }
255
256 const size_t take = std::min(m_expected - m_payload.size(), bytes.size());
257 m_payload.insert(m_payload.end(), bytes.begin(), bytes.begin() + static_cast<std::ptrdiff_t>(take));
258 bytes = bytes.subspan(take);
259 if (m_payload.size() < m_expected) {
260 break;
261 }
262
263 m_in_payload = false;
264 const detail::ClearOnExit guard { m_payload };
265 sink(Message { m_payload });
266 ++report.messages;
267 }
268
269 return report;
270 }
271
272 /** @brief Drop partial input and clear a terminal fault. */
273 void reset() noexcept
274 {
275 m_header_size = 0;
276 m_in_payload = false;
277 m_expected = 0;
278 m_payload.clear();
280 }
281
282 /** @brief True after a terminal fault, until reset(). */
283 [[nodiscard]] bool broken() const noexcept { return m_fault != FrameFault::None; }
284
285 /** @brief Partial header bytes plus payload bytes held for a frame that has not completed. */
286 [[nodiscard]] size_t buffered() const noexcept { return m_header_size + m_payload.size(); }
287
288private:
289 static constexpr size_t header_size = 4;
290
291 FrameReport fail(FrameReport& report, FrameFault fault) noexcept
292 {
293 m_fault = fault;
294 m_header_size = 0;
295 m_in_payload = false;
296 m_payload.clear();
297 report.fault = fault;
298 return report;
299 }
300
301 std::array<uint8_t, header_size> m_header {};
302 std::vector<uint8_t> m_payload;
303 size_t m_header_size { 0 };
304 size_t m_expected { 0 };
307 bool m_in_payload { false };
309};
310
311/**
312 * @brief Append a payload and its LF to out, in the form LineFramer reads back.
313 *
314 * Refused, with out unchanged, when the payload contains an LF or ends in CR,
315 * because LineFramer could not return it exactly. An empty payload is a blank
316 * line.
317 */
318[[nodiscard]] inline bool encode_line(Message payload, std::vector<uint8_t>& out)
319{
320 if (std::ranges::find(payload, static_cast<uint8_t>('\n')) != payload.end()) {
321 return false;
322 }
323 if (!payload.empty() && payload.back() == '\r') {
324 return false;
325 }
326 out.insert(out.end(), payload.begin(), payload.end());
327 out.push_back(static_cast<uint8_t>('\n'));
328 return true;
329}
330
331/**
332 * @brief Append a length prefix and a payload to out, in the form LengthPrefixFramer reads back.
333 *
334 * Refused, with out unchanged, when the payload is longer than max_payload or
335 * 4294967295 bytes, or is empty while reject_empty is set.
336 */
337[[nodiscard]] inline bool encode_length_prefixed(Message payload, std::vector<uint8_t>& out,
338 size_t max_payload = default_max_frame, bool reject_empty = false)
339{
340 const size_t limit = std::min<size_t>(max_payload, std::numeric_limits<uint32_t>::max());
341 if (payload.size() > limit || (payload.empty() && reject_empty)) {
342 return false;
343 }
344 detail::append_be_u32(out, static_cast<uint32_t>(payload.size()));
345 out.insert(out.end(), payload.begin(), payload.end());
346 return true;
347}
348
349/**
350 * @struct RawChunkFramer
351 * @brief The framer for raw streams: every push is one message, with nothing to reassemble.
352 *
353 * An empty push delivers nothing.
354 */
356 template <MessageSink Sink>
357 FrameReport push(Message bytes, Sink&& sink)
358 {
359 FrameReport report;
360 if (!bytes.empty()) {
361 sink(bytes);
362 report.messages = 1;
363 }
364 return report;
365 }
366
367 void reset() noexcept { }
368};
369
370/**
371 * @class DelimiterFramer
372 * @brief Splits a byte stream at a terminator of one or more bytes, whatever the chunking.
373 *
374 * A message is the bytes before each terminator, such as "\r" for a modem, ">" for an
375 * ELM327 or "\r\n". Empty messages are delivered. A message longer than max_message is
376 * dropped and the framer resumes after the next terminator. An empty terminator is
377 * taken as LF.
378 *
379 * Not thread safe: one thread at a time per framer.
380 */
382public:
383 explicit DelimiterFramer(std::span<const uint8_t> terminator, size_t max_message = default_max_line)
384 : m_terminator(terminator.begin(), terminator.end())
385 , m_max_message(max_message)
386 {
387 if (m_terminator.empty()) {
388 m_terminator.push_back(static_cast<uint8_t>('\n'));
389 }
390 }
391
392 explicit DelimiterFramer(std::string_view terminator, size_t max_message = default_max_line)
393 : DelimiterFramer(std::span<const uint8_t> { reinterpret_cast<const uint8_t*>(terminator.data()), terminator.size() }, max_message)
394 {
395 }
396
397 template <MessageSink Sink>
398 FrameReport push(Message bytes, Sink&& sink)
399 {
400 FrameReport report;
401 const size_t width = m_terminator.size();
402
403 for (const uint8_t byte : bytes) {
404 m_pending.push_back(byte);
405 if (m_discarding && m_pending.size() > width) {
406 m_pending.erase(m_pending.begin());
407 }
408
409 if (!ends_with_terminator()) {
410 if (!m_discarding && m_pending.size() >= width && m_pending.size() - width >= m_max_message) {
411 m_discarding = true;
412 ++report.discarded;
414 if (m_pending.size() > width) {
415 m_pending.erase(m_pending.begin(), m_pending.end() - static_cast<std::ptrdiff_t>(width));
416 }
417 }
418 continue;
419 }
420
421 if (m_discarding) {
422 m_pending.clear();
423 m_discarding = false;
424 continue;
425 }
426
427 const Message message = Message { m_pending }.first(m_pending.size() - width);
428 const detail::ClearOnExit guard { m_pending };
429 sink(message);
430 ++report.messages;
431 }
432
433 return report;
434 }
435
436 /** @brief Drop any partial message and any discard in progress. */
437 void reset() noexcept
438 {
439 m_pending.clear();
440 m_discarding = false;
441 }
442
443 /** @brief Bytes held for a message that has not ended. */
444 [[nodiscard]] size_t buffered() const noexcept { return m_pending.size(); }
445
446private:
447 [[nodiscard]] bool ends_with_terminator() const
448 {
449 return m_pending.size() >= m_terminator.size()
450 && std::equal(m_terminator.begin(), m_terminator.end(),
451 m_pending.end() - static_cast<std::ptrdiff_t>(m_terminator.size()));
452 }
453
454 std::vector<uint8_t> m_terminator;
455 std::vector<uint8_t> m_pending;
457 bool m_discarding { false };
458};
459
460/**
461 * @brief Append a payload and a terminator to out, in the form DelimiterFramer reads back.
462 *
463 * Refused, with out unchanged, when the terminator is empty or when the terminator
464 * would end the message before the payload does.
465 */
466[[nodiscard]] inline bool encode_delimited(Message payload, Message terminator, std::vector<uint8_t>& out)
467{
468 if (terminator.empty()) {
469 return false;
470 }
471
472 std::vector<uint8_t> joined(payload.begin(), payload.end());
473 joined.insert(joined.end(), terminator.begin(), terminator.end());
474 const auto hit = std::ranges::search(joined, terminator);
475 if (static_cast<size_t>(hit.begin() - joined.begin()) != payload.size()) {
476 return false;
477 }
478
479 out.insert(out.end(), joined.begin(), joined.end());
480 return true;
481}
482
483namespace detail {
484
485 /**
486 * @brief Decode one COBS frame, without its zero delimiter.
487 * @return false when the frame is malformed. out may then hold a partial result.
488 */
489 [[nodiscard]] inline bool cobs_decode(Message frame, std::vector<uint8_t>& out)
490 {
491 size_t index = 0;
492 while (index < frame.size()) {
493 const size_t code = frame[index++];
494 if (code == 0) {
495 return false;
496 }
497 const size_t run = code - 1;
498 if (index + run > frame.size()) {
499 return false;
500 }
501 for (size_t i = 0; i < run; ++i) {
502 if (frame[index + i] == 0) {
503 return false;
504 }
505 }
506 out.insert(out.end(), frame.begin() + static_cast<std::ptrdiff_t>(index),
507 frame.begin() + static_cast<std::ptrdiff_t>(index + run));
508 index += run;
509 if (code != 0xFF && index < frame.size()) {
510 out.push_back(0);
511 }
512 }
513 return true;
514 }
515
516}
517
518/**
519 * @class CobsFramer
520 * @brief Messages in Consistent Overhead Byte Stuffing, each ended by a zero byte.
521 *
522 * The payload may hold any bytes, since COBS removes every zero from the encoded
523 * frame. Frames that are only a delimiter are skipped. A frame that does not decode
524 * is dropped and counted as discarded with FrameFault::Invalid, and one whose
525 * encoded length exceeds max_frame is dropped with FrameFault::Oversized. Either way
526 * the framer resumes after the next zero.
527 *
528 * Not thread safe: one thread at a time per framer.
529 */
531public:
532 explicit CobsFramer(size_t max_frame = default_max_line) noexcept
533 : m_max_frame(max_frame)
534 {
535 }
536
537 template <MessageSink Sink>
538 FrameReport push(Message bytes, Sink&& sink)
539 {
540 FrameReport report;
541
542 for (const uint8_t byte : bytes) {
543 if (byte != 0) {
544 if (m_discarding) {
545 continue;
546 }
547 if (m_pending.size() >= m_max_frame) {
548 m_pending.clear();
549 m_discarding = true;
550 ++report.discarded;
552 continue;
553 }
554 m_pending.push_back(byte);
555 continue;
556 }
557
558 if (m_discarding) {
559 m_discarding = false;
560 continue;
561 }
562 if (m_pending.empty()) {
563 continue;
564 }
565
566 m_decoded.clear();
567 const bool decoded = detail::cobs_decode(Message { m_pending }, m_decoded);
568 m_pending.clear();
569 if (!decoded) {
570 ++report.discarded;
571 report.fault = FrameFault::Invalid;
572 continue;
573 }
574 sink(Message { m_decoded });
575 ++report.messages;
576 }
577
578 return report;
579 }
580
581 /** @brief Drop any partial frame and any discard in progress. */
582 void reset() noexcept
583 {
584 m_pending.clear();
585 m_decoded.clear();
586 m_discarding = false;
587 }
588
589 /** @brief Encoded bytes held for a frame that has not ended. */
590 [[nodiscard]] size_t buffered() const noexcept { return m_pending.size(); }
591
592private:
593 std::vector<uint8_t> m_pending;
594 std::vector<uint8_t> m_decoded;
596 bool m_discarding { false };
597};
598
599/**
600 * @brief Append a payload in COBS, followed by its zero delimiter, to out.
601 *
602 * Any payload is accepted, an empty one included.
603 */
604inline void encode_cobs(Message payload, std::vector<uint8_t>& out)
605{
606 size_t block = 0;
607 uint8_t code = 0;
608 bool open = false;
609
610 const auto begin = [&] {
611 block = out.size();
612 out.push_back(0);
613 code = 1;
614 open = true;
615 };
616 const auto close = [&] {
617 out[block] = code;
618 open = false;
619 };
620
621 begin();
622 for (const uint8_t byte : payload) {
623 if (!open) {
624 begin();
625 }
626 if (byte == 0) {
627 close();
628 begin();
629 continue;
630 }
631 out.push_back(byte);
632 if (++code == 0xFF) {
633 close();
634 }
635 }
636 if (open) {
637 close();
638 }
639 out.push_back(0);
640}
641
642/**
643 * @class SlipFramer
644 * @brief Messages in SLIP (RFC 1055), each ended by 0xC0.
645 *
646 * The payload may hold any bytes, with 0xC0 and 0xDB escaped. Empty frames are
647 * skipped, so a leading 0xC0 is harmless. An escape followed by anything but the two
648 * defined codes, or by 0xC0, drops the frame and counts it as discarded with
649 * FrameFault::Invalid. A decoded message longer than max_message is dropped with
650 * FrameFault::Oversized. Either way the framer resumes after the next 0xC0.
651 *
652 * Not thread safe: one thread at a time per framer.
653 */
655public:
656 explicit SlipFramer(size_t max_message = default_max_line) noexcept
657 : m_max_message(max_message)
658 {
659 }
660
661 template <MessageSink Sink>
662 FrameReport push(Message bytes, Sink&& sink)
663 {
664 FrameReport report;
665
666 const auto discard = [&](FrameFault fault) {
667 m_pending.clear();
668 m_escaped = false;
669 m_discarding = true;
670 ++report.discarded;
671 report.fault = fault;
672 };
673
674 for (const uint8_t byte : bytes) {
675 if (byte == end) {
676 const bool broken = m_escaped && !m_discarding;
677 const bool was_discarding = m_discarding;
678 const bool has_message = !m_pending.empty();
679 m_escaped = false;
680 m_discarding = false;
681 if (broken) {
682 m_pending.clear();
683 ++report.discarded;
684 report.fault = FrameFault::Invalid;
685 } else if (!was_discarding && has_message) {
686 const detail::ClearOnExit guard { m_pending };
687 sink(Message { m_pending });
688 ++report.messages;
689 } else {
690 m_pending.clear();
691 }
692 continue;
693 }
694
695 if (m_discarding) {
696 continue;
697 }
698
699 uint8_t value = byte;
700 if (m_escaped) {
701 m_escaped = false;
702 if (byte == escaped_end) {
703 value = end;
704 } else if (byte == escaped_escape) {
705 value = escape;
706 } else {
707 discard(FrameFault::Invalid);
708 continue;
709 }
710 } else if (byte == escape) {
711 m_escaped = true;
712 continue;
713 }
714
715 if (m_pending.size() >= m_max_message) {
716 discard(FrameFault::Oversized);
717 continue;
718 }
719 m_pending.push_back(value);
720 }
721
722 return report;
723 }
724
725 /** @brief Drop any partial frame and any discard in progress. */
726 void reset() noexcept
727 {
728 m_pending.clear();
729 m_escaped = false;
730 m_discarding = false;
731 }
732
733 /** @brief Decoded bytes held for a frame that has not ended. */
734 [[nodiscard]] size_t buffered() const noexcept { return m_pending.size(); }
735
736 static constexpr uint8_t end = 0xC0;
737 static constexpr uint8_t escape = 0xDB;
738 static constexpr uint8_t escaped_end = 0xDC;
739 static constexpr uint8_t escaped_escape = 0xDD;
740
741private:
742 std::vector<uint8_t> m_pending;
744 bool m_escaped { false };
745 bool m_discarding { false };
746};
747
748/**
749 * @brief Append a payload in SLIP, followed by 0xC0, to out.
750 *
751 * Any payload is accepted, an empty one included.
752 */
753inline void encode_slip(Message payload, std::vector<uint8_t>& out)
754{
755 for (const uint8_t byte : payload) {
756 if (byte == SlipFramer::end) {
757 out.push_back(SlipFramer::escape);
758 out.push_back(SlipFramer::escaped_end);
759 } else if (byte == SlipFramer::escape) {
760 out.push_back(SlipFramer::escape);
761 out.push_back(SlipFramer::escaped_escape);
762 } else {
763 out.push_back(byte);
764 }
765 }
766 out.push_back(SlipFramer::end);
767}
768
769/**
770 * @class IdleGapFramer
771 * @brief Messages ended by a quiet period on the line, as in Modbus RTU.
772 *
773 * The framer reads no clock. push() only gathers bytes, and the caller ends the
774 * message by calling flush() once gap() has passed with no further push(), for
775 * example from a timer re-armed on every chunk. A message longer than max_message is
776 * dropped with FrameFault::Oversized, and the rest of that burst is ignored until
777 * flush().
778 *
779 * Not thread safe: one thread at a time per framer, and flush() must not run
780 * concurrently with push().
781 */
783public:
784 explicit IdleGapFramer(std::chrono::microseconds gap, size_t max_message = default_max_line) noexcept
785 : m_gap(gap)
786 , m_max_message(max_message)
787 {
788 }
789
790 /** @brief How long the line must stay quiet before the caller calls flush(). */
791 [[nodiscard]] std::chrono::microseconds gap() const noexcept { return m_gap; }
792
793 template <MessageSink Sink>
794 FrameReport push(Message bytes, Sink&&)
795 {
796 FrameReport report;
797 if (m_discarding) {
798 return report;
799 }
800
801 if (m_pending.size() + bytes.size() > m_max_message) {
802 m_pending.clear();
803 m_discarding = true;
804 ++report.discarded;
806 return report;
807 }
808
809 m_pending.insert(m_pending.end(), bytes.begin(), bytes.end());
810 return report;
811 }
812
813 /** @brief End the message in progress, delivering it, or ending a discard. */
814 template <MessageSink Sink>
815 FrameReport flush(Sink&& sink)
816 {
817 FrameReport report;
818 const bool was_discarding = m_discarding;
819 m_discarding = false;
820 if (was_discarding || m_pending.empty()) {
821 return report;
822 }
823
824 const detail::ClearOnExit guard { m_pending };
825 sink(Message { m_pending });
826 ++report.messages;
827 return report;
828 }
829
830 /** @brief Drop any partial message and any discard in progress. */
831 void reset() noexcept
832 {
833 m_pending.clear();
834 m_discarding = false;
835 }
836
837 /** @brief Bytes held for a message that has not ended. */
838 [[nodiscard]] size_t buffered() const noexcept { return m_pending.size(); }
839
840private:
841 std::vector<uint8_t> m_pending;
842 std::chrono::microseconds m_gap;
844 bool m_discarding { false };
845};
846
847} // namespace MayaFlux::Transitive::Protocol
size_t buffered() const noexcept
Encoded bytes held for a frame that has not ended.
Definition Framing.hpp:590
void reset() noexcept
Drop any partial frame and any discard in progress.
Definition Framing.hpp:582
FrameReport push(Message bytes, Sink &&sink)
Definition Framing.hpp:538
CobsFramer(size_t max_frame=default_max_line) noexcept
Definition Framing.hpp:532
FrameReport push(Message bytes, Sink &&sink)
Definition Framing.hpp:398
void reset() noexcept
Drop any partial message and any discard in progress.
Definition Framing.hpp:437
size_t buffered() const noexcept
Bytes held for a message that has not ended.
Definition Framing.hpp:444
DelimiterFramer(std::span< const uint8_t > terminator, size_t max_message=default_max_line)
Definition Framing.hpp:383
DelimiterFramer(std::string_view terminator, size_t max_message=default_max_line)
Definition Framing.hpp:392
IdleGapFramer(std::chrono::microseconds gap, size_t max_message=default_max_line) noexcept
Definition Framing.hpp:784
void reset() noexcept
Drop any partial message and any discard in progress.
Definition Framing.hpp:831
FrameReport push(Message bytes, Sink &&)
Definition Framing.hpp:794
size_t buffered() const noexcept
Bytes held for a message that has not ended.
Definition Framing.hpp:838
FrameReport flush(Sink &&sink)
End the message in progress, delivering it, or ending a discard.
Definition Framing.hpp:815
std::chrono::microseconds gap() const noexcept
How long the line must stay quiet before the caller calls flush().
Definition Framing.hpp:791
LengthPrefixFramer(size_t max_payload=default_max_frame, bool reject_empty=false) noexcept
Definition Framing.hpp:205
FrameReport push(Message bytes, Sink &&sink)
Definition Framing.hpp:212
void reset() noexcept
Drop partial input and clear a terminal fault.
Definition Framing.hpp:273
bool broken() const noexcept
True after a terminal fault, until reset().
Definition Framing.hpp:283
std::array< uint8_t, header_size > m_header
Definition Framing.hpp:301
FrameReport fail(FrameReport &report, FrameFault fault) noexcept
Definition Framing.hpp:291
size_t buffered() const noexcept
Partial header bytes plus payload bytes held for a frame that has not completed.
Definition Framing.hpp:286
FrameReport push(Message bytes, Sink &&sink)
Definition Framing.hpp:120
static void deliver(Message line, Sink &sink, FrameReport &report)
Definition Framing.hpp:173
size_t buffered() const noexcept
Bytes held for a line that has not ended.
Definition Framing.hpp:169
LineFramer(size_t max_line=default_max_line) noexcept
Definition Framing.hpp:114
void reset() noexcept
Drop any partial line and any discard in progress.
Definition Framing.hpp:162
static constexpr uint8_t escaped_end
Definition Framing.hpp:738
size_t buffered() const noexcept
Decoded bytes held for a frame that has not ended.
Definition Framing.hpp:734
FrameReport push(Message bytes, Sink &&sink)
Definition Framing.hpp:662
static constexpr uint8_t escaped_escape
Definition Framing.hpp:739
void reset() noexcept
Drop any partial frame and any discard in progress.
Definition Framing.hpp:726
SlipFramer(size_t max_message=default_max_line) noexcept
Definition Framing.hpp:656
ClearOnExit & operator=(ClearOnExit &&)=delete
ClearOnExit(std::vector< uint8_t > &buffer) noexcept
Definition Framing.hpp:65
ClearOnExit & operator=(const ClearOnExit &)=delete
A callable that receives each complete message.
Definition Framing.hpp:18
void run()
Definition main.cpp:21
bool cobs_decode(Message frame, std::vector< uint8_t > &out)
Decode one COBS frame, without its zero delimiter.
Definition Framing.hpp:489
void append_be_u32(std::vector< uint8_t > &out, uint32_t value)
Definition Framing.hpp:87
uint32_t load_be_u32(const uint8_t *src) noexcept
Definition Framing.hpp:81
bool encode_line(Message payload, std::vector< uint8_t > &out)
Append a payload and its LF to out, in the form LineFramer reads back.
Definition Framing.hpp:318
void encode_cobs(Message payload, std::vector< uint8_t > &out)
Append a payload in COBS, followed by its zero delimiter, to out.
Definition Framing.hpp:604
void encode_slip(Message payload, std::vector< uint8_t > &out)
Append a payload in SLIP, followed by 0xC0, to out.
Definition Framing.hpp:753
bool encode_length_prefixed(Message payload, std::vector< uint8_t > &out, size_t max_payload=default_max_frame, bool reject_empty=false)
Append a length prefix and a payload to out, in the form LengthPrefixFramer reads back.
Definition Framing.hpp:337
bool encode_delimited(Message payload, Message terminator, std::vector< uint8_t > &out)
Append a payload and a terminator to out, in the form DelimiterFramer reads back.
Definition Framing.hpp:466
std::span< const uint8_t > Message
One complete message.
Definition Framing.hpp:8
constexpr size_t default_max_line
Definition Framing.hpp:20
constexpr size_t default_max_frame
Definition Framing.hpp:21
FrameFault
Why input was refused.
Definition Framing.hpp:30
std::string_view as_text(Message message) noexcept
View a message as text without copying.
Definition Framing.hpp:56
FrameReport push(Message bytes, Sink &&sink)
Definition Framing.hpp:357
The framer for raw streams: every push is one message, with nothing to reassemble.
Definition Framing.hpp:355