feat(upload): support batching via header and update ShareX config

Introduce support for grouping multiple sequential file uploads into a single box using the `X-Warpbox-Batch` header. This is particularly useful for ShareX multi-file selections, which are sent as separate back-to-back requests.

Additionally, this change:
- Updates the ShareX configuration template to opt-in to batching by default.
- Switches ShareX configuration placeholders to the modern `{json:...}` format.
- Adds `thumbnailUrl` to the upload response schema and documents its usage.

backend/libs/handlers/api_docs.go

@@ -17,6 +17,7 @@ type apiDocsData struct {
 	ShareXExampleURL    string
 	ShareXDownloadURL   string
 	ShareXFileFieldName string
+	ShareXGroupWindow   string
 }
 
 func (a *App) APIDocs(w http.ResponseWriter, r *http.Request) {
@@ -33,6 +34,7 @@ func (a *App) APIDocs(w http.ResponseWriter, r *http.Request) {
 			ShareXExampleURL:    a.cfg.BaseURL + "/api/v1/upload",
 			ShareXDownloadURL:   a.cfg.BaseURL + "/api/v1/sharex/warpbox-anonymous.sxcu",
 			ShareXFileFieldName: "sharex",
+			ShareXGroupWindow:   uploadGroupWindow.String(),
 		},
 	})
 }
@@ -47,11 +49,16 @@ func (a *App) ShareXAnonymousConfig(w http.ResponseWriter, r *http.Request) {
 		"RequestURL":      a.cfg.BaseURL + "/api/v1/upload",
 		"Headers": map[string]string{
 			"Accept": "application/json",
+			// Group a multi-file selection (sent as back-to-back requests) into
+			// one box. Remove this header for one box per file.
+			uploadBatchHeader: "sharex",
 		},
 		"Body":         "MultipartFormData",
 		"FileFormName": "sharex",
-		"URL":          "$json:boxUrl$",
-		"DeletionURL":  "$json:manageUrl$",
+		"URL":          "{json:boxUrl}",
+		"ThumbnailURL": "{json:thumbnailUrl}",
+		"DeletionURL":  "{json:deleteUrl}",
+		"ErrorMessage": "{json:error}",
 	})
 }
 
