✨(backend) allow masking documents from the list view

Once users have visited a document to which they have access,
they can't remove it from their list view anymore. Several
users reported that this is annoying because a document that
gets a lot of updates keeps popping up at the top of their list
view.

They want to be able to mask the document in a click. We propose
to add a "masked documents" section in the left side bar where the
masked documents can still be found.

src/backend/core/tests/documents/test_api_documents_favorite_list.py

@@ -41,8 +41,8 @@ def test_api_document_favorite_list_authenticated_with_favorite():
     client = APIClient()
     client.force_login(user)
 
-    # User don't have access to this document (e.g the user had access and this
-    # access was removed. It should not be in the favorite list anymore.
+    # If the user doesn't have access to this document (e.g the user had access
+    # and this access was removed), it should not be in the favorite list anymore.
     factories.DocumentFactory(favorited_by=[user])
 
     document = factories.UserDocumentAccessFactory(

src/backend/core/tests/documents/test_api_documents_list_filters.py

@@ -312,6 +312,84 @@ def test_api_documents_list_filter_is_favorite_invalid():
     assert len(results) == 5
 
 
+# Filters: is_masked
+
+
+def test_api_documents_list_filter_is_masked_true():
+    """
+    Authenticated users should be able to filter documents they marked as masked.
+    """
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    factories.DocumentFactory.create_batch(2, users=[user])
+    masked_documents = factories.DocumentFactory.create_batch(
+        3, users=[user], masked_by=[user]
+    )
+    unmasked_documents = factories.DocumentFactory.create_batch(2, users=[user])
+    for document in unmasked_documents:
+        models.LinkTrace.objects.create(document=document, user=user, is_masked=False)
+
+    response = client.get("/api/v1.0/documents/?is_masked=true")
+
+    assert response.status_code == 200
+    results = response.json()["results"]
+    assert len(results) == 3
+
+    # Ensure all results are marked as masked by the current user
+    masked_documents_ids = [str(doc.id) for doc in masked_documents]
+    for result in results:
+        assert result["id"] in masked_documents_ids
+
+
+def test_api_documents_list_filter_is_masked_false():
+    """
+    Authenticated users should be able to filter documents they didn't mark as masked.
+    """
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    factories.DocumentFactory.create_batch(2, users=[user])
+    masked_documents = factories.DocumentFactory.create_batch(
+        3, users=[user], masked_by=[user]
+    )
+    unmasked_documents = factories.DocumentFactory.create_batch(2, users=[user])
+    for document in unmasked_documents:
+        models.LinkTrace.objects.create(document=document, user=user, is_masked=False)
+
+    response = client.get("/api/v1.0/documents/?is_masked=false")
+
+    assert response.status_code == 200
+    results = response.json()["results"]
+    assert len(results) == 4
+
+    # Ensure all results are not marked as masked by the current user
+    masked_documents_ids = [str(doc.id) for doc in masked_documents]
+    for result in results:
+        assert result["id"] not in masked_documents_ids
+
+
+def test_api_documents_list_filter_is_masked_invalid():
+    """Filtering with an invalid `is_masked` value should do nothing."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    factories.DocumentFactory.create_batch(2, users=[user])
+    factories.DocumentFactory.create_batch(3, users=[user], masked_by=[user])
+    unmasked_documents = factories.DocumentFactory.create_batch(2, users=[user])
+    for document in unmasked_documents:
+        models.LinkTrace.objects.create(document=document, user=user, is_masked=False)
+
+    response = client.get("/api/v1.0/documents/?is_masked=invalid")
+
+    assert response.status_code == 200
+    results = response.json()["results"]
+    assert len(results) == 7
+
+
 # Filters: title
 
 

src/backend/core/tests/documents/test_api_documents_mask.py

@@ -0,0 +1,353 @@
+"""Test mask document API endpoint for users in impress's core app."""
+
+import pytest
+from rest_framework.test import APIClient
+
+from core import factories, models
+
+pytestmark = pytest.mark.django_db
+
+
+@pytest.mark.parametrize(
+    "reach",
+    [
+        "restricted",
+        "authenticated",
+        "public",
+    ],
+)
+@pytest.mark.parametrize("method", ["post", "delete"])
+def test_api_document_mask_anonymous_user(method, reach):
+    """Anonymous users should not be able to mask/unmask documents."""
+    document = factories.DocumentFactory(link_reach=reach)
+
+    response = getattr(APIClient(), method)(
+        f"/api/v1.0/documents/{document.id!s}/mask/"
+    )
+
+    assert response.status_code == 401
+    assert response.json() == {
+        "detail": "Authentication credentials were not provided."
+    }
+
+    # Verify in database
+    assert models.LinkTrace.objects.exists() is False
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_mask_authenticated_post_allowed(reach, has_role):
+    """Authenticated users should be able to mask a document to which they have access."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach=reach)
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+
+    # Try masking the document without a link trace
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/mask/")
+    assert response.status_code == 400
+    assert response.json() == {"detail": "User never accessed this document before."}
+    assert not models.LinkTrace.objects.filter(document=document, user=user).exists()
+
+    models.LinkTrace.objects.create(document=document, user=user)
+    # Mask document
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/mask/")
+
+    assert response.status_code == 201
+    assert response.json() == {"detail": "Document was masked"}
+    assert models.LinkTrace.objects.filter(
+        document=document, user=user, is_masked=True
+    ).exists()
+
+
+def test_api_document_mask_authenticated_post_forbidden():
+    """
+    Authenticated users should no be allowed to mask a document
+    to which they don't have access.
+    """
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach="restricted")
+
+    # Try masking
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/mask/")
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You do not have permission to perform this action."
+    }
+
+    # Verify in database
+    assert (
+        models.LinkTrace.objects.filter(document=document, user=user).exists() is False
+    )
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_mask_authenticated_post_already_masked_allowed(reach, has_role):
+    """POST should not create duplicate link trace if already marked."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach=reach, masked_by=[user])
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+
+    # Try masking again
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/mask/")
+
+    assert response.status_code == 200
+    assert response.json() == {"detail": "Document was already masked"}
+    assert models.LinkTrace.objects.filter(
+        document=document, user=user, is_masked=True
+    ).exists()
+
+
+def test_api_document_mask_authenticated_post_already_masked_forbidden():
+    """POST should not create duplicate masks if already marked."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach="restricted", masked_by=[user])
+    # Try masking again
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/mask/")
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You do not have permission to perform this action."
+    }
+    assert models.LinkTrace.objects.filter(document=document, user=user).exists()
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_mask_authenticated_post_unmasked_allowed(reach, has_role):
+    """POST should not create duplicate link trace if unmasked."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach=reach)
+    models.LinkTrace.objects.create(document=document, user=user, is_masked=False)
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+
+    # Try masking again
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/mask/")
+
+    assert response.status_code == 201
+    assert response.json() == {"detail": "Document was masked"}
+    assert models.LinkTrace.objects.filter(
+        document=document, user=user, is_masked=True
+    ).exists()
+
+
+def test_api_document_mask_authenticated_post_unmasked_forbidden():
+    """POST should not create duplicate masks if unmasked."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach="restricted")
+    models.LinkTrace.objects.create(document=document, user=user, is_masked=False)
+    # Try masking again
+    response = client.post(f"/api/v1.0/documents/{document.id!s}/mask/")
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You do not have permission to perform this action."
+    }
+    assert models.LinkTrace.objects.filter(
+        document=document, user=user, is_masked=False
+    ).exists()
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_mask_authenticated_delete_allowed(reach, has_role):
+    """Authenticated users should be able to unmask a document using DELETE."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach=reach, masked_by=[user])
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+
+    # Unmask document
+    response = client.delete(f"/api/v1.0/documents/{document.id!s}/mask/")
+
+    assert response.status_code == 204
+    assert response.content == b""  # No body
+    assert response.text == ""  # Empty decoded text
+    assert "Content-Type" not in response.headers  # No Content-Type for 204
+
+    assert models.LinkTrace.objects.filter(
+        document=document, user=user, is_masked=False
+    ).exists()
+
+
+def test_api_document_mask_authenticated_delete_forbidden():
+    """
+    Authenticated users should not be allowed to unmask a document if
+    they don't have access to it.
+    """
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach="restricted", masked_by=[user])
+
+    # Unmask document
+    response = client.delete(f"/api/v1.0/documents/{document.id!s}/mask/")
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You do not have permission to perform this action."
+    }
+    assert models.LinkTrace.objects.filter(
+        document=document, user=user, is_masked=True
+    ).exists()
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_mask_authenticated_delete_not_masked_allowed(reach, has_role):
+    """DELETE should be idempotent if the document is not masked."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach=reach)
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+
+    # Try unmasking the document without a link trace
+    response = client.delete(f"/api/v1.0/documents/{document.id!s}/mask/")
+    assert response.status_code == 400
+    assert response.json() == {"detail": "User never accessed this document before."}
+    assert not models.LinkTrace.objects.filter(document=document, user=user).exists()
+
+    models.LinkTrace.objects.create(document=document, user=user, is_masked=False)
+    # Unmask document
+    response = client.delete(f"/api/v1.0/documents/{document.id!s}/mask/")
+
+    assert response.status_code == 200
+    assert response.json() == {"detail": "Document was already not masked"}
+    assert models.LinkTrace.objects.filter(
+        document=document, user=user, is_masked=False
+    ).exists()
+
+
+def test_api_document_mask_authenticated_delete_not_masked_forbidden():
+    """DELETE should be idempotent if the document is not masked."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach="restricted")
+
+    # Try to unmask when no entry exists
+    response = client.delete(f"/api/v1.0/documents/{document.id!s}/mask/")
+
+    assert response.status_code == 403
+    assert response.json() == {
+        "detail": "You do not have permission to perform this action."
+    }
+    assert (
+        models.LinkTrace.objects.filter(document=document, user=user).exists() is False
+    )
+
+
+@pytest.mark.parametrize(
+    "reach, has_role",
+    [
+        ["restricted", True],
+        ["authenticated", False],
+        ["authenticated", True],
+        ["public", False],
+        ["public", True],
+    ],
+)
+def test_api_document_mask_authenticated_post_unmark_then_mark_again_allowed(
+    reach, has_role
+):
+    """A user should be able to mask, unmask, and mask a document again."""
+    user = factories.UserFactory()
+    client = APIClient()
+    client.force_login(user)
+
+    document = factories.DocumentFactory(link_reach=reach)
+    if has_role:
+        models.DocumentAccess.objects.create(document=document, user=user)
+    models.LinkTrace.objects.create(document=document, user=user, is_masked=False)
+
+    url = f"/api/v1.0/documents/{document.id!s}/mask/"
+
+    # Mask document
+    response = client.post(url)
+    assert response.status_code == 201
+
+    # Unmask document
+    response = client.delete(url)
+    assert response.status_code == 204
+    assert response.content == b""  # No body
+    assert response.text == ""  # Empty decoded text
+    assert "Content-Type" not in response.headers  # No Content-Type for 204
+
+    # Mask document again
+    response = client.post(url)
+    assert response.status_code == 201
+    assert response.json() == {"detail": "Document was masked"}
+
+    assert models.LinkTrace.objects.filter(
+        document=document, user=user, is_masked=True
+    ).exists()

