api

type Build struct {
	// Selectors specifies any source selection strings to be sent to the
	// builder. In the case of go builders, this field maps to build tags.
	Selectors []string `toml:"selectors" json:"selectors"`

	// Dependencies specifies any upstream dependency overrides to apply to this
	// build.
	Dependencies Dependencies `toml:"dependencies" json:"dependencies"`
}

type BuildInput struct {
	// BuildID is a unique ID for this build.
	BuildID string

	// EnvConfig is the env configuration of the engine. Not a pointer to force
	// a copy.
	EnvConfig config.EnvConfig

	// TestPlan is the name of the test plan being built.
	TestPlan string

	// UnpackedSources encapsulates the directories where sources for this
	// build job have been unpacked.
	UnpackedSources *UnpackedSources

	// Selectors specifies any source selection strings to be sent to the
	// builder. In the case of go builders, this field maps to build tags.
	Selectors []string

	// Dependencies are the versions and target of upstream dependencies we wants
	// to build against. For a go build, this could be e.g.:
	//  github.com/ipfs/go-ipfs=v0.4.22
	//  github.com/libp2p/go-libp2p=github.com/user/fork@v0.2.8
	Dependencies map[string]DependencyTarget

	// BuildConfig is the configuration of the build job sourced from the test
	// plan manifest, coalesced with any user-provided overrides.
	BuildConfig interface{}
}

type BuildOutput struct {
	// BuilderID is the ID of the builder used.
	BuilderID string

	// ArtifactPath can be the docker image ID, a file location, etc. of the
	// resulting artifact. It is builder-dependent.
	ArtifactPath string

	// Dependencies is a map of modules (as keys) to versions (as values),
	// containing the collapsed transitive upstream dependency set of this
	// build.
	Dependencies map[string]string
}

type BuildPurgeRequest struct {
	Builder  string `json:"builder"`
	Testplan string `json:"testplan"`
}

type BuildRequest struct {
	Priority    int              `json:"priority"`
	Composition Composition      `json:"composition"`
	Manifest    TestPlanManifest `json:"manifest"`
	CreatedBy   CreatedBy        `json:"created_by"`
}

type BuildResponse = []BuildOutput

type Builder interface {
	// ID returns the canonical identifier for this builder.
	ID() string

	// Build performs a build.
	Build(ctx context.Context, input *BuildInput, ow *rpc.OutputWriter) (*BuildOutput, error)

	// Purge frees resources, such as caches.
	Purge(ctx context.Context, testplan string, ow *rpc.OutputWriter) error

	// ConfigType returns the configuration type of this builder.
	ConfigType() reflect.Type
}

type CancelRequest struct {
	TaskID string `json:"task_id"`
}

type CollectResponse struct {
	File   bytes.Buffer
	Exists bool
}

type CollectionInput struct {
	// EnvConfig is the env configuration of the engine. Not a pointer to force
	// a copy.
	EnvConfig config.EnvConfig
	RunID     string
	RunnerID  string

	// RunnerConfig is the configuration of the runner sourced from the test
	// plan manifest, coalesced with any user-provided overrides.
	RunnerConfig interface{}
}

type ComponentType string

type Composition struct {
	// Metadata expresses optional metadata about this composition.
	Metadata Metadata `toml:"metadata" json:"metadata"`

	// Global defines the general parameters for this composition.
	Global Global `toml:"global" json:"global"`

	// Groups enumerates the instances groups that participate in this
	// composition.
	Groups Groups `toml:"groups" json:"groups" validate:"required,gt=0"`

	// Runs enumerate the runs that participate in this composition.
	Runs Runs `toml:"runs" json:"runs" validate:"required,gt=0"`
}

type CompositionRunGroup struct {
	// ID is the unique ID of this group.
	ID string `toml:"id" json:"id"`

	// GroupID is the ID of the group that this run group belongs to.
	// It will default to ID.
	GroupID string `toml:"group_id" json:"group_id" mapstructure:"group_id"`

	// Resources requested for each pod from the Kubernetes cluster
	Resources Resources `toml:"resources" json:"resources"`

	// Instances defines the number of instances that belong to this group.
	Instances Instances `toml:"instances" json:"instances"`

	// TestParams specify the test parameters to pass down to instances of this
	// group.
	TestParams map[string]string `toml:"test_params" json:"test_params" mapstructure:"test_params"`

	// Profiles specifies the profiles to capture, and the frequency of capture
	// of each. Profile support is SDK-dependent, as it relies entirely on the
	// facilities provided by the language runtime.
	//
	// In the case of Go, all profile kinds listed in https://golang.org/pkg/runtime/pprof/#Profile
	// are supported, taking a frequency expressed in time.Duration string
	// representation (e.g. 5s for every five seconds). Additionally, a special
	// profile kind "cpu" is supported; it takes no frequency and it starts a
	// CPU profile for the entire duration of the test.
	Profiles map[string]string `toml:"profiles" json:"profiles"`
	// contains filtered or unexported fields
}

