bufsync

type ErrorHandler interface {
	// InvalidModuleConfig is invoked by Syncer upon encountering a module
	// with an invalid module config.
	//
	// Returning an error will abort sync.
	InvalidModuleConfig(
		module Module,
		commit git.Commit,
		err error,
	) error
	// BuildFailure is invoked by Syncer upon encountering a module that fails
	// build.
	//
	// Returning an error will abort sync.
	BuildFailure(
		module Module,
		commit git.Commit,
		err error,
	) error
	// InvalidSyncPoint is invoked by Syncer upon encountering a module's branch
	// sync point that is invalid. A typical example is either a sync point that
	// point to a commit that cannot be found anymore, or the commit itself has
	// been corrupted.
	//
	// Returning an error will abort sync.
	InvalidSyncPoint(
		module Module,
		branch string,
		syncPoint git.Hash,
		err error,
	) error
}

type Module interface {
	// Dir is the path to the module relative to the repository root.
	Dir() string
	// RemoteIdentity is the identity of the remote module that the
	// local module is synced to.
	RemoteIdentity() bufmoduleref.ModuleIdentity
	// String is the string representation of this module.
	String() string
}

type ModuleCommit interface {
	// Identity is the identity of the module, accounting for any configured override.
	Identity() bufmoduleref.ModuleIdentity
	// Bucket is the bucket for the module.
	Bucket() storage.ReadBucket
	// Commit is the commit that the module is sourced from.
	Commit() git.Commit
	// Branch is the git branch that this module is sourced from.
	Branch() string
	// Tags are the git tags associated with Commit.
	Tags() []string
}

type ModuleDefaultBranchGetter func(
	ctx context.Context,
	module bufmoduleref.ModuleIdentity,
) (string, error)

type SyncFunc func(ctx context.Context, commit ModuleCommit) error

type SyncPointResolver func(
	ctx context.Context,
	module bufmoduleref.ModuleIdentity,
	branch string,
) (git.Hash, error)

type SyncedGitCommitChecker func(
	ctx context.Context,
	module bufmoduleref.ModuleIdentity,
	commitHashes map[string]struct{},
) (map[string]struct{}, error)

type Syncer interface {
	// Sync syncs the repository using the provided SyncFunc. It processes
	// commits in reverse topological order, loads any configured named
	// modules, extracts any Git metadata for that commit, and invokes
	// SyncFunc with a ModuleCommit.
	//
	// Only commits/branches belonging to the remote named 'origin' are
	// processed. All tags are processed.
	Sync(context.Context, SyncFunc) error
}

type SyncerOption func(*syncer) error