Skip to content

feat: Add user quota management system#5658

Draft
jondkelley wants to merge 3 commits intofilebrowser:masterfrom
jondkelley:user_quota
Draft

feat: Add user quota management system#5658
jondkelley wants to merge 3 commits intofilebrowser:masterfrom
jondkelley:user_quota

Conversation

@jondkelley
Copy link
Copy Markdown

@jondkelley jondkelley commented Jan 3, 2026 •
edited
Loading

Description

Introduces comprehensive quota management with real-time usage tracking, frontend components, backend API endpoints, and TUS upload integration for storage limit enforcement.

Screenshot 2026-01-03 at 1 24 33 AM Screenshot 2026-01-03 at 1 23 34 AM

Additional Information

This PR implements a complete quota management system with the following technical approach:

Backend Architecture:

  • Added quota fields to the User model (users/users.go): QuotaLimit (bytes), QuotaUnit (GB/TB), EnforceQuota (hard/soft limit), and QuotaUsed (calculated on-demand)
  • Created quota calculation utilities (users/quota.go) that walk the user's directory tree to sum file sizes, with 30-second timeout protection
  • Implemented middleware-based quota enforcement (http/quota.go) that intercepts file upload/update operations and validates against quotas before processing
  • Integrated quota checks into resource handlers (http/resource.go) for POST and PUT operations
  • Added dedicated API endpoint GET /api/users/{id}/quota for real-time usage tracking

TUS Upload Integration:

  • Modified http/quota.go to extract file size from both Upload-Length header (TUS protocol) and Content-Length header
  • Updated TUS client (frontend/src/api/tus.ts) to handle 413 status codes, disable retries on quota exceeded, and display quota information from response headers

Frontend Components:

  • Created QuotaInput.vue for admin configuration with unit selection (GB/TB) and enforcement toggle
  • Created QuotaUsage.vue with color-coded progress bar (green <80%, yellow 80-95%, red >95%) and warning messages
  • Integrated components into user settings form, visible only to administrators

CLI Support:

Enforcement Modes:

  • Hard limit (enforceQuota=true): Returns 413 Payload Too Large and blocks operations when quota exceeded
  • Soft limit (enforceQuota=false): Shows warnings but allows operations to proceed
  • Unlimited (quotaLimit=0): No restrictions applied

Design Decisions:

  • On-demand quota calculation rather than caching to ensure accuracy, with timeout protection to prevent long-running operations
  • Middleware-based enforcement ensures all file operations are covered without modifying individual handlers
  • Admin-only quota management prevents users from bypassing restrictions
  • TUS protocol support ensures quota enforcement works with resumable uploads
  • Response headers (X-Quota-Limit, X-Quota-Used) provide detailed feedback on quota exceeded errors

Error Handling:

  • Added ErrQuotaExceeded and ErrInvalidQuotaUnit errors
  • Graceful handling of quota calculation timeouts and filesystem access errors
  • User-friendly error messages with current usage and limit information

Checklist

Before submitting your PR, please indicate which issues are either fixed or closed by this PR. See GitHub Help: Closing issues using keywords.

Closes #2090
Closes #711
Addresses #1214

  • I am aware the project is currently in maintenance-only mode. See README
  • I am aware that translations MUST be made through Transifex and that this PR is NOT a translation update
  • I am making a PR against the master branch.
  • I am sure File Browser can be successfully built. See builds and development.

Explanation:

  • Use "Closes Storage quota limit per user #2090" and "Closes Storage Quota #711" for the issues that will be fully resolved by this PR
  • Use "Addresses Feature Proposal #1214" for the discussion since it's not a traditional issue and may need further community input
  • Place these references at the top of the checklist section before the checkbox items
  • GitHub will automatically link these and close the issues when the PR is merged to the default branch

