fix: make multipart discovery and cancellation explicit and bounded

Signed-off-by: Feng Ruohang <rh@vonng.com>

internal/config/api/api.go

@@ -45,6 +45,7 @@ const (
 	apiTransitionWorkers           = "transition_workers"
 	apiStaleUploadsCleanupInterval = "stale_uploads_cleanup_interval"
 	apiStaleUploadsExpiry          = "stale_uploads_expiry"
+	apiMultipartListing            = "multipart_listing"
 	apiDeleteCleanupInterval       = "delete_cleanup_interval"
 	apiDisableODirect              = "disable_odirect"
 	apiODirect                     = "odirect"
@@ -67,6 +68,7 @@ const (
 
 	EnvAPIStaleUploadsCleanupInterval = "MINIO_API_STALE_UPLOADS_CLEANUP_INTERVAL"
 	EnvAPIStaleUploadsExpiry          = "MINIO_API_STALE_UPLOADS_EXPIRY"
+	EnvAPIMultipartListing            = "MINIO_API_MULTIPART_LISTING"
 	EnvAPIDeleteCleanupInterval       = "MINIO_API_DELETE_CLEANUP_INTERVAL"
 	EnvDeleteCleanupInterval          = "MINIO_DELETE_CLEANUP_INTERVAL"
 	EnvAPIODirect                     = "MINIO_API_ODIRECT"
@@ -133,6 +135,7 @@ var (
 			Key:   apiStaleUploadsExpiry,
 			Value: "24h",
 		},
+		config.KV{Key: apiMultipartListing, Value: "strict"},
 		config.KV{
 			Key:   apiDeleteCleanupInterval,
 			Value: "5m",
@@ -178,6 +181,7 @@ type Config struct {
 	TransitionWorkers           int           `json:"transition_workers"`
 	StaleUploadsCleanupInterval time.Duration `json:"stale_uploads_cleanup_interval"`
 	StaleUploadsExpiry          time.Duration `json:"stale_uploads_expiry"`
+	MultipartListing            string        `json:"multipart_listing"`
 	DeleteCleanupInterval       time.Duration `json:"delete_cleanup_interval"`
 	EnableODirect               bool          `json:"enable_odirect"`
 	GzipObjects                 bool          `json:"gzip_objects"`
@@ -320,6 +324,10 @@ func LookupConfig(kvs config.KVS) (cfg Config, err error) {
 		return cfg, err
 	}
 	cfg.StaleUploadsExpiry = staleUploadsExpiry
+	cfg.MultipartListing = env.Get(EnvAPIMultipartListing, kvs.GetWithDefault(apiMultipartListing, DefaultKVS))
+	if cfg.MultipartListing != "strict" && cfg.MultipartListing != "legacy" {
+		return cfg, fmt.Errorf("%s must be strict or legacy", apiMultipartListing)
+	}
 
 	cfg.SyncEvents = env.Get(EnvAPISyncEvents, kvs.Get(apiSyncEvents)) == config.EnableOn
 

internal/config/api/api_test.go

@@ -0,0 +1,41 @@
+// Copyright (c) 2026 Ruohang Feng
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+package api
+
+import (
+	"testing"
+
+	"github.com/minio/minio/internal/config"
+)
+
+func TestMultipartListingMigrationMode(t *testing.T) {
+	for _, tc := range []struct {
+		name, stored, override, want string
+		invalid                      bool
+	}{
+		{name: "default", want: "strict"},
+		{name: "explicit-migration", stored: "legacy", want: "legacy"},
+		{name: "environment-override", stored: "strict", override: "legacy", want: "legacy"},
+		{name: "invalid-stored", stored: "automatic", invalid: true},
+		{name: "invalid-environment", stored: "strict", override: "automatic", invalid: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv(EnvAPIMultipartListing, tc.override)
+			var kvs config.KVS
+			if tc.stored != "" {
+				kvs = config.KVS{{Key: apiMultipartListing, Value: tc.stored}}
+			}
+			cfg, err := LookupConfig(kvs)
+			if tc.invalid {
+				if err == nil {
+					t.Fatal("invalid migration mode silently accepted")
+				}
+				return
+			}
+			if err != nil || cfg.MultipartListing != tc.want {
+				t.Fatalf("mode=%q err=%v, want %q", cfg.MultipartListing, err, tc.want)
+			}
+		})
+	}
+}

internal/config/api/help.go

@@ -26,6 +26,12 @@ var (
 
 	// Help holds configuration keys and their default values for api subsystem.
 	Help = config.HelpKVS{
+		config.HelpKV{
+			Key:         apiMultipartListing,
+			Description: "multipart listing mode: strict, or temporary legacy mode during coordinated upgrade" + defaultHelpPostfix(apiMultipartListing),
+			Type:        "string",
+			Optional:    true,
+		},
 		config.HelpKV{
 			Key:         apiRequestsMax,
 			Description: `set the maximum number of concurrent requests (default: auto)`,