A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
byte_chunking.h
Go to the documentation of this file.
1/*
2 * Copyright 2026 The A11 Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
25#ifndef A11_NET_BYTE_CHUNKING_H_
26#define A11_NET_BYTE_CHUNKING_H_
27
28#include <cstddef>
29#include <cstdint>
30#include <optional>
31#include <string>
32#include <string_view>
33#include <vector>
34
35#include <absl/base/nullability.h>
36#include <absl/status/status.h>
37#include <absl/status/statusor.h>
38
39namespace a11::net {
40
42inline constexpr size_t kMinimumBytePacketSize =
43 sizeof(std::uint64_t) + 2 * sizeof(std::uint32_t) + 2;
44
46enum class BytePacketType : std::uint8_t {
47 kCompleteBytes = 0x00,
48 kByteChunk = 0x01,
50};
51
53struct BytePacket {
55 std::string payload;
56 std::uint64_t transient_id = 0;
57 std::uint32_t sequence = 0;
58 std::uint32_t packet_count =
59 0;
60
61 template <typename Sink>
62 friend void AbslStringify(Sink& sink, const BytePacket& packet) {
63 sink.Append("BytePacket{type=");
64 sink.Append(packet.type == BytePacketType::kCompleteBytes ? "complete"
65 : packet.type == BytePacketType::kByteChunk ? "chunk"
66 : "first_chunk");
67 sink.Append(", id=");
68 sink.Append(packet.transient_id);
69 sink.Append(", sequence=");
70 sink.Append(packet.sequence);
71 sink.Append(", packet_count=");
72 sink.Append(packet.packet_count);
73 sink.Append(", payload_size=");
74 sink.Append(packet.payload.size());
75 sink.Append("}");
76 }
77};
78
81 size_t packet_size = 64 * 1024;
82 size_t max_message_size = 32 * 1024 * 1024;
85 64 * 1024 * 1024;
86
88 absl::Status Validate() const;
89};
90
92absl::StatusOr<std::vector<std::string>> SplitBytesIntoPackets(
93 std::string_view bytes, std::uint64_t transient_id, size_t packet_size);
100absl::StatusOr<std::vector<std::string>> SplitOwnedBytesIntoPackets(
101 std::string bytes, std::uint64_t transient_id, size_t packet_size);
103absl::StatusOr<BytePacket> ParseBytePacket(std::string_view packet);
109absl::StatusOr<BytePacket> ParseOwnedBytePacket(std::string packet);
110
120 public:
124
127
129 absl::StatusOr<std::optional<std::string>> Feed(std::string packet);
131 void Clear();
132
134 [[nodiscard]] size_t pending_message_count() const;
136 [[nodiscard]] size_t pending_byte_count() const;
137
138 private:
139 struct Impl;
140 static constexpr size_t kImplSize = 256;
141 static constexpr size_t kImplAlignment = alignof(std::max_align_t);
142
143 Impl* absl_nonnull GetImpl();
144 [[nodiscard]] const Impl* absl_nonnull GetImpl() const;
145
146 alignas(kImplAlignment) std::byte impl_[kImplSize];
147};
148
149} // namespace a11::net
150
151#endif // A11_NET_BYTE_CHUNKING_H_
Bounded, thread-safe reassembly for interleaved binary messages.
Definition byte_chunking.h:119
size_t pending_message_count() const
Number of message ids currently awaiting more packets.
Definition byte_chunking.cc:384
ByteReassembler(const ByteReassembler &)=delete
ByteReassembler & operator=(const ByteReassembler &)=delete
absl::StatusOr< std::optional< std::string > > Feed(std::string packet)
Admit one packet and return a complete message when this finishes one.
Definition byte_chunking.cc:273
size_t pending_byte_count() const
Aggregate payload bytes retained by incomplete messages.
Definition byte_chunking.cc:390
~ByteReassembler()
Definition byte_chunking.cc:261
void Clear()
Discard every incomplete message, for example when a channel aborts.
Definition byte_chunking.cc:377
Definition action.h:66
absl::StatusOr< BytePacket > ParseOwnedBytePacket(std::string packet)
Parse one packet, reusing its buffer as the payload.
Definition byte_chunking.cc:231
absl::StatusOr< std::vector< std::string > > SplitOwnedBytesIntoPackets(std::string bytes, std::uint64_t transient_id, size_t packet_size)
Split bytes the caller owns, reusing the buffer when it fits a packet.
Definition byte_chunking.cc:206
absl::StatusOr< BytePacket > ParseBytePacket(std::string_view packet)
Parse and validate one packet without retaining the input view.
Definition byte_chunking.cc:223
BytePacketType
Packet shapes in the A11 byte-chunking wire format.
Definition byte_chunking.h:46
constexpr size_t kMinimumBytePacketSize
Smallest packet that holds framing metadata and one payload byte.
Definition byte_chunking.h:42
absl::StatusOr< std::vector< std::string > > SplitBytesIntoPackets(std::string_view bytes, std::uint64_t transient_id, size_t packet_size)
Split bytes into A11 packets with fixed little-endian suffixes.
Definition byte_chunking.cc:114
stores::ChunkStoreReaderOptions options
Definition runtime_streams.cc:31
Bounds packet size and incomplete-message memory during reassembly.
Definition byte_chunking.h:80
size_t packet_size
Maximum encoded packet size.
Definition byte_chunking.h:81
size_t max_pending_messages
Simultaneous incomplete messages.
Definition byte_chunking.h:83
size_t max_message_size
Reassembled message limit.
Definition byte_chunking.h:82
size_t max_pending_bytes
Aggregate pending payload limit.
Definition byte_chunking.h:84
absl::Status Validate() const
Validate that all limits can represent at least one useful packet.
Definition byte_chunking.cc:97
Parsed packet metadata plus the owned piece of application payload.
Definition byte_chunking.h:53
std::uint32_t sequence
Zero-based position in the message.
Definition byte_chunking.h:57
BytePacketType type
Packet shape.
Definition byte_chunking.h:54
std::uint32_t packet_count
Total count, when supplied by the first packet.
Definition byte_chunking.h:58
std::string payload
Bytes contributed by this packet.
Definition byte_chunking.h:55
std::uint64_t transient_id
Definition byte_chunking.h:56
friend void AbslStringify(Sink &sink, const BytePacket &packet)
Definition byte_chunking.h:62
Definition byte_chunking.cc:240