updated package docs

Signed-off-by: Daniele Martinoli <[email protected]>

Author: dmartinol

pkg/git/doc.go

@@ -10,11 +10,12 @@
 // # Client Interface
 //
 // The Client interface defines the core Git operations:
-//   - Clone: Clone public repositories
-//   - Pull: Update existing repositories (planned for future implementation)
+//   - Clone: Clone public repositories to in-memory filesystem
 //   - GetFileContent: Retrieve specific files from repositories
-//   - GetCommitHash: Get current commit hash for change detection
-//   - Cleanup: Remove local repository directories
+//   - Cleanup: Clean up in-memory repository resources
+//
+// Repository information including commit hashes is tracked via the
+// RepositoryInfo struct which is populated during clone operations.
 //
 // # Example Usage
 //
@@ -39,23 +40,32 @@
 // # Security Considerations
 //
 // This package is designed to be used within a Kubernetes operator environment
-// where Git repositories contain MCP server registry data. Future versions will
-// include security hardening such as:
+// where Git repositories contain MCP server registry data. Security features include:
+//   - In-memory filesystem operations (no disk access)
+//   - Size limits on cloned repositories (max files and total size)
+//   - Shallow clones by default for efficiency
+//
+// Future security hardening may include:
 //   - Repository URL validation to prevent SSRF attacks
-//   - Sandboxed Git operations
-//   - Secure credential management via Kubernetes secrets
+//   - Additional resource limits and timeouts
+//   - Secure credential management via Kubernetes secrets for private repos
+//
+// # Implementation Details
 //
-// # Implementation Status
+// Current implementation uses:
+//   - In-memory filesystems (go-billy memfs) for all Git operations
+//   - LimitedFs wrapper to enforce size constraints (10k files, 100MB total)
+//   - Shallow clones (depth=1) for branch/tag checkouts
+//   - Full clones only when specific commits are requested
+//   - Explicit memory cleanup via Cleanup() method with GC hints
 //
-// Current implementation supports:
+// Supported features:
 //   - Public repository access via HTTPS
 //   - Branch, tag, and commit checkout
-//   - File content retrieval
-//   - Temporary directory management
+//   - File content retrieval from any path in the repository
 //
 // Planned features:
 //   - Authentication for private repositories
-//   - Repository caching for performance
 //   - Webhook support for immediate sync triggers
 //   - Git LFS support for large files
 package git

pkg/sources/doc.go

@@ -15,13 +15,12 @@
 // Current implementations:
 //   - ConfigMapSourceHandler: Retrieves registry data from Kubernetes ConfigMaps
 //     Supports both ToolHive and Upstream registry formats with format validation
+//   - GitSourceHandler: Retrieves registry data from Git repositories
+//     Supports public repos via HTTPS with branch/tag/commit checkout
+//   - APISourceHandler: Retrieves registry data from HTTP/HTTPS endpoints
+//     Delegates to format-specific handlers (ToolHiveAPIHandler, UpstreamAPIHandler)
 //   - ConfigMapStorageManager: Persists Registry data to Kubernetes ConfigMaps
 //
-// Future implementations may include:
-//   - URLSourceHandler: HTTP/HTTPS endpoints
-//   - GitSourceHandler: Git repositories
-//   - RegistrySourceHandler: External registries
-//
 // The package provides a factory pattern for creating appropriate
 // source handlers based on the source type configuration, and uses
 // strongly-typed Registry instances throughout for type safety.

pkg/sync/doc.go

@@ -2,20 +2,82 @@
 // for registry resources in the ToolHive Registry Server.
 //
 // This package implements a clean separation of concerns by extracting all
-// sync-related logic from the controller into dedicated interfaces:
+// sync-related logic from the controller into dedicated interfaces and types:
+//
+// # Core Interfaces
 //
 //   - Manager: Main interface for orchestrating sync operations
 //   - DataChangeDetector: Detects changes in source data using hash comparison
 //   - AutomaticSyncChecker: Manages time-based automatic sync scheduling
 //
-// The package follows Go best practices by using interfaces for testability
-// and dependency injection, while providing concrete struct implementations
-// for actual functionality.
+// # 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), reason (string), and next sync time:
+//
+//   - Registry state (failed, not ready, complete)
+//   - Filter configuration changes (via hash comparison)
+//   - Source data changes (via hash comparison)
+//   - Manual sync requests (via annotations)
+//   - Automatic sync intervals (time-based policies)
+//   - Requeue timing (minimum time between sync attempts)
+//
+// # 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, automatic policy active
+//   - ReasonUpToDateNoPolicy: No sync needed, no automatic policy
+//   - ReasonRequeueTimeNotElapsed: Too soon to retry after last attempt
+//   - 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
+//
+// # Timing Configuration
+//
+// Default timing constants control sync behavior:
+//
+//   - DefaultSyncRequeueAfter: Minimum time between sync attempts (5 minutes)
+//     This variable can be modified in tests for faster iteration
+//
+// # Key Features
 //
-// Key features:
 //   - Hash-based change detection to avoid unnecessary syncs
-//   - Manual sync support via annotations
+//   - Filter change detection via hash comparison
+//   - Manual sync support via Kubernetes annotations
 //   - Automatic sync scheduling with configurable intervals
-//   - Comprehensive error handling and status management
+//   - Comprehensive error handling with structured Error types
+//   - Detailed sync reason tracking for observability
 //   - Clean integration with Kubernetes controller patterns
+//   - Resource cleanup on Registry 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.
 package sync