type CompositionRunGroups []*CompositionRunGroup

type CreatedBy task.CreatedBy

type Dependencies []Dependency

type Dependency struct {
	// Module is the module name/path for the import to be overridden.
	Module string `toml:"module" json:"module" validate:"required"`

	// Target is the override module.
	Target string `toml:"target" json:"target" validate:"target"`

	// Version is the override version.
	Version string `toml:"version" json:"version" validate:"required"`
}

type DependencyTarget struct {
	// Target is the replacement dependency we want to use. It can be a different
	// fork or some module if the builder supports it.
	Target string

	// Version is the version of the dependency we want to use.
	Version string
}

type DescribeRequest struct {
	Term string `json:"term"`
}

type Engine interface {
	TasksManager

	BuilderByName(name string) (Builder, bool)
	RunnerByName(name string) (Runner, bool)

	ListBuilders() map[string]Builder
	ListRunners() map[string]Runner

	QueueBuild(request *BuildRequest, sources *UnpackedSources) (string, error)
	QueueRun(request *RunRequest, sources *UnpackedSources) (string, error)

	DoBuildPurge(ctx context.Context, builder, plan string, ow *rpc.OutputWriter) error
	DoCollectOutputs(ctx context.Context, runID string, ow *rpc.OutputWriter) error
	DoTerminate(ctx context.Context, ctype ComponentType, ref string, ow *rpc.OutputWriter) error
	DoHealthcheck(ctx context.Context, runner string, fix bool, ow *rpc.OutputWriter) (*HealthcheckReport, error)

	EnvConfig() config.EnvConfig
	Context() context.Context
}

type Global struct {
	// Plan is the test plan we want to run.
	Plan string `toml:"plan" json:"plan" validate:"required"`

	// Case is the test case we want to run.
	Case string `toml:"case" json:"case" validate:"required"`

	// TotalInstances defines the default total number of instances that participate in
	// runs of this composition; it is the sum of all instances in all groups.
	//
	// If all your instance counts are absolute values (and not percentages), you
	// may skip this value. It will be calculated automatically.
	TotalInstances uint `toml:"total_instances" json:"total_instances" mapstructure:"total_instances" validate:"gte=0"`

	// ConcurrentBuilds defines the maximum number of concurrent builds that are
	// scheduled for this test.
	ConcurrentBuilds int `toml:"concurrent_builds" json:"concurrent_builds"`

	// Builder is the default builder we're using.
	Builder string `toml:"builder" json:"builder"`

	// BuildConfig specifies the build configuration for this run.
	BuildConfig map[string]interface{} `toml:"build_config" json:"build_config" mapstructure:"build_config"`

	// Build applies global build defaults that trickle down to all groups, such
	// as selectors or dependencies. Groups can override these in their local
	// build definition.
	Build *Build `toml:"build" json:"build"`

	// Runner is the runner we're using.
	Runner string `toml:"runner" json:"runner" validate:"required"`

	// RunConfig specifies the run configuration for this run.
	RunConfig map[string]interface{} `toml:"run_config" json:"run_config" mapstructure:"run_config"`

	// Run applies global run defaults that trickle down to all groups, such as
	// test parameters or build artifacts. Groups can override these in their
	// local run definition.
	Run *RunParams `toml:"run" json:"run"`

	// DisableMetrics is used to disable metrics batching.
	DisableMetrics bool `toml:"disable_metrics" json:"disable_metrics"`
}

type Group struct {
	// ID is the unique ID of this group.
	ID string `toml:"id" json:"id"`

	// Builder is the builder we're using.
	Builder string `toml:"builder" json:"builder"`

	// BuildConfig specifies the build configuration for this run.
	BuildConfig map[string]interface{} `toml:"build_config" json:"build_config" mapstructure:"build_config"`

	// Build specifies the build configuration for this group.
	Build Build `toml:"build" json:"build"`

	// Resources requested for each pod from the Kubernetes cluster
	Resources Resources `toml:"resources" json:"resources"`

	// Instances defines the number of instances that belong to this group.
	Instances Instances `toml:"instances" json:"instances"`

	// Run specifies the run configuration for this group.
	Run RunParams `toml:"run" json:"run"`
	// contains filtered or unexported fields
}

