diff --git a/apps/backend/internal/backendapp/main.go b/apps/backend/internal/backendapp/main.go index 57a2b98e43..0ae508e9fd 100644 --- a/apps/backend/internal/backendapp/main.go +++ b/apps/backend/internal/backendapp/main.go @@ -1142,7 +1142,7 @@ func startGatewayAndServe( TaskSessions: repos.Task, }) storageComposition, err := provideStorageComposition( - cfg, dbPool, systemSvc.Jobs, lifecycleMgr, services.WorktreeMgr, services.Task, + cfg, dbPool, systemSvc.Jobs, eventBus, lifecycleMgr, services.WorktreeMgr, services.Task, log, func(message string, err error) { log.Error(message, zap.Error(err)) }, ) diff --git a/apps/backend/internal/backendapp/storage_analysis_cancellation_test.go b/apps/backend/internal/backendapp/storage_analysis_cancellation_test.go new file mode 100644 index 0000000000..c6f5be8af0 --- /dev/null +++ b/apps/backend/internal/backendapp/storage_analysis_cancellation_test.go @@ -0,0 +1,68 @@ +package backendapp + +import ( + "context" + "errors" + "testing" + + storagepkg "github.com/kandev/kandev/internal/system/storage" + "github.com/kandev/kandev/internal/system/storage/dockerstore" + "github.com/kandev/kandev/internal/system/storage/gocache" + "github.com/kandev/kandev/internal/system/storage/workspaces" +) + +func TestOverviewCacheDoesNotCommitCancelledStorageOverview(t *testing.T) { + settings, _ := newStorageMaintenanceStores(t) + workspaceStarted := make(chan struct{}) + overview := &storageOverview{ + settings: settings, + quarantine: failingQuarantineSummarizer{err: errors.New("quarantine unavailable")}, + workspaceAnalyze: func(ctx context.Context, _ storagepkg.StorageMaintenanceSettings) (workspaces.Analysis, error) { + close(workspaceStarted) + <-ctx.Done() + return workspaces.Analysis{}, ctx.Err() + }, + goCacheAnalyze: func(context.Context) (gocache.Analysis, error) { + return gocache.Analysis{}, nil + }, + docker: dockerstore.NewProvider(&overviewDockerClient{}, overviewContainerInventory{}, settings), + } + updates := make(chan storagepkg.StorageAnalysisUpdated, 16) + cache := storagepkg.NewOverviewCacheWithOptions(overview, storagepkg.OverviewCacheOptions{ + Publisher: func(update storagepkg.StorageAnalysisUpdated) { updates <- update }, + }) + ctx, cancel := context.WithCancel(context.Background()) + defer cancel() + resultCh := make(chan error, 1) + go func() { + _, err := cache.Refresh(ctx) + resultCh <- err + }() + + <-workspaceStarted + cancel() + if err := <-resultCh; !errors.Is(err, context.Canceled) { + t.Fatalf("Refresh error = %v, want context cancellation", err) + } + + read, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("Read after cancellation: %v", err) + } + if read.Snapshot != nil { + t.Fatalf("cancelled snapshot = %#v, want no committed snapshot", read.Snapshot) + } + if read.Analysis.State != storagepkg.AnalysisStateFailed { + t.Fatalf("cancelled analysis state = %q, want failed", read.Analysis.State) + } + for { + select { + case update := <-updates: + if update.State == storagepkg.AnalysisStateReady { + t.Fatal("cancelled overview reported ready") + } + default: + return + } + } +} diff --git a/apps/backend/internal/backendapp/storage_maintenance.go b/apps/backend/internal/backendapp/storage_maintenance.go index f8dc3c53f4..90f32a2601 100644 --- a/apps/backend/internal/backendapp/storage_maintenance.go +++ b/apps/backend/internal/backendapp/storage_maintenance.go @@ -3,7 +3,6 @@ package backendapp import ( "context" "encoding/json" - "errors" "fmt" "os" "path/filepath" @@ -15,16 +14,20 @@ import ( "github.com/kandev/kandev/internal/common/config" "github.com/kandev/kandev/internal/common/logger" "github.com/kandev/kandev/internal/db" + "github.com/kandev/kandev/internal/events" + "github.com/kandev/kandev/internal/events/bus" "github.com/kandev/kandev/internal/system/jobs" systemmetrics "github.com/kandev/kandev/internal/system/metrics" systemsettings "github.com/kandev/kandev/internal/system/settings" storagepkg "github.com/kandev/kandev/internal/system/storage" "github.com/kandev/kandev/internal/system/storage/dockerstore" + "github.com/kandev/kandev/internal/system/storage/filescan" "github.com/kandev/kandev/internal/system/storage/gocache" "github.com/kandev/kandev/internal/system/storage/tempartifacts" "github.com/kandev/kandev/internal/system/storage/workspaces" taskservice "github.com/kandev/kandev/internal/task/service" "github.com/kandev/kandev/internal/worktree" + "go.uber.org/zap" ) const workspaceDependenciesProviderName = "workspace_dependencies" @@ -40,6 +43,7 @@ func provideStorageComposition( cfg *config.Config, pool *db.Pool, tracker *jobs.Tracker, + eventBus bus.EventBus, lifecycleMgr *lifecycle.Manager, worktreeMgr *worktree.Manager, taskSvc *taskservice.Service, @@ -61,9 +65,11 @@ func provideStorageComposition( if err := tempArtifacts.Reconcile(context.Background()); err != nil { logError("reconcile temporary artifact registry", err) } + scanner := filescan.NewLimiter(4) tempProvider := tempartifacts.NewProvider(tempartifacts.ProviderConfig{ Registry: tempArtifacts, Store: store, HomeDir: cfg.ResolvedHomeDir(), TrashDir: filepath.Join(cfg.ResolvedHomeDir(), "trash"), + Scanner: scanner, }) if err := tempProvider.Reconcile(context.Background()); err != nil { logError("reconcile temporary artifact quarantine", err) @@ -72,7 +78,7 @@ func provideStorageComposition( taskSvc.SetTaskResourceCleanupActivityGate(&taskCleanupActivityGate{coordinator: coordinator}) goCache := gocache.New(gocache.Config{ HomeDir: cfg.ResolvedHomeDir(), TrashDir: filepath.Join(cfg.ResolvedHomeDir(), "trash"), - Settings: settings, Store: store, + Settings: settings, Store: store, Scanner: scanner, }) lifecycleMgr.SetActivityCoordinator(coordinator) lifecycleMgr.SetManagedGoCacheEnvironmentProvider(goCache) @@ -81,7 +87,7 @@ func provideStorageComposition( } inventory := &storageInventory{reader: pool.Reader(), worktrees: worktreeMgr, lifecycle: lifecycleMgr} - workspaceFactory := newWorkspaceFactory(cfg, store, inventory, worktreeMgr) + workspaceFactory := newWorkspaceFactory(cfg, store, inventory, worktreeMgr, scanner) dockerClient := &lazyStorageDocker{provider: lifecycleMgr.DockerClientProvider(), activity: coordinator} dockerProvider := dockerstore.NewProvider( dockerClient, &containerInventory{reader: pool.Reader()}, settings, @@ -91,7 +97,22 @@ func provideStorageComposition( docker: dockerProvider, dockerClient: dockerClient, dockerHost: cfg.Docker.Host, homeDir: cfg.ResolvedHomeDir(), tempArtifacts: tempProvider, } - cachedOverview := storagepkg.NewOverviewCache(overview) + cachedOverview := storagepkg.NewOverviewCacheWithOptions(overview, storagepkg.OverviewCacheOptions{ + Publisher: func(update storagepkg.StorageAnalysisUpdated) { + if eventBus == nil { + return + } + if err := eventBus.Publish( + context.Background(), events.SystemStorageAnalysisUpdated, + bus.NewEvent(events.SystemStorageAnalysisUpdated, "storage-analysis", update), + ); err != nil { + logError("publish storage analysis update", err) + } + }, + Observer: func(completion storagepkg.StorageAnalysisCompletion) { + logStorageAnalysisCompletion(log, completion) + }, + }) quarantine := &workspaceQuarantineController{ settings: settings, store: store, factory: workspaceFactory, homeDir: cfg.ResolvedHomeDir(), activity: coordinator, temporary: tempProvider, @@ -172,6 +193,7 @@ func newWorkspaceFactory( store *storagepkg.Store, inventory workspaces.InventorySource, pruner workspaces.WorktreePruner, + scanner *filescan.Limiter, ) workspaceFactory { return func(current storagepkg.StorageMaintenanceSettings) *workspaces.Provider { return workspaces.New(workspaces.Config{ @@ -180,6 +202,7 @@ func newWorkspaceFactory( Inventory: inventory, Store: store, Pruner: pruner, GracePeriod: time.Duration(current.OrphanGraceHours) * time.Hour, Retention: time.Duration(current.QuarantineRetentionHours) * time.Hour, + Scanner: scanner, }) } } @@ -203,10 +226,25 @@ type storageOverview struct { } func (o *storageOverview) Summary(ctx context.Context) (storagepkg.Summary, error) { + return o.summary(ctx, nil) +} + +func (o *storageOverview) SummaryWithProgress( + ctx context.Context, + notify storagepkg.OverviewProgressCallback, +) (storagepkg.Summary, error) { + return o.summary(ctx, notify) +} + +func (o *storageOverview) summary( + ctx context.Context, + notify storagepkg.OverviewProgressCallback, +) (storagepkg.Summary, error) { settings, err := o.settings.GetSettings(ctx) if err != nil { return storagepkg.Summary{}, err } + reporter := newStorageProgressReporter(notify) var ( workspaceSummary workspaces.Analysis workspaceErr error @@ -232,41 +270,269 @@ func (o *storageOverview) Summary(ctx context.Context) (storagepkg.Summary, erro } go func() { defer measurements.Done() - workspaceSummary, workspaceErr = workspaceAnalyze(ctx, settings) + reporter.start(storagepkg.StorageSourceWorkspaces) + workspaceSummary, workspaceErr = o.analyzeWorkspaces(ctx, settings, workspaceAnalyze, reporter) + reporter.complete(storagepkg.StorageSourceWorkspaces, summaryValue(workspaceSummary, workspaceErr), workspaceErr) }() go func() { defer measurements.Done() - goCacheSummary, goCacheErr = goCacheAnalyze(ctx) + reporter.start(storagepkg.StorageSourceGoCache) + goCacheSummary, goCacheErr = o.analyzeGoCache(ctx, goCacheAnalyze, reporter) + reporter.complete(storagepkg.StorageSourceGoCache, summaryValue(goCacheSummary, goCacheErr), goCacheErr) }() go func() { defer measurements.Done() + reporter.start(storagepkg.StorageSourceQuarantine) quarantineSummary, quarantineErr = o.quarantine.SummarizeQuarantine(ctx) + reporter.complete(storagepkg.StorageSourceQuarantine, summaryValue(quarantineSummary, quarantineErr), quarantineErr) }() go func() { defer measurements.Done() + reporter.start(storagepkg.StorageSourceDocker) dockerSummary = o.docker.Analyze(ctx) + reporter.complete(storagepkg.StorageSourceDocker, dockerSummaryMap(dockerSummary), nil) }() if o.tempArtifacts != nil { measurements.Add(1) go func() { defer measurements.Done() - tempSummary, tempErr = o.tempArtifacts.Analyze(ctx) + reporter.start(storagepkg.StorageSourceTemporaryArtifacts) + tempSummary, tempErr = o.analyzeTemporaryArtifacts(ctx, reporter) + reporter.complete( + storagepkg.StorageSourceTemporaryArtifacts, + summaryValue(tempSummary, tempErr), tempErr, + ) }() + } else { + reporter.start(storagepkg.StorageSourceTemporaryArtifacts) + reporter.complete(storagepkg.StorageSourceTemporaryArtifacts, tempSummary, nil) } measurements.Wait() + if err := ctx.Err(); err != nil { + return storagepkg.Summary{}, err + } + return summaryFromMeasurements( + workspaceSummary, workspaceErr, goCacheSummary, goCacheErr, + quarantineSummary, quarantineErr, tempSummary, tempErr, dockerSummary, + ), nil +} + +func summaryFromMeasurements( + workspaceSummary workspaces.Analysis, + workspaceErr error, + goCacheSummary gocache.Analysis, + goCacheErr error, + quarantineSummary storagepkg.QuarantineSummary, + quarantineErr error, + tempSummary tempartifacts.Analysis, + tempErr error, + dockerSummary dockerstore.Analysis, +) storagepkg.Summary { return storagepkg.Summary{ Workspaces: summaryValue(workspaceSummary, workspaceErr), GoCache: summaryValue(goCacheSummary, goCacheErr), Quarantine: summaryValue(quarantineSummary, quarantineErr), TemporaryArtifacts: summaryValue(tempSummary, tempErr), - Docker: map[string]any{ - "available": dockerSummary.Available, "build_cache_bytes": dockerSummary.BuildCacheBytes, - "image_layer_bytes": dockerSummary.ImageLayerBytes, - "unused_image_bytes": dockerSummary.UnusedImageBytes, "warnings": dockerSummary.Warnings, - "managed_container_count": dockerSummary.ManagedContainerCount, - "managed_container_bytes": dockerSummary.ManagedContainerBytes, - }, - }, nil + Docker: dockerSummaryMap(dockerSummary), + } +} + +type workspaceProgressAnalyzer interface { + AnalyzeWithProgress(context.Context, func(filescan.Progress)) (workspaces.Analysis, error) +} + +type goCacheProgressAnalyzer interface { + AnalyzeWithProgress(context.Context, func(filescan.Progress)) (gocache.Analysis, error) +} + +type temporaryArtifactsProgressAnalyzer interface { + AnalyzeWithProgress(context.Context, func(filescan.Progress)) (tempartifacts.Analysis, error) +} + +var ( + _ workspaceProgressAnalyzer = (*workspaces.Provider)(nil) + _ goCacheProgressAnalyzer = (*gocache.Provider)(nil) + _ temporaryArtifactsProgressAnalyzer = (*tempartifacts.Provider)(nil) +) + +func (o *storageOverview) analyzeWorkspaces( + ctx context.Context, + settings storagepkg.StorageMaintenanceSettings, + fallback func(context.Context, storagepkg.StorageMaintenanceSettings) (workspaces.Analysis, error), + reporter *storageProgressReporter, +) (workspaces.Analysis, error) { + if o.workspaceAnalyze != nil { + return fallback(ctx, settings) + } + provider := o.workspaceFactory(settings) + return provider.AnalyzeWithProgress(ctx, reporter.filesystem(storagepkg.StorageSourceWorkspaces)) +} + +func (o *storageOverview) analyzeGoCache( + ctx context.Context, + fallback func(context.Context) (gocache.Analysis, error), + reporter *storageProgressReporter, +) (gocache.Analysis, error) { + if o.goCacheAnalyze != nil { + return fallback(ctx) + } + return o.goCache.AnalyzeWithProgress(ctx, reporter.filesystem(storagepkg.StorageSourceGoCache)) +} + +func (o *storageOverview) analyzeTemporaryArtifacts( + ctx context.Context, + reporter *storageProgressReporter, +) (tempartifacts.Analysis, error) { + return o.tempArtifacts.AnalyzeWithProgress( + ctx, reporter.filesystem(storagepkg.StorageSourceTemporaryArtifacts), + ) +} + +func dockerSummaryMap(summary dockerstore.Analysis) map[string]any { + return map[string]any{ + "available": summary.Available, "build_cache_bytes": summary.BuildCacheBytes, + "image_layer_bytes": summary.ImageLayerBytes, + "unused_image_bytes": summary.UnusedImageBytes, "warnings": summary.Warnings, + "managed_container_count": summary.ManagedContainerCount, + "managed_container_bytes": summary.ManagedContainerBytes, + } +} + +type storageProgressReporter struct { + notify storagepkg.OverviewProgressCallback + mu sync.Mutex + sourceStarted map[string]time.Time + sourceCounters map[string]storageSourceCounters + sourcePartitions map[string]int + activeWalkers int + maxActiveWalkers int +} + +type storageSourceCounters struct { + completedItems int + totalItems int + hasTotalItems bool + bytesScanned int64 +} + +func newStorageProgressReporter(notify storagepkg.OverviewProgressCallback) *storageProgressReporter { + return &storageProgressReporter{ + notify: notify, sourceStarted: make(map[string]time.Time), + sourceCounters: make(map[string]storageSourceCounters), + sourcePartitions: make(map[string]int), + } +} + +func (r *storageProgressReporter) sendLocked(progress storagepkg.OverviewProgress) { + if r.notify != nil { + r.notify(progress) + } +} + +func (r *storageProgressReporter) start(source string) { + r.mu.Lock() + defer r.mu.Unlock() + r.sourceStarted[source] = time.Now() + r.sendLocked(storagepkg.OverviewProgress{Source: source, State: storagepkg.SourceStateScanning}) +} + +func (r *storageProgressReporter) complete(source string, value any, err error) { + r.mu.Lock() + defer r.mu.Unlock() + duration := time.Duration(0) + if started, ok := r.sourceStarted[source]; ok { + duration = time.Since(started) + } + counters := r.sourceCounters[source] + var totalItems *int + if counters.hasTotalItems { + totalItems = &counters.totalItems + } + state := storagepkg.SourceStateReady + if err != nil { + state = storagepkg.SourceStateFailed + } + r.sendLocked(storagepkg.OverviewProgress{ + Source: source, State: state, Value: value, Err: err, Duration: duration, + CompletedItems: counters.completedItems, TotalItems: totalItems, + BytesScanned: counters.bytesScanned, + }) +} + +func (r *storageProgressReporter) filesystem(source string) func(filescan.Progress) { + return func(progress filescan.Progress) { + completed, total := progress.CompletedPartitions, progress.TotalPartitions + if progress.Phase == filescan.RootCompleted { + completed, total = progress.CompletedRoots, progress.TotalRoots + } + r.mu.Lock() + defer r.mu.Unlock() + if progress.Phase == filescan.PartitionStarted { + r.activeWalkers++ + if r.activeWalkers > r.maxActiveWalkers { + r.maxActiveWalkers = r.activeWalkers + } + } + if progress.Phase == filescan.PartitionCompleted && r.activeWalkers > 0 { + r.activeWalkers-- + } + if progress.TotalPartitions > r.sourcePartitions[source] { + r.sourcePartitions[source] = progress.TotalPartitions + } + partitionCount := 0 + for _, count := range r.sourcePartitions { + partitionCount += count + } + maxActiveWalkers := r.maxActiveWalkers + counters := r.sourceCounters[source] + if completed > counters.completedItems { + counters.completedItems = completed + } + if total > counters.totalItems { + counters.totalItems = total + counters.hasTotalItems = true + } + if progress.BytesScanned > counters.bytesScanned { + counters.bytesScanned = progress.BytesScanned + } + r.sourceCounters[source] = counters + var totalItems *int + if counters.hasTotalItems { + totalItems = &counters.totalItems + } + r.sendLocked(storagepkg.OverviewProgress{ + Source: source, State: storagepkg.SourceStateScanning, + CompletedItems: counters.completedItems, TotalItems: totalItems, + BytesScanned: counters.bytesScanned, + PartitionCount: partitionCount, MaxActiveWalkers: maxActiveWalkers, + }) + } +} + +func logStorageAnalysisCompletion( + log *logger.Logger, + completion storagepkg.StorageAnalysisCompletion, +) { + if log == nil { + return + } + outcomes := make(map[string]string, len(completion.SourceStates)) + durations := make(map[string]int64, len(completion.SourceDurations)) + for source, state := range completion.SourceStates { + outcomes[source] = string(state) + } + for source, duration := range completion.SourceDurations { + durations[source] = duration.Milliseconds() + } + log.Info("system.storage.analysis.completed", + zap.Uint64("generation", completion.Generation), + zap.Duration("duration", completion.Duration), + zap.Any("source_durations_ms", durations), + zap.Any("source_outcomes", outcomes), + zap.Int("partition_count", completion.PartitionCount), + zap.Int("max_active_walkers", completion.MaxActiveWalkers), + zap.Bool("succeeded", completion.Succeeded), + ) } func (o *storageOverview) Capabilities( @@ -448,451 +714,3 @@ func (r *workspaceReconciler) Reconcile(ctx context.Context) error { _, err = r.factory(settings).Reconcile(ctx) return err } - -type workspaceQuarantineController struct { - settings *storagepkg.SettingsStore - store quarantineEntryStore - factory workspaceFactory - homeDir string - activity *activity.Coordinator - temporary *tempartifacts.Provider - rename func(string, string) error -} - -type quarantineEntryStore interface { - GetQuarantineEntry(context.Context, string) (storagepkg.QuarantineEntry, error) - ListQuarantineEntries(context.Context, bool) ([]storagepkg.QuarantineEntry, error) - TransitionQuarantineEntry( - context.Context, string, storagepkg.QuarantineState, string, - ) (storagepkg.QuarantineEntry, error) -} - -func (c *workspaceQuarantineController) Purge( - ctx context.Context, - scope storagepkg.QuarantinePurgeScope, - confirmation string, -) (storagepkg.QuarantinePurgeResult, error) { - result := storagepkg.QuarantinePurgeResult{Scope: scope} - force := false - switch scope { - case storagepkg.QuarantinePurgeScopeEligible: - if confirmation != storagepkg.QuarantineConfirmationEligible { - return result, fmt.Errorf("%w: eligible quarantine purge requires %s confirmation", storagepkg.ErrValidation, storagepkg.QuarantineConfirmationEligible) - } - case storagepkg.QuarantinePurgeScopeAll: - if confirmation != storagepkg.QuarantineConfirmationForce { - return result, storagepkg.ErrForceDeleteConfirmation - } - force = true - default: - return result, fmt.Errorf("%w: unknown quarantine purge scope %q", storagepkg.ErrValidation, scope) - } - entries, err := c.store.ListQuarantineEntries(ctx, false) - if err != nil { - return result, err - } - now := time.Now().UTC() - var purgeErrs []error - for _, entry := range entries { - if err := ctx.Err(); err != nil { - return result, err - } - result.Considered++ - if !force && now.Before(entry.DeleteAfter) { - result.Protected++ - result.ProtectedBytes += entry.SizeBytes - continue - } - var deleted storagepkg.QuarantineEntry - var payloadRemoved bool - if force { - deleted, payloadRemoved, err = c.permanentDeleteWithPayload(ctx, entry.ID, confirmation, true) - } else { - deleted, payloadRemoved, err = c.permanentDeleteWithPayload(ctx, entry.ID, storagepkg.QuarantineConfirmationDelete, false) - } - if err != nil { - result.Failed++ - result.FailedBytes += entry.SizeBytes - result.Failures = append(result.Failures, storagepkg.QuarantinePurgeFailure{ID: entry.ID, Error: err.Error()}) - purgeErrs = append(purgeErrs, fmt.Errorf("%s: %w", entry.ID, err)) - continue - } - result.Deleted++ - if payloadRemoved { - result.DeletedBytes += deleted.SizeBytes - } - } - return result, errors.Join(purgeErrs...) -} - -const ( - goCacheOwnershipManaged = "managed" - goCacheOwnershipAdopted = "adopted" -) - -func (c *workspaceQuarantineController) RestoreTask( - ctx context.Context, - taskID string, -) workspaces.WorkspaceRecovery { - current, err := c.settings.GetSettings(ctx) - if err != nil { - return workspaces.WorkspaceRecovery{TaskID: taskID, Status: "failed", Message: err.Error()} - } - return c.factory(current).RestoreTask(ctx, taskID) -} - -func (c *workspaceQuarantineController) Restore( - ctx context.Context, - id string, -) (storagepkg.QuarantineEntry, error) { - entry, err := c.store.GetQuarantineEntry(ctx, id) - if err != nil { - return storagepkg.QuarantineEntry{}, err - } - if entry.ResourceType == storagepkg.ResourceTypeGoCache { - return c.restoreGoCache(ctx, entry) - } - if entry.ResourceType == storagepkg.ResourceTypeTemporaryArtifact { - if c.temporary == nil { - return storagepkg.QuarantineEntry{}, errors.New("temporary artifact provider is unavailable") - } - return c.temporary.Restore(ctx, id) - } - if entry.ResourceType != storagepkg.ResourceTypeTaskWorkspace { - return storagepkg.QuarantineEntry{}, fmt.Errorf("%w: unsupported quarantine resource %q", storagepkg.ErrValidation, entry.ResourceType) - } - settings, err := c.settings.GetSettings(ctx) - if err != nil { - return storagepkg.QuarantineEntry{}, err - } - restored, err := c.factory(settings).Restore(ctx, id) - if errors.Is(err, workspaces.ErrRestoreConflict) { - return storagepkg.QuarantineEntry{}, fmt.Errorf("%w: %v", storagepkg.ErrConflict, err) - } - return restored, err -} - -func (c *workspaceQuarantineController) PermanentDelete( - ctx context.Context, - id string, - confirmation string, -) (storagepkg.QuarantineEntry, error) { - return c.permanentDelete(ctx, id, confirmation, false) -} - -func (c *workspaceQuarantineController) PermanentDeleteForce( - ctx context.Context, - id string, - confirmation string, -) (storagepkg.QuarantineEntry, error) { - return c.permanentDelete(ctx, id, confirmation, true) -} - -func (c *workspaceQuarantineController) permanentDelete( - ctx context.Context, - id string, - confirmation string, - force bool, -) (storagepkg.QuarantineEntry, error) { - deleted, _, err := c.permanentDeleteWithPayload(ctx, id, confirmation, force) - return deleted, err -} - -func (c *workspaceQuarantineController) permanentDeleteWithPayload( - ctx context.Context, - id string, - confirmation string, - force bool, -) (storagepkg.QuarantineEntry, bool, error) { - entry, err := c.store.GetQuarantineEntry(ctx, id) - if err != nil { - return storagepkg.QuarantineEntry{}, false, err - } - if entry.ResourceType == storagepkg.ResourceTypeGoCache { - if force { - return c.deleteGoCacheWithRetention(ctx, entry, confirmation, true) - } - return c.deleteGoCacheWithRetention(ctx, entry, confirmation, false) - } - if entry.ResourceType == storagepkg.ResourceTypeTemporaryArtifact { - if c.temporary == nil { - return storagepkg.QuarantineEntry{}, false, errors.New("temporary artifact provider is unavailable") - } - var deleted storagepkg.QuarantineEntry - if force { - deleted, err = c.temporary.PermanentDeleteForce(ctx, id, confirmation) - } else { - deleted, err = c.temporary.PermanentDelete(ctx, id, confirmation) - } - return deleted, true, err - } - if entry.ResourceType != storagepkg.ResourceTypeTaskWorkspace { - return storagepkg.QuarantineEntry{}, false, fmt.Errorf("%w: unsupported quarantine resource %q", storagepkg.ErrValidation, entry.ResourceType) - } - settings, err := c.settings.GetSettings(ctx) - if err != nil { - return storagepkg.QuarantineEntry{}, false, err - } - var deleted storagepkg.QuarantineEntry - if force { - deleted, err = c.factory(settings).PermanentDeleteForce(ctx, id, confirmation) - } else { - deleted, err = c.factory(settings).PermanentDelete(ctx, id, confirmation) - } - return deleted, true, err -} - -func (c *workspaceQuarantineController) restoreGoCache( - ctx context.Context, - entry storagepkg.QuarantineEntry, -) (storagepkg.QuarantineEntry, error) { - if err := c.validateGoCacheEntry(ctx, entry); err != nil { - return storagepkg.QuarantineEntry{}, err - } - lease, err := c.acquireGoCacheMaintenance(ctx) - if err != nil { - return storagepkg.QuarantineEntry{}, err - } - if lease != nil { - defer lease.Release() - } - if err := c.rejectAmbiguousMissingGoCachePayload(entry); err != nil { - return storagepkg.QuarantineEntry{}, err - } - if err := c.prepareGoCacheRestoreDestination(entry); err != nil { - return storagepkg.QuarantineEntry{}, err - } - if err := c.renamePath(entry.QuarantinePath, entry.OriginalPath); err != nil { - return storagepkg.QuarantineEntry{}, fmt.Errorf("restore Go cache: %w", err) - } - return c.persistGoCacheRestore(ctx, entry) -} - -func (c *workspaceQuarantineController) prepareGoCacheRestoreDestination( - entry storagepkg.QuarantineEntry, -) error { - if err := c.validateGoCacheRestorePath(entry.OriginalPath); err != nil { - return err - } - if _, err := os.Lstat(entry.OriginalPath); err == nil { - ownership, ownershipErr := goCacheEntryOwnership(entry) - if ownershipErr != nil { - return ownershipErr - } - removed, removeErr := gocache.RemoveRestorePlaceholder( - entry.OriginalPath, ownership == goCacheOwnershipAdopted, - ) - if removeErr != nil { - return removeErr - } - if !removed { - return fmt.Errorf("%w: Go-cache restore destination already exists", storagepkg.ErrConflict) - } - } else if !errors.Is(err, os.ErrNotExist) { - return fmt.Errorf("inspect Go-cache restore destination: %w", err) - } - if err := os.MkdirAll(filepath.Dir(entry.OriginalPath), 0o700); err != nil { - return fmt.Errorf("create Go-cache restore parent: %w", err) - } - return nil -} - -func (c *workspaceQuarantineController) persistGoCacheRestore( - ctx context.Context, - entry storagepkg.QuarantineEntry, -) (storagepkg.QuarantineEntry, error) { - restored, err := c.store.TransitionQuarantineEntry( - ctx, entry.ID, storagepkg.QuarantineStateRestored, "", - ) - if err != nil { - persistErr := fmt.Errorf("persist Go-cache restore: %w", err) - if rollbackErr := c.renamePath(entry.OriginalPath, entry.QuarantinePath); rollbackErr != nil { - return storagepkg.QuarantineEntry{}, errors.Join( - persistErr, fmt.Errorf("rollback Go-cache restore: %w", rollbackErr), - ) - } - return storagepkg.QuarantineEntry{}, persistErr - } - return restored, nil -} - -func (c *workspaceQuarantineController) renamePath(oldPath, newPath string) error { - if c.rename != nil { - return c.rename(oldPath, newPath) - } - return os.Rename(oldPath, newPath) -} - -func (c *workspaceQuarantineController) acquireGoCacheMaintenance( - ctx context.Context, -) (*activity.MaintenanceLease, error) { - if c.activity == nil { - return nil, nil - } - lease, busy, err := c.activity.TryAcquireMaintenance(ctx, 0) - if errors.Is(err, activity.ErrBusy) { - return nil, &storagepkg.BusyError{ - Resources: activity.BusyResourcesForKinds(busy), - ForceAvailable: false, - } - } - return lease, err -} - -func (c *workspaceQuarantineController) deleteGoCacheWithRetention( - ctx context.Context, - entry storagepkg.QuarantineEntry, - confirmation string, - force bool, -) (storagepkg.QuarantineEntry, bool, error) { - if force { - if confirmation != storagepkg.QuarantineConfirmationForce { - return storagepkg.QuarantineEntry{}, false, storagepkg.ErrForceDeleteConfirmation - } - } else if confirmation != storagepkg.QuarantineConfirmationDelete { - return storagepkg.QuarantineEntry{}, false, fmt.Errorf("%w: quarantine deletion requires DELETE confirmation", storagepkg.ErrValidation) - } - if err := c.validateGoCacheEntry(ctx, entry); err != nil { - return storagepkg.QuarantineEntry{}, false, err - } - if !force && time.Now().UTC().Before(entry.DeleteAfter) { - return storagepkg.QuarantineEntry{}, false, fmt.Errorf("%w: quarantine retention deadline has not elapsed", storagepkg.ErrConflict) - } - payloadPresent, err := goCacheQuarantinePayloadPresent(entry) - if err != nil { - return storagepkg.QuarantineEntry{}, false, err - } - if !payloadPresent { - deleted, err := c.persistGoCacheDeletion(ctx, entry) - return deleted, false, err - } - if err := c.rejectAmbiguousMissingGoCachePayload(entry); err != nil { - return storagepkg.QuarantineEntry{}, false, err - } - if err := os.RemoveAll(entry.QuarantinePath); err != nil { - return storagepkg.QuarantineEntry{}, false, fmt.Errorf("delete quarantined Go cache: %w", err) - } - deleted, err := c.persistGoCacheDeletion(ctx, entry) - return deleted, true, err -} - -func goCacheQuarantinePayloadPresent(entry storagepkg.QuarantineEntry) (bool, error) { - if _, err := os.Lstat(entry.QuarantinePath); errors.Is(err, os.ErrNotExist) { - return false, nil - } else if err != nil { - return false, fmt.Errorf("inspect Go-cache quarantine payload: %w", err) - } - return true, nil -} - -func (c *workspaceQuarantineController) persistGoCacheDeletion( - ctx context.Context, - entry storagepkg.QuarantineEntry, -) (storagepkg.QuarantineEntry, error) { - deleted, err := c.store.TransitionQuarantineEntry( - context.WithoutCancel(ctx), entry.ID, storagepkg.QuarantineStateDeleted, "", - ) - if err != nil { - return storagepkg.QuarantineEntry{}, fmt.Errorf("persist Go-cache deletion: %w", err) - } - return deleted, nil -} - -func (c *workspaceQuarantineController) validateGoCacheEntry( - _ context.Context, - entry storagepkg.QuarantineEntry, -) error { - if entry.State != storagepkg.QuarantineStateQuarantined && - entry.State != storagepkg.QuarantineStateFailed { - return fmt.Errorf("%w: Go-cache quarantine entry is %q", storagepkg.ErrConflict, entry.State) - } - expectedQuarantine := filepath.Join(c.homeDir, "trash", "go-cache", entry.ID) - if filepath.Clean(entry.QuarantinePath) != filepath.Clean(expectedQuarantine) { - return fmt.Errorf("%w: Go-cache quarantine paths do not match managed storage", storagepkg.ErrValidation) - } - ownership, err := goCacheEntryOwnership(entry) - if err != nil { - return err - } - switch ownership { - case goCacheOwnershipManaged: - expectedOriginal := filepath.Join(c.homeDir, "cache", "go-build") - if filepath.Clean(entry.OriginalPath) != filepath.Clean(expectedOriginal) { - return fmt.Errorf("%w: managed Go-cache original path does not match owned storage", storagepkg.ErrValidation) - } - case goCacheOwnershipAdopted: - original := filepath.Clean(entry.OriginalPath) - if !filepath.IsAbs(original) || original == filepath.VolumeName(original)+string(filepath.Separator) { - return fmt.Errorf("%w: adopted Go-cache original path is unsafe", storagepkg.ErrValidation) - } - default: - return fmt.Errorf("%w: unknown Go-cache ownership policy %q", storagepkg.ErrValidation, ownership) - } - if err := storagepkg.ValidateNoSymlinkPath(c.homeDir, entry.QuarantinePath); err != nil { - return fmt.Errorf("%w: validate Go-cache quarantine path: %v", storagepkg.ErrValidation, err) - } - return nil -} - -func goCacheEntryOwnership(entry storagepkg.QuarantineEntry) (string, error) { - var metadata struct { - Ownership string `json:"ownership"` - } - if err := json.Unmarshal(entry.Metadata, &metadata); err != nil || metadata.Ownership == "" { - return "", fmt.Errorf("%w: invalid Go-cache quarantine ownership metadata", storagepkg.ErrValidation) - } - return metadata.Ownership, nil -} - -func (c *workspaceQuarantineController) rejectAmbiguousMissingGoCachePayload( - entry storagepkg.QuarantineEntry, -) error { - if entry.State != storagepkg.QuarantineStateFailed && - entry.State != storagepkg.QuarantineStateQuarantined { - return nil - } - if _, err := os.Lstat(entry.OriginalPath); errors.Is(err, os.ErrNotExist) { - return nil - } else if err != nil { - return fmt.Errorf("inspect failed Go-cache original path: %w", err) - } - if _, err := os.Lstat(entry.QuarantinePath); err == nil { - return nil - } else if !errors.Is(err, os.ErrNotExist) { - return fmt.Errorf("inspect failed Go-cache quarantine path: %w", err) - } - if err := c.validateGoCacheRestorePath(entry.OriginalPath); err != nil { - return err - } - ownership, err := goCacheEntryOwnership(entry) - if err != nil { - return err - } - placeholder, err := gocache.IsRestorePlaceholder( - entry.OriginalPath, ownership == goCacheOwnershipAdopted, - ) - if err != nil { - return fmt.Errorf("inspect Go-cache restore placeholder: %w", err) - } - if placeholder { - return fmt.Errorf( - "%w: quarantined Go-cache payload is missing and the original path is only a rotation placeholder", - storagepkg.ErrConflict, - ) - } - return fmt.Errorf( - "%w: quarantined Go-cache payload is missing and the populated original cannot be proven restored", - storagepkg.ErrConflict, - ) -} - -func (c *workspaceQuarantineController) validateGoCacheRestorePath(path string) error { - anchor, err := storagepkg.CommonPath(c.homeDir, path) - if err != nil { - return fmt.Errorf("%w: resolve Go-cache restore safety anchor: %v", storagepkg.ErrValidation, err) - } - if err := storagepkg.ValidateNoSymlinkPath(anchor, path); err != nil { - return fmt.Errorf("%w: validate Go-cache restore path: %v", storagepkg.ErrValidation, err) - } - return nil -} diff --git a/apps/backend/internal/backendapp/storage_maintenance_test.go b/apps/backend/internal/backendapp/storage_maintenance_test.go index b6d7fef133..b48dbe918b 100644 --- a/apps/backend/internal/backendapp/storage_maintenance_test.go +++ b/apps/backend/internal/backendapp/storage_maintenance_test.go @@ -20,6 +20,7 @@ import ( systemsettings "github.com/kandev/kandev/internal/system/settings" storagepkg "github.com/kandev/kandev/internal/system/storage" "github.com/kandev/kandev/internal/system/storage/dockerstore" + "github.com/kandev/kandev/internal/system/storage/filescan" "github.com/kandev/kandev/internal/system/storage/gocache" "github.com/kandev/kandev/internal/system/storage/workspaces" ) @@ -93,6 +94,76 @@ func TestStorageOverviewIncludesQuarantineAndManagedContainers(t *testing.T) { } } +func TestStorageOverviewReportsProgressForEachSource(t *testing.T) { + settings, _ := newStorageMaintenanceStores(t) + docker := dockerstore.NewProvider( + &overviewDockerClient{}, overviewContainerInventory{}, settings, + ) + events := make(chan storagepkg.OverviewProgress, 16) + overview := &storageOverview{ + settings: settings, + quarantine: failingQuarantineSummarizer{err: errors.New("quarantine unavailable")}, + workspaceAnalyze: func(context.Context, storagepkg.StorageMaintenanceSettings) (workspaces.Analysis, error) { + return workspaces.Analysis{TotalBytes: 10}, nil + }, + goCacheAnalyze: func(context.Context) (gocache.Analysis, error) { + return gocache.Analysis{SizeBytes: 20}, nil + }, + docker: docker, + } + + if _, err := overview.SummaryWithProgress(context.Background(), func(progress storagepkg.OverviewProgress) { + events <- progress + }); err != nil { + t.Fatalf("SummaryWithProgress: %v", err) + } + seen := make(map[string]map[storagepkg.SourceStateName]bool) + for len(events) > 0 { + progress := <-events + if seen[progress.Source] == nil { + seen[progress.Source] = make(map[storagepkg.SourceStateName]bool) + } + seen[progress.Source][progress.State] = true + } + for _, source := range []string{ + storagepkg.StorageSourceWorkspaces, + storagepkg.StorageSourceGoCache, + storagepkg.StorageSourceQuarantine, + storagepkg.StorageSourceTemporaryArtifacts, + storagepkg.StorageSourceDocker, + } { + if !seen[source][storagepkg.SourceStateScanning] { + t.Fatalf("source %q did not report scanning progress: %#v", source, seen[source]) + } + } + if !seen[storagepkg.StorageSourceQuarantine][storagepkg.SourceStateFailed] { + t.Fatalf("quarantine source did not report failure: %#v", seen[storagepkg.StorageSourceQuarantine]) + } +} + +func TestStorageProgressReporterCompletionPreservesFilesystemCounters(t *testing.T) { + var events []storagepkg.OverviewProgress + reporter := newStorageProgressReporter(func(progress storagepkg.OverviewProgress) { + events = append(events, progress) + }) + reporter.filesystem(storagepkg.StorageSourceWorkspaces)(filescan.Progress{ + Phase: filescan.PartitionCompleted, CompletedPartitions: 2, TotalPartitions: 3, + BytesScanned: 42, + }) + reporter.complete(storagepkg.StorageSourceWorkspaces, map[string]any{"total_bytes": int64(42)}, nil) + + if len(events) != 2 { + t.Fatalf("progress event count = %d, want 2", len(events)) + } + completion := events[1] + if completion.CompletedItems != 2 || completion.BytesScanned != 42 { + t.Fatalf("completion progress = %#v, want filesystem counters", completion) + } + if completion.TotalItems == nil || *completion.TotalItems != 3 { + t.Fatalf("completion total_items = %v, want 3", completion.TotalItems) + } +} + func TestStorageCleanupProvidersIncludeWorkspaceDependencyCleanup(t *testing.T) { settings, store := newStorageMaintenanceStores(t) home := t.TempDir() diff --git a/apps/backend/internal/backendapp/storage_quarantine_controller.go b/apps/backend/internal/backendapp/storage_quarantine_controller.go new file mode 100644 index 0000000000..9528944e93 --- /dev/null +++ b/apps/backend/internal/backendapp/storage_quarantine_controller.go @@ -0,0 +1,465 @@ +package backendapp + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "os" + "path/filepath" + "time" + + "github.com/kandev/kandev/internal/agent/runtime/activity" + storagepkg "github.com/kandev/kandev/internal/system/storage" + "github.com/kandev/kandev/internal/system/storage/gocache" + "github.com/kandev/kandev/internal/system/storage/tempartifacts" + "github.com/kandev/kandev/internal/system/storage/workspaces" +) + +type workspaceQuarantineController struct { + settings *storagepkg.SettingsStore + store quarantineEntryStore + factory workspaceFactory + homeDir string + activity *activity.Coordinator + temporary *tempartifacts.Provider + rename func(string, string) error +} + +type quarantineEntryStore interface { + GetQuarantineEntry(context.Context, string) (storagepkg.QuarantineEntry, error) + ListQuarantineEntries(context.Context, bool) ([]storagepkg.QuarantineEntry, error) + TransitionQuarantineEntry( + context.Context, string, storagepkg.QuarantineState, string, + ) (storagepkg.QuarantineEntry, error) +} + +func (c *workspaceQuarantineController) Purge( + ctx context.Context, + scope storagepkg.QuarantinePurgeScope, + confirmation string, +) (storagepkg.QuarantinePurgeResult, error) { + result := storagepkg.QuarantinePurgeResult{Scope: scope} + force := false + switch scope { + case storagepkg.QuarantinePurgeScopeEligible: + if confirmation != storagepkg.QuarantineConfirmationEligible { + return result, fmt.Errorf("%w: eligible quarantine purge requires %s confirmation", storagepkg.ErrValidation, storagepkg.QuarantineConfirmationEligible) + } + case storagepkg.QuarantinePurgeScopeAll: + if confirmation != storagepkg.QuarantineConfirmationForce { + return result, storagepkg.ErrForceDeleteConfirmation + } + force = true + default: + return result, fmt.Errorf("%w: unknown quarantine purge scope %q", storagepkg.ErrValidation, scope) + } + entries, err := c.store.ListQuarantineEntries(ctx, false) + if err != nil { + return result, err + } + now := time.Now().UTC() + var purgeErrs []error + for _, entry := range entries { + if err := ctx.Err(); err != nil { + return result, err + } + result.Considered++ + if !force && now.Before(entry.DeleteAfter) { + result.Protected++ + result.ProtectedBytes += entry.SizeBytes + continue + } + var deleted storagepkg.QuarantineEntry + var payloadRemoved bool + if force { + deleted, payloadRemoved, err = c.permanentDeleteWithPayload(ctx, entry.ID, confirmation, true) + } else { + deleted, payloadRemoved, err = c.permanentDeleteWithPayload(ctx, entry.ID, storagepkg.QuarantineConfirmationDelete, false) + } + if err != nil { + result.Failed++ + result.FailedBytes += entry.SizeBytes + result.Failures = append(result.Failures, storagepkg.QuarantinePurgeFailure{ID: entry.ID, Error: err.Error()}) + purgeErrs = append(purgeErrs, fmt.Errorf("%s: %w", entry.ID, err)) + continue + } + result.Deleted++ + if payloadRemoved { + result.DeletedBytes += deleted.SizeBytes + } + } + return result, errors.Join(purgeErrs...) +} + +const ( + goCacheOwnershipManaged = "managed" + goCacheOwnershipAdopted = "adopted" +) + +func (c *workspaceQuarantineController) RestoreTask( + ctx context.Context, + taskID string, +) workspaces.WorkspaceRecovery { + current, err := c.settings.GetSettings(ctx) + if err != nil { + return workspaces.WorkspaceRecovery{TaskID: taskID, Status: "failed", Message: err.Error()} + } + return c.factory(current).RestoreTask(ctx, taskID) +} + +func (c *workspaceQuarantineController) Restore( + ctx context.Context, + id string, +) (storagepkg.QuarantineEntry, error) { + entry, err := c.store.GetQuarantineEntry(ctx, id) + if err != nil { + return storagepkg.QuarantineEntry{}, err + } + if entry.ResourceType == storagepkg.ResourceTypeGoCache { + return c.restoreGoCache(ctx, entry) + } + if entry.ResourceType == storagepkg.ResourceTypeTemporaryArtifact { + if c.temporary == nil { + return storagepkg.QuarantineEntry{}, errors.New("temporary artifact provider is unavailable") + } + return c.temporary.Restore(ctx, id) + } + if entry.ResourceType != storagepkg.ResourceTypeTaskWorkspace { + return storagepkg.QuarantineEntry{}, fmt.Errorf("%w: unsupported quarantine resource %q", storagepkg.ErrValidation, entry.ResourceType) + } + settings, err := c.settings.GetSettings(ctx) + if err != nil { + return storagepkg.QuarantineEntry{}, err + } + restored, err := c.factory(settings).Restore(ctx, id) + if errors.Is(err, workspaces.ErrRestoreConflict) { + return storagepkg.QuarantineEntry{}, fmt.Errorf("%w: %v", storagepkg.ErrConflict, err) + } + return restored, err +} + +func (c *workspaceQuarantineController) PermanentDelete( + ctx context.Context, + id string, + confirmation string, +) (storagepkg.QuarantineEntry, error) { + return c.permanentDelete(ctx, id, confirmation, false) +} + +func (c *workspaceQuarantineController) PermanentDeleteForce( + ctx context.Context, + id string, + confirmation string, +) (storagepkg.QuarantineEntry, error) { + return c.permanentDelete(ctx, id, confirmation, true) +} + +func (c *workspaceQuarantineController) permanentDelete( + ctx context.Context, + id string, + confirmation string, + force bool, +) (storagepkg.QuarantineEntry, error) { + deleted, _, err := c.permanentDeleteWithPayload(ctx, id, confirmation, force) + return deleted, err +} + +func (c *workspaceQuarantineController) permanentDeleteWithPayload( + ctx context.Context, + id string, + confirmation string, + force bool, +) (storagepkg.QuarantineEntry, bool, error) { + entry, err := c.store.GetQuarantineEntry(ctx, id) + if err != nil { + return storagepkg.QuarantineEntry{}, false, err + } + if entry.ResourceType == storagepkg.ResourceTypeGoCache { + if force { + return c.deleteGoCacheWithRetention(ctx, entry, confirmation, true) + } + return c.deleteGoCacheWithRetention(ctx, entry, confirmation, false) + } + if entry.ResourceType == storagepkg.ResourceTypeTemporaryArtifact { + if c.temporary == nil { + return storagepkg.QuarantineEntry{}, false, errors.New("temporary artifact provider is unavailable") + } + var deleted storagepkg.QuarantineEntry + if force { + deleted, err = c.temporary.PermanentDeleteForce(ctx, id, confirmation) + } else { + deleted, err = c.temporary.PermanentDelete(ctx, id, confirmation) + } + return deleted, true, err + } + if entry.ResourceType != storagepkg.ResourceTypeTaskWorkspace { + return storagepkg.QuarantineEntry{}, false, fmt.Errorf("%w: unsupported quarantine resource %q", storagepkg.ErrValidation, entry.ResourceType) + } + settings, err := c.settings.GetSettings(ctx) + if err != nil { + return storagepkg.QuarantineEntry{}, false, err + } + var deleted storagepkg.QuarantineEntry + if force { + deleted, err = c.factory(settings).PermanentDeleteForce(ctx, id, confirmation) + } else { + deleted, err = c.factory(settings).PermanentDelete(ctx, id, confirmation) + } + return deleted, true, err +} + +func (c *workspaceQuarantineController) restoreGoCache( + ctx context.Context, + entry storagepkg.QuarantineEntry, +) (storagepkg.QuarantineEntry, error) { + if err := c.validateGoCacheEntry(ctx, entry); err != nil { + return storagepkg.QuarantineEntry{}, err + } + lease, err := c.acquireGoCacheMaintenance(ctx) + if err != nil { + return storagepkg.QuarantineEntry{}, err + } + if lease != nil { + defer lease.Release() + } + if err := c.rejectAmbiguousMissingGoCachePayload(entry); err != nil { + return storagepkg.QuarantineEntry{}, err + } + if err := c.prepareGoCacheRestoreDestination(entry); err != nil { + return storagepkg.QuarantineEntry{}, err + } + if err := c.renamePath(entry.QuarantinePath, entry.OriginalPath); err != nil { + return storagepkg.QuarantineEntry{}, fmt.Errorf("restore Go cache: %w", err) + } + return c.persistGoCacheRestore(ctx, entry) +} + +func (c *workspaceQuarantineController) prepareGoCacheRestoreDestination( + entry storagepkg.QuarantineEntry, +) error { + if err := c.validateGoCacheRestorePath(entry.OriginalPath); err != nil { + return err + } + if _, err := os.Lstat(entry.OriginalPath); err == nil { + ownership, ownershipErr := goCacheEntryOwnership(entry) + if ownershipErr != nil { + return ownershipErr + } + removed, removeErr := gocache.RemoveRestorePlaceholder( + entry.OriginalPath, ownership == goCacheOwnershipAdopted, + ) + if removeErr != nil { + return removeErr + } + if !removed { + return fmt.Errorf("%w: Go-cache restore destination already exists", storagepkg.ErrConflict) + } + } else if !errors.Is(err, os.ErrNotExist) { + return fmt.Errorf("inspect Go-cache restore destination: %w", err) + } + if err := os.MkdirAll(filepath.Dir(entry.OriginalPath), 0o700); err != nil { + return fmt.Errorf("create Go-cache restore parent: %w", err) + } + return nil +} + +func (c *workspaceQuarantineController) persistGoCacheRestore( + ctx context.Context, + entry storagepkg.QuarantineEntry, +) (storagepkg.QuarantineEntry, error) { + restored, err := c.store.TransitionQuarantineEntry( + ctx, entry.ID, storagepkg.QuarantineStateRestored, "", + ) + if err != nil { + persistErr := fmt.Errorf("persist Go-cache restore: %w", err) + if rollbackErr := c.renamePath(entry.OriginalPath, entry.QuarantinePath); rollbackErr != nil { + return storagepkg.QuarantineEntry{}, errors.Join( + persistErr, fmt.Errorf("rollback Go-cache restore: %w", rollbackErr), + ) + } + return storagepkg.QuarantineEntry{}, persistErr + } + return restored, nil +} + +func (c *workspaceQuarantineController) renamePath(oldPath, newPath string) error { + if c.rename != nil { + return c.rename(oldPath, newPath) + } + return os.Rename(oldPath, newPath) +} + +func (c *workspaceQuarantineController) acquireGoCacheMaintenance( + ctx context.Context, +) (*activity.MaintenanceLease, error) { + if c.activity == nil { + return nil, nil + } + lease, busy, err := c.activity.TryAcquireMaintenance(ctx, 0) + if errors.Is(err, activity.ErrBusy) { + return nil, &storagepkg.BusyError{ + Resources: activity.BusyResourcesForKinds(busy), + ForceAvailable: false, + } + } + return lease, err +} + +func (c *workspaceQuarantineController) deleteGoCacheWithRetention( + ctx context.Context, + entry storagepkg.QuarantineEntry, + confirmation string, + force bool, +) (storagepkg.QuarantineEntry, bool, error) { + if force { + if confirmation != storagepkg.QuarantineConfirmationForce { + return storagepkg.QuarantineEntry{}, false, storagepkg.ErrForceDeleteConfirmation + } + } else if confirmation != storagepkg.QuarantineConfirmationDelete { + return storagepkg.QuarantineEntry{}, false, fmt.Errorf("%w: quarantine deletion requires DELETE confirmation", storagepkg.ErrValidation) + } + if err := c.validateGoCacheEntry(ctx, entry); err != nil { + return storagepkg.QuarantineEntry{}, false, err + } + if !force && time.Now().UTC().Before(entry.DeleteAfter) { + return storagepkg.QuarantineEntry{}, false, fmt.Errorf("%w: quarantine retention deadline has not elapsed", storagepkg.ErrConflict) + } + payloadPresent, err := goCacheQuarantinePayloadPresent(entry) + if err != nil { + return storagepkg.QuarantineEntry{}, false, err + } + if !payloadPresent { + deleted, err := c.persistGoCacheDeletion(ctx, entry) + return deleted, false, err + } + if err := c.rejectAmbiguousMissingGoCachePayload(entry); err != nil { + return storagepkg.QuarantineEntry{}, false, err + } + if err := os.RemoveAll(entry.QuarantinePath); err != nil { + return storagepkg.QuarantineEntry{}, false, fmt.Errorf("delete quarantined Go cache: %w", err) + } + deleted, err := c.persistGoCacheDeletion(ctx, entry) + return deleted, true, err +} + +func goCacheQuarantinePayloadPresent(entry storagepkg.QuarantineEntry) (bool, error) { + if _, err := os.Lstat(entry.QuarantinePath); errors.Is(err, os.ErrNotExist) { + return false, nil + } else if err != nil { + return false, fmt.Errorf("inspect Go-cache quarantine payload: %w", err) + } + return true, nil +} + +func (c *workspaceQuarantineController) persistGoCacheDeletion( + ctx context.Context, + entry storagepkg.QuarantineEntry, +) (storagepkg.QuarantineEntry, error) { + deleted, err := c.store.TransitionQuarantineEntry( + context.WithoutCancel(ctx), entry.ID, storagepkg.QuarantineStateDeleted, "", + ) + if err != nil { + return storagepkg.QuarantineEntry{}, fmt.Errorf("persist Go-cache deletion: %w", err) + } + return deleted, nil +} + +func (c *workspaceQuarantineController) validateGoCacheEntry( + _ context.Context, + entry storagepkg.QuarantineEntry, +) error { + if entry.State != storagepkg.QuarantineStateQuarantined && + entry.State != storagepkg.QuarantineStateFailed { + return fmt.Errorf("%w: Go-cache quarantine entry is %q", storagepkg.ErrConflict, entry.State) + } + expectedQuarantine := filepath.Join(c.homeDir, "trash", "go-cache", entry.ID) + if filepath.Clean(entry.QuarantinePath) != filepath.Clean(expectedQuarantine) { + return fmt.Errorf("%w: Go-cache quarantine paths do not match managed storage", storagepkg.ErrValidation) + } + ownership, err := goCacheEntryOwnership(entry) + if err != nil { + return err + } + switch ownership { + case goCacheOwnershipManaged: + expectedOriginal := filepath.Join(c.homeDir, "cache", "go-build") + if filepath.Clean(entry.OriginalPath) != filepath.Clean(expectedOriginal) { + return fmt.Errorf("%w: managed Go-cache original path does not match owned storage", storagepkg.ErrValidation) + } + case goCacheOwnershipAdopted: + original := filepath.Clean(entry.OriginalPath) + if !filepath.IsAbs(original) || original == filepath.VolumeName(original)+string(filepath.Separator) { + return fmt.Errorf("%w: adopted Go-cache original path is unsafe", storagepkg.ErrValidation) + } + default: + return fmt.Errorf("%w: unknown Go-cache ownership policy %q", storagepkg.ErrValidation, ownership) + } + if err := storagepkg.ValidateNoSymlinkPath(c.homeDir, entry.QuarantinePath); err != nil { + return fmt.Errorf("%w: validate Go-cache quarantine path: %v", storagepkg.ErrValidation, err) + } + return nil +} + +func goCacheEntryOwnership(entry storagepkg.QuarantineEntry) (string, error) { + var metadata struct { + Ownership string `json:"ownership"` + } + if err := json.Unmarshal(entry.Metadata, &metadata); err != nil || metadata.Ownership == "" { + return "", fmt.Errorf("%w: invalid Go-cache quarantine ownership metadata", storagepkg.ErrValidation) + } + return metadata.Ownership, nil +} + +func (c *workspaceQuarantineController) rejectAmbiguousMissingGoCachePayload( + entry storagepkg.QuarantineEntry, +) error { + if entry.State != storagepkg.QuarantineStateFailed && + entry.State != storagepkg.QuarantineStateQuarantined { + return nil + } + if _, err := os.Lstat(entry.OriginalPath); errors.Is(err, os.ErrNotExist) { + return nil + } else if err != nil { + return fmt.Errorf("inspect failed Go-cache original path: %w", err) + } + if _, err := os.Lstat(entry.QuarantinePath); err == nil { + return nil + } else if !errors.Is(err, os.ErrNotExist) { + return fmt.Errorf("inspect failed Go-cache quarantine path: %w", err) + } + if err := c.validateGoCacheRestorePath(entry.OriginalPath); err != nil { + return err + } + ownership, err := goCacheEntryOwnership(entry) + if err != nil { + return err + } + placeholder, err := gocache.IsRestorePlaceholder( + entry.OriginalPath, ownership == goCacheOwnershipAdopted, + ) + if err != nil { + return fmt.Errorf("inspect Go-cache restore placeholder: %w", err) + } + if placeholder { + return fmt.Errorf( + "%w: quarantined Go-cache payload is missing and the original path is only a rotation placeholder", + storagepkg.ErrConflict, + ) + } + return fmt.Errorf( + "%w: quarantined Go-cache payload is missing and the populated original cannot be proven restored", + storagepkg.ErrConflict, + ) +} + +func (c *workspaceQuarantineController) validateGoCacheRestorePath(path string) error { + anchor, err := storagepkg.CommonPath(c.homeDir, path) + if err != nil { + return fmt.Errorf("%w: resolve Go-cache restore safety anchor: %v", storagepkg.ErrValidation, err) + } + if err := storagepkg.ValidateNoSymlinkPath(anchor, path); err != nil { + return fmt.Errorf("%w: validate Go-cache restore path: %v", storagepkg.ErrValidation, err) + } + return nil +} diff --git a/apps/backend/internal/events/types.go b/apps/backend/internal/events/types.go index 9d6f9b64ba..91fe1d25e0 100644 --- a/apps/backend/internal/events/types.go +++ b/apps/backend/internal/events/types.go @@ -211,6 +211,7 @@ const PluginUserStateUpdated = "plugin.user-state.updated" // every state transition and broadcast to all WebSocket clients. const ( SystemJobUpdate = "system.job.update" + SystemStorageAnalysisUpdated = "system.storage.analysis.updated" AgentRuntimeAvailabilityChanged = "system.agent_runtime.availability_changed" ) diff --git a/apps/backend/internal/gateway/websocket/agent_runtime_notifications_test.go b/apps/backend/internal/gateway/websocket/agent_runtime_notifications_test.go index 517325fb37..79c150885a 100644 --- a/apps/backend/internal/gateway/websocket/agent_runtime_notifications_test.go +++ b/apps/backend/internal/gateway/websocket/agent_runtime_notifications_test.go @@ -9,6 +9,7 @@ import ( "github.com/kandev/kandev/internal/events" "github.com/kandev/kandev/internal/events/bus" + storagepkg "github.com/kandev/kandev/internal/system/storage" ws "github.com/kandev/kandev/pkg/websocket" ) @@ -77,6 +78,36 @@ func TestSystemEventBroadcasterCloseIsIdempotent(t *testing.T) { eventBus.Close() } +func TestSystemStorageAnalysisNotificationsBroadcastProgressState(t *testing.T) { + hub := newTestHub(t) + ctx, cancel := context.WithCancel(context.Background()) + t.Cleanup(cancel) + go hub.Run(ctx) + + eventBus := bus.NewMemoryEventBus(testLoggerForUserNotifications(t)) + t.Cleanup(eventBus.Close) + broadcaster := RegisterSystemNotifications(ctx, eventBus, hub, testLoggerForUserNotifications(t)) + t.Cleanup(broadcaster.Close) + client := newTestClient("storage") + registerTestClient(hub, client) + payload := storagepkg.StorageAnalysisUpdated{Generation: 3, State: storagepkg.AnalysisStateScanning} + if err := eventBus.Publish(ctx, events.SystemStorageAnalysisUpdated, + bus.NewEvent(events.SystemStorageAnalysisUpdated, "test", payload)); err != nil { + t.Fatalf("publish storage event: %v", err) + } + message := readNotification(t, client) + if message.Action != ws.ActionSystemStorageAnalysisUpdated { + t.Fatalf("storage action = %q, want %q", message.Action, ws.ActionSystemStorageAnalysisUpdated) + } + var received storagepkg.StorageAnalysisUpdated + if err := json.Unmarshal(message.Payload, &received); err != nil { + t.Fatalf("decode storage payload: %v", err) + } + if received != payload { + t.Fatalf("storage payload = %#v, want %#v", received, payload) + } +} + func readNotification(t *testing.T, client *Client) ws.Message { t.Helper() select { diff --git a/apps/backend/internal/gateway/websocket/system_notifications.go b/apps/backend/internal/gateway/websocket/system_notifications.go index e853a227bc..c0cc9e5eee 100644 --- a/apps/backend/internal/gateway/websocket/system_notifications.go +++ b/apps/backend/internal/gateway/websocket/system_notifications.go @@ -34,6 +34,7 @@ func RegisterSystemNotifications(ctx context.Context, eventBus bus.EventBus, hub } b.subscribe(eventBus, events.SystemJobUpdate, ws.ActionSystemJobUpdate) + b.subscribe(eventBus, events.SystemStorageAnalysisUpdated, ws.ActionSystemStorageAnalysisUpdated) go func() { <-ctx.Done() diff --git a/apps/backend/internal/system/storage/analysis_state.go b/apps/backend/internal/system/storage/analysis_state.go new file mode 100644 index 0000000000..2351492513 --- /dev/null +++ b/apps/backend/internal/system/storage/analysis_state.go @@ -0,0 +1,111 @@ +package storage + +import ( + "context" + "time" +) + +type AnalysisStateName string + +const ( + AnalysisStateScanning AnalysisStateName = "scanning" + AnalysisStateReady AnalysisStateName = "ready" + AnalysisStateFailed AnalysisStateName = "failed" +) + +type SourceStateName string + +const ( + SourceStatePending SourceStateName = "pending" + SourceStateScanning SourceStateName = "scanning" + SourceStateReady SourceStateName = "ready" + SourceStateFailed SourceStateName = "failed" +) + +const ( + StorageSourceWorkspaces = "workspaces" + StorageSourceGoCache = "go_cache" + StorageSourceQuarantine = "quarantine" + StorageSourceTemporaryArtifacts = "temporary_artifacts" + StorageSourceDocker = "docker" +) + +var storageAnalysisSources = [...]string{ + StorageSourceWorkspaces, + StorageSourceGoCache, + StorageSourceQuarantine, + StorageSourceTemporaryArtifacts, + StorageSourceDocker, +} + +type StorageSourceProgress struct { + State SourceStateName `json:"state"` + CompletedItems int `json:"completed_items"` + TotalItems *int `json:"total_items,omitempty"` + BytesScanned int64 `json:"bytes_scanned"` + Error *string `json:"error,omitempty"` +} + +type StorageAnalysisProgress struct { + CompletedSources int `json:"completed_sources"` + TotalSources int `json:"total_sources"` + Sources map[string]StorageSourceProgress `json:"sources"` +} + +type StorageAnalysisState struct { + Generation uint64 `json:"generation"` + State AnalysisStateName `json:"state"` + StartedAt *time.Time `json:"started_at"` + CompletedAt *time.Time `json:"completed_at"` + DurationMS *int64 `json:"duration_ms"` + CacheTTLSeconds int64 `json:"cache_ttl_seconds"` + RefreshDueAt *time.Time `json:"refresh_due_at"` + Stale bool `json:"stale"` + Error *string `json:"error"` + Progress StorageAnalysisProgress `json:"progress"` + PartialSummary *Summary `json:"partial_summary"` +} + +type OverviewRead struct { + Snapshot *OverviewSnapshot + Analysis StorageAnalysisState +} + +type StorageAnalysisUpdated struct { + Generation uint64 `json:"generation"` + State AnalysisStateName `json:"state"` +} + +type StorageAnalysisCompletion struct { + Generation uint64 + Duration time.Duration + SourceDurations map[string]time.Duration + SourceStates map[string]SourceStateName + PartitionCount int + MaxActiveWalkers int + Succeeded bool +} + +type OverviewCacheOptions struct { + Publisher func(StorageAnalysisUpdated) + Observer func(StorageAnalysisCompletion) +} + +type OverviewProgress struct { + Source string + State SourceStateName + CompletedItems int + TotalItems *int + BytesScanned int64 + Value any + Err error + Duration time.Duration + PartitionCount int + MaxActiveWalkers int +} + +type OverviewProgressCallback func(OverviewProgress) + +type ProgressiveOverviewProvider interface { + SummaryWithProgress(context.Context, OverviewProgressCallback) (Summary, error) +} diff --git a/apps/backend/internal/system/storage/filescan/goleak_test.go b/apps/backend/internal/system/storage/filescan/goleak_test.go new file mode 100644 index 0000000000..8b31fa777f --- /dev/null +++ b/apps/backend/internal/system/storage/filescan/goleak_test.go @@ -0,0 +1,11 @@ +package filescan + +import ( + "testing" + + "go.uber.org/goleak" +) + +func TestMain(m *testing.M) { + goleak.VerifyTestMain(m) +} diff --git a/apps/backend/internal/system/storage/filescan/measure.go b/apps/backend/internal/system/storage/filescan/measure.go new file mode 100644 index 0000000000..54d0ccf285 --- /dev/null +++ b/apps/backend/internal/system/storage/filescan/measure.go @@ -0,0 +1,354 @@ +// Package filescan provides bounded, read-only filesystem measurements. +package filescan + +import ( + "context" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "sync" +) + +type SymlinkPolicy uint8 + +const ( + SkipSymlinks SymlinkPolicy = iota + RejectSymlinks +) + +type Root struct { + Path string + SymlinkPolicy SymlinkPolicy + MissingOK bool + Exclude func(string, fs.DirEntry) bool +} + +type ProgressPhase string + +const ( + PartitionStarted ProgressPhase = "partition_started" + PartitionCompleted ProgressPhase = "partition_completed" + RootCompleted ProgressPhase = "root_completed" +) + +type Progress struct { + Phase ProgressPhase + RootIndex int + PartitionIndex int + CompletedPartitions int + TotalPartitions int + CompletedRoots int + TotalRoots int + BytesScanned int64 +} + +type Result struct { + Bytes int64 + Err error +} + +type Limiter struct { + maxPartitions int + slots chan struct{} +} + +func NewLimiter(maxPartitions int) *Limiter { + if maxPartitions <= 0 { + maxPartitions = 4 + } + return &Limiter{maxPartitions: maxPartitions, slots: make(chan struct{}, maxPartitions)} +} + +type partition struct { + rootIndex int + partitionIndex int + root Root + path string +} + +type rootPlan struct { + root Root + partitions []partition + err error +} + +type partitionResult struct { + bytes int64 + err error +} + +type progressTracker struct { + mu sync.Mutex + notifyMu sync.Mutex + completedPartitions int + completedRoots int + bytesScanned int64 + rootPartitions []int + rootCompleted []int + totalPartitions int + totalRoots int + notify func(Progress) +} + +func (l *Limiter) Measure(ctx context.Context, roots []Root, notify func(Progress)) []Result { + if l == nil { + l = NewLimiter(4) + } + plans := make([]rootPlan, len(roots)) + partitions := make([]partition, 0) + rootPartitionCounts := make([]int, len(roots)) + for index, root := range roots { + planned, err := planRoot(ctx, index, root) + plans[index] = rootPlan{root: root, partitions: planned, err: err} + if err == nil { + rootPartitionCounts[index] = len(planned) + partitions = append(partitions, planned...) + } + } + tracker := &progressTracker{ + rootPartitions: rootPartitionCounts, + rootCompleted: make([]int, len(roots)), + totalPartitions: len(partitions), + totalRoots: len(roots), + notify: notify, + } + results := make([]Result, len(roots)) + partitionResults := make([][]partitionResult, len(roots)) + for index, plan := range plans { + partitionResults[index] = make([]partitionResult, len(plan.partitions)) + if plan.err != nil { + results[index].Err = plan.err + tracker.completeRoot(index) + } else if len(plan.partitions) == 0 { + tracker.completeRoot(index) + } + } + if len(partitions) > 0 { + l.measurePartitions(ctx, partitions, partitionResults, tracker) + } + for index, plan := range plans { + if plan.err != nil { + continue + } + var errs []error + for _, measured := range partitionResults[index] { + if measured.err != nil { + errs = append(errs, measured.err) + continue + } + results[index].Bytes += measured.bytes + } + results[index].Err = errors.Join(errs...) + } + return results +} + +func (l *Limiter) measurePartitions( + ctx context.Context, + partitions []partition, + partitionResults [][]partitionResult, + tracker *progressTracker, +) { + workerCount := l.maxPartitions + if workerCount > len(partitions) { + workerCount = len(partitions) + } + jobs := make(chan partition, len(partitions)) + for _, item := range partitions { + jobs <- item + } + close(jobs) + var workers sync.WaitGroup + workers.Add(workerCount) + for range workerCount { + go func() { + defer workers.Done() + for item := range jobs { + measured := l.measurePartition(ctx, item, tracker) + partitionResults[item.rootIndex][item.partitionIndex] = measured + } + }() + } + workers.Wait() +} + +func (l *Limiter) measurePartition(ctx context.Context, item partition, tracker *progressTracker) partitionResult { + if err := l.acquire(ctx); err != nil { + tracker.partitionCompleted(item, 0, err) + return partitionResult{err: err} + } + tracker.partitionStarted(item) + bytes, err := walkPartition(ctx, item.root, item.path) + tracker.partitionCompleted(item, bytes, err) + l.release() + return partitionResult{bytes: bytes, err: err} +} + +func (l *Limiter) acquire(ctx context.Context) error { + select { + case l.slots <- struct{}{}: + return nil + case <-ctx.Done(): + return ctx.Err() + } +} + +func (l *Limiter) release() { + <-l.slots +} + +func planRoot(ctx context.Context, rootIndex int, root Root) ([]partition, error) { + if err := ctx.Err(); err != nil { + return nil, err + } + info, err := os.Lstat(root.Path) + if errors.Is(err, os.ErrNotExist) && root.MissingOK { + return nil, nil + } + if err != nil { + return nil, err + } + if info.Mode()&os.ModeSymlink != 0 { + if root.SymlinkPolicy == SkipSymlinks { + return nil, nil + } + return nil, fmt.Errorf("symlink found at %s", root.Path) + } + if !info.IsDir() { + return []partition{{rootIndex: rootIndex, root: root, path: root.Path}}, nil + } + return planDirectory(ctx, rootIndex, root) +} + +func planDirectory(ctx context.Context, rootIndex int, root Root) ([]partition, error) { + entries, err := os.ReadDir(root.Path) + if err != nil { + return nil, err + } + partitions := make([]partition, 0, len(entries)) + for _, entry := range entries { + if err := ctx.Err(); err != nil { + return nil, err + } + path := filepath.Join(root.Path, entry.Name()) + if root.Exclude != nil && root.Exclude(path, entry) { + continue + } + if entry.Type()&os.ModeSymlink != 0 && root.SymlinkPolicy == SkipSymlinks { + continue + } + partitions = append(partitions, partition{ + rootIndex: rootIndex, partitionIndex: len(partitions), root: root, path: path, + }) + } + if len(partitions) == 0 { + partitions = append(partitions, partition{rootIndex: rootIndex, root: root, path: root.Path}) + } + return partitions, nil +} + +func walkPartition(ctx context.Context, root Root, path string) (int64, error) { + var total int64 + err := filepath.WalkDir(path, func(path string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + if err := ctx.Err(); err != nil { + return err + } + if root.Exclude != nil && root.Exclude(path, entry) { + if entry.IsDir() { + return fs.SkipDir + } + return nil + } + if entry.Type()&os.ModeSymlink != 0 { + if root.SymlinkPolicy == SkipSymlinks { + return nil + } + return fmt.Errorf("symlink found at %s", path) + } + if !entry.Type().IsRegular() { + return nil + } + if err := ctx.Err(); err != nil { + return err + } + info, err := entry.Info() + if err != nil { + return err + } + total += info.Size() + return nil + }) + if err != nil { + return 0, err + } + return total, nil +} + +func (t *progressTracker) partitionStarted(item partition) { + t.mu.Lock() + event := t.progressLocked(Progress{ + Phase: PartitionStarted, RootIndex: item.rootIndex, PartitionIndex: item.partitionIndex, + }) + t.mu.Unlock() + t.emitEvent(event) +} + +func (t *progressTracker) partitionCompleted(item partition, bytes int64, err error) { + t.notifyMu.Lock() + defer t.notifyMu.Unlock() + t.mu.Lock() + t.completedPartitions++ + if err == nil { + t.bytesScanned += bytes + } + t.rootCompleted[item.rootIndex]++ + rootDone := t.rootCompleted[item.rootIndex] == t.rootPartitions[item.rootIndex] + event := t.progressLocked(Progress{ + Phase: PartitionCompleted, RootIndex: item.rootIndex, PartitionIndex: item.partitionIndex, + }) + if rootDone { + t.completedRoots++ + } + var rootEvent *Progress + if rootDone { + event := t.progressLocked(Progress{ + Phase: RootCompleted, RootIndex: item.rootIndex, PartitionIndex: item.partitionIndex, + }) + rootEvent = &event + } + t.mu.Unlock() + t.emitEvent(event) + if rootEvent != nil { + t.emitEvent(*rootEvent) + } +} + +func (t *progressTracker) completeRoot(rootIndex int) { + t.notifyMu.Lock() + defer t.notifyMu.Unlock() + t.mu.Lock() + t.completedRoots++ + event := t.progressLocked(Progress{Phase: RootCompleted, RootIndex: rootIndex}) + t.mu.Unlock() + t.emitEvent(event) +} + +func (t *progressTracker) progressLocked(event Progress) Progress { + event.CompletedPartitions = t.completedPartitions + event.TotalPartitions = t.totalPartitions + event.CompletedRoots = t.completedRoots + event.TotalRoots = t.totalRoots + event.BytesScanned = t.bytesScanned + return event +} + +func (t *progressTracker) emitEvent(event Progress) { + if t.notify != nil { + t.notify(event) + } +} diff --git a/apps/backend/internal/system/storage/filescan/measure_test.go b/apps/backend/internal/system/storage/filescan/measure_test.go new file mode 100644 index 0000000000..a9867f8080 --- /dev/null +++ b/apps/backend/internal/system/storage/filescan/measure_test.go @@ -0,0 +1,225 @@ +package filescan + +import ( + "context" + "errors" + "os" + "path/filepath" + "sync" + "sync/atomic" + "testing" + "time" +) + +func TestMeasureUsesBoundedConcurrentPartitionsAndIndexedResults(t *testing.T) { + root := t.TempDir() + for index, contents := range []string{"one", "two", "three", "four", "five"} { + partition := filepath.Join(root, string(rune('a'+index))) + if err := os.Mkdir(partition, 0o700); err != nil { + t.Fatalf("Mkdir(%s): %v", partition, err) + } + if err := os.WriteFile(filepath.Join(partition, "data"), []byte(contents), 0o600); err != nil { + t.Fatalf("WriteFile(%s): %v", partition, err) + } + } + + var active atomic.Int32 + var maxActive atomic.Int32 + var started atomic.Int32 + release := make(chan struct{}) + var releaseOnce atomic.Bool + progress := func(event Progress) { + if event.Phase == PartitionStarted { + current := active.Add(1) + for { + previous := maxActive.Load() + if current <= previous || maxActive.CompareAndSwap(previous, current) { + break + } + } + if started.Add(1) == 2 && releaseOnce.CompareAndSwap(false, true) { + close(release) + } + <-release + } + if event.Phase == PartitionCompleted { + active.Add(-1) + } + } + + results := NewLimiter(2).Measure(context.Background(), []Root{{Path: root}}, progress) + if len(results) != 1 { + t.Fatalf("result count = %d, want one root result", len(results)) + } + if results[0].Err != nil { + t.Fatalf("root measurement error = %v", results[0].Err) + } + if results[0].Bytes != int64(len("one"+"two"+"three"+"four"+"five")) { + t.Fatalf("root bytes = %d, want all partition bytes", results[0].Bytes) + } + if maxActive.Load() != 2 { + t.Fatalf("max active partitions = %d, want limiter ceiling 2", maxActive.Load()) + } +} + +func TestMeasurePreservesRootOptionsAndProgressOrder(t *testing.T) { + root := t.TempDir() + if err := os.WriteFile(filepath.Join(root, "included"), []byte("included"), 0o600); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(root, "excluded"), []byte("excluded"), 0o600); err != nil { + t.Fatal(err) + } + if err := os.Symlink(filepath.Join(root, "included"), filepath.Join(root, "link")); err != nil { + t.Fatal(err) + } + + var events []Progress + results := NewLimiter(1).Measure(context.Background(), []Root{{ + Path: root, + SymlinkPolicy: SkipSymlinks, + Exclude: func(path string, _ os.DirEntry) bool { + return filepath.Base(path) == "excluded" + }, + }}, func(event Progress) { + events = append(events, event) + }) + if len(results) != 1 { + t.Fatalf("result count = %d, want one root result", len(results)) + } + if results[0].Err != nil { + t.Fatalf("root measurement error = %v", results[0].Err) + } + if results[0].Bytes != int64(len("included")) { + t.Fatalf("root bytes = %d, want included file only", results[0].Bytes) + } + if len(events) == 0 || events[len(events)-1].Phase != RootCompleted { + t.Fatalf("last progress event = %#v, want root completion", events) + } + if events[len(events)-1].CompletedRoots != 1 || events[len(events)-1].TotalRoots != 1 { + t.Fatalf("root progress = %#v, want 1/1", events[len(events)-1]) + } +} + +func TestMeasureRejectsSymlinkAndSupportsMissingRoots(t *testing.T) { + root := t.TempDir() + target := filepath.Join(t.TempDir(), "target") + if err := os.WriteFile(target, []byte("target"), 0o600); err != nil { + t.Fatal(err) + } + link := filepath.Join(root, "link") + if err := os.Symlink(target, link); err != nil { + t.Fatal(err) + } + + results := NewLimiter(1).Measure(context.Background(), []Root{{ + Path: root, + SymlinkPolicy: RejectSymlinks, + }}, nil) + if len(results) != 1 { + t.Fatalf("result count = %d, want one root result", len(results)) + } + if results[0].Err == nil { + t.Fatal("symlink measurement succeeded, want an error") + } + + missing := NewLimiter(1).Measure(context.Background(), []Root{{Path: filepath.Join(root, "missing"), MissingOK: true}}, nil) + if len(missing) != 1 { + t.Fatalf("missing result count = %d, want one root result", len(missing)) + } + if missing[0].Err != nil || missing[0].Bytes != 0 { + t.Fatalf("missing root result = %#v, want empty successful result", missing[0]) + } + + cancelled, cancel := context.WithCancel(context.Background()) + cancel() + results = NewLimiter(1).Measure(cancelled, []Root{{Path: root}}, nil) + if len(results) != 1 { + t.Fatalf("cancelled result count = %d, want one root result", len(results)) + } + if !errors.Is(results[0].Err, context.Canceled) { + t.Fatalf("cancelled measurement error = %v, want context.Canceled", results[0].Err) + } +} + +func TestProgressTrackerNotifiesInSnapshotOrder(t *testing.T) { + var ( + events []Progress + eventsMu sync.Mutex + firstCallbackStarted = make(chan struct{}) + secondCallbackStarted = make(chan struct{}) + done = make(chan struct{}, 2) + ) + tracker := &progressTracker{ + rootPartitions: []int{2}, + rootCompleted: []int{0}, + totalPartitions: 2, + totalRoots: 1, + notify: func(event Progress) { + if event.Phase != PartitionCompleted { + return + } + if event.PartitionIndex == 0 { + close(firstCallbackStarted) + select { + case <-secondCallbackStarted: + case <-time.After(250 * time.Millisecond): + } + } + if event.PartitionIndex == 1 { + close(secondCallbackStarted) + } + eventsMu.Lock() + events = append(events, event) + eventsMu.Unlock() + }, + } + + go func() { + tracker.partitionCompleted(partition{rootIndex: 0, partitionIndex: 0}, 1, nil) + done <- struct{}{} + }() + select { + case <-firstCallbackStarted: + case <-time.After(time.Second): + t.Fatal("first progress callback did not start") + } + go func() { + tracker.partitionCompleted(partition{rootIndex: 0, partitionIndex: 1}, 1, nil) + done <- struct{}{} + }() + for range 2 { + select { + case <-done: + case <-time.After(time.Second): + t.Fatal("partition completion did not finish") + } + } + + eventsMu.Lock() + defer eventsMu.Unlock() + if len(events) != 2 || events[0].PartitionIndex != 0 || events[1].PartitionIndex != 1 { + t.Fatalf("progress events = %#v, want partition order 0 then 1", events) + } +} + +func BenchmarkMeasureTrees(b *testing.B) { + root := b.TempDir() + for index := 0; index < 8; index++ { + partition := filepath.Join(root, string(rune('a'+index))) + if err := os.Mkdir(partition, 0o700); err != nil { + b.Fatal(err) + } + if err := os.WriteFile(filepath.Join(partition, "data"), []byte("benchmark"), 0o600); err != nil { + b.Fatal(err) + } + } + roots := []Root{{Path: root}} + b.ResetTimer() + for i := 0; i < b.N; i++ { + results := NewLimiter(4).Measure(context.Background(), roots, nil) + if results[0].Err != nil { + b.Fatal(results[0].Err) + } + } +} diff --git a/apps/backend/internal/system/storage/gocache/analysis_scanner_test.go b/apps/backend/internal/system/storage/gocache/analysis_scanner_test.go new file mode 100644 index 0000000000..e2cc9a3aa5 --- /dev/null +++ b/apps/backend/internal/system/storage/gocache/analysis_scanner_test.go @@ -0,0 +1,88 @@ +package gocache + +import ( + "context" + "os" + "path/filepath" + "sync" + "sync/atomic" + "testing" + + "github.com/kandev/kandev/internal/system/storage" + "github.com/kandev/kandev/internal/system/storage/filescan" +) + +func TestAnalyzeUsesConfiguredBoundedScanner(t *testing.T) { + home := t.TempDir() + settings := storage.DefaultSettings() + settings.GoCache.Enabled = true + provider := New(Config{ + HomeDir: home, TrashDir: filepath.Join(home, "trash"), + Settings: staticSettings{settings: settings}, + }) + env, err := provider.ExecutionEnvironment(context.Background()) + if err != nil { + t.Fatalf("ExecutionEnvironment: %v", err) + } + t.Setenv("GOCACHE", env["GOCACHE"]) + if err := os.WriteFile(filepath.Join(env["GOCACHE"], "artifact"), []byte("cache"), 0o600); err != nil { + t.Fatal(err) + } + var completed atomic.Int32 + provider.config.Scanner = filescan.NewLimiter(1) + provider.config.OnProgress = func(progress filescan.Progress) { + if progress.Phase == filescan.RootCompleted { + completed.Add(1) + } + } + + if _, err := provider.Analyze(context.Background()); err != nil { + t.Fatalf("Analyze: %v", err) + } + if completed.Load() != 1 { + t.Fatalf("completed roots = %d, want one managed-cache root", completed.Load()) + } +} + +func TestAnalyzeKeepsProgressMonotonicAcrossManagedAndUnmanagedCaches(t *testing.T) { + home := t.TempDir() + unmanagedPath := filepath.Join(t.TempDir(), "go-build") + if err := os.MkdirAll(unmanagedPath, 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(unmanagedPath, "unmanaged"), []byte("unmanaged"), 0o600); err != nil { + t.Fatal(err) + } + t.Setenv("GOCACHE", unmanagedPath) + settings := storage.DefaultSettings() + settings.GoCache.Enabled = true + provider := New(Config{ + HomeDir: home, TrashDir: filepath.Join(home, "trash"), + Settings: staticSettings{settings: settings}, Scanner: filescan.NewLimiter(1), + }) + env, err := provider.ExecutionEnvironment(context.Background()) + if err != nil { + t.Fatalf("ExecutionEnvironment: %v", err) + } + if err := os.WriteFile(filepath.Join(env["GOCACHE"], "managed"), []byte("managed"), 0o600); err != nil { + t.Fatal(err) + } + var progressMu sync.Mutex + var bytesScanned []int64 + provider.config.OnProgress = func(progress filescan.Progress) { + progressMu.Lock() + bytesScanned = append(bytesScanned, progress.BytesScanned) + progressMu.Unlock() + } + + if _, err := provider.Analyze(context.Background()); err != nil { + t.Fatalf("Analyze: %v", err) + } + progressMu.Lock() + defer progressMu.Unlock() + for index := 1; index < len(bytesScanned); index++ { + if bytesScanned[index] < bytesScanned[index-1] { + t.Fatalf("progress bytes regressed at %d: %v", index, bytesScanned) + } + } +} diff --git a/apps/backend/internal/system/storage/gocache/provider.go b/apps/backend/internal/system/storage/gocache/provider.go index a24834d52b..24db4650e5 100644 --- a/apps/backend/internal/system/storage/gocache/provider.go +++ b/apps/backend/internal/system/storage/gocache/provider.go @@ -13,6 +13,7 @@ import ( "github.com/google/uuid" "github.com/kandev/kandev/internal/system/storage" + "github.com/kandev/kandev/internal/system/storage/filescan" ) var ( @@ -40,10 +41,12 @@ type QuarantineStore interface { // Config contains the provider's install-owned paths and persistence dependencies. type Config struct { - HomeDir string - TrashDir string - Settings SettingsSource - Store QuarantineStore + HomeDir string + TrashDir string + Settings SettingsSource + Store QuarantineStore + Scanner *filescan.Limiter + OnProgress func(filescan.Progress) } // Provider manages the single Go cache selected by persisted settings. @@ -118,24 +121,52 @@ func (p *Provider) Analyze(ctx context.Context) (Analysis, error) { return Analysis{}, err } owned := adopted || hasValidMarker(cachePath) - size, err := directorySize(cachePath) - if err != nil { - return Analysis{}, err + scanner := p.config.Scanner + if scanner == nil { + scanner = filescan.NewLimiter(4) } - analysis := Analysis{Path: cachePath, SizeBytes: size, Owned: owned, Enabled: settings.GoCache.Enabled} - unmanagedPath, ok := defaultGoCachePath() - if !ok || unmanagedPath == cachePath { + measurementRoots := []filescan.Root{ + { + Path: cachePath, MissingOK: true, SymlinkPolicy: filescan.RejectSymlinks, + Exclude: func(path string, _ fs.DirEntry) bool { return path == markerPath(cachePath) }, + }, + } + unmanagedPath, hasUnmanagedPath := defaultGoCachePath() + if hasUnmanagedPath && unmanagedPath != cachePath { + measurementRoots = append(measurementRoots, filescan.Root{ + Path: unmanagedPath, MissingOK: true, SymlinkPolicy: filescan.SkipSymlinks, + }) + } + measurements := scanner.Measure(ctx, measurementRoots, p.config.OnProgress) + if len(measurements) != len(measurementRoots) { + return Analysis{}, errors.New("go-cache scanner returned an invalid result") + } + if err := measurements[0].Err; err != nil { + return Analysis{}, fmt.Errorf("measure Go cache: %w", err) + } + analysis := Analysis{ + Path: cachePath, SizeBytes: measurements[0].Bytes, Owned: owned, Enabled: settings.GoCache.Enabled, + } + if !hasUnmanagedPath || unmanagedPath == cachePath { return analysis, nil } - unmanagedSize, err := directorySizeNoFollow(unmanagedPath) - if err != nil { - return Analysis{}, err + if err := measurements[1].Err; err != nil { + return Analysis{}, fmt.Errorf("measure Go cache: %w", err) } analysis.UnmanagedPath = unmanagedPath - analysis.UnmanagedSizeBytes = unmanagedSize + analysis.UnmanagedSizeBytes = measurements[1].Bytes return analysis, nil } +func (p *Provider) AnalyzeWithProgress( + ctx context.Context, + onProgress func(filescan.Progress), +) (Analysis, error) { + copy := *p + copy.config.OnProgress = onProgress + return copy.Analyze(ctx) +} + func defaultGoCachePath() (string, bool) { if configured := os.Getenv("GOCACHE"); configured != "" { if configured == "off" || !filepath.IsAbs(configured) { diff --git a/apps/backend/internal/system/storage/handler.go b/apps/backend/internal/system/storage/handler.go index eb0877a3ee..6eddf9bc6a 100644 --- a/apps/backend/internal/system/storage/handler.go +++ b/apps/backend/internal/system/storage/handler.go @@ -81,6 +81,10 @@ type OverviewReader interface { SettingsCapabilities(context.Context, StorageMaintenanceSettings) Capabilities } +type OverviewStateReader interface { + Read(context.Context) (OverviewRead, error) +} + type HandlerConfig struct { Settings SettingsManager Runs RunLister @@ -287,10 +291,25 @@ func (h *Handler) getStorage(c *gin.Context) { c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to load storage settings"}) return } - snapshot, err := h.config.Overview.Get(c.Request.Context()) - if err != nil { - c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) - return + var ( + snapshot *OverviewSnapshot + analysis StorageAnalysisState + ) + if stateReader, ok := h.config.Overview.(OverviewStateReader); ok { + read, readErr := stateReader.Read(c.Request.Context()) + if readErr != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": readErr.Error()}) + return + } + snapshot, analysis = read.Snapshot, read.Analysis + } else { + legacy, readErr := h.config.Overview.Get(c.Request.Context()) + if readErr != nil { + c.JSON(http.StatusInternalServerError, gin.H{"error": readErr.Error()}) + return + } + snapshot = &legacy + analysis = readyAnalysisState(0, defaultOverviewCacheTTL, legacy.AnalyzedAt, legacy.AnalyzedAt, legacy.AnalyzedAt) } runs, err := h.config.Runs.ListRuns(c.Request.Context(), 1) if err != nil { @@ -301,9 +320,14 @@ func (h *Handler) getStorage(c *gin.Context) { if len(runs) > 0 { lastRun = &runs[0] } + var summary any + var analyzedAt any + if snapshot != nil { + summary, analyzedAt = snapshot.Summary, snapshot.AnalyzedAt + } c.JSON(http.StatusOK, gin.H{ "settings": settings, "capabilities": h.config.Overview.Capabilities(c.Request.Context(), settings), - "summary": snapshot.Summary, "analyzed_at": snapshot.AnalyzedAt, "last_run": lastRun, + "summary": summary, "analyzed_at": analyzedAt, "analysis": analysis, "last_run": lastRun, }) } diff --git a/apps/backend/internal/system/storage/handler_test.go b/apps/backend/internal/system/storage/handler_test.go index 32d28e1ca4..f0355b99a9 100644 --- a/apps/backend/internal/system/storage/handler_test.go +++ b/apps/backend/internal/system/storage/handler_test.go @@ -85,6 +85,45 @@ func TestGetStorageReturnsSnapshotAnalyzedAt(t *testing.T) { } } +func TestGetStorageReturnsBeforeColdOverviewScanCompletes(t *testing.T) { + gin.SetMode(gin.TestMode) + provider := newProgressiveOverview() + cache := NewOverviewCache(provider) + router := newTestRouter(NewHandler(HandlerConfig{ + Settings: staticSettingsManager{}, Runs: staticRunLister{}, Overview: cache, + })) + + responseCh := make(chan *httptest.ResponseRecorder, 1) + go func() { + response := httptest.NewRecorder() + router.ServeHTTP(response, httptest.NewRequest(http.MethodGet, "/api/v1/system/storage", nil)) + responseCh <- response + }() + <-provider.started + + var response *httptest.ResponseRecorder + select { + case response = <-responseCh: + case <-time.After(100 * time.Millisecond): + close(provider.release) + t.Fatal("storage overview request waited for the cold scan") + } + close(provider.release) + if response.Code != http.StatusOK { + t.Fatalf("status = %d, want 200", response.Code) + } + var body struct { + Summary *Summary `json:"summary"` + Analysis StorageAnalysisState `json:"analysis"` + } + if err := json.Unmarshal(response.Body.Bytes(), &body); err != nil { + t.Fatalf("decode response: %v", err) + } + if body.Summary != nil || body.Analysis.State != AnalysisStateScanning { + t.Fatalf("cold response = %#v, want scanning state without summary", body) + } +} + func TestGetStorageDiskReturnsIndependentCapacityResponse(t *testing.T) { gin.SetMode(gin.TestMode) router := newTestRouter(NewHandler(HandlerConfig{})) diff --git a/apps/backend/internal/system/storage/metrics.go b/apps/backend/internal/system/storage/metrics.go new file mode 100644 index 0000000000..0c030a1e37 --- /dev/null +++ b/apps/backend/internal/system/storage/metrics.go @@ -0,0 +1,53 @@ +package storage + +import ( + "expvar" + "strconv" + "time" +) + +// Storage analysis metrics are exposed through the stdlib /debug/vars +// endpoint in development mode. Duration maps use one bucket per observation; +// this keeps the expvar contract useful without introducing a second metrics +// registry for a process-local cache. +var ( + storageAnalysisScansStartedTotal = expvar.NewInt("storage_analysis_scans_started_total") + storageAnalysisScansJoinedTotal = expvar.NewInt("storage_analysis_scans_joined_total") + storageAnalysisScansCompletedTotal = expvar.NewInt("storage_analysis_scans_completed_total") + storageAnalysisScansFailedTotal = expvar.NewInt("storage_analysis_scans_failed_total") + storageAnalysisDurationBucketTotal = expvar.NewMap("storage_analysis_duration_bucket_total") + storageAnalysisSourceDurationBucketTotal = expvar.NewMap( + "storage_analysis_source_duration_bucket_total", + ) +) + +func recordStorageAnalysisStarted() { + storageAnalysisScansStartedTotal.Add(1) +} + +func recordStorageAnalysisJoined() { + storageAnalysisScansJoinedTotal.Add(1) +} + +func recordStorageAnalysisCompleted(completion StorageAnalysisCompletion) { + storageAnalysisScansCompletedTotal.Add(1) + if !completion.Succeeded { + storageAnalysisScansFailedTotal.Add(1) + } + storageAnalysisDurationBucketTotal.Add(durationBucket(completion.Duration), 1) + for source, duration := range completion.SourceDurations { + storageAnalysisSourceDurationBucketTotal.Add( + "source="+source+";bucket="+durationBucket(duration), 1, + ) + } +} + +func durationBucket(duration time.Duration) string { + milliseconds := duration.Milliseconds() + for _, boundary := range []int64{10, 50, 100, 500, 1000, 5000, 30000, 60000} { + if milliseconds <= boundary { + return "le_" + strconv.FormatInt(boundary, 10) + "ms" + } + } + return "gt_60000ms" +} diff --git a/apps/backend/internal/system/storage/overview_cache.go b/apps/backend/internal/system/storage/overview_cache.go index 6efd058283..52cc5e8f19 100644 --- a/apps/backend/internal/system/storage/overview_cache.go +++ b/apps/backend/internal/system/storage/overview_cache.go @@ -6,7 +6,10 @@ import ( "time" ) -const defaultOverviewCacheTTL = 15 * time.Minute +const ( + defaultOverviewCacheTTL = 15 * time.Minute + progressPublishInterval = 250 * time.Millisecond +) // OverviewSnapshot is a successful storage overview and the time it was measured. type OverviewSnapshot struct { @@ -18,43 +21,94 @@ type OverviewInvalidator interface { Invalidate() } -// OverviewCache keeps one process-local successful overview snapshot. +// OverviewCache keeps one process-local successful overview snapshot and its active scan state. type OverviewCache struct { - provider OverviewProvider - ttl time.Duration - now func() time.Time + provider OverviewProvider + ttl time.Duration + now func() time.Time + publisher func(StorageAnalysisUpdated) + observer func(StorageAnalysisCompletion) mu sync.Mutex snapshot *OverviewSnapshot flight *overviewFlight + analysis StorageAnalysisState generation uint64 } type overviewFlight struct { - done chan struct{} - snapshot OverviewSnapshot - err error - generation uint64 + done chan struct{} + snapshot OverviewSnapshot + err error + generation uint64 + startedAt time.Time + partialValues map[string]any + sourceStarted map[string]time.Time + sourceDurations map[string]time.Duration + sourceStates map[string]SourceStateName + partitionCount int + maxActiveWalkers int + lastPublished time.Time } func NewOverviewCache(provider OverviewProvider) *OverviewCache { - return &OverviewCache{provider: provider, ttl: defaultOverviewCacheTTL, now: time.Now} + return NewOverviewCacheWithOptions(provider, OverviewCacheOptions{}) +} + +func NewOverviewCacheWithPublisher( + provider OverviewProvider, + publisher func(StorageAnalysisUpdated), +) *OverviewCache { + return NewOverviewCacheWithOptions(provider, OverviewCacheOptions{Publisher: publisher}) +} + +func NewOverviewCacheWithOptions(provider OverviewProvider, options OverviewCacheOptions) *OverviewCache { + cache := &OverviewCache{ + provider: provider, ttl: defaultOverviewCacheTTL, now: time.Now, + publisher: options.Publisher, observer: options.Observer, + } + cache.analysis = newAnalysisState(0, cache.ttl) + return cache +} + +// Read returns the latest snapshot and starts a missing or expired scan in the background. +func (c *OverviewCache) Read(ctx context.Context) (OverviewRead, error) { + if err := ctx.Err(); err != nil { + return OverviewRead{}, err + } + c.mu.Lock() + var flight *overviewFlight + if !c.snapshotFreshLocked() && c.flight == nil && c.shouldStartBackgroundLocked() { + flight = c.startRefreshLocked() + } + if flight == nil && !c.snapshotFreshLocked() && c.flight != nil { + recordStorageAnalysisJoined() + } + read := c.readLocked() + c.mu.Unlock() + if flight != nil { + c.publishUpdate(flight.generation, AnalysisStateScanning) + go c.refresh(context.WithoutCancel(ctx), flight) + } + return read, nil } func (c *OverviewCache) Get(ctx context.Context) (OverviewSnapshot, error) { c.mu.Lock() - if c.snapshot != nil && c.now().Sub(c.snapshot.AnalyzedAt) < c.ttl { + if c.snapshotFreshLocked() { snapshot := *c.snapshot c.mu.Unlock() return snapshot, nil } if c.flight != nil { flight := c.flight + recordStorageAnalysisJoined() c.mu.Unlock() return waitForOverviewRefresh(ctx, flight) } flight := c.startRefreshLocked() c.mu.Unlock() + c.publishUpdate(flight.generation, AnalysisStateScanning) go c.refresh(context.WithoutCancel(ctx), flight) return waitForOverviewRefresh(ctx, flight) } @@ -64,13 +118,15 @@ func (c *OverviewCache) Refresh(ctx context.Context) (OverviewSnapshot, error) { c.mu.Lock() if c.flight != nil { flight := c.flight + recordStorageAnalysisJoined() c.mu.Unlock() return waitForOverviewRefresh(ctx, flight) } flight := c.startRefreshLocked() c.mu.Unlock() + c.publishUpdate(flight.generation, AnalysisStateScanning) c.refresh(ctx, flight) - return flight.snapshot, flight.err + return waitForOverviewRefresh(ctx, flight) } func (c *OverviewCache) Capabilities(ctx context.Context, settings StorageMaintenanceSettings) Capabilities { @@ -89,31 +145,223 @@ func (c *OverviewCache) Invalidate() { c.generation++ c.snapshot = nil c.flight = nil + c.analysis = newAnalysisState(c.generation, c.ttl) c.mu.Unlock() } func (c *OverviewCache) startRefreshLocked() *overviewFlight { - flight := &overviewFlight{done: make(chan struct{}), generation: c.generation} + c.generation++ + startedAt := c.now().UTC() + flight := &overviewFlight{ + done: make(chan struct{}), generation: c.generation, startedAt: startedAt, + partialValues: make(map[string]any), sourceStarted: make(map[string]time.Time), + sourceDurations: make(map[string]time.Duration), sourceStates: make(map[string]SourceStateName), + } c.flight = flight + c.analysis = scanningAnalysisState(c.generation, c.ttl, startedAt, c.snapshot) + recordStorageAnalysisStarted() return flight } +func (c *OverviewCache) shouldStartBackgroundLocked() bool { + return c.analysis.State != AnalysisStateFailed || c.analysis.Generation != c.generation +} + +func (c *OverviewCache) snapshotFreshLocked() bool { + return c.snapshot != nil && c.now().Sub(c.snapshot.AnalyzedAt) < c.ttl +} + +func (c *OverviewCache) readLocked() OverviewRead { + var snapshot *OverviewSnapshot + if c.snapshot != nil { + copy := *c.snapshot + snapshot = © + } + return OverviewRead{Snapshot: snapshot, Analysis: cloneAnalysisState(c.analysis)} +} + func (c *OverviewCache) refresh(ctx context.Context, flight *overviewFlight) { - summary, err := c.provider.Summary(ctx) - c.mu.Lock() - if err == nil { - snapshot := OverviewSnapshot{Summary: summary, AnalyzedAt: c.now().UTC()} - flight.snapshot = snapshot - if flight.generation == c.generation { - c.snapshot = &snapshot + var ( + summary Summary + err error + ) + if progressive, ok := c.provider.(ProgressiveOverviewProvider); ok { + summary, err = progressive.SummaryWithProgress(ctx, func(progress OverviewProgress) { + c.recordProgress(flight, progress) + }) + } else { + summary, err = c.provider.Summary(ctx) + if err == nil { + c.recordLegacyProgress(flight, summary) } } + + completedAt := c.now().UTC() + c.mu.Lock() + current := c.flight == flight && flight.generation == c.generation + var completion StorageAnalysisCompletion + if err == nil { + flight.snapshot = OverviewSnapshot{Summary: summary, AnalyzedAt: completedAt} + if current { + progress := cloneAnalysisProgress(c.analysis.Progress) + c.snapshot = &flight.snapshot + c.analysis = readyAnalysisStateWithProgress( + flight.generation, c.ttl, flight.startedAt, completedAt, flight.snapshot.AnalyzedAt, + progress, + ) + } + } else if current { + c.analysis = failedAnalysisState( + c.analysis, flight.startedAt, completedAt, err, c.snapshot != nil, + ) + } flight.err = err + completion = StorageAnalysisCompletion{ + Generation: flight.generation, + Duration: completedAt.Sub(flight.startedAt), + SourceDurations: cloneDurations(flight.sourceDurations), + SourceStates: cloneSourceStates(flight.sourceStates), + PartitionCount: flight.partitionCount, + MaxActiveWalkers: flight.maxActiveWalkers, + Succeeded: err == nil, + } if c.flight == flight { c.flight = nil } close(flight.done) c.mu.Unlock() + recordStorageAnalysisCompleted(completion) + if c.observer != nil { + c.observer(completion) + } + + if current { + state := AnalysisStateReady + if err != nil { + state = AnalysisStateFailed + } + c.publishUpdate(flight.generation, state) + } +} + +func (c *OverviewCache) recordLegacyProgress(flight *overviewFlight, summary Summary) { + for _, progress := range []OverviewProgress{ + {Source: StorageSourceWorkspaces, State: SourceStateReady, Value: summary.Workspaces}, + {Source: StorageSourceGoCache, State: SourceStateReady, Value: summary.GoCache}, + {Source: StorageSourceQuarantine, State: SourceStateReady, Value: summary.Quarantine}, + {Source: StorageSourceTemporaryArtifacts, State: SourceStateReady, Value: summary.TemporaryArtifacts}, + {Source: StorageSourceDocker, State: SourceStateReady, Value: summary.Docker}, + } { + c.recordProgress(flight, progress) + } +} + +func (c *OverviewCache) recordProgress(flight *overviewFlight, progress OverviewProgress) { + if progress.Source == "" { + return + } + c.mu.Lock() + if !c.isCurrentFlightLocked(flight) { + c.mu.Unlock() + return + } + source, ok := c.analysis.Progress.Sources[progress.Source] + if !ok { + c.mu.Unlock() + return + } + if progress.State != "" { + source.State = progress.State + } + now := c.now() + c.updateSourceProgressLocked(flight, progress, &source, now) + c.analysis.Progress.Sources[progress.Source] = source + c.updateFlightProgressLocked(flight, progress, source, now) + c.analysis.Progress.CompletedSources = completedSourceCount(c.analysis.Progress.Sources) + if progress.Value != nil { + flight.partialValues[progress.Source] = progress.Value + c.analysis.PartialSummary = summaryFromSourceValues(flight.partialValues) + } + shouldPublish := c.shouldPublishProgressLocked(flight, source.State == SourceStateReady || source.State == SourceStateFailed, now) + if shouldPublish { + flight.lastPublished = now + } + generation := c.analysis.Generation + c.mu.Unlock() + if shouldPublish { + c.publishUpdate(generation, AnalysisStateScanning) + } +} + +func (c *OverviewCache) isCurrentFlightLocked(flight *overviewFlight) bool { + return c.flight == flight && flight.generation == c.generation +} + +func (c *OverviewCache) updateSourceProgressLocked( + flight *overviewFlight, + progress OverviewProgress, + source *StorageSourceProgress, + now time.Time, +) { + if source.State == SourceStateScanning { + if _, started := flight.sourceStarted[progress.Source]; !started { + flight.sourceStarted[progress.Source] = now + } + } + if progress.CompletedItems > source.CompletedItems { + source.CompletedItems = progress.CompletedItems + } + if progress.TotalItems != nil { + total := *progress.TotalItems + if source.TotalItems == nil || total > *source.TotalItems { + source.TotalItems = &total + } + } + if progress.BytesScanned > source.BytesScanned { + source.BytesScanned = progress.BytesScanned + } + if progress.Err != nil { + errorText := progress.Err.Error() + source.Error = &errorText + source.State = SourceStateFailed + } +} + +func (c *OverviewCache) updateFlightProgressLocked( + flight *overviewFlight, + progress OverviewProgress, + source StorageSourceProgress, + now time.Time, +) { + if progress.PartitionCount > flight.partitionCount { + flight.partitionCount = progress.PartitionCount + } + if progress.MaxActiveWalkers > flight.maxActiveWalkers { + flight.maxActiveWalkers = progress.MaxActiveWalkers + } + if source.State != SourceStateReady && source.State != SourceStateFailed { + return + } + flight.sourceStates[progress.Source] = source.State + if progress.Duration > 0 { + flight.sourceDurations[progress.Source] = progress.Duration + } else if started, ok := flight.sourceStarted[progress.Source]; ok { + flight.sourceDurations[progress.Source] = now.Sub(started) + } +} + +func (c *OverviewCache) shouldPublishProgressLocked( + flight *overviewFlight, + terminal bool, + now time.Time, +) bool { + return terminal || now.Sub(flight.lastPublished) >= progressPublishInterval +} + +func (c *OverviewCache) publishUpdate(generation uint64, state AnalysisStateName) { + if c.publisher != nil { + c.publisher(StorageAnalysisUpdated{Generation: generation, State: state}) + } } func waitForOverviewRefresh(ctx context.Context, flight *overviewFlight) (OverviewSnapshot, error) { @@ -124,3 +372,172 @@ func waitForOverviewRefresh(ctx context.Context, flight *overviewFlight) (Overvi return OverviewSnapshot{}, ctx.Err() } } + +func newAnalysisState(generation uint64, ttl time.Duration) StorageAnalysisState { + sources := make(map[string]StorageSourceProgress, len(storageAnalysisSources)) + for _, source := range storageAnalysisSources { + sources[source] = StorageSourceProgress{State: SourceStatePending} + } + return StorageAnalysisState{ + Generation: generation, State: AnalysisStateReady, CacheTTLSeconds: int64(ttl / time.Second), + Progress: StorageAnalysisProgress{ + TotalSources: len(storageAnalysisSources), Sources: sources, + }, + } +} + +func scanningAnalysisState( + generation uint64, + ttl time.Duration, + startedAt time.Time, + previous *OverviewSnapshot, +) StorageAnalysisState { + state := newAnalysisState(generation, ttl) + state.State = AnalysisStateScanning + state.StartedAt = timePointer(startedAt) + state.Stale = previous != nil + if previous != nil { + state.RefreshDueAt = timePointer(previous.AnalyzedAt.Add(ttl)) + } + return state +} + +func readyAnalysisState( + generation uint64, + ttl time.Duration, + startedAt time.Time, + completedAt time.Time, + analyzedAt time.Time, +) StorageAnalysisState { + return readyAnalysisStateWithProgress( + generation, ttl, startedAt, completedAt, analyzedAt, StorageAnalysisProgress{}, + ) +} + +func readyAnalysisStateWithProgress( + generation uint64, + ttl time.Duration, + startedAt time.Time, + completedAt time.Time, + analyzedAt time.Time, + progress StorageAnalysisProgress, +) StorageAnalysisState { + state := newAnalysisState(generation, ttl) + state.State = AnalysisStateReady + state.StartedAt = timePointer(startedAt) + state.CompletedAt = timePointer(completedAt) + state.DurationMS = durationPointer(completedAt.Sub(startedAt)) + state.RefreshDueAt = timePointer(analyzedAt.Add(ttl)) + if len(progress.Sources) > 0 { + state.Progress = progress + } + for source, progress := range state.Progress.Sources { + if progress.State == SourceStatePending || progress.State == SourceStateScanning { + progress.State = SourceStateReady + state.Progress.Sources[source] = progress + } + } + state.Progress.CompletedSources = completedSourceCount(state.Progress.Sources) + return state +} + +func failedAnalysisState( + state StorageAnalysisState, + startedAt time.Time, + completedAt time.Time, + err error, + stale bool, +) StorageAnalysisState { + state.State = AnalysisStateFailed + state.StartedAt = timePointer(startedAt) + state.CompletedAt = timePointer(completedAt) + state.DurationMS = durationPointer(completedAt.Sub(startedAt)) + state.Stale = stale + errorText := err.Error() + state.Error = &errorText + if stale { + state.PartialSummary = nil + } + return state +} + +func completedSourceCount(sources map[string]StorageSourceProgress) int { + completed := 0 + for _, source := range sources { + if source.State == SourceStateReady || source.State == SourceStateFailed { + completed++ + } + } + return completed +} + +func summaryFromSourceValues(values map[string]any) *Summary { + if len(values) == 0 { + return nil + } + summary := &Summary{} + if value, ok := values[StorageSourceWorkspaces]; ok { + summary.Workspaces = value + } + if value, ok := values[StorageSourceGoCache]; ok { + summary.GoCache = value + } + if value, ok := values[StorageSourceQuarantine]; ok { + summary.Quarantine = value + } + if value, ok := values[StorageSourceTemporaryArtifacts]; ok { + summary.TemporaryArtifacts = value + } + if value, ok := values[StorageSourceDocker]; ok { + summary.Docker = value + } + return summary +} + +func cloneAnalysisState(state StorageAnalysisState) StorageAnalysisState { + clone := state + clone.Progress = cloneAnalysisProgress(state.Progress) + return clone +} + +func cloneAnalysisProgress(progressState StorageAnalysisProgress) StorageAnalysisProgress { + clone := progressState + clone.Sources = make(map[string]StorageSourceProgress, len(progressState.Sources)) + for source, progress := range progressState.Sources { + if progress.TotalItems != nil { + total := *progress.TotalItems + progress.TotalItems = &total + } + if progress.Error != nil { + errorText := *progress.Error + progress.Error = &errorText + } + clone.Sources[source] = progress + } + return clone +} + +func cloneDurations(values map[string]time.Duration) map[string]time.Duration { + clone := make(map[string]time.Duration, len(values)) + for key, value := range values { + clone[key] = value + } + return clone +} + +func cloneSourceStates(values map[string]SourceStateName) map[string]SourceStateName { + clone := make(map[string]SourceStateName, len(values)) + for key, value := range values { + clone[key] = value + } + return clone +} + +func timePointer(value time.Time) *time.Time { + return &value +} + +func durationPointer(value time.Duration) *int64 { + milliseconds := value.Milliseconds() + return &milliseconds +} diff --git a/apps/backend/internal/system/storage/overview_cache_progress_test.go b/apps/backend/internal/system/storage/overview_cache_progress_test.go new file mode 100644 index 0000000000..cb748ed1f8 --- /dev/null +++ b/apps/backend/internal/system/storage/overview_cache_progress_test.go @@ -0,0 +1,363 @@ +package storage + +import ( + "context" + "errors" + "sync" + "testing" + "time" +) + +func TestOverviewCacheReadStartsColdScanWithoutWaiting(t *testing.T) { + provider := newProgressiveOverview() + cache := NewOverviewCache(provider) + + started := time.Now() + read, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("Read: %v", err) + } + if elapsed := time.Since(started); elapsed > 100*time.Millisecond { + t.Fatalf("cold Read took %s, want nonblocking response", elapsed) + } + if read.Snapshot != nil { + t.Fatalf("cold snapshot = %#v, want nil", read.Snapshot) + } + if read.Analysis.State != AnalysisStateScanning { + t.Fatalf("cold analysis state = %q, want scanning", read.Analysis.State) + } + if read.Analysis.Progress.TotalSources != len(storageAnalysisSources) { + t.Fatalf("total sources = %d, want %d", read.Analysis.Progress.TotalSources, len(storageAnalysisSources)) + } + <-provider.started + + joined, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("joined Read: %v", err) + } + if joined.Analysis.Generation != read.Analysis.Generation { + t.Fatalf("joined generation = %d, want %d", joined.Analysis.Generation, read.Analysis.Generation) + } + if provider.calls != 1 { + t.Fatalf("progressive Summary calls = %d, want 1", provider.calls) + } + + close(provider.release) + waitForOverviewState(t, cache, AnalysisStateReady) + complete, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("completed Read: %v", err) + } + if complete.Snapshot == nil || complete.Snapshot.Summary.Workspaces != 42 { + t.Fatalf("completed snapshot = %#v, want workspaces 42", complete.Snapshot) + } +} + +func TestOverviewCachePreservesSourceFailureOnSuccessfulScan(t *testing.T) { + provider := newProgressiveOverview() + provider.setSourceFailure(errors.New("go cache unavailable")) + cache := NewOverviewCache(provider) + + if _, err := cache.Read(context.Background()); err != nil { + t.Fatalf("Read: %v", err) + } + <-provider.started + close(provider.release) + read := waitForOverviewState(t, cache, AnalysisStateReady) + + progress, ok := read.Analysis.Progress.Sources[StorageSourceGoCache] + if !ok { + t.Fatalf("source progress does not include %q", StorageSourceGoCache) + } + if progress.State != SourceStateFailed { + t.Fatalf("Go-cache source state = %q, want failed", progress.State) + } + if progress.Error == nil || *progress.Error != "go cache unavailable" { + t.Fatalf("Go-cache source error = %v, want provider error", progress.Error) + } +} + +func TestOverviewCachePreservesCountersOnTerminalProgress(t *testing.T) { + cache := NewOverviewCache(terminalProgressOverview{}) + if _, err := cache.Get(context.Background()); err != nil { + t.Fatalf("Get: %v", err) + } + read, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("Read: %v", err) + } + progress := read.Analysis.Progress.Sources[StorageSourceWorkspaces] + if progress.CompletedItems != 7 || progress.BytesScanned != 42 { + t.Fatalf("terminal progress = %#v, want counters preserved", progress) + } + if progress.TotalItems == nil || *progress.TotalItems != 9 { + t.Fatalf("terminal total_items = %v, want 9", progress.TotalItems) + } +} + +func TestOverviewCacheReadKeepsExpiredSnapshotWhileRefreshing(t *testing.T) { + now := time.Date(2026, time.July, 23, 12, 0, 0, 0, time.UTC) + provider := newProgressiveOverview() + provider.summary = Summary{Workspaces: 1} + cache := newOverviewCacheForTest(provider, func() time.Time { return now }) + close(provider.release) + first, err := cache.Get(context.Background()) + if err != nil { + t.Fatalf("initial Get: %v", err) + } + + provider.setNextSummary(Summary{Workspaces: 2}) + now = now.Add(defaultOverviewCacheTTL) + read, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("expired Read: %v", err) + } + if read.Snapshot == nil || read.Snapshot.Summary.Workspaces != first.Summary.Workspaces { + t.Fatalf("expired snapshot = %#v, want previous snapshot", read.Snapshot) + } + if !read.Analysis.Stale || read.Analysis.State != AnalysisStateScanning { + t.Fatalf("expired analysis = %#v, want stale scanning", read.Analysis) + } + <-provider.nextStarted + if provider.calls != 2 { + t.Fatalf("refresh calls = %d, want 2", provider.calls) + } + + close(provider.nextRelease) + waitForOverviewState(t, cache, AnalysisStateReady) + refreshed, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("refreshed Read: %v", err) + } + if refreshed.Snapshot == nil || refreshed.Snapshot.Summary.Workspaces != 2 { + t.Fatalf("refreshed snapshot = %#v, want workspaces 2", refreshed.Snapshot) + } +} + +func TestOverviewCacheReadFailurePreservesSnapshotAndReportsAttempt(t *testing.T) { + now := time.Date(2026, time.July, 23, 12, 0, 0, 0, time.UTC) + provider := newProgressiveOverview() + provider.summary = Summary{Workspaces: 7} + cache := newOverviewCacheForTest(provider, func() time.Time { return now }) + close(provider.release) + first, err := cache.Get(context.Background()) + if err != nil { + t.Fatalf("initial Get: %v", err) + } + + provider.setNextError(errors.New("scan failed")) + now = now.Add(defaultOverviewCacheTTL) + read, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("failed refresh Read: %v", err) + } + <-provider.nextStarted + close(provider.nextRelease) + waitForOverviewState(t, cache, AnalysisStateFailed) + + failed, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("failed state Read: %v", err) + } + if failed.Snapshot == nil || failed.Snapshot.Summary.Workspaces != first.Summary.Workspaces { + t.Fatalf("failed snapshot = %#v, want previous snapshot", failed.Snapshot) + } + if !failed.Analysis.Stale || failed.Analysis.Error == nil || *failed.Analysis.Error != "scan failed" { + t.Fatalf("failed analysis = %#v, want stale error", failed.Analysis) + } + if !failed.Snapshot.AnalyzedAt.Equal(first.AnalyzedAt) { + t.Fatalf("failed analyzed_at = %s, want %s", failed.Snapshot.AnalyzedAt, first.AnalyzedAt) + } + _ = read +} + +func TestOverviewCacheInvalidationRejectsLateProgressAndCompletion(t *testing.T) { + provider := newProgressiveOverview() + provider.summary = Summary{Workspaces: 1} + cache := NewOverviewCache(provider) + first, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("initial Read: %v", err) + } + <-provider.started + + cache.Invalidate() + provider.setNextSummary(Summary{Workspaces: 2}) + second, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("second Read: %v", err) + } + if second.Analysis.Generation <= first.Analysis.Generation { + t.Fatalf("second generation = %d, want newer than %d", second.Analysis.Generation, first.Analysis.Generation) + } + <-provider.nextStarted + + close(provider.release) + close(provider.nextRelease) + waitForOverviewState(t, cache, AnalysisStateReady) + current, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("current Read: %v", err) + } + if current.Snapshot == nil || current.Snapshot.Summary.Workspaces != 2 { + t.Fatalf("current snapshot = %#v, want newer completion", current.Snapshot) + } +} + +func waitForOverviewState(t *testing.T, cache *OverviewCache, want AnalysisStateName) OverviewRead { + t.Helper() + deadline := time.NewTimer(time.Second) + defer deadline.Stop() + for { + read, err := cache.Read(context.Background()) + if err != nil { + t.Fatalf("poll Read: %v", err) + } + if read.Analysis.State == want { + return read + } + select { + case <-deadline.C: + t.Fatalf("analysis state = %q, want %q", read.Analysis.State, want) + default: + } + } +} + +type progressiveOverview struct { + mu sync.Mutex + + calls int + summary Summary + next Summary + nextErr error + hasNext bool + started chan struct{} + nextStarted chan struct{} + release chan struct{} + nextRelease chan struct{} + sourceFailure error +} + +func newProgressiveOverview() *progressiveOverview { + return &progressiveOverview{ + summary: Summary{Workspaces: 42}, + started: make(chan struct{}), + nextStarted: make(chan struct{}), + release: make(chan struct{}), + nextRelease: make(chan struct{}), + } +} + +func (o *progressiveOverview) Summary(ctx context.Context) (Summary, error) { + return o.SummaryWithProgress(ctx, nil) +} + +func (o *progressiveOverview) SummaryWithProgress( + ctx context.Context, + notify OverviewProgressCallback, +) (Summary, error) { + o.mu.Lock() + o.calls++ + call := o.calls + summary, err := o.summary, error(nil) + release := o.release + if o.hasNext { + summary, err, release = o.next, o.nextErr, o.nextRelease + o.hasNext = false + } + if call == 1 { + close(o.started) + } else { + close(o.nextStarted) + } + o.mu.Unlock() + if notify != nil { + notify(OverviewProgress{Source: StorageSourceWorkspaces, State: SourceStateScanning}) + } + select { + case <-release: + case <-ctx.Done(): + return Summary{}, ctx.Err() + } + if err != nil { + return Summary{}, err + } + if notify != nil { + o.mu.Lock() + sourceFailure := o.sourceFailure + o.mu.Unlock() + if sourceFailure != nil { + notify(OverviewProgress{ + Source: StorageSourceGoCache, State: SourceStateFailed, Err: sourceFailure, + }) + } + notify(OverviewProgress{ + Source: StorageSourceWorkspaces, State: SourceStateReady, + CompletedItems: 1, TotalItems: intPointer(1), Value: summary.Workspaces, + }) + } + return summary, nil +} + +func (o *progressiveOverview) Capabilities(context.Context, StorageMaintenanceSettings) Capabilities { + return Capabilities{} +} + +func (o *progressiveOverview) SettingsCapabilities( + context.Context, + StorageMaintenanceSettings, +) Capabilities { + return Capabilities{} +} + +func (o *progressiveOverview) setNextSummary(summary Summary) { + o.mu.Lock() + defer o.mu.Unlock() + o.next, o.nextErr, o.hasNext = summary, nil, true +} + +func (o *progressiveOverview) setNextError(err error) { + o.mu.Lock() + defer o.mu.Unlock() + o.next, o.nextErr, o.hasNext = Summary{}, err, true +} + +func (o *progressiveOverview) setSourceFailure(err error) { + o.mu.Lock() + defer o.mu.Unlock() + o.sourceFailure = err +} + +func intPointer(value int) *int { + return &value +} + +type terminalProgressOverview struct{} + +func (terminalProgressOverview) Summary(context.Context) (Summary, error) { + return Summary{Workspaces: 1}, nil +} + +func (terminalProgressOverview) SummaryWithProgress( + _ context.Context, + notify OverviewProgressCallback, +) (Summary, error) { + notify(OverviewProgress{ + Source: StorageSourceWorkspaces, State: SourceStateScanning, + CompletedItems: 7, TotalItems: intPointer(9), BytesScanned: 42, + }) + notify(OverviewProgress{Source: StorageSourceWorkspaces, State: SourceStateReady, Value: 1}) + return Summary{Workspaces: 1}, nil +} + +func (terminalProgressOverview) Capabilities(context.Context, StorageMaintenanceSettings) Capabilities { + return Capabilities{} +} + +func (terminalProgressOverview) SettingsCapabilities( + context.Context, + StorageMaintenanceSettings, +) Capabilities { + return Capabilities{} +} diff --git a/apps/backend/internal/system/storage/tempartifacts/analysis_scanner_test.go b/apps/backend/internal/system/storage/tempartifacts/analysis_scanner_test.go new file mode 100644 index 0000000000..f1bf8d542b --- /dev/null +++ b/apps/backend/internal/system/storage/tempartifacts/analysis_scanner_test.go @@ -0,0 +1,70 @@ +package tempartifacts + +import ( + "context" + "errors" + "os" + "path/filepath" + "sync/atomic" + "testing" + + "github.com/kandev/kandev/internal/system/storage" + "github.com/kandev/kandev/internal/system/storage/filescan" +) + +func TestAnalyzeUsesConfiguredBoundedScanner(t *testing.T) { + root := t.TempDir() + artifacts := newFakeArtifactStore() + quarantine := newFakeQuarantineStore() + registry := NewRegistry(Config{ + Store: artifacts, TempRoot: root, OwnerPID: 1234, + NewID: func() string { return "artifact-1" }, NewToken: func() string { return "token-1" }, + }) + lease, err := registry.Create(context.Background(), storage.TemporaryArtifactKindImproveBundle, nil) + if err != nil { + t.Fatalf("Create: %v", err) + } + if err := os.WriteFile(filepath.Join(lease.Path(), "bundle"), []byte("bundle"), 0o600); err != nil { + t.Fatal(err) + } + provider := NewProvider(ProviderConfig{Registry: registry, Store: quarantine, HomeDir: t.TempDir()}) + var completed atomic.Int32 + provider.scanner = filescan.NewLimiter(1) + provider.onProgress = func(progress filescan.Progress) { + if progress.Phase == filescan.RootCompleted { + completed.Add(1) + } + } + + if _, err := provider.Analyze(context.Background()); err != nil { + t.Fatalf("Analyze: %v", err) + } + if completed.Load() != 1 { + t.Fatalf("completed roots = %d, want one artifact root", completed.Load()) + } +} + +func TestAnalyzePropagatesCanceledScan(t *testing.T) { + root := t.TempDir() + artifacts := newFakeArtifactStore() + registry := NewRegistry(Config{ + Store: artifacts, TempRoot: root, OwnerPID: 1234, + NewID: func() string { return "artifact-1" }, NewToken: func() string { return "token-1" }, + }) + lease, err := registry.Create(context.Background(), storage.TemporaryArtifactKindImproveBundle, nil) + if err != nil { + t.Fatalf("Create: %v", err) + } + provider := NewProvider(ProviderConfig{ + Registry: registry, Store: newFakeQuarantineStore(), HomeDir: t.TempDir(), + }) + ctx, cancel := context.WithCancel(context.Background()) + cancel() + + if _, err := provider.Analyze(ctx); !errors.Is(err, context.Canceled) { + t.Fatalf("Analyze error = %v, want context.Canceled", err) + } + if err := lease.Close(context.Background()); err != nil { + t.Fatalf("Close: %v", err) + } +} diff --git a/apps/backend/internal/system/storage/tempartifacts/provider.go b/apps/backend/internal/system/storage/tempartifacts/provider.go index bf663b419f..b4d3900be4 100644 --- a/apps/backend/internal/system/storage/tempartifacts/provider.go +++ b/apps/backend/internal/system/storage/tempartifacts/provider.go @@ -13,6 +13,7 @@ import ( "github.com/google/uuid" "github.com/kandev/kandev/internal/system/storage" + "github.com/kandev/kandev/internal/system/storage/filescan" ) const staleArtifactAge = 24 * time.Hour @@ -25,23 +26,27 @@ type QuarantineStore interface { } type ProviderConfig struct { - Registry *Registry - Store QuarantineStore - HomeDir string - TrashDir string - Retention time.Duration - Now func() time.Time - NewID func() string + Registry *Registry + Store QuarantineStore + HomeDir string + TrashDir string + Retention time.Duration + Now func() time.Time + NewID func() string + Scanner *filescan.Limiter + OnProgress func(filescan.Progress) } type Provider struct { - registry *Registry - store QuarantineStore - homeDir string - trashDir string - retention time.Duration - now func() time.Time - newID func() string + registry *Registry + store QuarantineStore + homeDir string + trashDir string + retention time.Duration + now func() time.Time + newID func() string + scanner *filescan.Limiter + onProgress func(filescan.Progress) } type Analysis struct { @@ -90,6 +95,7 @@ func NewProvider(config ProviderConfig) *Provider { registry: config.Registry, store: config.Store, homeDir: filepath.Clean(config.HomeDir), trashDir: filepath.Clean(trashDir), retention: retention, now: now, newID: newID, + scanner: config.Scanner, onProgress: config.OnProgress, } } @@ -227,6 +233,8 @@ func (p *Provider) Analyze(ctx context.Context) (Analysis, error) { } analysis := Analysis{Available: true} cutoff := p.now().Add(-staleArtifactAge) + inspectable := make([]storage.TemporaryArtifact, 0, len(artifacts)) + roots := make([]filescan.Root, 0, len(artifacts)) for _, artifact := range artifacts { if artifact.State == storage.TemporaryArtifactStateQuarantined || artifact.State == storage.TemporaryArtifactStateDeleted { @@ -237,12 +245,34 @@ func (p *Provider) Analyze(ctx context.Context) (Analysis, error) { analysis.Warnings = append(analysis.Warnings, temporaryArtifactWarning(artifact)) continue } - size, inspectErr := p.inspect(artifact) - if inspectErr != nil { + if err := p.registry.Validate(artifact); err != nil { analysis.SkippedCount++ - analysis.Warnings = append(analysis.Warnings, inspectErr.Error()) + analysis.Warnings = append(analysis.Warnings, fmt.Errorf("skip temporary artifact %s: %w", artifact.Path, err).Error()) continue } + inspectable = append(inspectable, artifact) + roots = append(roots, filescan.Root{Path: artifact.Path, SymlinkPolicy: filescan.RejectSymlinks}) + } + scanner := p.scanner + if scanner == nil { + scanner = filescan.NewLimiter(4) + } + measurements := scanner.Measure(ctx, roots, p.onProgress) + for index, artifact := range inspectable { + measurement := measurements[index] + if measurement.Err != nil { + if errors.Is(measurement.Err, context.Canceled) || + errors.Is(measurement.Err, context.DeadlineExceeded) { + return analysis, measurement.Err + } + analysis.SkippedCount++ + analysis.Warnings = append( + analysis.Warnings, + fmt.Errorf("measure temporary artifact %s: %w", artifact.Path, measurement.Err).Error(), + ) + continue + } + size := measurement.Bytes analysis.TotalCount++ analysis.TotalBytes += size if artifact.State == storage.TemporaryArtifactStateActive { @@ -261,6 +291,15 @@ func (p *Provider) Analyze(ctx context.Context) (Analysis, error) { return analysis, nil } +func (p *Provider) AnalyzeWithProgress( + ctx context.Context, + onProgress func(filescan.Progress), +) (Analysis, error) { + copy := *p + copy.onProgress = onProgress + return copy.Analyze(ctx) +} + func (p *Provider) Cleanup(context.Context) (map[string]any, error) { return toMap(CleanupResult{Skipped: true, Reason: "manual_only"}), nil } diff --git a/apps/backend/internal/system/storage/workspaces/analysis_scanner_test.go b/apps/backend/internal/system/storage/workspaces/analysis_scanner_test.go new file mode 100644 index 0000000000..9634d3724d --- /dev/null +++ b/apps/backend/internal/system/storage/workspaces/analysis_scanner_test.go @@ -0,0 +1,37 @@ +package workspaces + +import ( + "context" + "os" + "path/filepath" + "sync/atomic" + "testing" + + "github.com/kandev/kandev/internal/system/storage/filescan" +) + +func TestAnalyzeUsesConfiguredBoundedScanner(t *testing.T) { + provider, root, _ := newProviderFixture(t, Inventory{Complete: true}, nil) + for index, name := range []string{"first-task_abc", "second-task_def"} { + workspace := createOwnedCandidate(t, root, name, OwnershipMarker{ + TaskID: name, TaskDirName: name, LayoutVersion: LayoutVersionSemantic, + }) + if err := os.WriteFile(filepath.Join(workspace, "data"), []byte(name), 0o600); err != nil { + t.Fatalf("write workspace %d: %v", index, err) + } + } + var completed atomic.Int32 + provider.config.Scanner = filescan.NewLimiter(1) + provider.config.OnProgress = func(progress filescan.Progress) { + if progress.Phase == filescan.RootCompleted { + completed.Add(1) + } + } + + if _, err := provider.Analyze(context.Background()); err != nil { + t.Fatalf("Analyze: %v", err) + } + if completed.Load() != 2 { + t.Fatalf("completed roots = %d, want two scanner roots", completed.Load()) + } +} diff --git a/apps/backend/internal/system/storage/workspaces/provider.go b/apps/backend/internal/system/storage/workspaces/provider.go index 3f6dc19876..561b61b34c 100644 --- a/apps/backend/internal/system/storage/workspaces/provider.go +++ b/apps/backend/internal/system/storage/workspaces/provider.go @@ -13,6 +13,7 @@ import ( "github.com/google/uuid" "github.com/kandev/kandev/internal/system/storage" + "github.com/kandev/kandev/internal/system/storage/filescan" ) type Provider struct { @@ -42,10 +43,11 @@ func New(config Config) *Provider { } type candidate struct { - path string - owner OwnershipMarker - size int64 - measured bool + path string + owner OwnershipMarker + size int64 + measured bool + measurementFailed bool } func (p *Provider) Analyze(ctx context.Context) (Analysis, error) { @@ -54,20 +56,33 @@ func (p *Provider) Analyze(ctx context.Context) (Analysis, error) { return Analysis{}, err } analysis := Analysis{Warnings: warnings} + scanner := p.config.Scanner + if scanner == nil { + scanner = filescan.NewLimiter(4) + } + measurementRoots := make([]filescan.Root, len(roots)) for index := range roots { - size, sizeErr := directorySizeNoFollow(roots[index].path) - if sizeErr != nil { + measurementRoots[index] = filescan.Root{Path: roots[index].path, SymlinkPolicy: filescan.SkipSymlinks} + } + measurements := scanner.Measure(ctx, measurementRoots, p.config.OnProgress) + for index := range roots { + measurement := measurements[index] + if measurement.Err != nil { + if errors.Is(measurement.Err, context.Canceled) || errors.Is(measurement.Err, context.DeadlineExceeded) { + return analysis, measurement.Err + } analysis.Warnings = append( analysis.Warnings, - fmt.Sprintf("measure workspace %s: %v", roots[index].path, sizeErr), + fmt.Sprintf("measure workspace %s: %v", roots[index].path, measurement.Err), ) + roots[index].measurementFailed = true continue } - roots[index].size = size + roots[index].size = measurement.Bytes roots[index].measured = true - analysis.TotalBytes += size + analysis.TotalBytes += measurement.Bytes if _, active := protected[roots[index].path]; active { - analysis.ActiveBytes += size + analysis.ActiveBytes += measurement.Bytes } } candidates, err := p.eligibleCandidates(roots, protected, trashTasks) @@ -80,6 +95,15 @@ func (p *Provider) Analyze(ctx context.Context) (Analysis, error) { return analysis, nil } +func (p *Provider) AnalyzeWithProgress( + ctx context.Context, + onProgress func(filescan.Progress), +) (Analysis, error) { + copy := *p + copy.config.OnProgress = onProgress + return copy.Analyze(ctx) +} + func (p *Provider) Cleanup(ctx context.Context) (CleanupResult, error) { candidates, _, warnings, err := p.classify(ctx) if err != nil { @@ -139,6 +163,9 @@ func (p *Provider) eligibleCandidates( cutoff := p.config.Now().Add(-p.config.GracePeriod) candidates := make([]candidate, 0) for _, root := range roots { + if root.measurementFailed { + continue + } if _, keep := protected[root.path]; keep { continue } diff --git a/apps/backend/internal/system/storage/workspaces/provider_test.go b/apps/backend/internal/system/storage/workspaces/provider_test.go index 3225736d2b..e49fb343d5 100644 --- a/apps/backend/internal/system/storage/workspaces/provider_test.go +++ b/apps/backend/internal/system/storage/workspaces/provider_test.go @@ -157,6 +157,23 @@ func TestAnalyzeReportsAllWorkspaceBytesIncludingYoungOrphans(t *testing.T) { } } +func TestEligibleCandidatesSkipsRootsThatFailedMeasurement(t *testing.T) { + provider, root, _ := newProviderFixture(t, Inventory{Complete: true}, nil) + failedPath := filepath.Join(root, "unreadable-workspace") + + candidates, err := provider.eligibleCandidates( + []candidate{{path: failedPath, measurementFailed: true}}, + map[string]struct{}{}, + filepath.Join(filepath.Dir(root), "trash"), + ) + if err != nil { + t.Fatalf("eligibleCandidates: %v", err) + } + if len(candidates) != 0 { + t.Fatalf("candidates = %#v, want failed root skipped", candidates) + } +} + func TestCleanupQuarantinesOldOwnedOrphanAndRestoreIsConflictSafe(t *testing.T) { provider, root, store := newProviderFixture(t, Inventory{Complete: true}, nil) candidate := createOwnedCandidate(t, root, "orphan-task_abc", OwnershipMarker{ diff --git a/apps/backend/internal/system/storage/workspaces/types.go b/apps/backend/internal/system/storage/workspaces/types.go index b431fd290c..c06d4fe746 100644 --- a/apps/backend/internal/system/storage/workspaces/types.go +++ b/apps/backend/internal/system/storage/workspaces/types.go @@ -7,6 +7,7 @@ import ( "time" "github.com/kandev/kandev/internal/system/storage" + "github.com/kandev/kandev/internal/system/storage/filescan" ) const ( @@ -65,6 +66,8 @@ type Config struct { Now func() time.Time NewID func() string Pruner WorktreePruner + Scanner *filescan.Limiter + OnProgress func(filescan.Progress) } type WorktreePruner interface { diff --git a/apps/backend/pkg/websocket/actions.go b/apps/backend/pkg/websocket/actions.go index 48883c8c7c..3b23aa3384 100644 --- a/apps/backend/pkg/websocket/actions.go +++ b/apps/backend/pkg/websocket/actions.go @@ -389,6 +389,7 @@ const ( // disk walk). Broadcast to all connected clients so the System pages can // render progress. ActionSystemJobUpdate = "system.job.update" + ActionSystemStorageAnalysisUpdated = "system.storage.analysis.updated" ActionSystemAgentRuntimeStatusChanged = "system.agent_runtime.status_changed" // VS Code server actions diff --git a/apps/web/components/settings/system/storage/storage-maintenance-settings.test.tsx b/apps/web/components/settings/system/storage/storage-maintenance-settings.test.tsx index bbcbfcd167..d91debb1eb 100644 --- a/apps/web/components/settings/system/storage/storage-maintenance-settings.test.tsx +++ b/apps/web/components/settings/system/storage/storage-maintenance-settings.test.tsx @@ -91,6 +91,19 @@ const overview = { managed_container_bytes: 0, }, }, + analysis: { + generation: 1, + state: "ready", + started_at: "2026-07-23T11:59:00Z", + completed_at: "2026-07-23T12:00:00Z", + duration_ms: 60000, + cache_ttl_seconds: 900, + refresh_due_at: "2099-07-23T12:15:00Z", + stale: false, + error: null, + progress: { completed_sources: 5, total_sources: 5, sources: {} }, + partial_summary: null, + }, analyzed_at: "2026-07-23T12:00:00Z", last_run: null, } satisfies StorageOverviewResponse; diff --git a/apps/web/components/settings/system/storage/storage-overview-card.test.tsx b/apps/web/components/settings/system/storage/storage-overview-card.test.tsx index e8faeae52b..9975cf2d4c 100644 --- a/apps/web/components/settings/system/storage/storage-overview-card.test.tsx +++ b/apps/web/components/settings/system/storage/storage-overview-card.test.tsx @@ -2,7 +2,8 @@ import { cleanup, fireEvent, render, screen } from "@testing-library/react"; import { TooltipProvider } from "@kandev/ui/tooltip"; import { afterEach, describe, expect, it, vi } from "vitest"; import { formatDateTime } from "@/lib/i18n/formats"; -import type { StorageOverviewResponse } from "@/lib/types/system"; +import { activateLocale } from "@/lib/i18n"; +import type { StorageAnalysisState, StorageOverviewResponse } from "@/lib/types/system"; import { StorageOverviewCard } from "./storage-overview-card"; const degradedOverview = { @@ -45,6 +46,19 @@ const degradedOverview = { managed_container_bytes: 0, }, }, + analysis: { + generation: 1, + state: "ready", + started_at: "2026-07-23T11:59:00Z", + completed_at: "2026-07-23T12:00:00Z", + duration_ms: 60000, + cache_ttl_seconds: 900, + refresh_due_at: "2099-07-23T12:15:00Z", + stale: false, + error: null, + progress: { completed_sources: 5, total_sources: 5, sources: {} }, + partial_summary: null, + } satisfies StorageAnalysisState, analyzed_at: "2026-07-23T12:00:00Z", last_run: null, } satisfies StorageOverviewResponse; @@ -241,4 +255,87 @@ describe("StorageOverviewCard refresh and policy state", () => { expect(screen.getByTestId("storage-overview-spinner")).toBeTruthy(); }); + + it("shows completed sources and in-progress source states during the first scan", () => { + const overview = { + ...degradedOverview, + summary: null, + analyzed_at: null, + analysis: { + ...degradedOverview.analysis, + state: "scanning", + stale: false, + progress: { + completed_sources: 1, + total_sources: 5, + sources: { + workspaces: { state: "ready", completed_items: 3, total_items: 3, bytes_scanned: 42 }, + go_cache: { state: "scanning", completed_items: 1, total_items: 4, bytes_scanned: 10 }, + quarantine: { state: "pending", completed_items: 0, bytes_scanned: 0 }, + temporary_artifacts: { state: "pending", completed_items: 0, bytes_scanned: 0 }, + docker: { state: "pending", completed_items: 0, bytes_scanned: 0 }, + }, + }, + partial_summary: { + workspaces: { + total_bytes: 2 * 1024 ** 3, + active_bytes: 1 * 1024 ** 3, + candidate_bytes: 0, + }, + }, + }, + } satisfies StorageOverviewResponse; + + render(); + + expect(screen.getByTestId("storage-analysis-total").textContent).toContain( + "Counted so far: 2 GB", + ); + expect(screen.getByTestId("storage-analysis-total-partial")).toBeTruthy(); + expect(screen.getByTestId("storage-analysis-source-go_cache").textContent).toContain( + "Measuring 1 of 4", + ); + expect(screen.getByTestId("storage-analysis-source-quarantine").textContent).toContain( + "Waiting to measure", + ); + }); + + it("discloses timing and the next refresh for a completed snapshot", () => { + render(, { + wrapper: TooltipProvider, + }); + + fireEvent.click(screen.getByTestId("storage-analysis-timing-help")); + const tooltip = screen.getByRole("tooltip"); + expect(tooltip.textContent).toContain("Scan duration: 1 min"); + expect(tooltip.textContent).toContain("Cache lifetime: 15 min"); + expect(tooltip.textContent).toContain("Analyze refreshes this data immediately"); + }); +}); + +describe("StorageOverviewCard localized timing", () => { + it("uses the active locale's decimal separator for fractional seconds", async () => { + await activateLocale("pt-pt"); + try { + const overview = { + ...degradedOverview, + analysis: { ...degradedOverview.analysis, duration_ms: 1_234 }, + } satisfies StorageOverviewResponse; + + render(, { + wrapper: TooltipProvider, + }); + + fireEvent.click(screen.getByTestId("storage-analysis-timing-help")); + const tooltip = screen.getByRole("tooltip"); + const localizedSeconds = new Intl.NumberFormat("pt-pt", { + minimumFractionDigits: 1, + maximumFractionDigits: 1, + }).format(1.234); + expect(tooltip.textContent).toContain(localizedSeconds); + expect(tooltip.textContent).not.toContain("1.2"); + } finally { + await activateLocale("en"); + } + }); }); diff --git a/apps/web/components/settings/system/storage/storage-overview-card.tsx b/apps/web/components/settings/system/storage/storage-overview-card.tsx index a8a8884a29..9ea8242708 100644 --- a/apps/web/components/settings/system/storage/storage-overview-card.tsx +++ b/apps/web/components/settings/system/storage/storage-overview-card.tsx @@ -2,29 +2,31 @@ import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from "@k import { Badge } from "@kandev/ui/badge"; import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@kandev/ui/card"; import { Spinner } from "@kandev/ui/spinner"; +import { TooltipProvider } from "@kandev/ui/tooltip"; import { IconChartPie, IconTrash } from "@tabler/icons-react"; import { useTranslation } from "react-i18next"; -import { formatDateTime, formatRelative } from "@/lib/i18n/formats"; +import { + formatDateTime, + formatNumber, + formatRelative, + formatRelativeTime, +} from "@/lib/i18n/formats"; import type { StorageMaintenanceSettings, StorageOverviewResponse, - StorageQuarantineSummary, - StorageTemporaryArtifactsSummary, + StorageSummaryPartial, } from "@/lib/types/system"; import { StorageActionButton } from "./storage-action-button"; +import { StorageSettingHelp } from "./storage-setting-help"; +import { + storageResources, + TEMPORARY_ARTIFACTS_RESOURCE_ID, + type StorageResource, + type Translate, +} from "./storage-overview-resources"; import { formatGigabytes } from "./storage-units"; import { storageAnalysisTotal } from "./storage-totals"; -/** - * Copy for the resource rows is built in plain functions rather than JSX, so - * `i18next/no-literal-string` (mode `jsx-only`) never inspected any of it. Each - * takes `t` from the caller's `useTranslation` instead of importing the - * module-level one, so the rows re-render on a locale switch. - */ -type Translate = (key: string, options?: Record) => string; -const STORAGE_UNAVAILABLE_VALUE_KEY = "system:storageUnavailableValue"; -const TEMPORARY_ARTIFACTS_RESOURCE_ID = "temporary-artifacts"; - interface Props { overview: StorageOverviewResponse | null; settings?: StorageMaintenanceSettings; @@ -35,14 +37,6 @@ interface Props { onRunTemporaryArtifacts?: () => void; } -interface StorageResource { - id: string; - label: string; - value: string; - detail: string; - warning?: string; -} - function goCacheDisabledReason( t: Translate, overview: StorageOverviewResponse, @@ -50,100 +44,27 @@ function goCacheDisabledReason( settings?: StorageMaintenanceSettings, ) { if (pendingReason) return pendingReason; - if (overview.summary.go_cache.owned !== true) { + const summary = overview.summary ?? overview.analysis.partial_summary; + const goCache = summary?.go_cache; + if (!goCache) return t("system:storageAnalysisSourcePending"); + if (goCache.owned !== true) { return t("system:storageGoCacheNotOwned"); } - if ( - (overview.summary.go_cache.size_bytes ?? 0) <= - (settings ?? overview.settings).go_cache.max_bytes - ) { + if ((goCache.size_bytes ?? 0) <= (settings ?? overview.settings).go_cache.max_bytes) { return t("system:storageGoCacheBelowLimit"); } return undefined; } -function quarantineResource(t: Translate, summary: StorageQuarantineSummary): StorageResource { - if (summary.available === false) { - return { - id: "quarantine", - label: t("system:storageQuarantinedResources"), - value: t(STORAGE_UNAVAILABLE_VALUE_KEY), - detail: t("system:storageQuarantineUnmeasured"), - warning: summary.warning, - }; - } - return { - id: "quarantine", - label: t("system:storageQuarantinedResources"), - value: formatGigabytes(summary.size_bytes), - detail: t("system:storageQuarantineMovedAside", { count: summary.count }), - }; -} - -function dockerMeasurement( - t: Translate, - available: boolean, - value: string, - detail: string, -): Pick { - if (!available) { - return { - value: t(STORAGE_UNAVAILABLE_VALUE_KEY), - detail: t("system:storageDockerUnmeasured"), - }; - } - return { value, detail }; -} - -function temporaryArtifactsResource( - t: Translate, - summary: StorageTemporaryArtifactsSummary, -): StorageResource { - const warnings = [summary.warning, ...(summary.warnings ?? [])].filter(Boolean).join(" · "); - if (summary.available === false) { - return { - id: TEMPORARY_ARTIFACTS_RESOURCE_ID, - label: t("system:storageTemporaryArtifacts"), - value: t(STORAGE_UNAVAILABLE_VALUE_KEY), - detail: t("system:storageTemporaryArtifactsUnavailable"), - warning: warnings || undefined, - }; - } - const stale = summary.stale_count ?? 0; - const active = summary.active_count ?? 0; - const protectedCount = summary.protected_count ?? 0; - const staleBytes = - summary.stale_bytes === undefined - ? undefined - : t("system:storageTemporaryArtifactsStaleBytes", { - value: formatGigabytes(summary.stale_bytes), - }); - return { - id: TEMPORARY_ARTIFACTS_RESOURCE_ID, - label: t("system:storageTemporaryArtifacts"), - value: - summary.total_bytes === undefined - ? t(STORAGE_UNAVAILABLE_VALUE_KEY) - : formatGigabytes(summary.total_bytes), - detail: [ - t("system:storageTemporaryArtifactsStaleCount", { count: stale }), - staleBytes, - t("system:storageTemporaryArtifactsActiveCount", { count: active }), - t("system:storageTemporaryArtifactsProtectedCount", { count: protectedCount }), - ] - .filter(Boolean) - .join(" · "), - warning: warnings || undefined, - }; -} - function temporaryArtifactsDisabledReason( t: Translate, overview: StorageOverviewResponse, pendingReason?: string, ) { if (pendingReason) return pendingReason; - const summary = overview.summary.temporary_artifacts; + const summary = + overview.summary?.temporary_artifacts ?? overview.analysis.partial_summary?.temporary_artifacts; + if (!summary) return t("system:storageAnalysisSourcePending"); if (overview.capabilities.temporary_artifacts_available !== true || summary.available === false) { return t("system:storageTemporaryArtifactsUnavailable"); } @@ -153,91 +74,6 @@ function temporaryArtifactsDisabledReason( return undefined; } -function storageResources(t: Translate, overview: StorageOverviewResponse): StorageResource[] { - const { summary } = overview; - const dockerWarning = summary.docker.warnings?.join(" · "); - // The Docker host is an address, not copy; the fallback naming the default is. - const dockerHost = overview.capabilities.docker_host || t("system:storageDefaultDockerHost"); - return [ - { - id: "workspaces", - label: t("system:storageTaskWorkspaces"), - value: formatGigabytes(summary.workspaces.total_bytes ?? 0), - detail: t("system:storageWorkspacesDetail", { - reclaimable: formatGigabytes(summary.workspaces.candidate_bytes ?? 0), - active: formatGigabytes(summary.workspaces.active_bytes ?? 0), - }), - warning: summary.workspaces.warning, - }, - quarantineResource(t, summary.quarantine), - { - id: "managed-containers", - label: t("system:storageKandevContainers"), - ...dockerMeasurement( - t, - summary.docker.available, - formatGigabytes(summary.docker.managed_container_bytes ?? 0), - t("system:storageManagedContainerCount", { - count: summary.docker.managed_container_count ?? 0, - }), - ), - warning: dockerWarning, - }, - { - id: "go-cache", - label: t("system:storageGoBuildCache"), - value: formatGigabytes(summary.go_cache.size_bytes ?? 0), - // A filesystem path from the API — never routed through the catalog. - detail: summary.go_cache.path ?? overview.capabilities.managed_go_cache_path, - warning: summary.go_cache.warning, - }, - ...(summary.go_cache.unmanaged_path - ? [ - { - id: "unmanaged-go-cache", - label: t("system:storageUserGoBuildCache"), - value: formatGigabytes(summary.go_cache.unmanaged_size_bytes ?? 0), - detail: summary.go_cache.unmanaged_path, - }, - ] - : []), - temporaryArtifactsResource(t, summary.temporary_artifacts), - { - id: "docker-image-layers", - label: t("system:storageDockerImageLayers"), - ...dockerMeasurement( - t, - summary.docker.available, - formatGigabytes(summary.docker.image_layer_bytes ?? 0), - dockerHost, - ), - warning: dockerWarning, - }, - { - id: "docker-build-cache", - label: t("system:storageDockerBuildCache"), - ...dockerMeasurement( - t, - summary.docker.available, - formatGigabytes(summary.docker.build_cache_bytes), - dockerHost, - ), - warning: dockerWarning, - }, - { - id: "docker-unused-images", - label: t("system:storageUnusedDockerImages"), - ...dockerMeasurement( - t, - summary.docker.available, - formatGigabytes(summary.docker.unused_image_bytes), - t("system:storageUnusedImagesDetail"), - ), - warning: dockerWarning, - }, - ]; -} - interface ResourceRowProps { resource: StorageResource; goCacheCleanupDisabledReason?: string; @@ -262,7 +98,12 @@ function ResourceRow({ > {resource.label} - {resource.value} + + {resource.value} + @@ -295,6 +136,207 @@ function ResourceRow({ ); } +function formatScanDuration(t: Translate, milliseconds: number): string { + const value = Math.max(0, Math.round(milliseconds)); + if (value >= 60_000) { + return t("system:storageAnalysisDurationMinutes", { value: Math.round(value / 60_000) }); + } + if (value >= 1_000) { + return t("system:storageAnalysisDurationSeconds", { + value: formatNumber(value / 1_000, { + minimumFractionDigits: 1, + maximumFractionDigits: 1, + }), + }); + } + return t("system:storageAnalysisDurationMilliseconds", { value }); +} + +function AnalysisTimingDisclosure({ overview }: { overview: StorageOverviewResponse }) { + const { t } = useTranslation(); + const { analysis } = overview; + if (analysis.state !== "ready" || !overview.analyzed_at || analysis.duration_ms == null) { + return null; + } + const nextRefresh = analysis.refresh_due_at + ? t("system:storageAnalysisNextRefresh", { + absolute: formatDateTime(analysis.refresh_due_at), + relative: formatRelativeTime(analysis.refresh_due_at), + }) + : t("system:storageAnalysisNextRefreshUnknown"); + const disclosure = [ + t("system:storageAnalysisDuration", { + duration: formatScanDuration(t, analysis.duration_ms), + }), + t("system:storageAnalysisCacheLifetime", { + duration: formatScanDuration(t, analysis.cache_ttl_seconds * 1_000), + }), + nextRefresh, + t("system:storageAnalysisTimingHelp"), + ].join(" "); + return ( + + + {disclosure} + + + ); +} + +function EmptyStorageOverview({ + isInitialLoading, + error, +}: { + isInitialLoading: boolean; + error?: string | null; +}) { + const { t } = useTranslation(); + return ( + + + {isInitialLoading && } + + {isInitialLoading + ? t("system:storageLoadingData") + : t("system:storageSectionUnavailable")} + + {error && {error}} + + + ); +} + +function AnalysisStatusTime({ + overview, + analyzedAt, +}: { + overview: StorageOverviewResponse; + analyzedAt: string | null; +}) { + const { t } = useTranslation(); + if (analyzedAt && overview.analyzed_at) { + return ( + + ); + } + return ( +

+ {overview.analysis.state === "failed" + ? t("system:storageAnalysisFailed") + : t("system:storageAnalysisRunning")} +

+ ); +} + +function AnalysisTotal({ + overview, + total, +}: { + overview: StorageOverviewResponse; + total: ReturnType; +}) { + const { t } = useTranslation(); + return ( +
+ + {overview.summary === null + ? t("system:storageTotalCountedSoFar", { size: formatGigabytes(total.bytes) }) + : t("system:storageTotalCounted", { size: formatGigabytes(total.bytes) })} + + {total.partial && ( + + {t("system:storageTotalPartial")} + + )} +
+ ); +} + +function StorageOverviewHeader({ + overview, + displaySummary, + loading, + error, + total, +}: { + overview: StorageOverviewResponse; + displaySummary: StorageSummaryPartial; + loading?: boolean; + error?: string | null; + total: ReturnType; +}) { + const { t } = useTranslation(); + const analysisRunning = overview.analysis.state === "scanning"; + const isAnalysisFailed = overview.analysis.state === "failed"; + const isLoading = (loading ?? false) || analysisRunning; + const analyzedAt = overview.analyzed_at ? formatDateTime(overview.analyzed_at) : null; + const overviewError = error ?? overview.analysis.error; + return ( + + + {t("system:storageAnalysisTitle")} + {isLoading && } + {isAnalysisFailed && {t("system:storageAnalysisFailed")}} + {displaySummary.docker?.available === false && ( + {t("system:storageDockerUnavailableBadge")} + )} + + {t("system:storageAnalysisDescription")} +
+ + +
+ + {overviewError && ( +

+ {t("system:storageSectionUnavailable")}: {overviewError} +

+ )} +
+ ); +} + +function StorageOverviewResources({ + resources, + cleanupDisabledReason, + temporaryArtifactsCleanupDisabledReason, + onRunGoCache, + onRunTemporaryArtifacts, +}: { + resources: StorageResource[]; + cleanupDisabledReason?: string; + temporaryArtifactsCleanupDisabledReason?: string; + onRunGoCache: () => void; + onRunTemporaryArtifacts: () => void; +}) { + return ( + + + {resources.map((resource) => ( + + ))} + + + ); +} + export function StorageOverviewCard({ overview, settings, @@ -305,82 +347,34 @@ export function StorageOverviewCard({ onRunTemporaryArtifacts = () => {}, }: Props) { const { t } = useTranslation(); - const isLoading = loading ?? overview === null; if (!overview) { - return ( - - - {isLoading && } - - {isLoading ? t("system:storageLoadingData") : t("system:storageSectionUnavailable")} - - {error && {error}} - - - ); + return ; } - const { summary } = overview; - const analyzedAt = formatDateTime(overview.analyzed_at); + const displaySummary: StorageSummaryPartial = + overview.summary ?? overview.analysis.partial_summary ?? {}; const cleanupDisabledReason = goCacheDisabledReason(t, overview, disabledReason, settings); const temporaryArtifactsCleanupDisabledReason = temporaryArtifactsDisabledReason( t, overview, disabledReason, ); - const resources = storageResources(t, overview); - const total = storageAnalysisTotal(summary); + const total = storageAnalysisTotal(displaySummary); return ( - - - {t("system:storageAnalysisTitle")} - {isLoading && } - {!summary.docker.available && ( - {t("system:storageDockerUnavailableBadge")} - )} - - {t("system:storageAnalysisDescription")} - -
- - {t("system:storageTotalCounted", { size: formatGigabytes(total.bytes) })} - - {total.partial && ( - - {t("system:storageTotalPartial")} - - )} -
- {error && ( -

- {t("system:storageSectionUnavailable")}: {error} -

- )} -
- - - {resources.map((resource) => ( - - ))} - - + +
); } diff --git a/apps/web/components/settings/system/storage/storage-overview-resources.ts b/apps/web/components/settings/system/storage/storage-overview-resources.ts new file mode 100644 index 0000000000..ce2decfcc0 --- /dev/null +++ b/apps/web/components/settings/system/storage/storage-overview-resources.ts @@ -0,0 +1,322 @@ +import type { + StorageOverviewResponse, + StorageQuarantineSummary, + StorageSourceProgress, + StorageSummaryPartial, + StorageTemporaryArtifactsSummary, +} from "@/lib/types/system"; +import { formatGigabytes } from "./storage-units"; + +/** + * Resource-row copy is built in plain functions so each caller can provide its + * current translation function and rows update after a locale switch. + */ +export type Translate = (key: string, options?: Record) => string; +export const TEMPORARY_ARTIFACTS_RESOURCE_ID = "temporary-artifacts"; + +export interface StorageResource { + id: string; + label: string; + value: string; + detail: string; + warning?: string; + source?: string; +} + +const STORAGE_UNAVAILABLE_VALUE_KEY = "system:storageUnavailableValue"; + +function analysisSourceText(t: Translate, progress?: StorageSourceProgress): string { + if (!progress || progress.state === "pending") { + return t("system:storageAnalysisSourcePending"); + } + if (progress.state === "scanning") { + if (progress.total_items !== undefined) { + return t("system:storageAnalysisSourceScanning", { + completed: progress.completed_items, + total: progress.total_items, + }); + } + return t("system:storageAnalysisSourceScanningUnknown"); + } + if (progress.state === "failed") { + return progress.error + ? t("system:storageAnalysisSourceFailedWithError", { error: progress.error }) + : t("system:storageAnalysisSourceFailed"); + } + return t("system:storageAnalysisSourceComplete"); +} + +function pendingStorageResource( + t: Translate, + id: string, + label: string, + progress?: StorageSourceProgress, + source = id, +): StorageResource { + const status = analysisSourceText(t, progress); + return { id, label, value: status, detail: status, source }; +} + +function quarantineResource(t: Translate, summary: StorageQuarantineSummary): StorageResource { + if (summary.available === false) { + return { + id: "quarantine", + label: t("system:storageQuarantinedResources"), + value: t(STORAGE_UNAVAILABLE_VALUE_KEY), + detail: t("system:storageQuarantineUnmeasured"), + warning: summary.warning, + }; + } + return { + id: "quarantine", + label: t("system:storageQuarantinedResources"), + value: formatGigabytes(summary.size_bytes), + detail: t("system:storageQuarantineMovedAside", { count: summary.count }), + }; +} + +function dockerMeasurement( + t: Translate, + available: boolean, + value: string, + detail: string, +): Pick { + if (!available) { + return { + value: t(STORAGE_UNAVAILABLE_VALUE_KEY), + detail: t("system:storageDockerUnmeasured"), + }; + } + return { value, detail }; +} + +function temporaryArtifactsResource( + t: Translate, + summary: StorageTemporaryArtifactsSummary, +): StorageResource { + const warnings = [summary.warning, ...(summary.warnings ?? [])].filter(Boolean).join(" · "); + if (summary.available === false) { + return { + id: TEMPORARY_ARTIFACTS_RESOURCE_ID, + label: t("system:storageTemporaryArtifacts"), + value: t(STORAGE_UNAVAILABLE_VALUE_KEY), + detail: t("system:storageTemporaryArtifactsUnavailable"), + warning: warnings || undefined, + }; + } + const stale = summary.stale_count ?? 0; + const active = summary.active_count ?? 0; + const protectedCount = summary.protected_count ?? 0; + const staleBytes = + summary.stale_bytes === undefined + ? undefined + : t("system:storageTemporaryArtifactsStaleBytes", { + value: formatGigabytes(summary.stale_bytes), + }); + return { + id: TEMPORARY_ARTIFACTS_RESOURCE_ID, + label: t("system:storageTemporaryArtifacts"), + value: + summary.total_bytes === undefined + ? t(STORAGE_UNAVAILABLE_VALUE_KEY) + : formatGigabytes(summary.total_bytes), + detail: [ + t("system:storageTemporaryArtifactsStaleCount", { count: stale }), + staleBytes, + t("system:storageTemporaryArtifactsActiveCount", { count: active }), + t("system:storageTemporaryArtifactsProtectedCount", { count: protectedCount }), + ] + .filter(Boolean) + .join(" · "), + warning: warnings || undefined, + }; +} + +function workspaceResource( + t: Translate, + workspace: StorageSummaryPartial["workspaces"], + progress?: StorageSourceProgress, +): StorageResource { + if (!workspace) { + return pendingStorageResource(t, "workspaces", t("system:storageTaskWorkspaces"), progress); + } + return { + id: "workspaces", + label: t("system:storageTaskWorkspaces"), + value: formatGigabytes(workspace.total_bytes ?? 0), + detail: t("system:storageWorkspacesDetail", { + reclaimable: formatGigabytes(workspace.candidate_bytes ?? 0), + active: formatGigabytes(workspace.active_bytes ?? 0), + }), + warning: workspace.warning, + source: "workspaces", + }; +} + +function quarantineResourceOrPending( + t: Translate, + quarantine: StorageSummaryPartial["quarantine"], + progress?: StorageSourceProgress, +): StorageResource { + if (!quarantine) { + return pendingStorageResource( + t, + "quarantine", + t("system:storageQuarantinedResources"), + progress, + ); + } + return { ...quarantineResource(t, quarantine), source: "quarantine" }; +} + +type DockerSummary = NonNullable; + +interface DockerResourceOptions { + progress?: StorageSourceProgress; + id: string; + label: string; + value: string; + detail: string; + warning?: string; +} + +function dockerResource( + t: Translate, + docker: DockerSummary | null | undefined, + options: DockerResourceOptions, +): StorageResource { + if (!docker) { + return pendingStorageResource(t, options.id, options.label, options.progress, "docker"); + } + return { + id: options.id, + label: options.label, + ...dockerMeasurement(t, docker.available === true, options.value, options.detail), + warning: options.warning, + source: "docker", + }; +} + +function goCacheResources( + t: Translate, + goCache: StorageSummaryPartial["go_cache"], + progress: StorageSourceProgress | undefined, + managedPath: string, +): StorageResource[] { + const resources: StorageResource[] = [ + goCache + ? { + id: "go-cache", + label: t("system:storageGoBuildCache"), + value: formatGigabytes(goCache.size_bytes ?? 0), + // A filesystem path from the API is never routed through the catalog. + detail: goCache.path ?? managedPath, + warning: goCache.warning, + source: "go_cache", + } + : pendingStorageResource( + t, + "go-cache", + t("system:storageGoBuildCache"), + progress, + "go_cache", + ), + ]; + if (goCache?.unmanaged_path) { + resources.push({ + id: "unmanaged-go-cache", + label: t("system:storageUserGoBuildCache"), + value: formatGigabytes(goCache.unmanaged_size_bytes ?? 0), + detail: goCache.unmanaged_path, + source: "go_cache", + }); + } + return resources; +} + +function temporaryArtifactsResourceOrPending( + t: Translate, + temporaryArtifacts: StorageSummaryPartial["temporary_artifacts"], + progress?: StorageSourceProgress, +): StorageResource { + if (!temporaryArtifacts) { + return pendingStorageResource( + t, + "temporary-artifacts", + t("system:storageTemporaryArtifacts"), + progress, + "temporary_artifacts", + ); + } + return { ...temporaryArtifactsResource(t, temporaryArtifacts), source: "temporary_artifacts" }; +} + +function dockerResources( + t: Translate, + docker: DockerSummary | null | undefined, + progress: StorageSourceProgress | undefined, + host: string, +): StorageResource[] { + const dockerWarning = docker?.warnings?.join(" · "); + const dockerHost = host || t("system:storageDefaultDockerHost"); + return [ + dockerResource(t, docker, { + progress, + id: "managed-containers", + label: t("system:storageKandevContainers"), + value: formatGigabytes(docker?.managed_container_bytes ?? 0), + detail: t("system:storageManagedContainerCount", { + count: docker?.managed_container_count ?? 0, + }), + warning: dockerWarning, + }), + dockerResource(t, docker, { + progress, + id: "docker-image-layers", + label: t("system:storageDockerImageLayers"), + value: formatGigabytes(docker?.image_layer_bytes ?? 0), + detail: dockerHost, + warning: dockerWarning, + }), + dockerResource(t, docker, { + progress, + id: "docker-build-cache", + label: t("system:storageDockerBuildCache"), + value: formatGigabytes(docker?.build_cache_bytes ?? 0), + detail: dockerHost, + warning: dockerWarning, + }), + dockerResource(t, docker, { + progress, + id: "docker-unused-images", + label: t("system:storageUnusedDockerImages"), + value: formatGigabytes(docker?.unused_image_bytes ?? 0), + detail: t("system:storageUnusedImagesDetail"), + warning: dockerWarning, + }), + ]; +} + +export function storageResources( + t: Translate, + overview: StorageOverviewResponse, +): StorageResource[] { + const summary = overview.summary ?? overview.analysis.partial_summary ?? {}; + const progress = overview.analysis.progress.sources; + return [ + workspaceResource(t, summary.workspaces, progress.workspaces), + quarantineResourceOrPending(t, summary.quarantine, progress.quarantine), + ...goCacheResources( + t, + summary.go_cache, + progress.go_cache, + overview.capabilities.managed_go_cache_path, + ), + temporaryArtifactsResourceOrPending( + t, + summary.temporary_artifacts, + progress.temporary_artifacts, + ), + ...dockerResources(t, summary.docker, progress.docker, overview.capabilities.docker_host), + ]; +} diff --git a/apps/web/components/settings/system/storage/storage-setting-help.tsx b/apps/web/components/settings/system/storage/storage-setting-help.tsx index 9b93d96997..107a072e8c 100644 --- a/apps/web/components/settings/system/storage/storage-setting-help.tsx +++ b/apps/web/components/settings/system/storage/storage-setting-help.tsx @@ -6,7 +6,15 @@ import { Tooltip, TooltipContent, TooltipTrigger } from "@kandev/ui/tooltip"; import { IconInfoCircle } from "@tabler/icons-react"; import { useTranslation } from "react-i18next"; -export function StorageSettingHelp({ label, children }: { label: string; children: string }) { +export function StorageSettingHelp({ + label, + children, + testId, +}: { + label: string; + children: string; + testId?: string; +}) { const { t } = useTranslation(); const [open, setOpen] = useState(false); return ( @@ -17,6 +25,7 @@ export function StorageSettingHelp({ label, children }: { label: string; childre variant="ghost" size="icon-sm" className="size-11 shrink-0 cursor-help text-muted-foreground sm:size-7" + data-testid={testId} aria-label={t("system:storageMoreInformationAbout", { label })} onClick={() => setOpen((current) => !current)} > diff --git a/apps/web/components/settings/system/storage/storage-totals.test.ts b/apps/web/components/settings/system/storage/storage-totals.test.ts index 61957adf88..7e9f6a317b 100644 --- a/apps/web/components/settings/system/storage/storage-totals.test.ts +++ b/apps/web/components/settings/system/storage/storage-totals.test.ts @@ -1,5 +1,9 @@ import { describe, expect, it } from "vitest"; -import type { StorageQuarantineEntry, StorageSummary } from "@/lib/types/system"; +import type { + StorageQuarantineEntry, + StorageSummary, + StorageSummaryPartial, +} from "@/lib/types/system"; import { quarantineTotalBytes, storageAnalysisTotal } from "./storage-totals"; const completeSummary: StorageSummary = { @@ -78,6 +82,15 @@ describe("storageAnalysisTotal", () => { expect(storageAnalysisTotal(summary)).toEqual({ bytes: 45, partial: false }); }); + + it("sums only completed values in a partial first-scan summary", () => { + const summary: StorageSummaryPartial = { + workspaces: { total_bytes: 12 }, + quarantine: null, + }; + + expect(storageAnalysisTotal(summary)).toEqual({ bytes: 12, partial: true }); + }); }); describe("quarantineTotalBytes", () => { diff --git a/apps/web/components/settings/system/storage/storage-totals.ts b/apps/web/components/settings/system/storage/storage-totals.ts index fb4e80af32..93cd8dc4b3 100644 --- a/apps/web/components/settings/system/storage/storage-totals.ts +++ b/apps/web/components/settings/system/storage/storage-totals.ts @@ -1,4 +1,8 @@ -import type { StorageQuarantineEntry, StorageSummary } from "@/lib/types/system"; +import type { + StorageQuarantineEntry, + StorageSummary, + StorageSummaryPartial, +} from "@/lib/types/system"; export interface StorageAnalysisTotal { bytes: number; @@ -9,7 +13,9 @@ function isMeasuredBytes(value: number | undefined): value is number { return value !== undefined && Number.isFinite(value) && value >= 0; } -export function storageAnalysisTotal(summary: StorageSummary): StorageAnalysisTotal { +export function storageAnalysisTotal( + summary: StorageSummary | StorageSummaryPartial, +): StorageAnalysisTotal { const total: StorageAnalysisTotal = { bytes: 0, partial: false }; const addMeasurement = (value: number | undefined, available = true) => { if (!available || !isMeasuredBytes(value)) { @@ -19,20 +25,27 @@ export function storageAnalysisTotal(summary: StorageSummary): StorageAnalysisTo total.bytes += value; }; - addMeasurement(summary.workspaces.total_bytes, summary.workspaces.available !== false); addMeasurement( - summary.quarantine.available === false ? undefined : summary.quarantine.size_bytes, + summary.workspaces?.total_bytes, + summary.workspaces != null && summary.workspaces.available !== false, ); - addMeasurement(summary.go_cache.size_bytes, summary.go_cache.available !== false); - if (summary.go_cache.unmanaged_path) { + addMeasurement( + summary.quarantine?.available === false ? undefined : summary.quarantine?.size_bytes, + summary.quarantine != null && summary.quarantine.available !== false, + ); + addMeasurement( + summary.go_cache?.size_bytes, + summary.go_cache != null && summary.go_cache.available !== false, + ); + if (summary.go_cache?.unmanaged_path) { addMeasurement(summary.go_cache.unmanaged_size_bytes); } addMeasurement( - summary.temporary_artifacts.total_bytes, - summary.temporary_artifacts.available !== false, + summary.temporary_artifacts?.total_bytes, + summary.temporary_artifacts != null && summary.temporary_artifacts.available !== false, ); - if (summary.docker.available) { + if (summary.docker?.available) { addMeasurement(summary.docker.managed_container_bytes); addMeasurement(summary.docker.image_layer_bytes); addMeasurement(summary.docker.build_cache_bytes); diff --git a/apps/web/e2e/helpers/storage-maintenance.ts b/apps/web/e2e/helpers/storage-maintenance.ts index b6da931739..ad4a4c5867 100644 --- a/apps/web/e2e/helpers/storage-maintenance.ts +++ b/apps/web/e2e/helpers/storage-maintenance.ts @@ -33,9 +33,10 @@ export async function mockTemporaryArtifactOverview(page: Page): Promise { }); const body = JSON.parse(await response.text()) as { capabilities: Record; - summary: Record; + summary: Record | null; }; body.capabilities.temporary_artifacts_available = true; + body.summary ??= {}; body.summary.temporary_artifacts = { available: true, total_count: 3, @@ -55,3 +56,144 @@ export async function mockTemporaryArtifactOverview(page: Page): Promise { }); }); } + +export async function mockProgressiveStorageOverview(page: Page): Promise<{ + complete: () => void; +}> { + let completed = false; + await page.route("**/api/v1/system/storage", async (route) => { + if (route.request().method() !== "GET") { + await route.continue(); + return; + } + const requestHeaders = route.request().headers(); + const response = await fetch(route.request().url(), { + headers: { + ...(requestHeaders.accept ? { accept: requestHeaders.accept } : {}), + ...(requestHeaders.cookie ? { cookie: requestHeaders.cookie } : {}), + }, + }); + const body = JSON.parse(await response.text()) as { + analysis?: unknown; + analyzed_at?: string | null; + capabilities?: Record; + summary?: Record | null; + }; + const startedAt = new Date(Date.now() - 1200).toISOString(); + const completedAt = new Date(Date.now()).toISOString(); + const refreshDueAt = new Date(Date.now() + 15 * 60 * 1000).toISOString(); + const sourceProgress = { + workspaces: { + state: "ready", + completed_items: 3, + total_items: 3, + bytes_scanned: 2 * 1024 ** 3, + }, + go_cache: { + state: "ready", + completed_items: 4, + total_items: 4, + bytes_scanned: 3 * 1024 ** 3, + }, + quarantine: { state: "ready", completed_items: 1, total_items: 1, bytes_scanned: 1024 }, + temporary_artifacts: { + state: "ready", + completed_items: 1, + total_items: 1, + bytes_scanned: 1024, + }, + docker: { state: "ready", completed_items: 1, total_items: 1, bytes_scanned: 1024 }, + }; + body.analysis = completed + ? { + generation: 901, + state: "ready", + started_at: startedAt, + completed_at: completedAt, + duration_ms: 1200, + cache_ttl_seconds: 900, + refresh_due_at: refreshDueAt, + stale: false, + error: null, + progress: { completed_sources: 5, total_sources: 5, sources: sourceProgress }, + partial_summary: null, + } + : { + generation: 901, + state: "scanning", + started_at: startedAt, + completed_at: null, + duration_ms: null, + cache_ttl_seconds: 900, + refresh_due_at: null, + stale: false, + error: null, + progress: { + completed_sources: 1, + total_sources: 5, + sources: { + ...sourceProgress, + go_cache: { + state: "scanning", + completed_items: 1, + total_items: 4, + bytes_scanned: 10, + }, + quarantine: { state: "pending", completed_items: 0, bytes_scanned: 0 }, + temporary_artifacts: { state: "pending", completed_items: 0, bytes_scanned: 0 }, + docker: { state: "pending", completed_items: 0, bytes_scanned: 0 }, + }, + }, + partial_summary: { + workspaces: { + total_bytes: 2 * 1024 ** 3, + active_bytes: 1 * 1024 ** 3, + candidate_bytes: 1 * 1024 ** 3, + }, + }, + }; + body.summary = completed + ? { + workspaces: { + total_bytes: 4 * 1024 ** 3, + active_bytes: 1 * 1024 ** 3, + candidate_bytes: 2 * 1024 ** 3, + }, + go_cache: { + path: "/data/cache/go-build", + size_bytes: 3 * 1024 ** 3, + owned: true, + enabled: false, + }, + quarantine: { available: true, count: 1, size_bytes: 1024 }, + temporary_artifacts: { + available: true, + total_count: 1, + total_bytes: 1024, + active_count: 1, + active_bytes: 1024, + protected_count: 1, + protected_bytes: 1024, + stale_count: 0, + stale_bytes: 0, + skipped_count: 0, + }, + docker: { + available: false, + build_cache_bytes: 0, + image_layer_bytes: 0, + unused_image_bytes: 0, + managed_container_count: 0, + managed_container_bytes: 0, + }, + } + : null; + body.analyzed_at = completed ? completedAt : null; + await route.fulfill({ + status: response.status, + contentType: "application/json", + body: JSON.stringify(body), + }); + }); + return { complete: () => (completed = true) }; +} diff --git a/apps/web/e2e/tests/system/mobile-storage-maintenance.spec.ts b/apps/web/e2e/tests/system/mobile-storage-maintenance.spec.ts index 805c74eb4d..b77e66a18c 100644 --- a/apps/web/e2e/tests/system/mobile-storage-maintenance.spec.ts +++ b/apps/web/e2e/tests/system/mobile-storage-maintenance.spec.ts @@ -3,6 +3,7 @@ import path from "node:path"; import type { Route } from "@playwright/test"; import { test, expect } from "../../fixtures/test-base"; import { + mockProgressiveStorageOverview, mockTemporaryArtifactOverview, seedManagedGoCache, } from "../../helpers/storage-maintenance"; @@ -247,6 +248,36 @@ test.describe("Mobile storage maintenance", () => { } }); + test("opens progressive analysis timing by touch without overflow", async ({ + testPage, + prCapture, + }) => { + const progressive = await mockProgressiveStorageOverview(testPage); + await testPage.goto("/settings/system/storage"); + + await expect(testPage.getByTestId("storage-analysis-total")).toContainText("Counted so far"); + progressive.complete(); + await expect(testPage.getByTestId("storage-analysis-total")).toContainText("Total counted"); + const timingHelp = testPage.getByTestId("storage-analysis-timing-help"); + const box = await timingHelp.boundingBox(); + expect(box).not.toBeNull(); + expect(box!.width).toBeGreaterThanOrEqual(44); + expect(box!.height).toBeGreaterThanOrEqual(44); + if (prCapture.capturing) { + await timingHelp.evaluate((element) => + element.scrollIntoView({ block: "center", inline: "nearest" }), + ); + } + await timingHelp.tap(); + await expect(testPage.getByRole("tooltip")).toContainText("Scan duration"); + await prCapture.screenshot("progressive-analysis-timing", { + caption: "Mobile storage opens progressive scan timing by touch", + }); + expect( + await testPage.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth), + ).toBe(true); + }); + test("keeps both quarantine cleanup actions reachable on a phone", async ({ testPage, prCapture, diff --git a/apps/web/e2e/tests/system/storage-maintenance.spec.ts b/apps/web/e2e/tests/system/storage-maintenance.spec.ts index 6f122126eb..899f82feff 100644 --- a/apps/web/e2e/tests/system/storage-maintenance.spec.ts +++ b/apps/web/e2e/tests/system/storage-maintenance.spec.ts @@ -3,6 +3,7 @@ import path from "node:path"; import type { Route } from "@playwright/test"; import { test, expect } from "../../fixtures/test-base"; import { + mockProgressiveStorageOverview, mockTemporaryArtifactOverview, seedManagedGoCache, } from "../../helpers/storage-maintenance"; @@ -229,12 +230,43 @@ test.describe("System storage maintenance", () => { } }); + test("shows progressive source values and timing disclosure", async ({ testPage, prCapture }) => { + const progressive = await mockProgressiveStorageOverview(testPage); + await testPage.goto("/settings/system/storage"); + + await expect(testPage.getByTestId("storage-analysis-total")).toContainText("Counted so far"); + await expect(testPage.getByTestId("storage-analysis-source-go_cache")).toContainText( + "Measuring 1 of 4", + ); + await expect(testPage.getByTestId("storage-analysis-source-quarantine")).toContainText( + "Waiting to measure", + ); + + progressive.complete(); + await expect(testPage.getByTestId("storage-analysis-total")).toContainText("Total counted"); + const timingHelp = testPage.getByTestId("storage-analysis-timing-help"); + await timingHelp.focus(); + await expect( + testPage.locator('[data-slot="tooltip-content"]:not([data-state="closed"])'), + ).toContainText("Scan duration"); + await testPage.mouse.move(4, 4); + await timingHelp.click(); + await expect( + testPage.locator('[data-slot="tooltip-content"]:not([data-state="closed"])'), + ).toContainText("Analyze refreshes this data immediately"); + await prCapture.screenshot("progressive-analysis", { + caption: "Desktop storage shows counted-so-far progress and scan timing", + }); + }); + test("persists policy and analyzes, quarantines, and restores an orphan workspace", async ({ testPage, backend, }) => { const orphan = seedOrphanWorkspace(backend.tmpDir); await testPage.goto("/settings/system/storage"); + await expect(testPage.getByTestId("storage-overview-card")).toBeVisible(); + await expect(testPage.getByTestId("storage-policy-card")).toBeVisible(); const overviewBox = await testPage.getByTestId("storage-overview-card").boundingBox(); const policyBox = await testPage.getByTestId("storage-policy-card").boundingBox(); expect(overviewBox).not.toBeNull(); diff --git a/apps/web/hooks/domains/system/use-storage-maintenance-terminal-refresh.test.tsx b/apps/web/hooks/domains/system/use-storage-maintenance-terminal-refresh.test.tsx new file mode 100644 index 0000000000..1eb4d1d88e --- /dev/null +++ b/apps/web/hooks/domains/system/use-storage-maintenance-terminal-refresh.test.tsx @@ -0,0 +1,162 @@ +import { act, renderHook, waitFor } from "@testing-library/react"; +import { beforeEach, describe, expect, it, vi } from "vitest"; +import type { StorageMaintenanceSettings } from "@/lib/types/system"; +import { + cleanupJob, + cleanupJobId, + disk, + overview, + settings, + wrapper, +} from "./use-storage-maintenance.test-fixtures"; + +const mocks = vi.hoisted(() => ({ + adopt: vi.fn(), + analyze: vi.fn(), + deleteEntry: vi.fn(), + purge: vi.fn(), + fetchJob: vi.fn(), + fetchOverview: vi.fn(), + fetchDisk: vi.fn(), + fetchPolicy: vi.fn(), + fetchQuarantine: vi.fn(), + fetchRuns: vi.fn(), + restore: vi.fn(), + run: vi.fn(), + save: vi.fn(), + toast: vi.fn(), +})); + +vi.mock("@/components/toast-provider", () => ({ + useToast: () => ({ toast: mocks.toast }), +})); + +vi.mock("@/lib/api/domains/system-api", () => ({ + adoptStorageGoCache: mocks.adopt, + analyzeStorage: mocks.analyze, + deleteStorageQuarantine: mocks.deleteEntry, + purgeStorageQuarantine: mocks.purge, + fetchSystemJob: mocks.fetchJob, + fetchStorageOverview: mocks.fetchOverview, + fetchStorageDisk: mocks.fetchDisk, + fetchStoragePolicy: mocks.fetchPolicy, + fetchStorageQuarantine: mocks.fetchQuarantine, + fetchStorageRuns: mocks.fetchRuns, + restoreStorageQuarantine: mocks.restore, + runStorageMaintenance: mocks.run, + saveStorageSettings: mocks.save, +})); + +import { useStorageMaintenance } from "./use-storage-maintenance"; + +beforeEach(() => { + vi.clearAllMocks(); + mocks.fetchOverview.mockResolvedValue(overview); + mocks.fetchDisk.mockResolvedValue(disk); + mocks.fetchPolicy.mockResolvedValue({ + settings: overview.settings, + capabilities: overview.capabilities, + }); + mocks.fetchRuns.mockResolvedValue([]); + mocks.fetchQuarantine.mockResolvedValue([]); + mocks.fetchJob.mockResolvedValue(cleanupJob); + mocks.save.mockResolvedValue({ settings } satisfies { settings: StorageMaintenanceSettings }); + mocks.run.mockResolvedValue({ job_id: cleanupJobId }); + mocks.purge.mockResolvedValue({ job_id: "purge-job" }); +}); + +describe("useStorageMaintenance terminal refresh", () => { + it("surfaces and retries a failed refresh after a cleanup job finishes", async () => { + mocks.fetchJob.mockResolvedValue({ + ...cleanupJob, + state: "succeeded", + ended_at: "2026-07-15T00:01:00Z", + }); + const { result } = renderHook(() => useStorageMaintenance(), { wrapper }); + await waitFor(() => expect(result.current.overview).toEqual(overview)); + mocks.fetchOverview.mockRejectedValueOnce(new Error("refresh unavailable")); + + await act(async () => { + await result.current.runNow(); + }); + + await waitFor(() => expect(String(result.current.error)).toContain("refresh unavailable")); + await waitFor(() => expect(mocks.fetchOverview).toHaveBeenCalledTimes(3), { timeout: 2500 }); + await waitFor(() => expect(result.current.error).toBeNull()); + }); + + it("backs off and stops after six terminal refresh attempts", async () => { + vi.useFakeTimers(); + try { + mocks.fetchJob.mockResolvedValue({ + ...cleanupJob, + state: "succeeded", + ended_at: "2026-07-15T00:01:00Z", + }); + const { result } = renderHook(() => useStorageMaintenance(), { wrapper }); + await act(async () => { + await Promise.resolve(); + }); + expect(result.current.overview).toEqual(overview); + + mocks.fetchOverview.mockRejectedValue(new Error("refresh unavailable")); + await act(async () => { + await result.current.runNow(); + await vi.advanceTimersByTimeAsync(0); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(2); + + await act(async () => { + await vi.advanceTimersByTimeAsync(999); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(2); + await act(async () => { + await vi.advanceTimersByTimeAsync(1); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(3); + + await act(async () => { + await vi.advanceTimersByTimeAsync(1999); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(3); + await act(async () => { + await vi.advanceTimersByTimeAsync(1); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(4); + + await act(async () => { + await vi.advanceTimersByTimeAsync(3999); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(4); + await act(async () => { + await vi.advanceTimersByTimeAsync(1); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(5); + + await act(async () => { + await vi.advanceTimersByTimeAsync(7999); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(5); + await act(async () => { + await vi.advanceTimersByTimeAsync(1); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(6); + + await act(async () => { + await vi.advanceTimersByTimeAsync(7999); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(6); + await act(async () => { + await vi.advanceTimersByTimeAsync(1); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(7); + + await act(async () => { + await vi.advanceTimersByTimeAsync(60000); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(7); + } finally { + vi.useRealTimers(); + } + }); +}); diff --git a/apps/web/hooks/domains/system/use-storage-maintenance.test-fixtures.tsx b/apps/web/hooks/domains/system/use-storage-maintenance.test-fixtures.tsx new file mode 100644 index 0000000000..4b33e4f233 --- /dev/null +++ b/apps/web/hooks/domains/system/use-storage-maintenance.test-fixtures.tsx @@ -0,0 +1,112 @@ +import type { ReactNode } from "react"; +import { StateProvider } from "@/components/state-provider"; +import type { + StorageAnalysisState, + StorageMaintenanceSettings, + StorageOverviewResponse, +} from "@/lib/types/system"; + +export const settings: StorageMaintenanceSettings = { + enabled: false, + check_interval_hours: 24, + idle_for_minutes: 10, + orphan_grace_hours: 168, + quarantine_retention_hours: 168, + workspaces: { enabled: true, dependency_cleanup_enabled: false }, + kandev_containers: { enabled: true }, + go_cache: { enabled: false, max_bytes: 16106127360, adopted_path: "" }, + docker: { + dedicated_daemon_acknowledged: true, + build_cache_enabled: true, + build_cache_keep_bytes: 10737418240, + build_cache_unused_hours: 168, + unused_images_enabled: true, + unused_images_hours: 168, + }, +}; + +export const overview: StorageOverviewResponse = { + settings, + capabilities: { + managed_go_cache_path: "/data/cache/go-build", + go_cache_adoption_available: true, + temporary_artifacts_available: true, + docker_available: true, + docker_host: "unix:///var/run/docker.sock", + host_global_docker_cleanup_allowed: true, + }, + summary: { + workspaces: { active_bytes: 10, candidate_bytes: 20 }, + go_cache: { path: "/data/cache/go-build", size_bytes: 30, owned: true, enabled: false }, + quarantine: { count: 2, size_bytes: 35 }, + temporary_artifacts: { + available: true, + total_count: 0, + total_bytes: 0, + active_count: 0, + active_bytes: 0, + protected_count: 0, + protected_bytes: 0, + stale_count: 0, + stale_bytes: 0, + skipped_count: 0, + }, + docker: { + available: true, + build_cache_bytes: 40, + unused_image_bytes: 50, + managed_container_count: 3, + managed_container_bytes: 60, + }, + }, + analysis: { + generation: 1, + state: "ready", + started_at: "2026-07-23T11:59:00Z", + completed_at: "2026-07-23T12:00:00Z", + duration_ms: 60000, + cache_ttl_seconds: 900, + refresh_due_at: "2099-07-23T12:15:00Z", + stale: false, + error: null, + progress: { completed_sources: 5, total_sources: 5, sources: {} }, + partial_summary: null, + } satisfies StorageAnalysisState, + analyzed_at: "2026-07-23T12:00:00Z", + last_run: null, +}; + +export const disk = { + path: "/data", + total_bytes: 100, + used_bytes: 80, + available_bytes: 20, + used_percent: 80, + available: true, +}; + +export const cleanupJobId = "cleanup-job"; +export const cleanupJob = { + id: cleanupJobId, + kind: "storage-cleanup", + state: "running", + started_at: "2026-07-15T00:00:00Z", +}; +// i18n-exempt: test-only busy-error payload +export const STORAGE_BUSY_ERROR_MESSAGE = "storage cleanup is blocked by active Kandev work"; +// i18n-exempt: test-only busy-resource label +export const TEST_COMMAND_BUSY_LABEL = "A test command is running"; + +export function deferred() { + let resolve!: (value: T) => void; + let reject!: (reason?: unknown) => void; + const promise = new Promise((resolvePromise, rejectPromise) => { + resolve = resolvePromise; + reject = rejectPromise; + }); + return { promise, resolve, reject }; +} + +export function wrapper({ children }: { children: ReactNode }) { + return {children}; +} diff --git a/apps/web/hooks/domains/system/use-storage-maintenance.test.tsx b/apps/web/hooks/domains/system/use-storage-maintenance.test.tsx index 2982f1e30c..2e3bbc6268 100644 --- a/apps/web/hooks/domains/system/use-storage-maintenance.test.tsx +++ b/apps/web/hooks/domains/system/use-storage-maintenance.test.tsx @@ -1,13 +1,24 @@ import type { ReactNode } from "react"; import { act, renderHook, waitFor } from "@testing-library/react"; import { beforeEach, describe, expect, it, vi } from "vitest"; -import { StateProvider } from "@/components/state-provider"; +import { StateProvider, useAppStoreApi } from "@/components/state-provider"; import { ApiError } from "@/lib/api/client"; import type { StorageMaintenanceSettings, StorageOverviewResponse, StoragePolicyResponse, } from "@/lib/types/system"; +import { + cleanupJob, + cleanupJobId, + deferred, + disk, + overview, + settings, + STORAGE_BUSY_ERROR_MESSAGE, + TEST_COMMAND_BUSY_LABEL, + wrapper, +} from "./use-storage-maintenance.test-fixtures"; const mocks = vi.hoisted(() => ({ adopt: vi.fn(), @@ -51,96 +62,6 @@ import { useStorageMaintenance, } from "./use-storage-maintenance"; -const settings: StorageMaintenanceSettings = { - enabled: false, - check_interval_hours: 24, - idle_for_minutes: 10, - orphan_grace_hours: 168, - quarantine_retention_hours: 168, - workspaces: { enabled: true, dependency_cleanup_enabled: false }, - kandev_containers: { enabled: true }, - go_cache: { enabled: false, max_bytes: 16106127360, adopted_path: "" }, - docker: { - dedicated_daemon_acknowledged: true, - build_cache_enabled: true, - build_cache_keep_bytes: 10737418240, - build_cache_unused_hours: 168, - unused_images_enabled: true, - unused_images_hours: 168, - }, -}; - -const overview: StorageOverviewResponse = { - settings, - capabilities: { - managed_go_cache_path: "/data/cache/go-build", - go_cache_adoption_available: true, - temporary_artifacts_available: true, - docker_available: true, - docker_host: "unix:///var/run/docker.sock", - host_global_docker_cleanup_allowed: true, - }, - summary: { - workspaces: { active_bytes: 10, candidate_bytes: 20 }, - go_cache: { path: "/data/cache/go-build", size_bytes: 30, owned: true, enabled: false }, - quarantine: { count: 2, size_bytes: 35 }, - temporary_artifacts: { - available: true, - total_count: 0, - total_bytes: 0, - active_count: 0, - active_bytes: 0, - protected_count: 0, - protected_bytes: 0, - stale_count: 0, - stale_bytes: 0, - skipped_count: 0, - }, - docker: { - available: true, - build_cache_bytes: 40, - unused_image_bytes: 50, - managed_container_count: 3, - managed_container_bytes: 60, - }, - }, - analyzed_at: "2026-07-23T12:00:00Z", - last_run: null, -}; - -const disk = { - path: "/data", - total_bytes: 100, - used_bytes: 80, - available_bytes: 20, - used_percent: 80, - available: true, -}; - -const cleanupJobId = "cleanup-job"; -const cleanupJob = { - id: cleanupJobId, - kind: "storage-cleanup", - state: "running", - started_at: "2026-07-15T00:00:00Z", -}; -const STORAGE_BUSY_ERROR_MESSAGE = "storage cleanup is blocked by active Kandev work"; -const TEST_COMMAND_BUSY_LABEL = "A test command is running"; - -function deferred() { - let resolve!: (value: T) => void; - let reject!: (reason?: unknown) => void; - const promise = new Promise((resolvePromise, rejectPromise) => { - resolve = resolvePromise; - reject = rejectPromise; - }); - return { promise, resolve, reject }; -} - -function wrapper({ children }: { children: ReactNode }) { - return {children}; -} - beforeEach(() => { vi.clearAllMocks(); mocks.fetchOverview.mockResolvedValue(overview); @@ -158,7 +79,7 @@ beforeEach(() => { mocks.purge.mockResolvedValue({ job_id: "purge-job" }); }); -describe("useStorageMaintenance", () => { +describe("useStorageMaintenance loading", () => { it("publishes fast sections before a cold overview scan finishes", async () => { const overviewRequest = deferred(); mocks.fetchOverview.mockReturnValueOnce(overviewRequest.promise); @@ -191,7 +112,118 @@ describe("useStorageMaintenance", () => { expect(mocks.fetchDisk).toHaveBeenCalledTimes(1); expect(result.current.pendingAction).toBeNull(); }); +}); +describe("useStorageMaintenance analysis updates", () => { + it("reloads only the overview when a live analysis event advances the revision", async () => { + let bumpRevision: (() => void) | undefined; + function CaptureRevisionAction() { + bumpRevision = useAppStoreApi().getState().bumpSystemStorageAnalysisRevision; + return null; + } + const capturedWrapper = ({ children }: { children: ReactNode }) => ( + + + {children} + + ); + const { result } = renderHook(() => useStorageMaintenance(), { wrapper: capturedWrapper }); + await waitFor(() => expect(result.current.overview).toEqual(overview)); + mocks.fetchOverview.mockClear(); + mocks.fetchPolicy.mockClear(); + mocks.fetchDisk.mockClear(); + mocks.fetchRuns.mockClear(); + mocks.fetchQuarantine.mockClear(); + + await act(async () => { + bumpRevision?.(); + await Promise.resolve(); + }); + await waitFor(() => expect(mocks.fetchOverview).toHaveBeenCalledTimes(1)); + expect(mocks.fetchPolicy).not.toHaveBeenCalled(); + expect(mocks.fetchDisk).not.toHaveBeenCalled(); + expect(mocks.fetchRuns).not.toHaveBeenCalled(); + expect(mocks.fetchQuarantine).not.toHaveBeenCalled(); + }); + + it("polls a scanning overview every 1.5 seconds and stops after completion", async () => { + vi.useFakeTimers(); + try { + const scanning = { + ...overview, + summary: null, + analyzed_at: null, + analysis: { ...overview.analysis, state: "scanning" as const }, + }; + mocks.fetchOverview.mockReset().mockResolvedValueOnce(scanning).mockResolvedValue(overview); + const { result } = renderHook(() => useStorageMaintenance(), { wrapper }); + await act(async () => { + await Promise.resolve(); + await Promise.resolve(); + }); + expect(result.current.overview?.analysis.state).toBe("scanning"); + mocks.fetchOverview.mockClear(); + + await act(async () => { + await vi.advanceTimersByTimeAsync(1499); + }); + expect(mocks.fetchOverview).not.toHaveBeenCalled(); + await act(async () => { + await vi.advanceTimersByTimeAsync(1); + await Promise.resolve(); + await Promise.resolve(); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(1); + expect(result.current.overview?.analysis.state).toBe("ready"); + mocks.fetchOverview.mockClear(); + await act(async () => { + await vi.advanceTimersByTimeAsync(3000); + }); + expect(mocks.fetchOverview).not.toHaveBeenCalled(); + } finally { + vi.useRealTimers(); + } + }); +}); + +describe("useStorageMaintenance analysis refresh", () => { + it("requests a new overview when its refresh deadline arrives", async () => { + vi.useFakeTimers(); + try { + vi.setSystemTime(new Date("2026-07-23T12:00:00Z")); + const dueOverview = { + ...overview, + analysis: { + ...overview.analysis, + refresh_due_at: "2026-07-23T12:00:00.500Z", + }, + }; + mocks.fetchOverview.mockReset().mockResolvedValue(dueOverview); + const { result } = renderHook(() => useStorageMaintenance(), { wrapper }); + await act(async () => { + await Promise.resolve(); + await Promise.resolve(); + }); + expect(result.current.overview).toEqual(dueOverview); + mocks.fetchOverview.mockClear(); + + await act(async () => { + await vi.advanceTimersByTimeAsync(499); + }); + expect(mocks.fetchOverview).not.toHaveBeenCalled(); + await act(async () => { + await vi.advanceTimersByTimeAsync(1); + await Promise.resolve(); + await Promise.resolve(); + }); + expect(mocks.fetchOverview).toHaveBeenCalledTimes(1); + } finally { + vi.useRealTimers(); + } + }); +}); + +describe("useStorageMaintenance actions", () => { it("owns confirmed settings persistence and success feedback", async () => { const { result } = renderHook(() => useStorageMaintenance(), { wrapper }); await waitFor(() => expect(result.current.overview).toEqual(overview)); @@ -430,102 +462,6 @@ describe("useStorageMaintenance pending action tracking", () => { }); }); -describe("useStorageMaintenance terminal refresh", () => { - it("surfaces and retries a failed refresh after a cleanup job finishes", async () => { - mocks.fetchJob.mockResolvedValue({ - ...cleanupJob, - state: "succeeded", - ended_at: "2026-07-15T00:01:00Z", - }); - const { result } = renderHook(() => useStorageMaintenance(), { wrapper }); - await waitFor(() => expect(result.current.overview).toEqual(overview)); - mocks.fetchOverview.mockRejectedValueOnce(new Error("refresh unavailable")); - - await act(async () => { - await result.current.runNow(); - }); - - await waitFor(() => expect(String(result.current.error)).toContain("refresh unavailable")); - await waitFor(() => expect(mocks.fetchOverview).toHaveBeenCalledTimes(3), { timeout: 2500 }); - await waitFor(() => expect(result.current.error).toBeNull()); - }); - - it("backs off and stops after six terminal refresh attempts", async () => { - vi.useFakeTimers(); - try { - mocks.fetchJob.mockResolvedValue({ - ...cleanupJob, - state: "succeeded", - ended_at: "2026-07-15T00:01:00Z", - }); - const { result } = renderHook(() => useStorageMaintenance(), { wrapper }); - await act(async () => { - await Promise.resolve(); - }); - expect(result.current.overview).toEqual(overview); - - mocks.fetchOverview.mockRejectedValue(new Error("refresh unavailable")); - await act(async () => { - await result.current.runNow(); - await vi.advanceTimersByTimeAsync(0); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(2); - - await act(async () => { - await vi.advanceTimersByTimeAsync(999); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(2); - await act(async () => { - await vi.advanceTimersByTimeAsync(1); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(3); - - await act(async () => { - await vi.advanceTimersByTimeAsync(1999); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(3); - await act(async () => { - await vi.advanceTimersByTimeAsync(1); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(4); - - await act(async () => { - await vi.advanceTimersByTimeAsync(3999); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(4); - await act(async () => { - await vi.advanceTimersByTimeAsync(1); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(5); - - await act(async () => { - await vi.advanceTimersByTimeAsync(7999); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(5); - await act(async () => { - await vi.advanceTimersByTimeAsync(1); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(6); - - await act(async () => { - await vi.advanceTimersByTimeAsync(7999); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(6); - await act(async () => { - await vi.advanceTimersByTimeAsync(1); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(7); - - await act(async () => { - await vi.advanceTimersByTimeAsync(60000); - }); - expect(mocks.fetchOverview).toHaveBeenCalledTimes(7); - } finally { - vi.useRealTimers(); - } - }); -}); - describe("useStorageMaintenance reload ordering", () => { it("does not let an older reload overwrite a newer result", async () => { const { result } = renderHook(() => useStorageMaintenance(), { wrapper }); diff --git a/apps/web/hooks/domains/system/use-storage-maintenance.ts b/apps/web/hooks/domains/system/use-storage-maintenance.ts index d666a468b1..643d35030a 100644 --- a/apps/web/hooks/domains/system/use-storage-maintenance.ts +++ b/apps/web/hooks/domains/system/use-storage-maintenance.ts @@ -36,6 +36,7 @@ import type { StorageBusyResource, StorageBusyResponse, StorageMaintenanceSettings, + StorageOverviewResponse, StoragePolicyResponse, StorageQuarantinePurgeScope, SystemJob, @@ -105,6 +106,8 @@ type SetStorageError = Dispatch>; const TERMINAL_REFRESH_RETRY_MS = 1000; const TERMINAL_REFRESH_MAX_RETRY_MS = 8000; const MAX_TERMINAL_REFRESH_ATTEMPTS = 6; +const STORAGE_ANALYSIS_POLL_MS = 1500; +const MAX_BROWSER_TIMEOUT_MS = 2_147_483_647; function useStorageActionRunner() { const { toast } = useToast(); @@ -373,8 +376,75 @@ function useReloadCompletedJobs( useTerminalJobRefresh(reload, setError, deleteJob); } +function useStorageAnalysisUpdates(analysisRevision: number, reload: Reload) { + const previousRevision = useRef(analysisRevision); + useEffect(() => { + if (previousRevision.current === analysisRevision) return; + previousRevision.current = analysisRevision; + void reload(["overview"]).catch(() => undefined); + }, [analysisRevision, reload]); +} + +function useStorageAnalysisPolling( + analysisState: string | undefined, + analysisGeneration: number | undefined, + reload: Reload, +) { + useEffect(() => { + if (analysisState !== "scanning") return; + const timer = setInterval(() => { + void reload(["overview"]).catch(() => undefined); + }, STORAGE_ANALYSIS_POLL_MS); + return () => clearInterval(timer); + }, [analysisGeneration, analysisState, reload]); +} + +function useStorageAnalysisRefreshSchedule( + analysisState: string | undefined, + refreshDueAt: string | null | undefined, + reload: Reload, +) { + useEffect(() => { + if (!refreshDueAt || analysisState === "scanning") return; + const dueAt = Date.parse(refreshDueAt); + if (!Number.isFinite(dueAt)) return; + const delay = Math.max(0, dueAt - Date.now()); + if (delay > MAX_BROWSER_TIMEOUT_MS) return; + const timer = setTimeout(() => { + void reload(["overview"]).catch(() => undefined); + }, delay); + return () => clearTimeout(timer); + }, [analysisState, refreshDueAt, reload]); +} + +function useStorageMaintenanceEffects( + reload: Reload, + setError: SetStorageError, + actions: ReturnType, + analysisRevision: number, + overview: StorageOverviewResponse | null, +) { + useEffect(() => { + void reload().catch(() => undefined); + }, [reload]); + const analysisState = overview?.analysis.state; + const analysisGeneration = overview?.analysis.generation; + const refreshDueAt = overview?.analysis.refresh_due_at; + useStorageAnalysisUpdates(analysisRevision, reload); + useStorageAnalysisPolling(analysisState, analysisGeneration, reload); + useStorageAnalysisRefreshSchedule(analysisState, refreshDueAt, reload); + useReloadCompletedJobs( + reload, + actions.setError, + actions.analysisJob, + actions.cleanupJob, + actions.deleteJob, + ); +} + export function useStorageMaintenance() { const storage = useAppStore((state) => state.system.storage); + const analysisRevision = useAppStore((state) => state.system.storage.analysisRevision); const setPolicy = useAppStore((state) => state.setSystemStoragePolicy); const setOverview = useAppStore((state) => state.setSystemStorageOverview); const setDisk = useAppStore((state) => state.setSystemStorageDisk); @@ -459,16 +529,12 @@ export function useStorageMaintenance() { [setPolicy], ); const actions = useStorageActions(reload, commitAdoptedPolicy); - - useEffect(() => { - void reload().catch(() => undefined); - }, [reload]); - useReloadCompletedJobs( + useStorageMaintenanceEffects( reload, actions.setError, - actions.analysisJob, - actions.cleanupJob, - actions.deleteJob, + actions, + analysisRevision, + storage.overview, ); return { ...storage, ...actions, loading, sectionErrors, reload }; } diff --git a/apps/web/lib/state/slices/system/system-slice.test.ts b/apps/web/lib/state/slices/system/system-slice.test.ts index 4aa0aba697..3d05d788a1 100644 --- a/apps/web/lib/state/slices/system/system-slice.test.ts +++ b/apps/web/lib/state/slices/system/system-slice.test.ts @@ -85,6 +85,20 @@ const JOB: SystemJob = { started_at: TS, }; +const ANALYSIS = { + generation: 1, + state: "ready", + started_at: TS, + completed_at: TS, + duration_ms: 10, + cache_ttl_seconds: 900, + refresh_due_at: "2026-05-18T00:15:00Z", + stale: false, + error: null, + progress: { completed_sources: 5, total_sources: 5, sources: {} }, + partial_summary: null, +} as const; + describe("system storage slice", () => { it("stores storage overview, runs, and quarantine state", () => { const store = makeStore(); @@ -131,6 +145,7 @@ describe("system storage slice", () => { managed_container_bytes: 0, }, }, + analysis: ANALYSIS, analyzed_at: "2026-07-23T12:00:00Z", last_run: null, } satisfies StorageOverviewResponse; @@ -142,6 +157,7 @@ describe("system storage slice", () => { expect(store.getState().system.storage).toEqual({ policy, overview, + analysisRevision: 0, disk: null, runs: [], quarantine: [], @@ -226,4 +242,12 @@ describe("system slice", () => { store.getState().clearSystemJob("does-not-exist"); expect(store.getState().system.jobs).toEqual({}); }); + + it("advances the storage analysis revision for live updates", () => { + const store = makeStore(); + expect(store.getState().system.storage.analysisRevision).toBe(0); + store.getState().bumpSystemStorageAnalysisRevision(); + store.getState().bumpSystemStorageAnalysisRevision(); + expect(store.getState().system.storage.analysisRevision).toBe(2); + }); }); diff --git a/apps/web/lib/state/slices/system/system-slice.ts b/apps/web/lib/state/slices/system/system-slice.ts index 1e228aed76..22ed5baeaa 100644 --- a/apps/web/lib/state/slices/system/system-slice.ts +++ b/apps/web/lib/state/slices/system/system-slice.ts @@ -10,7 +10,14 @@ export const defaultSystemState: SystemSliceState = { updates: null, jobs: {}, metrics: null, - storage: { policy: null, overview: null, disk: null, runs: [], quarantine: [] }, + storage: { + policy: null, + overview: null, + analysisRevision: 0, + disk: null, + runs: [], + quarantine: [], + }, }, }; @@ -65,6 +72,10 @@ export const createSystemSlice: StateCreator< set((draft) => { draft.system.storage.overview = overview; }), + bumpSystemStorageAnalysisRevision: () => + set((draft) => { + draft.system.storage.analysisRevision += 1; + }), setSystemStorageDisk: (disk) => set((draft) => { draft.system.storage.disk = disk; diff --git a/apps/web/lib/state/slices/system/types.ts b/apps/web/lib/state/slices/system/types.ts index 82e44f387a..7135fdaf36 100644 --- a/apps/web/lib/state/slices/system/types.ts +++ b/apps/web/lib/state/slices/system/types.ts @@ -32,6 +32,7 @@ export type SystemSliceState = { storage: { policy: StoragePolicyResponse | null; overview: StorageOverviewResponse | null; + analysisRevision: number; disk: StorageDiskCapacityResponse | null; runs: StorageMaintenanceRun[]; quarantine: StorageQuarantineEntry[]; @@ -50,6 +51,7 @@ export type SystemSliceActions = { setSystemMetricsSnapshot: (snapshot: SystemMetricsSnapshot) => void; setSystemStoragePolicy: (policy: StoragePolicyResponse) => void; setSystemStorageOverview: (overview: StorageOverviewResponse) => void; + bumpSystemStorageAnalysisRevision: () => void; setSystemStorageDisk: (disk: StorageDiskCapacityResponse) => void; setSystemStorageRuns: (runs: StorageMaintenanceRun[]) => void; setSystemStorageQuarantine: (entries: StorageQuarantineEntry[]) => void; diff --git a/apps/web/lib/types/backend.ts b/apps/web/lib/types/backend.ts index f71ca2548c..b142450340 100644 --- a/apps/web/lib/types/backend.ts +++ b/apps/web/lib/types/backend.ts @@ -40,7 +40,7 @@ import type { TaskMR } from "@/lib/types/gitlab"; import type { TaskStatusSummary } from "@/lib/types/task-status-summary"; import type { TaskMRAutomationOptions } from "@/lib/types/gitlab"; import type { AgentProfileRecentUseApiRecord } from "@/lib/types/http-agent-profile-recent-use"; -import type { SystemMetricsSnapshot } from "./system"; +import type { SystemMetricsSnapshot, StorageAnalysisUpdatedPayload } from "./system"; import type { AgentRuntimeAvailability } from "./agent-runtime"; import type { ExecutorPayload, @@ -445,6 +445,10 @@ export type BackendMessageMap = SessionBackendMessageMap & "diff.update": BackendMessage<"diff.update", DiffUpdatePayload>; "session.git.event": BackendMessage<"session.git.event", GitEventPayload>; "system.job.update": BackendMessage<"system.job.update", import("./system").SystemJob>; + "system.storage.analysis.updated": BackendMessage< + "system.storage.analysis.updated", + StorageAnalysisUpdatedPayload + >; "system.metrics.updated": BackendMessage<"system.metrics.updated", SystemMetricsSnapshot>; [SYSTEM_AGENT_RUNTIME_STATUS_CHANGED]: BackendMessage< typeof SYSTEM_AGENT_RUNTIME_STATUS_CHANGED, diff --git a/apps/web/lib/types/system.ts b/apps/web/lib/types/system.ts index e7977ec101..83f5562170 100644 --- a/apps/web/lib/types/system.ts +++ b/apps/web/lib/types/system.ts @@ -369,6 +369,50 @@ export interface StorageSummary { docker: StorageDockerSummary; } +export type StorageSummaryPartial = { + workspaces?: StorageWorkspaceSummary | null; + go_cache?: StorageGoCacheSummary | null; + quarantine?: StorageQuarantineSummary | null; + temporary_artifacts?: StorageTemporaryArtifactsSummary | null; + docker?: StorageDockerSummary | null; +}; + +export type StorageAnalysisStateName = "scanning" | "ready" | "failed"; +export type StorageSourceStateName = "pending" | "scanning" | "ready" | "failed"; + +export interface StorageSourceProgress { + state: StorageSourceStateName; + completed_items: number; + total_items?: number; + bytes_scanned: number; + error?: string; +} + +export interface StorageAnalysisProgress { + completed_sources: number; + total_sources: number; + sources: Record; +} + +export interface StorageAnalysisState { + generation: number; + state: StorageAnalysisStateName; + started_at: string | null; + completed_at: string | null; + duration_ms: number | null; + cache_ttl_seconds: number; + refresh_due_at: string | null; + stale: boolean; + error: string | null; + progress: StorageAnalysisProgress; + partial_summary: StorageSummaryPartial | null; +} + +export interface StorageAnalysisUpdatedPayload { + generation: number; + state: StorageAnalysisStateName; +} + export type StorageRunState = | "queued" | "running" @@ -438,8 +482,9 @@ export interface StorageQuarantinePurgeResult { export interface StorageOverviewResponse { settings: StorageMaintenanceSettings; capabilities: StorageCapabilities; - summary: StorageSummary; - analyzed_at: string; + summary: StorageSummary | null; + analyzed_at: string | null; + analysis: StorageAnalysisState; last_run: StorageMaintenanceRun | null; } diff --git a/apps/web/lib/ws/handlers/system-events.test.ts b/apps/web/lib/ws/handlers/system-events.test.ts index 3106b4ac16..eeef90a54e 100644 --- a/apps/web/lib/ws/handlers/system-events.test.ts +++ b/apps/web/lib/ws/handlers/system-events.test.ts @@ -13,6 +13,19 @@ const unavailable: AgentRuntimeAvailability = { const available: AgentRuntimeAvailability = { status: "available" }; describe("registerSystemEventsHandlers", () => { + it("bumps the storage revision when analysis progress is published", () => { + const store = createAppStore(); + const handlers = registerSystemEventsHandlers(store); + + handlers["system.storage.analysis.updated"]?.({ + type: "notification", + action: "system.storage.analysis.updated", + payload: { generation: 4, state: "scanning" }, + }); + + expect(store.getState().system.storage.analysisRevision).toBe(1); + }); + it("replaces the complete runtime snapshot without touching domain state", () => { const store = createAppStore({ agentRuntime: unavailable, diff --git a/apps/web/lib/ws/handlers/system-events.ts b/apps/web/lib/ws/handlers/system-events.ts index ea3a18b036..0139ef5821 100644 --- a/apps/web/lib/ws/handlers/system-events.ts +++ b/apps/web/lib/ws/handlers/system-events.ts @@ -12,6 +12,9 @@ export function registerSystemEventsHandlers(store: StoreApi): WsHandl // jobs map mirrors the latest queued/running/succeeded/failed state. store.getState().upsertSystemJob(message.payload); }, + "system.storage.analysis.updated": () => { + store.getState().bumpSystemStorageAnalysisRevision(); + }, "system.metrics.updated": (message) => { store.getState().setSystemMetricsSnapshot(message.payload); }, diff --git a/apps/web/src/locales/en/system.json b/apps/web/src/locales/en/system.json index 797fd7416a..b62679449b 100644 --- a/apps/web/src/locales/en/system.json +++ b/apps/web/src/locales/en/system.json @@ -276,8 +276,23 @@ "storageAnalysisComplete": "Analysis complete", "storageAnalysisDescription": "A read-only breakdown of current usage and reclaimable space. Run Analyze occasionally to refresh these estimates; it never deletes or moves anything.", "storageAnalysisFailed": "Analysis failed", + "storageAnalysisCacheLifetime": "Cache lifetime: {{duration}}", + "storageAnalysisDuration": "Scan duration: {{duration}}", + "storageAnalysisDurationMilliseconds": "{{value}} ms", + "storageAnalysisDurationMinutes": "{{value}} min", + "storageAnalysisDurationSeconds": "{{value}} sec", + "storageAnalysisNextRefresh": "Next refresh: {{absolute}} ({{relative}})", + "storageAnalysisNextRefreshUnknown": "Next refresh time is not available.", "storageAnalysisRunning": "Storage analysis is still running.", + "storageAnalysisSourceComplete": "Measurement complete", + "storageAnalysisSourceFailed": "Measurement failed", + "storageAnalysisSourceFailedWithError": "Measurement failed: {{error}}", + "storageAnalysisSourcePending": "Waiting to measure", + "storageAnalysisSourceScanning": "Measuring {{completed}} of {{total}}", + "storageAnalysisSourceScanningUnknown": "Measuring", "storageAnalysisTitle": "Storage analysis", + "storageAnalysisTimingHelp": "Analyze refreshes this data immediately. The scan runs on demand while a Storage page or another client is open.", + "storageAnalysisTimingTitle": "Analysis timing", "storageAnalyze": "Analyze", "storageAnalyzing": "Analyzing...", "storageBuildCacheKeepHelp": "Docker keeps approximately this much build cache when pruning eligible records. A larger value preserves more reusable build layers but reclaims less disk space.", @@ -441,6 +456,7 @@ "storageToastPolicySaved": "Storage policy saved", "storageToastQuarantineRestored": "Quarantined resource restored", "storageTotalCounted": "Total counted: {{size}}", + "storageTotalCountedSoFar": "Counted so far: {{size}}", "storageTotalPartial": "Partial measurement", "storageTrashPath": "Trash: {{path}}", "storageTypeToConfirm": "Type <1>{{phrase}} to continue.", diff --git a/apps/web/src/locales/pseudo/settings.json b/apps/web/src/locales/pseudo/settings.json index 146b2e303a..b2b81d858d 100644 --- a/apps/web/src/locales/pseudo/settings.json +++ b/apps/web/src/locales/pseudo/settings.json @@ -398,9 +398,9 @@ "modelWithValue": "Ḿōďēĺ: {{model}}", "settingsMenu": "Śēţţĩńĝś Ḿēńũ", "settingsMenuAccordion": "Àććōŕďĩōń ţŕēē", - "settingsMenuAccordionDescription": "Ŵōŕķśƥàćēś, Àĝēńţś àńď Ēxēćũţōŕś ēxƥàńď ĩńţō ŵĥàţ ţĥēŷ ĥōĺď: à ŵōŕķśƥàćē ďōŵń ţō à śĩńĝĺē ĩńţēĝŕàţĩōń. Ōƥēńĩńĝ ōńē ƀŕàńćĥ ćĺōśēś ţĥē ōţĥēŕś, śō ţĥē ḿēńũ ōńĺŷ ēvēŕ śĥōŵś ţĥē ŵàŷ ţō ţĥē ƥàĝē ŷōũ àŕē ōń.", + "settingsMenuAccordionDescription": "Ŵōŕķśƥàćēś, Àĝēńţś àńď Ēxēćũţōŕś ēxƥàńď ĩńţō ŵĥàţ ţĥēŷ ĥōĺď: à ŵōŕķśƥàćē ďōŵń ţō à śĩńĝĺē ĩńţēĝŕàţĩōń. Ōƥēńĩńĝ ōńē ƀŕàńćĥ ćĺōśēś ţĥē ōţĥēŕś, śō ţĥē ḿēńũ ōńĺŷ ēvēŕ śĥōŵś ţĥē ŵàŷ ţō ţĥē ƥàĝē ŷōũ àŕē ōń. Ţĥĩś ĩś ţĥē ďēƒàũĺţ ḿēńũ.", "settingsMenuFlat": "Ƒĺàţ ĺĩśţ", - "settingsMenuFlatDescription": "Ōńē ŕōŵ ƥēŕ śēţţĩńĝś ƥàĝē, ńēvēŕ ḿōŕē. Ĩńďĩvĩďũàĺ ŵōŕķśƥàćēś, àĝēńţś àńď ēxēćũţōŕś àŕē ŕēàćĥēď ƒŕōḿ ţĥēĩŕ ƥàĝē. Ţĥē ďēƒàũĺţ, àńď ţĥē śĥōŕţēśţ ḿēńũ.", + "settingsMenuFlatDescription": "Ōńē ŕōŵ ƥēŕ śēţţĩńĝś ƥàĝē, ńēvēŕ ḿōŕē. Ĩńďĩvĩďũàĺ ŵōŕķśƥàćēś, àĝēńţś àńď ēxēćũţōŕś àŕē ŕēàćĥēď ƒŕōḿ ţĥēĩŕ ƥàĝē. Ţĥē śĥōŕţēśţ ḿēńũ.", "settingsMenuPersistent": "Ƥēŕśĩśţēńţ ţŕēē", "settingsMenuPersistentDescription": "Ţĥē śàḿē ƀŕàńćĥēś, ƀũţ śēvēŕàĺ śţàŷ ōƥēń àţ ōńćē àńď àŕē śţĩĺĺ ōƥēń àƒţēŕ à ŕēĺōàď. Ćĥōōśē ţĥĩś ţō ķēēƥ à ƒēŵ ŕēćōŕďś śĩďē ƀŷ śĩďē; ŵĩţĥ ḿàńŷ ŵōŕķśƥàćēś ōŕ àĝēńţś ţĥē ḿēńũ ĝēţś ĺōńĝ.", "settingsMenuShape": "Ḿēńũ Śĥàƥē", diff --git a/apps/web/src/locales/pseudo/system.json b/apps/web/src/locales/pseudo/system.json index 4d5ea293f6..68630107b3 100644 --- a/apps/web/src/locales/pseudo/system.json +++ b/apps/web/src/locales/pseudo/system.json @@ -276,8 +276,23 @@ "storageAnalysisComplete": "Àńàĺŷśĩś ćōḿƥĺēţē", "storageAnalysisDescription": "À ŕēàď-ōńĺŷ ƀŕēàķďōŵń ōƒ ćũŕŕēńţ ũśàĝē àńď ŕēćĺàĩḿàƀĺē śƥàćē. Ŕũń Àńàĺŷźē ōććàśĩōńàĺĺŷ ţō ŕēƒŕēśĥ ţĥēśē ēśţĩḿàţēś; ĩţ ńēvēŕ ďēĺēţēś ōŕ ḿōvēś àńŷţĥĩńĝ.", "storageAnalysisFailed": "Àńàĺŷśĩś ƒàĩĺēď", + "storageAnalysisCacheLifetime": "Ćàćĥē ĺĩƒēţĩḿē: {{duration}}", + "storageAnalysisDuration": "Śćàń ďũŕàţĩōń: {{duration}}", + "storageAnalysisDurationMilliseconds": "{{value}} ḿś", + "storageAnalysisDurationMinutes": "{{value}} ḿĩń", + "storageAnalysisDurationSeconds": "{{value}} śēć", + "storageAnalysisNextRefresh": "Ńēxţ ŕēƒŕēśĥ: {{absolute}} ({{relative}})", + "storageAnalysisNextRefreshUnknown": "Ńēxţ ŕēƒŕēśĥ ţĩḿē ĩś ńōţ àvàĩĺàƀĺē.", "storageAnalysisRunning": "Śţōŕàĝē àńàĺŷśĩś ĩś śţĩĺĺ ŕũńńĩńĝ.", + "storageAnalysisSourceComplete": "Ḿēàśũŕēḿēńţ ćōḿƥĺēţē", + "storageAnalysisSourceFailed": "Ḿēàśũŕēḿēńţ ƒàĩĺēď", + "storageAnalysisSourceFailedWithError": "Ḿēàśũŕēḿēńţ ƒàĩĺēď: {{error}}", + "storageAnalysisSourcePending": "Ŵàĩţĩńĝ ţō ḿēàśũŕē", + "storageAnalysisSourceScanning": "Ḿēàśũŕĩńĝ {{completed}} ōƒ {{total}}", + "storageAnalysisSourceScanningUnknown": "Ḿēàśũŕĩńĝ", "storageAnalysisTitle": "Śţōŕàĝē àńàĺŷśĩś", + "storageAnalysisTimingHelp": "Àńàĺŷźē ŕēƒŕēśĥēś ţĥĩś ďàţà ĩḿḿēďĩàţēĺŷ. Ţĥē śćàń ŕũńś ōń ďēḿàńď ŵĥĩĺē à Śţōŕàĝē ƥàĝē ōŕ àńōţĥēŕ ćĺĩēńţ ĩś ōƥēń.", + "storageAnalysisTimingTitle": "Àńàĺŷśĩś ţĩḿĩńĝ", "storageAnalyze": "Àńàĺŷźē", "storageAnalyzing": "Àńàĺŷźĩńĝ...", "storageBuildCacheKeepHelp": "Ďōćķēŕ ķēēƥś àƥƥŕōxĩḿàţēĺŷ ţĥĩś ḿũćĥ ƀũĩĺď ćàćĥē ŵĥēń ƥŕũńĩńĝ ēĺĩĝĩƀĺē ŕēćōŕďś. À ĺàŕĝēŕ vàĺũē ƥŕēśēŕvēś ḿōŕē ŕēũśàƀĺē ƀũĩĺď ĺàŷēŕś ƀũţ ŕēćĺàĩḿś ĺēśś ďĩśķ śƥàćē.", @@ -441,6 +456,7 @@ "storageToastPolicySaved": "Śţōŕàĝē ƥōĺĩćŷ śàvēď", "storageToastQuarantineRestored": "Qũàŕàńţĩńēď ŕēśōũŕćē ŕēśţōŕēď", "storageTotalCounted": "Ţōţàĺ ćōũńţēď: {{size}}", + "storageTotalCountedSoFar": "Ćōũńţēď śō ƒàŕ: {{size}}", "storageTotalPartial": "Ƥàŕţĩàĺ ḿēàśũŕēḿēńţ", "storageTrashPath": "Ţŕàśĥ: {{path}}", "storageTypeToConfirm": "Ţŷƥē <1>{{phrase}} ţō ćōńţĩńũē.", diff --git a/apps/web/src/locales/pt-pt/system.json b/apps/web/src/locales/pt-pt/system.json index 980680eee3..eb56b54fbb 100644 --- a/apps/web/src/locales/pt-pt/system.json +++ b/apps/web/src/locales/pt-pt/system.json @@ -271,8 +271,23 @@ "storageAnalysisComplete": "Análise concluída", "storageAnalysisDescription": "Uma decomposição só de leitura da utilização atual e do espaço recuperável. Execute a Análise de vez em quando para atualizar estas estimativas; nunca elimina nem move nada.", "storageAnalysisFailed": "A análise falhou", + "storageAnalysisCacheLifetime": "Duração da cache: {{duration}}", + "storageAnalysisDuration": "Duração da análise: {{duration}}", + "storageAnalysisDurationMilliseconds": "{{value}} milissegundos", + "storageAnalysisDurationMinutes": "{{value}} minutos", + "storageAnalysisDurationSeconds": "{{value}} s", + "storageAnalysisNextRefresh": "Próxima atualização: {{absolute}} ({{relative}})", + "storageAnalysisNextRefreshUnknown": "A hora da próxima atualização não está disponível.", "storageAnalysisRunning": "A análise do armazenamento ainda está em curso.", + "storageAnalysisSourceComplete": "Medição concluída", + "storageAnalysisSourceFailed": "A medição falhou", + "storageAnalysisSourceFailedWithError": "A medição falhou: {{error}}", + "storageAnalysisSourcePending": "A aguardar medição", + "storageAnalysisSourceScanning": "A medir {{completed}} de {{total}}", + "storageAnalysisSourceScanningUnknown": "A medir", "storageAnalysisTitle": "Análise do armazenamento", + "storageAnalysisTimingHelp": "A Análise atualiza estes dados imediatamente. A análise é executada a pedido enquanto uma página de Armazenamento ou outro cliente estiver aberto.", + "storageAnalysisTimingTitle": "Momento da análise", "storageAnalyze": "Analisar", "storageAnalyzing": "A analisar...", "storageBuildCacheKeepHelp": "O Docker mantém aproximadamente esta quantidade de cache de compilação ao limpar os registos elegíveis. Um valor maior preserva mais camadas de compilação reutilizáveis, mas recupera menos espaço em disco.", @@ -436,6 +451,7 @@ "storageToastPolicySaved": "Política de armazenamento guardada", "storageToastQuarantineRestored": "Recurso em quarentena restaurado", "storageTotalCounted": "Total contabilizado: {{size}}", + "storageTotalCountedSoFar": "Contabilizado até agora: {{size}}", "storageTotalPartial": "Medição parcial", "storageTrashPath": "Reciclagem: {{path}}", "storageTypeToConfirm": "Escreva <1>{{phrase}} para continuar.", diff --git a/apps/web/src/locales/zh-cn/system.json b/apps/web/src/locales/zh-cn/system.json index e2c3fa9943..b0b84a72fa 100644 --- a/apps/web/src/locales/zh-cn/system.json +++ b/apps/web/src/locales/zh-cn/system.json @@ -273,8 +273,23 @@ "storageAnalysisComplete": "分析完成", "storageAnalysisDescription": "当前用量与可回收空间的只读分解。偶尔运行“分析”以刷新估算;它从不删除或移动任何内容。", "storageAnalysisFailed": "分析失败", + "storageAnalysisCacheLifetime": "缓存有效期:{{duration}}", + "storageAnalysisDuration": "扫描时长:{{duration}}", + "storageAnalysisDurationMilliseconds": "{{value}} 毫秒", + "storageAnalysisDurationMinutes": "{{value}} 分钟", + "storageAnalysisDurationSeconds": "{{value}} 秒", + "storageAnalysisNextRefresh": "下次刷新:{{absolute}}({{relative}})", + "storageAnalysisNextRefreshUnknown": "下次刷新时间不可用。", "storageAnalysisRunning": "存储分析仍在运行。", + "storageAnalysisSourceComplete": "测量完成", + "storageAnalysisSourceFailed": "测量失败", + "storageAnalysisSourceFailedWithError": "测量失败:{{error}}", + "storageAnalysisSourcePending": "等待测量", + "storageAnalysisSourceScanning": "正在测量 {{completed}}/{{total}}", + "storageAnalysisSourceScanningUnknown": "正在测量", "storageAnalysisTitle": "存储分析", + "storageAnalysisTimingHelp": "分析会立即刷新这些数据。扫描会在存储页面或其他客户端打开时按需运行。", + "storageAnalysisTimingTitle": "分析时间", "storageAnalyze": "分析", "storageAnalyzing": "正在分析…", "storageBuildCacheKeepHelp": "清理符合条件的记录时,Docker 大约保留这么多构建缓存。值越大可保留更多可复用层,但回收空间更少。", @@ -438,6 +453,7 @@ "storageToastPolicySaved": "存储策略已保存", "storageToastQuarantineRestored": "已恢复隔离资源", "storageTotalCounted": "已统计总量:{{size}}", + "storageTotalCountedSoFar": "目前已统计:{{size}}", "storageTotalPartial": "部分测量结果", "storageTrashPath": "回收站:{{path}}", "storageTypeToConfirm": "输入 <1>{{phrase}} 以继续。", diff --git a/apps/web/src/locales/zh-hk/account.json b/apps/web/src/locales/zh-hk/account.json index e8ca3578c5..37b4ed283a 100644 --- a/apps/web/src/locales/zh-hk/account.json +++ b/apps/web/src/locales/zh-hk/account.json @@ -7,7 +7,7 @@ "cancel": "取消", "changePassword": "修改密碼", "couldNotChangePassword": "無法修改密碼。", - "couldNotUpdateHostnameResolution": "無法更新主機名稱解析。", + "couldNotUpdateHostnameResolution": "無法更新主機名解析。", "couldNotCreateToken": "無法建立權杖。", "createApiToken": "建立 API 權杖", "createApiTokenDescription": "授予與你的帳戶相同的存取權限,供腳本或 CLI 使用。請為其命名,便於日後識別。", @@ -22,7 +22,7 @@ "failedToSaveLastSeenDisplay": "無法儲存上次活動的顯示方式。", "failedToRevokeSession": "無法吊銷工作階段。", "ipAddress": "IP", - "hostname": "主機名稱", + "hostname": "主機名", "hostnameNotAvailable": "不適用", "lastSeen": "上次活動", "lastSeenDisplay": "上次活動顯示", @@ -42,8 +42,8 @@ "saving": "正在儲存…", "securityPageDescription": "修改密碼並查看已登入你帳戶的設備。", "securityPageTitle": "個人數據與密碼", - "resolveDeviceHostnames": "解析裝置主機名稱", - "resolveDeviceHostnamesDescription": "使用系統 DNS 解析器解析已登入裝置的 IP 位址。", + "resolveDeviceHostnames": "解析設備主機名", + "resolveDeviceHostnamesDescription": "使用系統 DNS 解析器解析已登入設備的 IP 地址。", "signOut": "登出", "thisDevice": "此設備", "tokenCreated": "權杖已建立", diff --git a/apps/web/src/locales/zh-hk/agents.json b/apps/web/src/locales/zh-hk/agents.json index cb09eee932..5f173f8e87 100644 --- a/apps/web/src/locales/zh-hk/agents.json +++ b/apps/web/src/locales/zh-hk/agents.json @@ -195,7 +195,7 @@ "runtimeUpdateStatusUnknown": "無法擷取 {{name}} 的最新版本。更新控制項仍可使用。", "runtimeVersionMarkerGroup": "({{markers}})", "runtimeVersionOption": "{{version}} {{markers}}", - "selectRuntimeVersion": "要啟用的版本", + "selectRuntimeVersion": "要激活的版本", "updateAvailableWithVersions": "將 {{name}} 從 {{current}} 更新到 {{latest}}", "updateRuntime": "更新執行時", "rollBackRuntime": "回滾執行時", @@ -248,53 +248,53 @@ "saveProfile": "儲存設定", "savingProfile": "正在儲存…", "dynamicAgents": "動態代理", - "dynamicAgentsDescription": "透過有序的具體代理設定檔列表路由一個邏輯設定檔。", - "dynamicProfileDisabled": "動態代理程式路由已停用。", - "dynamicProfileDescription": "選擇按順序執行的具體設定檔,以便在失敗時切換。", + "dynamicAgentsDescription": "通過有序的具體代理設定列表路由一個邏輯設定。", + "dynamicProfileDisabled": "動態代理路由已停用。", + "dynamicProfileDescription": "選擇按順序執行的具體設定,以便在失敗時切換。", "dynamicProfileSettings": "動態設定檔設定", - "dynamicCandidates": "候選設定檔", - "dynamicCandidatesDescription": "候選設定檔按順序執行。只有在已設定的錯誤動作允許時,才會使用下一個候選設定檔。", - "dynamicRoutingPolicyTitle": "Kandev 何時切換候選設定檔", - "dynamicRoutingPolicySwitchable": "切換可以由已分類的供應商故障觸發,包括驗證或訂閱問題、缺少憑證或設定、配額或速率限制、模型不可用、容量不足、網絡問題,以及供應商不可用或過載。", - "dynamicRoutingPolicyExcluded": "對於工作、儲存庫、權限、工具或執行階段錯誤、傳輸中斷,或執行中途結果不明確的情況,Kandev 不會切換。這些情況會停止並等待手動恢復,以避免重複工作。", - "dynamicRoutingPolicyRecovery": "切換後,發生故障的供應商會暫停 1 分鐘,或者暫停至已提供的重設時間。之後,Kandev 會先執行一次獨佔健康探測,再次使用該供應商。", - "dynamicPolicyWaitExplanation": "重設等待會在每個候選設定檔和錯誤類別中使用一次可信的未來重設時間,並且只在時間不超過最大等待時間時使用。等待結束後,Kandev 會先進行一次新嘗試,再套用重試策略。", + "dynamicCandidates": "候選設定", + "dynamicCandidatesDescription": "候選設定按順序執行。只有在設定的錯誤操作允許時,才會使用下一個候選設定。", + "dynamicRoutingPolicyTitle": "Kandev 何時切換候選設定", + "dynamicRoutingPolicySwitchable": "切換可以由已分類的提供者故障觸發,包括身份驗證或訂閲問題、缺少認證資料或設定、配額或速率限制、模型不可用、容量不足、網絡問題,以及提供者不可用或過載。", + "dynamicRoutingPolicyExcluded": "對於任務、儲存庫、權限、工具或執行時錯誤、傳輸中斷,或執行中途結果不明確的情況,Kandev 不會切換。這些情況會停止並等待手動恢復,以避免重複工作。", + "dynamicRoutingPolicyRecovery": "切換後,發生故障的提供者會暫停 1 分鐘,或者暫停到已提供的重置時間。之後,Kandev 會先執行一次獨佔健康探測,再次使用該提供者。", + "dynamicPolicyWaitExplanation": "重置等待會在每個候選設定和錯誤類別中使用一次可信的未來重置時間,並且只在時間不超過最大等待時間時使用。等待結束後,Kandev 會先進行一次新嘗試,再應用重試策略。", "dynamicTransientErrors": "暫時性錯誤", - "dynamicTransientErrorsDescription": "臨時狀況,例如容量不足、速率限制、網絡故障、逾時、供應商中斷和傳輸中斷。", + "dynamicTransientErrorsDescription": "臨時狀況,例如容量不足、速率限制、網絡故障、超時、提供者中斷和傳輸中斷。", "dynamicHardErrors": "硬錯誤", - "dynamicHardErrorsDescription": "帳戶或設定狀況,例如訂閱限制、額度耗盡、驗證、缺少憑證、模型不可用或供應商設定問題。", - "dynamicPolicyRetry": "重試此候選設定檔", - "dynamicPolicyWaitForReset": "等待供應商重設", + "dynamicHardErrorsDescription": "帳戶或設定狀況,例如訂閲限制、額度耗盡、身份驗證、缺少認證資料、模型不可用或提供者設定問題。", + "dynamicPolicyRetry": "重試此候選設定", + "dynamicPolicyWaitForReset": "等待提供者重置", "dynamicPolicyAfterExhausted": "恢復操作耗盡後", "dynamicPolicyMaxRetries": "最大重試次數", "dynamicPolicyInitialInterval": "初始間隔(秒)", - "dynamicPolicyMaxWait": "最大重設等待時間(秒)", - "dynamicPolicyValidation": "儲存前請修正標示的策略值。", - "dynamicPolicyMaxRetriesValidation": "請輸入 1 至 10 次重試。", - "dynamicPolicyInitialIntervalValidation": "請輸入 1 秒至 1 小時之間的初始間隔。", - "dynamicPolicyMaxWaitValidation": "請輸入 1 秒至 7 日之間的重設等待時間。", + "dynamicPolicyMaxWait": "最大重置等待時間(秒)", + "dynamicPolicyValidation": "儲存前請修正突出顯示的策略值。", + "dynamicPolicyMaxRetriesValidation": "請輸入 1 到 10 次重試。", + "dynamicPolicyInitialIntervalValidation": "請輸入 1 秒到 1 小時之間的初始間隔。", + "dynamicPolicyMaxWaitValidation": "請輸入 1 秒到 7 天之間的重置等待時間。", "dynamicPolicySchedule": "最多重試 {{retries}} 次。第一次重試等待 {{first}} 秒,之後間隔加倍。", - "dynamicPolicyNoRetry": "不重試同一候選設定檔。Kandev 會立即套用所選結果。", - "dynamicPolicyWaitDescription": "當可信的未來重設或重試時間不超過最大等待時間時使用它。", - "dynamicPolicySkip": "略過候選設定檔", + "dynamicPolicyNoRetry": "不重試同一候選設定。Kandev 會立即應用所選結果。", + "dynamicPolicyWaitDescription": "當可信的未來重置或重試時間不超過最大等待時間時使用它。", + "dynamicPolicySkip": "跳過候選設定", "dynamicPolicyStop": "停止並手動恢復", - "dynamicPolicyRetryHelp": "在套用所選結果前,以指數退避方式重試同一候選設定檔。", - "dynamicPolicyWaitHelp": "等待可信的未來供應商重設或重試時間。等待時間有限制,並且每個候選設定檔和類別只使用一次。", - "dynamicPolicyOutcomeHelp": "控制重設等待和同一候選設定檔的所有重試都耗盡後 Kandev 的操作。", + "dynamicPolicyRetryHelp": "在應用所選結果前,以指數退避方式重試同一候選設定。", + "dynamicPolicyWaitHelp": "等待可信的未來提供者重置或重試時間。等待時間有限制,並且每個候選設定和類別只使用一次。", + "dynamicPolicyOutcomeHelp": "控制重置等待和同一候選設定的所有重試都耗盡後 Kandev 的操作。", "dynamicPolicyOptionInfo": "解釋 {{option}} 策略", - "addDynamicCandidate": "新增候選設定檔", - "noDynamicCandidates": "至少新增一個具體設定檔。", - "moveDynamicCandidateUp": "上移候選設定檔", - "moveDynamicCandidateDown": "下移候選設定檔", - "removeDynamicCandidate": "移除候選設定檔", - "dynamicCandidatePickerDescription": "選擇符合動態路由條件的具體設定檔。", - "searchDynamicCandidates": "搜尋代理設定檔...", - "noDynamicCandidatesFound": "找不到符合條件的代理設定檔。", - "dynamicRouteAction": "供應商發生錯誤時", + "addDynamicCandidate": "新增候選設定", + "noDynamicCandidates": "至少新增一個具體設定。", + "moveDynamicCandidateUp": "上移候選設定", + "moveDynamicCandidateDown": "下移候選設定", + "removeDynamicCandidate": "移除候選設定", + "dynamicCandidatePickerDescription": "選擇一個符合動態路由條件的具體設定。", + "searchDynamicCandidates": "搜尋代理設定...", + "noDynamicCandidatesFound": "未找到符合條件的代理設定。", + "dynamicRouteAction": "提供者出錯時", "dynamicRouteActionInfo": "說明{{action}}路由行為", - "dynamicRouteRetryDescription": "供應商發生錯誤後重試相同候選設定檔。適用於可能暫時恢復的故障。", - "dynamicRouteTryNextDescription": "本次執行略過此候選設定檔,繼續使用下一個符合條件的設定檔。", - "dynamicRouteStopDescription": "此候選設定檔失敗後停止路由。工作會等待手動恢復操作。", - "dynamicProfileSaved": "動態設定檔已儲存。", + "dynamicRouteRetryDescription": "提供者出錯後重試同一候選設定。適用於可能暫時恢復的故障。", + "dynamicRouteTryNextDescription": "本次執行跳過此候選設定,繼續使用下一個符合條件的設定。", + "dynamicRouteStopDescription": "此候選設定失敗後停止路由。任務會等待手動恢復操作。", + "dynamicProfileSaved": "動態設定已儲存。", "adminOnly": "只有管理員可以更改代理和代理設定檔。" } diff --git a/apps/web/src/locales/zh-hk/auth.json b/apps/web/src/locales/zh-hk/auth.json index 2112e4e4d1..a9bdaa55da 100644 --- a/apps/web/src/locales/zh-hk/auth.json +++ b/apps/web/src/locales/zh-hk/auth.json @@ -16,7 +16,7 @@ "joinThisKandevDeployment": "加入此 Kandev 部署。", "joining": "正在加入…", "orContinueWith": "或使用以下方式繼續", - "organizationUnavailable": "您的組織目前無法使用。請聯絡您的 Kandev 管理員。", + "organizationUnavailable": "您的組織目前不可用。請聯繫您的 Kandev 管理員。", "password": "密碼", "setUpKandev": "設定 Kandev", "setupFailed": "初始化失敗。請重試。", diff --git a/apps/web/src/locales/zh-hk/automations.json b/apps/web/src/locales/zh-hk/automations.json index dd1cc8dd49..d2bbc36bf2 100644 --- a/apps/web/src/locales/zh-hk/automations.json +++ b/apps/web/src/locales/zh-hk/automations.json @@ -32,13 +32,13 @@ "comingSoonSuffix": "(即將推出)", "completeRequiredFields": "請先填寫必填的自動化欄位,再儲存。", "completed": "已完成", - "contextBetweenRunsConcurrencyLock": "此選項一次只支援一個執行中的工作。", - "contextBetweenRunsDescription": "選擇每次執行是重新開始,還是繼續使用相同的對話和檔案。", - "contextBetweenRunsNewTask": "每次執行都開始新工作", - "contextBetweenRunsNewTaskDescription": "每次執行都會使用獨立的對話和檔案。這些工作不會出現在看板或側邊欄。此選項適用於互相獨立的工作和並行執行。", - "contextBetweenRunsNewTaskNormalDescription": "每次執行都會使用獨立的對話和檔案。這些工作會出現在看板和側邊欄。此選項適用於互相獨立的工作和並行執行。", + "contextBetweenRunsConcurrencyLock": "此選項一次只支援一個執行中的任務。", + "contextBetweenRunsDescription": "選擇每次執行是從頭開始,還是繼續使用相同的對話和檔案。", + "contextBetweenRunsNewTask": "每次執行都開始新任務", + "contextBetweenRunsNewTaskDescription": "每次執行都會使用獨立的對話和檔案。這些任務不會出現在看板或側邊欄中。此選項適用於相互獨立的作業和併發執行。", + "contextBetweenRunsNewTaskNormalDescription": "每次執行都會使用獨立的對話和檔案。這些任務會出現在看板和側邊欄中。此選項適用於相互獨立的作業和併發執行。", "contextBetweenRunsReuseThread": "繼續之前的工作階段", - "contextBetweenRunsReuseThreadDescription": "執行會繼續使用相同的對話和檔案,讓代理保留之前的上下文和變更。執行會依次進行。", + "contextBetweenRunsReuseThreadDescription": "執行會繼續使用相同的對話和檔案,因此代理可以保留之前的上下文和更改。執行會依次執行。", "contextBetweenRunsTitle": "執行之間的上下文", "configurationLabel": "設定", "couldNotLoadWorkflows": "無法載入工作流程", @@ -52,7 +52,7 @@ "cronHelp": "標準五欄位 cron 或快捷方式({{shortcuts}})", "delete": "刪除", "deleteAutomationTitle": "刪除自動化?", - "deleteAutomationDescription": "這將永久刪除 {{name}}。此操作無法復原。", + "deleteAutomationDescription": "這將永久刪除 {{name}}。此操作無法撤銷。", "deleteAll": "全部刪除", "deleteAllRuns": "刪除所有執行記錄", "deleteAllRunsDescription": "這將永久刪除此自動化的所有執行記錄;包括目前未載入的記錄;以及關聯的任務。此操作無法撤銷。", @@ -123,9 +123,9 @@ "replyToThisRun": "回覆此執行…", "repositoryLabel": "儲存庫", "repositoryNone": "無;不使用儲存庫", - "repositoryModeTitle": "儲存庫存取權", - "repositoryModeDescription": "新增一個或多個儲存庫與基礎分支組合,或在沒有儲存庫的情況下執行。", - "repositoryModeNoneDescription": "在工作專屬的暫存工作區中執行,不使用儲存庫檔案。", + "repositoryModeTitle": "儲存庫存取", + "repositoryModeDescription": "新增一個或多個儲存庫與基礎分支組合,或在無儲存庫的情況下執行。", + "repositoryModeNoneDescription": "在任務專屬的臨時工作區中執行,不使用儲存庫檔案。", "repositoryPlaceholderAuto": "自動", "required": "必填", "resizeRuns": "調整執行記錄區域大小", @@ -188,14 +188,14 @@ "taskTitleLabel": "任務標題", "taskTitlePlaceholder": "[自動] 自動化名稱", "taskModeTitle": "執行目標", - "taskModeDescription": "選擇每次觸發只保留在自動化記錄中,還是建立普通任務。", - "taskModeAutomationRun": "只在自動化記錄中執行", - "taskModeAutomationRunDescription": "每次執行使用私人任務和對話。這些任務不會出現在看板或側邊欄。", + "taskModeDescription": "選擇每次觸發是隻保留在自動化歷史中,還是建立普通任務。", + "taskModeAutomationRun": "僅在自動化歷史中執行", + "taskModeAutomationRunDescription": "每次執行使用私有任務和對話。這些任務不會出現在看板或側邊欄中。", "taskModeNormalTask": "建立普通任務", - "taskModeNormalTaskDescription": "每次執行都會在選取的工作流程中建立普通任務。任務會出現在看板和側邊欄。", + "taskModeNormalTaskDescription": "每次執行都會在選定的工作流程中建立普通任務。任務會出現在看板和側邊欄中。", "workflowRequiredLabel": "工作流程(必填)", "selectWorkflowRequired": "選擇工作流程", - "normalTaskWorkflowHelp": "選擇工作流程,讓此任務出現在看板和側邊欄。", + "normalTaskWorkflowHelp": "選擇工作流程,讓此任務出現在看板和側邊欄中。", "thenDescription": "每次此自動化觸發時都會建立一個新任務", "thenTitle": "然後", "triggerCategoryGithub": "GitHub", diff --git a/apps/web/src/locales/zh-hk/azuredevops.json b/apps/web/src/locales/zh-hk/azuredevops.json index bffd13de33..423a892454 100644 --- a/apps/web/src/locales/zh-hk/azuredevops.json +++ b/apps/web/src/locales/zh-hk/azuredevops.json @@ -149,7 +149,7 @@ "placeholderDescriptionBody": "描述正文", "placeholderIdDescription": "工作項或拉取要求 ID", "placeholderProjectDescription": "項目名稱", - "placeholderSourceBranchDescription": "來源分支", + "placeholderSourceBranchDescription": "源分支", "placeholderStateDescription": "目前狀態", "placeholderTargetBranchDescription": "目標分支", "placeholderTypeDescription": "工作項類型", diff --git a/apps/web/src/locales/zh-hk/chat.json b/apps/web/src/locales/zh-hk/chat.json index 05edd77b30..366b5d66d8 100644 --- a/apps/web/src/locales/zh-hk/chat.json +++ b/apps/web/src/locales/zh-hk/chat.json @@ -96,7 +96,7 @@ "quickChatDialogIntro": "與代理程式開始快速對話,無需建立正式任務。", "quickChatIntro": "就想法、問題或程式碼庫與代理程式聊天。", "quickChatIntroSecondary": "快速聊天獨立於任務看板。", - "quickChatTabOrderSaveFailed": "無法儲存快速聊天分頁順序。", + "quickChatTabOrderSaveFailed": "無法儲存快速聊天標籤頁順序。", "quickChatTabOrderSaveFailedDescription": "目前順序會保留在此處。重新載入可恢復上次儲存的順序。", "renameChat": "重命名聊天", "renameSavedOnThisDeviceOnly": "重命名僅儲存在此設備上", diff --git a/apps/web/src/locales/zh-hk/common.json b/apps/web/src/locales/zh-hk/common.json index f07d9415f9..d07f6d6a45 100644 --- a/apps/web/src/locales/zh-hk/common.json +++ b/apps/web/src/locales/zh-hk/common.json @@ -78,7 +78,7 @@ "commandGoToStats": "前往統計", "commandGoToStatsKeywords": "統計, 數據分析, 分析, 指標", "commandGoToThreads": "前往對話流", - "commandGoToThreadsKeywords": "對話流, 代理程式, 即時, 欄", + "commandGoToThreadsKeywords": "對話流, 代理程式, 實時, 列", "commandGroupActions": "操作", "commandGroupAgent": "代理程式", "commandGroupCommands": "命令", diff --git a/apps/web/src/locales/zh-hk/github.json b/apps/web/src/locales/zh-hk/github.json index 9786b849ba..c7a660763b 100644 --- a/apps/web/src/locales/zh-hk/github.json +++ b/apps/web/src/locales/zh-hk/github.json @@ -382,7 +382,7 @@ "prTaskStatusCi": "CI", "prTaskStatusMerge": "合併", "prTaskStatusNumber": "PR #{{number}}", - "prTaskStatusRepositoryNumber": "{{repository}} 拉取請求 #{{number}}", + "prTaskStatusRepositoryNumber": "{{repository}} 拉取要求 #{{number}}", "prTaskStatusReview": "審閱", "prTaskStatusState": "狀態", "prepareAppOnGithub": "在 GitHub 上準備應用", diff --git a/apps/web/src/locales/zh-hk/jira.json b/apps/web/src/locales/zh-hk/jira.json index 1b7f14bea3..e7360fd797 100644 --- a/apps/web/src/locales/zh-hk/jira.json +++ b/apps/web/src/locales/zh-hk/jira.json @@ -212,7 +212,7 @@ "builtinViewAssignedToMe": "指派給我", "builtinViewUnassigned": "未指派", "connectWithAtlassian": "連接 Atlassian", - "connecting": "正在連線...", + "connecting": "正在連接...", "oauth2": "OAuth 2.0", "oauthConnected": "已通過 OAuth 連接。權杖會自動刷新。", "oauthDescription": "通過 Atlassian OAuth 2.1(含 PKCE)進行身份驗證。無需建立應用或提供認證資料。點擊即可在瀏覽器中授權。權杖過期後會自動刷新。", @@ -220,7 +220,7 @@ "oauthTokenExpires": "權杖過期時間:{{date}}", "oauthPasteInstructions": "在新標籤頁中完成授權", "oauthPasteHelp": "在 Atlassian 上批准後,你將被重定向到一個無法載入的 localhost 網址。請從瀏覽器地址欄複製完整網址並貼上到下方。", - "oauthPopupBlocked": "瀏覽器已封鎖授權視窗。請允許彈出式視窗,然後再試。", + "oauthPopupBlocked": "瀏覽器已阻止授權窗口。請允許彈出窗口,然後重試。", "oauthComplete": "完成", "oauthCancel": "取消", "oauthPasteInvalid": "網址無效。請確保複製了包含 code 和 state 參數的完整重定向網址。" diff --git a/apps/web/src/locales/zh-hk/kanban.json b/apps/web/src/locales/zh-hk/kanban.json index 16d000e6c4..62060714cd 100644 --- a/apps/web/src/locales/zh-hk/kanban.json +++ b/apps/web/src/locales/zh-hk/kanban.json @@ -101,9 +101,9 @@ "wipTaskCount": "{{label}} 個任務", "workflow": "工作流程", "workflowStepFallback": "工作流程步驟 {{stepId}}", - "columns": "欄", - "autoHideEmptyColumns": "自動隱藏空白欄", - "allEmptyStepsAutoHidden": "所有空白步驟都已隱藏。在「欄」中關閉「自動隱藏空白欄」即可重新顯示它們。", + "columns": "列", + "autoHideEmptyColumns": "自動隱藏空列", + "allEmptyStepsAutoHidden": "所有空步驟都已隱藏。在「列」中關閉「自動隱藏空列」即可重新顯示它們。", "columnsForWorkflow": "{{name}} 的列", "needsReassignment": "需要重新分配", "blockedByCount_one": "被 {{count}} 項阻塞", diff --git a/apps/web/src/locales/zh-hk/orgs.json b/apps/web/src/locales/zh-hk/orgs.json index 610d930b43..718d52647d 100644 --- a/apps/web/src/locales/zh-hk/orgs.json +++ b/apps/web/src/locales/zh-hk/orgs.json @@ -3,34 +3,34 @@ "adminCreate": "建立管理員", "adminCreated": "管理員已建立。", "adminDescription": "管理員只能在自己的組織中建立帳戶,因此新組織需要在此建立首位管理員。", - "adminEmail": "電子郵件", + "adminEmail": "電郵地址", "adminName": "顯示名稱", "adminPassword": "密碼", - "adminPasswordHint": "至少 8 個字元。請告知對方並要求其登入後變更。", + "adminPasswordHint": "至少 8 個字符。請告知對方並要求其登入後修改。", "adminTitle": "{{name}} 的首位管理員", - "boundaryDescription": "工作區、任務、工作階段、密鑰和帳戶均屬於一個組織。身為執行個體維運人員,您管理組織本身;但不會取得任何組織內部的存取權限,包括您自己的組織。", + "boundaryDescription": "工作區、任務、工作階段、密鑰和帳戶均歸屬於一個組織。作為實例運維人員,您管理組織本身;但不會獲得任何組織內部的存取權限,包括您自己的組織。", "boundaryTitle": "組織隔離的內容", "create": "建立", "createDescription": "先建立組織,然後新增其首位管理員。此後該組織將自行管理。", - "createTitle": "新增組織", + "createTitle": "新建組織", "created": "組織已建立。", "defaultBadge": "預設", "delete": "刪除組織", "deleteConfirm": "刪除組織", "deleteConfirmLabel": "輸入 {{slug}} 以確認", "deleteTitle": "刪除 {{name}}", - "deleteWarning": "這將移除該組織中的所有工作區、任務、工作階段和帳戶,且無法復原。", + "deleteWarning": "這將移除該組織中的所有工作區、任務、工作階段和帳戶,且無法撤銷。", "deleted": "組織已刪除。", - "description": "每個組織都是獨立的租戶。使用者僅屬於一個組織,組織之間無法看到彼此的工作區、任務或密鑰。", - "genericError": "無法儲存該變更。", + "description": "每個組織都是獨立的租户。用戶僅屬於一個組織,組織之間無法看到彼此的工作區、任務或密鑰。", + "genericError": "無法儲存該更改。", "nameLabel": "組織名稱", "namePlaceholder": "Acme Corp", "navOrganizations": "組織", - "operatorOnly": "只有執行個體維運人員可以管理組織。", - "renamed": "組織已重新命名。", + "operatorOnly": "只有實例運維人員可以管理組織。", + "renamed": "組織已重命名。", "resume": "恢復", "resumed": "組織已恢復。", - "statusActive": "使用中", + "statusActive": "活動", "statusSuspended": "已暫停", "suspend": "暫停", "suspended": "組織已暫停。", diff --git a/apps/web/src/locales/zh-hk/settings.json b/apps/web/src/locales/zh-hk/settings.json index e02269aa40..fb696accbb 100644 --- a/apps/web/src/locales/zh-hk/settings.json +++ b/apps/web/src/locales/zh-hk/settings.json @@ -751,22 +751,22 @@ "keyValueKeyPlaceholder": "鍵", "keyValueValuePlaceholder": "值", "profileStartModelNotAdvertisedOnHost": "主機探測未公佈 {{model}}。所選執行器將在啓動時決定使用的模型。", - "navUnits": "組織單位", - "unitsTitle": "組織單位", - "unitsDescription": "單位包含團隊、工作區和成員。加入某個單位即可存取其下的所有工作區,包括之後建立的。", - "unitsEmpty": "尚無單位。", + "navUnits": "組織單元", + "unitsTitle": "組織單元", + "unitsDescription": "單元包含團隊、工作區和成員。加入某個單元即可存取其下的所有工作區,包括之後建立的。", + "unitsEmpty": "尚無單元。", "unitRootBadge": "整個組織", "unitPersonalBadge": "個人", - "unitAddChild": "新增單位", + "unitAddChild": "新增單元", "unitMembers": "成員", - "unitDelete": "刪除單位", - "unitCreateTitle": "在 {{parent}} 中新增單位", - "unitCreateDescription": "部門和團隊都是單位,差別只在於所處位置。", + "unitDelete": "刪除單元", + "unitCreateTitle": "在 {{parent}} 中新建單元", + "unitCreateDescription": "部門和團隊都是單元,區別只在於所處位置。", "unitNamePlaceholder": "平台", "unitCreate": "建立", "unitMembersTitle": "{{unit}} 的成員", - "unitMembersDescription": "這裡的每個人都能以你指定的角色存取該單位下的所有工作區。", - "unitNoMembers": "該單位尚無成員。", + "unitMembersDescription": "這裏的每個人都能以你指定的角色存取該單元下的所有工作區。", + "unitNoMembers": "該單元暫無成員。", "unitAddMember": "新增", "unitRemoveMember": "移除成員", "unitPickPerson": "選擇成員", diff --git a/apps/web/src/locales/zh-hk/system.json b/apps/web/src/locales/zh-hk/system.json index b93af84ff1..54af93bcaf 100644 --- a/apps/web/src/locales/zh-hk/system.json +++ b/apps/web/src/locales/zh-hk/system.json @@ -13,7 +13,7 @@ "actionDone": "完成", "actionFailed": "失敗", "actionRunning": "執行中…", - "backupsAdminOnly": "只有管理員可以建立、下載、還原或刪除備份。", + "backupsAdminOnly": "只有管理員可以建立、下載、恢復或刪除備份。", "backupsColumnActions": "操作", "backupsColumnCreated": "建立時間", "backupsColumnKind": "類型", @@ -273,8 +273,23 @@ "storageAnalysisComplete": "分析完成", "storageAnalysisDescription": "目前用量與可回收空間的只讀分解。偶爾執行「分析」以刷新估算;它從不刪除或移動任何內容。", "storageAnalysisFailed": "分析失敗", + "storageAnalysisCacheLifetime": "快取有效期:{{duration}}", + "storageAnalysisDuration": "掃描時長:{{duration}}", + "storageAnalysisDurationMilliseconds": "{{value}} 毫秒", + "storageAnalysisDurationMinutes": "{{value}} 分鐘", + "storageAnalysisDurationSeconds": "{{value}} 秒", + "storageAnalysisNextRefresh": "下次刷新:{{absolute}}({{relative}})", + "storageAnalysisNextRefreshUnknown": "下次刷新時間不可用。", "storageAnalysisRunning": "存儲分析仍在執行。", + "storageAnalysisSourceComplete": "測量完成", + "storageAnalysisSourceFailed": "測量失敗", + "storageAnalysisSourceFailedWithError": "測量失敗:{{error}}", + "storageAnalysisSourcePending": "等待測量", + "storageAnalysisSourceScanning": "正在測量 {{completed}}/{{total}}", + "storageAnalysisSourceScanningUnknown": "正在測量", "storageAnalysisTitle": "存儲分析", + "storageAnalysisTimingHelp": "分析會立即刷新這些數據。掃描會在存儲頁面或其他用戶端開啟時按需執行。", + "storageAnalysisTimingTitle": "分析時間", "storageAnalyze": "分析", "storageAnalyzing": "正在分析…", "storageBuildCacheKeepHelp": "清理符合條件的記錄時,Docker 大約保留這麼多構建快取。值越大可保留更多可複用層,但回收空間更少。", @@ -438,6 +453,7 @@ "storageToastPolicySaved": "存儲策略已儲存", "storageToastQuarantineRestored": "已恢復隔離資源", "storageTotalCounted": "已統計總量:{{size}}", + "storageTotalCountedSoFar": "目前已統計:{{size}}", "storageTotalPartial": "部分測量結果", "storageTrashPath": "回收站:{{path}}", "storageTypeToConfirm": "輸入 <1>{{phrase}} 以繼續。", diff --git a/apps/web/src/locales/zh-hk/task.json b/apps/web/src/locales/zh-hk/task.json index d6995adc6b..93c9fb9189 100644 --- a/apps/web/src/locales/zh-hk/task.json +++ b/apps/web/src/locales/zh-hk/task.json @@ -37,7 +37,7 @@ "addReviewer": "+ 新增審閱人", "addShort": "+ 新增", "addSubIssue": "新增子議題", - "addToWorkspace": "加入工作區", + "addToWorkspace": "新增到工作區", "addYourCommentOrInstruction": "新增你的評論或指示…", "addedRemoved": "新增 {{added}} · 刪除 {{removed}}", "adding": "正在新增…", @@ -970,7 +970,7 @@ "plan": "計劃", "planCommentCount_one": "{{count}} 條計劃評論", "planCommentCount_other": "{{count}} 條計劃評論", - "planContentTooLarge": "您的計劃為 {{submitted}},超過了 {{limit}} 的限制。請縮短文件後重新儲存。", + "planContentTooLarge": "您的計劃為 {{submitted}},超過了 {{limit}} 的限制。請縮短文檔後重新儲存。", "planHistory": "計劃歷史", "planIsEmpty": "計劃為空", "planLoadError": "無法載入計劃。", @@ -1953,28 +1953,28 @@ "branchPolicyOptionSummary": "從 {{base}} 到 {{target}}", "branchPolicySelected": "{{name}}(從 {{base}})", "branchPolicyUnavailable": "基礎分支不可用。請刷新分支或編輯此策略。", - "branchPolicyRequiresSingleRepository": "使用本機執行器時,分支策略需要單一儲存庫。", + "branchPolicyRequiresSingleRepository": "使用本地執行器時,分支策略需要單個儲存庫。", "assignedTo": "指派給", "unassigned": "未指派", "assignToMe": "指派給我", "searchPeople": "搜尋成員", - "noPeopleFound": "找不到成員", + "noPeopleFound": "未找到成員", "assignedToName": "指派給 {{name}}", "uploadConflictTitle_one": "{{count}} 個檔案已存在", "uploadConflictTitle_other": "{{count}} 個檔案已存在", - "uploadConflictBody": "請選擇如何處理每個檔案。確認之前不會上載任何內容。", - "uploadConflictApplyToAll": "套用至全部", + "uploadConflictBody": "請選擇如何處理每個檔案。確認之前不會上傳任何內容。", + "uploadConflictApplyToAll": "應用於全部", "uploadConflictKeepBoth": "兩者都保留", - "uploadConflictReplace": "取代", - "uploadConflictSkip": "略過", - "uploadConflictConfirm": "上載", - "uploadFiles": "上載檔案", - "uploadFolder": "上載資料夾", - "uploadFilesHere": "上載檔案至此", - "uploadComplete_one": "已上載 {{count}} 個檔案", - "uploadComplete_other": "已上載 {{count}} 個檔案", - "uploadedTo": "已上載至 {{path}}", - "failedToUploadFile": "上載檔案失敗", - "uploadPartiallyFailed_one": "{{count}} 個檔案上載失敗", - "uploadPartiallyFailed_other": "{{count}} 個檔案上載失敗" + "uploadConflictReplace": "替換", + "uploadConflictSkip": "跳過", + "uploadConflictConfirm": "上傳", + "uploadFiles": "上傳檔案", + "uploadFolder": "上傳資料夾", + "uploadFilesHere": "上傳檔案到此處", + "uploadComplete_one": "已上傳 {{count}} 個檔案", + "uploadComplete_other": "已上傳 {{count}} 個檔案", + "uploadedTo": "已上傳至 {{path}}", + "failedToUploadFile": "上傳檔案失敗", + "uploadPartiallyFailed_one": "{{count}} 個檔案上傳失敗", + "uploadPartiallyFailed_other": "{{count}} 個檔案上傳失敗" } diff --git a/apps/web/src/locales/zh-hk/workspaces.json b/apps/web/src/locales/zh-hk/workspaces.json index c9bf9aa49d..a7aa397e8e 100644 --- a/apps/web/src/locales/zh-hk/workspaces.json +++ b/apps/web/src/locales/zh-hk/workspaces.json @@ -209,44 +209,44 @@ "branchPolicyGitflowCreated": "Gitflow 策略已建立", "branchPolicyGitflowFailed": "無法建立 Gitflow 策略。", "branchPolicySummary": "基礎:{{base}}。模板:{{template}}。拉取要求目標:{{target}}。", - "defaultVisibility.description": "適用於此後建立的工作區。現有工作區維持其目前的可見性。", - "defaultVisibility.existingUnaffected": "變更此設定絕不會變更現有工作區。", + "defaultVisibility.description": "適用於此後建立的工作區。現有工作區保持其目前可見性。", + "defaultVisibility.existingUnaffected": "更改此設定絕不會更改現有工作區。", "defaultVisibility.label": "新工作區為", "defaultVisibility.savedOrg": "新工作區將對組織可見。", - "defaultVisibility.savedPrivate": "新工作區將為私人。", + "defaultVisibility.savedPrivate": "新工作區將為私有。", "defaultVisibility.title": "新工作區預設設定", "teamAccess.addMember": "新增", "teamAccess.addMemberLabel": "新增同事", - "teamAccess.addMemberPlaceholder": "選擇一位人員", - "teamAccess.description": "選擇誰可以存取此工作區,並為同事指派角色。", - "teamAccess.genericError": "無法儲存該變更。", - "teamAccess.makeOwner": "設為擁有者", - "teamAccess.memberAdded": "已新增成員。", - "teamAccess.memberRemoved": "已移除成員。", + "teamAccess.addMemberPlaceholder": "選擇一個人", + "teamAccess.description": "選擇誰可以存取此工作區,併為同事分配角色。", + "teamAccess.genericError": "無法儲存該更改。", + "teamAccess.makeOwner": "設為所有者", + "teamAccess.memberAdded": "成員已新增。", + "teamAccess.memberRemoved": "成員已移除。", "teamAccess.membersLabel": "成員", - "teamAccess.noMembers": "尚無成員。擁有者一律具有完整存取權限。", + "teamAccess.noMembers": "暫無成員。所有者始終擁有完全存取權限。", "teamAccess.noUsersToAdd": "所有人都已是成員", "teamAccess.nowOrgVisible": "此工作區現在對組織可見。", - "teamAccess.nowPrivate": "此工作區現在為私人。", - "teamAccess.ownershipTransferred": "{{name}} 現在是擁有者。", + "teamAccess.nowPrivate": "此工作區現在為私有。", + "teamAccess.ownershipTransferred": "{{name}} 現在是所有者。", "teamAccess.removeMember": "移除成員", "teamAccess.roleCollaborator": "協作者", "teamAccess.roleLabel": "角色", - "teamAccess.roleOwner": "擁有者", - "teamAccess.roleUpdated": "已更新角色。", - "teamAccess.roleViewer": "檢視者", + "teamAccess.roleOwner": "所有者", + "teamAccess.roleUpdated": "角色已更新。", + "teamAccess.roleViewer": "查看者", "teamAccess.title": "團隊存取", "teamAccess.visibilityLabel": "可見性", "teamAccess.visibilityOrg": "組織中的所有人", - "teamAccess.visibilityOrgHint": "除訪客外的所有使用者都可以開啟此工作區並處理其任務。", - "teamAccess.visibilityPrivate": "私人", - "teamAccess.visibilityPrivateHint": "只有擁有者和下方列出的成員可以開啟此工作區。", + "teamAccess.visibilityOrgHint": "除訪客外的所有用戶都可以開啟此工作區並處理其任務。", + "teamAccess.visibilityPrivate": "私有", + "teamAccess.visibilityPrivateHint": "只有所有者和下方列出的成員可以開啟此工作區。", "placement.title": "位置", - "placement.description": "該工作區所屬的單位,也就決定了誰能存取它。移動它是改變存取範圍的唯一方式:角色按最高權限合併,無法就地收回。", - "placement.pick": "選擇單位", - "placement.search": "搜尋單位", - "placement.none": "找不到單位", + "placement.description": "該工作區所屬的單元,也就決定了誰能存取它。移動它是改變存取範圍的唯一方式:角色按最高權限合併,無法就地收回。", + "placement.pick": "選擇單元", + "placement.search": "搜尋單元", + "placement.none": "未找到單元", "placement.moved": "工作區已移動。", "placement.failed": "無法移動該工作區。", - "placement.ownerOnly": "僅工作區擁有者可移動" + "placement.ownerOnly": "僅工作區所有者可移動" } diff --git a/apps/web/src/locales/zh-tw/account.json b/apps/web/src/locales/zh-tw/account.json index e199c0446f..c840579668 100644 --- a/apps/web/src/locales/zh-tw/account.json +++ b/apps/web/src/locales/zh-tw/account.json @@ -7,7 +7,7 @@ "cancel": "取消", "changePassword": "修改密碼", "couldNotChangePassword": "無法修改密碼。", - "couldNotUpdateHostnameResolution": "無法更新主機名稱解析。", + "couldNotUpdateHostnameResolution": "無法更新主機名解析。", "couldNotCreateToken": "無法建立權杖。", "createApiToken": "建立 API 權杖", "createApiTokenDescription": "授予與你的帳戶相同的存取權限,供指令碼或 CLI 使用。請為其命名,便於日後識別。", @@ -22,7 +22,7 @@ "failedToSaveLastSeenDisplay": "無法儲存上次活動的顯示方式。", "failedToRevokeSession": "無法吊銷工作階段。", "ipAddress": "IP", - "hostname": "主機名稱", + "hostname": "主機名", "hostnameNotAvailable": "不適用", "lastSeen": "上次活動", "lastSeenDisplay": "上次活動顯示", @@ -42,8 +42,8 @@ "saving": "正在儲存…", "securityPageDescription": "修改密碼並檢視已登入你帳戶的裝置。", "securityPageTitle": "個人資料與密碼", - "resolveDeviceHostnames": "解析裝置主機名稱", - "resolveDeviceHostnamesDescription": "使用系統 DNS 解析器解析已登入裝置的 IP 位址。", + "resolveDeviceHostnames": "解析裝置主機名", + "resolveDeviceHostnamesDescription": "使用系統 DNS 解析器解析已登入裝置的 IP 地址。", "signOut": "登出", "thisDevice": "此裝置", "tokenCreated": "權杖已建立", diff --git a/apps/web/src/locales/zh-tw/agents.json b/apps/web/src/locales/zh-tw/agents.json index b8d65d0356..416c7c7014 100644 --- a/apps/web/src/locales/zh-tw/agents.json +++ b/apps/web/src/locales/zh-tw/agents.json @@ -248,53 +248,53 @@ "saveProfile": "儲存設定", "savingProfile": "正在儲存…", "dynamicAgents": "動態代理", - "dynamicAgentsDescription": "透過有序的具體代理設定檔清單路由一個邏輯設定檔。", - "dynamicProfileDisabled": "動態代理程式路由已停用。", - "dynamicProfileDescription": "選擇按順序執行的具體設定檔,以便在失敗時切換。", + "dynamicAgentsDescription": "通過有序的具體代理設定清單路由一個邏輯設定。", + "dynamicProfileDisabled": "動態代理路由已停用。", + "dynamicProfileDescription": "選擇按順序執行的具體設定,以便在失敗時切換。", "dynamicProfileSettings": "動態設定檔設定", - "dynamicCandidates": "候選設定檔", - "dynamicCandidatesDescription": "候選設定檔按順序執行。只有在已設定的錯誤動作允許時,才會使用下一個候選設定檔。", - "dynamicRoutingPolicyTitle": "Kandev 何時切換候選設定檔", - "dynamicRoutingPolicySwitchable": "切換可以由已分類的供應商故障觸發,包括驗證或訂閱問題、缺少憑證或設定、配額或速率限制、模型無法使用、容量不足、網路問題,以及供應商無法使用或過載。", - "dynamicRoutingPolicyExcluded": "對於工作、儲存庫、權限、工具或執行階段錯誤、傳輸中斷,或執行中途結果不明確的情況,Kandev 不會切換。這些情況會停止並等待手動復原,以避免重複工作。", - "dynamicRoutingPolicyRecovery": "切換後,發生故障的供應商會暫停 1 分鐘,或者暫停至已提供的重設時間。之後,Kandev 會先執行一次獨佔健康探測,再次使用該供應商。", - "dynamicPolicyWaitExplanation": "重設等待會在每個候選設定檔和錯誤類別中使用一次可信的未來重設時間,並且只在時間不超過最大等待時間時使用。等待結束後,Kandev 會先進行一次新嘗試,再套用重試策略。", + "dynamicCandidates": "候選設定", + "dynamicCandidatesDescription": "候選設定按順序執行。只有在設定的錯誤操作允許時,才會使用下一個候選設定。", + "dynamicRoutingPolicyTitle": "Kandev 何時切換候選設定", + "dynamicRoutingPolicySwitchable": "切換可以由已分類的提供者故障觸發,包括身分驗證或訂閱問題、缺少認證資訊或設定、配額或速率限制、模型不可用、容量不足、網路問題,以及提供者不可用或過載。", + "dynamicRoutingPolicyExcluded": "對於任務、儲存庫、權限、工具或執行時錯誤、傳輸中斷,或執行中途結果不明確的情況,Kandev 不會切換。這些情況會停止並等待手動恢復,以避免重複工作。", + "dynamicRoutingPolicyRecovery": "切換後,發生故障的提供者會暫停 1 分鐘,或者暫停到已提供的重置時間。之後,Kandev 會先執行一次獨佔健康探測,再次使用該提供者。", + "dynamicPolicyWaitExplanation": "重置等待會在每個候選設定和錯誤類別中使用一次可信的未來重置時間,並且只在時間不超過最大等待時間時使用。等待結束後,Kandev 會先進行一次新嘗試,再應用重試策略。", "dynamicTransientErrors": "暫時性錯誤", - "dynamicTransientErrorsDescription": "臨時狀況,例如容量不足、速率限制、網路故障、逾時、供應商中斷和傳輸中斷。", + "dynamicTransientErrorsDescription": "臨時狀況,例如容量不足、速率限制、網路故障、超時、提供者中斷和傳輸中斷。", "dynamicHardErrors": "硬錯誤", - "dynamicHardErrorsDescription": "帳戶或設定狀況,例如訂閱限制、額度耗盡、驗證、缺少憑證、模型無法使用或供應商設定問題。", - "dynamicPolicyRetry": "重試此候選設定檔", - "dynamicPolicyWaitForReset": "等待供應商重設", - "dynamicPolicyAfterExhausted": "復原操作耗盡後", + "dynamicHardErrorsDescription": "帳戶或設定狀況,例如訂閱限制、額度耗盡、身分驗證、缺少認證資訊、模型不可用或提供者設定問題。", + "dynamicPolicyRetry": "重試此候選設定", + "dynamicPolicyWaitForReset": "等待提供者重置", + "dynamicPolicyAfterExhausted": "恢復操作耗盡後", "dynamicPolicyMaxRetries": "最大重試次數", "dynamicPolicyInitialInterval": "初始間隔(秒)", - "dynamicPolicyMaxWait": "最大重設等待時間(秒)", - "dynamicPolicyValidation": "儲存前請修正標示的策略值。", - "dynamicPolicyMaxRetriesValidation": "請輸入 1 至 10 次重試。", - "dynamicPolicyInitialIntervalValidation": "請輸入 1 秒至 1 小時之間的初始間隔。", - "dynamicPolicyMaxWaitValidation": "請輸入 1 秒至 7 日之間的重設等待時間。", + "dynamicPolicyMaxWait": "最大重置等待時間(秒)", + "dynamicPolicyValidation": "儲存前請修正突出顯示的策略值。", + "dynamicPolicyMaxRetriesValidation": "請輸入 1 到 10 次重試。", + "dynamicPolicyInitialIntervalValidation": "請輸入 1 秒到 1 小時之間的初始間隔。", + "dynamicPolicyMaxWaitValidation": "請輸入 1 秒到 7 天之間的重置等待時間。", "dynamicPolicySchedule": "最多重試 {{retries}} 次。第一次重試等待 {{first}} 秒,之後間隔加倍。", - "dynamicPolicyNoRetry": "不重試同一候選設定檔。Kandev 會立即套用所選結果。", - "dynamicPolicyWaitDescription": "當可信的未來重設或重試時間不超過最大等待時間時使用它。", - "dynamicPolicySkip": "略過候選設定檔", - "dynamicPolicyStop": "停止並手動復原", - "dynamicPolicyRetryHelp": "在套用所選結果前,以指數退避方式重試同一候選設定檔。", - "dynamicPolicyWaitHelp": "等待可信的未來供應商重設或重試時間。等待時間有限制,並且每個候選設定檔和類別只使用一次。", - "dynamicPolicyOutcomeHelp": "控制重設等待和同一候選設定檔的所有重試都耗盡後 Kandev 的操作。", + "dynamicPolicyNoRetry": "不重試同一候選設定。Kandev 會立即應用所選結果。", + "dynamicPolicyWaitDescription": "當可信的未來重置或重試時間不超過最大等待時間時使用它。", + "dynamicPolicySkip": "跳過候選設定", + "dynamicPolicyStop": "停止並手動恢復", + "dynamicPolicyRetryHelp": "在應用所選結果前,以指數退避方式重試同一候選設定。", + "dynamicPolicyWaitHelp": "等待可信的未來提供者重置或重試時間。等待時間有限制,並且每個候選設定和類別只使用一次。", + "dynamicPolicyOutcomeHelp": "控制重置等待和同一候選設定的所有重試都耗盡後 Kandev 的操作。", "dynamicPolicyOptionInfo": "解釋 {{option}} 策略", - "addDynamicCandidate": "新增候選設定檔", - "noDynamicCandidates": "至少新增一個具體設定檔。", - "moveDynamicCandidateUp": "上移候選設定檔", - "moveDynamicCandidateDown": "下移候選設定檔", - "removeDynamicCandidate": "移除候選設定檔", - "dynamicCandidatePickerDescription": "選擇符合動態路由條件的具體設定檔。", - "searchDynamicCandidates": "搜尋代理設定檔...", - "noDynamicCandidatesFound": "找不到符合條件的代理設定檔。", - "dynamicRouteAction": "供應商發生錯誤時", + "addDynamicCandidate": "新增候選設定", + "noDynamicCandidates": "至少新增一個具體設定。", + "moveDynamicCandidateUp": "上移候選設定", + "moveDynamicCandidateDown": "下移候選設定", + "removeDynamicCandidate": "移除候選設定", + "dynamicCandidatePickerDescription": "選擇一個符合動態路由條件的具體設定。", + "searchDynamicCandidates": "搜尋代理設定...", + "noDynamicCandidatesFound": "未找到符合條件的代理設定。", + "dynamicRouteAction": "提供者出錯時", "dynamicRouteActionInfo": "說明{{action}}路由行為", - "dynamicRouteRetryDescription": "供應商發生錯誤後重試相同候選設定檔。適用於可能暫時恢復的故障。", - "dynamicRouteTryNextDescription": "本次執行略過此候選設定檔,繼續使用下一個符合條件的設定檔。", - "dynamicRouteStopDescription": "此候選設定檔失敗後停止路由。工作會等待手動恢復操作。", - "dynamicProfileSaved": "動態設定檔已儲存。", + "dynamicRouteRetryDescription": "提供者出錯後重試同一候選設定。適用於可能暫時恢復的故障。", + "dynamicRouteTryNextDescription": "本次執行跳過此候選設定,繼續使用下一個符合條件的設定。", + "dynamicRouteStopDescription": "此候選設定失敗後停止路由。任務會等待手動恢復操作。", + "dynamicProfileSaved": "動態設定已儲存。", "adminOnly": "只有管理員可以更改代理和代理設定檔。" } diff --git a/apps/web/src/locales/zh-tw/auth.json b/apps/web/src/locales/zh-tw/auth.json index 5783fcc7c5..4aaaa14ab7 100644 --- a/apps/web/src/locales/zh-tw/auth.json +++ b/apps/web/src/locales/zh-tw/auth.json @@ -16,7 +16,7 @@ "joinThisKandevDeployment": "加入此 Kandev 部署。", "joining": "正在加入…", "orContinueWith": "或使用以下方式繼續", - "organizationUnavailable": "您的組織目前無法使用。請聯絡您的 Kandev 管理員。", + "organizationUnavailable": "您的組織目前不可用。請聯絡您的 Kandev 管理員。", "password": "密碼", "setUpKandev": "設定 Kandev", "setupFailed": "初始化失敗。請重試。", diff --git a/apps/web/src/locales/zh-tw/automations.json b/apps/web/src/locales/zh-tw/automations.json index d7a744a56f..8a31fc9032 100644 --- a/apps/web/src/locales/zh-tw/automations.json +++ b/apps/web/src/locales/zh-tw/automations.json @@ -32,13 +32,13 @@ "comingSoonSuffix": "(即將推出)", "completeRequiredFields": "請先填寫必填的自動化欄位,再儲存。", "completed": "已完成", - "contextBetweenRunsConcurrencyLock": "此選項一次只支援一個執行中的工作。", - "contextBetweenRunsDescription": "選擇每次執行是重新開始,還是繼續使用相同的對話和檔案。", - "contextBetweenRunsNewTask": "每次執行都開始新工作", - "contextBetweenRunsNewTaskDescription": "每次執行都會使用獨立的對話和檔案。這些工作不會出現在看板或側邊欄。此選項適用於互相獨立的工作和並行執行。", - "contextBetweenRunsNewTaskNormalDescription": "每次執行都會使用獨立的對話和檔案。這些工作會出現在看板和側邊欄。此選項適用於互相獨立的工作和並行執行。", + "contextBetweenRunsConcurrencyLock": "此選項一次只支援一個執行中的任務。", + "contextBetweenRunsDescription": "選擇每次執行是從頭開始,還是繼續使用相同的對話和檔案。", + "contextBetweenRunsNewTask": "每次執行都開始新任務", + "contextBetweenRunsNewTaskDescription": "每次執行都會使用獨立的對話和檔案。這些任務不會出現在看板或側邊欄中。此選項適用於相互獨立的作業和併發執行。", + "contextBetweenRunsNewTaskNormalDescription": "每次執行都會使用獨立的對話和檔案。這些任務會出現在看板和側邊欄中。此選項適用於相互獨立的作業和併發執行。", "contextBetweenRunsReuseThread": "繼續之前的工作階段", - "contextBetweenRunsReuseThreadDescription": "執行會繼續使用相同的對話和檔案,讓代理保留之前的上下文和變更。執行會依次進行。", + "contextBetweenRunsReuseThreadDescription": "執行會繼續使用相同的對話和檔案,因此代理可以保留之前的上下文和更改。執行會依次執行。", "contextBetweenRunsTitle": "執行之間的上下文", "configurationLabel": "設定", "couldNotLoadWorkflows": "無法載入工作流程", @@ -52,7 +52,7 @@ "cronHelp": "標準五欄位 cron 或快捷方式({{shortcuts}})", "delete": "刪除", "deleteAutomationTitle": "刪除自動化?", - "deleteAutomationDescription": "這將永久刪除 {{name}}。此操作無法復原。", + "deleteAutomationDescription": "這將永久刪除 {{name}}。此操作無法撤銷。", "deleteAll": "全部刪除", "deleteAllRuns": "刪除所有執行記錄", "deleteAllRunsDescription": "這將永久刪除此自動化的所有執行記錄;包括目前未載入的記錄;以及關聯的任務。此操作無法撤銷。", @@ -123,9 +123,9 @@ "replyToThisRun": "回覆此執行…", "repositoryLabel": "儲存庫", "repositoryNone": "無;不使用儲存庫", - "repositoryModeTitle": "儲存庫存取權", - "repositoryModeDescription": "新增一個或多個儲存庫與基礎分支組合,或在沒有儲存庫的情況下執行。", - "repositoryModeNoneDescription": "在任務專屬的暫存工作區中執行,不使用儲存庫檔案。", + "repositoryModeTitle": "儲存庫存取", + "repositoryModeDescription": "新增一個或多個儲存庫與基礎分支組合,或在無儲存庫的情況下執行。", + "repositoryModeNoneDescription": "在任務專屬的臨時工作區中執行,不使用儲存庫檔案。", "repositoryPlaceholderAuto": "自動", "required": "必填", "resizeRuns": "調整執行記錄區域大小", @@ -188,14 +188,14 @@ "taskTitleLabel": "任務標題", "taskTitlePlaceholder": "[自動] 自動化名稱", "taskModeTitle": "執行目標", - "taskModeDescription": "選擇每次觸發只保留在自動化記錄中,還是建立普通任務。", - "taskModeAutomationRun": "只在自動化記錄中執行", - "taskModeAutomationRunDescription": "每次執行使用私人任務和對話。這些任務不會出現在看板或側邊欄。", + "taskModeDescription": "選擇每次觸發是隻保留在自動化歷史中,還是建立普通任務。", + "taskModeAutomationRun": "僅在自動化歷史中執行", + "taskModeAutomationRunDescription": "每次執行使用私有任務和對話。這些任務不會出現在看板或側邊欄中。", "taskModeNormalTask": "建立普通任務", - "taskModeNormalTaskDescription": "每次執行都會在選取的工作流程中建立普通任務。任務會出現在看板和側邊欄。", + "taskModeNormalTaskDescription": "每次執行都會在選定的工作流程中建立普通任務。任務會出現在看板和側邊欄中。", "workflowRequiredLabel": "工作流程(必填)", "selectWorkflowRequired": "選擇工作流程", - "normalTaskWorkflowHelp": "選擇工作流程,讓此任務出現在看板和側邊欄。", + "normalTaskWorkflowHelp": "選擇工作流程,讓此任務出現在看板和側邊欄中。", "thenDescription": "每次此自動化觸發時都會建立一個新任務", "thenTitle": "然後", "triggerCategoryGithub": "GitHub", diff --git a/apps/web/src/locales/zh-tw/azuredevops.json b/apps/web/src/locales/zh-tw/azuredevops.json index 2617411eff..134ee9b28a 100644 --- a/apps/web/src/locales/zh-tw/azuredevops.json +++ b/apps/web/src/locales/zh-tw/azuredevops.json @@ -146,13 +146,13 @@ "personalAccessToken": "個人存取權杖", "placeholderTitleDescription": "Azure DevOps 工作項或提取要求的標題", "placeholderUrlDescription": "Azure DevOps 工作項或提取要求的 URL", - "placeholderDescriptionBody": "描述內容", + "placeholderDescriptionBody": "描述正文", "placeholderIdDescription": "工作項或提取要求 ID", "placeholderProjectDescription": "專案名稱", - "placeholderSourceBranchDescription": "來源分支", + "placeholderSourceBranchDescription": "源分支", "placeholderStateDescription": "目前狀態", "placeholderTargetBranchDescription": "目標分支", - "placeholderTypeDescription": "工作項類型", + "placeholderTypeDescription": "工作項型別", "planningAndEffort": "規劃與工作量", "policiesLabelled": "策略:{{state}}", "pollIntervalSeconds": "輪詢間隔(秒)", diff --git a/apps/web/src/locales/zh-tw/chat.json b/apps/web/src/locales/zh-tw/chat.json index fb51afc34d..981919aaac 100644 --- a/apps/web/src/locales/zh-tw/chat.json +++ b/apps/web/src/locales/zh-tw/chat.json @@ -96,7 +96,7 @@ "quickChatDialogIntro": "與代理程式開始快速對話,無需建立正式任務。", "quickChatIntro": "就想法、問題或程式碼庫與代理程式聊天。", "quickChatIntroSecondary": "快速聊天獨立於任務看板。", - "quickChatTabOrderSaveFailed": "無法儲存快速聊天分頁順序。", + "quickChatTabOrderSaveFailed": "無法儲存快速聊天標籤頁順序。", "quickChatTabOrderSaveFailedDescription": "目前順序會保留在此處。重新載入可恢復上次儲存的順序。", "renameChat": "重新命名聊天", "renameSavedOnThisDeviceOnly": "重新命名僅儲存在此裝置上", diff --git a/apps/web/src/locales/zh-tw/common.json b/apps/web/src/locales/zh-tw/common.json index 72b01ac3e1..9b5fee7b72 100644 --- a/apps/web/src/locales/zh-tw/common.json +++ b/apps/web/src/locales/zh-tw/common.json @@ -78,7 +78,7 @@ "commandGoToStats": "前往統計", "commandGoToStatsKeywords": "統計, 資料分析, 分析, 指標", "commandGoToThreads": "前往對話流", - "commandGoToThreadsKeywords": "對話流, 代理程式, 即時, 欄", + "commandGoToThreadsKeywords": "對話流, 代理程式, 即時, 列", "commandGroupActions": "操作", "commandGroupAgent": "代理程式", "commandGroupCommands": "命令", diff --git a/apps/web/src/locales/zh-tw/github.json b/apps/web/src/locales/zh-tw/github.json index 7a05134ad2..fd11056ae1 100644 --- a/apps/web/src/locales/zh-tw/github.json +++ b/apps/web/src/locales/zh-tw/github.json @@ -382,7 +382,7 @@ "prTaskStatusCi": "CI", "prTaskStatusMerge": "合併", "prTaskStatusNumber": "PR #{{number}}", - "prTaskStatusRepositoryNumber": "{{repository}} 拉取請求 #{{number}}", + "prTaskStatusRepositoryNumber": "{{repository}} 提取要求 #{{number}}", "prTaskStatusReview": "審閱", "prTaskStatusState": "狀態", "prepareAppOnGithub": "在 GitHub 上準備應用", diff --git a/apps/web/src/locales/zh-tw/jira.json b/apps/web/src/locales/zh-tw/jira.json index 4a03bc97e0..ba3946926b 100644 --- a/apps/web/src/locales/zh-tw/jira.json +++ b/apps/web/src/locales/zh-tw/jira.json @@ -220,7 +220,7 @@ "oauthTokenExpires": "權杖過期時間:{{date}}", "oauthPasteInstructions": "在新標籤頁中完成授權", "oauthPasteHelp": "在 Atlassian 上批准後,你將被重定向到一個無法載入的 localhost 網址。請從瀏覽器位址列複製完整網址並貼上到下方。", - "oauthPopupBlocked": "瀏覽器已封鎖授權視窗。請允許彈出式視窗,然後再試。", + "oauthPopupBlocked": "瀏覽器已阻止授權視窗。請允許彈出視窗,然後重試。", "oauthComplete": "完成", "oauthCancel": "取消", "oauthPasteInvalid": "網址無效。請確保複製了包含 code 和 state 引數的完整重定向網址。" diff --git a/apps/web/src/locales/zh-tw/kanban.json b/apps/web/src/locales/zh-tw/kanban.json index 571f4d3d9a..3ed25a0a63 100644 --- a/apps/web/src/locales/zh-tw/kanban.json +++ b/apps/web/src/locales/zh-tw/kanban.json @@ -101,9 +101,9 @@ "wipTaskCount": "{{label}} 個任務", "workflow": "工作流程", "workflowStepFallback": "工作流程步驟 {{stepId}}", - "columns": "欄", - "autoHideEmptyColumns": "自動隱藏空白欄", - "allEmptyStepsAutoHidden": "所有空白步驟都已隱藏。在「欄」中關閉「自動隱藏空白欄」即可重新顯示它們。", + "columns": "列", + "autoHideEmptyColumns": "自動隱藏空列", + "allEmptyStepsAutoHidden": "所有空步驟都已隱藏。在「列」中關閉「自動隱藏空列」即可重新顯示它們。", "columnsForWorkflow": "{{name}} 的列", "needsReassignment": "需要重新分配", "blockedByCount_one": "被 {{count}} 項阻塞", diff --git a/apps/web/src/locales/zh-tw/orgs.json b/apps/web/src/locales/zh-tw/orgs.json index 610d930b43..4275fe6d9d 100644 --- a/apps/web/src/locales/zh-tw/orgs.json +++ b/apps/web/src/locales/zh-tw/orgs.json @@ -3,34 +3,34 @@ "adminCreate": "建立管理員", "adminCreated": "管理員已建立。", "adminDescription": "管理員只能在自己的組織中建立帳戶,因此新組織需要在此建立首位管理員。", - "adminEmail": "電子郵件", + "adminEmail": "電子郵件地址", "adminName": "顯示名稱", "adminPassword": "密碼", - "adminPasswordHint": "至少 8 個字元。請告知對方並要求其登入後變更。", + "adminPasswordHint": "至少 8 個字元。請告知對方並要求其登入後修改。", "adminTitle": "{{name}} 的首位管理員", - "boundaryDescription": "工作區、任務、工作階段、密鑰和帳戶均屬於一個組織。身為執行個體維運人員,您管理組織本身;但不會取得任何組織內部的存取權限,包括您自己的組織。", + "boundaryDescription": "工作區、任務、工作階段、金鑰和帳戶均歸屬於一個組織。作為實例運維人員,您管理組織本身;但不會獲得任何組織內部的存取權限,包括您自己的組織。", "boundaryTitle": "組織隔離的內容", "create": "建立", "createDescription": "先建立組織,然後新增其首位管理員。此後該組織將自行管理。", - "createTitle": "新增組織", + "createTitle": "新建組織", "created": "組織已建立。", "defaultBadge": "預設", "delete": "刪除組織", "deleteConfirm": "刪除組織", "deleteConfirmLabel": "輸入 {{slug}} 以確認", "deleteTitle": "刪除 {{name}}", - "deleteWarning": "這將移除該組織中的所有工作區、任務、工作階段和帳戶,且無法復原。", + "deleteWarning": "這將移除該組織中的所有工作區、任務、工作階段和帳戶,且無法撤銷。", "deleted": "組織已刪除。", - "description": "每個組織都是獨立的租戶。使用者僅屬於一個組織,組織之間無法看到彼此的工作區、任務或密鑰。", - "genericError": "無法儲存該變更。", + "description": "每個組織都是獨立的租戶。使用者僅屬於一個組織,組織之間無法看到彼此的工作區、任務或金鑰。", + "genericError": "無法儲存該更改。", "nameLabel": "組織名稱", "namePlaceholder": "Acme Corp", "navOrganizations": "組織", - "operatorOnly": "只有執行個體維運人員可以管理組織。", + "operatorOnly": "只有實例運維人員可以管理組織。", "renamed": "組織已重新命名。", "resume": "恢復", "resumed": "組織已恢復。", - "statusActive": "使用中", + "statusActive": "活動", "statusSuspended": "已暫停", "suspend": "暫停", "suspended": "組織已暫停。", diff --git a/apps/web/src/locales/zh-tw/settings.json b/apps/web/src/locales/zh-tw/settings.json index eae1ea586b..d9b0199227 100644 --- a/apps/web/src/locales/zh-tw/settings.json +++ b/apps/web/src/locales/zh-tw/settings.json @@ -508,9 +508,9 @@ "programming": "程式設計", "promptAdd": "新增提示詞", "promptEditorAriaLabel": "提示詞編輯器", - "promptEditorBothHint": "輸入 {{placeholder}} 查看可用佔位符,或輸入 {{mention}} 查看已儲存的提示詞。", - "promptEditorPlaceholderHint": "輸入 {{placeholder}} 查看可用佔位符。", - "promptEditorPromptReferenceHint": "輸入 {{mention}} 查看已儲存的提示詞。", + "promptEditorBothHint": "輸入 {{placeholder}} 檢視可用佔位符,或輸入 {{mention}} 檢視已儲存的提示詞。", + "promptEditorPlaceholderHint": "輸入 {{placeholder}} 檢視可用佔位符。", + "promptEditorPromptReferenceHint": "輸入 {{mention}} 檢視已儲存的提示詞。", "promptCreateFailed": "無法建立提示詞", "promptDelete": "刪除提示詞", "promptDeleteDescription": "這將永久移除 <2>{{name}}。此操作無法撤銷。", @@ -751,22 +751,22 @@ "keyValueKeyPlaceholder": "鍵", "keyValueValuePlaceholder": "值", "profileStartModelNotAdvertisedOnHost": "主機探測未公佈 {{model}}。所選執行器將在啟動時決定使用的模型。", - "navUnits": "組織單位", - "unitsTitle": "組織單位", - "unitsDescription": "單位包含團隊、工作區和成員。加入某個單位即可存取其下的所有工作區,包括之後建立的。", - "unitsEmpty": "尚無單位。", + "navUnits": "組織單元", + "unitsTitle": "組織單元", + "unitsDescription": "單元包含團隊、工作區和成員。加入某個單元即可存取其下的所有工作區,包括之後建立的。", + "unitsEmpty": "尚無單元。", "unitRootBadge": "整個組織", "unitPersonalBadge": "個人", - "unitAddChild": "新增單位", + "unitAddChild": "新增單元", "unitMembers": "成員", - "unitDelete": "刪除單位", - "unitCreateTitle": "在 {{parent}} 中新增單位", - "unitCreateDescription": "部門和團隊都是單位,差別只在於所處位置。", - "unitNamePlaceholder": "平台", + "unitDelete": "刪除單元", + "unitCreateTitle": "在 {{parent}} 中新建單元", + "unitCreateDescription": "部門和團隊都是單元,區別只在於所處位置。", + "unitNamePlaceholder": "平臺", "unitCreate": "建立", "unitMembersTitle": "{{unit}} 的成員", - "unitMembersDescription": "這裡的每個人都能以你指定的角色存取該單位下的所有工作區。", - "unitNoMembers": "該單位尚無成員。", + "unitMembersDescription": "這裡的每個人都能以你指定的角色存取該單元下的所有工作區。", + "unitNoMembers": "該單元暫無成員。", "unitAddMember": "新增", "unitRemoveMember": "移除成員", "unitPickPerson": "選擇成員", diff --git a/apps/web/src/locales/zh-tw/system.json b/apps/web/src/locales/zh-tw/system.json index 387a5e8941..e1c6dd643f 100644 --- a/apps/web/src/locales/zh-tw/system.json +++ b/apps/web/src/locales/zh-tw/system.json @@ -13,7 +13,7 @@ "actionDone": "完成", "actionFailed": "失敗", "actionRunning": "執行中…", - "backupsAdminOnly": "只有管理員可以建立、下載、還原或刪除備份。", + "backupsAdminOnly": "只有管理員可以建立、下載、恢復或刪除備份。", "backupsColumnActions": "操作", "backupsColumnCreated": "建立時間", "backupsColumnKind": "型別", @@ -273,8 +273,23 @@ "storageAnalysisComplete": "分析完成", "storageAnalysisDescription": "目前用量與可回收空間的只讀分解。偶爾執行「分析」以重新整理估算;它從不刪除或移動任何內容。", "storageAnalysisFailed": "分析失敗", + "storageAnalysisCacheLifetime": "快取有效期:{{duration}}", + "storageAnalysisDuration": "掃描時長:{{duration}}", + "storageAnalysisDurationMilliseconds": "{{value}} 毫秒", + "storageAnalysisDurationMinutes": "{{value}} 分鐘", + "storageAnalysisDurationSeconds": "{{value}} 秒", + "storageAnalysisNextRefresh": "下次重新整理:{{absolute}}({{relative}})", + "storageAnalysisNextRefreshUnknown": "下次重新整理時間不可用。", "storageAnalysisRunning": "儲存分析仍在執行。", + "storageAnalysisSourceComplete": "測量完成", + "storageAnalysisSourceFailed": "測量失敗", + "storageAnalysisSourceFailedWithError": "測量失敗:{{error}}", + "storageAnalysisSourcePending": "等待測量", + "storageAnalysisSourceScanning": "正在測量 {{completed}}/{{total}}", + "storageAnalysisSourceScanningUnknown": "正在測量", "storageAnalysisTitle": "儲存分析", + "storageAnalysisTimingHelp": "分析會立即重新整理這些資料。掃描會在儲存頁面或其他用戶端開啟時按需執行。", + "storageAnalysisTimingTitle": "分析時間", "storageAnalyze": "分析", "storageAnalyzing": "正在分析…", "storageBuildCacheKeepHelp": "清理符合條件的記錄時,Docker 大約保留這麼多構建快取。值越大可保留更多可複用層,但回收空間更少。", @@ -438,6 +453,7 @@ "storageToastPolicySaved": "儲存策略已儲存", "storageToastQuarantineRestored": "已恢復隔離資源", "storageTotalCounted": "已統計總量:{{size}}", + "storageTotalCountedSoFar": "目前已統計:{{size}}", "storageTotalPartial": "部分測量結果", "storageTrashPath": "回收站:{{path}}", "storageTypeToConfirm": "輸入 <1>{{phrase}} 以繼續。", diff --git a/apps/web/src/locales/zh-tw/task.json b/apps/web/src/locales/zh-tw/task.json index 2296b0913c..a6790e36af 100644 --- a/apps/web/src/locales/zh-tw/task.json +++ b/apps/web/src/locales/zh-tw/task.json @@ -37,7 +37,7 @@ "addReviewer": "+ 新增審閱人", "addShort": "+ 新增", "addSubIssue": "新增子議題", - "addToWorkspace": "加入工作區", + "addToWorkspace": "新增到工作區", "addYourCommentOrInstruction": "新增你的評論或指示…", "addedRemoved": "新增 {{added}} · 刪除 {{removed}}", "adding": "正在新增…", @@ -970,7 +970,7 @@ "plan": "計劃", "planCommentCount_one": "{{count}} 條計劃評論", "planCommentCount_other": "{{count}} 條計劃評論", - "planContentTooLarge": "您的計劃為 {{submitted}},超過了 {{limit}} 的限制。請縮短文件後重新儲存。", + "planContentTooLarge": "您的計劃為 {{submitted}},超過了 {{limit}} 的限制。請縮短檔案後重新儲存。", "planHistory": "計劃歷史", "planIsEmpty": "計劃為空", "planLoadError": "無法載入計劃。", @@ -1953,24 +1953,24 @@ "branchPolicyOptionSummary": "從 {{base}} 到 {{target}}", "branchPolicySelected": "{{name}}(從 {{base}})", "branchPolicyUnavailable": "基礎分支不可用。請重新整理分支或編輯此策略。", - "branchPolicyRequiresSingleRepository": "使用本機執行器時,分支策略需要單一儲存庫。", + "branchPolicyRequiresSingleRepository": "使用本地執行器時,分支策略需要單個儲存庫。", "assignedTo": "指派給", "unassigned": "未指派", "assignToMe": "指派給我", "searchPeople": "搜尋成員", - "noPeopleFound": "找不到成員", + "noPeopleFound": "未找到成員", "assignedToName": "指派給 {{name}}", "uploadConflictTitle_one": "{{count}} 個檔案已存在", "uploadConflictTitle_other": "{{count}} 個檔案已存在", "uploadConflictBody": "請選擇如何處理每個檔案。確認之前不會上傳任何內容。", - "uploadConflictApplyToAll": "套用至全部", + "uploadConflictApplyToAll": "應用於全部", "uploadConflictKeepBoth": "兩者都保留", - "uploadConflictReplace": "取代", - "uploadConflictSkip": "略過", + "uploadConflictReplace": "替換", + "uploadConflictSkip": "跳過", "uploadConflictConfirm": "上傳", "uploadFiles": "上傳檔案", "uploadFolder": "上傳資料夾", - "uploadFilesHere": "上傳檔案至此", + "uploadFilesHere": "上傳檔案到此處", "uploadComplete_one": "已上傳 {{count}} 個檔案", "uploadComplete_other": "已上傳 {{count}} 個檔案", "uploadedTo": "已上傳至 {{path}}", diff --git a/apps/web/src/locales/zh-tw/workspaces.json b/apps/web/src/locales/zh-tw/workspaces.json index d9a9e20fba..c8c02b4ac5 100644 --- a/apps/web/src/locales/zh-tw/workspaces.json +++ b/apps/web/src/locales/zh-tw/workspaces.json @@ -209,44 +209,44 @@ "branchPolicyGitflowCreated": "Gitflow 策略已建立", "branchPolicyGitflowFailed": "無法建立 Gitflow 策略。", "branchPolicySummary": "基礎:{{base}}。模板:{{template}}。提取要求目標:{{target}}。", - "defaultVisibility.description": "適用於此後建立的工作區。現有工作區維持其目前的可見性。", - "defaultVisibility.existingUnaffected": "變更此設定絕不會變更現有工作區。", + "defaultVisibility.description": "適用於此後建立的工作區。現有工作區保持其目前可見性。", + "defaultVisibility.existingUnaffected": "更改此設定絕不會更改現有工作區。", "defaultVisibility.label": "新工作區為", "defaultVisibility.savedOrg": "新工作區將對組織可見。", - "defaultVisibility.savedPrivate": "新工作區將為私人。", + "defaultVisibility.savedPrivate": "新工作區將為私有。", "defaultVisibility.title": "新工作區預設設定", "teamAccess.addMember": "新增", "teamAccess.addMemberLabel": "新增同事", - "teamAccess.addMemberPlaceholder": "選擇一位人員", - "teamAccess.description": "選擇誰可以存取此工作區,並為同事指派角色。", - "teamAccess.genericError": "無法儲存該變更。", - "teamAccess.makeOwner": "設為擁有者", - "teamAccess.memberAdded": "已新增成員。", - "teamAccess.memberRemoved": "已移除成員。", + "teamAccess.addMemberPlaceholder": "選擇一個人", + "teamAccess.description": "選擇誰可以存取此工作區,併為同事分配角色。", + "teamAccess.genericError": "無法儲存該更改。", + "teamAccess.makeOwner": "設為所有者", + "teamAccess.memberAdded": "成員已新增。", + "teamAccess.memberRemoved": "成員已移除。", "teamAccess.membersLabel": "成員", - "teamAccess.noMembers": "尚無成員。擁有者一律具有完整存取權限。", + "teamAccess.noMembers": "暫無成員。所有者始終擁有完全存取權限。", "teamAccess.noUsersToAdd": "所有人都已是成員", "teamAccess.nowOrgVisible": "此工作區現在對組織可見。", - "teamAccess.nowPrivate": "此工作區現在為私人。", - "teamAccess.ownershipTransferred": "{{name}} 現在是擁有者。", + "teamAccess.nowPrivate": "此工作區現在為私有。", + "teamAccess.ownershipTransferred": "{{name}} 現在是所有者。", "teamAccess.removeMember": "移除成員", "teamAccess.roleCollaborator": "協作者", "teamAccess.roleLabel": "角色", - "teamAccess.roleOwner": "擁有者", - "teamAccess.roleUpdated": "已更新角色。", + "teamAccess.roleOwner": "所有者", + "teamAccess.roleUpdated": "角色已更新。", "teamAccess.roleViewer": "檢視者", "teamAccess.title": "團隊存取", "teamAccess.visibilityLabel": "可見性", "teamAccess.visibilityOrg": "組織中的所有人", "teamAccess.visibilityOrgHint": "除訪客外的所有使用者都可以開啟此工作區並處理其任務。", - "teamAccess.visibilityPrivate": "私人", - "teamAccess.visibilityPrivateHint": "只有擁有者和下方列出的成員可以開啟此工作區。", + "teamAccess.visibilityPrivate": "私有", + "teamAccess.visibilityPrivateHint": "只有所有者和下方列出的成員可以開啟此工作區。", "placement.title": "位置", - "placement.description": "該工作區所屬的單位,也就決定了誰能存取它。移動它是改變存取範圍的唯一方式:角色按最高權限合併,無法就地收回。", - "placement.pick": "選擇單位", - "placement.search": "搜尋單位", - "placement.none": "找不到單位", + "placement.description": "該工作區所屬的單元,也就決定了誰能存取它。移動它是改變存取範圍的唯一方式:角色按最高權限合併,無法就地收回。", + "placement.pick": "選擇單元", + "placement.search": "搜尋單元", + "placement.none": "未找到單元", "placement.moved": "工作區已移動。", "placement.failed": "無法移動該工作區。", - "placement.ownerOnly": "僅工作區擁有者可移動" + "placement.ownerOnly": "僅工作區所有者可移動" } diff --git a/docs/decisions/2026-09-05-bounded-progressive-storage-analysis.md b/docs/decisions/2026-09-05-bounded-progressive-storage-analysis.md new file mode 100644 index 0000000000..2bfccc5d7f --- /dev/null +++ b/docs/decisions/2026-09-05-bounded-progressive-storage-analysis.md @@ -0,0 +1,61 @@ +# ADR-2026-09-05-bounded-progressive-storage-analysis: Use bounded progressive storage analysis + +**Status:** accepted +**Date:** 2026-09-05 +**Area:** backend, frontend, protocol + +## Context + +The storage overview already runs its top-level providers concurrently. Large workspace and cache +trees still take a long time because each provider walks directories serially. + +The overview endpoint also waits for every provider. A cold or expired cache therefore leaves the +analysis card empty until the slowest scan finishes. + +Operators need useful progress, but a partial scan must not look like a complete snapshot. Storage +paths and byte counts also must not leak through broadcast WebSocket events. + +## Decision + +Storage analysis will use a shared limit of four active read-only directory partitions. The scanner +will preserve the symlink, marker, containment, and ownership rules of each provider. + +The overview cache will use stale-while-revalidate reads. A read returns the last successful +snapshot immediately and starts one background refresh when that snapshot is absent or expired. + +The last successful snapshot remains atomic. During the first cold scan, partial results remain in +a separate current-scan field and every aggregate is identified as incomplete. + +The cache will publish `system.storage.analysis.updated` after bounded progress changes. The event +contains only generation and state. An authorized client refetches the admin endpoint for details. + +The WebSocket event is the primary update signal. A short poll operates only while analysis is +active and recovers a missed event. + +The snapshot cache remains process-local. The page requests a refresh at the cache deadline while +it stays open, and manual Analyze requests an immediate refresh. + +## Consequences + +- Independent directory partitions can overlap without unbounded filesystem pressure. +- A cold scan can show completed sources before the full snapshot is ready. +- An expired snapshot stays useful while Kandev measures its replacement. +- The API must distinguish complete snapshots from current-scan partial results. +- A backend restart still has a cold cache. +- The frontend needs event-triggered reads, a bounded poll fallback, and refresh-time scheduling. +- Scan metadata can show duration, cache lifetime, and the next page-owned refresh time. + +## Alternatives Considered + +- **Keep the blocking endpoint.** Rejected because top-level parallelism cannot improve first-result + latency when one filesystem provider dominates. +- **Send full progress in WebSocket events.** Rejected because broadcast events can expose paths, + sizes, warnings, or errors outside the admin request boundary. +- **Persist completed snapshots across backend restarts.** Rejected because it adds a migration, + schema-version rules, and stale host-state recovery for a cache. +- **Replace snapshot values source by source during refresh.** Rejected because one displayed total + can then mix measurements from different times. +- **Start a permanent backend refresh timer.** Rejected because Kandev scans idle installations + that have no active Storage viewer. +- **Use unbounded or file-level parallelism.** Rejected because it can increase disk contention, + allocate excessive goroutines, and complicate symlink safety. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index c5f7c81f8e..6203fe7d3b 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -247,3 +247,4 @@ Read individual ADRs for full context. Create new ones via `/record decision` or | 2026-09-04-use-repository-token-for-runtime-pin-prs | [Use the built-in Actions token for runtime pin PRs](2026-09-04-use-repository-token-for-runtime-pin-prs.md) | accepted | workflow, security | 2026-09-04 | | 2026-09-05-agent-owned-credential-file-conflicts | [Agent-owned credential file conflicts](2026-09-05-agent-owned-credential-file-conflicts.md) | accepted | backend | 2026-09-05 | | 2026-09-06-opt-in-external-e2e-runners | [Opt in selected Linux CI jobs to external runners](2026-09-06-opt-in-external-e2e-runners.md) | accepted | infra, workflow, security | 2026-09-06 | +| 2026-09-05-bounded-progressive-storage-analysis | [Use bounded progressive storage analysis](2026-09-05-bounded-progressive-storage-analysis.md) | accepted | backend, frontend, protocol | 2026-09-05 | diff --git a/docs/plans/storage-analysis-progress/plan.md b/docs/plans/storage-analysis-progress/plan.md new file mode 100644 index 0000000000..74ba149054 --- /dev/null +++ b/docs/plans/storage-analysis-progress/plan.md @@ -0,0 +1,174 @@ +--- +created: 2026-09-05 +status: complete +requirements: + - REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002 +system_design: + - ../../specs/system-page/system-design/storage-analysis-progress.md +legacy_specs: [] +--- + +# Implementation Plan: Progressive Storage Analysis + +## Overview + +Reduce scan time with bounded filesystem concurrency. Then make overview reads nonblocking and +stream coarse progress to the Storage page. + +The order protects the cache contract. The scanner lands first, the backend state contract follows, +and the web work consumes that contract. + +## Scope + +### In scope + +- Bounded, context-aware byte measurement for read-only storage analysis. +- Nonblocking overview reads with stale-while-revalidate behavior. +- Coarse progress notifications with a polling fallback. +- First-scan partial results and atomic replacement of older snapshots. +- Scan duration, cache lifetime, and next-refresh details. +- Desktop and phone access to the timing disclosure. +- Focused public operator documentation. + +### Out of scope + +- Changes to destructive cleanup or quarantine rules. +- A persistent overview snapshot across backend restarts. +- A user-configurable scan worker count or cache lifetime. +- File-level progress events or exact time-remaining estimates. +- Remote-executor disk analysis. +- Automatic scans when no client reads the Storage overview. + +## Technical approach + +### Bounded filesystem measurement + +Add `apps/backend/internal/system/storage/filescan`. Its shared limiter will permit four active +directory partitions across workspace, Go-cache, and temporary-artifact analysis. + +Partition each root by immediate children. Preserve provider-specific symlink rejection, marker +exclusion, warning order, and path ownership. + +Inject the limiter through `storageOverview` provider construction. Keep destructive provider paths +on their current serial code. + +### Progressive cache and API + +Extend `OverviewCache` with process-local analysis state and a nonblocking read. Keep `Refresh` as +the tracked manual path and join every concurrent request to one scan generation. + +Add source progress callbacks to `storageOverview`. Keep the last successful `Summary` atomic and +store cold-scan partial results separately. + +Extend `GET /api/v1/system/storage` with nullable first-scan snapshot fields and an `analysis` +object. Include scan timestamps, duration, cache lifetime, refresh time, source progress, and a +partial summary. + +Publish `system.storage.analysis.updated` with generation and state only. Add the event constant, +gateway action, subscription, and frontend revision field. + +### Web state and presentation + +Update storage API types and the Zustand system slice for analysis state and revision ordering. + +Refactor `useStorageMaintenance` so WebSocket revisions reload only the overview. Poll every 1.5 +seconds while analysis is active and stop in a terminal state. + +Schedule one read at `refresh_due_at` while the Storage page remains mounted. Preserve request +generation checks and terminal Analyze refresh behavior. + +Update `StorageOverviewCard` to show cold-scan source progress and counted-so-far totals. Keep a +stale completed snapshot visible during revalidation. + +Add an information icon beside the completed snapshot time. Reuse `StorageSettingHelp` interaction +and permit structured content for the three timing values. + +### Documentation and observability + +Update `docs/public/operations.md` with the asynchronous scan, 15-minute cache, and Analyze behavior. + +Add structured scan completion logs and storage scan metrics. Do not include task paths in logs or +metrics. + +## Tests + +| Acceptance criteria | Evidence | +| --- | --- | +| `AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.1`, `.10` | Cache and handler tests block the provider and prove immediate, single-flight reads. | +| `.2`, `.3` | Provider, cache, hook, and card tests publish sources progressively and mark partial totals. | +| `.4`, `.9` | Cache tests keep the last snapshot through expired and failed refreshes. | +| `.5` | Event, hook, and fake-timer tests cover WebSocket refresh and the 1.5-second fallback. | +| `.6`, `.7` | Component and Playwright tests cover timing values, focus, hover, tap, and touch size. | +| `.8` | Hook fake-timer tests request at `refresh_due_at`. Analyze tests retain forced refresh. | + +The filesystem scanner tests will cover exact bytes, no-follow behavior, deterministic warnings, +cancellation, and a four-worker ceiling. + +The provider tests will use barriers instead of elapsed-time assertions. They will prove that two +partitions enter before either partition is released. + +## E2E tests + +Update `apps/web/e2e/tests/system/storage-maintenance.spec.ts` for progressive cold-scan values, +stale refresh, and pointer or keyboard timing disclosure. + +Update `apps/web/e2e/tests/system/mobile-storage-maintenance.spec.ts` for tap disclosure, a 44-pixel +trigger, progressive values, and no horizontal overflow. + +Both flows map to `AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.2` through `.8`. + +## Mobile design contract + +Desktop and phone users enter through `/settings/system/storage`. Both receive the same snapshot, +progress, and timing data. + +The existing Storage page and `StorageSettingHelp` are the nearest shipped examples. They provide +the one-column card flow and the hover, focus, and pinned-tap help interaction. + +Storage analysis remains an inline card in the page scroll. No drawer or full-height surface is +necessary because the timing content contains three short values. + +The information trigger will use the existing 44-pixel phone hit area and compact desktop size. +The page keeps one scroll owner and no horizontal overflow. + +Business state, progress derivation, and refresh scheduling remain shared across viewports. Only the +responsive trigger size differs. + +## Work orders + +- [x] [Task 01: Build bounded filesystem scanner](task-01-bounded-filesystem-scanner.md) +- [x] [Task 02: Add progressive overview state](task-02-progressive-overview-state.md) +- [x] [Task 03: Render live analysis details](task-03-live-analysis-ui.md) +- [x] [Task 04: Prove progressive storage behavior](task-04-storage-progress-e2e.md) + +## Dependency order + +1. Task 01 creates the scan and progress primitives. +2. Task 02 uses those primitives for the cache, API, events, and observability. +3. Task 03 consumes the backend contract and updates public operator documentation. +4. Task 04 proves the integrated desktop and phone behavior. + +All tasks are sequential. They share contracts, fixtures, and storage test files. + +## Verification results + +- Task 01: `go test -race ./internal/system/storage/filescan ./internal/system/storage/workspaces ./internal/system/storage/gocache ./internal/system/storage/tempartifacts ./internal/backendapp` passed (853 tests). +- Task 01 benchmark: `go test ./internal/system/storage/filescan -run '^$' -bench 'BenchmarkMeasureTrees' -benchmem` passed at 81,604 ns/op and 11,367 B/op. +- Task 02: `go test -race ./internal/system/storage ./internal/backendapp ./internal/gateway/websocket` passed (1,423 tests). +- Task 03: the focused web suite passed (46 tests), the extracted terminal-refresh suite passed (2 tests), typecheck, lint, i18n checks, and public-doc validation passed. +- Task 04: `make build-web`, `make build-backend`, Chromium storage E2E (8 tests), and mobile Chromium storage E2E (6 tests) passed. +- Changed-file Go lint passed with `golangci-lint run ./... --new-from-rev=481359ddb282fd7d3e8c9cdff99da6f9bdd24c7c --timeout=5m`. +- Specification lint passed with `python3 scripts/lint-spec-files.py --all`. + +## Risks + +- Parallel directory reads can increase contention on rotating disks. The shared four-walker limit + bounds this risk, and timing evidence will record regressions. +- Partial results can look final. The API separates them from completed snapshots, and the UI marks + aggregates as counted so far. +- Late progress can corrupt a new scan. Generation checks must guard every progress and completion + write. +- Broadcast events can disclose storage facts. The event carries only generation and state. +- A missed event can leave stale UI. The active-scan poll provides recovery. +- A page timer can drift after sleep. The timer callback reads the server state instead of assuming + that a scan started. diff --git a/docs/plans/storage-analysis-progress/task-01-bounded-filesystem-scanner.md b/docs/plans/storage-analysis-progress/task-01-bounded-filesystem-scanner.md new file mode 100644 index 0000000000..2a8ead840e --- /dev/null +++ b/docs/plans/storage-analysis-progress/task-01-bounded-filesystem-scanner.md @@ -0,0 +1,87 @@ +--- +id: "01-bounded-filesystem-scanner" +title: "Build bounded filesystem scanner" +status: done +wave: 1 +depends_on: [] +plan: "plan.md" +requirements: + - REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002 +acceptance_criteria: + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.2 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.10 +system_design: + - ../../specs/system-page/system-design/storage-analysis-progress.md +--- + +# Task 01: Build Bounded Filesystem Scanner + +## Summary + +Add a shared read-only scanner with four active directory partitions. Migrate the three filesystem +analysis providers without changing cleanup behavior or byte semantics. + +## In scope + +- Add `internal/system/storage/filescan` with indexed multi-root results. +- Preserve symlink, marker, warning, cancellation, and missing-root behavior. +- Migrate workspace, Go-cache, and temporary-artifact analysis. +- Publish partition and root progress through a callback. +- Add deterministic concurrency tests and a comparison benchmark. + +## Out of scope + +- Cache, HTTP, WebSocket, or React changes. +- Destructive cleanup paths. +- Operator configuration for concurrency. + +## Acceptance + +- No more than four directory partitions execute at once across one overview scan. +- Two independent partitions can enter before either finishes, without timing assertions. +- Serial and bounded implementations return the same bytes, warnings, and symlink outcomes. + +## Verification + +```bash +(cd apps/backend && go test -race ./internal/system/storage/filescan ./internal/system/storage/workspaces ./internal/system/storage/gocache ./internal/system/storage/tempartifacts ./internal/backendapp) +(cd apps/backend && go test ./internal/system/storage/filescan -run '^$' -bench 'BenchmarkMeasureTrees' -benchmem) +``` + +## Files likely touched + +- `apps/backend/internal/system/storage/filescan/*.go` +- `apps/backend/internal/system/storage/filescan/*_test.go` +- `apps/backend/internal/system/storage/workspaces/provider.go` +- `apps/backend/internal/system/storage/workspaces/provider_test.go` +- `apps/backend/internal/system/storage/gocache/provider.go` +- `apps/backend/internal/system/storage/gocache/provider_test.go` +- `apps/backend/internal/system/storage/tempartifacts/provider.go` +- `apps/backend/internal/system/storage/tempartifacts/provider_test.go` +- `apps/backend/internal/backendapp/storage_maintenance.go` + +## Dependencies + +None. + +## Risks + +- Root partitioning can double-count direct files or overlapping paths. +- A shared limiter can deadlock if a worker acquires another slot recursively. +- Provider warning order can become nondeterministic. + +## Parallelism + +`sequential` + +## Inputs + +- `storage-analysis-progress.md` sections "Bounded filesystem scanner" and "Filesystem scan". +- Existing `directorySizeNoFollow` implementations and provider tests. + +## Results + +- Added the shared four-partition limiter and context-aware indexed scanner. +- Migrated workspace, Go-cache, and temporary-artifact analysis to the scanner while leaving cleanup traversal serial. +- Verified with `go test -race ./internal/system/storage/filescan ./internal/system/storage/workspaces ./internal/system/storage/gocache ./internal/system/storage/tempartifacts ./internal/backendapp` (853 tests passed). +- Verified `BenchmarkMeasureTrees` with `go test ./internal/system/storage/filescan -run '^$' -bench 'BenchmarkMeasureTrees' -benchmem` (81,604 ns/op, 11,367 B/op). diff --git a/docs/plans/storage-analysis-progress/task-02-progressive-overview-state.md b/docs/plans/storage-analysis-progress/task-02-progressive-overview-state.md new file mode 100644 index 0000000000..194896d70f --- /dev/null +++ b/docs/plans/storage-analysis-progress/task-02-progressive-overview-state.md @@ -0,0 +1,93 @@ +--- +id: "02-progressive-overview-state" +title: "Add progressive overview state" +status: done +wave: 2 +depends_on: + - 01-bounded-filesystem-scanner +plan: "plan.md" +requirements: + - REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002 +acceptance_criteria: + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.1 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.2 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.4 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.5 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.9 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.10 +system_design: + - ../../specs/system-page/system-design/storage-analysis-progress.md +--- + +# Task 02: Add Progressive Overview State + +## Summary + +Make storage overview reads nonblocking. Add single-flight progress state, stale-while-revalidate +snapshots, safe notifications, timing metadata, logs, and metrics. + +## In scope + +- Add progressive source callbacks to `storageOverview`. +- Extend `OverviewCache` with nonblocking state reads and generation fencing. +- Extend the storage response with snapshot, progress, and timing fields. +- Publish `system.storage.analysis.updated` without storage details. +- Add gateway wiring and focused observability. +- Preserve manual Analyze run history and job behavior. + +## Out of scope + +- Frontend rendering and polling. +- Persistent cache storage. +- Cleanup provider changes. + +## Acceptance + +- A blocked cold provider cannot block the initial HTTP response. +- Expired and failed refreshes keep the last successful snapshot unchanged. +- Concurrent reads, Analyze, invalidation, and late progress obey one generation-fenced flight. + +## Verification + +```bash +(cd apps/backend && go test -race ./internal/system/storage ./internal/backendapp ./internal/gateway/websocket) +``` + +## Files likely touched + +- `apps/backend/internal/system/storage/overview_cache.go` +- `apps/backend/internal/system/storage/overview_cache_test.go` +- `apps/backend/internal/system/storage/handler.go` +- `apps/backend/internal/system/storage/handler_test.go` +- `apps/backend/internal/system/storage/types.go` +- `apps/backend/internal/system/storage/operations.go` +- `apps/backend/internal/backendapp/storage_maintenance.go` +- `apps/backend/internal/backendapp/storage_maintenance_test.go` +- `apps/backend/internal/events/types.go` +- `apps/backend/internal/gateway/websocket/system_notifications.go` +- `apps/backend/pkg/websocket/actions.go` + +## Dependencies + +Task 01 supplies bounded progress callbacks. + +## Risks + +- Manual Analyze can accidentally create a second scan or job. +- Publishing while the cache mutex is locked can deadlock event consumers. +- A late callback can replace current state without generation checks. + +## Parallelism + +`sequential` + +## Inputs + +- `storage-analysis-progress.md` sections "Analysis state", "Cache flow", and "Progress delivery". +- ADR `2026-09-05-bounded-progressive-storage-analysis`. + +## Results + +Implemented the progressive cache/API contract, generation-fenced single-flight refreshes, +WebSocket notifications, structured completion logging, and storage scan metrics. The exact race +suite passed: 1,423 tests across storage, backendapp, and gateway/websocket. diff --git a/docs/plans/storage-analysis-progress/task-03-live-analysis-ui.md b/docs/plans/storage-analysis-progress/task-03-live-analysis-ui.md new file mode 100644 index 0000000000..594eef4296 --- /dev/null +++ b/docs/plans/storage-analysis-progress/task-03-live-analysis-ui.md @@ -0,0 +1,104 @@ +--- +id: "03-live-analysis-ui" +title: "Render live analysis details" +status: done +wave: 3 +depends_on: + - 02-progressive-overview-state +plan: "plan.md" +requirements: + - REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002 +acceptance_criteria: + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.2 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.3 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.4 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.5 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.6 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.7 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.8 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.9 +system_design: + - ../../specs/system-page/system-design/storage-analysis-progress.md +--- + +# Task 03: Render Live Analysis Details + +## Summary + +Consume the progressive backend contract. Show cold-scan results, keep stale snapshots visible, and +add the scan and cache information disclosure on desktop and phone. + +## In scope + +- Update API, Zustand, and WebSocket types. +- Reload on analysis revisions and poll while a scan is active. +- Request a refresh at `refresh_due_at` while the page is mounted. +- Render completed, pending, failed, stale, and ready states. +- Add localized timing and progress copy in all required catalogs. +- Update `docs/public/operations.md` with the refresh behavior. + +## Out of scope + +- Backend scan logic. +- A new mobile route, drawer, or scroll owner. +- Time-remaining estimates. + +## Acceptance + +- The first scan reveals completed sources and labels every aggregate as counted so far. +- A stale snapshot remains readable while progress updates continue. +- The timing disclosure works by hover, focus, click, and 44-pixel phone tap. + +## Verification + +```bash +(cd apps && pnpm --filter @kandev/web test -- --run lib/state/slices/system/system-slice.test.ts lib/ws/handlers/system-events.test.ts hooks/domains/system/use-storage-maintenance.test.tsx hooks/domains/system/use-storage-maintenance-terminal-refresh.test.tsx components/settings/system/storage/storage-overview-card.test.tsx) +(cd apps/web && pnpm run typecheck) +(cd apps/web && pnpm run i18n:check) +node --test scripts/validate-public-docs.test.mjs +node scripts/validate-public-docs.mjs +``` + +## Files likely touched + +- `apps/web/lib/types/system.ts` +- `apps/web/lib/api/domains/system-api.ts` +- `apps/web/lib/api/domains/system-api.test.ts` +- `apps/web/lib/state/slices/system/types.ts` +- `apps/web/lib/state/slices/system/system-slice.ts` +- `apps/web/lib/state/slices/system/system-slice.test.ts` +- `apps/web/lib/ws/handlers/system-events.ts` +- `apps/web/lib/ws/handlers/system-events.test.ts` +- `apps/web/hooks/domains/system/use-storage-maintenance.ts` +- `apps/web/hooks/domains/system/use-storage-maintenance.test.tsx` +- `apps/web/components/settings/system/storage/storage-overview-card.tsx` +- `apps/web/components/settings/system/storage/storage-overview-card.test.tsx` +- `apps/web/components/settings/system/storage/storage-setting-help.tsx` +- `apps/web/src/locales/*/system.json` +- `docs/public/operations.md` + +## Dependencies + +Task 02 defines the API and event contract. + +## Risks + +- A refresh timer can operate twice after a rerender if cleanup is incomplete. +- Partial and stale summaries can be combined accidentally. +- Tooltip content can become hover-only or too small for phone input. + +## Parallelism + +`sequential` + +## Inputs + +- `storage-analysis-progress.md` sections "Progress delivery" and "Storage page". +- Current `StorageSettingHelp` and Storage mobile E2E patterns. + +## Results + +Implemented progressive API/event state, polling and deadline refresh hooks, localized source and +timing disclosure UI, mobile-sized help interaction, and operator documentation. The focused suite +passed with 48 tests across five files, typecheck and lint passed, i18n catalogs and ratchet passed, +and public-doc validation passed. diff --git a/docs/plans/storage-analysis-progress/task-04-storage-progress-e2e.md b/docs/plans/storage-analysis-progress/task-04-storage-progress-e2e.md new file mode 100644 index 0000000000..c0c2564a7a --- /dev/null +++ b/docs/plans/storage-analysis-progress/task-04-storage-progress-e2e.md @@ -0,0 +1,94 @@ +--- +id: "04-storage-progress-e2e" +title: "Prove progressive storage behavior" +status: done +wave: 4 +depends_on: + - 01-bounded-filesystem-scanner + - 02-progressive-overview-state + - 03-live-analysis-ui +plan: "plan.md" +requirements: + - REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002 +acceptance_criteria: + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.1 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.2 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.3 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.4 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.5 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.6 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.7 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.8 + - AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.9 +system_design: + - ../../specs/system-page/system-design/storage-analysis-progress.md +--- + +# Task 04: Prove Progressive Storage Behavior + +## Summary + +Prove the integrated desktop and phone flows. Record bounded-scan timing without changing the live +storage data of the user. + +## In scope + +- Add desktop Playwright coverage for progressive data and the timing disclosure. +- Add mobile Playwright coverage for tap behavior, touch size, and containment. +- Make sure that cached, stale, failed, and manual Analyze flows remain correct. +- Record scanner benchmark results and a same-dataset live comparison when available. + +## Out of scope + +- Broad browser or backend verification. +- Creating large files in the live Kandev directory of the user. +- Performance claims without comparable measurements. + +## Acceptance + +- Desktop and phone flows receive useful data before the first scan finishes. +- Both viewports expose timing details without hover-only controls or horizontal overflow. +- The handoff records exact benchmark and available live timing evidence. + +## Verification + +```bash +make build-web +make build-backend +(cd apps/web && pnpm e2e:run --project chromium tests/system/storage-maintenance.spec.ts) +(cd apps/web && pnpm e2e:run --project mobile-chrome tests/system/mobile-storage-maintenance.spec.ts) +``` + +## Files likely touched + +- `apps/web/e2e/tests/system/storage-maintenance.spec.ts` +- `apps/web/e2e/tests/system/mobile-storage-maintenance.spec.ts` +- `apps/web/e2e/helpers/storage-maintenance.ts` +- `docs/plans/storage-analysis-progress/plan.md` +- `docs/plans/storage-analysis-progress/task-04-storage-progress-e2e.md` + +## Dependencies + +Tasks 01, 02, and 03 must be complete. + +## Risks + +- A fast test scan can finish before Playwright observes an intermediate state. +- Browser interception can prove UI behavior but cannot prove backend scan concurrency. +- Live storage timing can differ because of filesystem caches and background host activity. + +## Parallelism + +`sequential` + +## Inputs + +- All acceptance criteria in the requirement. +- Backend barrier tests from Tasks 01 and 02. +- Existing desktop and mobile Storage E2E flows. + +## Results + +Added progressive desktop and mobile storage fixtures and coverage for counted-so-far values, source +states, timing disclosure, touch sizing, and horizontal containment. Production builds passed. The +storage-maintenance E2E suite passed with 8 Chromium tests and the mobile suite passed with 6 tests. diff --git a/docs/public/operations.md b/docs/public/operations.md index fb556bb869..b8dff49481 100644 --- a/docs/public/operations.md +++ b/docs/public/operations.md @@ -172,8 +172,15 @@ only when the active task work can tolerate cleanup running alongside it. Storage analysis results are cached in the running backend for 15 minutes, so page reloads and policy saves reuse the displayed snapshot instead of scanning disk again. The page shows when that -snapshot was last analyzed. Select **Analyze** to force a fresh scan; restarting the backend also -clears the in-memory snapshot. +snapshot was last analyzed. The first read can return before the scan finishes. The card then shows +which sources are complete and labels the total as **Counted so far**. When an older snapshot +expires, Kandev keeps it visible while the replacement scan runs. A failed replacement also keeps +the last successful snapshot and shows the failure state. + +Select **Analyze** to force a fresh read-only scan. The timing information beside the completed +snapshot shows the scan duration, the 15-minute cache lifetime, and the next refresh time. A page +that remains open requests a new overview at that time. Restarting the backend clears the +in-memory snapshot, so the next Storage-page read starts a new scan. The page also shows the current percentage used on the filesystem containing Kandev's storage, along with used, available, and total capacity. This is host-volume capacity, not just the bytes diff --git a/docs/specs/system-page/README.md b/docs/specs/system-page/README.md index 779e26e61e..d04068e12f 100644 --- a/docs/specs/system-page/README.md +++ b/docs/specs/system-page/README.md @@ -46,6 +46,7 @@ feedback. - [Storage Maintenance System Design Part 1](system-design/storage-maintenance-01.md) - [Storage Maintenance System Design Part 2](system-design/storage-maintenance-02.md) - [Storage Maintenance System Design Part 3](system-design/storage-maintenance-03.md) +- [Progressive storage analysis](system-design/storage-analysis-progress.md) - [System pages System Design Part 1](system-design/system-page-01.md) - [System pages System Design Part 2](system-design/system-page-02.md) diff --git a/docs/specs/system-page/requirements/storage-overview-parallel-scan.md b/docs/specs/system-page/requirements/storage-overview-parallel-scan.md index 0ac9ab0487..22294167fc 100644 --- a/docs/specs/system-page/requirements/storage-overview-parallel-scan.md +++ b/docs/specs/system-page/requirements/storage-overview-parallel-scan.md @@ -2,6 +2,7 @@ status: active system: system-page created: 2026-08-08 +updated: 2026-09-05 owners: - kandev --- @@ -28,6 +29,37 @@ The Storage maintenance page currently waits for a cold overview scan before it - **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-001.7:** used, available, and total capacity in the existing GB formatting; and - **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-001.8:** the measured storage path or a localized explanation when the capacity read is unavailable. +### REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002: Progressive storage analysis + +**Intent:** Operators need useful storage information while Kandev scans large directory trees. +They also need clear freshness details for each completed snapshot. + +**User story:** As an operator, I want progressive storage results and scan timing, so that I can +understand long scans and the freshness of displayed values. + +#### Acceptance criteria + +- **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.1:** When no fresh snapshot exists, the + Storage page shall start or join one background scan without waiting for directory traversal. +- **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.2:** During the first scan, the analysis card + shall show each completed source while unfinished sources retain distinct progress states. +- **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.3:** During the first scan, the page shall + identify every aggregate as incomplete and shall never present scanned bytes as a final total. +- **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.4:** When a completed snapshot expires, the + page shall keep that snapshot visible while one background refresh replaces it atomically. +- **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.5:** While the page is open, live events shall + update scan progress. A polling fallback shall recover missed events within two seconds. +- **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.6:** A completed snapshot shall include scan + duration, cache lifetime, and the next refresh time in a localized information disclosure. +- **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.7:** The disclosure shall open by pointer + hover, keyboard focus, or activation. Its phone trigger shall provide a 44-pixel touch target. +- **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.8:** While the Storage page stays open, Kandev + shall request a refresh when the snapshot reaches its refresh time. **Analyze** shall refresh now. +- **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.9:** When a refresh fails, Kandev shall keep + the last successful snapshot and shall show the failed attempt without changing its measurement time. +- **AC-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002.10:** Concurrent requests and manual analysis + shall join one scan. Invalidated or older scans shall not overwrite newer progress or snapshots. + ## Migrated source detail This is a focused extension to [Storage maintenance](storage-maintenance.md). It improves cold diff --git a/docs/specs/system-page/system-design/storage-analysis-progress.md b/docs/specs/system-page/system-design/storage-analysis-progress.md new file mode 100644 index 0000000000..a5c09c9ed9 --- /dev/null +++ b/docs/specs/system-page/system-design/storage-analysis-progress.md @@ -0,0 +1,279 @@ +--- +status: draft +system: system-page +requirements: + - REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002 +--- + +# Progressive Storage Analysis System Design + +## Purpose and boundaries + +The system-page system owns storage analysis, its cache, and the operator-visible progress contract. +The platform event bus transports notifications but does not own storage state. + +This design keeps cleanup behavior unchanged. It changes only read-only analysis, cache reads, +progress delivery, and the Storage page presentation. + +## Requirement mapping + +| Requirement | Design section | +| --- | --- | +| `REQ-SYSTEM-PAGE-STORAGE-OVERVIEW-PARALLEL-SCAN-002` | [Analysis state](#analysis-state), [Filesystem scan](#filesystem-scan), [Cache flow](#cache-flow), [Progress delivery](#progress-delivery), [Storage page](#storage-page), [Failure and recovery](#failure-and-recovery) | + +## Current behavior + +`storageOverview.Summary` already starts workspace, Go-cache, quarantine, Docker, and temporary-artifact analysis concurrently. +The slow path is now inside the filesystem providers. + +`workspaces.Provider.Analyze` measures discovered task roots one after another. The Go-cache and +temporary-artifact providers also use serial `filepath.WalkDir` calls. + +`OverviewCache.Get` waits for the full scan when the cache is empty or expired. The frontend cannot +receive partial values because `GET /api/v1/system/storage` waits for `Get` to finish. + +## Components and responsibilities + +### Bounded filesystem scanner + +Add `internal/system/storage/filescan` for read-only byte measurement. It will preserve the symlink +and exclusion policy of each provider. + +One shared limiter permits at most four active directory partitions for one storage analysis. +The limit includes workspace, Go-cache, and temporary-artifact walks. + +The scanner partitions each requested root by its immediate children. Each partition uses a serial +`filepath.WalkDir`, so no two workers count the same entry. + +The scanner will provide these functions: + +- measure one or more roots with indexed results. +- reject or skip symlinks according to the policy of the caller. +- exclude provider-owned marker files. +- stop between filesystem operations when the context is canceled. +- report completed partitions, measured bytes, and completed roots. + +The scanner will aggregate results by input index. Worker completion order will not change warning +order or the final response. + +The concurrency limit is an internal constant. This change will not add an operator setting or an +environment variable. + +### Progressive overview provider + +Extend the overview provider with a progress callback. `storageOverview` will report source start, +source progress, source completion, and source failure. + +The source identities are `workspaces`, `go_cache`, `quarantine`, `temporary_artifacts`, and +`docker`. Disabled sources remain terminal and do not keep the scan active. + +The workspace source will forward completed-root and byte progress from `filescan`. Other sources +will report the finest stable progress that their provider can supply. + +### Overview cache + +`OverviewCache` remains the authority for single-flight refresh and process-local snapshots. It will +also own the active scan state and its generation. + +The cache will add a nonblocking read method for the HTTP handler. This method returns the current +snapshot and scan state, then starts one background refresh when the snapshot is absent or expired. + +`Refresh` will remain the manual Analyze path. It will bypass a fresh cache entry but join an active +scan instead of starting duplicate filesystem work. + +`Invalidate` will advance the generation and clear the completed snapshot. A late callback from an +older generation will not change progress or cache state. + +### Progress publisher + +The cache will accept a narrow publisher callback. Backend wiring will publish +`system.storage.analysis.updated` after meaningful state changes. + +The event payload will contain only the scan generation and state. It will not contain paths, byte +counts, warnings, or errors. + +The WebSocket gateway will map the event to the same action name. Authorized clients will read the +full state from the admin storage endpoint. + +## Analysis state + +The storage response will keep its settings and capabilities fields. It will make `summary` and +`analyzed_at` nullable for the first scan and add an `analysis` object. + +```text +StorageAnalysisState + generation: unsigned integer + state: scanning | ready | failed + started_at: timestamp or null + completed_at: timestamp or null + duration_ms: integer or null + cache_ttl_seconds: integer + refresh_due_at: timestamp or null + stale: boolean + error: string or null + progress: + completed_sources: integer + total_sources: integer + sources: map of StorageSourceProgress + partial_summary: partial Summary or null +``` + +`StorageSourceProgress` contains a source state, completed items, total items, and bytes scanned. +Item counts are optional when a provider cannot determine a stable total. + +`summary` always contains the last complete successful snapshot. The backend never mixes values +from different scans into this field. + +`partial_summary` contains only results from the current first scan. The frontend must identify its +aggregate as counted so far. + +`refresh_due_at` equals `analyzed_at` plus the 15-minute cache lifetime. It is a demand time, not a +daemon schedule. + +## Filesystem scan + +`backendapp` will construct one `filescan.Limiter` for each overview provider. It will inject that +limiter into workspace, Go-cache, and temporary-artifact analysis. + +Each provider will keep its current ownership and path rules. The shared scanner measures bytes but +does not classify ownership or choose cleanup candidates. + +Workspace analysis will discover and protect roots before it starts measurement. Then it will send +the non-overlapping roots to the bounded scanner. + +Go-cache analysis will preserve its current marker exclusion. It will reject or skip symlinks with +the same policy as the current provider. + +Temporary-artifact analysis will continue to measure only registered roots. It will not scan the +shared operating-system temporary directory. + +Cleanup providers will remain unchanged. Destructive work will not use the concurrent read-only +scanner. + +## Cache flow + +### Fresh snapshot + +The nonblocking read returns the snapshot with `state=ready`. It does not start filesystem work. + +### First scan + +The nonblocking read creates a scan generation and starts a background refresh. It returns +`state=scanning` without waiting for any directory partition. + +Progress callbacks update `partial_summary`. When all sources finish, the cache commits one atomic +snapshot and records completion time, duration, and refresh time. + +### Expired snapshot + +The nonblocking read returns the expired snapshot with `stale=true` and starts one background +refresh. The old summary stays visible until the replacement snapshot is complete. + +The frontend will request a read when `refresh_due_at` arrives while the page is mounted. Thus, the +displayed next-refresh time is accurate for an open Storage page. + +### Manual Analyze + +Manual Analyze starts a forced refresh through the current tracked operation. A concurrent cache +refresh joins the same flight. + +The Analyze button will keep its current job state. Scan progress will come from the analysis state, +not from a second job record. + +## Progress delivery + +The cache will publish these transitions: + +1. A scan starts. +2. A source starts or reports bounded progress. +3. A source finishes or fails. +4. The full scan finishes or fails. + +Byte progress will be throttled to at most four updates per second. Source terminal transitions will +publish immediately. + +The web store will keep an `analysisRevision`. The WebSocket handler will advance that revision for +each notification. + +`useStorageMaintenance` will reload only the overview after a revision change. While a scan is +active, it will also poll the endpoint every 1.5 seconds. + +The polling fallback stops after a ready or failed response. Existing request generations will +prevent an older response from replacing a newer analysis state. + +## Storage page + +The analysis card will use the complete snapshot when one exists. During the first scan, it will use +the partial summary and source progress. + +Completed sources will show their measured values. Pending sources will show localized progress or +an indeterminate state. + +The total label will say that the value is counted so far until the first scan finishes. It will +retain the existing partial-data badge when a completed source is unavailable. + +An information icon will appear beside the completed snapshot time. Its disclosure will show: + +- the scan duration. +- the 15-minute cache lifetime. +- the next refresh time in absolute and relative form. + +The disclosure will explain that Analyze refreshes immediately. It will not claim that the backend +scans while no Storage page or client is active. + +The existing `StorageSettingHelp` interaction is the nearest mobile example. The new icon will open +on hover and keyboard focus, and pointer activation will pin it. + +On a phone, the same button will use the current 44-pixel hit area. A second tap, outside interaction, +or Escape will close the disclosure. + +The page will keep one document scroll owner. This change adds no drawer, fixed control, or horizontal +scrolling region. + +## Failure and recovery + +A provider error will keep the current source-specific unavailable value. Other source results will +continue to update and complete. + +A top-level scan error will set `state=failed`. If a successful snapshot exists, that snapshot will +remain visible and keep its original `analyzed_at` value. + +A failed first scan will keep completed partial sources visible. The card will show a retry action +through Analyze and will identify the failed attempt. + +If the request context closes, the background first scan will continue with a service-owned context. +Manual Analyze will keep the current tracked-job cancellation behavior. + +Invalidation will discard late progress and completion from the old generation. WebSocket delivery +loss will not block recovery because the client polls while a scan is active. + +## Persistence + +The cache and progress state remain process-local. A backend restart starts a new cold scan. + +No database migration or snapshot file is part of this change. Storage runs will keep their current +durable history. + +## Security + +The storage endpoint remains in the admin route group. The progress event carries no storage data, +so it does not expose paths or byte counts through the broadcast bus. + +The scanner will not follow symlinks. It will preserve existing containment checks and ownership +classification before it reads a workspace root. + +## Observability + +The backend will log one structured completion record for each scan. The record will contain total +duration, source durations, source outcomes, partition count, and maximum active walkers. + +Add counters for scans started, joined, completed, and failed. Add histograms for full duration and +source duration. + +Logs and metrics will not include task paths. Live performance validation will compare serial and +bounded scans on the same dataset when that environment is available. + +## Related decisions + +- [Bounded progressive storage analysis](../../../decisions/2026-09-05-bounded-progressive-storage-analysis.md) +- [Install-wide storage maintenance](../../../decisions/0045-install-wide-storage-maintenance.md)