Upload Protocol & Server

<FileUploader
  endpoint="/legacy/upload"
  fieldNames={{
    chunk: "file",
    fileName: "originalname",
    fileSize: "originalFileSize",
  }}
/>

// lib/chunk-store.ts
import { randomUUID } from "node:crypto";
import {
  appendFile,
  mkdir,
  readFile,
  rename,
  rm,
  stat,
  writeFile,
} from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
 
const TEMP_ROOT = path.join(tmpdir(), "chunks");
const UPLOAD_ROOT = path.resolve("uploads");
const UPLOAD_ID = /^[\w-]{8,64}$/;
const MAX_CHUNKS = 10_000;
 
export class ChunkError extends Error {
  status: number;
  constructor(message: string, status: number) {
    super(message);
    this.status = status;
  }
}
 
export interface ChunkInput {
  uploadId: string;
  fileName: string;
  chunkIndex: number;
  totalChunks: number;
  fileSize: number;
  bytes: Uint8Array;
}
 
export async function saveChunk(input: ChunkInput) {
  const {
    uploadId,
    chunkIndex: index,
    totalChunks: total,
    fileSize,
    bytes,
  } = input;
  // Display name only: never part of a path.
  const fileName = path.basename(input.fileName.replaceAll("\\", "/"));
 
  const valid =
    UPLOAD_ID.test(uploadId) &&
    Number.isInteger(index) &&
    Number.isInteger(total) &&
    index >= 0 &&
    index < total &&
    total <= MAX_CHUNKS &&
    Number.isFinite(fileSize);
  if (!valid) throw new ChunkError("Invalid chunk metadata", 400);
 
  const dir = path.join(TEMP_ROOT, uploadId);
  await mkdir(dir, { recursive: true });
  // Write, then rename: a retried chunk replaces the old one in a single step.
  const temp = path.join(dir, `${index}.${randomUUID()}.tmp`);
  await writeFile(temp, bytes);
  await rename(temp, path.join(dir, String(index)));
 
  if (index < total - 1) return { status: "chunk_received", chunkIndex: index };
 
  await mkdir(UPLOAD_ROOT, { recursive: true });
  const storedName = `${randomUUID()}${path.extname(fileName)}`;
  const target = path.join(UPLOAD_ROOT, storedName);
  try {
    for (let i = 0; i < total; i++) {
      await appendFile(target, await readFile(path.join(dir, String(i))));
    }
    if ((await stat(target)).size !== fileSize)
      throw new Error("Size mismatch");
  } catch (error) {
    await rm(target, { force: true });
    throw new ChunkError(
      error instanceof Error ? error.message : "Could not assemble file",
      422,
    );
  }
  await rm(dir, { recursive: true, force: true });
 
  return {
    status: "complete",
    id: storedName,
    metadata: { storedName, originalName: fileName, fileSize },
  };
}

// app/api/upload/route.ts
import { ChunkError, saveChunk } from "@/lib/chunk-store";
 
export async function POST(request: Request) {
  const form = await request.formData();
  const chunk = form.get("chunk");
  if (!(chunk instanceof Blob))
    return Response.json({ error: "Missing chunk" }, { status: 400 });
 
  try {
    const result = await saveChunk({
      uploadId: String(form.get("uploadId")),
      fileName: String(form.get("fileName")),
      chunkIndex: Number(form.get("chunkIndex")),
      totalChunks: Number(form.get("totalChunks")),
      fileSize: Number(form.get("fileSize")),
      bytes: new Uint8Array(await chunk.arrayBuffer()),
    });
    return Response.json(result);
  } catch (error) {
    if (error instanceof ChunkError)
      return Response.json({ error: error.message }, { status: error.status });
    throw error;
  }
}

// server.ts
import express from "express";
import multer from "multer";
import { ChunkError, saveChunk } from "./lib/chunk-store";
 
const app = express();
const parts = multer({
  storage: multer.memoryStorage(),
  limits: { fileSize: 16 * 1024 * 1024 },
});
 
app.post("/api/upload", parts.single("chunk"), async (req, res, next) => {
  if (!req.file) return res.status(400).json({ error: "Missing chunk" });
  try {
    res.json(
      await saveChunk({
        uploadId: String(req.body.uploadId),
        fileName: String(req.body.fileName),
        chunkIndex: Number(req.body.chunkIndex),
        totalChunks: Number(req.body.totalChunks),
        fileSize: Number(req.body.fileSize),
        bytes: req.file.buffer,
      }),
    );
  } catch (error) {
    if (error instanceof ChunkError)
      return res.status(error.status).json({ error: error.message });
    next(error);
  }
});
 
