[PATCH pve-access-control v6 1/8] permission: add acl tree node parent lookup without node creation

[David Riley <d.riley@proxmox.com>]

Add helper function to look up ACL nodes by path without creating
missing nodes along the path. This is necessary for safely locating
paths intended for deletion or migration without side effects.

This is in preparation for the following SDN resource ACL pruning and
VNet migration changes.

Signed-off-by: David Riley <d.riley@proxmox.com>
Reviewed-by: Stefan Hanreich <s.hanreich@proxmox.com>
Tested-by: Stefan Hanreich <s.hanreich@proxmox.com>
---

Notes:
    Difference from v5:
    * The comment for find_acl_tree_node_parent now uses the POD
      format.

 src/PVE/AccessControl.pm | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/src/PVE/AccessControl.pm b/src/PVE/AccessControl.pm
index 0d632b3..a47495e 100644
--- a/src/PVE/AccessControl.pm
+++ b/src/PVE/AccessControl.pm
@@ -1000,6 +1000,37 @@ sub find_acl_tree_node {
     return $node;
 }
 
+=head3 find_acl_tree_node_parent($root, $path)
+
+Finds an ACL node by path C<$path> starting from the root node
+C<$root>, without autovivifying (creating) missing nodes.
+Returns a list containing the parent node, the final path
+segment, and the target node itself.
+
+=cut
+
+sub find_acl_tree_node_parent {
+    my ($root, $path) = @_;
+
+    my $current = $root;
+    my $parent = undef;
+    my $last_key = undef;
+
+    my @split_path = split('/', $path);
+
+    for my $segment (@split_path) {
+        if (defined($current->{children}) && defined($current->{children}->{$segment})) {
+            $parent = $current;
+            $last_key = $segment;
+            $current = $current->{children}->{$segment};
+        } else {
+            return (undef, undef, undef);
+        }
+    }
+
+    return ($parent, $last_key, $current);
+}
+
 sub add_user_group {
     my ($username, $usercfg, $group) = @_;
 
-- 
2.47.3