Merge pull request #10 from polius/v4.0.0

Ground-up rebuild of the backend. Removes the PeerJS dependency in favor of
  native WebRTC and a first-party WebSocket signaling server bundled with the
  app. Received files now stream straight to disk, keeping memory flat even on
  multi-GB transfers.

  Connectivity
  - Native RTCPeerConnection / RTCDataChannel client replacing PeerJS.
  - Built-in signaling relay at /ws with rate limiting, idle timeouts, and
    capacity guards; relays only connection setup, never file data.
  - Relayed transfers fixed behind Docker (TURN relay candidates rewritten
    in transit).

  Transfers
  - Chunked, backpressured protocol keeping sender and receiver memory-bounded.
  - Three auto-selected save methods: File System Access, Service Worker, Blob.

  Reliability
  - Serialized disk writes fix a File System Access corruption case.
  - Abort, remove, and "cancel all" tear down cleanly; no leaked connections.
  - Transient network blips tolerated instead of killing a transfer.
  - Container self-heals if the backend process dies.

  Security
  - Server refuses to start without SECRET_KEY.
  - /api/credentials rate-limited; CORS off by default (opt-in via CORS_ORIGINS).
  - Fonts self-hosted to satisfy the strict CSP.

  Tooling & docs
  - End-to-end Playwright harness (browsers x save methods x connection modes).
  - Dependabot for Python, Docker, GitHub Actions, and the test harness.
  - README refreshed.

  BREAKING CHANGE: upgrading from 3.x requires re-downloading the compose files
  and setting SECRET_KEY (the app will not start without it). A separate PeerJS
  server is no longer needed.

Author: polius

.github/dependabot.yml

@@ -0,0 +1,45 @@
+version: 2
+updates:
+  # Python backend dependencies (api/requirements.txt)
+  - package-ecosystem: "pip"
+    directory: "/api"
+    schedule:
+      interval: "daily"
+    groups:
+      pip-minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  # Container base image (Dockerfile)
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    groups:
+      docker-minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  # GitHub Actions used by the release workflow
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    groups:
+      actions-minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"
+
+  # End-to-end test harness (Playwright)
+  - package-ecosystem: "npm"
+    directory: "/e2e"
+    schedule:
+      interval: "daily"
+    groups:
+      npm-minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"

.github/workflows/release.yml

@@ -33,10 +33,12 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Set tag without first two chars
+      - name: Derive version tag from the git ref
         id: tag
         run: |
-          SHORT_TAG="${GITHUB_REF_NAME:2}"
+          # Strip a leading "v" and an optional "." so both v4.0.0 and v.4.0.0 -> 4.0.0.
+          SHORT_TAG="${GITHUB_REF_NAME#v}"
+          SHORT_TAG="${SHORT_TAG#.}"
           echo "SHORT_TAG=$SHORT_TAG" >> $GITHUB_OUTPUT
 
       - name: Build and push Docker image

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

Dockerfile

@@ -30,8 +30,8 @@ RUN find /install/lib/ -path "*/site-packages/tests" -type d -exec rm -rf {} + \
 # ==============================
 FROM python:3.14-alpine
 
-# Install Nginx runtime
-RUN apk add --no-cache nginx
+# Install Nginx runtime (+ bash for a reliable `wait -n` in the start command)
+RUN apk add --no-cache nginx bash
 
 WORKDIR /filesync
 
@@ -52,5 +52,11 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
 # Expose ports
 EXPOSE 80
 
-# Start FastAPI + Nginx
-CMD ["sh", "-c", "python3 -m uvicorn api.main:app --host 0.0.0.0 --port 8000 & nginx -g 'daemon off;'"]
+# Start FastAPI + Nginx. bash's `wait -n` returns as soon as EITHER process exits, so the
+# container stops (and `restart: unless-stopped` restarts it) if the backend dies —
+# instead of nginx keeping a half-dead container alive indefinitely. (busybox sh's
+# `wait -n` does not reliably fire for a backgrounded child as PID 1, so we use bash.)
+# --ws-max-size caps WebSocket frames at the transport (uvicorn's default is 16 MiB,
+# which would be fully buffered before the app's own 32 KiB payload check runs);
+# 64 KiB leaves headroom over the signaling _MAX_PAYLOAD_BYTES limit.
+CMD ["bash", "-c", "python3 -m uvicorn api.main:app --host 0.0.0.0 --port 8000 --ws-max-size 65536 & nginx -g 'daemon off;' & wait -n"]

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Pol Alzina
+Copyright (c) 2025-2026 Pol Alzina
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -2,178 +2,169 @@
 <img src="web/assets/icon.png" alt="FileSync Logo" width="80">
 <h1 align="center">FileSync</h1>
 
