json_util.h

Go to the documentation of this file.

#pragma once
 
#include <algorithm>
#include <cstddef>
#include <cstring>
#include <string>
#include <utility>
#include <vector>
 
#include "esphome/core/defines.h"
#include "esphome/core/helpers.h"
#include "esphome/core/progmem.h"
 
#define ARDUINOJSON_ENABLE_STD_STRING 1  // NOLINT
 
#define ARDUINOJSON_USE_LONG_LONG 1  // NOLINT
 
#include <ArduinoJson.h>
 
namespace esphome::json {
 
// Link a string into the document instead of copying it. Only for a literal, a codegen table
// entry or a name set once during setup; never a stack buffer or an entity state.
inline JsonString linked(const char *s) { return JsonString(s, true); }
inline JsonString linked(const char *s, size_t len) { return JsonString(s, len, true); }
inline JsonString linked(const std::string &s) { return JsonString(s.c_str(), s.size(), true); }
JsonString linked(std::string &&) = delete;  // a temporary dies before the document is serialized
#ifdef USE_ESP8266
// A PROGMEM string is copied out of flash
inline ProgmemStr linked(ProgmemStr s) { return s; }
#endif
 
template<size_t STACK_SIZE = 640> class SerializationBuffer {
 public:
  static constexpr size_t BUFFER_SIZE = STACK_SIZE;  
 
  explicit SerializationBuffer(size_t size) : size_(size) {
    if (size + 1 <= STACK_SIZE) {
      buffer_ = stack_buffer_;
    } else {
      heap_buffer_ = new char[size + 1];
      buffer_ = heap_buffer_;
    }
    buffer_[0] = '\0';
  }
 
  ~SerializationBuffer() { delete[] heap_buffer_; }
 
  // Move constructor - works with same template instantiation
  SerializationBuffer(SerializationBuffer &&other) noexcept
      : heap_buffer_(std::exchange(other.heap_buffer_, nullptr)), size_(other.size_) {
    if (other.buffer_ == other.stack_buffer_) {
      // Stack buffer - must copy content
      std::memcpy(stack_buffer_, other.stack_buffer_, size_ + 1);
      buffer_ = stack_buffer_;
    } else {
      // Heap buffer - ownership was taken above
      buffer_ = heap_buffer_;
    }
    // Leave moved-from object in valid empty state
    other.stack_buffer_[0] = '\0';
    other.buffer_ = other.stack_buffer_;
    other.size_ = 0;
  }
 
  // Move assignment
  SerializationBuffer &operator=(SerializationBuffer &&other) noexcept {
    if (this != &other) {
      delete[] heap_buffer_;
      heap_buffer_ = std::exchange(other.heap_buffer_, nullptr);
      size_ = other.size_;
      if (other.buffer_ == other.stack_buffer_) {
        std::memcpy(stack_buffer_, other.stack_buffer_, size_ + 1);
        buffer_ = stack_buffer_;
      } else {
        buffer_ = heap_buffer_;
      }
      // Leave moved-from object in valid empty state
      other.stack_buffer_[0] = '\0';
      other.buffer_ = other.stack_buffer_;
      other.size_ = 0;
    }
    return *this;
  }
 
  // Delete copy operations
  SerializationBuffer(const SerializationBuffer &) = delete;
  SerializationBuffer &operator=(const SerializationBuffer &) = delete;
 
  const char *c_str() const { return buffer_; }
  const char *data() const { return buffer_; }
  size_t size() const { return size_; }
 
  operator std::string() const { return std::string(buffer_, size_); }  // NOLINT(google-explicit-constructor)
 
 private:
  friend class JsonBuilder;  
 
  char *data_writable_() { return buffer_; }
  void set_size_(size_t size) {
    size_ = size;
    buffer_[size] = '\0';
  }
 
  void reallocate_heap_(size_t size) {
    delete[] heap_buffer_;
    heap_buffer_ = new char[size + 1];
    buffer_ = heap_buffer_;
    size_ = size;
    buffer_[0] = '\0';
  }
 
  char stack_buffer_[STACK_SIZE];
  char *heap_buffer_{nullptr};
  char *buffer_;
  size_t size_;
};
 
#ifdef USE_PSRAM
// Build an allocator for the JSON Library using the RAMAllocator class
// This is only compiled when PSRAM is enabled
struct SpiRamAllocator : ArduinoJson::Allocator {
  void *allocate(size_t size) override {
    RAMAllocator<uint8_t> allocator;
    return allocator.allocate(size);
  }
 
