sync

func (*GitClient) Clone ¶

func (g *GitClient) Clone(ctx context.Context, url, path, branch string, auth *AuthConfig) error

Clone clones a Git repository to a local path.

The clone operation:

1. Removes existing directory if present (fresh clone)
2. Performs shallow clone with --depth 1 (faster, smaller)
3. Checks out specified branch (or default branch)
4. Applies authentication if provided

Authentication is applied via:

• SSH: GIT_SSH_COMMAND with temporary key file
• Token: Injected into URL (https://token@github.com/...)
• Basic: Username:password in URL

Parameters:

• ctx: Context for cancellation and timeout
• url: Git repository URL (HTTPS or SSH)
• path: Local filesystem path for clone
• branch: Branch name to checkout (empty for default)
• auth: Authentication configuration (nil for public repos)

Returns an error if:

• Directory removal fails
• Git clone command fails
• Authentication is invalid

Example:

auth := &AuthConfig{Type: "token", Secret: "ghp_xxxxx"}
err := client.Clone(ctx, "https://github.com/user/repo", "/tmp/repo", "main", auth)

func (*GitClient) GetCommitHash ¶

func (g *GitClient) GetCommitHash(ctx context.Context, path string) (string, error)

GetCommitHash returns the current commit hash of a repository.

This retrieves the full SHA-1 hash of the current HEAD commit. The hash can be used to:

• Track which version of a repository was synced
• Detect when updates are available
• Record sync history in database

Parameters:

• ctx: Context for cancellation and timeout
• path: Local repository path

Returns:

• Full SHA-1 commit hash (40 characters)
• Error if repository is invalid or git command fails

Example:

hash, err := client.GetCommitHash(ctx, "/tmp/repo")
// hash = "7092ff4a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q"

func (*GitClient) Pull ¶

func (g *GitClient) Pull(ctx context.Context, path, branch string, auth *AuthConfig) error

Pull pulls the latest changes from a Git repository.

The pull operation:

1. Fetches latest changes from origin
2. Hard resets to origin/branch (discards local changes)
3. Cleans untracked files (git clean -fd)

This is a destructive operation that:

• Discards any local modifications
• Removes untracked files
• Ensures repository matches remote exactly

This behavior is intentional for repository sync, where the remote is the source of truth and local changes should never occur.

Parameters:

• ctx: Context for cancellation and timeout
• path: Local repository path
• branch: Branch name to reset to (empty for "main")
• auth: Authentication configuration (nil for public repos)

Returns an error if:

• Fetch fails (network issues, auth problems)
• Reset fails (branch doesn't exist)
• Clean fails (permission issues)

Example:

err := client.Pull(ctx, "/tmp/repo", "main", auth)

func (*GitClient) Validate ¶

func (g *GitClient) Validate() error

Validate validates that Git is installed and accessible.

This check should be performed on service startup to fail fast if Git is not available, rather than failing later during sync operations.

Validation steps:

1. Execute "git --version" command
2. Verify command succeeds (exit code 0)
3. Verify output contains "git version"

Returns an error if:

• Git command not found (not installed or not in PATH)
• Git command fails to execute
• Output doesn't match expected format

Example:

client := NewGitClient()
if err := client.Validate(); err != nil {
    log.Fatal("Git is not available:", err)
}

func (*PluginParser) ParsePluginFile ¶

func (p *PluginParser) ParsePluginFile(filePath string) (*ParsedPlugin, error)

ParsePluginFile parses a single plugin manifest.json file.

Parsing steps:

1. Read file from disk
2. Unmarshal JSON into PluginManifest struct
3. Validate required fields (name, version, displayName, type)
4. Validate plugin type is one of: extension, webhook, api, ui, theme
5. Convert manifest to JSON for database storage

Required fields:

• name: Unique plugin identifier
• version: Semantic version
• displayName: Human-readable name
• type: Plugin architecture type

Plugin type validation:

• "extension": General-purpose extension (most common)
• "webhook": Responds to webhook events
• "api": Adds new API endpoints
• "ui": Adds UI components or pages
• "theme": Visual theme customization

Parameters:

• filePath: Absolute path to manifest.json file

Returns:

• ParsedPlugin with extracted metadata
• Error if file cannot be read, parsed, or validated

Example:

plugin, err := parser.ParsePluginFile("/tmp/repo/analytics/manifest.json")
if err != nil {
    log.Printf("Invalid plugin: %v", err)
    return nil, err
}
fmt.Printf("Parsed: %s v%s\n", plugin.DisplayName, plugin.Version)

func (*PluginParser) ParseRepository ¶

func (p *PluginParser) ParseRepository(repoPath string) ([]*ParsedPlugin, error)

ParseRepository parses all plugin manifests in a Git repository.

Discovery process:

1. Walk all directories in repository
2. Find files named "manifest.json"
3. Parse JSON and validate structure
4. Extract metadata and validate required fields
5. Skip invalid files (continue processing others)

Behavior:

• Skips .git directory (performance)
• Only processes files named exactly "manifest.json"
• Logs parse errors but continues (partial success)
• Returns all successfully parsed plugins

Parameters:

• repoPath: Local filesystem path to Git repository

Returns:

• Array of parsed plugins (may be empty)
• Error only if directory walk fails (not for individual parse errors)

Example:

parser := NewPluginParser()
plugins, err := parser.ParseRepository("/tmp/streamspace-plugins")
if err != nil {
    log.Fatal("Failed to walk repository:", err)
}
log.Printf("Found %d plugins", len(plugins))

func (*PluginParser) ValidatePluginManifest ¶

func (p *PluginParser) ValidatePluginManifest(jsonContent string) error

ValidatePluginManifest validates a plugin manifest structure

func (*SyncService) StartScheduledSync ¶

func (s *SyncService) StartScheduledSync(ctx context.Context, interval time.Duration)

StartScheduledSync starts the scheduled sync loop

func (*SyncService) SyncAllRepositories ¶

func (s *SyncService) SyncAllRepositories(ctx context.Context) error

SyncAllRepositories synchronizes all enabled repositories.

This method:

1. Queries all repositories from database
2. Filters out repositories currently syncing
3. Syncs each repository sequentially
4. Logs success/failure counts

Behavior:

• Skips repositories with status="syncing" (avoid concurrent syncs)
• Continues on individual failures (doesn't abort entire sync)
• Returns nil even if some repositories fail
• Logs detailed results for each repository

Use cases:

• Manual "Sync All" button in admin UI
• Scheduled background sync (every hour)
• Initial platform setup

Performance:

• Sequential processing (one repo at a time)
• Can be slow with many large repositories
• Consider running in background goroutine

Example:

// Sync all repositories in background
go func() {
    err := syncService.SyncAllRepositories(context.Background())
    if err != nil {
        log.Printf("Sync all failed: %v", err)
    }
}()

func (*SyncService) SyncRepository ¶

func (s *SyncService) SyncRepository(ctx context.Context, repoID int) error

SyncRepository synchronizes a single repository.

The sync process:

1. Fetch repository details from database
2. Update status to "syncing"
3. Clone repository (if new) or pull latest changes
4. Parse template manifests (YAML files)
5. Parse plugin manifests (plugin.json files)
6. Update catalog database with parsed resources
7. Update repository status to "synced" or "failed"
8. Record sync timestamp and resource counts

Git operations:

• First sync: git clone <url> <work-dir>/repo-<id>
• Subsequent syncs: git pull in <work-dir>/repo-<id>
• Supports authentication (SSH keys, tokens)

Parsing:

• Templates: Searches for *.yaml files with template metadata
• Plugins: Searches for plugin.json manifest files
• Invalid manifests are logged but don't fail the sync

Database updates:

• Existing resources are updated (upsert)
• Missing resources are removed (cleanup)
• Transactions ensure consistency

Error handling:

• Git errors: Mark repository as "failed", log details
• Parse errors: Log warnings, continue with valid resources
• Database errors: Roll back transaction, return error

Parameters:

• ctx: Context for cancellation and timeouts
• repoID: Database ID of the repository to sync

Returns an error if:

• Repository not found in database
• Git clone/pull fails
• Catalog update fails

Example:

err := syncService.SyncRepository(ctx, 1)
if err != nil {
    log.Printf("Sync failed: %v", err)
}

func (*TemplateParser) ParseRepository ¶

func (p *TemplateParser) ParseRepository(repoPath string) ([]*ParsedTemplate, error)

ParseRepository parses all Template manifests in a Git repository.

Discovery process:

1. Walk all directories in repository
2. Find files with .yaml or .yml extension
3. Parse YAML and check if kind: Template
4. Extract metadata and validate
5. Skip invalid files (continue processing others)

Behavior:

• Skips .git directory (performance)
• Skips non-Template YAML files (no error)
• Logs parse errors but continues (partial success)
• Returns all successfully parsed templates

Parameters:

• repoPath: Local filesystem path to Git repository

Returns:

• Array of parsed templates (may be empty)
• Error only if directory walk fails (not for individual parse errors)

Example:

parser := NewTemplateParser()
templates, err := parser.ParseRepository("/tmp/streamspace-templates")
if err != nil {
    log.Fatal("Failed to walk repository:", err)
}
log.Printf("Found %d templates", len(templates))

func (*TemplateParser) ParseTemplateFile ¶

func (p *TemplateParser) ParseTemplateFile(filePath string) (*ParsedTemplate, error)

ParseTemplateFile parses a single Template YAML file.

Parsing steps:

1. Read file from disk
2. Unmarshal YAML into TemplateManifest struct
3. Validate kind == "Template"
4. Validate apiVersion == "stream.streamspace.io/v1alpha1"
5. Validate required fields (name, displayName, baseImage)
6. Infer appType from VNC/WebApp config if not specified
7. Convert manifest to JSON for database storage

App type inference:

• If spec.webapp.enabled: appType = "webapp"
• Otherwise: appType = "desktop" (VNC-based)

Parameters:

• filePath: Absolute path to YAML file

Returns:

• ParsedTemplate with extracted metadata
• Error if file cannot be read, parsed, or validated

Example:

template, err := parser.ParseTemplateFile("/tmp/repo/browsers/firefox.yaml")
if err != nil {
    log.Printf("Invalid template: %v", err)
    return nil, err
}
fmt.Printf("Parsed: %s\n", template.DisplayName)

func (*TemplateParser) ParseTemplateFromString ¶

func (p *TemplateParser) ParseTemplateFromString(yamlContent string) (*ParsedTemplate, error)

ParseTemplateFromString parses a template from a YAML string

func (*TemplateParser) ValidateTemplateManifest ¶

func (p *TemplateParser) ValidateTemplateManifest(yamlContent string) error

ValidateTemplateManifest validates a template manifest structure