fix lint

internal/apps/agent/sync/pages.go

@@ -1,3 +1,4 @@
+// Package sync applies control-plane configuration to the local agent runtime.
 package sync
 
 import (
@@ -10,6 +11,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"math"
 	"os"
 	"path"
 	"path/filepath"
@@ -18,6 +20,12 @@ import (
 	"github.com/Rain-kl/Wavelet/internal/apps/agent/protocol"
 )
 
+const (
+	pagesMaxExtractedFileBytes = 100 * 1024 * 1024
+	pagesDirPerm               = 0o755
+	pagesManifestFilePerm      = 0o644
+)
+
 type pagesSourceDocument struct {
 	Routes []pagesSourceRoute `json:"routes"`
 }
@@ -66,7 +74,7 @@ func (s *Service) ensurePagesDeployment(ctx context.Context, deployment pagesDep
 		return fmt.Errorf("download Pages deployment %d: %w", deployment.DeploymentID, err)
 	}
 	if got := checksumBytes(packageBytes); got != deployment.Checksum {
-		return fmt.Errorf("Pages deployment %d checksum mismatch: expected %s, got %s", deployment.DeploymentID, deployment.Checksum, got)
+		return fmt.Errorf("pages deployment %d checksum mismatch: expected %s, got %s", deployment.DeploymentID, deployment.Checksum, got)
 	}
 	releaseDir := pagesReleaseDir(s.pagesDir, deployment.DeploymentID, deployment.Checksum)
 	if !markerMatches(releaseDir, deployment) {
@@ -83,7 +91,7 @@ func referencedPagesDeployments(config *protocol.ActiveConfigResponse) ([]pagesD
 	}
 	var doc pagesSourceDocument
 	if err := json.Unmarshal([]byte(config.SourceConfigJSON), &doc); err != nil {
-		return nil, fmt.Errorf("decode Pages references: %w", err)
+		return nil, fmt.Errorf("decode pages references: %w", err)
 	}
 	seen := make(map[uint]struct{})
 	result := make([]pagesDeploymentSource, 0)
@@ -94,7 +102,7 @@ func referencedPagesDeployments(config *protocol.ActiveConfigResponse) ([]pagesD
 		deploymentID := route.PagesDeployment.DeploymentID
 		checksum := strings.TrimSpace(route.PagesDeployment.Checksum)
 		if deploymentID == 0 || checksum == "" {
-			return nil, errors.New("Pages deployment snapshot is incomplete")
+			return nil, errors.New("pages deployment snapshot is incomplete")
 		}
 		if _, ok := seen[deploymentID]; ok {
 			continue
@@ -152,7 +160,7 @@ func findCommonRootPrefix(files []*zip.File) (string, error) {
 func extractPagesPackage(packageBytes []byte, releaseDir string, deployment pagesDeploymentSource) error {
 	tmpDir := releaseDir + ".tmp"
 	_ = os.RemoveAll(tmpDir)
-	if err := os.MkdirAll(tmpDir, 0o755); err != nil {
+	if err := os.MkdirAll(tmpDir, pagesDirPerm); err != nil {
 		return err
 	}
 	reader, err := zip.NewReader(bytes.NewReader(packageBytes), int64(len(packageBytes)))
@@ -182,7 +190,7 @@ func extractPagesPackage(packageBytes []byte, releaseDir string, deployment page
 		}
 		if item.FileInfo().Mode()&os.ModeSymlink != 0 {
 			_ = os.RemoveAll(tmpDir)
-			return fmt.Errorf("Pages package contains unsupported symlink: %s", relativePath)
+			return fmt.Errorf("pages package contains unsupported symlink: %s", relativePath)
 		}
 		if err := extractPagesFile(item, filepath.Join(tmpDir, relativePath)); err != nil {
 			_ = os.RemoveAll(tmpDir)
@@ -197,21 +205,32 @@ func extractPagesPackage(packageBytes []byte, releaseDir string, deployment page
 	return os.Rename(tmpDir, releaseDir)
 }
 
+func pagesZipEntryCopyLimit(size uint64) (int64, error) {
+	if size == 0 || size > pagesMaxExtractedFileBytes || size > uint64(math.MaxInt64) {
+		return 0, errors.New("pages file size out of bounds")
+	}
+	return int64(size), nil //nolint:gosec // size is bounded to math.MaxInt64 above
+}
+
 func extractPagesFile(item *zip.File, targetPath string) error {
-	if err := os.MkdirAll(filepath.Dir(targetPath), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Dir(targetPath), pagesDirPerm); err != nil {
 		return err
 	}
 	source, err := item.Open()
 	if err != nil {
 		return err
 	}
-	defer source.Close()
-	target, err := os.OpenFile(targetPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, item.FileInfo().Mode().Perm())
+	defer func() { _ = source.Close() }()
+	target, err := os.OpenFile(targetPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, item.FileInfo().Mode().Perm()) //nolint:gosec // targetPath is under managed PagesDir from validated zip entry
 	if err != nil {
 		return err
 	}
-	defer target.Close()
-	_, err = io.Copy(target, source)
+	defer func() { _ = target.Close() }()
+	limit, err := pagesZipEntryCopyLimit(item.UncompressedSize64)
+	if err != nil {
+		return fmt.Errorf("%s: %w", item.Name, err)
+	}
+	_, err = io.CopyN(target, source, limit)
 	return err
 }
 
@@ -219,7 +238,7 @@ func switchPagesCurrentDir(baseDir string, deploymentID uint, releaseDir string)
 	currentDir := pagesCurrentDir(baseDir, deploymentID)
 	previousDir := currentDir + ".previous"
 	_ = os.RemoveAll(previousDir)
-	if err := os.MkdirAll(filepath.Dir(currentDir), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Dir(currentDir), pagesDirPerm); err != nil {
 		return err
 	}
 	if _, err := os.Stat(currentDir); err == nil {
@@ -249,25 +268,25 @@ func copyPagesDir(sourceDir string, targetDir string) error {
 		}
 		targetPath := filepath.Join(targetDir, relativePath)
 		if entry.IsDir() {
-			return os.MkdirAll(targetPath, 0o755)
+			return os.MkdirAll(targetPath, pagesDirPerm)
 		}
 		info, err := entry.Info()
 		if err != nil {
 			return err
 		}
-		input, err := os.Open(sourcePath)
+		input, err := os.Open(sourcePath) //nolint:gosec // sourcePath is under managed PagesDir walk root
 		if err != nil {
 			return err
 		}
-		defer input.Close()
-		if err := os.MkdirAll(filepath.Dir(targetPath), 0o755); err != nil {
+		defer func() { _ = input.Close() }()
+		if err := os.MkdirAll(filepath.Dir(targetPath), pagesDirPerm); err != nil {
 			return err
 		}
-		output, err := os.OpenFile(targetPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, info.Mode().Perm())
+		output, err := os.OpenFile(targetPath, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, info.Mode().Perm()) //nolint:gosec // targetPath is under managed PagesDir walk root
 		if err != nil {
 			return err
 		}
-		defer output.Close()
+		defer func() { _ = output.Close() }()
 		_, err = io.Copy(output, input)
 		return err
 	})
@@ -279,20 +298,20 @@ func normalizePagesArchivePath(raw string) (string, bool, error) {
 		return "", true, nil
 	}
 	if strings.HasPrefix(name, "/") {
-		return "", false, fmt.Errorf("Pages package contains absolute path: %s", raw)
+		return "", false, fmt.Errorf("pages package contains absolute path: %s", raw)
 	}
 	cleaned := path.Clean(name)
 	if cleaned == "." {
 		return "", true, nil
 	}
 	if cleaned == ".." || strings.HasPrefix(cleaned, "../") || strings.Contains(cleaned, "/../") {
-		return "", false, fmt.Errorf("Pages package path escapes deployment root: %s", raw)
+		return "", false, fmt.Errorf("pages package path escapes deployment root: %s", raw)
 	}
 	return filepath.FromSlash(cleaned), false, nil
 }
 
 func markerMatches(dir string, deployment pagesDeploymentSource) bool {
-	data, err := os.ReadFile(filepath.Join(dir, ".openflare-pages.json"))
+	data, err := os.ReadFile(filepath.Join(dir, ".openflare-pages.json")) //nolint:gosec // dir is managed PagesDir
 	if err != nil {
 		return false
 	}
@@ -304,14 +323,11 @@ func markerMatches(dir string, deployment pagesDeploymentSource) bool {
 }
 
 func writePagesMarker(dir string, deployment pagesDeploymentSource) error {
-	data, err := json.Marshal(pagesDeploymentMarker{
-		DeploymentID: deployment.DeploymentID,
-		Checksum:     deployment.Checksum,
-	})
+	data, err := json.Marshal(pagesDeploymentMarker(deployment))
 	if err != nil {
 		return err
 	}
-	return os.WriteFile(filepath.Join(dir, ".openflare-pages.json"), data, 0o644)
+	return os.WriteFile(filepath.Join(dir, ".openflare-pages.json"), data, pagesManifestFilePerm)
 }
 
 func pagesCurrentDir(baseDir string, deploymentID uint) string {

internal/apps/agent/sync/service.go

@@ -18,12 +18,14 @@ import (
 	"github.com/Rain-kl/Wavelet/internal/apps/agent/state"
 )
 
+// Apply result constants indicate the outcome reported back to the server.
 const (
 	ApplyResultSuccess = "success"
 	ApplyResultWarning = "warning"
 	ApplyResultFailed  = "failed"
 )
 
+// ConfigClient is the interface for communicating with the server control plane.
 type ConfigClient interface {
 	GetActiveConfig(ctx context.Context) (*protocol.ActiveConfigResponse, error)
 	DownloadPagesDeploymentPackage(ctx context.Context, deploymentID uint) ([]byte, error)
@@ -31,6 +33,7 @@ type ConfigClient interface {
 	SyncWAFIPGroups(ctx context.Context, payload protocol.WAFIPGroupSyncRequest) (*protocol.WAFIPGroupSyncResponse, error)
 }
 
+// NginxManager is the interface for managing the local OpenResty instance.
 type NginxManager interface {
 	Apply(ctx context.Context, mainConfig string, routeConfig string, supportFiles []protocol.SupportFile) nginx.ApplyOutcome
 	EnsureRuntime(ctx context.Context, recreate bool) error
@@ -40,6 +43,7 @@ type NginxManager interface {
 	SyncWAFIPGroups(groups []protocol.WAFIPGroup) error
 }
 
+// Service orchestrates configuration synchronisation between the server and the local OpenResty instance.
 type Service struct {
 	client       ConfigClient
 	nginxManager NginxManager
@@ -47,10 +51,12 @@ type Service struct {
 	pagesDir     string
 }
 
+// SetPagesDir sets the local directory used for pages deployment packages.
 func (s *Service) SetPagesDir(path string) {
 	s.pagesDir = strings.TrimSpace(path)
 }
 
+// New creates a new Service with the given client, nginx manager, and state store.
 func New(client ConfigClient, nginxManager NginxManager, stateStore *state.Store) *Service {
 	return &Service{
 		client:       client,
@@ -59,100 +65,34 @@ func New(client ConfigClient, nginxManager NginxManager, stateStore *state.Store
 	}
 }
 
+// SyncOnce performs a single periodic sync against the given active config summary.
 func (s *Service) SyncOnce(ctx context.Context, target *protocol.ActiveConfigMeta) error {
 	return s.sync(ctx, false, target)
 }
 
+// SyncOnStartup performs an initial sync at agent startup, applying config even when checksums already match.
 func (s *Service) SyncOnStartup(ctx context.Context, target *protocol.ActiveConfigMeta) error {
 	return s.sync(ctx, true, target)
 }
 
 func (s *Service) sync(ctx context.Context, startup bool, target *protocol.ActiveConfigMeta) error {
-	mode := "periodic"
-	if startup {
-		mode = "startup"
-	}
-	snapshot, err := s.stateStore.Load()
+	mode := syncMode(startup)
+	snapshot, currentChecksum, err := s.loadSyncState()
 	if err != nil {
 		return err
 	}
-	currentChecksum, err := s.nginxManager.CurrentChecksum()
-	if err != nil {
-		return err
-	}
-
-	if target != nil {
-		target.Version = strings.TrimSpace(target.Version)
-		target.Checksum = strings.TrimSpace(target.Checksum)
-	}
+	normalizeSyncTarget(target)
 
 	if target == nil || target.Version == "" || target.Checksum == "" {
-		if !startup {
-			slog.Debug("skipping sync because heartbeat returned no active config summary", "mode", mode)
-			return nil
-		}
-		slog.Debug("sync startup fallback: active config summary unavailable, fetching active config directly")
-		config, fetchErr := s.client.GetActiveConfig(ctx)
-		if fetchErr != nil {
-			slog.Error("fetch active config failed", "mode", mode, "error", fetchErr)
-			return fetchErr
-		}
-		target = &protocol.ActiveConfigMeta{
-			Version:  config.Version,
-			Checksum: config.Checksum,
-		}
-		return s.applyIfNeeded(ctx, mode, startup, snapshot, currentChecksum, target, config)
+		return s.syncWithoutTarget(ctx, mode, startup, snapshot, currentChecksum)
 	}
-
 	if currentChecksum == target.Checksum {
-		if startup {
-			config, fetchErr := s.client.GetActiveConfig(ctx)
-			if fetchErr != nil {
-				slog.Error("fetch active config failed", "mode", mode, "error", fetchErr)
-				return fetchErr
-			}
-			return s.applyIfNeeded(ctx, mode, startup, snapshot, currentChecksum, target, config)
-		}
-		slog.Debug("local openresty config already up to date", "mode", mode, "version", target.Version)
-		shouldReport := shouldReportNoopApply(snapshot, target.Version, target.Checksum)
-		if shouldReport {
-			if err = s.reportNoopApply(ctx, snapshot.NodeID, target.Version, target.Checksum, "", "", 0); err != nil {
-				return err
-			}
-		}
-		snapshot.CurrentVersion = target.Version
-		snapshot.CurrentChecksum = target.Checksum
-		clearBlockedTarget(snapshot)
-		snapshot.LastError = ""
-		slog.Debug("sync finished without changes", "mode", mode, "version", target.Version)
-		return s.stateStore.Save(snapshot)
+		return s.syncMatchingChecksum(ctx, mode, startup, snapshot, currentChecksum, target)
 	}
-	if isBlockedTarget(snapshot, target.Version, target.Checksum) {
-		slog.Warn("skipping blocked config version after previous failed apply", "mode", mode, "version", target.Version, "checksum", target.Checksum)
-		if startup {
-			if err = s.ensureRuntimeForCurrentConfig(ctx, mode, snapshot, currentChecksum); err != nil {
-				return err
-			}
-			return s.stateStore.Save(snapshot)
-		}
-		return nil
-	}
-	if hasBlockedTarget(snapshot) {
-		clearBlockedTarget(snapshot)
-	}
-	if snapshot.CurrentVersion == target.Version && snapshot.CurrentChecksum == target.Checksum && !startup {
-		slog.Debug("skipping config fetch because state already records target version/checksum", "version", target.Version, "checksum", target.Checksum)
-		return s.stateStore.Save(snapshot)
-	}
-
-	config, err := s.client.GetActiveConfig(ctx)
-	if err != nil {
-		slog.Error("fetch active config failed", "mode", mode, "error", err)
-		return err
-	}
-	return s.applyIfNeeded(ctx, mode, startup, snapshot, currentChecksum, target, config)
+	return s.syncMismatchedChecksum(ctx, mode, startup, snapshot, currentChecksum, target)
 }
 
+// ForceSyncOnce clears any blocked target state then unconditionally fetches and applies the active config.
 func (s *Service) ForceSyncOnce(ctx context.Context, target *protocol.ActiveConfigMeta) error {
 	snapshot, err := s.stateStore.Load()
 	if err != nil {
@@ -174,6 +114,7 @@ func (s *Service) ForceSyncOnce(ctx context.Context, target *protocol.ActiveConf
 	return s.applyIfNeeded(ctx, "force", true, snapshot, currentChecksum, target, config)
 }
 
+// WAFIPGroupChecksums returns the current per-group checksums held by the nginx manager.
 func (s *Service) WAFIPGroupChecksums() (map[string]string, error) {
 	if s.nginxManager == nil {
 		return map[string]string{}, nil
@@ -181,7 +122,8 @@ func (s *Service) WAFIPGroupChecksums() (map[string]string, error) {
 	return s.nginxManager.WAFIPGroupChecksums()
 }
 
-func (s *Service) ApplyWAFIPGroups(ctx context.Context, groups []protocol.WAFIPGroup) error {
+// ApplyWAFIPGroups writes the given WAF IP groups to the nginx manager.
+func (s *Service) ApplyWAFIPGroups(_ context.Context, groups []protocol.WAFIPGroup) error {
 	if len(groups) == 0 || s.nginxManager == nil {
 		return nil
 	}
@@ -190,36 +132,13 @@ func (s *Service) ApplyWAFIPGroups(ctx context.Context, groups []protocol.WAFIPG
 
 func (s *Service) applyIfNeeded(ctx context.Context, mode string, startup bool, snapshot *state.Snapshot, currentChecksum string, target *protocol.ActiveConfigMeta, config *protocol.ActiveConfigResponse) error {
 	if currentChecksum == config.Checksum && !startup {
-		slog.Debug("local openresty config already up to date", "mode", mode, "version", config.Version)
-		shouldReport := shouldReportNoopApply(snapshot, config.Version, config.Checksum)
-		if shouldReport {
-			rendered, renderErr := renderActiveConfig(config)
-			if renderErr != nil {
-				return renderErr
-			}
-			if err := s.reportNoopApply(ctx, snapshot.NodeID, config.Version, config.Checksum, checksumString(rendered.mainConfig), checksumString(rendered.routeConfig), len(rendered.supportFiles)); err != nil {
-				return err
-			}
-		}
-		snapshot.CurrentVersion = config.Version
-		snapshot.CurrentChecksum = config.Checksum
-		clearBlockedTarget(snapshot)
-		snapshot.LastError = ""
-		slog.Debug("sync finished without changes", "mode", mode, "version", config.Version)
-		return s.stateStore.Save(snapshot)
+		return s.handleUpToDateConfig(ctx, mode, snapshot, config)
 	}
 	if target != nil && (target.Version != config.Version || target.Checksum != config.Checksum) {
 		slog.Warn("active config changed between heartbeat and fetch", "heartbeat_version", target.Version, "heartbeat_checksum", target.Checksum, "fetched_version", config.Version, "fetched_checksum", config.Checksum)
 	}
-	if isBlockedTarget(snapshot, config.Version, config.Checksum) {
-		slog.Warn("skipping blocked config after fetch because the same version previously failed", "mode", mode, "version", config.Version, "checksum", config.Checksum)
-		if startup {
-			if err := s.ensureRuntimeForCurrentConfig(ctx, mode, snapshot, currentChecksum); err != nil {
-				return err
-			}
-			return s.stateStore.Save(snapshot)
-		}
-		return nil
+	if handled, err := s.handleBlockedConfigAfterFetch(ctx, mode, startup, snapshot, currentChecksum, config); handled {
+		return err
 	}
 	if hasBlockedTarget(snapshot) {
 		clearBlockedTarget(snapshot)
@@ -228,6 +147,10 @@ func (s *Service) applyIfNeeded(ctx context.Context, mode string, startup bool,
 		slog.Debug("skipping apply because state already records target version/checksum", "version", config.Version, "checksum", config.Checksum)
 		return s.stateStore.Save(snapshot)
 	}
+	return s.applyRenderedConfig(ctx, mode, snapshot, currentChecksum, config)
+}
+
+func (s *Service) applyRenderedConfig(ctx context.Context, mode string, snapshot *state.Snapshot, currentChecksum string, config *protocol.ActiveConfigResponse) error {
 	rendered, err := renderActiveConfig(config)
 	if err != nil {
 		return err
@@ -238,49 +161,8 @@ func (s *Service) applyIfNeeded(ctx context.Context, mode string, startup bool,
 	mainConfigChecksum := checksumString(rendered.mainConfig)
 	routeConfigChecksum := checksumString(rendered.routeConfig)
 	slog.Info("applying new openresty config", "mode", mode, "from_version", snapshot.CurrentVersion, "to_version", config.Version, "old_checksum", currentChecksum, "new_checksum", config.Checksum)
-	outcome := s.nginxManager.Apply(ctx, rendered.mainConfig, rendered.routeConfig, rendered.supportFiles)
-	message := strings.TrimSpace(outcome.Message)
-	if outcome.Status == "" {
-		outcome.Status = nginx.ApplyStatusFatal
-		if message == "" {
-			message = "openresty apply returned empty outcome"
-		}
-	}
-
-	reportResult := ApplyResultFailed
-	switch outcome.Status {
-	case nginx.ApplyStatusSuccess:
-		slog.Info("openresty config applied successfully", "mode", mode, "version", config.Version)
-		snapshot.CurrentVersion = config.Version
-		snapshot.CurrentChecksum = config.Checksum
-		clearBlockedTarget(snapshot)
-		snapshot.LastError = ""
-		snapshot.OpenrestyStatus = protocol.OpenrestyStatusHealthy
-		snapshot.OpenrestyMessage = ""
-		reportResult = ApplyResultSuccess
-		if message == "" {
-			message = "apply success"
-		}
-	case nginx.ApplyStatusWarning:
-		if message == "" {
-			message = "apply rolled back to previous config"
-		}
-		slog.Warn("openresty config apply rolled back", "mode", mode, "version", config.Version, "message", message)
-		markBlockedTarget(snapshot, config.Version, config.Checksum, message)
-		snapshot.LastError = message
-		snapshot.OpenrestyStatus = protocol.OpenrestyStatusHealthy
-		snapshot.OpenrestyMessage = message
-		reportResult = ApplyResultWarning
-	default:
-		if message == "" {
-			message = "openresty apply failed"
-		}
-		slog.Error("apply openresty config failed", "mode", mode, "version", config.Version, "message", message)
-		markBlockedTarget(snapshot, config.Version, config.Checksum, message)
-		snapshot.LastError = message
-		snapshot.OpenrestyStatus = protocol.OpenrestyStatusUnhealthy
-		snapshot.OpenrestyMessage = message
-	}
+	outcome, message := normalizeApplyOutcome(s.nginxManager.Apply(ctx, rendered.mainConfig, rendered.routeConfig, rendered.supportFiles))
+	applyResult := updateSnapshotFromApplyOutcome(mode, snapshot, config, outcome, message)
 
 	if err := s.stateStore.Save(snapshot); err != nil {
 		return err
@@ -288,25 +170,25 @@ func (s *Service) applyIfNeeded(ctx context.Context, mode string, startup bool,
 	if err := s.client.ReportApplyLog(ctx, protocol.ApplyLogPayload{
 		NodeID:              snapshot.NodeID,
 		Version:             config.Version,
-		Result:              reportResult,
-		Message:             message,
+		Result:              applyResult.reportResult,
+		Message:             applyResult.message,
 		Checksum:            config.Checksum,
 		MainConfigChecksum:  mainConfigChecksum,
 		RouteConfigChecksum: routeConfigChecksum,
 		SupportFileCount:    len(rendered.supportFiles),
 	}); err != nil {
-		slog.Error("report apply log failed", "version", config.Version, "result", reportResult, "error", err)
+		slog.Error("report apply log failed", "version", config.Version, "result", applyResult.reportResult, "error", err)
 		return err
 	}
-	if reportResult == ApplyResultFailed {
+	if applyResult.reportResult == ApplyResultFailed {
 		slog.Warn("failed apply log reported", "version", config.Version)
-		return outcomeError(config.Version, message)
+		return outcomeError(config.Version, applyResult.message)
 	}
 	if err := s.syncReferencedWAFIPGroups(ctx, rendered.supportFiles); err != nil {
 		slog.Error("sync referenced waf ip groups failed", "version", config.Version, "error", err)
 		return err
 	}
-	slog.Debug("apply log reported", "version", config.Version, "result", reportResult)
+	slog.Debug("apply log reported", "version", config.Version, "result", applyResult.reportResult)
 	return nil
 }
 
@@ -476,13 +358,13 @@ func (s *Service) ensureRuntimeForCurrentConfig(ctx context.Context, mode string
 	if err := s.nginxManager.EnsureRuntime(ctx, true); err != nil {
 		if strings.TrimSpace(snapshot.CurrentChecksum) == "" {
 			reason := fmt.Sprintf("blocked config %s has no historical config and current local config cannot start: %v", strings.TrimSpace(snapshot.BlockedVersion), err)
-			if fallbackErr := s.nginxManager.EnsureSafeFallbackRuntime(ctx, reason); fallbackErr == nil {
+			fallbackErr := s.nginxManager.EnsureSafeFallbackRuntime(ctx, reason)
+			if fallbackErr == nil {
 				snapshot.OpenrestyStatus = protocol.OpenrestyStatusHealthy
 				snapshot.OpenrestyMessage = "safe default fallback runtime started"
 				return nil
-			} else {
-				err = fmt.Errorf("%v; fallback recovery failed: %w", err, fallbackErr)
 			}
+			err = fmt.Errorf("%v; fallback recovery failed: %w", err, fallbackErr)
 		}
 		snapshot.OpenrestyStatus = protocol.OpenrestyStatusUnhealthy
 		snapshot.OpenrestyMessage = err.Error()

internal/apps/agent/sync/sync_helpers.go

@@ -0,0 +1,205 @@
+package sync
+
+import (
+	"context"
+	"log/slog"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/agent/nginx"
+	"github.com/Rain-kl/Wavelet/internal/apps/agent/protocol"
+	"github.com/Rain-kl/Wavelet/internal/apps/agent/state"
+)
+
+func syncMode(startup bool) string {
+	if startup {
+		return "startup"
+	}
+	return "periodic"
+}
+
+func normalizeSyncTarget(target *protocol.ActiveConfigMeta) {
+	if target == nil {
+		return
+	}
+	target.Version = strings.TrimSpace(target.Version)
+	target.Checksum = strings.TrimSpace(target.Checksum)
+}
+
+func (s *Service) loadSyncState() (*state.Snapshot, string, error) {
+	snapshot, err := s.stateStore.Load()
+	if err != nil {
+		return nil, "", err
+	}
+	currentChecksum, err := s.nginxManager.CurrentChecksum()
+	if err != nil {
+		return nil, "", err
+	}
+	return snapshot, currentChecksum, nil
+}
+
+func (s *Service) syncWithoutTarget(ctx context.Context, mode string, startup bool, snapshot *state.Snapshot, currentChecksum string) error {
+	if !startup {
+		slog.Debug("skipping sync because heartbeat returned no active config summary", "mode", mode)
+		return nil
+	}
+	slog.Debug("sync startup fallback: active config summary unavailable, fetching active config directly")
+	config, fetchErr := s.client.GetActiveConfig(ctx)
+	if fetchErr != nil {
+		slog.Error("fetch active config failed", "mode", mode, "error", fetchErr)
+		return fetchErr
+	}
+	target := &protocol.ActiveConfigMeta{
+		Version:  config.Version,
+		Checksum: config.Checksum,
+	}
+	return s.applyIfNeeded(ctx, mode, startup, snapshot, currentChecksum, target, config)
+}
+
+func (s *Service) syncMatchingChecksum(ctx context.Context, mode string, startup bool, snapshot *state.Snapshot, currentChecksum string, target *protocol.ActiveConfigMeta) error {
+	if startup {
+		config, fetchErr := s.client.GetActiveConfig(ctx)
+		if fetchErr != nil {
+			slog.Error("fetch active config failed", "mode", mode, "error", fetchErr)
+			return fetchErr
+		}
+		return s.applyIfNeeded(ctx, mode, startup, snapshot, currentChecksum, target, config)
+	}
+	return s.finishUpToDateSync(ctx, mode, snapshot, target)
+}
+
+func (s *Service) finishUpToDateSync(ctx context.Context, mode string, snapshot *state.Snapshot, target *protocol.ActiveConfigMeta) error {
+	slog.Debug("local openresty config already up to date", "mode", mode, "version", target.Version)
+	if shouldReportNoopApply(snapshot, target.Version, target.Checksum) {
+		if err := s.reportNoopApply(ctx, snapshot.NodeID, target.Version, target.Checksum, "", "", 0); err != nil {
+			return err
+		}
+	}
+	snapshot.CurrentVersion = target.Version
+	snapshot.CurrentChecksum = target.Checksum
+	clearBlockedTarget(snapshot)
+	snapshot.LastError = ""
+	slog.Debug("sync finished without changes", "mode", mode, "version", target.Version)
+	return s.stateStore.Save(snapshot)
+}
+
+func (s *Service) syncMismatchedChecksum(ctx context.Context, mode string, startup bool, snapshot *state.Snapshot, currentChecksum string, target *protocol.ActiveConfigMeta) error {
+	if isBlockedTarget(snapshot, target.Version, target.Checksum) {
+		slog.Warn("skipping blocked config version after previous failed apply", "mode", mode, "version", target.Version, "checksum", target.Checksum)
+		if startup {
+			if err := s.ensureRuntimeForCurrentConfig(ctx, mode, snapshot, currentChecksum); err != nil {
+				return err
+			}
+			return s.stateStore.Save(snapshot)
+		}
+		return nil
+	}
+	if hasBlockedTarget(snapshot) {
+		clearBlockedTarget(snapshot)
+	}
+	if snapshot.CurrentVersion == target.Version && snapshot.CurrentChecksum == target.Checksum && !startup {
+		slog.Debug("skipping config fetch because state already records target version/checksum", "version", target.Version, "checksum", target.Checksum)
+		return s.stateStore.Save(snapshot)
+	}
+
+	config, err := s.client.GetActiveConfig(ctx)
+	if err != nil {
+		slog.Error("fetch active config failed", "mode", mode, "error", err)
+		return err
+	}
+	return s.applyIfNeeded(ctx, mode, startup, snapshot, currentChecksum, target, config)
+}
+
+func (s *Service) handleUpToDateConfig(ctx context.Context, mode string, snapshot *state.Snapshot, config *protocol.ActiveConfigResponse) error {
+	slog.Debug("local openresty config already up to date", "mode", mode, "version", config.Version)
+	if shouldReportNoopApply(snapshot, config.Version, config.Checksum) {
+		rendered, renderErr := renderActiveConfig(config)
+		if renderErr != nil {
+			return renderErr
+		}
+		if err := s.reportNoopApply(
+			ctx,
+			snapshot.NodeID,
+			config.Version,
+			config.Checksum,
+			checksumString(rendered.mainConfig),
+			checksumString(rendered.routeConfig),
+			len(rendered.supportFiles),
+		); err != nil {
+			return err
+		}
+	}
+	snapshot.CurrentVersion = config.Version
+	snapshot.CurrentChecksum = config.Checksum
+	clearBlockedTarget(snapshot)
+	snapshot.LastError = ""
+	slog.Debug("sync finished without changes", "mode", mode, "version", config.Version)
+	return s.stateStore.Save(snapshot)
+}
+
+func (s *Service) handleBlockedConfigAfterFetch(ctx context.Context, mode string, startup bool, snapshot *state.Snapshot, currentChecksum string, config *protocol.ActiveConfigResponse) (bool, error) {
+	if !isBlockedTarget(snapshot, config.Version, config.Checksum) {
+		return false, nil
+	}
+	slog.Warn("skipping blocked config after fetch because the same version previously failed", "mode", mode, "version", config.Version, "checksum", config.Checksum)
+	if startup {
+		if err := s.ensureRuntimeForCurrentConfig(ctx, mode, snapshot, currentChecksum); err != nil {
+			return true, err
+		}
+		return true, s.stateStore.Save(snapshot)
+	}
+	return true, nil
+}
+
+type applyOutcomeResult struct {
+	reportResult string
+	message      string
+}
+
+func normalizeApplyOutcome(outcome nginx.ApplyOutcome) (nginx.ApplyOutcome, string) {
+	message := strings.TrimSpace(outcome.Message)
+	if outcome.Status == "" {
+		outcome.Status = nginx.ApplyStatusFatal
+		if message == "" {
+			message = "openresty apply returned empty outcome"
+		}
+	}
+	return outcome, message
+}
+
+func updateSnapshotFromApplyOutcome(mode string, snapshot *state.Snapshot, config *protocol.ActiveConfigResponse, outcome nginx.ApplyOutcome, message string) applyOutcomeResult {
+	result := applyOutcomeResult{reportResult: ApplyResultFailed, message: message}
+	switch outcome.Status {
+	case nginx.ApplyStatusSuccess:
+		slog.Info("openresty config applied successfully", "mode", mode, "version", config.Version)
+		snapshot.CurrentVersion = config.Version
+		snapshot.CurrentChecksum = config.Checksum
+		clearBlockedTarget(snapshot)
+		snapshot.LastError = ""
+		snapshot.OpenrestyStatus = protocol.OpenrestyStatusHealthy
+		snapshot.OpenrestyMessage = ""
+		result.reportResult = ApplyResultSuccess
+		if result.message == "" {
+			result.message = "apply success"
+		}
+	case nginx.ApplyStatusWarning:
+		if result.message == "" {
+			result.message = "apply rolled back to previous config"
+		}
+		slog.Warn("openresty config apply rolled back", "mode", mode, "version", config.Version, "message", result.message)
+		markBlockedTarget(snapshot, config.Version, config.Checksum, result.message)
+		snapshot.LastError = result.message
+		snapshot.OpenrestyStatus = protocol.OpenrestyStatusHealthy
+		snapshot.OpenrestyMessage = result.message
+		result.reportResult = ApplyResultWarning
+	default:
+		if result.message == "" {
+			result.message = "openresty apply failed"
+		}
+		slog.Error("apply openresty config failed", "mode", mode, "version", config.Version, "message", result.message)
+		markBlockedTarget(snapshot, config.Version, config.Checksum, result.message)
+		snapshot.LastError = result.message
+		snapshot.OpenrestyStatus = protocol.OpenrestyStatusUnhealthy
+		snapshot.OpenrestyMessage = result.message
+	}
+	return result
+}