app.listen(3000);

// upload/handler.go
package upload
 
import (
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"path/filepath"
	"regexp"
	"strconv"
	"strings"
)
 
const (
	tempRoot   = "./tmp/chunks"
	uploadRoot = "./uploads"
	maxChunk   = 10 << 20 // keep above the client's chunkSize
	maxChunks  = 10_000
)
 
var uploadIDPattern = regexp.MustCompile(`^[\w-]{8,64}$`)
 
func Handle(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodPost {
		writeJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "method not allowed"})
		return
	}
	r.Body = http.MaxBytesReader(w, r.Body, maxChunk+1<<20)
	if err := r.ParseMultipartForm(maxChunk); err != nil {
		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid form"})
		return
	}
	defer r.MultipartForm.RemoveAll()
 
	uploadID := r.FormValue("uploadId")
	// Display name only. Backslashes are separators on Windows clients, whatever the server OS.
	fileName := filepath.Base(strings.ReplaceAll(r.FormValue("fileName"), "\\", "/"))
	index, errIndex := strconv.Atoi(r.FormValue("chunkIndex"))
	total, errTotal := strconv.Atoi(r.FormValue("totalChunks"))
	fileSize, errSize := strconv.ParseInt(r.FormValue("fileSize"), 10, 64)
	if !uploadIDPattern.MatchString(uploadID) || errIndex != nil || errTotal != nil || errSize != nil ||
		index < 0 || index >= total || total > maxChunks {
		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid chunk metadata"})
		return
	}
 
	chunk, _, err := r.FormFile("chunk")
	if err != nil {
		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "missing chunk"})
		return
	}
	defer chunk.Close()
 
	dir := filepath.Join(tempRoot, uploadID)
	if err := saveChunk(dir, index, chunk); err != nil {
		writeJSON(w, http.StatusInternalServerError, map[string]string{"error": "could not store chunk"})
		return
	}
 
	if index < total-1 {
		writeJSON(w, http.StatusOK, map[string]any{"status": "chunk_received", "chunkIndex": index})
		return
	}
 
	storedName := randomID() + filepath.Ext(fileName)
	if err := assemble(dir, total, filepath.Join(uploadRoot, storedName), fileSize); err != nil {
		writeJSON(w, http.StatusUnprocessableEntity, map[string]string{"error": err.Error()})
		return
	}
	os.RemoveAll(dir)
 
	writeJSON(w, http.StatusOK, map[string]any{
		"status":   "complete",
		"id":       storedName,
		"metadata": map[string]any{"storedName": storedName, "originalName": fileName, "fileSize": fileSize},
	})
}
 
// saveChunk writes to a temporary file, then renames it over any earlier copy of the chunk.
func saveChunk(dir string, index int, chunk io.Reader) error {
	if err := os.MkdirAll(dir, 0o750); err != nil {
		return err
	}
	tmp, err := os.CreateTemp(dir, "part-*")
	if err != nil {
		return err
	}
	if _, err := io.Copy(tmp, chunk); err != nil {
		tmp.Close()
		os.Remove(tmp.Name())
		return err
	}
	if err := tmp.Close(); err != nil {
		return err
	}
	return os.Rename(tmp.Name(), filepath.Join(dir, strconv.Itoa(index)))
}
 
func assemble(dir string, total int, target string, want int64) error {
	if err := os.MkdirAll(filepath.Dir(target), 0o750); err != nil {
		return err
	}
	out, err := os.OpenFile(target, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o640)
	if err != nil {
		return err
	}
	fail := func(err error) error {
		out.Close()
		os.Remove(target)
		return err
	}
 
	var written int64
	for i := 0; i < total; i++ {
		in, err := os.Open(filepath.Join(dir, strconv.Itoa(i)))
		if err != nil {
			return fail(fmt.Errorf("missing chunk %d", i))
		}
		n, err := io.Copy(out, in)
		in.Close() // close before the folder is deleted, or Windows refuses
		if err != nil {
			return fail(err)
		}
		written += n
	}
	if err := out.Close(); err != nil {
		os.Remove(target)
		return err
	}
	if written != want {
		os.Remove(target)
		return fmt.Errorf("size mismatch: expected %d, got %d", want, written)
	}
	return nil
}
 
