transfer.sh

transfer.sh is a lightweight, self‑hostable file transfer service written in Go that exposes a minimal HTTP API for uploading, downloading, and deleting files. The service is designed to be drop‑in on any server or container orchestration platform, providing a command‑line friendly interface (curl, wget, etc.) and optional server‑side encryption. At its core, the application accepts multipart/form‑data uploads and streams them directly to a configured backend storage provider without materializing the entire file in memory, making it efficient for large payloads.

Architecture & Technical Stack

• Language & Runtime: Pure Go (1.20+), compiled to a single static binary, enabling zero‑dependency deployments.
• Frameworks: Standard net/http with a small router (github.com/gorilla/mux) for path handling; no heavy frameworks, keeping the attack surface minimal.
• Storage Abstraction: A pluggable backend interface (storage.Provider) supports S3, Google Drive, Storj, and a local filesystem. The provider layer abstracts bucket/namespace operations, upload/download streams, and lifecycle policies.
• Database: No relational database; metadata (file ID, deletion URL, expiry timestamps) is encoded into a deterministic URL and stored in memory or an optional key‑value store for persistence across restarts.
• Encryption: Optional AES‑256 server‑side encryption (via X-Encrypt-Password) and client‑side GPG support. Encryption is performed in streaming mode to avoid full file buffering.
• Metrics & Health: Exposes Prometheus metrics and a /healthz endpoint for observability.

Core Capabilities

• Upload API: PUT /<filename> or POST with multipart form data; supports custom headers for Max-Downloads, Max-Days, and encryption.
• Download API: Simple GET to the file URL; supports X-Decrypt-Password for server‑side decryption.
• Deletion API: DELETE <delete-url> where the delete URL is returned in the X-Url-Delete response header.
• VirusTotal Integration: Special endpoint (/virustotal) that forwards the file to VirusTotal’s API automatically after upload.
• Extensible Providers: New storage backends can be added by implementing the Provider interface and registering it in the provider registry.
• Webhooks & Callbacks: Not natively supported, but developers can wrap the service in a proxy that forwards POST requests to external endpoints on upload/delete events.

Deployment & Infrastructure

• Containerization: Official Docker image (dutchcoders/transfer.sh) is built on a scratch base, exposing port 80. The image can be run with environment variables for provider configuration (AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS, etc.).
• Self‑Hosting Requirements: Minimal – a machine with Go runtime (or Docker), network connectivity to the chosen storage provider, and optional TLS termination via a reverse proxy.
• Scalability: Stateless request handling allows horizontal scaling behind a load balancer. The storage provider handles concurrency; S3 and Storj naturally scale, while local FS requires shared storage (e.g., NFS) for multi‑node deployments.
• High Availability: Combine multiple instances with a shared backend (S3 or NFS) and a DNS round‑robin or Kubernetes Service for load balancing.

Integration & Extensibility

• API Usage: Exposed endpoints are RESTful and can be consumed by any HTTP client. The service supports CORS headers, enabling browser‑based uploads via drag‑and‑drop.
• SDKs: No official SDKs, but the API’s simplicity allows quick wrappers in any language.
• Customization: Developers can modify the main.go source to add custom headers, enforce authentication (JWT, Basic Auth), or integrate with CI/CD pipelines.
• Plugin System: Not built‑in, but the provider abstraction allows adding new storage backends by implementing a small interface.

Developer Experience

• Configuration: All settings are environment‑based; the README documents required variables for each provider. No configuration files mean fewer attack vectors.
• Documentation: The repository’s README covers usage patterns, header semantics, and examples. The code is well‑commented, and unit tests cover edge cases.
• Community & Support: Active GitHub repo with issue tracking and pull requests. Licensing is MIT, encouraging commercial use without restrictions.

Use Cases

• CI/CD Artifact Sharing: Upload build artifacts to a temporary S3 bucket and share the URL with downstream jobs.
• Internal Tooling: Provide a lightweight file drop for internal teams without relying on external services.
• Security Audits: Integrate with VirusTotal to automatically scan uploaded binaries before distribution.
• Developer Prototyping: Quickly spin up a local instance for testing file upload flows in new applications.

Advantages Over Alternatives

For developers who need a dependable,