[#2408] Documented the conflict status code usage

7 files changed, 43 insertions, 16 deletions

diff --git a/doc/sphinx/api2doc.py b/doc/sphinx/api2doc.py
index 4318fd2c62..de56d8c33e 100755
--- a/doc/sphinx/api2doc.py
+++ b/doc/sphinx/api2doc.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright (C) 2019-2021 Internet Systems Consortium, Inc. ("ISC")
+# Copyright (C) 2019-2022 Internet Systems Consortium, Inc. ("ISC")
 #
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -181,7 +181,8 @@ API Reference
             rst += '- 0 - success\n'
             rst += '- 1 - error\n'
             rst += '- 2 - unsupported\n'
-            rst += '- 3 - empty (command was completed successfully, but no data was affected or returned)\n\n'
+            rst += '- 3 - empty (command was completed successfully, but no data was affected or returned)\n'
+            rst += '- 4 - conflict (command could not apply requested configuration changes because they were in conflict with the server state)\n\n'
 
     return rst
 
diff --git a/doc/sphinx/arm/ctrl-channel.rst b/doc/sphinx/arm/ctrl-channel.rst
index ed41b2a73d..3375c1cf10 100644
--- a/doc/sphinx/arm/ctrl-channel.rst
+++ b/doc/sphinx/arm/ctrl-channel.rst
@@ -141,7 +141,7 @@ form:
 ::
 
    {
-       "result": 0|1|2|3,
+       "result": 0|1|2|3|4,
        "text": "textual description",
        "arguments": {
            "argument1": "value1",
@@ -150,16 +150,30 @@ form:
        }
    }
 
-``result`` indicates the outcome of the command. A value of 0 means
-success, while any non-zero value designates an error or a failure to
-complete the requested action. Currently 1 indicates a generic error, 2
-means that a command is not supported, and 3 means that the requested
-operation was completed, but the requested object was not found. For
-example, a well-formed command that requests a subnet that exists in a
-server's configuration returns the result 0. If the server encounters an
-error condition, it returns 1. If the command asks for the IPv6 subnet,
+``result`` value is a status code indicating a result of the command. The
+following general status codes are currently supported:
+
+-  ``0`` - the command has been processed successfully.
+-  ``1`` - a general error or failure has occurred during the command processing.
+-  ``2`` - specified command is unsupported by the server receiving it.
+-  ``3`` - the requested operation has been completed but the requested
+   resource was not found. This status code is returned when a command
+   returns no resources or affects no resources.
+-  ``4`` - the well-formed command has been processed but the requested
+   changes could not be applied because they were in conflict with the
+   server state or its notion of the configuration.
+
+For example, a well-formed command that requests a subnet that exists
+in a server's configuration returns the result 0. If the server encounters
+an error condition, it returns 1. If the command asks for the IPv6 subnet,
 but was sent to a DHCPv4 server, it returns 2. If the query asks for a
-``subnet-id`` and there is no subnet with such an ID, the result is 3.
+subnet with ``subnet-id`` that matches no subnets, the result is 3.
+If the command attempts to update a lease but the specified ``subnet-id``
+does not match the identifier in the server's configuration, the result
+is 4.
+
+Hook libraries can sometimes return some additional status codes specific
+to their use cases.
 
 The ``text`` field typically appears when the result is non-zero and
 contains a description of the error encountered, but it often also
@@ -204,7 +218,7 @@ to one service would be structured as follows:
 
     [
         {
-            "result": 0|1|2|3,
+            "result": 0|1|2|3|4,
             "text": "textual description",
             "arguments": {
                 "argument1": "value1",
@@ -221,7 +235,7 @@ contain responses from each service, in the order they were requested:
 
     [
         {
-            "result": 0|1|2|3,
+            "result": 0|1|2|3|4,
             "text": "textual description",
             "arguments": {
                 "argument1": "value1",
@@ -229,7 +243,7 @@ contain responses from each service, in the order they were requested:
             ...
         },
         {
-            "result": 0|1|2|3,
+            "result": 0|1|2|3|4,
             "text": "textual description",
             "arguments": {
                 "argument1": "value1",
diff --git a/src/share/api/lease4-add.json b/src/share/api/lease4-add.json
index c7fbca291d..3e6e83444e 100644
--- a/src/share/api/lease4-add.json
+++ b/src/share/api/lease4-add.json
@@ -19,6 +19,9 @@
     "description": "See <xref linkend=\"idp64\"/>",
     "hook": "lease_cmds",
     "name": "lease4-add",
+    "resp-comment": [
+        "If the returned result is equal to 4, it indicates that the lease could not be created because it was in conflict with the server's state or its notion of the configuration. The High Availability hook library can handle such a result differently than a general error. A general error of 1 can indicate issues with processing the command, database availability etc."
+    ],
     "support": [
         "kea-dhcp4"
     ]
diff --git a/src/share/api/lease4-update.json b/src/share/api/lease4-update.json
index 4cb65fa961..5b3c09e173 100644
--- a/src/share/api/lease4-update.json
+++ b/src/share/api/lease4-update.json
@@ -19,6 +19,9 @@
     "description": "See <xref linkend=\"idp62\"/>",
     "hook": "lease_cmds",
     "name": "lease4-update",
+    "resp-comment": [
+        "If the returned result is equal to 4, it indicates that the lease could not be updated because it was in conflict with the server's state or its notion of the configuration. The High Availability hook library can handle such a result differently than a general error. A general error of 1 can indicate issues with processing the command, database availability etc."
+    ],
     "support": [
         "kea-dhcp4"
     ]
diff --git a/src/share/api/lease6-add.json b/src/share/api/lease6-add.json
index 5c4ba5abfa..2760c422b3 100644
--- a/src/share/api/lease6-add.json
+++ b/src/share/api/lease6-add.json
@@ -26,6 +26,9 @@
         "or",
         "{ \"result\": 1, \"text\": \"missing parameter 'ip-address' (<string>:3:19)\" }"
     ],
+    "resp-comment": [
+        "If the returned result is equal to 4, it indicates that the lease could not be created because it was in conflict with the server's state or its notion of the configuration. The High Availability hook library can handle such a result differently than a general error. A general error of 1 can indicate issues with processing the command, database availability etc."
+    ],
     "support": [
         "kea-dhcp6"
     ]
diff --git a/src/share/api/lease6-bulk-apply.json b/src/share/api/lease6-bulk-apply.json
index 2958e41830..db86b655d0 100644
--- a/src/share/api/lease6-bulk-apply.json
+++ b/src/share/api/lease6-bulk-apply.json
@@ -43,7 +43,7 @@
     "hook": "lease_cmds",
     "name": "lease6-bulk-apply",
     "resp-comment": [
-        "The \"failed-deleted-leases\" holds the list of leases which failed to delete; this includes leases which were not found in the database. The \"failed-leases\" includes the list of leases which failed to create or update. For each lease for which there was an error during processing, insertion into the database, etc., the result is set to 1. For each lease which was not deleted because the server did not find it in the database, the result of 3 is returned."
+        "The \"failed-deleted-leases\" holds the list of leases which failed to delete; this includes leases which were not found in the database. The \"failed-leases\" includes the list of leases which failed to create or update. For each lease for which there was an error during processing, insertion into the database, etc., the result is set to 1. If an error occurs due to a conflict between the lease and the server's configuration or state, the result of 4 is returned instead of 1. For each lease which was not deleted because the server did not find it in the database, the result of 3 is returned."
     ],
     "resp-syntax": [
         "{",
diff --git a/src/share/api/lease6-update.json b/src/share/api/lease6-update.json
index b0c871ce13..0c27104c57 100644
--- a/src/share/api/lease6-update.json
+++ b/src/share/api/lease6-update.json
@@ -21,6 +21,9 @@
     "description": "See <xref linkend=\"idp62\"/>",
     "hook": "lease_cmds",
     "name": "lease6-update",
+    "resp-comment": [
+        "If the returned result is equal to 4, it indicates that the lease could not be updated because it was in conflict with the server's state or its notion of the configuration. The High Availability hook library can handle such a result differently than a general error. A general error of 1 can indicate issues with processing the command, database availability etc."
+    ],
     "support": [
         "kea-dhcp6"
     ]