func randomID() string {
	b := make([]byte, 16)
	rand.Read(b)
	return hex.EncodeToString(b)
}
 
func writeJSON(w http.ResponseWriter, status int, body any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	json.NewEncoder(w).Encode(body)
}

// src/main/java/com/example/upload/UploadController.java
package com.example.upload;
 
import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.nio.file.StandardOpenOption;
import java.util.Map;
import java.util.UUID;
import java.util.regex.Pattern;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.util.FileSystemUtils;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
 
@RestController
@RequestMapping("/api/upload")
public class UploadController {
 
    private static final Pattern UPLOAD_ID = Pattern.compile("^[\\w-]{8,64}$");
    private static final int MAX_CHUNKS = 10_000;
 
    private final Path tempRoot = Path.of(System.getProperty("java.io.tmpdir"), "chunks");
    private final Path uploadRoot = Path.of("uploads");
 
    @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<?> upload(
            @RequestParam String uploadId,
            @RequestParam String fileName,
            @RequestParam int chunkIndex,
            @RequestParam int totalChunks,
            @RequestParam long fileSize,
            @RequestParam(required = false) String additionalParams,
            @RequestParam("chunk") MultipartFile chunk) throws IOException {
 
        if (!UPLOAD_ID.matcher(uploadId).matches()
                || chunkIndex < 0 || chunkIndex >= totalChunks || totalChunks > MAX_CHUNKS) {
            return ResponseEntity.badRequest().body(Map.of("error", "Invalid chunk metadata"));
        }
        // Display name only: strip any directories the client sent.
        String safeName = fileName.replaceAll(".*[/\\\\]", "");
 
        Path dir = tempRoot.resolve(uploadId);
        Files.createDirectories(dir);
        // Write, then move: a retried chunk replaces the old one in a single step.
        Path temp = Files.createTempFile(dir, "part-", ".tmp");
        chunk.transferTo(temp);
        Files.move(temp, dir.resolve(Integer.toString(chunkIndex)), StandardCopyOption.REPLACE_EXISTING);
 
        if (chunkIndex < totalChunks - 1) {
            return ResponseEntity.ok(Map.of("status", "chunk_received", "chunkIndex", chunkIndex));
        }
 
        int dot = safeName.lastIndexOf('.');
        String storedName = UUID.randomUUID() + (dot >= 0 ? safeName.substring(dot) : "");
        Files.createDirectories(uploadRoot);
        Path target = uploadRoot.resolve(storedName);
 
        try (OutputStream out = Files.newOutputStream(target, StandardOpenOption.CREATE_NEW)) {
            for (int i = 0; i < totalChunks; i++) {
                Path piece = dir.resolve(Integer.toString(i));
                if (!Files.exists(piece)) {
                    throw new IOException("Missing chunk " + i);
                }
                Files.copy(piece, out);
            }
        } catch (IOException e) {
            Files.deleteIfExists(target);
            return ResponseEntity.unprocessableEntity().body(Map.of("error", String.valueOf(e.getMessage())));
        }
 
        if (Files.size(target) != fileSize) {
            Files.delete(target);
            return ResponseEntity.unprocessableEntity().body(Map.of("error", "Size mismatch"));
        }
        FileSystemUtils.deleteRecursively(dir);
 
        return ResponseEntity.ok(Map.of(
                "status", "complete",
                "id", storedName,
                "metadata", Map.of("storedName", storedName, "originalName", safeName, "fileSize", fileSize)));
    }
}

# application.properties
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=11MB

// Program.cs
using System.Text.RegularExpressions;
 
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
 
var uploadIdPattern = new Regex(@"^[\w-]{8,64}$");
var tempRoot = Path.Combine(Path.GetTempPath(), "chunks");
var uploadRoot = Path.Combine(app.Environment.ContentRootPath, "uploads");
const int MaxChunks = 10_000;
 
