✨(backend) add file upload feature & tests

For the coming features we will need to store files on the meet side.
(for instance user backgrounds).

This commits adds a new Model to manage files, and the associated
serializers & viewsets. All are tested.

This work was heavily inspired by the work done by our friends at
https://github.com/suitenumerique/drive
It build on the same architecture design (upload directly to S3 but
download goes through our proxy), but model is much much simplier
(no folders, no file sharing, etc.).

src/backend/core/models.py

@@ -1,11 +1,14 @@
 """
 Declare and configure the models for the Meet core application
+# pylint: disable=too-many-lines
 """
+# pylint: disable=too-many-lines
 
 import secrets
 import uuid
 from datetime import datetime, timedelta
 from logging import getLogger
+from os.path import splitext
 from typing import List, Optional
 
 from django.conf import settings
@@ -14,7 +17,7 @@ from django.contrib.auth.base_user import AbstractBaseUser
 from django.contrib.postgres.fields import ArrayField
 from django.core import mail, validators
 from django.core.exceptions import PermissionDenied, ValidationError
-from django.db import models
+from django.db import models, transaction
 from django.utils import timezone
 from django.utils.text import capfirst, slugify
 from django.utils.translation import gettext_lazy as _
@@ -829,3 +832,186 @@ class ApplicationDomain(BaseModel):
 
         self.domain = self.domain.lower().strip()
         super().save(*args, **kwargs)
+
+
+class FileUploadStateChoices(models.TextChoices):
+    """Possible states of a file."""
+
+    PENDING = "pending", _("Pending")
+    # Commented out for now, as we may need this when we implement the malware detection logic.
+    # ANALYZING = "analyzing", _("Analyzing")
+    # SUSPICIOUS = "suspicious", _("Suspicious")
+    # FILE_TOO_LARGE_TO_ANALYZE = (
+    #     "file_too_large_to_analyze",
+    #     _("File too large to analyze"),
+    # )
+    READY = "ready", _("Ready")
+
+
+class FileTypeChoices(models.TextChoices):
+    """Defines the possible types of a file."""
+
+    BACKGROUND_IMAGE = "background_image", _("Background image")
+
+
+class File(BaseModel):
+    """File uploaded by a user."""
+
+    type = models.CharField(
+        max_length=25,
+        choices=FileTypeChoices.choices,
+        null=False,
+        blank=False,
+    )
+    title = models.CharField(_("title"), max_length=255)
+    creator = models.ForeignKey(
+        User,
+        on_delete=models.RESTRICT,
+        related_name="files_created",
+        blank=True,
+        null=True,
+    )
+    deleted_at = models.DateTimeField(null=True, blank=True)
+    hard_deleted_at = models.DateTimeField(null=True, blank=True)
+
+    filename = models.CharField(max_length=255, null=False, blank=False)
+
+    upload_state = models.CharField(
+        max_length=25,
+        choices=FileUploadStateChoices.choices,
+    )
+    mimetype = models.CharField(max_length=255, null=True, blank=True)
+    size = models.BigIntegerField(null=True, blank=True)
+    description = models.TextField(null=True, blank=True)
+    malware_detection_info = models.JSONField(
+        null=True,
+        blank=True,
+        default=dict,
+        help_text=_("Malware detection info when the analysis status is unsafe."),
+    )
+
+    class Meta:
+        db_table = "file"
+        verbose_name = _("File")
+        verbose_name_plural = _("Files")
+        ordering = ("created_at",)
+        indexes = [
+            models.Index(fields=["creator", "type", "-created_at"]),
+        ]
+
+    def __str__(self):
+        return str(self.title)
+
+    def save(self, *args, **kwargs):
+        """Set the upload state to pending if it's the first save and it's a file."""
+
+        if self.created_at is None:
+            self.upload_state = FileUploadStateChoices.PENDING
+
+        return super().save(*args, **kwargs)
+
+    def delete(self, using=None, keep_parents=False):
+        if self.deleted_at is None:
+            raise RuntimeError("The file must be soft deleted before being deleted.")
+
+        return super().delete(using, keep_parents)
+
+    @property
+    def is_pending_upload(self):
+        """Return whether the file is in a pending upload state"""
+        return self.upload_state == FileUploadStateChoices.PENDING
+
+    @property
+    def extension(self):
+        """Return the extension related to the filename."""
+        if self.filename is None:
+            raise RuntimeError(
+                "The file must have a filename to compute its extension."
+            )
+
+        _, extension = splitext(self.filename)
+
+        if extension:
+            return extension.lstrip(".")
+
+        return None
+
+    @property
+    def key_base(self):
+        """Key base of the location where the file is stored in object storage."""
+        if not self.pk:
+            raise RuntimeError(
+                "The file instance must be saved before requesting a storage key."
+            )
+
+        return f"{settings.FILE_UPLOAD_PATH}/{self.pk!s}"
+
+    @property
+    def file_key(self):
+        """Key used to store the file in object storage."""
+        _, extension = splitext(self.filename)
+        # We store only the extension in the storage system to avoid
+        # leaking Personal Information in logs, etc.
+        return f"{self.key_base}/{extension!s}"
+
+    def get_abilities(self, user):
+        """
+        Compute and return abilities for a given user on the file.
+        """
+        # Characteristics that are based only on specific access
+        is_creator = user == self.creator
+        retrieve = is_creator
+        is_deleted = self.deleted_at is not None
+        can_update = is_creator and not is_deleted and user.is_authenticated
+        can_hard_delete = is_creator and user.is_authenticated
+        can_destroy = can_hard_delete and not is_deleted
+
+        return {
+            "destroy": can_destroy,
+            "hard_delete": can_hard_delete,
+            "retrieve": retrieve,
+            "media_auth": retrieve and not is_deleted,
+            "partial_update": can_update,
+            "update": can_update,
+            "upload_ended": can_update and user.is_authenticated,
+        }
+
+    @transaction.atomic
+    def soft_delete(self):
+        """
+        Soft delete the file.
+        We still keep the .delete() method untouched for programmatic purposes.
+        """
+        if self.deleted_at:
+            raise RuntimeError("This file is already deleted.")
+
+        self.deleted_at = timezone.now()
+        self.save(update_fields=["deleted_at"])
+
+    def hard_delete(self):
+        """
+        Hard delete the file.
+        We still keep the .delete() method untouched for programmatic purposes.
+        """
+        if self.hard_deleted_at:
+            raise ValidationError(
+                {
+                    "hard_deleted_at": ValidationError(
+                        _("This file is already hard deleted."),
+                        code="file_hard_delete_already_effective",
+                    )
+                }
+            )
+
+        if self.deleted_at is None:
+            raise ValidationError(
+                {
+                    "hard_deleted_at": ValidationError(
+                        _("To hard delete a file, it must first be soft deleted."),
+                        code="file_hard_delete_should_soft_delete_first",
+                    )
+                }
+            )
+
+        self.hard_deleted_at = timezone.now()
+        self.save(update_fields=["hard_deleted_at"])