Adding upstream version 2.1.148.upstream/2.1.148upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 89 insertions, 19 deletions

diff --git a/src/parser_data.h b/src/parser_data.h
index 050ced3..feedb14 100644
--- a/src/parser_data.h
+++ b/src/parser_data.h
@@ -1,9 +1,10 @@
 /**
  * @file parser_data.h
  * @author Radek Krejci <rkrejci@cesnet.cz>
+ * @author Michal Vasko <mvasko@cesnet.cz>
  * @brief Data parsers for libyang
  *
- * Copyright (c) 2015-2020 CESNET, z.s.p.o.
+ * Copyright (c) 2015-2023 CESNET, z.s.p.o.
  *
  * This source code is licensed under BSD 3-Clause License (the "License").
  * You may not use this file except in compliance with the License.
@@ -156,9 +157,14 @@ struct ly_in;
                                                  modified manually. If this flag is used incorrectly (for unordered data),
                                                  the behavior is undefined and most functions executed with these
                                                  data will not work correctly. */
-#define LYD_PARSE_SUBTREE 0x400000          /**< Parse only the current data subtree with any descendants, no siblings.
+#define LYD_PARSE_SUBTREE 0x400000          /**< Parse only the first child item along with any descendants, but no
+                                                 siblings. This flag is not required when parsing data which do not
+                                                 start at the schema root; for that purpose, use lyd_parse_data's parent
+                                                 argument.
                                                  Also, a new return value ::LY_ENOT is returned if there is a sibling
-                                                 subtree following in the input data. */
+                                                 subtree following in the input data. Note that if validation is requested,
+                                                 only the newly parsed subtree is validated. This might result in
+                                                 an invalid datastore content. */
 #define LYD_PARSE_WHEN_TRUE 0x800000        /**< Mark all the parsed nodes dependend on a when condition with the flag
                                                  that means the condition was satisifed before. This allows for
                                                  auto-deletion of these nodes during validation. */
@@ -196,6 +202,15 @@ struct ly_in;
 #define LYD_VALIDATE_NO_STATE   0x0001      /**< Consider state data not allowed and raise an error if they are found.
                                                  Also, no implicit state data are added. */
 #define LYD_VALIDATE_PRESENT    0x0002      /**< Validate only modules whose data actually exist. */