app.MapPost("/api/upload", async (HttpRequest request) =>
{
    var form = await request.ReadFormAsync();
    var uploadId = form["uploadId"].ToString();
    // Display name only: strip any directories the client sent.
    var fileName = Path.GetFileName(form["fileName"].ToString().Replace('\\', '/'));
    var chunk = form.Files["chunk"];
 
    if (chunk is null
        || !uploadIdPattern.IsMatch(uploadId)
        || !int.TryParse(form["chunkIndex"], out var index)
        || !int.TryParse(form["totalChunks"], out var total)
        || !long.TryParse(form["fileSize"], out var fileSize)
        || index < 0 || index >= total || total > MaxChunks)
    {
        return Results.BadRequest(new { error = "Invalid chunk metadata" });
    }
 
    var dir = Path.Combine(tempRoot, uploadId);
    Directory.CreateDirectory(dir);
    // Write, then move: a retried chunk replaces the old one in a single step.
    var temp = Path.Combine(dir, $"{index}.{Guid.NewGuid():N}.tmp");
    await using (var stream = File.Create(temp))
    {
        await chunk.CopyToAsync(stream);
    }
    File.Move(temp, Path.Combine(dir, index.ToString()), overwrite: true);
 
    if (index < total - 1)
    {
        return Results.Ok(new { status = "chunk_received", chunkIndex = index });
    }
 
    Directory.CreateDirectory(uploadRoot);
    var storedName = $"{Guid.NewGuid():N}{Path.GetExtension(fileName)}";
    var target = Path.Combine(uploadRoot, storedName);
 
    try
    {
        await using (var output = new FileStream(target, FileMode.CreateNew))
        {
            for (var i = 0; i < total; i++)
            {
                var piece = Path.Combine(dir, i.ToString());
                if (!File.Exists(piece)) throw new IOException($"Missing chunk {i}");
                await using var input = File.OpenRead(piece);
                await input.CopyToAsync(output);
            }
        }
        if (new FileInfo(target).Length != fileSize) throw new IOException("Size mismatch");
    }
    catch (IOException ex)
    {
        File.Delete(target);
        return Results.UnprocessableEntity(new { error = ex.Message });
    }
 
    Directory.Delete(dir, recursive: true);
    return Results.Ok(new
    {
        status = "complete",
        id = storedName,
        metadata = new { storedName, originalName = fileName, fileSize },
    });
});
 
app.Run();

URL=http://localhost:3000/api/upload
printf 'hello ' > part0 && printf 'world' > part1
 
# 1. First chunk → 200 {"status":"chunk_received",...}
curl -s -F uploadId=conformance-01 -F fileName=hello.txt -F chunkIndex=0 -F totalChunks=2 \
  -F fileSize=11 -F chunk=@part0 $URL
 
# 2. Send it again (a retry) → 200, nothing breaks
curl -s -F uploadId=conformance-01 -F fileName=hello.txt -F chunkIndex=0 -F totalChunks=2 \
  -F fileSize=11 -F chunk=@part0 $URL
 
# 3. Last chunk → 200 {"status":"complete","id":...}; the stored file contains "hello world"
curl -s -F uploadId=conformance-01 -F fileName=hello.txt -F chunkIndex=1 -F totalChunks=2 \
  -F fileSize=11 -F chunk=@part1 $URL
 
# 4. Index out of range → 400
curl -s -o /dev/null -w "%{http_code}\n" -F uploadId=conformance-02 -F fileName=x.txt \
  -F chunkIndex=5 -F totalChunks=2 -F fileSize=11 -F chunk=@part0 $URL
 
# 5. Path in the name → stored under a generated name, nothing written outside the upload folder
curl -s -F uploadId=conformance-03 -F "fileName=../../evil.txt" -F chunkIndex=0 -F totalChunks=1 \
  -F fileSize=6 -F chunk=@part0 $URL

interface ChunkRequest {
  file: File;
  chunk: Blob;
  index: number;
  total: number;
  offset: number;
  uploadId: string;
  signal: AbortSignal;
  onProgress(loaded: number): void;
}

import { UploadHttpError, type Transport } from "@/component-lib/file-uploader";
 
const rangeTransport: Transport = async ({
  file,
  chunk,
  offset,
  uploadId,
  signal,
}) => {
  const response = await fetch(`/api/files/${uploadId}`, {
    method: "PUT",
    signal,
    headers: {
      "Content-Range": `bytes ${offset}-${offset + chunk.size - 1}/${file.size}`,
      "X-File-Name": encodeURIComponent(file.name),
    },
    body: chunk,
  });
  if (!response.ok)
    throw new UploadHttpError(response.status, await response.text());
  return response.json();
};
 
<FileUploader transport={rangeTransport} />;