feat(files): 大文件分片上传、停服解压 zip 先列冲突再覆盖、文件和文件夹可下载；导出和下载不再带出 RCON 密码与转发密钥

cmd/felis/api.go

@@ -491,6 +491,9 @@ func cmdAPI(args []string, stdout, stderr io.Writer) int {
 		go pruner.Loop(ctx, registryPruneInterval)
 	}
 	go reapRejectedContexts(ctx, submissions, stderr)
+	if fileStage != nil {
+		go expireFileSessions(ctx, fileStage, fileSessionSweep, stderr)
+	}
 	go retention.Loop(ctx, drv.DB(), retention.Policy{Audit: auditRetention}, retentionInterval, slog.Default())
 
 	servers := []*http.Server{internalSrv, externalSrv}
@@ -797,6 +800,30 @@ func scheduleBackups(ctx context.Context, s *api.BackupScheduler, stderr io.Writ
 	}
 }
 
+// fileSessionSweep is how often expireFileSessions looks for idle upload
+// sessions: small beside fileedit.SessionIdle, so an abandoned one gives its
+// room back within minutes of going stale.
+const fileSessionSweep = 10 * time.Minute
+
+// expireFileSessions drops the file manager's upload sessions left untouched
+// for fileedit.SessionIdle. Each reserved room on the staging disk for its whole
+// file when it began, so one abandoned would otherwise hold that room until
+// felis-api restarts.
+func expireFileSessions(ctx context.Context, s *fileedit.Stage, every time.Duration, stderr io.Writer) {
+	t := time.NewTicker(every)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			if n := s.Expire(); n > 0 {
+				fmt.Fprintf(stderr, "felis api: dropped %d upload session(s) left idle for %s\n", n, fileedit.SessionIdle)
+			}
+		}
+	}
+}
+
 // reapRejectedContexts deletes, once an hour, the uploaded contexts of
 // submissions rejected more than submit.RejectedContextRetention ago, and the
 // chunked uploads left untouched for submit.StalePartRetention. Without it a

cmd/felis/api_test.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"bytes"
 	"context"
 	"errors"
 	"fmt"
@@ -8,6 +9,7 @@ import (
 	"net"
 	"net/http"
 	"slices"
+	"sync"
 	"sync/atomic"
 	"testing"
 	"time"
@@ -15,6 +17,7 @@ import (
 	"felis.lolicon.best/internal/api"
 	"felis.lolicon.best/internal/build"
 	"felis.lolicon.best/internal/config"
+	"felis.lolicon.best/internal/fileedit"
 )
 
 // The passkey relying party follows the panel host the SPA is served on: an install
@@ -235,3 +238,51 @@ func TestInUseImageRefsCoversEverySource(t *testing.T) {
 		t.Fatal("a failing whitelist read produced a reference list")
 	}
 }
+
+// TestExpireFileSessions runs the loop against a stage whose clock the test
+// holds: the session idle past fileedit.SessionIdle goes, the one touched since
+// stays, and the drop is said once.
+func TestExpireFileSessions(t *testing.T) {
+	var mu sync.Mutex
+	now := time.Date(2026, 9, 28, 10, 0, 0, 0, time.UTC)
+	advance := func(d time.Duration) { mu.Lock(); now = now.Add(d); mu.Unlock() }
+	st := &fileedit.Stage{Dir: t.TempDir(), MinFree: 1e-9, Now: func() time.Time {
+		mu.Lock()
+		defer mu.Unlock()
+		return now
+	}}
+	idle, err := st.Begin("u1", "survival", "a.jar", 3)
+	if err != nil {
+		t.Fatal(err)
+	}
+	advance(fileedit.SessionIdle - time.Minute)
+	fresh, err := st.Begin("u1", "survival", "b.jar", 3)
+	if err != nil {
+		t.Fatal(err)
+	}
+	advance(2 * time.Minute)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	var out bytes.Buffer
+	done := make(chan struct{})
+	go func() { expireFileSessions(ctx, st, time.Millisecond, &out); close(done) }()
+	for deadline := time.Now().Add(5 * time.Second); ; time.Sleep(time.Millisecond) {
+		if _, err := st.Status("u1", "survival", idle.ID); errors.Is(err, fileedit.ErrNotStaged) {
+			break
+		}
+		if time.Now().After(deadline) {
+			cancel()
+			t.Fatal("the idle session was never dropped")
+		}
+	}
+	// A few more ticks with nothing idle, which must stay quiet.
+	time.Sleep(20 * time.Millisecond)
+	cancel()
+	<-done
+	if _, err := st.Status("u1", "survival", fresh.ID); err != nil {
+		t.Fatalf("the session touched since went too: %v", err)
+	}
+	if got := out.String(); got != "felis api: dropped 1 upload session(s) left idle for 6h0m0s\n" {
+		t.Fatalf("said %q", got)
+	}
+}

cmd/felis/export.go

@@ -2,26 +2,33 @@ package main
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
+	"errors"
 	"flag"
 	"fmt"
+	"hash"
 	"io"
+	"io/fs"
 	"net/http"
 	"os"
 	"os/signal"
+	"strings"
 	"syscall"
 	"time"
 
 	"felis.lolicon.best/internal/backup"
