plugin

type AdmissionPlugin interface {
	// CheckAdmission enqueues an admission check to be performed by the plugin.
	//
	// The plugin will be asked if it's OK to deploy a package with the given pin
	// hosted on the CIPD service used by the running CIPD client.
	//
	// Returns a promise which is resolved when the result is available. If such
	// check is already pending (or has been done before), returns an existing
	// (perhaps already resolved) promise.
	CheckAdmission(pin common.Pin) Promise

	// ClearCache drops all resolved promises to free up some memory.
	ClearCache()

	// Close terminates the plugin (if it was running) and aborts all pending
	// checks.
	//
	// Tries to gracefully terminate the plugin, killing it with SIGKILL on the
	// context timeout or after 5 sec.
	//
	// Note that calling Close is not necessary if the plugin host itself
	// terminates. The plugin subprocess will be terminated by the host in this
	// case.
	Close(ctx context.Context)

	// Executable is a path to this plugin's executable.
	Executable() string
}

type Config struct {
	ServiceURL string           // URL of the CIPD repository ("https://...") used by the client
	Repository RepositoryClient // a subset of api.RepositoryClient available to plugins
}

type Host interface {
	// Initialize is called when the CIPD client starts before any other call.
	Initialize(cfg Config) error

	// Close is called when the CIPD client closes.
	Close(ctx context.Context)

	// NewAdmissionPlugin returns a handle to an admission plugin.
	//
	// The returned AdmissionPlugin can be used right away to enqueue admission
	// checks. The plugin subprocess will lazily be started on the first
	// CheckAdmission call. All enqueued checks will eventually be processed by
	// the plugin or rejected if the plugin fails to start.
	NewAdmissionPlugin(cmdLine []string) (AdmissionPlugin, error)
}

type Promise interface {
	// Wait blocks until the promise is fulfilled or the context expires.
	Wait(ctx context.Context) error
}

type RepositoryClient interface {
	// Lists metadata entries attached to an instance.
	ListMetadata(ctx context.Context, in *api.ListMetadataRequest, opts ...grpc.CallOption) (*api.ListMetadataResponse, error)
}