DragonWind/README.md

🌪️ Dragon Wind

Fast, dual-mode broadcast file uploader with S3 integration, UDP acceleration, and a Chrome extension.

---

Features

• HTTP Upload — Direct S3 presigned uploads, 50–200 MB/s on LAN
• UDP Upload — Relay-accelerated transfers, 4–8× faster on WAN/lossy networks
• Admin Web UI — Configure S3, UDP relay, users, and folders — all from the browser
• S3 Test & Confirm — Test connection with a real upload/delete before saving
• Chrome Extension — Drag-and-drop uploads from any browser tab
• AMPP Monitor — Live Grass Valley AMPP job queue monitoring
• User Management — Admin and user roles, session auth
• Folder Tree — Configurable prefix hierarchy for S3 organization
• Dark/Light Mode — Persistent theme preference

---

Quick Start

# 1. Clone
git clone https://forge.wilddragon.net/zgaetano/DragonWind.git
cd DragonWind

# 2. Configure
cp .env.example .env
# Edit .env with your S3 credentials

# 3. Start
docker-compose up -d

# 4. Open
open http://localhost:3000
# Default login: Admin / DragonWind2026!

---

Services

Service	Port	Protocol	Description
dragon-wind	3000	TCP/HTTP	Main web app + API
udp-relay	3001	TCP/HTTP	Relay control API
udp-relay	5000	UDP	Data transfer — port-forward this

---

Port Forwarding (Required for UDP Mode)

For UDP uploads to work from external clients:

Router Port	Internal Host	Internal Port	Protocol
5000	Your relay server IP	5000	UDP
3001	Your relay server IP	3001	TCP

See INFRASTRUCTURE.md for detailed setup instructions.

---

Chrome Extension

1. Open chrome://extensions/
2. Enable Developer mode
3. Click Load unpacked
4. Select the chrome-extension/ folder
5. Click the 🌪️ icon → Settings → enter your Dragon Wind server URL + credentials

---

Admin Configuration

All settings are available via the web UI at http://localhost:3000 → Admin tab:

• S3 Storage — Set endpoint, bucket, credentials. Use "Test Connection" to verify with a live upload.
• UDP Relay — Set relay URL and UDP port. Use "Test Relay" to verify connectivity.
• Users — Create/delete users, assign admin/user roles.
• Folders — Manage the folder prefix tree.

---

API Reference

Upload (HTTP)

POST /api/presigned         Get presigned S3 PUT URL
POST /api/upload            Multipart form upload (server-side)

UDP Sessions

POST /api/udp/session       Create UDP session
GET  /api/udp/session/:id   Get session status
POST /api/udp/session/:id/complete   Mark session complete
GET  /api/udp/relay/health  Check relay health

Admin

GET  /api/s3/config         Get S3 config (admin)
PUT  /api/s3/config         Update S3 config (admin)
POST /api/s3/test           Test S3 connection (admin)
GET  /api/relay/config      Get relay config (admin)
PUT  /api/relay/config      Update relay config (admin)

Auth / Users / Folders

POST /api/login
POST /api/logout
GET  /api/users             (admin)
POST /api/users             (admin)
DELETE /api/users/:user     (admin)
GET  /api/folders
POST /api/folders/add       (admin)
POST /api/folders/delete    (admin)

---

UDP Relay Architecture

Client Browser ──[UDP chunks]──▶ Dragon Wind Relay ──[S3 Multipart]──▶ S3
              ◀──[TCP ACK]────── (port 5000 UDP)       (port 3001 API)

The relay handles:

• UDP chunk reception with sequence numbers
• S3 multipart upload assembly
• Forward error correction via retransmission
• Session lifecycle management

---

Performance

Scenario	HTTP	UDP	Improvement
LAN	200 MB/s	180 MB/s	—
WAN (stable)	50 MB/s	200+ MB/s	4×
WAN (lossy)	5 MB/s	40 MB/s	8×
10 GB file	~30 min	5–10 min	3–6×

---

Built for Grass Valley AMPP / FramelightX broadcast workflows.