restore

package
v1.16.3 Latest Latest
Warning

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

Go to latest
Published: Feb 22, 2026 License: GPL-3.0 Imports: 10 Imported by: 0

Documentation

Overview

Package restore implements the 5-phase GitLab project restore workflow.

The restore process consists of:

  1. Validation - Verify target project is empty (unless --overwrite)
  2. Download - Fetch archive from S3 if needed
  3. Extraction - Extract and validate archive contents
  4. Import - Import project via GitLab Import/Export API
  5. Cleanup - Remove temporary files

The package provides:

  • Orchestrator: Main restore workflow coordination
  • Validator: Project emptiness validation
  • ProgressReporter: Console progress reporting

Architecture:

Orchestrator
    ├─> Validator (GitLab API)
    ├─> Storage (Local/S3)
    ├─> GitLabClient (Import API)
    └─> ProgressReporter (Console)

Example usage:

orchestrator := restore.NewOrchestrator(gitlabSvc, storage, cfg)
result, err := orchestrator.Restore(ctx, cfg)
if err != nil {
    log.Fatal(err)
}

Index

Constants

This section is empty.

Variables

View Source
var ErrProjectHasContent = errors.New("project is not empty - use --overwrite to skip validation")

ErrProjectHasContent is returned when project is not empty (has commits, issues, or labels).

Functions

This section is empty.

Types

type ConsoleProgressReporter

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

ConsoleProgressReporter implements ProgressReporter with console output.

func NewConsoleProgressReporter

func NewConsoleProgressReporter(logger *slog.Logger) *ConsoleProgressReporter

NewConsoleProgressReporter creates a new console progress reporter.

func (*ConsoleProgressReporter) CompletePhase

func (r *ConsoleProgressReporter) CompletePhase(phase Phase)

CompletePhase logs successful phase completion.

func (*ConsoleProgressReporter) FailPhase

func (r *ConsoleProgressReporter) FailPhase(phase Phase, err error)

FailPhase logs phase failure.

func (*ConsoleProgressReporter) SkipPhase

func (r *ConsoleProgressReporter) SkipPhase(phase Phase, reason string)

SkipPhase logs that a phase was skipped.

func (*ConsoleProgressReporter) StartPhase

func (r *ConsoleProgressReporter) StartPhase(phase Phase)

StartPhase logs the start of a restore phase.

func (*ConsoleProgressReporter) UpdatePhase

func (r *ConsoleProgressReporter) UpdatePhase(phase Phase, current, total int)

UpdatePhase logs mid-phase progress.

type EmptinessChecks

type EmptinessChecks struct {
	// HasCommits indicates whether project has any commits.
	HasCommits bool
	// HasIssues indicates whether project has any issues.
	HasIssues bool
	// HasLabels indicates whether project has any labels.
	HasLabels bool
	// CommitCount is the number of commits found.
	CommitCount int
	// IssueCount is the number of issues found.
	IssueCount int
	// LabelCount is the number of labels found.
	LabelCount int
}

EmptinessChecks tracks the three-part emptiness validation.

func (*EmptinessChecks) IsEmpty

func (e *EmptinessChecks) IsEmpty() bool

IsEmpty returns true if the project has no commits, issues, or labels.

type Error

type Error struct {
	// Phase indicates which phase the error occurred in.
	Phase Phase
	// Component identifies the component that failed (e.g., "import", "labels", "issues").
	Component string
	// Message is the error message.
	Message string
	// Fatal indicates whether the error is fatal (stops restore).
	Fatal bool
	// Timestamp is when the error occurred.
	Timestamp time.Time
}

Error represents an error that occurred during restore.

type Metrics

type Metrics struct {
	// BytesDownloaded is the bytes downloaded from S3 (if applicable).
	BytesDownloaded int64
	// BytesExtracted is the bytes extracted from archive.
	BytesExtracted int64
	// DurationSeconds is the total restore duration in seconds.
	DurationSeconds int64
}

Metrics tracks quantitative restore operation metrics.

type NoOpProgressReporter

type NoOpProgressReporter struct{}

NoOpProgressReporter is a progress reporter that does nothing. Useful for testing or when progress reporting is not desired.

func NewNoOpProgressReporter

func NewNoOpProgressReporter() *NoOpProgressReporter

NewNoOpProgressReporter creates a new no-op progress reporter.

func (*NoOpProgressReporter) CompletePhase

func (r *NoOpProgressReporter) CompletePhase(_ Phase)

