From df6c243b21634e89af648190dc2512c80a2bb298 Mon Sep 17 00:00:00 2001 From: ila Date: Sun, 19 Jul 2026 20:28:56 +0800 Subject: [PATCH] Preserve staging I/O failure causes (T-615) --- core/application/install/service.go | 67 ++++--- core/application/install/service_test.go | 83 +++++++- core/installer/durability.go | 4 +- core/installer/extractor.go | 114 ++++++++--- core/installer/extractor_io_test.go | 238 +++++++++++++++++++++++ core/installer/extractor_test.go | 3 + core/installer/recovery.go | 6 + core/installer/staging_output.go | 72 +++++++ docs/00-ai-start-here.md | 4 +- docs/04-architecture.md | 2 +- docs/06-tasks.md | 2 +- docs/api.md | 9 +- docs/current-state.md | 14 +- docs/tasks/T-615.md | 9 +- 14 files changed, 551 insertions(+), 76 deletions(-) create mode 100644 core/installer/extractor_io_test.go create mode 100644 core/installer/staging_output.go diff --git a/core/application/install/service.go b/core/application/install/service.go index 3873296..eddf633 100644 --- a/core/application/install/service.go +++ b/core/application/install/service.go @@ -83,6 +83,12 @@ type DiskSpaceChecker interface { AvailableBytes(appRoot string) (int64, error) } +// StorageFailureClassifier lets the platform identify a preserved staging I/O +// failure as insufficient storage without importing platform APIs into core. +type StorageFailureClassifier interface { + IsDiskFull(err error) bool +} + // TargetStateChecker reports whether the verified current entrypoint is still // running. It never starts, waits for, or terminates a process. type TargetStateChecker interface { @@ -106,24 +112,26 @@ type InstallResult struct { } // InstallServiceConfig makes all external installation dependencies explicit. -// Disk and target-state checks are mandatory so no caller can silently bypass -// the pre-extract safety boundary. +// Disk, storage-failure and target-state checks are mandatory so no caller can +// silently bypass the pre-extract safety boundary or disk-full diagnosis. type InstallServiceConfig struct { - Extractor installer.Extractor - Records InstallRecordStore - Health installer.HealthCheck - DiskSpace DiskSpaceChecker - TargetState TargetStateChecker + Extractor installer.Extractor + Records InstallRecordStore + Health installer.HealthCheck + DiskSpace DiskSpaceChecker + StorageFailures StorageFailureClassifier + TargetState TargetStateChecker } // InstallService implements the core-only verified package installation use // case. The caller must supply entries produced by catalog.Client. type InstallService struct { - extractor installer.Extractor - records InstallRecordStore - health installer.HealthCheck - diskSpace DiskSpaceChecker - targetState TargetStateChecker + extractor installer.Extractor + records InstallRecordStore + health installer.HealthCheck + diskSpace DiskSpaceChecker + storageFailures StorageFailureClassifier + targetState TargetStateChecker } func NewInstallService(config InstallServiceConfig) (*InstallService, error) { @@ -136,15 +144,19 @@ func NewInstallService(config InstallServiceConfig) (*InstallService, error) { if config.DiskSpace == nil { return nil, fmt.Errorf("%w: disk space checker is required", ErrInstallServiceConfig) } + if config.StorageFailures == nil { + return nil, fmt.Errorf("%w: storage failure classifier is required", ErrInstallServiceConfig) + } if config.TargetState == nil { return nil, fmt.Errorf("%w: target state checker is required", ErrInstallServiceConfig) } return &InstallService{ - extractor: config.Extractor, - records: config.Records, - health: config.Health, - diskSpace: config.DiskSpace, - targetState: config.TargetState, + extractor: config.Extractor, + records: config.Records, + health: config.Health, + diskSpace: config.DiskSpace, + storageFailures: config.StorageFailures, + targetState: config.TargetState, }, nil } @@ -154,16 +166,16 @@ func NewInstallService(config InstallServiceConfig) (*InstallService, error) { func (service *InstallService) Install(request InstallRequest) (InstallResult, error) { expectation, record, err := resolveInstallRequest(request) if err != nil { - return InstallResult{}, installError(InstallStageVerify, err) + return InstallResult{}, service.installError(InstallStageVerify, err) } appRoot, err := service.records.EnsureAppRoot(record.ID) if err != nil { - return InstallResult{}, installError(InstallStageRecover, err) + return InstallResult{}, service.installError(InstallStageRecover, err) } recovery, err := installer.Recover(appRoot) if err != nil { - return InstallResult{}, installError(InstallStageRecover, err) + return InstallResult{}, service.installError(InstallStageRecover, err) } extracted, err := service.extractor.ExtractVerifiedFileWithCheck( @@ -173,7 +185,7 @@ func (service *InstallService) Install(request InstallRequest) (InstallResult, e service.preExtractCheck(appRoot, record.ID), ) if err != nil { - return InstallResult{}, installError(stageForPackageError(err), err) + return InstallResult{}, service.installError(stageForPackageError(err), err) } record.Files = make([]storage.InstalledFile, 0, len(extracted.PayloadFiles)) for _, file := range extracted.PayloadFiles { @@ -196,7 +208,7 @@ func (service *InstallService) Install(request InstallRequest) (InstallResult, e return nil }) if err := switcher.Switch(appRoot); err != nil { - return InstallResult{}, installError(stageForSwitchError(err, recordWriteErr), err) + return InstallResult{}, service.installError(stageForSwitchError(err, recordWriteErr), err) } return InstallResult{ AppID: record.ID, @@ -298,8 +310,15 @@ func resolveInstallRequest(request InstallRequest) (installer.PackageExpectation }, nil } -func installError(stage InstallStage, err error) error { - return &InstallError{Stage: stage, Code: failureCodeFor(err), Err: err} +func (service *InstallService) installError(stage InstallStage, err error) error { + return &InstallError{Stage: stage, Code: service.failureCodeFor(err), Err: err} +} + +func (service *InstallService) failureCodeFor(err error) FailureCode { + if errors.Is(err, installer.ErrStagingOutput) && service.storageFailures.IsDiskFull(err) { + return FailureCodeDiskFull + } + return failureCodeFor(err) } func stageForPackageError(err error) InstallStage { diff --git a/core/application/install/service_test.go b/core/application/install/service_test.go index 7f5040d..6dc0f14 100644 --- a/core/application/install/service_test.go +++ b/core/application/install/service_test.go @@ -5,6 +5,7 @@ import ( "crypto/sha256" "encoding/hex" "errors" + "fmt" "os" "path/filepath" "testing" @@ -196,6 +197,9 @@ func TestNewInstallServiceRequiresPreflightCheckers(t *testing.T) { DiskSpace: diskSpaceCheckerFunc(func(string) (int64, error) { return StagingDiskReserveBytes, nil }), + StorageFailures: storageFailureClassifierFunc(func(error) bool { + return false + }), TargetState: targetStateCheckerFunc(func(string, string) (bool, error) { return false, nil }), @@ -217,6 +221,12 @@ func TestNewInstallServiceRequiresPreflightCheckers(t *testing.T) { config.TargetState = nil }, }, + { + name: "storage failure classifier", + modify: func(config *InstallServiceConfig) { + config.StorageFailures = nil + }, + }, } for _, test := range tests { @@ -248,6 +258,62 @@ func TestFailureCodeForPackageFailures(t *testing.T) { } } +func TestInstallServiceClassifiesStagingOutputFailures(t *testing.T) { + errDiskFull := errors.New("injected disk full") + errOutput := errors.New("injected output failure") + service := &InstallService{ + storageFailures: storageFailureClassifierFunc(func(err error) bool { + return errors.Is(err, errDiskFull) + }), + } + + for _, test := range []struct { + name string + err error + code FailureCode + }{ + { + name: "write disk full", + err: fmt.Errorf("%w: write staging file: %w", installer.ErrStagingOutput, errDiskFull), + code: FailureCodeDiskFull, + }, + { + name: "sync disk full", + err: fmt.Errorf("%w: sync staging file: %w", installer.ErrStagingOutput, errDiskFull), + code: FailureCodeDiskFull, + }, + { + name: "close disk full", + err: fmt.Errorf("%w: close staging file: %w", installer.ErrStagingOutput, errDiskFull), + code: FailureCodeDiskFull, + }, + { + name: "generic output I O", + err: fmt.Errorf("%w: write staging file: %w", installer.ErrStagingOutput, errOutput), + code: FailureCodeInstallFailed, + }, + { + name: "ZIP input remains corrupt", + err: fmt.Errorf("%w: %w", installer.ErrArchiveCorrupt, errDiskFull), + code: FailureCodeZIPCorrupt, + }, + } { + t.Run(test.name, func(t *testing.T) { + wrapped := service.installError(InstallStageExtract, test.err) + var installErr *InstallError + if !errors.As(wrapped, &installErr) { + t.Fatalf("install error = %v, want InstallError", wrapped) + } + if installErr.Code != test.code { + t.Fatalf("code = %q, want %q", installErr.Code, test.code) + } + if !errors.Is(wrapped, test.err) { + t.Fatalf("install error = %v, want preserved cause", wrapped) + } + }) + } +} + func TestInstallServiceAcceptsExactStagingCapacity(t *testing.T) { archivePath, publishedPackage := writeInstallPackage(t, "1.2.3", "new executable") appsRoot := filepath.Join(t.TempDir(), "apps") @@ -555,10 +621,13 @@ func newInstallServiceWithCheckers( t.Fatalf("NewExtractor() error = %v", err) } service, err := NewInstallService(InstallServiceConfig{ - Extractor: extractor, - Records: store, - Health: health, - DiskSpace: diskSpace, + Extractor: extractor, + Records: store, + Health: health, + DiskSpace: diskSpace, + StorageFailures: storageFailureClassifierFunc(func(error) bool { + return false + }), TargetState: targetState, }) if err != nil { @@ -573,6 +642,12 @@ func (check diskSpaceCheckerFunc) AvailableBytes(appRoot string) (int64, error) return check(appRoot) } +type storageFailureClassifierFunc func(error) bool + +func (classifier storageFailureClassifierFunc) IsDiskFull(err error) bool { + return classifier(err) +} + type targetStateCheckerFunc func(string, string) (bool, error) func (check targetStateCheckerFunc) IsRunning(appID string, entrypointPath string) (bool, error) { diff --git a/core/installer/durability.go b/core/installer/durability.go index 06c311c..f0ed625 100644 --- a/core/installer/durability.go +++ b/core/installer/durability.go @@ -39,14 +39,14 @@ func effectiveDurability(fence durabilityFence) durabilityFence { func syncFileWithFence(fence durabilityFence, file *os.File, description string) error { if err := effectiveDurability(fence).syncFile(file); err != nil { - return fmt.Errorf("%w: sync %s: %v", ErrDurability, description, err) + return fmt.Errorf("%w: sync %s: %w", ErrDurability, description, err) } return nil } func syncDirectoryWithFence(fence durabilityFence, path, description string) error { if err := effectiveDurability(fence).syncDirectory(path); err != nil { - return fmt.Errorf("%w: sync %s: %v", ErrDurability, description, err) + return fmt.Errorf("%w: sync %s: %w", ErrDurability, description, err) } return nil } diff --git a/core/installer/extractor.go b/core/installer/extractor.go index 516503e..fb39852 100644 --- a/core/installer/extractor.go +++ b/core/installer/extractor.go @@ -33,12 +33,15 @@ var ( ErrAppManifestMissing = errors.New("package app.json is missing") ErrDestinationExists = errors.New("staging destination already exists") ErrArchiveCorrupt = errors.New("ZIP archive data is corrupt") + ErrStagingOutput = errors.New("staging output failed") + ErrStagingCleanup = errors.New("staging cleanup failed") ) // Extractor writes only payload/ contents from a pre-verified package ZIP. type Extractor struct { limits Limits durability durabilityFence + files stagingFileOperations } type ExtractResult struct { @@ -87,7 +90,11 @@ func NewExtractor(limits Limits) (Extractor, error) { if err := limits.validate(); err != nil { return Extractor{}, err } - return Extractor{limits: limits, durability: defaultDurability()}, nil + return Extractor{ + limits: limits, + durability: defaultDurability(), + files: defaultStagingFileOperations(), + }, nil } // ExtractFile requires expectedPackageSize from the verified Catalog package. @@ -136,6 +143,7 @@ func (extractor Extractor) extractPlan( plan []plannedEntry, ) (result ExtractResult, err error) { fence := effectiveDurability(extractor.durability) + files := effectiveStagingFileOperations(extractor.files) destinationRoot, entrypointPath, err := planOutputPaths( destination, entrypoint, @@ -145,19 +153,21 @@ func (extractor Extractor) extractPlan( return ExtractResult{}, err } - if err := os.MkdirAll(filepath.Dir(destinationRoot), 0o700); err != nil { - return ExtractResult{}, fmt.Errorf("create staging parent: %w", err) + if err := files.mkdirAll(filepath.Dir(destinationRoot), 0o700); err != nil { + return ExtractResult{}, stagingOutputError("create staging parent", err) } - if err := os.Mkdir(destinationRoot, 0o700); err != nil { + if err := files.mkdir(destinationRoot, 0o700); err != nil { if os.IsExist(err) { return ExtractResult{}, ErrDestinationExists } - return ExtractResult{}, fmt.Errorf("create staging destination: %w", err) + return ExtractResult{}, stagingOutputError("create staging destination", err) } complete := false defer func() { if !complete { - _ = os.RemoveAll(destinationRoot) + if cleanupErr := files.removeAll(destinationRoot); cleanupErr != nil { + err = errors.Join(err, stagingCleanupError(cleanupErr)) + } } }() @@ -167,31 +177,37 @@ func (extractor Extractor) extractPlan( if entry.outputPath == "" { continue } - if err := os.MkdirAll(entry.targetPath, 0o700); err != nil { - return ExtractResult{}, fmt.Errorf("create staging directory: %w", err) + if err := files.mkdirAll(entry.targetPath, 0o700); err != nil { + return ExtractResult{}, stagingOutputError("create staging directory", err) } continue } - if err := os.MkdirAll(filepath.Dir(entry.targetPath), 0o700); err != nil { - return ExtractResult{}, fmt.Errorf("create staging file parent: %w", err) + if err := files.mkdirAll(filepath.Dir(entry.targetPath), 0o700); err != nil { + return ExtractResult{}, stagingOutputError("create staging file parent", err) } source, err := entry.file.Open() if err != nil { - return ExtractResult{}, fmt.Errorf("%w: open %s: %v", ErrArchiveCorrupt, entry.archivePath, err) + return ExtractResult{}, archiveInputError("open", entry.archivePath, err) } mode := os.FileMode(0o600) if entry.file.Mode().Perm()&0o111 != 0 { mode = 0o700 } - output, err := os.OpenFile( + output, err := files.openFile( entry.targetPath, os.O_CREATE|os.O_EXCL|os.O_WRONLY, mode, ) if err != nil { - source.Close() - return ExtractResult{}, fmt.Errorf("create staging file: %w", err) + outputErr := stagingOutputError("create staging file", err) + if closeErr := source.Close(); closeErr != nil { + return ExtractResult{}, errors.Join( + outputErr, + archiveInputError("close", entry.archivePath, closeErr), + ) + } + return ExtractResult{}, outputErr } remaining := extractor.limits.MaxUncompressedBytes - written @@ -200,39 +216,45 @@ func (extractor Extractor) extractPlan( readLimit++ } digest := sha256.New() + writer := stagingWriter{writer: output} copied, copyErr := io.Copy( - io.MultiWriter(output, digest), + io.MultiWriter(&writer, digest), io.LimitReader(source, readLimit), ) closeSourceErr := source.Close() if copyErr != nil { - _ = output.Close() - return ExtractResult{}, fmt.Errorf("%w: read %s: %v", ErrArchiveCorrupt, entry.archivePath, copyErr) + primary := archiveInputError("read", entry.archivePath, copyErr) + if writer.err != nil { + primary = stagingOutputError("write staging file", writer.err) + } + return ExtractResult{}, joinStagingCloseError(primary, output) } if closeSourceErr != nil { - _ = output.Close() - return ExtractResult{}, fmt.Errorf("%w: close %s: %v", ErrArchiveCorrupt, entry.archivePath, closeSourceErr) + return ExtractResult{}, joinStagingCloseError( + archiveInputError("close", entry.archivePath, closeSourceErr), + output, + ) } if copied > remaining { - _ = output.Close() - return ExtractResult{}, ErrExpandedTooLarge + return ExtractResult{}, joinStagingCloseError(ErrExpandedTooLarge, output) } if uint64(copied) != entry.file.UncompressedSize64 { - _ = output.Close() - return ExtractResult{}, fmt.Errorf( + return ExtractResult{}, joinStagingCloseError(fmt.Errorf( "%w: %s expanded to %d bytes, header declares %d", ErrArchiveCorrupt, entry.archivePath, copied, entry.file.UncompressedSize64, + ), output) + } + if err := syncFileWithFence(fence, output.osFile(), "staging payload"); err != nil { + return ExtractResult{}, joinStagingCloseError( + stagingOutputError("sync staging file", err), + output, ) } - if err := syncFileWithFence(fence, output, "staging payload"); err != nil { - _ = output.Close() - return ExtractResult{}, err - } if err := output.Close(); err != nil { - return ExtractResult{}, fmt.Errorf("close staging file: %w", err) + return ExtractResult{}, stagingOutputError("close staging file", err) } written += copied result.Files++ @@ -243,7 +265,7 @@ func (extractor Extractor) extractPlan( }) } if err := syncStagingTree(fence, destinationRoot); err != nil { - return ExtractResult{}, err + return ExtractResult{}, stagingOutputError("sync staging tree", err) } result.Bytes = written @@ -252,6 +274,40 @@ func (extractor Extractor) extractPlan( return result, nil } +type stagingWriter struct { + writer io.Writer + err error +} + +func (writer *stagingWriter) Write(data []byte) (int, error) { + written, err := writer.writer.Write(data) + if err != nil { + writer.err = err + } else if written != len(data) { + writer.err = io.ErrShortWrite + } + return written, err +} + +func archiveInputError(operation, path string, cause error) error { + return fmt.Errorf("%w: %s %s: %w", ErrArchiveCorrupt, operation, path, cause) +} + +func stagingOutputError(operation string, cause error) error { + return fmt.Errorf("%w: %s: %w", ErrStagingOutput, operation, cause) +} + +func stagingCleanupError(cause error) error { + return fmt.Errorf("%w: remove staging: %w", ErrStagingCleanup, cause) +} + +func joinStagingCloseError(primary error, output stagingOutputFile) error { + if closeErr := output.Close(); closeErr != nil { + return errors.Join(primary, stagingOutputError("close staging file", closeErr)) + } + return primary +} + func planOutputPaths( destination string, entrypoint string, diff --git a/core/installer/extractor_io_test.go b/core/installer/extractor_io_test.go new file mode 100644 index 0000000..9eced0c --- /dev/null +++ b/core/installer/extractor_io_test.go @@ -0,0 +1,238 @@ +package installer + +import ( + "archive/zip" + "errors" + "os" + "path/filepath" + "testing" +) + +func TestExtractorKeepsStagingOutputFailuresDistinctFromZIPInput(t *testing.T) { + archivePath := writeTestZIP(t, []testZIPEntry{ + {name: "app.json", body: []byte(`{}`)}, + {name: "payload/App.exe", body: []byte("executable")}, + }) + errDiskFull := errors.New("injected disk full") + errOutput := errors.New("injected output failure") + + tests := []struct { + name string + failure error + configure func(*Extractor, error) + }{ + { + name: "write disk full", + failure: errDiskFull, + configure: func(extractor *Extractor, failure error) { + extractor.files = outputFailureOperations{ + stagingFileOperations: defaultStagingFileOperations(), + writeErr: failure, + } + }, + }, + { + name: "sync disk full", + failure: errDiskFull, + configure: func(extractor *Extractor, failure error) { + extractor.durability = fileSyncFailureFence{err: failure} + }, + }, + { + name: "close disk full", + failure: errDiskFull, + configure: func(extractor *Extractor, failure error) { + extractor.files = outputFailureOperations{ + stagingFileOperations: defaultStagingFileOperations(), + closeErr: failure, + } + }, + }, + { + name: "generic output I O", + failure: errOutput, + configure: func(extractor *Extractor, failure error) { + extractor.files = outputFailureOperations{ + stagingFileOperations: defaultStagingFileOperations(), + writeErr: failure, + } + }, + }, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + extractor := mustExtractor(t, testLimits()) + test.configure(&extractor, test.failure) + destination := filepath.Join(t.TempDir(), "staging") + + _, err := extractor.ExtractFile( + archivePath, + destination, + "App.exe", + archiveSize(t, archivePath), + ) + if !errors.Is(err, ErrStagingOutput) { + t.Fatalf("ExtractFile() error = %v, want %v", err, ErrStagingOutput) + } + if errors.Is(err, ErrArchiveCorrupt) { + t.Fatalf("ExtractFile() error = %v, must not be ZIP corruption", err) + } + if !errors.Is(err, test.failure) { + t.Fatalf("ExtractFile() error = %v, want preserved %v", err, test.failure) + } + if _, statErr := os.Stat(destination); !os.IsNotExist(statErr) { + t.Fatalf("output failure left staging, stat error = %v", statErr) + } + }) + } +} + +func TestExtractorReportsCleanupFailureAndRecoveryRemovesOnlyManagedStaging(t *testing.T) { + archivePath := writeTestZIP(t, []testZIPEntry{ + {name: "app.json", body: []byte(`{}`)}, + {name: "payload/App.exe", body: []byte("verified bytes"), method: zip.Store}, + }) + corruptZIPEntryData(t, archivePath, "payload/App.exe") + + root := t.TempDir() + currentPath := filepath.Join(root, "current", "App.exe") + if err := os.MkdirAll(filepath.Dir(currentPath), 0o700); err != nil { + t.Fatalf("create current: %v", err) + } + if err := os.WriteFile(currentPath, []byte("old executable"), 0o600); err != nil { + t.Fatalf("write current: %v", err) + } + recordPath := filepath.Join(root, "installed-app.json") + oldRecord := []byte(`{"version":"1.0.0"}`) + if err := os.WriteFile(recordPath, oldRecord, 0o600); err != nil { + t.Fatalf("write record: %v", err) + } + for _, preserved := range []string{"data", "licenses"} { + path := filepath.Join(root, preserved, "keep.txt") + if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil { + t.Fatalf("create %s: %v", preserved, err) + } + if err := os.WriteFile(path, []byte(preserved), 0o600); err != nil { + t.Fatalf("write %s: %v", preserved, err) + } + } + + errCleanup := errors.New("injected cleanup failure") + extractor := mustExtractor(t, testLimits()) + extractor.files = outputFailureOperations{ + stagingFileOperations: defaultStagingFileOperations(), + cleanupErr: errCleanup, + } + destination := filepath.Join(root, "staging") + _, err := extractor.ExtractFile( + archivePath, + destination, + "App.exe", + archiveSize(t, archivePath), + ) + if !errors.Is(err, ErrArchiveCorrupt) || !errors.Is(err, ErrStagingCleanup) || !errors.Is(err, errCleanup) { + t.Fatalf("ExtractFile() error = %v, want ZIP and cleanup causes", err) + } + if _, statErr := os.Stat(destination); statErr != nil { + t.Fatalf("cleanup failure removed staging, stat error = %v", statErr) + } + + result, err := Recover(root) + if err != nil { + t.Fatalf("Recover() error = %v", err) + } + if result.Action != RecoveryAborted { + t.Fatalf("recovery action = %q, want %q", result.Action, RecoveryAborted) + } + if got := mustReadTestFile(t, currentPath); got != "old executable" { + t.Fatalf("current after recovery = %q", got) + } + if record, readErr := os.ReadFile(recordPath); readErr != nil || string(record) != string(oldRecord) { + t.Fatalf("record after recovery = %q error = %v", record, readErr) + } + for _, preserved := range []string{"data", "licenses"} { + if got := mustReadTestFile(t, filepath.Join(root, preserved, "keep.txt")); got != preserved { + t.Fatalf("%s after recovery = %q", preserved, got) + } + } + if _, statErr := os.Stat(destination); !os.IsNotExist(statErr) { + t.Fatalf("Recover() left staging, stat error = %v", statErr) + } +} + +type outputFailureOperations struct { + stagingFileOperations + writeErr error + closeErr error + cleanupErr error +} + +func (operations outputFailureOperations) openFile( + name string, + flag int, + perm os.FileMode, +) (stagingOutputFile, error) { + file, err := operations.stagingFileOperations.openFile(name, flag, perm) + if err != nil { + return nil, err + } + return &outputFailureFile{ + stagingOutputFile: file, + writeErr: operations.writeErr, + closeErr: operations.closeErr, + }, nil +} + +func (operations outputFailureOperations) removeAll(path string) error { + if operations.cleanupErr != nil { + return operations.cleanupErr + } + return operations.stagingFileOperations.removeAll(path) +} + +type outputFailureFile struct { + stagingOutputFile + writeErr error + closeErr error +} + +func (file *outputFailureFile) Write(data []byte) (int, error) { + if file.writeErr != nil { + return 0, file.writeErr + } + return file.stagingOutputFile.Write(data) +} + +func (file *outputFailureFile) Close() error { + closeErr := file.stagingOutputFile.Close() + if file.closeErr != nil { + return file.closeErr + } + return closeErr +} + +func (file *outputFailureFile) osFile() *os.File { + return file.stagingOutputFile.osFile() +} + +type fileSyncFailureFence struct { + err error +} + +func (fence fileSyncFailureFence) syncFile(*os.File) error { + return fence.err +} + +func (fence fileSyncFailureFence) syncDirectory(string) error { + return nil +} + +func mustReadTestFile(t *testing.T, path string) string { + t.Helper() + data, err := os.ReadFile(path) + if err != nil { + t.Fatalf("read %s: %v", path, err) + } + return string(data) +} diff --git a/core/installer/extractor_test.go b/core/installer/extractor_test.go index 8209dce..3ef78ae 100644 --- a/core/installer/extractor_test.go +++ b/core/installer/extractor_test.go @@ -401,6 +401,9 @@ func TestExtractorRemovesDestinationAfterCopyFailure(t *testing.T) { if !errors.Is(err, ErrArchiveCorrupt) { t.Fatalf("ExtractFile() error = %v, want %v", err, ErrArchiveCorrupt) } + if errors.Is(err, ErrStagingOutput) { + t.Fatalf("ExtractFile() error = %v, must not be a staging output failure", err) + } if _, statErr := os.Stat(destination); !os.IsNotExist(statErr) { t.Fatalf("copy failure left staging, stat error = %v", statErr) } diff --git a/core/installer/recovery.go b/core/installer/recovery.go index 7bfcd58..79a2fb5 100644 --- a/core/installer/recovery.go +++ b/core/installer/recovery.go @@ -47,6 +47,12 @@ func recoverWithFence(root string, fence durabilityFence) (RecoveryResult, error ErrRecoveryInconsistent, ) } + if state.staging { + if err := removeManagedDirectoryWithFence(layout, layout.staging, fence); err != nil { + return RecoveryResult{}, err + } + return RecoveryResult{Action: RecoveryAborted}, nil + } return RecoveryResult{Action: RecoveryNone}, nil } diff --git a/core/installer/staging_output.go b/core/installer/staging_output.go new file mode 100644 index 0000000..ac97066 --- /dev/null +++ b/core/installer/staging_output.go @@ -0,0 +1,72 @@ +package installer + +import "os" + +// stagingOutputFile is the narrow output seam used by extraction. Keeping it +// internal lets tests inject write and close failures without exposing a file +// abstraction to package consumers. +type stagingOutputFile interface { + Write([]byte) (int, error) + Close() error + osFile() *os.File +} + +type stagingFileOperations interface { + mkdirAll(path string, perm os.FileMode) error + mkdir(path string, perm os.FileMode) error + openFile(name string, flag int, perm os.FileMode) (stagingOutputFile, error) + removeAll(path string) error +} + +type filesystemStagingFileOperations struct{} + +type filesystemStagingOutputFile struct { + file *os.File +} + +func (operations filesystemStagingFileOperations) mkdirAll(path string, perm os.FileMode) error { + return os.MkdirAll(path, perm) +} + +func (operations filesystemStagingFileOperations) mkdir(path string, perm os.FileMode) error { + return os.Mkdir(path, perm) +} + +func (operations filesystemStagingFileOperations) openFile( + name string, + flag int, + perm os.FileMode, +) (stagingOutputFile, error) { + file, err := os.OpenFile(name, flag, perm) + if err != nil { + return nil, err + } + return filesystemStagingOutputFile{file: file}, nil +} + +func (operations filesystemStagingFileOperations) removeAll(path string) error { + return os.RemoveAll(path) +} + +func (file filesystemStagingOutputFile) Write(data []byte) (int, error) { + return file.file.Write(data) +} + +func (file filesystemStagingOutputFile) Close() error { + return file.file.Close() +} + +func (file filesystemStagingOutputFile) osFile() *os.File { + return file.file +} + +func defaultStagingFileOperations() stagingFileOperations { + return filesystemStagingFileOperations{} +} + +func effectiveStagingFileOperations(operations stagingFileOperations) stagingFileOperations { + if operations == nil { + return defaultStagingFileOperations() + } + return operations +} diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index f38d199..1c14f07 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -47,7 +47,7 @@ SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端, ## 当前阶段 -当前项目已完成 Phase 0～2、T-301～T-303 与审核整改 `T-604`～`T-614`。Windows 安全路径阻断项、图标缓存资源边界、后台结果回 UI 线程的事件接线、双适配器交互契约、`VisibleItems` 快照生命周期、双端 Gio shell 职责拆分、unsafe cache 安全诊断/runbook、ZIP 中央目录/EOCD(含 ZIP64)预扫描、安装文件/目录/journal 的代码层耐久顺序、Catalog canonicalization/签名静态 corpus，以及同句柄 Catalog size/SHA→严格 app.json→staging/switch/回滚安装链均已关闭；T-303 已将 verified-package 的 staging 前磁盘/运行状态预检和稳定失败码落实到 core。T-615 已正式落成，下一步先关闭 staging 输出 I/O 根因与磁盘满诊断，再正式落成 T-401 进程检测与软件启动。物理断电、文件锁与杀毒软件干扰验证保留到 T-601 发布前环境验证。 +当前项目已完成 Phase 0～2、T-301～T-303、T-615 与审核整改 `T-604`～`T-614`。Windows 安全路径阻断项、图标缓存资源边界、后台结果回 UI 线程的事件接线、双适配器交互契约、`VisibleItems` 快照生命周期、双端 Gio shell 职责拆分、unsafe cache 安全诊断/runbook、ZIP 中央目录/EOCD(含 ZIP64)预扫描、安装文件/目录/journal 的代码层耐久顺序、Catalog canonicalization/签名静态 corpus，以及同句柄 Catalog size/SHA→严格 app.json→staging/switch/回滚安装链均已关闭；T-303 已将 verified-package 的 staging 前磁盘/运行状态预检和稳定失败码落实到 core，T-615 已将 ZIP 输入/staging 输出 I/O 分界、平台磁盘满分类和清理失败恢复落实到 core。下一步正式落成 T-401 进程检测与软件启动。物理断电、文件锁与杀毒软件干扰验证保留到 T-601 发布前环境验证。 优先路径: @@ -55,7 +55,7 @@ SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端, 2. 已完成 Phase 1:清单验签、ZIP 安全解压、原子切换回滚原型。 3. 已完成 Phase 2 与 T-301:清单/列表/详情/图标缓存 + 可恢复下载队列。 4. 已完成 T-604:modern/Win7 workspace 与 Gio 版本解析彻底隔离。 -5. 已完成 T-606～T-614:图标缓存资源边界、UI 线程事件接线、双 Gio 适配器交互契约、`VisibleItems` generation 生命周期、双端 `shell.go` 同 package 镜像职责拆分、unsafe cache 诊断/人工恢复指引、ZIP 中央目录/EOCD 预扫描、安装耐久顺序和 Catalog 静态签名向量;已完成 T-302/T-303:已验签 Catalog 选择与同句柄 size/SHA、严格 app.json、安全 staging/switch/健康与记录写回滚链路，以及 staging 前磁盘/运行状态预检与稳定失败码。下一步执行 T-615，关闭 staging 输出 I/O 根因保留与磁盘满诊断，再继续 T-401 与 Phase 4-6。T-601 仍须补真实 Windows 环境的断电/干扰注入。 +5. 已完成 T-606～T-615:图标缓存资源边界、UI 线程事件接线、双 Gio 适配器交互契约、`VisibleItems` generation 生命周期、双端 `shell.go` 同 package 镜像职责拆分、unsafe cache 诊断/人工恢复指引、ZIP 中央目录/EOCD 预扫描、安装耐久顺序、Catalog 静态签名向量，以及 staging 输出 I/O 根因与磁盘满诊断;已完成 T-302/T-303:已验签 Catalog 选择与同句柄 size/SHA、严格 app.json、安全 staging/switch/健康与记录写回滚链路，以及 staging 前磁盘/运行状态预检与稳定失败码。下一步正式落成并执行 T-401，再继续 Phase 4-6。T-601 仍须补真实 Windows 环境的断电/干扰注入。 ## 领取任务规则 diff --git a/docs/04-architecture.md b/docs/04-architecture.md index 66f805b..199f31f 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -179,7 +179,7 @@ T-301 下载队列: 必须防止:绝对路径、`../` 与 Windows dot-space 归一化穿越、首尾空格/尾随句点路径别名、DOS 设备名、符号链接逃逸、写入其他软件目录、覆盖 data 与 licenses、运行中强替换 EXE、未验证包被执行、解压数量/体积/压缩比无上限、包内自动执行脚本。 -Phase 1 ZIP 原型采用“两阶段解压”:第 0 阶段在任何 `zip.Reader` 构造前,从同一普通文件句柄核对 `expectedPackageSize` 与实际长度,并只读有界 EOCD 尾部及固定 ZIP64 end 记录以限制原始包、中央目录和声明条目数;第 1 阶段才由标准库解析完整中央目录,继续预检协议顶层、共享 Windows 安全路径、类型、重复项、entrypoint 与展开资源上限,再规划并确认所有 native 输出路径仍在 destination 内。全部通过后才创建新的 staging 并只写 `payload/`;任一复制/CRC 失败删除本次 staging。T-302 把这一原型封装为同句柄 `size → SHA-256 → scan → app.json → extract` 的生产安装链：app.json 读取有 1 MiB 上限并严格对齐可信 Catalog，实际写入文件 hash 进入 installed-app record；原型默认限制见 [api.md](api.md)，真实包分布复核仍是本任务验收的一部分。T-303 在严格验证和 extraction 之间加入唯一的 pre-extract 边界：提取器只输出已规划 payload 的 bytes/files 与安全 entrypoint，`core/application/install` 注入容量/目标状态 checker 并在创建 staging 前要求 `payload bytes + 64 MiB` 可用空间及目标未运行；checker 故障 fail closed。core 不包含 Windows API、进程枚举、等待、强杀或启动，具体 Toolhelp 适配与进程退出协议由 T-401 在 `platform/windows`/命令装配时实现。 +Phase 1 ZIP 原型采用“两阶段解压”:第 0 阶段在任何 `zip.Reader` 构造前,从同一普通文件句柄核对 `expectedPackageSize` 与实际长度,并只读有界 EOCD 尾部及固定 ZIP64 end 记录以限制原始包、中央目录和声明条目数;第 1 阶段才由标准库解析完整中央目录,继续预检协议顶层、共享 Windows 安全路径、类型、重复项、entrypoint 与展开资源上限,再规划并确认所有 native 输出路径仍在 destination 内。全部通过后才创建新的 staging 并只写 `payload/`;任一复制/CRC 失败删除本次 staging。T-302 把这一原型封装为同句柄 `size → SHA-256 → scan → app.json → extract` 的生产安装链：app.json 读取有 1 MiB 上限并严格对齐可信 Catalog，实际写入文件 hash 进入 installed-app record；原型默认限制见 [api.md](api.md)，真实包分布复核仍是本任务验收的一部分。T-303 在严格验证和 extraction 之间加入唯一的 pre-extract 边界：提取器只输出已规划 payload 的 bytes/files 与安全 entrypoint，`core/application/install` 注入容量/目标状态 checker 并在创建 staging 前要求 `payload bytes + 64 MiB` 可用空间及目标未运行；checker 故障 fail closed。T-615 进一步将 ZIP entry 输入的 open/read/CRC/close 与 staging 输出的创建/write/sync/close 分开：后者保留底层错误链，由必需的、平台注入的 `StorageFailureClassifier` 仅对 `ErrStagingOutput` 判断 `disk_full`，其他输出 I/O 稳定为 `install_failed`；清理失败不吞掉，下一次 Recover 仅在已验证 app layout 内删除残留 staging。core 不包含 Windows API、进程枚举、等待、强杀或启动，具体 Toolhelp 适配与进程退出协议由 T-401 在 `platform/windows`/命令装配时实现。 Phase 1 原子切换原型把 `install-transaction.json` 与目录现实共同作为恢复依据。阶段写入顺序为 `prepared → current_backed_up → staging_activated → committed`,健康失败写 `rollback_required`;崩溃恢复不自动信任未健康检查的新 current,而是恢复旧 backup 或撤销首次安装。日志结构见 [api.md](api.md)。 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index eb98fab..e2c98f5 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -85,7 +85,7 @@ Phase 3 的 T-301 → T-302 → T-303 是安全关键依赖链,任务之间保 #### Phase 3 交叉复核整改 -`docs/review/phase3-review.md` 的交叉复核裁定：在继续落成 T-401 前，先关闭 T-303 未覆盖的 staging 输出 I/O 根因保留与磁盘满统一诊断；运行状态切换临界区复查随 T-401 落成。 +`docs/review/phase3-review.md` 的交叉复核裁定已由 T-615 关闭 T-303 未覆盖的 staging 输出 I/O 根因保留与磁盘满统一诊断；运行状态切换临界区复查仍随 T-401 落成。 | ID | 任务 | 依赖 | 验收要点 | | --- | --- | --- | --- | diff --git a/docs/api.md b/docs/api.md index dc8b1b1..76afb31 100644 --- a/docs/api.md +++ b/docs/api.md @@ -160,6 +160,7 @@ T-102 Phase 1 原型进一步固定: - entrypoint 使用 payload 内相对路径表示,不得自带 `payload/` 前缀,且必须精确对应 ZIP 中的普通文件。 - 所有输出路径在创建 staging 前完成规划,并在逐段名称校验后再次验证 native `filepath.Join` 结果仍位于 destination 内;包含性检查是纵深防御,不能替代 Windows 名称规则。 - `app.json` 必须是 ZIP 根目录唯一普通文件，读取上限 1 MiB；严格 JSON 解析拒绝未知字段和尾随值，完整 v1 字段/常量必须通过运行时校验。`id`、`version`、`channel`、`min_os`、`architecture`、`entrypoint`、`requires_admin` 必须与可信 Catalog selection 一致；只有这一比对成功后才可创建 staging 并提取 payload。 +- T-615 将 ZIP 输入与 staging 输出错误分开：ZIP entry 的 open/read/CRC/close 失败保留为 `ErrArchiveCorrupt`；创建目录/文件、write、sync、close 与 staging-tree sync 失败保留 `ErrStagingOutput` 和底层错误链，不能误报为 ZIP 损坏。提取失败后的本次 staging 清理必须可观察；主失败和清理失败同时发生时，两者都可由 `errors.Is` 识别。 ### 2.4 安装记录 installed-app.json(本地) @@ -218,13 +219,15 @@ T-613 为该原型建立了 fail-closed 的耐久顺序:每个 payload 先完成 T-302 在 Switcher 的 health 阶段先运行必需的注入 health check，再原子写入新 `installed-app.json`;health 或记录写失败都必须触发既有 rollback，使旧 current/记录保持可用。只有 health 与记录均成功后才写 committed 并清理 backup/journal。 +若无 transaction 但存在残留 `staging/`，Recover 只会在 app root 已通过真实目录布局校验后删除该受控同级目录并返回 `aborted`；`staging` 不是目录或布局不安全时 fail closed。此恢复不得覆盖 `current/`、`installed-app.json`、`data/` 或 `licenses/`。 + 这些栅栏与注入失败测试只证明代码层面的调用顺序和 fail-closed 行为,不证明断电后硬件/驱动缓存、网络文件系统、文件锁或杀毒软件的物理表现。T-302 已完成代码整合；T-601 仍须在目标 Windows VM/真机执行断电与干扰故障注入。 ### 2.6 安装预检与失败码 在同句柄 size/SHA、ZIP 预扫描和严格 `app.json` 身份比对均通过后，提取器会在创建 `staging/` 前提供已规划 payload 的准确展开字节数、普通文件数和安全 entrypoint。安装 use case 必须以 `payload_bytes + 64 MiB` 查询 app root 所在卷的可用空间；可用空间不足时不创建 staging。预检不能替代写入、同步、切换或回滚阶段的 fail-closed I/O 错误处理。 -安装 use case 同时在上述位置检查当前 `current/` 是否正在运行。容量与运行状态均通过 core 接口注入；检查失败按不可安全继续处理。v1 不强杀、不启动、不等待进程退出。Windows Toolhelp 枚举、正常退出等待与启动协议属于后续 T-401，不能进入 core。 +安装 use case 同时在上述位置检查当前 `current/` 是否正在运行。容量、storage failure classifier 与运行状态均通过 core 接口注入，且均为必需依赖；classifier 只对已带 `ErrStagingOutput` 的原始 I/O 链识别磁盘满，core 不导入 Windows API。检查失败按不可安全继续处理。v1 不强杀、不启动、不等待进程退出。Windows Toolhelp 枚举、正常退出等待与启动协议属于后续 T-401，不能进入 core。 安装结果面向调用方的错误码为下表的稳定英文枚举；UI 负责本地化，原始错误只保留给 `errors.Is`、日志和诊断，不得进入 UI payload。 @@ -234,11 +237,11 @@ T-302 在 Switcher 的 health 阶段先运行必需的注入 health check，再 | `zip_path_escape` | ZIP/app manifest 路径违反共享 Windows 安全相对路径规则 | | `zip_corrupt` | ZIP 结构、CRC 或受限读取/提取不完整，不能作为有效包 | | `package_invalid` | package/app manifest 身份或协议不符合可信 selection | -| `disk_full` | 可用空间小于 `payload_bytes + 64 MiB` | +| `disk_full` | 可用空间小于 `payload_bytes + 64 MiB`，或平台 classifier 识别 staging write/sync/close 的底层 I/O 为磁盘满 | | `disk_check_failed` | 无法可靠取得可用空间或得到非法容量值 | | `app_running` | 当前目标程序仍在运行，更新不能替换 | | `target_state_unavailable` | 无法可靠取得目标运行状态 | -| `install_failed` | 其他未细分的安装、健康、记录、切换或回滚失败 | +| `install_failed` | 其他未细分的安装、健康、记录、切换、回滚或非磁盘满 staging 输出 I/O 失败 | 上述任一预检或验证失败都发生在 switch 前；已有版本的 `current` 和 `installed-app.json` 必须保持可用，首次安装不得留下 executable `current`。 diff --git a/docs/current-state.md b/docs/current-state.md index cde6734..4db5dee 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -13,22 +13,22 @@ ## 当前快照 - 日期:2026-07-19 -- 阶段:Phase 2 已完成(T-201～T-204);Phase 3 的 T-301 可恢复下载队列、T-302 安装流程整合与 T-303 失败处理/磁盘预检查已完成;审核整改 T-604～T-614 已完成;T-615 已正式落成，下一步领取并执行 staging 输出 I/O 根因保留与磁盘满诊断整改 +- 阶段:Phase 2 已完成(T-201～T-204);Phase 3 的 T-301 可恢复下载队列、T-302 安装流程整合、T-303 失败处理/磁盘预检查与 T-615 staging 输出 I/O/磁盘满诊断整改已完成;审核整改 T-604～T-614 已完成;下一步正式落成并执行 T-401 进程检测与软件启动 - 技术栈:根 Go 1.25 workspace 只纳入 core/app-modern,`app-win7/go.work` 独立纳入 core/app-win7;版本闸门证明 modern Gio v0.10.1 与 win7 Gio v0.6.0 不交叉解析 -- 生产代码:core 已有 Catalog/本地状态/存储、共享 Windows 安全相对路径策略与静态跨实现 canonicalization/Ed25519 vector corpus(拒绝非法 surrogate、`-0` 和非唯一 Base64 signature,大整数保持 token)、安全 ZIP 解压/回滚原型及 T-302/T-303 安装 use case(`core/application/install.InstallService` 只取已过滤 Catalog entry + architecture，强制注入 disk/target-state checker；`Extractor.ExtractVerifiedFileWithCheck` 在同一普通文件句柄按 size→SHA-256→EOCD/ZIP64→严格 app.json→已规划 payload 的 staging 前预检→安全 staging 的顺序处理，空间要求为 payload+64 MiB，失败返回稳定 code 且不触发 switch；每个实际 payload 文件 hash 写入 installed-app;health 或记录写失败经 Switcher 回滚),transaction/switch/rollback/recovery 的 journal、rename、清理经统一 fail-closed 耐久栅栏,Windows 使用目录句柄 FlushFileBuffers)、发布稳定只读 generation 的无 IO 软件列表模型、按 key in-flight + 流式有界读取 + 32 MiB/256-key LRU 的可信图标缓存、图标 Load/Decode 事件发布用例、有界 application event relay,以及默认并发 2 的持久可恢复下载队列;modern/win7 主循环已接 relay/Invalidate,AppShell 已实现搜索/分类/视图、惰性列表、详情右栏、完整图标失败 identity 生命周期与仅 `unsafe_cache` 可见的安全 locator/人工恢复提示,并按 root/header/catalog/detail/style 同 package 镜像职责拆文件 -- 测试:core 覆盖 Catalog 静态 canonicalization/Ed25519 vectors、非法 surrogate/`-0`/Base64 fail-closed、列表快照 generation/零复制、SemVer/12 状态、本地安装记录、Windows dot-space/设备名/Unicode 折叠路径攻击、ZIP destination 包含性与 EOCD/ZIP64 原始包/中央目录/条目数预扫描、T-302/T-303 同句柄 package size/SHA、严格/有界 app.json、verified payload 预检 hook、容量精确阈值/故障、程序运行/状态故障、稳定安装失败码、payload hash 记录、Catalog 选择拒绝、transaction recovery、health/记录写失败回滚、payload/staging tree/journal/rename/rollback/recovery/cleanup 耐久顺序及错误注入、Windows 原生目录 `FlushFileBuffers`、图标并发/取消/读取边界/LRU、真实目录/symlink fail-closed 与 cache→`unsafe_cache` event、relay 背压与关闭、下载并发/暂停/取消/重试/Range/断连/恢复/事件失败与文件身份替换;两个 app 覆盖 Editor/视图/分类/行/恢复/关闭接线、500 项 viewport、AppID 控件与分类控件生命周期、详情上下文、空状态语义、UI drain 前后、图标失败身份生命周期与 `unsafe_cache` 详情语义;安装恢复矩阵保持通过 +- 生产代码:core 已有 Catalog/本地状态/存储、共享 Windows 安全相对路径策略与静态跨实现 canonicalization/Ed25519 vector corpus(拒绝非法 surrogate、`-0` 和非唯一 Base64 signature,大整数保持 token)、安全 ZIP 解压/回滚原型及 T-302/T-303/T-615 安装 use case(`core/application/install.InstallService` 只取已过滤 Catalog entry + architecture，强制注入 disk/storage-failure/target-state checker；`Extractor.ExtractVerifiedFileWithCheck` 在同一普通文件句柄按 size→SHA-256→EOCD/ZIP64→严格 app.json→已规划 payload 的 staging 前预检→安全 staging 的顺序处理，空间要求为 payload+64 MiB，ZIP 输入错误与 staging 创建/write/sync/close 错误分界并保留原始 I/O 链；平台可识别的后者磁盘满返回 `disk_full`，其余输出 I/O 返回稳定 code 且不触发 switch；清理失败可观察，Recover 仅删除已验证 layout 内的残留 staging；每个实际 payload 文件 hash 写入 installed-app;health 或记录写失败经 Switcher 回滚),transaction/switch/rollback/recovery 的 journal、rename、清理经统一 fail-closed 耐久栅栏,Windows 使用目录句柄 FlushFileBuffers)、发布稳定只读 generation 的无 IO 软件列表模型、按 key in-flight + 流式有界读取 + 32 MiB/256-key LRU 的可信图标缓存、图标 Load/Decode 事件发布用例、有界 application event relay,以及默认并发 2 的持久可恢复下载队列;modern/win7 主循环已接 relay/Invalidate,AppShell 已实现搜索/分类/视图、惰性列表、详情右栏、完整图标失败 identity 生命周期与仅 `unsafe_cache` 可见的安全 locator/人工恢复提示,并按 root/header/catalog/detail/style 同 package 镜像职责拆文件 +- 测试:core 覆盖 Catalog 静态 canonicalization/Ed25519 vectors、非法 surrogate/`-0`/Base64 fail-closed、列表快照 generation/零复制、SemVer/12 状态、本地安装记录、Windows dot-space/设备名/Unicode 折叠路径攻击、ZIP destination 包含性与 EOCD/ZIP64 原始包/中央目录/条目数预扫描、T-302/T-303/T-615 同句柄 package size/SHA、严格/有界 app.json、verified payload 预检 hook、容量精确阈值/故障、程序运行/状态故障、稳定安装失败码、staging write/sync/close ENOSPC 与普通输出 I/O 原因保留、CRC 输入分界、清理失败/受控恢复、payload hash 记录、Catalog 选择拒绝、transaction recovery、health/记录写失败回滚、payload/staging tree/journal/rename/rollback/recovery/cleanup 耐久顺序及错误注入、Windows 原生目录 `FlushFileBuffers`、图标并发/取消/读取边界/LRU、真实目录/symlink fail-closed 与 cache→`unsafe_cache` event、relay 背压与关闭、下载并发/暂停/取消/重试/Range/断连/恢复/事件失败与文件身份替换;两个 app 覆盖 Editor/视图/分类/行/恢复/关闭接线、500 项 viewport、AppID 控件与分类控件生命周期、详情上下文、空状态语义、UI drain 前后、图标失败身份生命周期与 `unsafe_cache` 详情语义;安装恢复矩阵保持通过 - 数据:`schemas/` 已有 manifest/app.json/installed-app.json/download-task.json v1 Schema并注明 Windows 路径运行时权威规则;`testdata/catalog/` 有公开虚构清单样例和 v1 静态 canonicalization/Ed25519 corpus;`testdata/zip/` 与 `testdata/download/` 记录运行时生成的攻击/传输矩阵 - 标准启动路径:`./init.sh` / `./init.ps1`(同步依赖、执行完整 Phase 0 闸门、打印双目标构建命令) - 标准验证路径:`bash scripts/verify_phase0.sh` / `./scripts/verify_phase0.ps1` - 版本管理:git 已初始化,main 分支,远端 origin 为 Gitea `opc/soft_quay`;harness 文档已提交 -- 当前 blocker:T-615 必须先关闭 staging 输出 I/O 错误链、磁盘满分类和清理失败恢复语义，才可落成 T-401；T-614 已以静态 corpus 冻结客户端 Catalog canonicalization/签名行为,外部 `softbox-catalog` 消费 corpus 的 CI 证据仍需跨仓库协调,但不阻止 T-615。物理断电、文件锁/杀毒软件干扰仍需 T-601 的目标 Windows VM/真机故障注入 +- 当前 blocker:T-615 已关闭 staging 输出 I/O 错误链、磁盘满分类和清理失败恢复语义；T-401 尚未正式落成，必须先定义其消费 T-303 的 `TargetStateChecker`、切换临界区最后复查与启动边界。T-614 的外部 `softbox-catalog` 消费 corpus CI 证据仍需跨仓库协调，但不阻止 T-401。物理断电、文件锁/杀毒软件干扰仍需 T-601 的目标 Windows VM/真机故障注入 ## 当前目录要点 | 路径 | 状态 | 说明 | | --- | --- | --- | | `docs/` | 已有 | harness coding 文档集(本次初始化完成) | -| `docs/tasks/` | 已有 | Phase 0～2、T-301～T-303 与 T-604～T-614 已完成;T-615 已正式落成，待领取执行；之后落成 T-401 进程检测与软件启动任务 | +| `docs/tasks/` | 已有 | Phase 0～2、T-301～T-303、T-604～T-615 已完成;下一步落成 T-401 进程检测与软件启动任务 | | `scripts/` | 已有 | harness 治理、core 边界、Go 版本检查与 Phase 0 双平台验证入口 | | `core/` | 已建 | Go 1.20 兼容;已有正式 Catalog、本地状态/存储、共享 Windows safepath、列表模型、有界并发图标缓存、图标事件/relay、可恢复下载队列与 Phase 1 安装安全原型 | | `app-modern/` | 已建 | Go 1.25.0 + Gio v0.10.1;Modern AppShell 已接入虚拟列表、详情、图标事件 drain/过期拒绝和内存 ImageOp,并拆为五类 shell 职责文件 | @@ -40,9 +40,9 @@ 任务状态以 `docs/tasks/` 各任务文件 frontmatter 的 `status` 为准。本节只写项目级摘要: -- 已完成:Phase 0 的 `T-001`～`T-004`;Phase 1 的 `T-101`、`T-102`、`T-103`;Phase 2 的 `T-201`～`T-204`;Phase 3 的 `T-301`～`T-303`;审核整改 `T-604`～`T-614`。 +- 已完成:Phase 0 的 `T-001`～`T-004`;Phase 1 的 `T-101`、`T-102`、`T-103`;Phase 2 的 `T-201`～`T-204`;Phase 3 的 `T-301`～`T-303` 与 `T-615`;审核整改 `T-604`～`T-614`。 - 正在进行:无。 -- 下一个可领取任务:T-615（依赖 T-303 已完成）；T-401 需等待 T-615 完成后再正式落成。T-601 的物理断电与干扰故障注入仍保留为发布前环境验证。 +- 下一个动作:正式落成 T-401（其依赖 T-303、T-615 均已完成），然后按单 Agent 流程领取执行。T-601 的物理断电与干扰故障注入仍保留为发布前环境验证。 ## 当前可运行内容 diff --git a/docs/tasks/T-615.md b/docs/tasks/T-615.md index abf9c08..86ae77e 100644 --- a/docs/tasks/T-615.md +++ b/docs/tasks/T-615.md @@ -3,12 +3,12 @@ id: T-615 title: 保留安装输出 I/O 根因并统一磁盘满诊断 phase: 3 deps: [T-303] -status: TODO +status: DONE created: 2026-07-19 issue: null -context_ref: null +context_ref: d1603c52b6c2df645db11a808ced9a3cc8b3e764 claim_branch: null -work_branch: null +work_branch: agent/codex/T-615 write_paths: - docs/tasks/T-615.md - core/installer/ @@ -57,3 +57,6 @@ T-303 的磁盘预检只能 fail-fast，不能消除“查询后被其他进程 ## 执行记录 - 2026-07-19:正式落成。根据 Phase 3 交叉复核冻结输出 I/O/ZIP 输入的错误分界、可注入磁盘满分类、清理失败恢复语义及 T-401/O1 与后续编排/O3 的边界。 +- 2026-07-19:领取任务，基于 `d1603c52b6c2df645db11a808ced9a3cc8b3e764` 在 `agent/codex/T-615` 执行；先运行基线验证，再实现与复核。 +- 2026-07-19:完成。`Extractor` 以内部 file-operation seam 区分 ZIP 输入与 staging 创建/write/sync/close 输出，新增可保留原始错误链的 `ErrStagingOutput`；清理失败以 `ErrStagingCleanup` 与主失败共同返回。无 journal 的残留 staging 仅在通过 app layout 校验后由 Recover 删除，不影响 current、installed-app、data 或 licenses。`InstallService` 强制注入 `StorageFailureClassifier`，只对 `ErrStagingOutput` 中的平台可识别磁盘满返回 `disk_full`，其他输出 I/O 返回 `install_failed`。 +- 2026-07-19:验证通过：基线 `./init.ps1`；`go -C core vet ./...`；`go -C core test -count=1 ./...`；`go -C core test -count=10 ./installer ./application/install`；`./scripts/verify_phase0.ps1`；`python scripts/validate_agent_context.py`；`python scripts/validate_harness_governance.py`。新增写/sync/close ENOSPC、普通输出 I/O、CRC 分界、清理失败及后续恢复测试。