taskgraph

type BackedUpFramework interface {
	// Ask framework to do update on this update on this task, which consists
	// of one primary and some backup copies.
	Update(taskID uint64, log UpdateLog)
}

type Backupable interface {
	// Some hooks that need for master slave etc.
	BecamePrimary()
	BecameBackup()

	// Framework notify this copy to update. This should be the only way that
	// one update the state of copy.
	Update(log UpdateLog)
}

type Bootstrap interface {
	// These allow application developer to set the task configuration so framework
	// implementation knows which task to invoke at each node.
	SetTaskBuilder(taskBuilder TaskBuilder)

	// This allow user add their own link type of Topology into framework topology
	AddLinkage(linkType string, topology Topology)

	// After all the configure is done, driver need to call start so that all
	// nodes will get into the event loop to run the application.
	Start()
}

type Bootup interface {
	// Blocking call to run the task until it finishes.
	Start()
}

type Datum interface{}

type DatumIterator interface {
	HasNext() bool
	Next() Datum
}

type DatumIteratorBuilder interface {
	Build(path string) DatumIterator
}

type DatumStore struct {
	Cache []Datum
}

type DatumTransformer interface {
	Transform(old Datum) Datum
}

type Framework interface {
	// This allow the task implementation query its neighbors.
	GetTopology() map[string]Topology

	// Kill the framework itself.
	// As epoch changes, some nodes isn't needed anymore
	Kill()

	// Some task can inform all participating tasks to shutdown.
	// If successful, all tasks will be gracefully shutdown.
	// TODO: @param status
	ShutdownJob()

	GetLogger() *log.Logger

	// This is used to figure out taskid for current node
	GetTaskID() uint64

	// This is useful for task to inform the framework their status change.
	// metaData has to be really small, since it might be stored in etcd.
	// Set meta flag to notify meta to all nodes of linkType to this node.
	FlagMeta(ctx context.Context, linkType, meta string)

	// Some task can inform all participating tasks to new epoch
	IncEpoch(ctx context.Context)

	// Request data from task toID with specified linkType and meta.
	DataRequest(ctx context.Context, toID uint64, method string, input proto.Message)
	CheckGRPCContext(ctx context.Context) error
}

type GRPCHandlerInterceptor interface {
	// Currently grpc doesn't support interceptor functionality. We need to rely on user
	// to call this at handler implementation.
	// The workflow would be
	//   C:Notify -> S:Intercept -> S:OnNotify
	Intercept(ctx context.Context, method string, input proto.Message) (proto.Message, error)
}

type GRPCHelper interface {
	CreateOutputMessage(methodName string) proto.Message
	CreateServer() *grpc.Server
}

type MasterFrame interface {
	// User can use this interface to simplify sending the messages to worker. By keeping
	// track of workers' states, user can make decisions on logical worker and communicate it
	// using proto messages.
	NotifyWorker(ctx context.Context, workerID uint64, method string, input proto.Message) (proto.Message, error)
	GRPCHandlerInterceptor
}

type MasterTask interface {
	Setup(framework MasterFrame)
	Run(ctx context.Context)

	// Corresponds to NotifyMaster
	OnNotify(ctx context.Context, workerID uint64, method string, input proto.Message) (proto.Message, error)
	GRPCHelper
}

type Node interface {
	// return the ID of this node
	ID() uint64
	// return the task this node associated to
	TaskID() uint64
	// return the status of this node
	// possible status: no associated to any task
	//                  master of a task
	//                  slave of a task
	Status() uint64
	// return a connection string of this node
	// scheme://host:port
	Connection() string
}

type Task interface {
	// This is useful to bring the task up to speed from scratch or if it recovers.
	Init(taskID uint64, framework Framework)

	// Task is finished up for exit. Last chance to save some task specific work.
	Exit()

	// Framework tells user task what current epoch is.
	// This give the task an opportunity to cleanup and regroup.
	EnterEpoch(ctx context.Context, epoch uint64)

	// The meta/data notifications obey exactly-once semantics. Note that the same
	// meta string will be notified only once even if you flag the meta more than once.
	// TODO: one can also get this from channel.
	MetaReady(ctx context.Context, fromID uint64, linkType, meta string)

	// This is the callback when data from server is ready.
	DataReady(ctx context.Context, fromID uint64, method string, output proto.Message)

	CreateOutputMessage(methodName string) proto.Message
	CreateServer() *grpc.Server
}

type TaskBuilder interface {
	// This method is called once by framework implementation to get the
	// right task implementation for given node/task.
	GetTask(taskID uint64) Task
}

type Topology interface {
	// This method is called once by framework implementation. So that
	// we can get the local topology for each epoch later.
	SetTaskID(taskID uint64)

	// This returns the neighbors of given link for this node at this epoch.
	GetNeighbors(epoch uint64) []uint64
}

type UpdateLog interface {
	UpdateID()
}

type WorkerFrame interface {
	// It usually send states, etc. information to master in order to get further decision.
	NotifyMaster(ctx context.Context, method string, input proto.Message) (proto.Message, error)
	// Worker-worker data flow
	DataRequest(ctx context.Context, workerID uint64, method string, input proto.Message) (proto.Message, error)
	GRPCHandlerInterceptor
}

type WorkerTask interface {
	Setup(framework WorkerFrame, workerID uint64)
	Run(ctx context.Context)

	// Corresponds to NotifyWorker
	OnNotify(ctx context.Context, method string, input proto.Message) (proto.Message, error)
	// Corresponds to DataRequest
	ServeData(ctx context.Context, workerID uint64, method string, input proto.Message) (proto.Message, error)
	GRPCHelper
}