sync

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 19, 2025 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package sync provides synchronization management interfaces and implementations for registry resources in the ToolHive Registry Server.

This package implements a clean separation of concerns by extracting all sync-related logic into dedicated interfaces and types:

Core Interfaces

  • Manager: Main interface for orchestrating sync operations (domain logic)
  • DataChangeDetector: Detects changes in source data using hash comparison
  • AutomaticSyncChecker: Manages time-based automatic sync scheduling

Coordinator Package

The sync/coordinator subpackage provides the orchestration layer that schedules and executes background sync operations. It handles ticker-based periodic syncs, status persistence, and lifecycle management. See pkg/sync/coordinator for details.

Result Types

  • Result: Contains the outcome of successful sync operations (hash, server count)
  • Error: Structured error type with Kubernetes condition information

Sync Decision Making

The Manager.ShouldSync method evaluates multiple factors to determine if a sync is needed, returning a decision (bool) and reason (string):

  • Registry state (failed, not ready, complete)
  • Filter configuration changes (via hash comparison)
  • Source data changes (via hash comparison)
  • Sync interval elapsed (time-based automatic sync)
  • Manual sync requests

The coordinator package (pkg/sync/coordinator) handles periodic sync scheduling using the configured sync interval from server configuration.

Sync Reasons

The package defines extensive reason constants to track why syncs occur or don't:

  • ReasonAlreadyInProgress: Sync already running
  • ReasonRegistryNotReady: Initial sync or recovery from failure
  • ReasonSourceDataChanged: Source data hash changed
  • ReasonFilterChanged: Filter configuration modified
  • ReasonManualWithChanges: Manual sync requested with detected changes
  • ReasonManualNoChanges: Manual sync requested but no changes detected
  • ReasonUpToDateWithPolicy: No sync needed, data is current
  • ReasonUpToDateNoPolicy: No sync needed, no automatic policy
  • ReasonErrorCheckingChanges: Error during change detection

Kubernetes Status Integration

The package defines condition types for Kubernetes status reporting:

  • ConditionSourceAvailable: Source is accessible
  • ConditionDataValid: Registry data passes validation
  • ConditionSyncSuccessful: Last sync operation succeeded
  • ConditionAPIReady: Registry API is ready to serve requests

The Error type includes condition information for automatic status updates:

  • ConditionType: Which condition to update
  • ConditionReason: Reason code for the condition
  • Message: Human-readable error message

Key Features

  • Hash-based change detection to avoid unnecessary syncs
  • Filter change detection via hash comparison
  • Manual sync support
  • Configurable sync intervals via server configuration
  • Comprehensive error handling with structured Error types
  • Detailed sync reason tracking for observability
  • Resource cleanup on deletion

Implementation

The package follows Go best practices by using interfaces for testability and dependency injection, while providing concrete struct implementations (DefaultSyncManager, DefaultDataChangeDetector, DefaultAutomaticSyncChecker) for actual functionality.

Index

Constants

View Source 
const (
	// Registry state related reasons
	ReasonAlreadyInProgress = "sync-already-in-progress"
	ReasonRegistryNotReady  = "registry-not-ready"

	// Filter change related reasons
	ReasonFilterChanged = "filter-changed"

	// Data change related reasons
	ReasonSourceDataChanged    = "source-data-changed"
	ReasonErrorCheckingChanges = "error-checking-data-changes"

	// Manual sync related reasons
	ReasonManualWithChanges = "manual-sync-with-data-changes"
	ReasonManualNoChanges   = "manual-sync-no-data-changes"

	// Automatic sync related reasons
	ReasonErrorParsingInterval  = "error-parsing-sync-interval"
	ReasonErrorCheckingSyncNeed = "error-checking-sync-need"

	// Up-to-date reasons
	ReasonUpToDateWithPolicy = "up-to-date-with-policy"
	ReasonUpToDateNoPolicy   = "up-to-date-no-policy"
)

Sync reason constants

View Source 
const (
	ManualSyncReasonNoAnnotations    = "no-annotations"
	ManualSyncReasonNoTrigger        = "no-manual-trigger"
	ManualSyncReasonAlreadyProcessed = "manual-trigger-already-processed"
	ManualSyncReasonRequested        = "manual-sync-requested"
)

Manual sync annotation detection reasons

View Source 
const (
	// ConditionSourceAvailable indicates whether the source is available and accessible
	ConditionSourceAvailable = "SourceAvailable"

	// ConditionDataValid indicates whether the registry data is valid
	ConditionDataValid = "DataValid"

	// ConditionSyncSuccessful indicates whether the last sync was successful
	ConditionSyncSuccessful = "SyncSuccessful"

	// ConditionAPIReady indicates whether the registry API is ready
	ConditionAPIReady = "APIReady"
)

