handler

type CLUpdater interface {
	ScheduleBatch(ctx context.Context, luciProject string, cls []*changelist.CL, requester changelist.UpdateCLTask_Requester) error
}

type Handler interface {
	// Start starts a Run.
	Start(context.Context, *state.RunState) (*Result, error)

	// Cancel cancels a Run.
	Cancel(context.Context, *state.RunState, []string) (*Result, error)

	// OnCLsUpdated decides whether to cancel a Run based on changes to the CLs.
	OnCLsUpdated(context.Context, *state.RunState, common.CLIDs) (*Result, error)

	// UpdateConfig updates Run's config if possible.
	//
	// If Run is no longer viable, cancels the Run.
	UpdateConfig(context.Context, *state.RunState, string) (*Result, error)

	// OnReadyForSubmission acquires a slot in Submit Queue and makes sure this
	// Run is not currently being submitted by another RM task. If all succeeded,
	// returns a PostProcessFn for submission.
	OnReadyForSubmission(context.Context, *state.RunState) (*Result, error)

	// OnCLsSubmitted records provided CLs have been submitted.
	OnCLsSubmitted(context.Context, *state.RunState, common.CLIDs) (*Result, error)

	// OnSubmissionCompleted acts on the submission result.
	//
	// If submission succeeds, mark run as `SUCCEEDED`. Otherwise, decides whether
	// to retry submission or fail the run depending on the submission result.
	OnSubmissionCompleted(ctx context.Context, rs *state.RunState, sc *eventpb.SubmissionCompleted) (*Result, error)

	// OnLongOpCompleted processes results of the completed long operation.
	OnLongOpCompleted(ctx context.Context, rs *state.RunState, result *eventpb.LongOpCompleted) (*Result, error)

	// OnTryjobsUpdated decides the next step for the given tryjobs and the run.
	OnTryjobsUpdated(context.Context, *state.RunState, common.TryjobIDs) (*Result, error)

	// TryResumeSubmission resumes not-yet-expired submission if the current task
	// is a retry of the submission task.
	//
	// Fail the Run if the submission deadline has been exceeded.
	TryResumeSubmission(context.Context, *state.RunState) (*Result, error)

	// Poke checks current Run state and takes actions to progress the Run.
	Poke(context.Context, *state.RunState) (*Result, error)

	// OnParentRunCompleted checks decides how to handle the run based on its completed parent run.
	OnParentRunCompleted(context.Context, *state.RunState) (*Result, error)
}

type Impl struct {
	PM          PM
	RM          RM
	TN          TryjobNotifier
	QM          QM
	GFactory    gerrit.Factory
	CLUpdater   CLUpdater
	CLMutator   *changelist.Mutator
	BQExporter  *bq.Exporter
	RdbNotifier *rdb.Notifier
	TreeClient  tree.Client
	Publisher   *pubsub.Publisher
	Env         *common.Env
}

type PM interface {
	NotifyRunFinished(ctx context.Context, runID common.RunID, status run.Status) error
	NotifyCLsUpdated(ctx context.Context, luciProject string, cls *changelist.CLUpdatedEvents) error
}

type QM interface {
	DebitRunQuota(ctx context.Context, r *run.Run) (*quotapb.OpResult, *cfgpb.UserLimit, error)
}

type RM interface {
	Invoke(ctx context.Context, runID common.RunID, eta time.Time) error
	PokeAfter(ctx context.Context, runID common.RunID, after time.Duration) error
	NotifyReadyForSubmission(ctx context.Context, runID common.RunID, eta time.Time) error
	NotifyCLsSubmitted(ctx context.Context, runID common.RunID, clids common.CLIDs) error
	NotifySubmissionCompleted(ctx context.Context, runID common.RunID, sc *eventpb.SubmissionCompleted, invokeRM bool) error
	Start(ctx context.Context, runID common.RunID) error
	NotifyParentRunCompleted(ctx context.Context, runID common.RunID) error
}

type Result struct {
	// State is the new RunState after handling the events.
	State *state.RunState
	// SideEffectFn is called in a transaction to atomically transition the
	// RunState to the new state and perform side effect.
	SideEffectFn eventbox.SideEffectFn
	// PreserveEvents, if true, instructs RunManager not to consume the events
	// during state transition.
	PreserveEvents bool
	// PostProcessFn is executed by the eventbox user after event processing
	// completes.
	PostProcessFn eventbox.PostProcessFn
}

type TryjobNotifier interface {
	ScheduleUpdate(ctx context.Context, id common.TryjobID, eid tryjob.ExternalID) error
}