src/backend/core/tests/documents/test_api_documents_retrieve.py

@@ -49,6 +49,7 @@ def test_api_documents_retrieve_anonymous_public_standalone():
                 "public": ["reader", "editor"],
                 "restricted": None,
             },
+            "mask": False,
             "media_auth": True,
             "media_check": True,
             "move": False,
@@ -121,6 +122,7 @@ def test_api_documents_retrieve_anonymous_public_parent():
             "link_select_options": models.LinkReachChoices.get_select_options(
                 **links_definition
             ),
+            "mask": False,
             "media_auth": True,
             "media_check": True,
             "move": False,
@@ -226,6 +228,7 @@ def test_api_documents_retrieve_authenticated_unrelated_public_or_authenticated(
                 "public": ["reader", "editor"],
                 "restricted": None,
             },
+            "mask": True,
             "media_auth": True,
             "media_check": True,
             "move": False,
@@ -305,6 +308,7 @@ def test_api_documents_retrieve_authenticated_public_or_authenticated_parent(rea
             "link_select_options": models.LinkReachChoices.get_select_options(
                 **links_definition
             ),
+            "mask": True,
             "move": False,
             "media_auth": True,
             "media_check": True,
@@ -498,6 +502,7 @@ def test_api_documents_retrieve_authenticated_related_parent():
             "link_select_options": models.LinkReachChoices.get_select_options(
                 **link_definition
             ),
+            "mask": True,
             "media_auth": True,
             "media_check": True,
             "move": access.role in ["administrator", "owner"],

src/backend/core/tests/documents/test_api_documents_trashbin.py

@@ -91,6 +91,7 @@ def test_api_documents_trashbin_format():
                 "public": ["reader", "editor"],
                 "restricted": None,
             },
