Filebrowser: Upload Feature #92

Summary

• As a data engineer or platform user, I want to upload files to an S3 bucket via the Stackable UI File Browser so I can add or replace data without leaving the UI.

Description

• The Stackable UI File Browser (v0) must support uploading a single file from the user's browser to an S3-compatible storage location using the active connection configuration. Uploads are initiated from the browser UI (file chooser or drag-and-drop on file-item area). The system sends the file to S3 using the provided connection and reports success or clear errors to the user.
• v0 constraints:
  • No Kubernetes or SDP integration
  • No production-grade credential handling
  • Feature behind a feature flag
  • Single-file uploads only (no folder or bulk uploads)
  • For large files, use streaming/multipart upload where feasible, but keep implementation "good enough" for v0

Business Value

• Enables quick data ingestion and corrections directly from the UI.
• Reduces context switching and reliance on external tools for small uploads or quick edits.
• Complements read/preview/download capabilities to provide basic round-trip data access.

Acceptance Criteria

Scenario: Upload a single file successfully
	Given a user has configured a valid S3 connection
	And the user is browsing an S3 bucket
	When the user clicks "Upload" and selects a file
	Then the file is uploaded to the selected bucket/prefix
	And the UI shows success
	And the object appears in the file listing with correct name and size

Scenario: Upload large file
	Given a file larger than typical preview limits exists locally
	When the user uploads the file
	Then the upload streams or uses multipart so the UI/backend does not load the whole file into memory
	And the upload completes successfully

Scenario: Upload fails due to missing permissions
	Given the user's S3 credentials do not allow PutObject or multipart permissions
	When the user attempts to upload a file
	Then the upload fails
	And a clear error message is shown based on the S3 error response

Scenario: Upload fails due to invalid destination (bucket/prefix missing)
	Given the target bucket or prefix does not exist or is not addressable
	When the user attempts to upload
	Then the upload fails
	And the user sees a "Not Found" or equivalent error message

Scenario: Feature flag disabled
	Given the S3 Browser feature flag is disabled
	When the user navigates the Stackable UI
	Then upload functionality is not visible or accessible

Functional Requirements

• UI must expose an Upload action for file objects and an explicit upload control in the file listing or toolbar.
• Upload must accept a single file selection (or drag-and-drop) and target the current bucket + selected prefix.
• For large files, use multipart upload (preferred) or streaming proxied through backend to avoid full memory buffering.
• Maintain original file name and binary integrity (no encoding changes).
• Surface S3 errors (403, 404, NoSuchBucket, InvalidPart) as clear user-readable messages.
• Support optional "overwrite" confirmation when object with same name exists (configurable prompt).
• Upload must be feature-flag gated.

Non-Functional Requirements

• Performance: Stream or chunk files to avoid excessive memory usage.
• Reliability: Partial or failed uploads must surface clear failure states and allow retry.
• Security: v0 may use in-memory or ephemeral credentials; do not implement production credential vaulting.
• Usability: Upload control should be clearly distinct from Download/Preview actions; show progress and success/failure states.
• Maintainability: Keep API surface small and document assumptions (credential handling, region behavior).

Implementation Notes / Frontend vs Backend

• Backend-driven upload (recommended):
  • Browser uploads file to backend endpoint which then performs S3 PutObject or multipart upload. Backend streams file to S3 to avoid memory issues and to centralize S3 credentials.
  • Pros: Simplifies CORS, credentials, and supports streaming/multipart without browser-side presign complexity.
  • Cons: Requires server bandwidth and temporary storage/streaming logic.
• Frontend-driven upload (alternative):
  • Use signed URLs (presigned PUT or multipart) from backend; browser uploads directly to S3.
  • Pros: Offloads bandwidth from backend; scales better for large files.
  • Cons: Requires implementing presign endpoints, CORS on S3, and multipart presign flow if large files are required.
• For v0, implement backend-driven simple PUT streaming first; add presign/multipart later if needed.

API / UX

• UI: Upload button in toolbar + drag-and-drop area over file listing; file chooser for single file.
• UX states: Selecting -> Uploading (progress%) -> Success or Failed (with message + retry).
• Overwrite: If target exists, prompt "Replace existing object?" with options Replace/Cancel/Rename.

Dependencies

• Feature flag mechanism (env var or build-time toggle).
• Backend upload endpoint if choosing backend-driven approach.

Assumptions

• Only single-object uploads supported in v0.
• No folder uploads, archive handling, or resumable client-side uploads.
• Browser-native upload progress and backend streaming are acceptable.
• Insecure credential handling acceptable for v0 (documented).

Out of Scope

• Bulk/folder uploads, recursive uploads, or archive creation.
• Resumable uploads, client-side chunking with resume.
• Production credential storage, auditing, or advanced security.
• Integration with Kubernetes/SDP/CR.

QA Notes

• Test with:
  • Small text files
  • Large binary files (e.g., >1GB)
  • Files with special characters and unicode names
• Validate:
  • Expired or invalid credentials produce clear error messages
  • Permission-denied responses (403) surfaced to user
  • Behaviour when bucket/prefix does not exist
  • Overwrite confirmation works and prevents accidental replacements
  • Feature flag hides UI when disabled

Definition of Done

• Upload UI control implemented and gated by feature flag.
• Uploads work for small and large files (streaming/multipart or backend streaming).
• Errors from S3 surfaced clearly to users (403, 404, InvalidPart, etc.).
• Overwrite flow and progress feedback implemented.
• QA tests passed for small, large, and special-character filenames.
• Documentation updated (e.g., add a section to instruction.md or companion doc).
• Code reviewed and meets project quality standards.