From 1c61bced03e68096fc467c5f806bff9f08373dcd Mon Sep 17 00:00:00 2001
From: Yonas Habteab <yonas.habteab@icinga.com>
Date: Thu, 3 Jul 2025 13:40:10 +0200
Subject: [PATCH] Introduce `AsyncJsonWriter` output adapter interface

---
 lib/base/json.cpp |  1 -
 lib/base/json.hpp | 30 ++++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/lib/base/json.cpp b/lib/base/json.cpp
index 56893308a..2d48970bb 100644
--- a/lib/base/json.cpp
+++ b/lib/base/json.cpp
@@ -11,7 +11,6 @@
 #include <bitset>
 #include <boost/exception_ptr.hpp>
 #include <cstdint>
-#include <json.hpp>
 #include <stack>
 #include <utility>
 #include <vector>
diff --git a/lib/base/json.hpp b/lib/base/json.hpp
index df0ea18a0..3df6e797e 100644
--- a/lib/base/json.hpp
+++ b/lib/base/json.hpp
@@ -4,10 +4,40 @@
 #define JSON_H
 
 #include "base/i2-base.hpp"
+#include <boost/asio/spawn.hpp>
+#include <json.hpp>
 
 namespace icinga
 {
 
+/**
+ * AsyncJsonWriter allows writing JSON data to any output stream asynchronously.
+ *
+ * All users of this class must ensure that the underlying output stream will not perform any asynchronous I/O
+ * operations when the @c write_character() or @c write_characters() methods are called. They shall only perform
+ * such ops when the @c JsonEncoder allows them to do so by calling the @c Flush() method.
+ *
+ * @ingroup base
+ */
+class AsyncJsonWriter : public nlohmann::detail::output_adapter_protocol<char>
+{
+public:
+	/**
+	 * Flush instructs the underlying output stream to write any buffered data to wherever it is supposed to go.
+	 *
+	 * The @c JsonEncoder allows the stream to even perform asynchronous operations in a safe manner by calling
+	 * this method with a dedicated @c boost::asio::yield_context object. The stream must not perform any async
+	 * I/O operations triggered by methods other than this one. Any attempt to do so will result in undefined behavior.
+	 *
+	 * However, this doesn't necessarily enforce the stream to really flush its data immediately, but it's up
+	 * to the implementation to do whatever it needs to. The encoder just gives it a chance to do so by calling
+	 * this method.
+	 *
+	 * @param yield The yield context to use for asynchronous operations.
+	 */
+	virtual void Flush(boost::asio::yield_context& yield) = 0;
+};
+
 class String;
 class Value;