From c625a607479dc5771b44022e5a65d3b878941bcd Mon Sep 17 00:00:00 2001
From: chronolaw <chrono_cpp@me.com>
Date: Sun, 27 Oct 2024 14:26:49 +0800
Subject: [PATCH] sync comments clean

---
 kong/clustering/services/sync/rpc.lua              |  9 +++++++--
 .../services/sync/strategies/postgres.lua          |  4 ++--
 kong/db/declarative/import.lua                     | 14 +++++++++++---
 3 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/kong/clustering/services/sync/rpc.lua b/kong/clustering/services/sync/rpc.lua
index 921adf3b3835..978a355fb1a2 100644
--- a/kong/clustering/services/sync/rpc.lua
+++ b/kong/clustering/services/sync/rpc.lua
@@ -17,7 +17,6 @@ local CLUSTERING_SYNC_STATUS = constants.CLUSTERING_SYNC_STATUS
 local SYNC_MUTEX_OPTS = { name = "get_delta", timeout = 0, }
 
 
-local pairs = pairs
 local ipairs = ipairs
 local fmt = string.format
 local ngx_null = ngx.null
@@ -44,7 +43,8 @@ function _M:init_cp(manager)
   -- CP
   -- Method: kong.sync.v2.get_delta
   -- Params: versions: list of current versions of the database
-  -- { { namespace = "default", version = 1000, }, }
+  --
+  -- example: { default = { version = 1000, }, }
   local purge_delay = manager.conf.cluster_data_plane_purge_delay
 
   local function gen_delta_result(res, wipe)
@@ -195,6 +195,9 @@ local function do_sync()
     return true
   end
 
+  -- ns_deltas should look like:
+  -- { default = { deltas = { ... }, wipe = true, }, }
+
   local ns_delta = ns_deltas.default
   if not ns_delta then
     return nil, "default namespace does not exist inside params"
@@ -233,6 +236,8 @@ local function do_sync()
   local crud_events = {}
   local crud_events_n = 0
 
+  -- delta should look like:
+  -- { type = ..., row = { ... }, version = 1, ws_id = ..., }
   for _, delta in ipairs(deltas) do
     local delta_type = delta.type
     local delta_row = delta.row
diff --git a/kong/clustering/services/sync/strategies/postgres.lua b/kong/clustering/services/sync/strategies/postgres.lua
index 1169a2d626d0..589b9f025047 100644
--- a/kong/clustering/services/sync/strategies/postgres.lua
+++ b/kong/clustering/services/sync/strategies/postgres.lua
@@ -93,14 +93,14 @@ end
 
 
 function _M:get_latest_version()
-  local sql = "SELECT MAX(version) AS max_version FROM clustering_sync_version"
+  local sql = "SELECT MAX(version) FROM clustering_sync_version"
 
   local res, err = self.connector:query(sql)
   if not res then
     return nil, err
   end
 
-  local ver = res[1] and res[1].max_version
+  local ver = res[1] and res[1].max
   if ver == ngx_null then
     return 0
   end
diff --git a/kong/db/declarative/import.lua b/kong/db/declarative/import.lua
index f90f6452bfe4..3d6e30c05160 100644
--- a/kong/db/declarative/import.lua
+++ b/kong/db/declarative/import.lua
@@ -383,10 +383,18 @@ end
 -- the provided LMDB txn object, this operation is only safe
 -- is the entity does not already exist inside the LMDB database
 --
+-- The actual item key is: <entity_name>|<ws_id>|*|<pk_string>
+--
 -- This function sets the following:
--- * <entity_name>|<ws_id>|*|<pk_string> => serialized item
--- * <entity_name>|<ws_id>|<unique_field_name>|sha256(field_value) => <entity_name>|<ws_id>|*|<pk_string>
--- * <entity_name>|<ws_id>|<foreign_field_name>|<foreign_key>|<pk_string> -> <entity_name>|<ws_id>|*|<pk_string>
+--
+-- * <entity_name>|*|*|<pk_string> => serialized item
+-- * <entity_name>|<ws_id>|*|<pk_string> => actual item key
+--
+-- * <entity_name>|*|<unique_field_name>|sha256(field_value) => actual item key
+-- * <entity_name>|<ws_id>|<unique_field_name>|sha256(field_value) => actual item key
+--
+-- * <entity_name>|*|<foreign_field_name>|<foreign_key>|<pk_string> => actual item key
+-- * <entity_name>|<ws_id>|<foreign_field_name>|<foreign_key>|<pk_string> => actual item key
 --
 -- DO NOT touch `item`, or else the entity will be changed
 local function insert_entity_for_txn(t, entity_name, item, options)