CompletePhase does nothing.

func (*NoOpProgressReporter) FailPhase

func (r *NoOpProgressReporter) FailPhase(_ Phase, _ error)

FailPhase does nothing.

func (*NoOpProgressReporter) SkipPhase

func (r *NoOpProgressReporter) SkipPhase(_ Phase, _ string)

SkipPhase does nothing.

func (*NoOpProgressReporter) StartPhase

func (r *NoOpProgressReporter) StartPhase(_ Phase)

StartPhase does nothing.

func (*NoOpProgressReporter) UpdatePhase

func (r *NoOpProgressReporter) UpdatePhase(_ Phase, _, _ int)

UpdatePhase does nothing.

type Orchestrator

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

Orchestrator coordinates the restore workflow across all phases.

func NewOrchestrator

func NewOrchestrator(gitlabClient gitlab.GitLabService, storage Storage, cfg *config.Config) *Orchestrator

NewOrchestrator creates a new restore orchestrator.

func (*Orchestrator) Restore

func (o *Orchestrator) Restore(ctx context.Context, cfg *config.Config) (*Result, error)

Restore executes the complete 5-phase restore workflow. It orchestrates validation, download, extraction, and import.

Returns Result with success status, metrics, and any errors encountered. Fatal errors stop the workflow; non-fatal errors are collected but allow continuation.

type Phase

type Phase string

Phase represents the current phase of the restore operation.

const (
	// PhaseValidation validates configuration and target project emptiness.
	PhaseValidation Phase = "validation"
	// PhaseDownload downloads archive from S3 (if applicable).
	PhaseDownload Phase = "download"
	// PhaseExtraction extracts archive contents to temporary directory.
	PhaseExtraction Phase = "extraction"
	// PhaseImport imports the GitLab project repository.
	PhaseImport Phase = "import"
	// PhaseCleanup removes temporary files.
	PhaseCleanup Phase = "cleanup"
	// PhaseComplete indicates successful completion.
	PhaseComplete Phase = "complete"
)

type Progress

type Progress struct {
	// CurrentPhase is the active phase.
	CurrentPhase Phase
	// CompletedPhases contains successfully completed phases.
	CompletedPhases []Phase
	// StartTime is the restore start timestamp.
	StartTime time.Time
	// PhaseStartTime is the current phase start timestamp.
	PhaseStartTime time.Time
	// Metrics contains current progress metrics.
	Metrics Metrics
}

Progress tracks restore operation progress.

type ProgressReporter

type ProgressReporter interface {
	// StartPhase signals the beginning of a phase.
	StartPhase(phase Phase)

	// UpdatePhase provides mid-phase progress (e.g., "5/10 issues restored").
	UpdatePhase(phase Phase, current, total int)

	// CompletePhase signals successful phase completion.
	CompletePhase(phase Phase)

	// FailPhase signals phase failure.
	FailPhase(phase Phase, err error)

	// SkipPhase signals that a phase was skipped.
	SkipPhase(phase Phase, reason string)
}

ProgressReporter provides user-visible progress reporting for restore operations.

type Result

type Result struct {
	// Success indicates whether the restore completed successfully.
	Success bool
	// ProjectID is the ID of the restored project.
	ProjectID int64
	// ProjectURL is the web URL of the restored project.
	ProjectURL string
	// Metrics contains quantitative restore metrics.
	Metrics Metrics
	// Errors contains all errors encountered during restore.
	Errors []Error
	// Warnings contains non-fatal warnings.
	Warnings []string
}

Result represents the final outcome of a restore operation.

type Storage

type Storage interface {
	// Get retrieves a file from storage and returns the local path.
	Get(ctx context.Context, key string) (string, error)
}

Storage interface defines the storage operations needed for restore.

type Validator

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

Validator provides project emptiness validation functionality.

func NewValidator

func NewValidator(
	commitsService gitlab.CommitsService,
	issuesService gitlab.IssuesService,
	labelsService gitlab.LabelsService,
) *Validator

NewValidator creates a new Validator instance.

func (*Validator) ValidateProjectEmpty

func (v *Validator) ValidateProjectEmpty(ctx context.Context, projectID int64) (*EmptinessChecks, error)

ValidateProjectEmpty checks if a GitLab project is empty (no commits, issues, or labels). It returns EmptinessChecks with detailed information about what exists in the project. This is used to ensure a project is empty before restore to avoid overwriting data. The context is propagated to GitLab API calls and allows for cancellation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL