Uploads¶
The core.uploads module provides validation utilities for file uploads.
It ensures that uploaded files meet size and type requirements before being processed or stored.
Purpose¶
The uploads layer is responsible for:
- enforcing file size limits
- restricting allowed file types
- providing consistent validation across the backend
- protecting the system from unsafe or unsupported uploads
Entry Point¶
Main function:
validate_upload(file_obj)
This function should be called before saving or processing any uploaded file.
Validation Rules¶
File Size¶
The maximum allowed file size is controlled by settings:
MAX_UPLOAD_MB
The validator:
- converts this value to bytes
- compares it against the uploaded file size
If exceeded, it raises:
ValidationError("File too large. Max is X MB.")
File Type¶
Validation is based on MIME type.
Allowed prefixes are defined in settings:
ALLOWED_UPLOAD_MIME_PREFIXES
Default example:
- image/
- video/
- application/pdf
The validator checks:
- file_obj.content_type
If the MIME type does not match any allowed prefix, it raises:
ValidationError("Unsupported file type:
Example Flow¶
flowchart TD
A[File uploaded] --> B[validate_upload called]
B --> C{Size OK?}
C -->|No| D[ValidationError: file too large]
C -->|Yes| E{Type OK?}
E -->|No| F[ValidationError: unsupported type]
E -->|Yes| G[File accepted]
¶
flowchart TD
A[File uploaded] --> B[validate_upload called]
B --> C{Size OK?}
C -->|No| D[ValidationError: file too large]
C -->|Yes| E{Type OK?}
E -->|No| F[ValidationError: unsupported type]
E -->|Yes| G[File accepted]
Usage¶
This function should be used in: - serializers - upload endpoints - file processing services
Example scenarios: - image upload - document upload - attachment handling
Responsibilities¶
Upload Validation Layer¶
- validate file size
- validate MIME type
- raise validation errors
Storage Layer¶
- store files
- provide access URLs
Feature Apps¶
- decide when uploads are allowed
- call validation before saving
What Upload Validation Does NOT Do¶
The uploads layer does not: - store files - manage permissions - determine access rights - inspect file contents deeply (e.g. virus scanning) - perform business-specific validation
Security Considerations¶
This layer helps protect against: - excessively large uploads - unsupported file formats - basic misuse of upload endpoints
However, it does not replace: - authentication - authorization - deeper file inspection (e.g. antivirus, content scanning)
Configuration¶
The behavior depends on Django settings:
MAX_UPLOAD_MB¶
Defines maximum allowed file size.
Example:
MAX_UPLOAD_MB = 50
ALLOWED_UPLOAD_MIME_PREFIXES¶
Defines allowed MIME type prefixes.
Example:
ALLOWED_UPLOAD_MIME_PREFIXES = [ "image/", "video/", "application/pdf", ]
Error Handling¶
Errors are raised using:
rest_framework.exceptions.ValidationError
These are automatically handled by the global exception handler and returned in a consistent API format.
Best Practices¶
- always validate uploads before saving
- keep allowed MIME types restrictive
- set reasonable size limits
- do not trust client-provided file metadata blindly
Future Extensions¶
Possible improvements: - file extension validation - virus scanning integration - content inspection (e.g. PDF validation) - per-endpoint upload rules - per-org upload limits
Summary¶
The core.uploads module provides a simple and consistent way to validate uploaded files.
It ensures that: - file size limits are enforced - only allowed file types are accepted - uploads are handled safely before storage