+	"felis.lolicon.best/internal/fileedit"
 	"felis.lolicon.best/internal/worldexport"
 )
 
 // cmdExport is the in-Pod entrypoint the export Job runs. internal/worldexport
 // renders a Pod whose command is `/usr/local/bin/felis export`. It archives the
-// mounted world (or opens one archive on the mounted backup store), PUTs the
-// tar.gz to felis-api's internal face, and exits once felis-api says the
-// owner's browser got all of it. It is NOT a user-facing command and is never
-// invoked by hand.
+// mounted world, re-streams one archive from the mounted backup store, or sends
+// one file or folder of the world, PUTs it to felis-api's internal face, and
+// exits once felis-api says the owner's browser got all of it. It is NOT a
+// user-facing command and is never invoked by hand.
 //
 // Like cmdRestore it holds no database credentials and never calls config.Load:
 // felis-api made every decision (who may download what, that the server is
@@ -29,19 +36,29 @@ import (
 // plus the one-time upload token in the environment, which opens this one
 // export and nothing else.
 //
+// Whatever leaves goes through the same guards as the file editor
+// (fileedit.Guard): the proxy forwarding secret, which every server on the
+// install shares, never leaves, and server.properties leaves with its RCON
+// password redacted. A backup is stored with both, since a restore must bring
+// the world back whole, so it is filtered on the way out rather than handed
+// over as stored.
+//
 // Exit status: 0 once felis-api answers 204 (the download completed), 1 when
-// the archive could not be read or handed over, or felis-api refused it (the
-// browser never came, left early, or the backup failed its digest check), 2 on
+// the export could not be read or handed over, a backup failed its digest
+// check, or felis-api refused it (the browser never came or left early), 2 on
 // bad flags. The last stderr line reaches the export's status and the jobs list.
 func cmdExport(args []string, stdout, stderr io.Writer) int {
 	fs := flag.NewFlagSet("export", flag.ContinueOnError)
 	fs.SetOutput(stderr)
-	mode := fs.String("mode", "", "what to export: world or backup")
+	mode := fs.String("mode", "", "what to export: world, backup or files")
 	server := fs.String("server", "", "server name being exported (for logging)")
-	target := fs.String("target-url", "", "felis-api URL to PUT the archive to")
+	target := fs.String("target-url", "", "felis-api URL to PUT the export to")
 	ref := fs.String("ref", "", "backup only: absolute path to the archive on the backup mount")
 	backupRoot := fs.String("backup-root", "/backups", "backup only: mount path of the backup PVC (the ref must resolve under it)")
-	worldsRoot := fs.String("worlds-root", "/world", "world only: mount path of the world PVC to archive")
+	sum := fs.String("sha256", "", "backup only: the sha256 recorded when the archive was written; a mismatch fails the export before its end is sent")
+	worldsRoot := fs.String("worlds-root", "/world", "world and files: mount path of the world PVC")
+	path := fs.String("path", "", "files only: the file or folder to send, relative to the world root")
+	dir := fs.Bool("dir", false, "files only: the path is a folder, sent as a zip")
 	if err := fs.Parse(args); err != nil {
 		return 2
 	}
@@ -60,11 +77,17 @@ func cmdExport(args []string, stdout, stderr io.Writer) int {
 			fmt.Fprintln(stderr, "felis export: --ref is required for a backup")
 			return 2
 		}
-		err = exportBackup(ctx, *target, token, *ref, *backupRoot)
+		err = exportBackup(ctx, *target, token, *ref, *backupRoot, *sum, stdout)
 	case worldexport.ModeWorld:
 		err = exportWorld(ctx, *target, token, *worldsRoot, stdout)
+	case worldexport.ModeFiles:
+		if *path == "" {
+			fmt.Fprintln(stderr, "felis export: --path is required for files")
+			return 2
+		}
+		err = exportFiles(ctx, *target, token, *worldsRoot, *path, *dir, stdout)
 	default:
-		fmt.Fprintf(stderr, "felis export: --mode must be %s or %s\n", worldexport.ModeWorld, worldexport.ModeBackup)
+		fmt.Fprintf(stderr, "felis export: --mode must be %s, %s or %s\n", worldexport.ModeWorld, worldexport.ModeBackup, worldexport.ModeFiles)
 		return 2
 	}
 	if err != nil {
@@ -75,9 +98,20 @@ func cmdExport(args []string, stdout, stderr io.Writer) int {
 	return 0
 }
 
-// exportBackup hands over one stored archive as it is, with its length, so the
-// browser shows real progress and felis-api can check its recorded digest.
-func exportBackup(ctx context.Context, target, token, ref, root string) error {
+// archiveType is the content type of a world or backup export.
+const archiveType = "application/gzip"
+
+// errBackupDigest fails a backup export whose stored archive no longer hashes
+// to what was recorded when it was written.
+var errBackupDigest = errors.New("the backup archive does not match the sha256 recorded when it was written")
+
+// exportBackup re-streams one stored archive through the export guards
+// (backup.FilterTarGz with archiveFilter). Its length changes on the way, so it
+// goes chunked. With want set, the stored bytes are hashed as they are read,
+// and FilterTarGz reads them to their end before it closes its own archive: a
+// mismatch aborts the upload while what felis-api has passed on still lacks
+// its end, so the browser never keeps a complete-looking corrupt file.
+func exportBackup(ctx context.Context, target, token, ref, root, want string, stdout io.Writer) error {
 	// Defense in depth, as in cmdRestore: the ref comes from felis-api, but this
 	// process opens it, so it confirms the ref stays on the backup mount.
 	if !refWithinRoot(ref, root) {
@@ -88,47 +122,140 @@ func exportBackup(ctx context.Context, target, token, ref, root string) error {
 		return err
 	}
 	defer f.Close()
-	st, err := f.Stat()
-	if err != nil {
-		return err
+	var src io.Reader = f
+	if want != "" {
+		src = &digestReader{r: f, sum: sha256.New(), want: want}
 	}
-	return putExport(ctx, target, token, f, st.Size())
+	var withheld []string
+	err = streamExport(ctx, target, token, archiveType, -1, func(w io.Writer) error {
+		var err error
+		withheld, err = backup.FilterTarGz(ctx, w, src, archiveFilter)
+		return err
+	})
+	if errors.Is(err, errBackupDigest) {
+		return errBackupDigest // the jobs list shows it as it is, not wrapped as a read error
+	}
+	reportWithheld(stdout, len(withheld))
+	return err
 }
 
 // exportWorld archives the world straight into the request body: nothing is
 // staged, so a world bigger than the Pod's memory or any scratch disk exports
-// the same. A read error mid-way aborts the chunked body, and felis-api cuts
-// the browser's download off rather than end it.
+// the same.
 func exportWorld(ctx context.Context, target, token, root string, stdout io.Writer) error {
-	pr, pw := io.Pipe()
-	skippedc := make(chan []string, 1)
-	go func() {
-		skipped, err := backup.WriteTarGz(ctx, pw, root)
-		pw.CloseWithError(err)
-		skippedc <- skipped
-	}()
-	err := putExport(ctx, target, token, pr, -1)
-	pr.CloseWithError(io.ErrClosedPipe) // stops the archiver if the PUT ended first
-	if skipped := <-skippedc; len(skipped) > 0 {
+	r, err := os.OpenRoot(root)
+	if err != nil {
+		return err
+	}
+	guard := fileedit.NewGuard(r)
+	r.Close()
+	var skipped, withheld []string
+	err = streamExport(ctx, target, token, archiveType, -1, func(w io.Writer) error {
+		var err error
+		skipped, withheld, err = backup.WriteTarGz(ctx, w, root, worldFilter(guard))
+		return err
+	})
+	if len(skipped) > 0 {
 		fmt.Fprintf(stdout, "felis export: left out %d entries a tar cannot hold (symbolic links, devices, sockets)\n", len(skipped))
 	}
+	reportWithheld(stdout, len(withheld))
+	return err
+}
+
+// exportFiles sends one file or folder of the world (fileedit.OpenDownload): a
+// file with its exact length, a folder as a zip made as it streams. dir is
+// what the owner saw at path when they asked.
+func exportFiles(ctx context.Context, target, token, root, path string, dir bool, stdout io.Writer) error {
+	d, err := fileedit.OpenDownload(root, path, dir)
+	if err != nil {
+		return err
+	}
+	defer d.Close()
+	err = streamExport(ctx, target, token, d.ContentType, d.Size, func(w io.Writer) error { return d.WriteTo(ctx, w) })
+	if d.Skipped > 0 {
+		fmt.Fprintf(stdout, "felis export: left out %d entries a zip does not carry (symbolic links, devices, sockets)\n", d.Skipped)
+	}
+	reportWithheld(stdout, d.Withheld)
+	return err
+}
+
+func reportWithheld(stdout io.Writer, n int) {
+	if n > 0 {
+		fmt.Fprintf(stdout, "felis export: left out %d files that hold platform secrets\n", n)
+	}
+}
+
+// worldFilter guards a live world by file identity, so a link to a guarded
+// file under another name is caught as well.
+func worldFilter(g fileedit.Guard) backup.Filter {
+	return func(_ string, info fs.FileInfo) (bool, func([]byte) []byte) {
+		return guardAction(g.Rule(info))
+	}
+}
+
+// archiveFilter guards a stored archive, which has only names.
+func archiveFilter(name string, _ fs.FileInfo) (bool, func([]byte) []byte) {
+	return guardAction(fileedit.ArchiveRule(name))
+}
+
+func guardAction(withhold, redact bool) (bool, func([]byte) []byte) {
+	if redact {
+		return withhold, fileedit.RedactProps
+	}
+	return withhold, nil
+}
+
+// digestReader passes r through, hashing it, and turns r's EOF into
+// errBackupDigest when the bytes do not hash to want.
+type digestReader struct {
+	r    io.Reader
+	sum  hash.Hash
+	want string
+}
+
+func (d *digestReader) Read(p []byte) (int, error) {
+	n, err := d.r.Read(p)
+	d.sum.Write(p[:n])
+	if err == io.EOF && !strings.EqualFold(hex.EncodeToString(d.sum.Sum(nil)), d.want) {
+		return n, errBackupDigest
+	}
+	return n, err
+}
+
+// streamExport runs write straight into the body of the PUT. An error from
+// write aborts the chunked body, and felis-api then cuts the browser's download
+// off rather than end it; that error is the one reported, since the PUT's own
+// error only wraps it. When the PUT ends first, write is stopped.
+func streamExport(ctx context.Context, target, token, contentType string, size int64, write func(io.Writer) error) error {
+	pr, pw := io.Pipe()
+	werr := make(chan error, 1)
+	go func() {
+		err := write(pw)
+		pw.CloseWithError(err)
+		werr <- err
+	}()
+	err := putExport(ctx, target, token, contentType, pr, size)
+	pr.CloseWithError(io.ErrClosedPipe)
+	if w := <-werr; w != nil && !errors.Is(w, io.ErrClosedPipe) {
+		return w
+	}
 	return err
 }
 
-// putExport PUTs the archive to felis-api. There is no retry: the token opens
+// putExport PUTs the export to felis-api. There is no retry: the token opens
 // the export once, so a second attempt could only be refused. Redirects are
 // refused because the request carries the token and the internal face never
 // redirects. felis-api answers only after the whole download, which the Job's
 // activeDeadlineSeconds bounds, so the header timeout is a backstop for a
 // wedged endpoint and not the real limit.
-func putExport(ctx context.Context, target, token string, body io.Reader, size int64) error {
+func putExport(ctx context.Context, target, token, contentType string, body io.Reader, size int64) error {
 	req, err := http.NewRequestWithContext(ctx, http.MethodPut, target, body)
 	if err != nil {
 		return err
 	}
 	req.ContentLength = size
 	req.Header.Set("Authorization", "Bearer "+token)
-	req.Header.Set("Content-Type", "application/gzip")
+	req.Header.Set("Content-Type", contentType)
 	client := &http.Client{
 		Transport:     &http.Transport{ResponseHeaderTimeout: 10 * time.Minute},
 		CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },

cmd/felis/export_test.go

@@ -2,13 +2,21 @@ package main
 
 import (
 	"archive/tar"
+	"archive/zip"
 	"bytes"
 	"compress/gzip"
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"path/filepath"
+	"reflect"
+	"slices"
 	"strconv"
 	"strings"
 	"sync/atomic"
@@ -67,15 +75,51 @@ func tarEntries(t *testing.T, archive []byte) map[string]string {
 	}
 }
 
-func TestCmdExportWorld(t *testing.T) {
-	root := t.TempDir()
-	if err := os.MkdirAll(filepath.Join(root, "world", "region"), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	for name, body := range map[string]string{"server.properties": "motd=hi\n", "world/region/r.0.0.mca": "chunks"} {
-		if err := os.WriteFile(filepath.Join(root, name), []byte(body), 0o600); err != nil {
+// writeTree writes name → body under root, making the folders on the way.
+func writeTree(t *testing.T, root string, files map[string]string) {
+	t.Helper()
+	for name, body := range files {
+		p := filepath.Join(root, name)
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
 			t.Fatal(err)
 		}
+		if err := os.WriteFile(p, []byte(body), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+// The two secrets a world holds, and what server.properties reads as once
+// redacted.
+const (
+	secretProps   = "motd=hi\nrcon.password=hunter2\n"
+	redactedProps = "motd=hi\nrcon.password=<redacted by felis>\n"
+	forwardingKey = "secret: aVeryRealForwardingKey\n"
+)
+
+// secretWorld is a world holding both secrets, with a hard link to the
+// forwarding secret under a name nothing would guard by.
+func secretWorld(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	writeTree(t, root, map[string]string{
+		"server.properties":       secretProps,
+		"config/paper-global.yml": forwardingKey,
+		"world/region/r.0.0.mca":  "chunks",
+	})
+	if err := os.MkdirAll(filepath.Join(root, "plugins"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Link(filepath.Join(root, "config/paper-global.yml"), filepath.Join(root, "plugins/copy.yml")); err != nil {
+		t.Fatal(err)
+	}
+	return root
+}
+
+func TestCmdExportWorld(t *testing.T) {
+	root := secretWorld(t)
+	if err := os.Symlink("server.properties", filepath.Join(root, "props-link")); err != nil {
+		t.Fatal(err)
 	}
 	rcv := receiveExport(t, noContent)
 	t.Setenv(worldexport.TokenEnv, "tok")
@@ -90,61 +134,202 @@ func TestCmdExportWorld(t *testing.T) {
 		r.Header.Get("Content-Type") != "application/gzip" || r.ContentLength != -1 || strings.Join(r.TransferEncoding, ",") != "chunked" {
 		t.Fatalf("request = %s %s, headers %v, length %d, encoding %v", r.Method, r.URL.Path, r.Header, r.ContentLength, r.TransferEncoding)
 	}
-	got := tarEntries(t, rcv.body)
-	want := map[string]string{"server.properties": "motd=hi\n", "world/": "", "world/region/": "", "world/region/r.0.0.mca": "chunks"}
-	if len(got) != len(want) {
-		t.Fatalf("archive holds %v, want %v", got, want)
+	want := map[string]string{
+		"server.properties": redactedProps, "config/": "", "plugins/": "",
+		"world/": "", "world/region/": "", "world/region/r.0.0.mca": "chunks",
 	}
-	for name, body := range want {
-		if b, ok := got[name]; !ok || b != body {
-			t.Errorf("%s = %q (present %v), want %q", name, b, ok, body)
-		}
+	if got := tarEntries(t, rcv.body); !reflect.DeepEqual(got, want) {
+		t.Fatalf("archive holds %v\nwant %v", got, want)
 	}
-	if !strings.Contains(stdout.String(), "server=survival mode=world downloaded") {
-		t.Errorf("stdout = %q", stdout.String())
+	want2 := "felis export: left out 1 entries a tar cannot hold (symbolic links, devices, sockets)\n" +
+		"felis export: left out 2 files that hold platform secrets\n" +
+		"felis export: server=survival mode=world downloaded\n"
+	if stdout.String() != want2 {
+		t.Errorf("stdout = %q, want %q", stdout.String(), want2)
 	}
 }
 
-// A world that cannot be read must never reach felis-api as a complete body:
-// the chunked upload is cut off, so felis-api aborts the browser's download.
-func TestCmdExportWorldReadErrorAbortsTheUpload(t *testing.T) {
+// A world root that cannot be opened fails before anything reaches felis-api.
+func TestCmdExportWorldUnreadable(t *testing.T) {
 	rcv := receiveExport(t, noContent)
 	t.Setenv(worldexport.TokenEnv, "tok")
 	var stdout, stderr bytes.Buffer
 	code := cmdExport([]string{"--mode", "world", "--target-url", rcv.srv.URL, "--worlds-root", filepath.Join(t.TempDir(), "missing")}, &stdout, &stderr)
-	if code != 1 {
-		t.Fatalf("exit %d, want 1", code)
+	if code != 1 || rcv.hits.Load() != 0 {
+		t.Fatalf("exit %d with %d requests, want 1 and none", code, rcv.hits.Load())
+	}
+}
+
+// An export that fails part-way must never reach felis-api as a complete body:
+// the chunked upload is cut off, so felis-api aborts the browser's download,
+// and the failure itself is what the Job reports.
+func TestStreamExportWriteErrorAbortsTheUpload(t *testing.T) {
+	broken := errors.New("disk read failed")
+	rcv := receiveExport(t, noContent)
+	err := streamExport(context.Background(), rcv.srv.URL, "tok", "application/gzip", -1, func(w io.Writer) error {
+		if _, err := w.Write(bytes.Repeat([]byte("x"), 100_000)); err != nil {
+			return err
+		}
+		return broken
+	})
+	if err != broken {
+		t.Fatalf("err = %v, want the write's own error, unwrapped", err)
 	}
 	select {
 	case <-rcv.served:
 		if rcv.readErr == nil {
-			t.Fatalf("felis-api read a complete %d-byte body from an unreadable world", len(rcv.body))
+			t.Fatalf("felis-api read a complete %d-byte body from a failed export", len(rcv.body))
 		}
-	case <-time.After(2 * time.Second): // the request never reached the handler
+	case <-time.After(5 * time.Second):
+		t.Fatal("the request never reached felis-api")
 	}
 }
 
+// When felis-api refuses first, its reason is reported, not the closed pipe
+// that then stops the writer.
+func TestStreamExportRefusalStopsTheWriter(t *testing.T) {
+	refusing := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+	}))
+	defer refusing.Close()
+	stopped := make(chan error, 1)
+	err := streamExport(context.Background(), refusing.URL, "tok", "application/gzip", -1, func(w io.Writer) error {
+		for {
+			if _, err := w.Write(make([]byte, 32<<10)); err != nil {
+				stopped <- err
+				return err
+			}
+		}
+	})
+	if err == nil || err.Error() != "felis-api answered 404 Not Found" {
+		t.Fatalf("err = %v, want felis-api's answer", err)
+	}
+	if werr := <-stopped; !errors.Is(werr, io.ErrClosedPipe) {
+		t.Fatalf("the writer stopped on %v, want the closed pipe", werr)
+	}
+
+	// A PUT that never starts leaves no transport to close the body: the writer
+	// is still stopped, and the export fails rather than hangs.
+	done := make(chan error, 1)
+	go func() {
+		done <- streamExport(context.Background(), "http://[::1", "tok", "application/gzip", -1, func(w io.Writer) error {
+			_, err := w.Write([]byte("x"))
+			return err
+		})
+	}()
+	select {
+	case err := <-done:
+		if err == nil || !strings.Contains(err.Error(), "missing ']'") {
+			t.Fatalf("err = %v, want the bad URL", err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("an export whose PUT never started hung")
+	}
+}
+
+// storedBackup writes, at path, a gzip+tar like one the backup store holds:
+// the world whole, both secrets included, and a region file that does not
+// compress. It returns the archive's sha256.
+func storedBackup(t *testing.T, path string) string {
+	t.Helper()
+	region := make([]byte, 64<<10)
+	if _, err := rand.Read(region); err != nil {
+		t.Fatal(err)
+	}
+	var buf bytes.Buffer
+	zw := gzip.NewWriter(&buf)
+	tw := tar.NewWriter(zw)
+	for _, e := range []struct{ name, body string }{
+		{"server.properties", secretProps},
+		{"config/paper-global.yml", forwardingKey},
+		{"world/level.dat", "level"},
+		{"world/region/r.0.0.mca", string(region)},
+	} {
+		if err := tw.WriteHeader(&tar.Header{Name: e.name, Typeflag: tar.TypeReg, Mode: 0o600, Size: int64(len(e.body))}); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := io.WriteString(tw, e.body); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := tw.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := zw.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, buf.Bytes(), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	sum := sha256.Sum256(buf.Bytes())
+	return hex.EncodeToString(sum[:])
+}
+
 func TestCmdExportBackup(t *testing.T) {
 	root := t.TempDir()
-	archive := bytes.Repeat([]byte("felis"), 10_000)
 	ref := filepath.Join(root, "survival-1.tar.gz")
-	if err := os.WriteFile(ref, archive, 0o600); err != nil {
+	sum := storedBackup(t, ref)
+	stored, err := os.ReadFile(ref)
+	if err != nil {
 		t.Fatal(err)
 	}
+	region := tarEntries(t, stored)["world/region/r.0.0.mca"]
 	args := func(url, ref string) []string {
 		return []string{"--mode", "backup", "--server", "survival", "--target-url", url, "--ref", ref, "--backup-root", root}
 	}
 
-	t.Run("hands the archive over with its length", func(t *testing.T) {
+	for name, extra := range map[string][]string{
+		"no digest recorded":      nil,
+		"recorded digest matches": {"--sha256", sum},
+	} {
+		t.Run(name+": re-streamed through the guards", func(t *testing.T) {
+			rcv := receiveExport(t, noContent)
+			t.Setenv(worldexport.TokenEnv, "tok")
+			var stdout, stderr bytes.Buffer
+			if code := cmdExport(append(args(rcv.srv.URL, ref), extra...), &stdout, &stderr); code != 0 {
+				t.Fatalf("exit %d, stderr %q", code, stderr.String())
+			}
+			r := rcv.req
+			if r.ContentLength != -1 || r.Header.Get("Content-Type") != "application/gzip" || r.Header.Get("Authorization") != "Bearer tok" {
+				t.Fatalf("length %d, headers %v", r.ContentLength, r.Header)
+			}
+			want := map[string]string{"server.properties": redactedProps, "world/level.dat": "level", "world/region/r.0.0.mca": region}
+			if got := tarEntries(t, rcv.body); !reflect.DeepEqual(got, want) {
+				t.Fatalf("archive holds %d entries, want exactly the redacted properties, level.dat and the region file", len(got))
+			}
+			if want := "felis export: left out 1 files that hold platform secrets\nfelis export: server=survival mode=backup downloaded\n"; stdout.String() != want {
+				t.Errorf("stdout = %q, want %q", stdout.String(), want)
+			}
+		})
+	}
+
+	// The stored bytes are checked as they stream, and the archive the Job sends
+	// is only closed once they are all read: a mismatch cuts the upload off
+	// short of its end, so felis-api never passes on a complete-looking copy.
+	t.Run("a digest mismatch cuts the upload off before its end", func(t *testing.T) {
 		rcv := receiveExport(t, noContent)
 		t.Setenv(worldexport.TokenEnv, "tok")
 		var stdout, stderr bytes.Buffer
-		if code := cmdExport(args(rcv.srv.URL, ref), &stdout, &stderr); code != 0 {
-			t.Fatalf("exit %d, stderr %q", code, stderr.String())
+		if code := cmdExport(append(args(rcv.srv.URL, ref), "--sha256", strings.Repeat("ab", 32)), &stdout, &stderr); code != 1 {
+			t.Fatalf("exit %d, want 1", code)
 		}
-		if rcv.req.ContentLength != int64(len(archive)) || !bytes.Equal(rcv.body, archive) || rcv.req.Header.Get("Authorization") != "Bearer tok" {
-			t.Fatalf("got %d bytes (length %d, auth %q), want the %d archive bytes",
-				len(rcv.body), rcv.req.ContentLength, rcv.req.Header.Get("Authorization"), len(archive))
+		if want := "felis export: the backup archive does not match the sha256 recorded when it was written\n"; stderr.String() != want {
+			t.Fatalf("stderr = %q, want %q", stderr.String(), want)
+		}
+		select {
+		case <-rcv.served:
+		case <-time.After(5 * time.Second):
+			t.Fatal("the upload never reached felis-api")
+		}
+		if rcv.readErr == nil {
+			t.Fatalf("felis-api read a complete %d-byte body", len(rcv.body))
+		}
+		zr, err := gzip.NewReader(bytes.NewReader(rcv.body))
+		if err == nil {
+			_, err = io.ReadAll(zr)
+		}
+		if err == nil {
+			t.Fatal("what felis-api got is a complete archive")
 		}
 	})
 
@@ -204,6 +389,86 @@ func TestCmdExportBackup(t *testing.T) {
 	}
 }
 
+func TestCmdExportFiles(t *testing.T) {
+	root := secretWorld(t)
+	writeTree(t, root, map[string]string{"plugins/Essentials/config.yml": "x: 1"})
+	if err := os.Symlink("config.yml", filepath.Join(root, "plugins/Essentials/link.yml")); err != nil {
+		t.Fatal(err)
+	}
+	export := func(t *testing.T, path string, dir bool) (*exportReceiver, int, string, string) {
+		t.Helper()
+		rcv := receiveExport(t, noContent)
+		t.Setenv(worldexport.TokenEnv, "tok")
+		args := []string{"--mode", "files", "--server", "survival", "--target-url", rcv.srv.URL, "--worlds-root", root, "--path", path}
+		if dir {
+			args = append(args, "--dir")
+		}
+		var stdout, stderr bytes.Buffer
+		code := cmdExport(args, &stdout, &stderr)
+		return rcv, code, stdout.String(), stderr.String()
+	}
+
+	for path, want := range map[string]string{
+		"world/region/r.0.0.mca": "chunks",
+		"server.properties":      redactedProps,
+	} {
+		t.Run("a file goes with its exact length: "+path, func(t *testing.T) {
+			rcv, code, stdout, stderr := export(t, path, false)
+			if code != 0 || stdout != "felis export: server=survival mode=files downloaded\n" {
+				t.Fatalf("exit %d, stdout %q, stderr %q", code, stdout, stderr)
+			}
+			if string(rcv.body) != want || rcv.req.ContentLength != int64(len(want)) || rcv.req.Header.Get("Content-Type") != "application/octet-stream" {
+				t.Fatalf("body %q, length %d, type %q; want %q", rcv.body, rcv.req.ContentLength, rcv.req.Header.Get("Content-Type"), want)
+			}
+		})
+	}
+
+	t.Run("a folder goes as a zip, guarded", func(t *testing.T) {
+		rcv, code, stdout, stderr := export(t, "plugins", true)
+		if code != 0 {
+			t.Fatalf("exit %d, stderr %q", code, stderr)
+		}
+		if rcv.req.ContentLength != -1 || rcv.req.Header.Get("Content-Type") != "application/zip" {
+			t.Fatalf("length %d, type %q", rcv.req.ContentLength, rcv.req.Header.Get("Content-Type"))
+		}
+		zr, err := zip.NewReader(bytes.NewReader(rcv.body), int64(len(rcv.body)))
+		if err != nil {
+			t.Fatal(err)
+		}
+		var names []string
+		for _, f := range zr.File {
+			names = append(names, f.Name)
+		}
+		if want := []string{"plugins/", "plugins/Essentials/", "plugins/Essentials/config.yml"}; !slices.Equal(names, want) {
+			t.Fatalf("zip holds %v, want %v", names, want)
+		}
+		want := "felis export: left out 1 entries a zip does not carry (symbolic links, devices, sockets)\n" +
+			"felis export: left out 1 files that hold platform secrets\n" +
+			"felis export: server=survival mode=files downloaded\n"
+		if stdout != want {
+			t.Errorf("stdout = %q, want %q", stdout, want)
+		}
+	})
+
+	for _, c := range []struct {
+		path string
+		dir  bool
+		want string
+	}{
+		{"config/paper-global.yml", false, "forwarding secret"},
+		{"plugins/copy.yml", false, "forwarding secret"},
+		{"plugins", false, "is a folder now"},
+		{"server.properties", true, "is not a folder now"},
+	} {
+		t.Run("refused before any request: "+c.path, func(t *testing.T) {
+			rcv, code, _, stderr := export(t, c.path, c.dir)
+			if code != 1 || rcv.hits.Load() != 0 || !strings.Contains(stderr, c.want) {
+				t.Fatalf("exit %d, %d requests, stderr %q; want 1, none, and %q", code, rcv.hits.Load(), stderr, c.want)
+			}
+		})
+	}
+}
+
 func TestCmdExportUsage(t *testing.T) {
 	for name, tc := range map[string]struct {
 		token string
@@ -213,6 +478,7 @@ func TestCmdExportUsage(t *testing.T) {
 		"no target":          {"tok", []string{"--mode", "world"}},
 		"unknown mode":       {"tok", []string{"--mode", "both", "--target-url", "http://api/x"}},
 		"backup without ref": {"tok", []string{"--mode", "backup", "--target-url", "http://api/x"}},
+		"files without path": {"tok", []string{"--mode", "files", "--target-url", "http://api/x"}},
 	} {
 		t.Run(name, func(t *testing.T) {
 			t.Setenv(worldexport.TokenEnv, tc.token)

cmd/felis/files.go

@@ -39,7 +39,7 @@ import (
 func cmdFiles(args []string, stdout, stderr io.Writer) int {
 	fs := flag.NewFlagSet("files", flag.ContinueOnError)
 	fs.SetOutput(stderr)
-	op := fs.String("op", "", "operation: list, read, write, mkdir, delete, rename or upload")
+	op := fs.String("op", "", "operation: list, read, write, mkdir, delete, rename, upload or unzip")
 	path := fs.String("path", "", "path to operate on, relative to the world root (empty = the root itself)")
 	worldsRoot := fs.String("worlds-root", "/data", "mount path of the world PVC; every path resolves under it")
 	expect := fs.String("expect-sha256", "", "write only: refuse unless the file's current SHA-256 (hex) is this")
@@ -48,7 +48,7 @@ func cmdFiles(args []string, stdout, stderr io.Writer) int {
 	sourceURL := fs.String("source-url", "", "upload only: felis-api URL to fetch the bytes from")
 	size := fs.Int64("size", -1, "upload only: the byte count the fetched file must have")
 	sum := fs.String("sha256", "", "upload only: the SHA-256 (hex) the fetched file must have")
-	overwrite := fs.Bool("overwrite", false, "upload only: replace a file already at the path")
+	overwrite := fs.Bool("overwrite", false, "upload and unzip: replace files already there")
 	if err := fs.Parse(args); err != nil {
 		return 2
 	}
@@ -88,6 +88,10 @@ func cmdFiles(args []string, stdout, stderr io.Writer) int {
 			Open: func() (io.ReadCloser, error) { return fetchUpload(ctx, *sourceURL, token) },
 		}
 	}
+	// An upload or an unzip (the only ops that report progress) can run long
+	// enough that felis-api does not wait on its Job, and the panel shows how far
+	// it has got from the latest of these lines (fileedit.K8sRunner.Ops).
+	req.Progress = fileedit.ThrottledProgress(stdout, time.Second, time.Now)
 
 	res, err := fileedit.Execute(*worldsRoot, req)
 	if err != nil {
@@ -107,8 +111,9 @@ func cmdFiles(args []string, stdout, stderr io.Writer) int {
 
 // fetchUpload opens the staged upload on felis-api's internal face. There is no
 // retry: the token opens the upload once (fileedit.Stage), so a second attempt
-// could only be refused, and felis-api answers the failed Job with a 500 the
-// caller can retry whole. Redirects are refused because the request carries the
+// could only be refused, and the caller retries the failed Job whole (a file
+// sent in parts stays staged until it has been served whole once, so that retry
+// does not send it again). Redirects are refused because the request carries the
 // token and the internal face never redirects; the header timeout catches a
 // wedged endpoint, and the Job's activeDeadlineSeconds bounds the body.
 func fetchUpload(ctx context.Context, url, token string) (io.ReadCloser, error) {

cmd/felis/files_test.go

@@ -1,11 +1,13 @@
 package main
 
 import (
+	"archive/zip"
 	"bytes"
 	"crypto/sha256"
 	"encoding/base64"
 	"encoding/hex"
 	"encoding/json"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"os"
@@ -17,10 +19,12 @@ import (
 	"felis.lolicon.best/internal/fileedit"
 )
 
-// filesResult is the Result a `felis files` run printed on its marked line.
+// filesResult is the Result a `felis files` run printed on its marked line,
+// the last it prints.
 func filesResult(t *testing.T, stdout string) fileedit.Result {
 	t.Helper()
-	line, ok := strings.CutPrefix(strings.TrimSpace(stdout), fileedit.ResultPrefix)
+	lines := strings.Split(strings.TrimSpace(stdout), "\n")
+	line, ok := strings.CutPrefix(lines[len(lines)-1], fileedit.ResultPrefix)
 	if !ok {
 		t.Fatalf("stdout has no result line: %q", stdout)
 	}
@@ -75,6 +79,9 @@ func TestCmdFilesUpload(t *testing.T) {
 		if code := cmdFiles(uploadArgs(root, srv.URL+"/u", body), &stdout, &stderr); code != 0 {
 			t.Fatalf("exit %d, stderr %q", code, stderr.String())
 		}
+		if !strings.HasPrefix(stdout.String(), fileedit.ProgressPrefix+`{"done":4,"total":4}`+"\n") {
+			t.Fatalf("stdout %q does not start with the progress to the last byte", stdout.String())
+		}
 		if res := filesResult(t, stdout.String()); res.Code != "" {
 			t.Fatalf("result = %+v", res)
 		}
@@ -201,3 +208,43 @@ func TestCmdFilesCallerFaultIsAResult(t *testing.T) {
 		t.Fatalf("no --op: exit %d, want 2", code)
 	}
 }
+
+// TestCmdFilesUnzip checks an unzip extracts next to the archive and reports its
+// progress before its result, the same way an upload does.
+func TestCmdFilesUnzip(t *testing.T) {
+	root := t.TempDir()
+	if err := os.Mkdir(filepath.Join(root, "maps"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	var zb bytes.Buffer
+	zw := zip.NewWriter(&zb)
+	for name, body := range map[string]string{"world/level.dat": "level", "world/region/r.0.0.mca": "region!"} {
+		w, err := zw.Create(name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		io.WriteString(w, body)
+	}
+	if err := zw.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "maps", "a.zip"), zb.Bytes(), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	if code := cmdFiles([]string{"--op", "unzip", "--path", "maps/a.zip", "--worlds-root", root}, &stdout, &stderr); code != 0 {
+		t.Fatalf("exit %d, stderr %q", code, stderr.String())
+	}
+	if res := filesResult(t, stdout.String()); res.Code != "" || res.Files != 2 || res.Bytes != 12 {
+		t.Fatalf("result = %+v", res)
+	}
+	if !strings.HasPrefix(stdout.String(), fileedit.ProgressPrefix) ||
+		!strings.Contains(stdout.String(), fileedit.ProgressPrefix+`{"done":12,"total":12}`+"\n") {
+		t.Fatalf("stdout %q does not report the progress to the last byte", stdout.String())
+	}
+	got, err := os.ReadFile(filepath.Join(root, "maps", "world", "region", "r.0.0.mca"))
+	if err != nil || string(got) != "region!" {
+		t.Fatalf("extracted %q, %v", got, err)
+	}
+}

cmd/felis/run.go

@@ -21,7 +21,7 @@ Commands:
   restore           Extract a world archive into a world volume (internal Job entrypoint)
   backup            Archive a world into the backup store and record it (internal Job entrypoint)
   backup-now        Archive every user server's world now, one at a time (or the named ones; -stop stops running ones first; prints the plan, -yes applies; requires root/sudo)
-  files             List, read, write, mkdir, delete, rename or upload one path in a stopped server's world (internal Job entrypoint)
+  files             List, read, write, mkdir, delete, rename, upload or unzip one path in a stopped server's world (internal Job entrypoint)
   export            Archive a stopped server's world, or read one of its backups, and hand it to felis-api for download (internal Job entrypoint)
   egress-gate       Hold a build or game server pod until its egress NetworkPolicy is enforced (internal init container entrypoint)
   fetch-context     Fetch and extract a submission's build context (internal Job entrypoint)