@jondkelley
Add user quota management system
0a3d164 
Introduces comprehensive quota management with real-time usage tracking, frontend components, backend API endpoints, and TUS upload integration for storage limit enforcement.
@jondkelley jondkelley changed the title Add user quota management system feat: Add user quota management system Jan 3, 2026
@jondkelley jondkelley marked this pull request as ready for review January 3, 2026 06:18
@jondkelley jondkelley requested a review from a team as a code owner January 3, 2026 06:18
@WinnerWind
Copy link
Copy Markdown

WinnerWind commented Jan 3, 2026

(I saw your e-mail)
Great patch!

I don't use FileBrowser anymore, so I won't be testing this, but I think it's a cool feature! One nitpick I do have (judging from the screenshots, not by actually testing it) is that the left side usage bar shows the SERVER usage bar and not the user quota bar. The workaround in #2090 does show the USER quota in the left panel because of how it works.

@jondkelley
Copy link
Copy Markdown
Author

jondkelley commented Jan 3, 2026

Good feedback, I added quota and usage to the usage bar in the UI.

Screenshot 2026-01-03 at 2 26 53 AM

@hacdias
Copy link
Copy Markdown
Member

hacdias commented Jan 10, 2026

Just wanna say that this is quite a large PR, so it may take longer to take a look at.

@azdfzshffg
Copy link
Copy Markdown

azdfzshffg commented Feb 17, 2026

Nice PR !

@hacdias
Copy link
Copy Markdown
Member

hacdias commented Feb 28, 2026

@jondkelley I really want to look at this, but now I see there's quite a few conflicts. If you have time, could you rebase it?

@hacdias
Copy link
Copy Markdown
Member

hacdias commented Mar 11, 2026

Over the past months, I've realized I don't have enough time to review new features, especially quite large ones. Sadly, I need to mark this PR. Read more on https://hacdias.com/2026/03/11/filebrowser/

@hacdias hacdias marked this pull request as draft March 11, 2026 18:34
@jondkelley
Copy link
Copy Markdown
Author

jondkelley commented Mar 12, 2026 •
edited
Loading

Just had a newborn child, so will have to revisit this. I also don't have time for this at the moment.

We're using this branch in production though, seems worthwhile to add at some point.

@hacdias
Copy link
Copy Markdown
Member

hacdias commented Mar 12, 2026

Congratulations!!

We're using this branch in production though

That's interesting. My problem with maybe accepting one PR is that it creates a precedent. But if you've been using it for some time and it seems to work fine, I might go for it.

kumaraguru1735 added a commit to kumaraguru1735/filebrowser-laravel that referenced this pull request Mar 31, 2026
@kumaraguru1735 @claude
Fix 10 upstream issues + port 4 PRs from filebrowser/filebrowser
5d251da 
Bug fixes:
- filebrowser#5627: Skip inaccessible subfolders in directory listing (was 500)
- filebrowser#5294: Cap text editor content at 5MB (prevents memory exhaustion DoS)
- filebrowser#5683: Allow copy/move TO root directory (was blocked)
- filebrowser#5835: Share creation requires both share AND download permissions
- filebrowser#5834: Reject negative/zero TUS Upload-Length, add 10GB sanity cap
- filebrowser#5239: Block sharing root directory (too broad, accidental exposure)
- filebrowser#5216: Validate JWT signature on token renewal
- filebrowser#2078: Support BMP thumbnails, skip GIF resize (preserve animation)
- filebrowser#5306: Normalize paths in copy/rename (strip trailing slashes)

Ported PRs:
- filebrowser#5876: Reject negative TUS upload-length
- filebrowser#5875: Check download perm when sharing
- filebrowser#5873: Deep conflict resolution — merge dirs, preserve non-conflicting
- filebrowser#5832: Optional directory sizes via ?dirSizes=true param
- filebrowser#5658: User quota management — configurable quota_resolver callback

Config additions:
- quota_resolver: callable for per-user disk quotas
- max_content_size: cap for text editor loading (default 5MB)

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Storage quota limit per user Storage Quota

4 participants

@jondkelley @WinnerWind @hacdias @azdfzshffg