✨ What is URLDrop?

URLDrop is an admin-focused plugin that turns your Minecraft server into a download station.
Instead of SSH-ing into your machine to wget a backup or a world archive, you open a
chest GUI in-game, paste a URL, choose a destination, and let the server do the rest.

Perfect for:

• 📦 Downloading server backups from remote storage
• 🌍 Pulling world archives or data packs
• 🔌 Staging plugin updates without leaving the game
• 📁 Migrating large files between servers via URL

🖥️ GUI Overview

Open with /urldrop or /ud:

| Screen | Description |
|--------|-------------|
| Main Menu | Hub for all actions |
| New Download | 5-step wizard: URL → path → filename → checksum → confirm |
| Active Downloads | Live progress bars, speed, ETA, cancel button |
| Queue | Reorder, start-now, or remove pending jobs |
| History | Re-download or purge completed entries |
| Settings | Toggle runtime options without reloading |

⚡ Features

Downloads

• ✅ Async downloads on Java 21 virtual threads — zero main-thread blocking
• ✅ HTTP streaming directly to disk — no RAM spike for large files
• ✅ HTTP Range resume — picks up where it left off if interrupted
• ✅ Configurable retry with exponential back-off
• ✅ Automatic progress tracking (speed, ETA, % complete)
• ✅ Auto-unzip .zip archives after download
• ✅ Backup existing files before overwrite (with retention limit)

Security

• 🔒 Path traversal prevention (.. blocked before and after normalization)
• 🔒 URL validation — http/https only, optional domain whitelist/blacklist
• 🔒 Blocked file extensions / content-type filtering
• 🔒 Optional SHA-256 checksum verification before file is placed
• 🔒 Downloads stage to a temp file first, then atomically move to destination
• 🔒 File size hard cap (default 2 GB)

Destinations

• 📂 Any path the server process can reach (relative or absolute)
• 📂 Works with Pterodactyl (/home/container/...)
• 📂 Configurable path aliases (e.g. type backup → resolves to backups/)

Notifications

• 💬 Clickable in-game Adventure messages with [Retry] / [History] buttons
• 🔔 Operator join reminders for downloads that finished while you were offline
• 🟣 Discord webhook support with rich embeds

Commands

/ud                         Open GUI
/ud download <url> <path>   Start immediately
/ud queue <url> <path>      Add to queue
/ud status [id]             Show progress
/ud cancel <id>             Cancel
/ud retry <id>              Retry failed download
/ud history                 Recent history in chat
/ud debug <id>              Full diagnostics
/ud reload                  Reload config

⚙️ Configuration

Four config files are generated on first run:

| File | Purpose |
|------|---------|
| config.yml | Limits, timeouts, retry, security, notifications |
| messages.yml | All messages (MiniMessage format — fully customisable) |
| paths.yml | Aliases, sensitive paths, blocked fragments |
| webhook.yml | Discord webhook URL and event toggles |

Quick example — config.yml

max-simultaneous-downloads: 3
max-file-size-mb: 2048
allow-resume: true
auto-unzip: false
require-checksum-for-sensitive-paths: false
operator-notify-on-complete: true

Quick example — paths.yml aliases

aliases:
  backup: "backups"
  update: "plugins/update"
  home:   "/home/container"

🔐 Permissions

| Permission | Description |
|------------|-------------|
| urldrop.admin | All permissions |
| urldrop.open | Open the GUI |
| urldrop.download | Start downloads |
| urldrop.queue | Queue downloads |
| urldrop.cancel | Cancel downloads |
| urldrop.history | View history |
| urldrop.settings | Toggle settings |
| urldrop.reload | Reload config |
| urldrop.debug | View diagnostics |

All permissions default to operator only.

📋 Requirements

| Requirement | Version |
|-------------|---------|
| Server | Paper 1.21.x |
| Java | 21+ |

No other plugins required. Gson is bundled inside the JAR.