From 748124f20d1b152474dc3f2d597a3597461082b9 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Tue, 12 Nov 2024 15:55:28 +0700 Subject: [PATCH 1/9] Update iproto replication doc --- .../images/repl_fetch_snapshot_request.puml | 22 +++++++++ .../images/repl_fetch_snapshot_request.svg | 32 +++++++++++++ .../iproto/images/repl_join_request.puml | 3 +- .../iproto/images/repl_join_request.svg | 11 +++-- doc/reference/internals/iproto/keys.rst | 2 +- .../internals/iproto/replication.rst | 48 +++++++++++++++++-- 6 files changed, 108 insertions(+), 10 deletions(-) create mode 100644 doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml create mode 100644 doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg diff --git a/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml new file mode 100644 index 000000000..e58fc69ba --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml @@ -0,0 +1,22 @@ +@startuml + +skinparam { + HyperlinkColor #0077FF + FontColor #313131 + BorderColor #313131 + BackgroundColor transparent +} + +json "**IPROTO_FETCH_SNAPSHOT**" as fetch_snapshot_request { + "Size": "MP_UINT", + "Header": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_FETCH_SNAPSHOT", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" + }, + "Body": { + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INSTANCE_UUID]]": "MP_STR – UUID of this instance", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SERVER_VERSION]]": "MP_UINT – replica's version" + } +} + +@enduml diff --git a/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg new file mode 100644 index 000000000..30bf53ccb --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg @@ -0,0 +1,32 @@ +IPROTO_FETCH_SNAPSHOTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_FETCH_SNAPSHOTIPROTO_SYNCMP_UINTBodyIPROTO_INSTANCE_UUIDMP_STR - UUID of this instanceIPROTO_SERVER_VERSIONMP_UINT - replica's version \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_join_request.puml b/doc/reference/internals/iproto/images/repl_join_request.puml index 849f6ad47..b7841817e 100644 --- a/doc/reference/internals/iproto/images/repl_join_request.puml +++ b/doc/reference/internals/iproto/images/repl_join_request.puml @@ -14,7 +14,8 @@ json "**IPROTO_JOIN**" as join_request { "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" }, "Body": { - "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INSTANCE_UUID]]": "MP_STR – UUID of this instance" + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INSTANCE_UUID]]": "MP_STR – UUID of this instance", + "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SERVER_VERSION]]": "MP_UINT – replica's version" } } diff --git a/doc/reference/internals/iproto/images/repl_join_request.svg b/doc/reference/internals/iproto/images/repl_join_request.svg index 96b5fb6f9..aec1fb634 100644 --- a/doc/reference/internals/iproto/images/repl_join_request.svg +++ b/doc/reference/internals/iproto/images/repl_join_request.svg @@ -1,4 +1,4 @@ -IPROTO_JOINSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_JOINIPROTO_SYNCMP_UINTBodyIPROTO_INSTANCE_UUIDMP_STR - UUID of this instance \ No newline at end of file diff --git a/doc/reference/internals/iproto/images/repl_join_snapshot.svg b/doc/reference/internals/iproto/images/repl_join_snapshot.svg new file mode 100644 index 000000000..359b793d0 --- /dev/null +++ b/doc/reference/internals/iproto/images/repl_join_snapshot.svg @@ -0,0 +1,28 @@ +IPROTO_JOIN_SNAPSHOTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_JOIN_SNAPSHOTIPROTO_SYNCMP_UINT \ No newline at end of file From 5e66c2fccbc9c52ffb106d15fb172bc6b8895299 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 13 Nov 2024 17:07:30 +0700 Subject: [PATCH 6/9] Review fixes --- .../images/repl_fetch_snapshot_request.puml | 4 -- .../images/repl_fetch_snapshot_request.svg | 6 +-- .../iproto/images/repl_register.puml | 22 ++++++++ .../internals/iproto/images/repl_register.svg | 32 ++++++++++++ .../internals/iproto/replication.rst | 52 +++++++++++++------ 5 files changed, 92 insertions(+), 24 deletions(-) create mode 100644 doc/reference/internals/iproto/images/repl_register.puml create mode 100644 doc/reference/internals/iproto/images/repl_register.svg diff --git a/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml index e58fc69ba..5779ea724 100644 --- a/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml +++ b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.puml @@ -12,10 +12,6 @@ json "**IPROTO_FETCH_SNAPSHOT**" as fetch_snapshot_request { "Header": { "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_FETCH_SNAPSHOT", "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SYNC]]": "MP_UINT" - }, - "Body": { - "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_INSTANCE_UUID]]": "MP_STR – UUID of this instance", - "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_SERVER_VERSION]]": "MP_UINT – replica's version" } } diff --git a/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg index 30bf53ccb..240afb874 100644 --- a/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg +++ b/doc/reference/internals/iproto/images/repl_fetch_snapshot_request.svg @@ -1,4 +1,4 @@ -IPROTO_FETCH_SNAPSHOTSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_FETCH_SNAPSHOTIPROTO_SYNCMP_UINTBodyIPROTO_INSTANCE_UUIDMP_STR - UUID of this instanceIPROTO_SERVER_VERSIONMP_UINT - replica's version \ No newline at end of file diff --git a/doc/reference/internals/iproto/replication.rst b/doc/reference/internals/iproto/replication.rst index dbbffa06e..43416491d 100644 --- a/doc/reference/internals/iproto/replication.rst +++ b/doc/reference/internals/iproto/replication.rst @@ -52,11 +52,13 @@ General * - :ref:`IPROTO_JOIN_META ` - 0x47 - - A request sent in response to IPROTO_JOIN before the instance initialization information + - A request sent in response to IPROTO_JOIN or IPROTO_FETCH_SNAPSHOT + before the instance initialization information * - :ref:`IPROTO_JOIN_SNAPSHOT ` - 0x48 - - A request sent in response to IPROTO_JOIN after the instance initialization information + - A request sent in response to IPROTO_JOIN or IPROTO_FETCH_SNAPSHOT + after the instance initialization information The master also sends :ref:`heartbeat ` messages to the replicas. The heartbeat message's IPROTO_REQUEST_TYPE is ``0``. @@ -104,7 +106,7 @@ To join a replica set, an instance must send an initial IPROTO_JOIN request to a .. raw:: html :file: images/repl_join_request.svg -.. iproto_join_response_sequence_start +.. iproto_fetch_snapshot_response_sequence_start The instance that receives the request sends the following messages in response: @@ -128,16 +130,18 @@ The instance that receives the request sends the following messages in response: #. The new vclock's MP_MAP in a response similar to the one above. +.. iproto_join_response_sequence_end + #. A number of :ref:`INSERT `, :ref:`REPLACE `, :ref:`UPDATE `, :ref:`UPSERT `, and :ref:`DELETE ` requests. This way, the instance that is joining the replica set receives data updates that happened during the join stage. -#. The new vclock's MP_MAP in a response similar to the one above. After this, - the instance closes the socket. +#. The new vclock's MP_MAP in a response similar to the one above. + +Then the instance closes the socket. -.. iproto_join_response_sequence_end .. _internals-iproto-replication-subscribe: @@ -182,6 +186,8 @@ To learn about anonymous replicas, see :ref:`replication.anon `, :ref:`REPLACE `, + :ref:`UPDATE `, :ref:`UPSERT `, + and :ref:`DELETE ` requests. This way, the instance + that is registering in the replica set receives data updates that happened + since the time it fetched the snapshot. + +#. The new vclock's MP_MAP. + +Then the instance closes the socket. -TODO: request structure diagram +Technically, subsequent IPROTO_FETCH_SNAPSHOT and IPROTO_REGISTER requests are equivalent +to IPROTO_JOIN. .. _box_protocol-join-meta: @@ -201,10 +223,10 @@ IPROTO_JOIN_META Code: 0x47. -When an instance receives an IPOTO_JOIN request, its response includes information -required for the instance initialization: current Raft term, current state of -synchronous transaction queue. Before sending this information, the instance -sends an IPROTO_JOIN_META request with an empty body: +When an instance receives an IPOTO_JOIN or IPROTO_FETCH_SNAPSHOT request, its responses +include the information required for the instance initialization: current Raft term, +current state of synchronous transaction queue. Before sending this information, +the instance sends an IPROTO_JOIN_META request with an empty body: .. raw:: html :file: images/repl_join_meta.svg @@ -218,9 +240,9 @@ IPROTO_JOIN_SNAPSHOT Code: 0x48. -An instance that has received an IPROTO_JOIN request sends an IPROTO_JOIN_SNAPSHOT -request with an empty body after it completes sending the instance initialization -information. +An instance that has received an IPROTO_JOIN or IPROTO_FETCH_SNAPSHOT request +sends an IPROTO_JOIN_SNAPSHOT request with an empty body after it completes sending +the instance initialization information. .. raw:: html :file: images/repl_join_snapshot.svg From 22d87894260509743f02a97d1a47fc438abcb861 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 13 Nov 2024 17:26:57 +0700 Subject: [PATCH 7/9] Fix --- .../internals/iproto/replication.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/reference/internals/iproto/replication.rst b/doc/reference/internals/iproto/replication.rst index 43416491d..e30ea03db 100644 --- a/doc/reference/internals/iproto/replication.rst +++ b/doc/reference/internals/iproto/replication.rst @@ -64,7 +64,7 @@ The master also sends :ref:`heartbeat ` messages to the replicas. The heartbeat message's IPROTO_REQUEST_TYPE is ``0``. Below are details on individual replication requests. -For synchronous replication requests, see :ref:``. +For synchronous replication requests, see :ref:`internals-iproto-replication-synchronous`. .. _box_protocol-heartbeat: @@ -110,12 +110,12 @@ To join a replica set, an instance must send an initial IPROTO_JOIN request to a The instance that receives the request sends the following messages in response: -#. Its vclock: +1. Its vclock: .. raw:: html :file: images/repl_join_response.svg -#. (Optional) A sequence of requests with information required for instance initialization: +2. (Optional) A sequence of requests with information required for instance initialization: - an :ref:`IPROTO_JOIN_META ` request - an :ref:`IPROTO_RAFT ` request with IPROTO_RAFT_TERM and IPROTO_RAFT_VOTE fields @@ -124,21 +124,21 @@ The instance that receives the request sends the following messages in response: This step applies if the IPROTO_SERVER_VERSION specified in the request is `2.10` or later. -#. A number of :ref:`INSERT ` requests (with additional LSN and ServerID). +3. A number of :ref:`INSERT ` requests (with additional LSN and ServerID). This way, the data is updated on the instance that sent the IPROTO_JOIN request. The instance should not reply to these INSERT requests. -#. The new vclock's MP_MAP in a response similar to the one above. +4. The new vclock's MP_MAP in a response similar to the one above. -.. iproto_join_response_sequence_end +.. iproto_fetch_snapshot_response_sequence_end -#. A number of :ref:`INSERT `, :ref:`REPLACE `, +5. A number of :ref:`INSERT `, :ref:`REPLACE `, :ref:`UPDATE `, :ref:`UPSERT `, and :ref:`DELETE ` requests. This way, the instance that is joining the replica set receives data updates that happened during the join stage. -#. The new vclock's MP_MAP in a response similar to the one above. +6. The new vclock's MP_MAP in a response similar to the one above. Then the instance closes the socket. @@ -183,8 +183,8 @@ IPROTO_FETCH_SNAPSHOT request to any node in the replica set: To learn about anonymous replicas, see :ref:`replication.anon `. .. include:: replication.rst - :start-after: iproto_join_response_sequence_start - :end-before: iproto_join_response_sequence_end + :start-after: iproto_fetch_snapshot_response_sequence_start + :end-before: iproto_fetch_snapshot_response_sequence_end Then the instance closes the socket. From ea5705013a48fdcf3f817e588b79794e4d603d02 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Thu, 14 Nov 2024 14:50:55 +0700 Subject: [PATCH 8/9] Fix --- .../internals/iproto/images/repl_join_response.puml | 2 +- .../internals/iproto/images/repl_join_response.svg | 10 +++++----- doc/reference/internals/iproto/replication.rst | 5 +++-- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/reference/internals/iproto/images/repl_join_response.puml b/doc/reference/internals/iproto/images/repl_join_response.puml index 02ed8cfcf..9dee3ac72 100644 --- a/doc/reference/internals/iproto/images/repl_join_response.puml +++ b/doc/reference/internals/iproto/images/repl_join_response.puml @@ -7,7 +7,7 @@ skinparam { BackgroundColor transparent } -json "**Response to IPROTO_JOIN**" as join_response { +json "**Response to IPROTO_JOIN/IPROTO_FETCH_SNAPSHOT**" as join_response { "Size": "MP_UINT", "Header": { "[[https://tarantool.io/en/doc/latest/reference/internals/iproto/keys IPROTO_REQUEST_TYPE]]": "IPROTO_OK", diff --git a/doc/reference/internals/iproto/images/repl_join_response.svg b/doc/reference/internals/iproto/images/repl_join_response.svg index 84a817eb5..d0a3b1d10 100644 --- a/doc/reference/internals/iproto/images/repl_join_response.svg +++ b/doc/reference/internals/iproto/images/repl_join_response.svg @@ -1,4 +1,4 @@ -Response to IPROTO_JOINSizeMP_UINTHeaderIPROTO_REQUEST_TYPEIPROTO_OKIPROTO_SYNCMP_UINTBodyIPROTO_VCLOCKMP_MAP