@@ -109,22 +116,24 @@ func (a *App) UploadResponseSchema(w http.ResponseWriter, r *http.Request) {
 		"type":        "object",
 		"required":    []string{"boxId", "boxUrl", "zipUrl", "manageUrl", "deleteUrl", "expiresAt", "files"},
 		"properties": map[string]any{
-			"boxId":     map[string]any{"type": "string"},
-			"boxUrl":    map[string]any{"type": "string", "format": "uri"},
-			"zipUrl":    map[string]any{"type": "string", "format": "uri"},
-			"manageUrl": map[string]any{"type": "string", "format": "uri", "description": "Private bearer URL for managing/deleting this upload. Returned only at upload time."},
-			"deleteUrl": map[string]any{"type": "string", "format": "uri", "description": "Private bearer POST URL for deleting this upload. Returned only at upload time."},
-			"expiresAt": map[string]any{"type": "string", "format": "date-time"},
+			"boxId":        map[string]any{"type": "string"},
+			"boxUrl":       map[string]any{"type": "string", "format": "uri"},
+			"zipUrl":       map[string]any{"type": "string", "format": "uri"},
+			"thumbnailUrl": map[string]any{"type": "string", "format": "uri", "description": "Thumbnail of the most recently uploaded file (placeholder until generated)."},
+			"manageUrl":    map[string]any{"type": "string", "format": "uri", "description": "Private bearer URL for managing/deleting this upload. Returned only at upload time."},
+			"deleteUrl":    map[string]any{"type": "string", "format": "uri", "description": "Private bearer URL for deleting this upload (GET or POST). Returned only at upload time."},
+			"expiresAt":    map[string]any{"type": "string", "format": "date-time"},
 			"files": map[string]any{
 				"type": "array",
 				"items": map[string]any{
 					"type":     "object",
 					"required": []string{"id", "name", "size", "url"},
 					"properties": map[string]any{
-						"id":   map[string]any{"type": "string"},
-						"name": map[string]any{"type": "string"},
-						"size": map[string]any{"type": "string"},
-						"url":  map[string]any{"type": "string", "format": "uri"},
+						"id":           map[string]any{"type": "string"},
+						"name":         map[string]any{"type": "string"},
+						"size":         map[string]any{"type": "string"},
+						"url":          map[string]any{"type": "string", "format": "uri"},
+						"thumbnailUrl": map[string]any{"type": "string", "format": "uri"},
 					},
 				},
 			},

backend/libs/handlers/app.go

@@ -18,6 +18,7 @@ type App struct {
 	settingsService *services.SettingsService
 	banService      *services.BanService
 	rateLimiter     *rateLimiter
+	uploadGroups    *uploadGrouper
 }
 
 func NewApp(cfg config.Config, logger *slog.Logger, renderer *web.Renderer, uploadService *services.UploadService, authService *services.AuthService, settingsService *services.SettingsService, banService *services.BanService) *App {
@@ -30,6 +31,7 @@ func NewApp(cfg config.Config, logger *slog.Logger, renderer *web.Renderer, uplo
 		settingsService: settingsService,
 		banService:      banService,
 		rateLimiter:     newRateLimiter(),
+		uploadGroups:    newUploadGrouper(),
 	}
 }
 
@@ -112,6 +114,9 @@ func (a *App) RegisterRoutes(mux *http.ServeMux) {
 	mux.HandleFunc("GET /d/{boxID}/deleted", a.ManageDeleted)
 	mux.HandleFunc("GET /d/{boxID}/manage/{token}", a.ManageBox)
 	mux.HandleFunc("POST /d/{boxID}/manage/{token}/delete", a.ManageDeleteBox)
+	// GET variant so ShareX (which issues a GET to the configured DeletionURL)
+	// can delete a box via its secret one-time delete token.
+	mux.HandleFunc("GET /d/{boxID}/manage/{token}/delete", a.ManageDeleteBox)
 	mux.HandleFunc("POST /d/{boxID}/unlock", a.UnlockBox)
 	mux.HandleFunc("GET /d/{boxID}/zip", a.DownloadZip)
 	mux.HandleFunc("GET /d/{boxID}/f/{fileID}", a.DownloadFile)

backend/libs/handlers/upload.go

@@ -92,7 +92,7 @@ func (a *App) Upload(w http.ResponseWriter, r *http.Request) {
 		helpers.WriteJSONError(w, http.StatusRequestEntityTooLarge, fmt.Sprintf("expiration cannot exceed %d days", effectivePolicy.MaxDays))
 		return
 	}
-	result, err := a.uploadService.CreateBox(files, services.UploadOptions{
+	opts := services.UploadOptions{
 		MaxDays:           maxDays,
 		ExpiresInMinutes:  expiresMinutes,
 		MaxDownloads:      parseInt(r.FormValue("max_downloads")),
@@ -103,14 +103,15 @@ func (a *App) Upload(w http.ResponseWriter, r *http.Request) {
 		SkipSizeLimit:     isAdminUpload || effectivePolicy.MaxUploadMB < 0,
 		CreatorIP:         uploadClientIP(r),
 		StorageBackendID:  effectivePolicy.StorageBackendID,
-	})
+	}
+	result, boxesAdded, err := a.createOrAppendBox(r, user, loggedIn, files, opts)
 	if err != nil {
 		a.logger.Warn("upload failed", "source", "user-upload", "severity", "warn", "code", 4001, "ip", uploadClientIP(r), "user_id", user.ID, "error", err.Error())
 		helpers.WriteJSONError(w, http.StatusBadRequest, err.Error())
 		return
 	}
 	if !isAdminUpload {
-		if err := a.recordUploadUsage(r, user, loggedIn, totalBytes, 1); err != nil {
+		if err := a.recordUploadUsage(r, user, loggedIn, totalBytes, boxesAdded); err != nil {
 			a.logger.Warn("failed to record upload usage", "source", "quota", "severity", "warn", "code", 4402, "error", err.Error())
 		}
 		if err := a.settingsService.CleanupUsage(time.Now().UTC(), settings.UsageRetentionDays); err != nil {
@@ -130,6 +131,67 @@ func (a *App) Upload(w http.ResponseWriter, r *http.Request) {
 	_, _ = fmt.Fprintln(w, result.BoxURL)
 }
 
+// createOrAppendBox creates a new box. It only ever appends to an existing box
+// when the request opts in via the X-Warpbox-Batch header: requests sharing the
+// same batch value (per account, or per IP for anonymous) within
+// uploadGroupWindow are folded into one box. Without the header the behaviour is
+// identical to creating a fresh box every time. Returns the result and how many
+// boxes were created (1 for a new box, 0 for an append) for usage accounting.
+func (a *App) createOrAppendBox(r *http.Request, user services.User, loggedIn bool, files []*multipart.FileHeader, opts services.UploadOptions) (services.UploadResult, int, error) {
+	batch := strings.TrimSpace(r.Header.Get(uploadBatchHeader))
+	if batch == "" {
+		result, err := a.uploadService.CreateBox(files, opts)
+		if err != nil {
+			return services.UploadResult{}, 0, err
+		}
+		return result, 1, nil
+	}
+
+	// Group key is scoped to the uploader so batches never cross accounts/IPs.
+	identity := "ip:" + uploadClientIP(r)
+	if loggedIn {
+		identity = "user:" + user.ID
+	}
+	entry := a.uploadGroups.entryFor(identity + "|" + batch)
+
+	// Hold the per-key lock across the whole create/append so concurrent batched
+	// uploads serialise into the same box instead of racing.
+	entry.mu.Lock()
+	defer entry.mu.Unlock()
+
+	if entry.boxID != "" && time.Since(entry.at) < uploadGroupWindow {
+		if box, err := a.uploadService.GetBox(entry.boxID); err == nil && a.batchBoxMatches(box, user, loggedIn, r) && a.uploadService.CanDownload(box) == nil {
+			if result, err := a.uploadService.AppendFiles(entry.boxID, files, opts); err == nil {
+				// Re-attach the manage/delete URLs from the box's creation so every
+				// upload in the batch returns a working deletion URL.
+				result.ManageURL = entry.manageURL
+				result.DeleteURL = entry.deleteURL
+				entry.at = time.Now()
+				return result, 0, nil
+			}
+		}
+	}
+
+	result, err := a.uploadService.CreateBox(files, opts)
+	if err != nil {
+		return services.UploadResult{}, 0, err
+	}
+	entry.boxID = result.BoxID
+	entry.manageURL = result.ManageURL
+	entry.deleteURL = result.DeleteURL
+	entry.at = time.Now()
+	return result, 1, nil
+}
+
+// batchBoxMatches guards that a batched append only ever touches a box owned by
+// the same uploader (account for logged-in users, creator IP for anonymous).
+func (a *App) batchBoxMatches(box services.Box, user services.User, loggedIn bool, r *http.Request) bool {
+	if loggedIn {
+		return box.OwnerID == user.ID
+	}
+	return box.OwnerID == "" && box.CreatorIP == uploadClientIP(r)
+}
+
 func (a *App) checkUploadPolicy(r *http.Request, user services.User, loggedIn bool, settings services.UploadPolicySettings, policy services.EffectiveUploadPolicy, files []*multipart.FileHeader, totalBytes int64) (int, string) {
 	if len(files) == 0 {
 		return 0, ""

backend/libs/handlers/upload_group.go

@@ -0,0 +1,49 @@
+package handlers
+
+import (
+	"sync"
+	"time"
+)
+
+// uploadGroupWindow is how long after a batched upload a follow-up upload with
+// the same X-Warpbox-Batch value (and same account/IP) is folded into the same
+// box. ShareX sends a multi-file selection as separate back-to-back requests;
+// the batch header lets it land them in one box.
+const uploadGroupWindow = 20 * time.Second
+
+// uploadBatchHeader is the opt-in request header. Without it, uploads behave
+// exactly as before (one box per request). With it, requests sharing the same
+// value (per account/IP) within uploadGroupWindow are grouped into one box.
+const uploadBatchHeader = "X-Warpbox-Batch"
+
+// uploadGrouper tracks the most recent box per batch key so opt-in batched
+// uploads land in a single box. Each key has its own lock, which also serialises
+// that key's concurrent uploads so they append to the same box instead of racing
+// to create several.
+type uploadGrouper struct {
+	mu      sync.Mutex
+	entries map[string]*uploadGroupEntry
+}
+
+type uploadGroupEntry struct {
+	mu        sync.Mutex
+	boxID     string
+	manageURL string
+	deleteURL string
+	at        time.Time
+}
+
+func newUploadGrouper() *uploadGrouper {
+	return &uploadGrouper{entries: make(map[string]*uploadGroupEntry)}
+}
+
+func (g *uploadGrouper) entryFor(key string) *uploadGroupEntry {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	entry, ok := g.entries[key]
+	if !ok {
+		entry = &uploadGroupEntry{}
+		g.entries[key] = entry
+	}
+	return entry
+}