serialization.h

Go to the documentation of this file.

/*
 * Copyright 2026 The A11 Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef A11_DATA_SERIALIZATION_H_
#define A11_DATA_SERIALIZATION_H_
 
#include <any>
#include <cstddef>
#include <functional>
#include <string>
#include <string_view>
#include <typeindex>
#include <typeinfo>
#include <utility>
#include <vector>
 
#include <absl/base/nullability.h>
#include <absl/status/status.h>
#include <absl/status/status_macros.h>
#include <absl/status/statusor.h>
#include <absl/strings/str_cat.h>
 
#include "a11/data/types.h"
#include "a11/exception_guard.h"
 
namespace a11::data {
 
inline constexpr std::string_view kJsonMimetype = "application/json";
inline constexpr std::string_view kMsgpackMimetype = "application/x-msgpack";
inline constexpr std::string_view kTextMimetype = "text/plain";
inline constexpr std::string_view kBytesMimetype = "application/octet-stream";
 
class SerializationRegistry;
 
template <typename T>
class TypedChunkObject final : public ChunkObject {
 public:
  TypedChunkObject(T value, std::string tag, std::string mimetype,
                   std::shared_ptr<const SerializationRegistry> registry)
      : value_(std::move(value)),
        tag_(std::move(tag)),
        mimetype_(std::move(mimetype)),
        registry_(std::move(registry)) {}
 
  [[nodiscard]] std::string_view tag() const override { return tag_; }
 
  [[nodiscard]] std::string_view mimetype() const override { return mimetype_; }
 
  [[nodiscard]] const void* absl_nonnull address() const override {
    return &value_;
  }
 
  [[nodiscard]] absl::StatusOr<Bytes> Encode() const override;
 
  [[nodiscard]] size_t ApproxBytes() const override {
    // A stand-in, not a measurement: this is called for buffer accounting on
    // every put, and encoding the value to find its size would be the cost the
    // whole mechanism exists to avoid.
    return sizeof(T) + 64;
  }
 
 private:
  const T value_;
  const std::string tag_;
  const std::string mimetype_;
  const std::shared_ptr<const SerializationRegistry> registry_;
};
 
template <typename T>
std::optional<T> TryTakeObject(const Chunk& chunk, std::string_view tag) {
  if (chunk.object == nullptr || chunk.object->tag() != tag) {
    return std::nullopt;
  }
  // Sound because the tags matched, and tags are unique per type across four
  // languages by construction. This is the only cast of address() anywhere.
  return *static_cast<const T*>(chunk.object->address());
}
 
class SerializationRegistry {
 public:
  explicit SerializationRegistry(bool register_defaults = false);
  ~SerializationRegistry();
 
  SerializationRegistry(const SerializationRegistry&) = delete;
  SerializationRegistry& operator=(const SerializationRegistry&) = delete;
 
  template <typename T>
  using Serializer = std::function<absl::StatusOr<Chunk>(const T&)>;
 
  template <typename T>
  using Deserializer = std::function<absl::StatusOr<T>(const Chunk&)>;
 
  template <typename T>
  absl::Status RegisterSerializer(std::string type_name,
                                  const std::string& mimetype,
                                  Serializer<T> serializer) {
    if (!serializer) {
      return absl::InvalidArgumentError("serializer must be callable");
    }
    return RegisterSerializerErased(
        typeid(T), std::move(type_name), mimetype,
        [serializer = std::move(serializer)](
            const void* absl_nonnull value) -> absl::StatusOr<Chunk> {
          if (value == nullptr) {
            return absl::InvalidArgumentError("serializer value is null");
          }
          // Guarded here, in the translation unit that registered the codec,
          // because that is the one that owns it: if the codec can throw, this
          // instantiation was compiled with exceptions and catches it.
          absl::StatusOr<Chunk> chunk;
          absl::Status raised = exception_guard::Attempt(
              [&] { chunk = serializer(*static_cast<const T*>(value)); },
              "serializer");
          if (!raised.ok()) {
            return raised;
          }
          return chunk;
        });
  }
 
  template <typename T>
  absl::Status RegisterDeserializer(std::string type_name,
                                    const std::string& mimetype,
                                    Deserializer<T> deserializer) {
    if (!deserializer) {
      return absl::InvalidArgumentError("deserializer must be callable");
    }
    return RegisterDeserializerErased(
        typeid(T), std::move(type_name), mimetype,
        [deserializer = std::move(deserializer)](
            const Chunk& chunk) -> absl::StatusOr<std::any> {
          // See RegisterSerializer above for why the guard sits here.
          absl::StatusOr<T> result;
          absl::Status raised = exception_guard::Attempt(
              [&] { result = deserializer(chunk); }, "deserializer");
          if (!raised.ok()) {
            return raised;
          }
          if (!result.ok()) {
            return result.status();
          }
          return std::any(std::move(*result));
        });
  }
 
  template <typename T>
  absl::Status Register(const std::string& type_name,
                        const std::string& mimetype, Serializer<T> serializer,
                        Deserializer<T> deserializer) {
    ABSL_RETURN_IF_ERROR(
        RegisterSerializer<T>(type_name, mimetype, std::move(serializer)));
    absl::Status status =
        RegisterDeserializer<T>(type_name, mimetype, std::move(deserializer));
    if (!status.ok()) {
      RemoveSerializer(typeid(T), type_name, mimetype);
      return status;
    }
    return absl::OkStatus();
  }
 
  template <typename T>
  absl::StatusOr<Chunk> ToChunk(const T& value,
                                std::string_view mimetype = {}) const {
    return ToChunkErased(typeid(T), &value, mimetype);
  }
 
  template <typename T>
  absl::StatusOr<T> FromChunk(
      const Chunk& chunk,
      const std::vector<std::string>& mimetype_patterns = {}) const {
    ABSL_ASSIGN_OR_RETURN(std::any result,
                          FromChunkErased(chunk, typeid(T), mimetype_patterns));
    // The pointer form, which reports a mismatch by returning null rather than
    // by raising.
    T* absl_nullable value = std::any_cast<T>(&result);
    if (value == nullptr) {
      return absl::InternalError(
          absl::StrCat("A deserializer produced ", result.type().name(),
                       ", which is not the requested ", typeid(T).name()));
    }
    return std::move(*value);
  }
 
  absl::Status RegisterDefaults();
  [[nodiscard]] size_t serializer_count() const;
  [[nodiscard]] size_t deserializer_count() const;
 
 private:
  using ErasedSerializer =
      std::function<absl::StatusOr<Chunk>(const void* absl_nonnull value)>;
  using ErasedDeserializer =
      std::function<absl::StatusOr<std::any>(const Chunk& chunk)>;
 
  struct SerializerRegistration;
  struct DeserializerRegistration;
  struct Impl;
 
  static constexpr size_t kImplSize = 192;
  static constexpr size_t kImplAlignment = alignof(std::max_align_t);
 
  Impl* absl_nonnull GetImpl();
  [[nodiscard]] const Impl* absl_nonnull GetImpl() const;
 
  absl::Status RegisterSerializerErased(std::type_index type,
                                        std::string type_name,
                                        const std::string& mimetype,
                                        ErasedSerializer serializer);
  absl::Status RegisterDeserializerErased(std::type_index type,
                                          std::string type_name,
                                          const std::string& mimetype,
                                          ErasedDeserializer deserializer);
  void RemoveSerializer(std::type_index type, std::string_view type_name,
                        std::string_view mimetype);
 
  absl::StatusOr<Chunk> ToChunkErased(std::type_index type,
                                      const void* absl_nonnull value,
                                      std::string_view mimetype) const;
  absl::StatusOr<std::any> FromChunkErased(
      const Chunk& chunk, std::type_index requested_type,
      const std::vector<std::string>& mimetype_patterns) const;
 
  alignas(kImplAlignment) std::byte impl_[kImplSize];
};
 
SerializationRegistry& GlobalSerializationRegistry();
 
template <typename T>
absl::StatusOr<Bytes> TypedChunkObject<T>::Encode() const {
  if (registry_ == nullptr) {
    return absl::FailedPreconditionError(
        absl::StrCat("a chunk carrying a ", tag_,
                     " was asked for its bytes, but no serialization registry "
                     "came with it"));
  }
  ABSL_ASSIGN_OR_RETURN(Chunk encoded,
                        registry_->ToChunk<T>(value_, mimetype_));
  return std::move(encoded.data);
}
 
template <typename T>
Chunk MakeChunkObject(T value, std::string tag, std::string mimetype,
                      std::shared_ptr<const SerializationRegistry> registry) {
  Chunk chunk;
  // The mimetype is set even though the bytes are not: it is what selects a
  // codec, what a `| mime "text/*"` stage filters on, and what tells a reader
  // what it is about to get.
  chunk.metadata = ChunkMetadata{.mimetype = mimetype};
  chunk.object = std::make_shared<const TypedChunkObject<T>>(
      std::move(value), std::move(tag), std::move(mimetype),
      std::move(registry));
  return chunk;
}
 
}  // namespace a11::data
 
#endif  // A11_DATA_SERIALIZATION_H_