gighive
TUS Implementation Rationale
Question: Is it worthwhile to implement TUS protocol for Cloudflare compatibility?
Recommendation: Yes, implement TUS - but with caveats
Rationale for TUS Implementation
1. Real-World Usage Pattern
- Users will frequently upload from outside networks (coffee shops, venues, traveling)
- Your target content (wedding videos, band performances) is typically >100MB
- From testing: 24-min video = 4.7GB after H.264 transcoding
- Even shorter videos often exceed 100MB (e.g., 10-min 4K video ≈ 2GB)
2. Current Limitation is Severe For Cloudflare Free Tier Users
- 100MB = ~5 minutes of 4K video at typical bitrates
- Most gig/event videos are 15-60+ minutes
- Without TUS, the app is essentially broken for remote uploads of typical content
- Discovered during testing from outside Wi-Fi network
- Note these limits are not in place if you bypass Cloudflare and go direct to your GigHive server
3. Technical Feasibility
You already have the hard parts solved:
- ✅ Memory-efficient streaming (
MultipartInputStream) - ✅ Progress tracking infrastructure
- ✅ Cancellation handling
- ✅ Clean architecture with
UploadClientabstraction
TUS is just adding a routing layer on top of existing code.
4. Low Implementation Risk
- Fallback strategy: Files <100MB use existing path (proven to work)
- New path: Files >100MB use TUS (new code path)
- If TUS fails, show clear error message
- No risk to existing functionality
Counter-Arguments (Why You Might NOT Do It)
1. Workaround Exists
- Users can upload via local network / direct IP
- Could document: “For large files, connect to venue WiFi”
- Acceptable if this is a niche tool for tech-savvy users
2. Server Complexity
- Requires TUS-compatible server endpoint
- Current
uploads.phpwon’t work as-is - Need to implement/deploy TUS server (tusd, or PHP TUS library)
- Additional server maintenance burden
3. Alternative: Bypass Cloudflare
- Could use separate subdomain without Cloudflare proxy
- E.g.,
upload.gighive.app→ direct to server (DNS only) - Simpler than TUS implementation
- Trade-off: Lose Cloudflare DDoS protection on upload endpoint
4. Usage Frequency
- If 90% of uploads happen on local network at venues, TUS adds complexity for edge cases
- Depends on actual usage patterns
Decision Matrix
Implement TUS if:
- ✅ Users regularly upload remotely (not just at venues)
- ✅ You want a polished, “works everywhere” experience
- ✅ You’re willing to set up TUS server infrastructure
- ✅ This is a product you’re building for wider use
Skip TUS if:
- ❌ This is primarily for local network use
- ❌ You can’t easily deploy TUS server
- ❌ You’re okay with “upload large files on local network only” limitation
- ❌ You prefer the Cloudflare bypass approach (separate upload subdomain)
Recommended Alternative: Cloudflare Bypass
Easiest solution without TUS:
- Create
upload.gighive.appsubdomain - Point it directly to your server (DNS only, no Cloudflare proxy)
- Use this for uploads >100MB
- Keep main site behind Cloudflare
Benefits:
- ✅ No 100MB limit
- ✅ No code changes needed
- ✅ Works with existing implementation
- ✅ Simple DNS configuration
Trade-offs:
- ❌ Lose Cloudflare DDoS protection on upload endpoint
- ✅ But uploads are authenticated anyway (Basic Auth)
- ✅ Upload endpoint is not publicly advertised
Implementation Comparison
Option 1: TUS Protocol
Client Changes:
- Add TUSKit dependency
- Create
TUSUploadClient.swift(~80 lines) - Add routing logic in
UploadClient.swift(~30 lines) - Update one line in
UploadView.swift
Server Changes:
- Deploy TUS server (tusd or PHP library)
- Configure chunked upload handling
- Update Apache/nginx config
Complexity: Medium-High
Maintenance: Ongoing (TUS server)
Option 2: Cloudflare Bypass
Client Changes:
- Add setting toggle for “use direct upload”
- Change base URL conditionally
Server Changes:
- Add DNS A record for
upload.gighive.app - Point to server IP (no Cloudflare proxy)
Complexity: Low
Maintenance: Minimal
Option 3: Hybrid Approach
Strategy:
- Start with Cloudflare bypass (quick win)
- Implement TUS later if needed
- Keep TUS implementation guide ready
Benefits:
- Unblocks users immediately
- Defers complexity
- Can evaluate actual need based on usage
Current State
What Works:
- ✅ Local network uploads (any size up to 6GB)
- ✅ Remote uploads <100MB through Cloudflare
- ✅ Memory-efficient streaming
- ✅ Real-time progress tracking
- ✅ Cancellation support
What Fails:
- ❌ Remote uploads >100MB through Cloudflare (HTTP 413)
Test Results:
- 177MB video: ❌ Failed (Cloudflare 413)
- 241MB video: ❌ Failed (Cloudflare 413)
- 350MB video: ❌ Failed (Cloudflare 413)
- 4.7GB video: ✅ Works on local network
Recommendation Summary
Short-term (Immediate): Implement Cloudflare Bypass approach:
- Fastest to deploy
- Unblocks remote uploads immediately
- No code changes required
- Minimal risk
Long-term (If needed): Implement TUS Protocol if:
- User feedback indicates frequent remote uploads
- You want enterprise-grade reliability
- You’re building this as a commercial product
- You have resources for server infrastructure
Pragmatic Approach:
- Deploy Cloudflare bypass now (1 hour)
- Monitor usage patterns for 1-2 months
- Decide on TUS based on actual data
- Keep TUS implementation guide ready for when needed
Related Documentation
PICKER_TRANSCODING_METHOD.md- PHPicker HEVC→H.264 transcoding behaviorhttps://gighive.app/tusimplementationweek1.html- TUS implementation guide (line 658, not 512)CLOUDFLARE_UPLOAD_LIMIT.md- Detailed Cloudflare 100MB limit analysis (if exists)
Key Files
UploadClient.swift- Main upload routing (line 72:uploadWithMultipartInputStream)NetworkProgressUploadClient.swift- Current streaming implementationUploadView.swift- UI integration (line 658: upload call)project.yml- Dependencies (TUSKit commented out, lines 6-10)