  void deallocate(void *ptr) override {
    // ArduinoJson's Allocator interface doesn't provide the size parameter in deallocate.
    // RAMAllocator::deallocate() requires the size, which we don't have access to here.
    // RAMAllocator::deallocate implementation just calls free() regardless of whether
    // the memory was allocated with heap_caps_malloc or malloc.
    // This is safe because ESP-IDF's heap implementation internally tracks the memory region
    // and routes free() to the appropriate heap.
    free(ptr);  // NOLINT(cppcoreguidelines-owning-memory,cppcoreguidelines-no-malloc)
  }
 
  void *reallocate(void *ptr, size_t new_size) override {
    RAMAllocator<uint8_t> allocator;
    return allocator.reallocate(static_cast<uint8_t *>(ptr), new_size);
  }
};
#endif
 
using json_parse_t = std::function<bool(JsonObject)>;
 
using json_build_t = std::function<void(JsonObject)>;
 
SerializationBuffer<> build_json(const json_build_t &f);
 
bool parse_json(const std::string &data, const json_parse_t &f);
bool parse_json(const uint8_t *data, size_t len, const json_parse_t &f);
 
JsonDocument parse_json(const uint8_t *data, size_t len);
inline JsonDocument parse_json(const std::string &data) {
  return parse_json(reinterpret_cast<const uint8_t *>(data.c_str()), data.size());
}
 
ArduinoJson::Allocator *heap_json_allocator();
 
#ifdef USE_JSON_ARENA
constexpr size_t JSON_POOL_BYTES = ARDUINOJSON_POOL_CAPACITY * sizeof(ArduinoJson::detail::VariantData);
constexpr size_t JSON_ARENA_SIZE = JSON_POOL_BYTES + 1152;
static_assert(sizeof(void *) != 4 || JSON_ARENA_SIZE == 2176, "the arena was sized for a 1 KB pool");
 
template<size_t N> class JsonArena final : public ArduinoJson::Allocator {
 public:
  // Takes what the buffer cannot hold
  explicit JsonArena(ArduinoJson::Allocator *fallback = heap_json_allocator()) : fallback_(fallback) {}
  // The document points into buf_
  JsonArena(const JsonArena &) = delete;
  JsonArena &operator=(const JsonArena &) = delete;
 
  void *allocate(size_t size) override {
    if (size > N) {
      return this->fallback_->allocate(size);  // also keeps the rounding below from wrapping
    }
    size = (size + ALIGN - 1) & ~(ALIGN - 1);
    if (size > N - this->used_) {
      return this->fallback_->allocate(size);
    }
    this->last_ = this->used_;
    this->used_ += size;
    return this->buf_ + this->last_;
  }
  void deallocate(void *ptr) override {
    if (!this->owns_(ptr)) {
      this->fallback_->deallocate(ptr);
    }
  }
  void *reallocate(void *ptr, size_t new_size) override {
    if (!this->owns_(ptr)) {
      return this->fallback_->reallocate(ptr, new_size);
    }
    const size_t off = static_cast<uint8_t *>(ptr) - this->buf_;
    const size_t size = new_size > N ? N + ALIGN : (new_size + ALIGN - 1) & ~(ALIGN - 1);
    const bool newest = off == this->last_;
    if (newest && size <= N - off) {
      this->used_ = off + size;  // the newest block grows or shrinks in place
      return ptr;
    }
    // An older block's size is unknown; copying to the end of the buffer stays in bounds
    const size_t old_size = newest ? this->used_ - off : N - off;
    void *moved = this->fallback_->allocate(new_size);
    if (moved == nullptr) {
      return nullptr;  // the caller keeps ptr, so its arena space stays reserved
    }
    std::memcpy(moved, ptr, std::min(new_size, old_size));
    if (newest) {
      this->used_ = off;  // it moved to the heap, so its arena space is free again
    }
    return moved;
  }
  size_t used() const { return this->used_; }
 
 private:
  static constexpr size_t ALIGN = alignof(std::max_align_t);
  bool owns_(const void *ptr) const { return ptr >= this->buf_ && ptr < this->buf_ + N; }
  ArduinoJson::Allocator *fallback_;
  alignas(ALIGN) uint8_t buf_[N];
  size_t used_{0};
  size_t last_{0};
};
#endif  // USE_JSON_ARENA
 
class JsonBuilder {
 public:
  // Out of line: inlining the JsonDocument constructor duplicates it at every call site
  JsonBuilder();
#ifdef USE_JSON_ARENA
  // The builder must not outlive the allocator
  explicit JsonBuilder(ArduinoJson::Allocator *allocator);
#endif
 
  JsonObject root() {
    if (!root_created_) {
      root_ = doc_.to<JsonObject>();
      root_created_ = true;
    }
    return root_;
  }
 
  size_t serialize_to(char *buf, size_t cap);
 
  SerializationBuffer<> serialize();
 
 private:
  JsonDocument doc_;
  JsonObject root_;
  bool root_created_{false};
};
 
}  // namespace esphome::json