[#2408] Documented the conflict status code usage

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
 

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
+``result`` value is a status code indicating a result of the command. The
-success, while any non-zero value designates an error or a failure to
+following general status codes are currently supported:
-complete the requested action. Currently 1 indicates a generic error, 2
+
-means that a command is not supported, and 3 means that the requested
+-  ``0`` - the command has been processed successfully.
-operation was completed, but the requested object was not found. For
+-  ``1`` - a general error or failure has occurred during the command processing.
-example, a well-formed command that requests a subnet that exists in a
+-  ``2`` - specified command is unsupported by the server receiving it.
-server's configuration returns the result 0. If the server encounters an
+-  ``3`` - the requested operation has been completed but the requested
-error condition, it returns 1. If the command asks for the IPv6 subnet,
+   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",

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"
     ]

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"
     ]

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"
     ]

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": [
         "{",

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"
     ]