-**Send files from one device to many in real-time**
+**Send files from one device to many, in real time — private, peer-to-peer, with no size limit.**
 
 <p align="center">
-<a href="https://github.com/polius/filesync/actions/workflows/release.yml"><img src="https://github.com/polius/filesync/actions/workflows/release.yml/badge.svg"></a>&nbsp;<a href="https://github.com/polius/filesync/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/polius/filesync"></a>&nbsp;<a href="https://hub.docker.com/r/poliuscorp/filesync"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/poliuscorp/filesync"></a>
+<a href="https://github.com/polius/filesync/actions/workflows/release.yml"><img src="https://github.com/polius/filesync/actions/workflows/release.yml/badge.svg"></a>&nbsp;<a href="https://github.com/polius/filesync/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/polius/filesync"></a>&nbsp;<a href="https://hub.docker.com/r/poliuscorp/filesync"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/poliuscorp/filesync"></a>&nbsp;<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg"></a>
 </p>
 
 <br>
 
-<p align="center">
-<b>FileSync</b> is a file sharing web application that allows users to transfer files between multiple devices with end-to-end encryption.
-</p>
+![FileSync](web/assets/filesync.png?v=4.0.0)
 
-<br>
+</div>
 
-![FileSync](web/assets/filesync.png?v=3.4.0)
+## Features
 
