16007: Add comment about override_edge_* parameters

Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <peter.amstutz@curii.com>

diff --git a/services/api/db/migrate/20200501150153_permission_table.rb b/services/api/db/migrate/20200501150153_permission_table.rb
index 4d7bc25ba66b60c27facb5a6a006f73b343a4070..77944eb6ee823e210ee2de2f8c6bf0fcd08a4e1a 100644 (file)
--- a/services/api/db/migrate/20200501150153_permission_table.rb
+++ b/services/api/db/migrate/20200501150153_permission_table.rb
@@ -156,6 +156,13 @@ as $$
   at can_manage but when traversing a can_read link everything
   touched through that link will only be can_read).
 
+  When revoking a permission, we follow the chain of permissions but
+  with a permissions level of 0.  The update on the permissions table
+  has to happen _before_ the permission is actually removed, because
+  we need to be able to traverse the edge before it goes away.  When
+  we do that, we also need to traverse it at the _new_ permission
+  level - this is what override_edge_tail/head/perm are for.
+
   Yields the set of objects that are potentially affected, and
   their permission levels granted by having starting_perm on
   starting_uuid.

diff --git a/services/api/db/structure.sql b/services/api/db/structure.sql
index 508d90757c89f540000bc89b592d0b7d3d756c06..eaa3d6299a685e0c9d23cb57d067ce9735290d02 100644 (file)
--- a/services/api/db/structure.sql
+++ b/services/api/db/structure.sql
@@ -257,6 +257,13 @@ CREATE FUNCTION public.search_permission_graph(starting_uuid character varying,
   at can_manage but when traversing a can_read link everything
   touched through that link will only be can_read).
 
+  When revoking a permission, we follow the chain of permissions but
+  with a permissions level of 0.  The update on the permissions table
+  has to happen _before_ the permission is actually removed, because
+  we need to be able to traverse the edge before it goes away.  When
+  we do that, we also need to traverse it at the _new_ permission
+  level - this is what override_edge_tail/head/perm are for.
+
   Yields the set of objects that are potentially affected, and
   their permission levels granted by having starting_perm on
   starting_uuid.