distributor

type Config struct {
	// DMHost is the host for the DM API. This may be used by the distributor
	// implementation to pass to jobs so that they can call back into DM's api.
	DMHost string

	// Name is the name of this distributor configuration. This is always the
	// fully-resolved name of the configuration (i.e. aliases are dereferenced).
	Name string

	// Version is the version of the distributor configuration retrieved from
	// luci-config.
	Version string

	// Content is the actual parsed implementation-specific configuration.
	Content proto.Message
}

type D interface {
	// Run prepares and runs a new Task from the given parameters.
	//
	// Scheduling the same execution ID multiple times SHOULD return the same
	// Token. It's OK if this doesn't happen, but only one of the scheduled tasks
	// will be able to invoke ActivateExecution; the other one(s) will
	// early-abort and/or timeout.
	//
	// If this returns a non-Transient error, the Execution will be marked as
	// Rejected with the returned error message as the 'Reason'.
	//
	// The various time durations, if non-zero, will be used verbatim for DM to
	// timeout that phase of the task's execution. If the task's execution times
	// out in the 'STOPPING' phase, DM will poll the distributor's GetStatus
	// method up to 3 times with a 30-second gap to attempt to retrieve the final
	// information. After more than 3 times, DM will give up and mark the task as
	// expired.
	//
	// If the distributor doesn't intend to use Pubsub for notifying DM about the
	// final status of the job, set pollTimeout to the amount of time you want DM
	// to wait before polling GetStatus. e.g. if after calling FinishAttempt or
	// EnsureGraphData your distributor needs 10 seconds before it can correctly
	// respond to a GetStatus request, you should set pollTimeout to >= 10s.
	// Otherwise pollTimeout should be set fairly high (e.g. 12 hours) as a hedge
	// against a broken pubsub notification pipeline.
	//
	// If you have the choice between pubsub or not, prefer to use pubsub as it
	// allows DM to more proactively update the graph state (and unblock waiting
	// Attempts, etc.)
	Run(qst *dm.Quest_Desc, auth *dm.Execution_Auth, prevResult *dm.JsonResult) (tok Token, pollTimeout time.Duration, err error)

	// Cancel attempts to cancel a running task. If a task is canceled more than
	// once, this should return nil.
	Cancel(*dm.Quest_Desc, Token) error

	// GetStatus retrieves the current state of the task from the distributor.
	//
	// If this returns a non-Transient error more than 30 seconds after the task
	// was Run(), the execution will be marked Missing with the returned error
	// message as the 'Reason'. If it returns a non-Transient error within 30
	// seconds of being run, DM will automatically treat that as Transient.
	GetStatus(*dm.Quest_Desc, Token) (*dm.Result, error)

	// InfoURL calculates a user-presentable information url for the task
	// identified by Token. This should be a local operation, so it is not the
	// implementation's responsibility to validate the token in this method (e.g.
	// it could point to a non-existent job, etc.)
	InfoURL(Token) string

	// HandleNotification is called whenever DM receives a PubSub message sent to
	// a topic created with Config.PrepareTopic. The Attrs map will omit
	// the 'auth_token' field.
	//
	// Returning (nil, nil) will indicate that DM should ignore this notification.
	//
	// DM will convert pubsub Messages to a delayed GetStatus if a pubsub message
	// is delivered which refers to an Attempt whose status is NeedsExecution,
	// which could happen in the event of a not-fully-settled transacion.
	//
	// DM will ignore any notifications for executions which it doesn't know
	// about.
	HandleNotification(qst *dm.Quest_Desc, notification *Notification) (*dm.Result, error)

	// HandleTaskQueueTask is called if the distributor used Config.EnqueueTask.
	//
	// It may return zero or more Notifications for DM about arbitrary Executions.
	// These notifications will be handled 'later' by the HandleNotification
	// implementation.
	HandleTaskQueueTask(*http.Request) ([]*Notification, error)

	// Validate should return a non-nil error if the given distributor parameters
	// are not appropriate for this Distributor. Payload is guaranteed to be
	// a valid JSON object. This should validate that the content of that JSON
	// object is what the distributor expects.
	Validate(parameters string) error
}

type Factory func(c context.Context, dist *Config) (D, error)

type FactoryMap map[proto.Message]Factory

type FinishExecutionFn func(c context.Context, eid *dm.Execution_ID, rslt *dm.Result) ([]tumble.Mutation, error)

type Notification struct {
	ID    *dm.Execution_ID
	Data  []byte
	Attrs map[string]string
}

type NotifyExecution struct {
	CfgName      string
	Notification *Notification
}

type Registry interface {
	FinishExecution(c context.Context, eid *dm.Execution_ID, rslt *dm.Result) ([]tumble.Mutation, error)

	// MakeDistributor builds a distributor instance that's configured with the
	// provided config.
	//
	// The configuration for this distributor are obtained from luci-config at the
	// time an Execution is started.
	MakeDistributor(c context.Context, cfgName string) (d D, ver string, err error)
}

type TestFactoryFn func(context.Context, *Config) D

type TestFactoryMap map[string]TestFactoryFn

type Token string