+            "mask": True,
             "media_auth": True,
             "media_check": True,
             "move": False,  # Can't move a deleted document

src/backend/core/tests/test_models_documents.py

@@ -165,6 +165,7 @@ def test_models_documents_get_abilities_forbidden(
         "duplicate": False,
         "favorite": False,
         "invite_owner": False,
+        "mask": False,
         "media_auth": False,
         "media_check": False,
         "move": False,
@@ -233,6 +234,7 @@ def test_models_documents_get_abilities_reader(
             "public": ["reader", "editor"],
             "restricted": None,
         },
+        "mask": is_authenticated,
         "media_auth": True,
         "media_check": True,
         "move": False,
@@ -297,6 +299,7 @@ def test_models_documents_get_abilities_editor(
             "public": ["reader", "editor"],
             "restricted": None,
         },
+        "mask": is_authenticated,
         "media_auth": True,
         "media_check": True,
         "move": False,
@@ -350,6 +353,7 @@ def test_models_documents_get_abilities_owner(django_assert_num_queries):
             "public": ["reader", "editor"],
             "restricted": None,
         },
+        "mask": True,
         "media_auth": True,
         "media_check": True,
         "move": True,
@@ -400,6 +404,7 @@ def test_models_documents_get_abilities_administrator(django_assert_num_queries)
             "public": ["reader", "editor"],
             "restricted": None,
         },
+        "mask": True,
         "media_auth": True,
         "media_check": True,
         "move": True,
@@ -453,6 +458,7 @@ def test_models_documents_get_abilities_editor_user(django_assert_num_queries):
             "public": ["reader", "editor"],
             "restricted": None,
         },
+        "mask": True,
         "media_auth": True,
         "media_check": True,
         "move": False,
@@ -513,6 +519,7 @@ def test_models_documents_get_abilities_reader_user(
             "public": ["reader", "editor"],
             "restricted": None,
         },
+        "mask": True,
         "media_auth": True,
         "media_check": True,
         "move": False,
@@ -571,6 +578,7 @@ def test_models_documents_get_abilities_preset_role(django_assert_num_queries):
             "public": ["reader", "editor"],
             "restricted": None,
         },
+        "mask": True,
         "media_auth": True,
         "media_check": True,
         "move": False,