+#define LYD_VALIDATE_MULTI_ERROR 0x0004     /**< Do not stop validation on the first error but generate all the detected errors. */
+#define LYD_VALIDATE_OPERATIONAL 0x0008     /**< Semantic constraint violations are reported only as warnings instead of
+                                                 errors (see [RFC 8342 sec. 5.3](https://datatracker.ietf.org/doc/html/rfc8342#section-5.3)). */
+#define LYD_VALIDATE_NO_DEFAULTS 0x0010     /**< Do not add any default nodes during validation, other implicit nodes
+                                                 (such as NP containers) are still added. Validation will fail if a
+                                                 default node is required for it to pass. */
+#define LYD_VALIDATE_NOT_FINAL 0x0020       /**< Skip final validation tasks that require for all the data nodes to
+                                                 either exist or not, based on the YANG constraints. Once the data
+                                                 satisfy this requirement, the final validation should be performed. */
 
 #define LYD_VALIDATE_OPTS_MASK  0x0000FFFF  /**< Mask for all the LYD_VALIDATE_* options. */
 
@@ -205,7 +220,8 @@ struct ly_in;
  * @brief Parse (and validate) data from the input handler as a YANG data tree.
  *
  * @param[in] ctx Context to connect with the tree being built here.
- * @param[in] parent Optional parent to connect the parsed nodes to.
+ * @param[in] parent Optional parent to connect the parsed nodes to. If provided, the data are expected to describe
+ * a subtree of the YANG model instead of starting at the schema root.
  * @param[in] in The input handle to provide the dumped data in the specified @p format to parse (and validate).
  * @param[in] format Format of the input data to be parsed. Can be 0 to try to detect format from the input handler.
  * @param[in] parse_options Options for parser, see @ref dataparseroptions.
@@ -213,6 +229,11 @@ struct ly_in;
  * @param[out] tree Full parsed data tree, note that NULL can be a valid tree. If @p parent is set, set to NULL.
  * @return LY_SUCCESS in case of successful parsing (and validation).
  * @return LY_ERR value in case of error. Additional error information can be obtained from the context using ly_err* functions.
+ *
+ * When parsing subtrees (i.e., when @p parent is non-NULL), validation is only performed on the newly parsed data.
+ * This might result in allowing invalid datastore content when the schema contains cross-branch constraints,
+ * complicated `must` statements, etc. When a full-datastore validation is desirable, parse all subtrees
+ * first, and then request validation of the complete datastore content.
  */
 LIBYANG_API_DECL LY_ERR lyd_parse_data(const struct ly_ctx *ctx, struct lyd_node *parent, struct ly_in *in, LYD_FORMAT format,
         uint32_t parse_options, uint32_t validate_options, struct lyd_node **tree);
@@ -303,26 +324,35 @@ LIBYANG_API_DECL LY_ERR lyd_parse_ext_data(const struct lysc_ext_instance *ext,
  * @{
  */
 enum lyd_type {
-    LYD_TYPE_DATA_YANG = 0, /* generic YANG instance data */
-    LYD_TYPE_RPC_YANG,      /* instance of a YANG RPC/action request with only "input" data children,
-                               including all parents in case of an action */
-    LYD_TYPE_NOTIF_YANG,    /* instance of a YANG notification, including all parents in case of a nested one */
-    LYD_TYPE_REPLY_YANG,    /* instance of a YANG RPC/action reply with only "output" data children,
-                               including all parents in case of an action */
+    LYD_TYPE_DATA_YANG = 0,     /* generic YANG instance data */
+    LYD_TYPE_RPC_YANG,          /* instance of a YANG RPC/action request with only "input" data children,
+                                   including all parents and optional top-level "action" element in case of an action */
+    LYD_TYPE_NOTIF_YANG,        /* instance of a YANG notification, including all parents in case of a nested one */
+    LYD_TYPE_REPLY_YANG,        /* instance of a YANG RPC/action reply with only "output" data children,
+                                   including all parents in case of an action */
+
+    LYD_TYPE_RPC_NETCONF,       /* complete NETCONF RPC invocation as defined for
+                                   [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and
+                                   [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */
+    LYD_TYPE_NOTIF_NETCONF,     /* complete NETCONF notification message as defined for
+                                   [notification](https://tools.ietf.org/html/rfc7950#section-7.16.2) */
+    LYD_TYPE_REPLY_NETCONF,     /* complete NETCONF RPC reply as defined for
+                                   [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and
+                                   [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */
 
-    LYD_TYPE_RPC_NETCONF,   /* complete NETCONF RPC invocation as defined for
-                               [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and
-                               [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */
-    LYD_TYPE_NOTIF_NETCONF, /* complete NETCONF notification message as defined for
-                               [notification](https://tools.ietf.org/html/rfc7950#section-7.16.2) */
-    LYD_TYPE_REPLY_NETCONF  /* complete NETCONF RPC reply as defined for
-                               [RPC](https://tools.ietf.org/html/rfc7950#section-7.14.4) and
-                               [action](https://tools.ietf.org/html/rfc7950#section-7.15.2) */
+    LYD_TYPE_RPC_RESTCONF,      /* message-body of a RESTCONF operation input parameters
+                                   ([ref](https://www.rfc-editor.org/rfc/rfc8040.html#section-3.6.1)) */
+    LYD_TYPE_NOTIF_RESTCONF,    /* RESTCONF JSON notification data
+                                   ([ref](https://www.rfc-editor.org/rfc/rfc8040.html#section-6.4)), to parse
+                                   a notification in XML, use ::LYD_TYPE_NOTIF_NETCONF */
+    LYD_TYPE_REPLY_RESTCONF     /* message-body of a RESTCONF operation output parameters
+                                   ([ref](https://www.rfc-editor.org/rfc/rfc8040.html#section-3.6.2)) */
 };
 /** @} datatype */
 
 /**
- * @brief Parse YANG data into an operation data tree.
+ * @brief Parse YANG data into an operation data tree. Specific parsing flags ::LYD_PARSE_ONLY, ::LYD_PARSE_STRICT and
+ * no validation flags are used.
  *
  * At least one of @p parent, @p tree, or @p op must always be set.
  *
@@ -349,6 +379,28 @@ enum lyd_type {
  *   - @p op - must be NULL, the reply is appended to the RPC;
  *   Note that there are 3 kinds of NETCONF replies - ok, error, and data. Only data reply appends any nodes to the RPC.
  *
+ * - ::LYD_TYPE_RPC_RESTCONF:
+ *   - @p parent - must be set, pointing to the invoked RPC operation (RPC or action) node;
+ *   - @p format - can be both ::LYD_JSON and ::LYD_XML;
+ *   - @p tree - must be provided, all the RESTCONF-specific JSON objects will be returned here as
+ *               a separate opaque data tree, even if the function fails, this may be returned;
+ *   - @p op - must be NULL, @p parent points to the operation;
+ *
+ * - ::LYD_TYPE_NOTIF_RESTCONF:
+ *   - @p parent - must be NULL, the whole notification is expected;
+ *   - @p format - must be ::LYD_JSON, XML-formatted notifications are parsed using ::LYD_TYPE_NOTIF_NETCONF;
+ *   - @p tree - must be provided, all the RESTCONF-specific JSON objects will be returned here as
+ *               a separate opaque data tree, even if the function fails, this may be returned;
+ *   - @p op - must be provided, the notification data tree itself will be returned here, pointing to the operation;
+ *
+ * - ::LYD_TYPE_REPLY_RESTCONF:
+ *   - @p parent - must be set, pointing to the invoked RPC operation (RPC or action) node;
+ *   - @p format - can be both ::LYD_JSON and ::LYD_XML;
+ *   - @p tree - must be provided, all the RESTCONF-specific JSON objects will be returned here as
+ *               a separate opaque data tree, even if the function fails, this may be returned;
+ *   - @p op - must be NULL, @p parent points to the operation;
+ *   Note that error reply should be parsed as 'yang-data' extension data.
+ *
  * @param[in] ctx libyang context.
  * @param[in] parent Optional parent to connect the parsed nodes to.
  * @param[in] in Input handle to read the input from.
@@ -427,6 +479,10 @@ LIBYANG_API_DECL LY_ERR lyd_validate_all(struct lyd_node **tree, const struct ly
  * The data tree is modified in-place. As a result of the validation, some data might be removed
  * from the tree. In that case, the removed items are freed, not just unlinked.
  *
+ * If several modules need to be validated, the flag ::LYD_VALIDATE_NOT_FINAL should be used first for validation
+ * of each module and then ::lyd_validate_module_final() should be called also for each module. Otherwise,
+ * false-positive validation errors for foreign dependencies may occur.
+ *
  * @param[in,out] tree Data tree to recursively validate. May be changed by validation, might become NULL.
  * @param[in] module Module whose data (and schema restrictions) to validate.
  * @param[in] val_opts Validation options (@ref datavalidationoptions).
@@ -438,6 +494,20 @@ LIBYANG_API_DECL LY_ERR lyd_validate_module(struct lyd_node **tree, const struct
         struct lyd_node **diff);
 
 /**
+ * @brief Finish validation of a module data that have previously been validated with ::LYD_VALIDATE_NOT_FINAL flag.
+ *
+ * This final validation will not add or remove any nodes.
+ *
+ * @param[in] tree Data tree to recursively validate.
+ * @param[in] module Module whose data (and schema restrictions) to validate.
+ * @param[in] val_opts Validation options (@ref datavalidationoptions).
+ * @return LY_SUCCESS on success.
+ * @return LY_ERR error on error.
+ */
+LIBYANG_API_DECL LY_ERR lyd_validate_module_final(struct lyd_node *tree, const struct lys_module *module,
+        uint32_t val_opts);
+
+/**
  * @brief Validate an RPC/action request, reply, or notification. Only the operation data tree (input/output/notif)
  * is validate, any parents are ignored.
  *