-</div>
+- 🔒 **Private by design** — files travel directly between browsers over encrypted WebRTC. The server only brokers the initial handshake; it never sees your file contents.
+- 🚀 **No size limit** — received files stream straight to disk, so even multi-gigabyte transfers use almost no memory (over HTTPS — see [how files are saved](#how-received-files-are-saved)).
+- 👥 **One-to-many** — share a room link or QR code and send to as many devices at once.
+- 🌐 **Works across networks** — connects directly when possible, with automatic STUN/TURN relay fallback for restrictive NATs and firewalls.
+- 🪄 **No installs, no accounts** — recipients just open a link in any modern browser. Optional password protection per room.
+- 🐳 **Self-hosted** — a single Docker image you run yourself.
 
-# Installation
+## Table of contents
 
-## Prerequisites
+- [Features](#features)
+- [Table of contents](#table-of-contents)
+- [How to use](#how-to-use)
+- [Self-hosting](#self-hosting)
+  - [Prerequisites](#prerequisites)
+  - [Option A — HTTP (local network / quick start)](#option-a--http-local-network--quick-start)
+  - [Option B — HTTPS (public domain, recommended)](#option-b--https-public-domain-recommended)
+  - [Stopping FileSync](#stopping-filesync)
+- [Required ports](#required-ports)
+- [Customizing ports](#customizing-ports)
+- [Configuration](#configuration)
+- [How received files are saved](#how-received-files-are-saved)
+- [Under the hood](#under-the-hood)
+- [License](#license)
 
-- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed
-- Python 3 (for generating the secret key)
+## How to use
 
-## Quick Start
+1. **Open** your FileSync URL — you land in a room with a unique link and a QR code.
+2. **Share** the link (or QR) with the people or devices you want to send to.
+3. **Drop in your files** — drag and drop them (or click **Send Files**). Recipients see them appear and can download instantly.
 
-### Option 1: HTTP (Local Development)
+> Want to restrict access? Click **Add password** to protect the room before sharing the link.
 
-**1. Download the required files**
+## Self-hosting
 
-Get [docker-compose.yml](deploy/docker-compose.yml) from the `deploy` folder.
+### Prerequisites
 
-**2. Generate a secret key**
+- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/)
+- Python 3 (only to generate the secret key below)
 
-Run the following command to generate a secure 32-byte base64-encoded secret:
+Every deployment needs a **secret key** (it signs the TURN credentials used for NAT traversal). Generate one with:
 
 ```bash
 python3 -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
 ```
 
-**3. Configure the secret**
-
-Open `docker-compose.yml` and replace **both occurrences** of `<SECRET_KEY>` with the generated value.
-
-Example:
-```yaml
-...
-- --static-auth-secret=/RaFOHJQQPAAXRNdaDhfBghvX9+o9UJEazKgIopK3TI=
-...
-- SECRET_KEY=/RaFOHJQQPAAXRNdaDhfBghvX9+o9UJEazKgIopK3TI=
-...
-```
-
-**4. Start FileSync**
-
-```bash
-docker-compose up -d
-```
+> ⚠️ Use your **own** generated value — never ship the examples shown below.
 
-Access FileSync at `http://localhost:80`
+### Option A — HTTP (local network / quick start)
 
-### Option 2: HTTPS (Production with Custom Domain)
+Best for trying FileSync or running it on a trusted LAN. Note that large transfers (>~500 MB) are unreliable over plain HTTP — for those, use [Option B](#option-b--https-public-domain-recommended).
 
-**1. Download the required files**
+**1. Download** [`deploy/docker-compose.yml`](deploy/docker-compose.yml).
 
-Get [docker-compose-ssl.yml](deploy/docker-compose-ssl.yml) and [Caddyfile](deploy/Caddyfile) from the `deploy` folder.
+**2. Set your secret.** Replace **both** `<SECRET_KEY>` placeholders with your generated value:
 
-**2. Generate a secret key**
+```yaml
+# (use your own generated value — these are illustrative)
+- --static-auth-secret=Hs9k…your-generated-key…=
+- SECRET_KEY=Hs9k…your-generated-key…=
+```
 
-Run the following command to generate a secure 32-byte base64-encoded secret:
+**3. Start it:**
 
 ```bash
-python3 -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
+docker compose up -d
 ```
 
-**3. Configure the secret**
+Open **`http://localhost`** (or your server's IP).
 
-Open `docker-compose-ssl.yml` and replace **both occurrences** of `<SECRET_KEY>` with the generated value.
+### Option B — HTTPS (public domain, recommended)
 
-Example:
-```yaml
-...
-- --static-auth-secret=/RaFOHJQQPAAXRNdaDhfBghvX9+o9UJEazKgIopK3TI=
-...
-- SECRET_KEY=/RaFOHJQQPAAXRNdaDhfBghvX9+o9UJEazKgIopK3TI=
-...
-```
+Caddy obtains and renews a Let's Encrypt certificate automatically. HTTPS also unlocks memory-safe streaming for files of any size.
 
-**4. Configure your domain**
+**1. Download** [`deploy/docker-compose-ssl.yml`](deploy/docker-compose-ssl.yml) and [`deploy/Caddyfile`](deploy/Caddyfile).
 
-Open `Caddyfile` and replace `yourdomain.com` with your actual domain.
+**2. Set your secret.** Replace **both** `<SECRET_KEY>` placeholders (same as Option A).
 
-Example:
-```
-filesync.app {
-	reverse_proxy filesync:80
+**3. Set your domain.** In `Caddyfile`, replace `yourdomain.com` with your domain:
+
+```caddyfile
+filesync.example.com {
+    reverse_proxy filesync:80
 }
 ```
 
-**5. Start FileSync**
+**4. Start it:**
 
 ```bash
-docker-compose -f docker-compose-ssl.yml up -d
+docker compose -f docker-compose-ssl.yml up -d
 ```
 
-Caddy will automatically obtain and manage SSL certificates from Let's Encrypt.
+Open **`https://yourdomain.com`**.
 
-Access FileSync at `https://yourdomain.com`
-
-## Stopping FileSync
+### Stopping FileSync
 
 ```bash
-# For HTTP setup
-docker-compose down
-
-# For HTTPS setup
-docker-compose -f docker-compose-ssl.yml down
+docker compose down                          # HTTP setup
+docker compose -f docker-compose-ssl.yml down  # HTTPS setup
 ```
 
-## Required Ports
-
-To expose FileSync to the internet, ensure the following ports are open on your server/firewall:
-
-### HTTP Setup
-- **Port 80** (TCP) - Web interface
-- **Port 3478** (TCP + UDP) - STUN/TURN server for WebRTC
+## Required ports
 
-### HTTPS Setup
-- **Port 443** (TCP) - Web interface (HTTPS)
-- **Port 3478** (TCP + UDP) - STUN/TURN server for WebRTC
+Open these on your server/firewall to expose FileSync to the internet:
 
-> **Note:** Port 3478 is essential for establishing peer-to-peer connections, especially when devices are behind NAT/firewalls.
+| Port | Protocol | Purpose |
+|---|---|---|
+| `80` *(HTTP)* / `443` *(HTTPS)* | TCP | Web interface |
+| `3478` | TCP + UDP | STUN/TURN — peer-to-peer connection setup |
+| `50000–50100` | UDP | TURN relay range — used when a direct connection isn't possible |
 
-## Customizing Ports
+> Port `3478` handles connection setup. The `50000–50100` UDP range carries relayed traffic for the ~5–10% of connections that can't go direct (typically a peer behind symmetric NAT or a UDP-blocking firewall).
 
-### Changing the HTTP Port
+## Customizing ports
 
-By default, FileSync uses port 80. To use a different port (e.g., 8080):
-
-**1. Edit `docker-compose.yml`**
-
-Find the `ports` section under the `filesync` service:
+**HTTP port.** In `docker-compose.yml`, change the **first** number of the `filesync` port mapping (the second is the internal container port — leave it as `80`):
 
 ```yaml
 ports:
-  - "80:80"
+  - "8080:80"   # serve on http://localhost:8080
 ```
 
-Change the **first** port number to your desired port:
+**HTTPS port.** Keep Caddy on `443` and put your own reverse proxy (Nginx, Traefik, standalone Caddy) in front if you need a non-standard external port — terminate TLS there and forward to FileSync's internal HTTP port.
 
-```yaml
-ports:
-  - "8080:80"
-```
+## Configuration
 
-**2. Access FileSync**
+Environment variables on the `filesync` service:
 
-Access FileSync at `http://localhost:8080` (or your server IP with the new port).
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `SECRET_KEY` | **Yes** | — | Signs TURN credentials and tokens. Must match the coturn `--static-auth-secret`. The app won't start without it. |
 
-> **Note:** The second port number (80) should remain unchanged as it refers to the internal container port.
+## How received files are saved
 
-### Changing the HTTPS Port
+FileSync writes received files to disk as the bytes arrive, so transfers use almost no memory regardless of size. It uses the first method the browser supports, falling back in order:
 
-To use a custom external port, deploy a separate reverse proxy (Nginx, Traefik, or standalone Caddy) that:
-- Listens on port 443 with SSL termination
-- Forwards traffic to FileSync on your custom internal HTTP port
+1. **File System Access API** — streams straight to a file you pick. Desktop Chromium browsers (Chrome, Edge, Brave, Opera) over HTTPS.
+2. **Service Worker** — streams into a normal browser download. All modern browsers over HTTPS.
+3. **Blob** — buffers the whole file in memory, then saves it. Last resort; the only option over plain HTTP, and unreliable past ~500 MB.
 
-This approach maintains standard HTTPS on port 443 while allowing flexible internal port configuration.
+The first two require a secure context (HTTPS, or `localhost`), so **serving FileSync over HTTPS is recommended** — it enables memory-safe transfers of any size.
 
 ## Under the hood
 
-FileSync uses [PeerJS](https://github.com/peers/peerjs) (a WebRTC wrapper) to transfer files between multiple devices. Files shared are peer-to-peer, which means there is a direct file transfer between the sender and receiver without any intermediate server. Your files remain private and secure throughout the entire transfer process.
+FileSync uses native [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API) to transfer files directly between devices — peer-to-peer, with no intermediate server in the data path. Your files stay private throughout.
+
+A lightweight WebSocket signaling server (served at `/ws` by the FileSync app itself) assists only with the initial connection setup — relaying SDP offers/answers and ICE candidates between peers. Once a peer-to-peer connection is established, the signaling server steps back and file bytes flow directly between browsers. **The server never has access to file contents.**
+
+![File Transfer - https://xkcd.com/949](web/assets/comic.png)
+
+## License
 
-![File Transfer - https://xkcd.com/949](web/assets/comic.png)
+Released under the [MIT License](LICENSE).