Condition types for Config

Variables

This section is empty.

Functions

func IsManualSync 

func IsManualSync(reason string) bool

IsManualSync checks if the sync reason indicates a manual sync

Types

type AutomaticSyncChecker 

type AutomaticSyncChecker interface {
	// IsIntervalSyncNeeded checks if sync is needed based on time interval
	// Returns (syncNeeded, nextSyncTime, error) where nextSyncTime is always in the future
	IsIntervalSyncNeeded(cfg *config.Config, syncStatus *status.SyncStatus) (bool, time.Time, error)
}

AutomaticSyncChecker handles automatic sync timing logic

type DataChangeDetector 

type DataChangeDetector interface {
	// IsDataChanged checks if source data has changed by comparing hashes
	IsDataChanged(ctx context.Context, cfg *config.Config, syncStatus *status.SyncStatus) (bool, error)
}

DataChangeDetector detects changes in source data

type DefaultAutomaticSyncChecker 

type DefaultAutomaticSyncChecker struct{}

DefaultAutomaticSyncChecker implements AutomaticSyncChecker

func (*DefaultAutomaticSyncChecker) IsIntervalSyncNeeded 

func (*DefaultAutomaticSyncChecker) IsIntervalSyncNeeded(
	cfg *config.Config, syncStatus *status.SyncStatus,
) (bool, time.Time, error)

IsIntervalSyncNeeded checks if sync is needed based on time interval Returns: (syncNeeded, nextSyncTime, error) nextSyncTime is a future time when the next sync should occur, or zero time if no policy configured

type DefaultDataChangeDetector 

type DefaultDataChangeDetector struct {
	// contains filtered or unexported fields
}

DefaultDataChangeDetector implements DataChangeDetector

func (*DefaultDataChangeDetector) IsDataChanged 

func (d *DefaultDataChangeDetector) IsDataChanged(
	ctx context.Context, cfg *config.Config, syncStatus *status.SyncStatus,
) (bool, error)

IsDataChanged checks if source data has changed by comparing hashes

type DefaultSyncManager 

type DefaultSyncManager struct {
	// contains filtered or unexported fields
}

DefaultSyncManager is the default implementation of Manager

func NewDefaultSyncManager 

func NewDefaultSyncManager(
	sourceHandlerFactory sources.SourceHandlerFactory, storageManager sources.StorageManager) *DefaultSyncManager

NewDefaultSyncManager creates a new DefaultSyncManager

func (*DefaultSyncManager) Delete 

func (s *DefaultSyncManager) Delete(ctx context.Context, cfg *config.Config) error

Delete cleans up storage resources for the Registry

func (*DefaultSyncManager) PerformSync 

func (s *DefaultSyncManager) PerformSync(
	ctx context.Context, cfg *config.Config,
) (*Result, *Error)

PerformSync performs the complete sync operation for the Registry Returns sync result on success, or error on failure

func (*DefaultSyncManager) ShouldSync 

func (s *DefaultSyncManager) ShouldSync(
	ctx context.Context,
	cfg *config.Config,
	syncStatus *status.SyncStatus,
	manualSyncRequested bool,
) (bool, string, *time.Time)

ShouldSync determines if a sync operation is needed Returns: (shouldSync bool, reason string, nextSyncTime *time.Time) nextSyncTime is always nil - timing is controlled by the configured sync interval

type Error 

type Error struct {
	Err             error
	Message         string
	ConditionType   string
	ConditionReason string
}

Error represents a structured error with condition information for operator components

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type Manager 

type Manager interface {
	// ShouldSync determines if a sync operation is needed
	ShouldSync(
		ctx context.Context, cfg *config.Config, syncStatus *status.SyncStatus, manualSyncRequested bool,
	) (bool, string, *time.Time)

	// PerformSync executes the complete sync operation
	PerformSync(ctx context.Context, cfg *config.Config) (*Result, *Error)

	// Delete cleans up storage resources for the Registry
	Delete(ctx context.Context, cfg *config.Config) error
}

Manager manages synchronization operations for Registry resources

type Result 

type Result struct {
	Hash        string
	ServerCount int
}

Result contains the result of a successful sync operation

Source Files

View all Source files

Directories

Path Synopsis
Package coordinator provides background synchronization coordination for registry resources.
 Package coordinator provides background synchronization coordination for registry resources.
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.