From 55e48ef1afef8216770c5a2deaaf80d2ae57d650 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dani=C3=ABl=20van=20Eeden?= <git@myname.nl>
Date: Mon, 10 Feb 2025 19:10:40 +0100
Subject: [PATCH] Document the network protocol part of SemiSync

---
 plugin/semisync/semisync.cc | 42 +++++++++++++++++++++++++++++++++++++
 sql/rpl_source.cc           |  5 +++++
 2 files changed, 47 insertions(+)

diff --git a/plugin/semisync/semisync.cc b/plugin/semisync/semisync.cc
index dc7997e55c49..e1b1f8285434 100644
--- a/plugin/semisync/semisync.cc
+++ b/plugin/semisync/semisync.cc
@@ -36,6 +36,48 @@ const unsigned long Trace::kTraceFunction = 0x0040;
 const unsigned char ReplSemiSyncBase::kSyncHeader[2] = {
     ReplSemiSyncBase::kPacketMagicNum, 0};
 
+/* clang-format off */
+/**
+  @page page_protocol_semisync Semisync
+
+  Semisync is a set of two plugins, a server one and a client one.
+  Both plugins enhance the replication protocol.
+
+  @section sect_semisync_source Semisync source
+
+  A source with semisync enabled will prepend binlog events with
+  a semisync request.
+
+  <table>
+  <caption>Semisync Request</caption>
+  <tr><th>Type</th><th>Name</th><th>Description</th></tr>
+  <tr><td>@ref a_protocol_type_int1 "int&lt;1&gt;"</td>
+      <td>semisync marker</td>
+      <td>Marker to indicate semisync</td></tr>
+  <tr><td>@ref a_protocol_type_int1 "int&lt;1&gt;"</td>
+      <td>semisync flag</td>
+      <td>Set to 0x1 to request semisync acknowledgement, otherwise 0x0.</td></tr>
+  </table>
+
+  @section sect_semisync_replica Semisync replica
+
+  A replica with semisync enabled will send acknowledgements to Semisync Requests
+
+  <table>
+  <caption>Semisync Request</caption>
+  <tr><th>Type</th><th>Name</th><th>Description</th></tr>
+  <tr><td>@ref a_protocol_type_int1 "int&lt;1&gt;"</td>
+      <td>semisync marker</td>
+      <td>Marker to indicate semisync</td></tr>
+  <tr><td>@ref a_protocol_type_int8 "int&lt;8&gt;"</td>
+      <td>Binlog Position</td>
+      <td>Binlog position of the acknowledgement.</td></tr>
+  <tr><td>@ref sect_protocol_basic_dt_string_eof "string[EOF]"</td>
+      <td>Binlog File Name</td>
+      <td>Binlog file name of the acknowledgement.</td></tr>
+  </table>
+*/
+
 bool is_sysvar_defined(const char *name) {
   char buffer[256];
   void *value = buffer;
diff --git a/sql/rpl_source.cc b/sql/rpl_source.cc
index 1efdbd2e3160..138cb36ab379 100644
--- a/sql/rpl_source.cc
+++ b/sql/rpl_source.cc
@@ -340,6 +340,11 @@ bool show_replicas(THD *thd) {
 
   In MySQL 5.1.x the @ref sect_protocol_replication_binlog_event_rbr were
   added.
+
+  @section sect_protocol_replication_semisync Semisync
+
+  See:
+  - @subpage page_protocol_semisync
 */
 
 /**