A11 (C++ runtime)
Native C++ implementation of the A11 streaming action runtime
Loading...
Searching...
No Matches
serialization.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
29#ifndef A11_DATA_SERIALIZATION_H_
30#define A11_DATA_SERIALIZATION_H_
31
32#include <any>
33#include <cstddef>
34#include <functional>
35#include <string>
36#include <string_view>
37#include <typeindex>
38#include <typeinfo>
39#include <utility>
40#include <vector>
41
42#include <absl/base/nullability.h>
43#include <absl/status/status.h>
44#include <absl/status/status_macros.h>
45#include <absl/status/statusor.h>
46#include <absl/strings/str_cat.h>
47
48#include "a11/data/types.h"
49#include "a11/exception_guard.h"
50
51namespace a11::data {
52
54inline constexpr std::string_view kJsonMimetype = "application/json";
56inline constexpr std::string_view kMsgpackMimetype = "application/x-msgpack";
65inline constexpr std::string_view kTextMimetype = "text/plain";
75inline constexpr std::string_view kBytesMimetype = "application/octet-stream";
76
87
100template <typename T>
101class TypedChunkObject final : public ChunkObject {
102 public:
103 TypedChunkObject(T value, std::string tag, std::string mimetype,
104 std::shared_ptr<const SerializationRegistry> registry)
105 : value_(std::move(value)),
106 tag_(std::move(tag)),
107 mimetype_(std::move(mimetype)),
108 registry_(std::move(registry)) {}
109
110 [[nodiscard]] std::string_view tag() const override { return tag_; }
111
112 [[nodiscard]] std::string_view mimetype() const override { return mimetype_; }
113
114 [[nodiscard]] const void* absl_nonnull address() const override {
115 return &value_;
116 }
117
118 [[nodiscard]] const T& value() const { return value_; }
119
120 [[nodiscard]] absl::StatusOr<Bytes> Encode() const override;
121
122 [[nodiscard]] size_t ApproxBytes() const override {
123 // A stand-in, not a measurement: this is called for buffer accounting on
124 // every put, and encoding the value to find its size would be the cost the
125 // whole mechanism exists to avoid.
126 return sizeof(T) + 64;
127 }
128
129 private:
130 const T value_;
131 const std::string tag_;
132 const std::string mimetype_;
133 const std::shared_ptr<const SerializationRegistry> registry_;
134};
135
143template <typename T>
144std::optional<T> TryTakeObject(const Chunk& chunk, std::string_view tag) {
145 if (chunk.object == nullptr || chunk.object->tag() != tag) {
146 return std::nullopt;
147 }
148 const auto* typed =
149 dynamic_cast<const TypedChunkObject<T>*>(chunk.object.get());
150 return typed == nullptr ? std::nullopt : std::optional<T>(typed->value());
151}
152
154 public:
160 explicit SerializationRegistry(bool register_defaults = false);
162
165
167 template <typename T>
168 using Serializer = std::function<absl::StatusOr<Chunk>(const T&)>;
169
171 template <typename T>
172 using Deserializer = std::function<absl::StatusOr<T>(const Chunk&)>;
173
183 template <typename T>
184 absl::Status RegisterSerializer(std::string_view type_name,
185 std::string_view mimetype,
186 Serializer<T> serializer) {
187 if (!serializer) {
188 return absl::InvalidArgumentError("serializer must be callable");
189 }
190 return RegisterSerializerErased(
191 typeid(T), type_name, mimetype,
192 [serializer = std::move(serializer)](
193 const void* absl_nonnull value) -> absl::StatusOr<Chunk> {
194 if (value == nullptr) {
195 return absl::InvalidArgumentError("serializer value is null");
196 }
197 // Guarded here, in the translation unit that registered the codec,
198 // because that is the one that owns it: if the codec can throw, this
199 // instantiation was compiled with exceptions and catches it.
200 absl::StatusOr<Chunk> chunk;
201 absl::Status raised = exception_guard::Attempt(
202 [&] { chunk = serializer(*static_cast<const T*>(value)); },
203 "serializer");
204 if (!raised.ok()) {
205 return raised;
206 }
207 return chunk;
208 });
209 }
210
220 template <typename T>
221 absl::Status RegisterDeserializer(std::string_view type_name,
222 std::string_view mimetype,
223 Deserializer<T> deserializer) {
224 if (!deserializer) {
225 return absl::InvalidArgumentError("deserializer must be callable");
226 }
227 return RegisterDeserializerErased(
228 typeid(T), type_name, mimetype,
229 [deserializer = std::move(deserializer)](
230 const Chunk& chunk) -> absl::StatusOr<std::any> {
231 // See RegisterSerializer above for why the guard sits here.
232 absl::StatusOr<T> result;
233 absl::Status raised = exception_guard::Attempt(
234 [&] { result = deserializer(chunk); }, "deserializer");
235 if (!raised.ok()) {
236 return raised;
237 }
238 if (!result.ok()) {
239 return result.status();
240 }
241 return std::any(std::move(*result));
242 });
243 }
244
259 template <typename T>
260 absl::Status Register(std::string_view type_name, std::string_view mimetype,
261 Serializer<T> serializer,
262 Deserializer<T> deserializer) {
263 ABSL_RETURN_IF_ERROR(
264 RegisterSerializer<T>(type_name, mimetype, std::move(serializer)));
265 absl::Status status =
266 RegisterDeserializer<T>(type_name, mimetype, std::move(deserializer));
267 if (!status.ok()) {
268 RemoveSerializer(typeid(T), type_name, mimetype);
269 return status;
270 }
271 return absl::OkStatus();
272 }
273
282 template <typename T>
283 absl::StatusOr<Chunk> ToChunk(const T& value,
284 std::string_view mimetype = {}) const {
285 return ToChunkErased(typeid(T), &value, mimetype);
286 }
287
299 template <typename T>
300 absl::StatusOr<T> FromChunk(
301 const Chunk& chunk,
302 const std::vector<std::string>& mimetype_patterns = {}) const {
303 ABSL_ASSIGN_OR_RETURN(std::any result,
304 FromChunkErased(chunk, typeid(T), mimetype_patterns));
305 // The pointer form, which reports a mismatch by returning null rather than
306 // by raising.
307 T* absl_nullable value = std::any_cast<T>(&result);
308 if (value == nullptr) {
309 return absl::InternalError(
310 absl::StrCat("A deserializer produced ", result.type().name(),
311 ", which is not the requested ", typeid(T).name()));
312 }
313 return std::move(*value);
314 }
315
317 absl::Status RegisterDefaults();
319 [[nodiscard]] size_t serializer_count() const;
321 [[nodiscard]] size_t deserializer_count() const;
322
323 private:
324 using ErasedSerializer =
325 std::function<absl::StatusOr<Chunk>(const void* absl_nonnull value)>;
326 using ErasedDeserializer =
327 std::function<absl::StatusOr<std::any>(const Chunk& chunk)>;
328
329 struct SerializerRegistration;
330 struct DeserializerRegistration;
331 struct Impl;
332
333 static constexpr size_t kImplSize = 192;
334 static constexpr size_t kImplAlignment = alignof(std::max_align_t);
335
336 Impl* absl_nonnull GetImpl();
337 [[nodiscard]] const Impl* absl_nonnull GetImpl() const;
338
339 absl::Status RegisterSerializerErased(std::type_index type,
340 std::string_view type_name,
341 std::string_view mimetype,
342 ErasedSerializer serializer);
343 absl::Status RegisterDeserializerErased(std::type_index type,
344 std::string_view type_name,
345 std::string_view mimetype,
346 ErasedDeserializer deserializer);
347 void RemoveSerializer(std::type_index type, std::string_view type_name,
348 std::string_view mimetype);
349
350 absl::StatusOr<Chunk> ToChunkErased(std::type_index type,
351 const void* absl_nonnull value,
352 std::string_view mimetype) const;
353 absl::StatusOr<std::any> FromChunkErased(
354 const Chunk& chunk, std::type_index requested_type,
355 const std::vector<std::string>& mimetype_patterns) const;
356
357 alignas(kImplAlignment) std::byte impl_[kImplSize];
358};
359
361SerializationRegistry& GlobalSerializationRegistry();
362
363template <typename T>
364absl::StatusOr<Bytes> TypedChunkObject<T>::Encode() const {
365 if (registry_ == nullptr) {
366 return absl::FailedPreconditionError(
367 absl::StrCat("a chunk carrying a ", tag_,
368 " was asked for its bytes, but no serialization registry "
369 "came with it"));
370 }
371 ABSL_ASSIGN_OR_RETURN(Chunk encoded,
372 registry_->ToChunk<T>(value_, mimetype_));
373 return std::move(encoded.data);
374}
375
386template <typename T>
387Chunk MakeChunkObject(T value, std::string tag, std::string mimetype,
388 std::shared_ptr<const SerializationRegistry> registry) {
389 Chunk chunk;
390 // The mimetype is set even though the bytes are not: it is what selects a
391 // codec, what a `| mime "text/*"` stage filters on, and what tells a reader
392 // what it is about to get.
394 chunk.object = std::make_shared<const TypedChunkObject<T>>(
395 std::move(value), std::move(tag), std::move(mimetype),
396 std::move(registry));
397 return chunk;
398}
399
400} // namespace a11::data
401
402#endif // A11_DATA_SERIALIZATION_H_
a11::Promise< a11::Unit > result
Definition async_node.cc:56
An in-process value a chunk may carry instead of its encoded bytes.
Definition types.h:140
Definition serialization.h:153
absl::Status RegisterDefaults()
Installs the standard JSON and MessagePack codecs.
Definition serialization.cc:493
size_t serializer_count() const
Number of registered serializers.
Definition serialization.cc:511
std::function< absl::StatusOr< Chunk >(const T &)> Serializer
Callable turning a T into a Chunk.
Definition serialization.h:168
SerializationRegistry & operator=(const SerializationRegistry &)=delete
std::function< absl::StatusOr< T >(const Chunk &)> Deserializer
Callable reconstructing a T from a Chunk.
Definition serialization.h:172
absl::StatusOr< Chunk > ToChunk(const T &value, std::string_view mimetype={}) const
Serializes value into a Chunk.
Definition serialization.h:283
absl::Status RegisterSerializer(std::string_view type_name, std::string_view mimetype, Serializer< T > serializer)
Registers a serializer for type T and an exact media type.
Definition serialization.h:184
size_t deserializer_count() const
Number of registered deserializers.
Definition serialization.cc:517
absl::Status Register(std::string_view type_name, std::string_view mimetype, Serializer< T > serializer, Deserializer< T > deserializer)
Atomically registers a serializer/deserializer pair for T.
Definition serialization.h:260
~SerializationRegistry()
Definition serialization.cc:275
absl::Status RegisterDeserializer(std::string_view type_name, std::string_view mimetype, Deserializer< T > deserializer)
Registers a deserializer for type T and an exact media type.
Definition serialization.h:221
absl::StatusOr< T > FromChunk(const Chunk &chunk, const std::vector< std::string > &mimetype_patterns={}) const
Deserializes chunk into a value of type T.
Definition serialization.h:300
SerializationRegistry(const SerializationRegistry &)=delete
The local fast path: a value in a chunk, encoded only if needed.
Definition serialization.h:101
size_t ApproxBytes() const override
A size estimate that does not encode anything.
Definition serialization.h:122
std::string_view tag() const override
The serialisation tag of the held type.
Definition serialization.h:110
TypedChunkObject(T value, std::string tag, std::string mimetype, std::shared_ptr< const SerializationRegistry > registry)
Definition serialization.h:103
std::string_view mimetype() const override
The mimetype the value would be encoded as.
Definition serialization.h:112
absl::StatusOr< Bytes > Encode() const override
Encodes the value, for whoever needs bytes after all.
Definition serialization.h:364
const void *absl_nonnull address() const override
An opaque address supplied by the object implementation.
Definition serialization.h:114
const T & value() const
Definition serialization.h:118
std::string value
Definition discover.cc:100
Turns what a caller's callable throws into a Status, at the boundary.
std::string type
The type and what follows it: string required, list[a11.Chunk] stream.
Definition format.cc:52
Definition json.cc:35
constexpr std::string_view kBytesMimetype
Media type of opaque bytes carried as themselves.
Definition serialization.h:75
constexpr std::string_view kJsonMimetype
Media type of the built-in JSON codec.
Definition serialization.h:54
constexpr std::string_view kTextMimetype
Media type of UTF-8 text carried as itself.
Definition serialization.h:65
SerializationRegistry & GlobalSerializationRegistry()
Returns the process-wide registry (defaults pre-installed).
Definition serialization.cc:523
constexpr std::string_view kMsgpackMimetype
Media type of the built-in MessagePack codec.
Definition serialization.h:56
Chunk MakeChunkObject(T value, std::string tag, std::string mimetype, std::shared_ptr< const SerializationRegistry > registry)
Builds a chunk carrying value, with no bytes produced.
Definition serialization.h:387
std::optional< T > TryTakeObject(const Chunk &chunk, std::string_view tag)
Takes the value out of chunk, if it is carrying one of type T.
Definition serialization.h:144
absl::Status Attempt(Callable &&callable, std::string_view what)
Runs callable, reporting anything it throws as a Status.
Definition exception_guard.h:114
std::string mimetype
Definition sqlite_chunk_store.cc:191
Descriptive metadata attached to a a11::data::Chunk.
Definition types.h:74
std::string mimetype
Media type of the chunk payload.
Definition types.h:75
A unit of data: bytes plus optional descriptive metadata.
Definition types.h:173
std::optional< ChunkMetadata > metadata
Optional payload metadata.
Definition types.h:174
Bytes data
Inline byte payload.
Definition types.h:176
std::shared_ptr< const ChunkObject > object
The value this chunk stands for, when its bytes have not been produced.
Definition types.h:184
A11's core wire value types: chunks, node fragments and messages.