gapi

type Data struct {
	Program       string // name of the originating program
	Version       string // version of the originating program
	Hostname      string // uuid for the host, required for GAPI
	Local         *local.API
	World         engine.World
	Noop          bool
	NoStreamWatch bool
	Prefix        string
	Debug         bool
	Logf          func(format string, v ...interface{})
}

type Deploy struct {
	ID   uint64
	Name string // lang, puppet, yaml, etc...
	//Sync bool // wait for everyone to close previous GAPI before switching
	Noop bool
	Sema int // sema override

	NoAutoEdges bool

	GAPI GAPI
}

type Flags struct {
	Hostname *string

	Noop bool
	Sema int

	NoAutoEdges bool
}

type GAPI interface {
	// Cli is run on each GAPI to give it a chance to decide if it wants to
	// activate, and if it does, then it will return a deploy struct. During
	// this time, it uses the Info struct as useful information to decide
	// what to do.
	Cli(*Info) (*Deploy, error)

	// Init initializes the GAPI and passes in some useful data.
	Init(*Data) error

	// Info returns some data about the GAPI implementation.
	Info() *InfoResult

	// Next returns a stream of events. Each next event contains a resource
	// graph.
	Next(ctx context.Context) chan Next

	// Err will contain the last error when Next shuts down. It waits for
	// all the running processes to exit before it returns.
	Err() error
}

type Info struct {
	// Args are the CLI args that are populated after parsing the args list.
	// They need to be converted to the struct you are expecting to read it.
	Args interface{}

	// Flags are the common data which is passed down into the sub command.
	Flags *Flags

	// Fs is the filesystem the Cli method should copy data into. It usually
	// copies *from* the local filesystem using standard io functionality.
	Fs engine.Fs

	Debug bool
	Logf  func(format string, v ...interface{})
}

type InfoResult struct {
	// URI is the FS URI that we pass around everywhere.
	// TODO: can this be deprecated?
	URI string
}

type Next struct {
	// Graph returns the current resource graph.
	Graph *pgraph.Graph

	// FIXME: the Fast pause parameter should eventually get replaced with a
	// "SwitchMethod" parameter or similar that instead lets the implementer
	// choose between fast pause, slow pause, and interrupt. Interrupt could
	// be a future extension to the Resource API that lets an Interrupt() be
	// called if we want to exit immediately from the CheckApply part of the
	// resource for some reason. For now we'll keep this simple with a bool.
	Fast bool  // run a fast pause to switch?
	Exit bool  // should we cause the program to exit? (specify err or not)
	Err  error // if something goes wrong (use with or without exit!)
}