type Groups []*Group

type HealthcheckItem struct {
	// Name is a short name describing this item.
	Name string
	// Status is the status of this check/fix.
	Status HealthcheckStatus
	// Message optionally contains any human-readable messages to be presented
	// to the user.
	Message string
}

type HealthcheckReport struct {
	// Checks enumerates the outcomes of the health checks.
	Checks []HealthcheckItem

	// Fixes enumerates the outcomes of the fixes applied during fix, if a
	// fix was requested.
	Fixes []HealthcheckItem
}

type HealthcheckRequest struct {
	Runner string `json:"runner"`
	Fix    bool   `json:"fix"`
}

type HealthcheckResponse = HealthcheckReport

type HealthcheckStatus string

type Healthchecker interface {
	Healthcheck(ctx context.Context, engine Engine, ow *rpc.OutputWriter, fix bool) (*HealthcheckReport, error)
}

type InstanceConstraints struct {
	Minimum int `toml:"min"`
	Maximum int `toml:"max"`
}

type Instances struct {
	// Count specifies the exact number of instances that belong to a group.
	//
	// Specifying a count is mutually exclusive with specifying a percentage.
	Count uint `toml:"count" json:"count"`

	// Percentage indicates the number of instances belonging to a group as a
	// proportion of the total instance count.
	//
	// Specifying a percentage is mutually exclusive with specifying a count.
	Percentage float64 `toml:"percentage" json:"percentage"`
}

type LogsRequest struct {
	TaskID string `json:"task_id"`
	Follow bool   `json:"follow"`
	// CancelWithContext indicates if the task should be cancelled
	// on context cancellation.
	CancelWithContext bool `json:"cancel_with_context"`
}

type LogsResponse = task.Task

type Metadata struct {
	// Name is the name of this composition.
	Name string `toml:"name" json:"name"`

	// Author is the author of this composition.
	Author string `toml:"author" json:"author"`
}

type OutputsRequest struct {
	Runner string `json:"runner"`
	RunID  string `json:"run_id"`
}

type Parameter struct {
	Type        string
	Description string `toml:"desc"`
	Unit        string
	Default     interface{}
}

type Resources struct {
	Memory string `toml:"memory" json:"memory"`
	CPU    string `toml:"cpu" json:"cpu"`
}

type Run struct {
	// ID is the unique ID of this run group.
	ID string `toml:"id" json:"id"`

	// TestParams specify the test parameters to pass down to instances of this
	// group.
	TestParams map[string]string `toml:"test_params" json:"test_params" mapstructure:"test_params"`

	// TotalInstances defines the total number of instances that participate in
	// this run; it is the sum of all instances in all groups.
	TotalInstances uint `toml:"total_instances" json:"total_instances" mapstructure:"total_instances" validate:"gte=0"`

	// Instances defines the number of instances that belong to this group.
	Groups CompositionRunGroups `toml:"groups" json:"groups" validate:"required,gt=0"`
}

type RunGroup struct {
	// ID is the id of the instance group this run pertains to.
	ID string

	// Instances is the number of instances to run with this configuration.
	Instances int

	// Resources for per instance in this group
	Resources Resources

	// ArtifactPath can be a docker image ID or an executable path; it's
	// runner-dependent.
	ArtifactPath string

	// Parameters are the runtime parameters to the test case.
	Parameters map[string]string

	// Profiles specifies the profiles to capture. Refer to the docs
	// on Run#Profiles for more info.
	Profiles map[string]string
}

type RunInput struct {
	// RunID is the run id assigned to this job by the Engine.
	RunID string

	// EnvConfig is the env configuration of the engine. Not a pointer to force
	// a copy.
	EnvConfig config.EnvConfig

	// RunnerConfig is the configuration of the runner sourced from the test
	// plan manifest, coalesced with any user-provided overrides.
	RunnerConfig interface{}

	// TestPlan is the name of the test plan.
	TestPlan string

	// TestCase is the name of the test case.
	TestCase string

	// TotalInstances is the total number of instances participating in this test case.
	TotalInstances int

	// DisableMetrics disables metrics batching.
	DisableMetrics bool

	// Groups enumerates the groups participating in this run.
	Groups []*RunGroup
}

type RunOutput struct {
	// RunnerID is the ID of the runner used.
	RunID string

	// Composition that was used for this run.
	Composition Composition

	// Result of the run
	// Depending on runner, might include:
	// - Status of run (green, red, yellow :: success, fail, partial success)
	// - Event log containing various information related to the run, for example:
	// -- Kubernetes events
	// -- Kubernetes pod Status
	// -- etc.
	Result interface{}
}

type RunParams struct {
	// Artifact specifies the build artifact to use for this run.
	Artifact string `toml:"artifact" json:"artifact"`

	// TestParams specify the test parameters to pass down to instances of this
	// group.
	TestParams map[string]string `toml:"test_params" json:"test_params"`

	// Profiles specifies the profiles to capture, and the frequency of capture
	// of each. Profile support is SDK-dependent, as it relies entirely on the
	// facilities provided by the language runtime.
	//
	// In the case of Go, all profile kinds listed in https://golang.org/pkg/runtime/pprof/#Profile
	// are supported, taking a frequency expressed in time.Duration string
	// representation (e.g. 5s for every five seconds). Additionally, a special
	// profile kind "cpu" is supported; it takes no frequency and it starts a
	// CPU profile for the entire duration of the test.
	Profiles map[string]string `toml:"profiles" json:"profiles"`
}

type RunRequest struct {
	Priority    int              `json:"priority"`
	BuildGroups []int            `json:"build_groups"`
	RunIds      []string         `json:"run_ids"`
	Composition Composition      `json:"composition"`
	Manifest    TestPlanManifest `json:"manifest"`
	CreatedBy   CreatedBy        `json:"created_by"`
}

type RunResponse = RunOutput

type Runner interface {
	// ID returns the canonical identifier for this runner.
	ID() string

	// Run runs a test case.
	Run(ctx context.Context, job *RunInput, ow *rpc.OutputWriter) (*RunOutput, error)

	// ConfigType returns the configuration type of this runner.
	ConfigType() reflect.Type

	// CompatibleBuilders returns the IDs of the builders whose artifacts this
	// runner can work with.
	CompatibleBuilders() []string

	// CollectOutputs gathers the outputs from a run, and produces a zip file
	// with the contents, writing it to the specified io.Writer.
	CollectOutputs(context.Context, *CollectionInput, *rpc.OutputWriter) error
}

type Runs []*Run

type StatusRequest struct {
	TaskID string `json:"task_id"`
}

type StatusResponse = task.Task

type TasksFilters struct {
	Types    []task.Type
	States   []task.State
	After    *time.Time
	Before   *time.Time
	TestPlan string
	TestCase string
}

type TasksManager interface {
	Tasks(filters TasksFilters) ([]task.Task, error)
	GetTask(id string) (*task.Task, error)
	Kill(taskId string) error
	DeleteTask(taskId string) error
	Logs(ctx context.Context, taskId string, follow bool, cancel bool, w io.Writer) (*task.Task, error)
}

type TasksRequest = TasksFilters

type Terminatable interface {
	TerminateAll(context.Context, *rpc.OutputWriter) error
}

type TerminateRequest struct {
	Runner  string `json:"runner"`
	Builder string `json:"builder"`
}

type TestCase struct {
	Name      string
	Instances InstanceConstraints
	// Parameters that can be passed to this test case.
	Parameters map[string]Parameter `toml:"params"`
}

type TestPlanManifest struct {
	Name      string
	Builders  map[string]config.ConfigMap `toml:"builders"`
	Runners   map[string]config.ConfigMap `toml:"runners"`
	TestCases []*TestCase                 `toml:"testcases"`

	// ExtraSources allows the user to ship extra source directories to the
	// daemon so they can be considered in the build (e.g. assets, package
	// overrides, etc.), when certain builders are used.
	//
	// It's a mapping of builder => directories.
	ExtraSources map[string][]string `toml:"extra_sources"`
}

type UnpackedSources struct {
	// BaseDir is the directory containing the plan under ./plan, and an
	// optional sdk under ./sdk.
	BaseDir string `json:"base_dir"`

	// PlanDir is the directory where the test plan's source has been
	// placed (i.e. BaseSrcPath/plan).
	PlanDir string `json:"plan_dir"`

	// SDKDir is the directory where the SDK's source has been placed. It
	// will be a zero-value if no SDK replacement has been requested, or
	// BaseSrcPath/sdk otherwise.
	SDKDir string `json:"sdk_dir"`

	// ExtraDir is the directory where any extra sources have been unpacked.
	ExtraDir string `json:"extra_dir"`
}