components

type ComposeSpec struct {
	// ComposeFile is the repo-relative compose file. Its services are this component's
	// internals.
	ComposeFile string

	// ComposeOverrideFiles are repo-relative Compose files merged after ComposeFile.
	// They contain only component-specific overrides.
	ComposeOverrideFiles []string

	// StagedFiles maps repository-relative source files to their names beside the
	// staged Compose file.
	StagedFiles map[string]string

	// GeneratedFiles maps framework-generated file names to their contents.
	GeneratedFiles map[string][]byte

	// PrimaryService is the compose service whose ports back this component's
	// Endpoints. Everything a test addresses must be on this service.
	PrimaryService string

	// Services lists the services whose logs are collected.
	Services []string

	// Env contains variables passed to Compose for interpolation.
	Env map[string]string

	// ProjectEnv contains variables set only in the Compose project environment, for
	// interpolation and environment-sourced configs and secrets. Unlike Env, they are never
	// written to a service env file, so a value may span lines and stays out of every
	// container's environment.
	ProjectEnv map[string]string

	// CoverageServices lists services and artifact formats collected after shutdown.
	CoverageServices []CoverageService

	// BootAttempts caps how many times the runtime retries a failed boot of this stack,
	// tearing down and relaunching with a fresh stack each time. Zero or one means no
	// retry, matching the default for every compose component that does not set this.
	BootAttempts int
}

type ConfigFormat string

type ConfigInjection struct {
	// BaseConfigPath is the product's shipped config, relative to the repo root.
	BaseConfigPath string
	// SharedOverlayPath is the small overlay every block gets, relative to the repo
	// root. Optional.
	SharedOverlayPath string
	// ExtraOverlays are optional overlays merged after the shared overlay and before the
	// block-specific overlay.
	ExtraOverlays []string
	// ContainerPath is where the merged file lands in the container.
	ContainerPath string
	// Format is the merge syntax.
	Format ConfigFormat
	// Versioned contains exact released-version configuration profiles. When a
	// component using versioned profiles is assigned an image version, it must
	// select one of these profiles instead of using the source-tree defaults.
	Versioned map[string]ConfigProfile
}

type ConfigProfile struct {
	BaseConfigPath    string
	SharedOverlayPath string
}

type CoverageService struct {
	Name string
	// OutputName optionally identifies the coverage output directory. Empty uses Name.
	OutputName string
	Types      []string
}

type DBContract struct {
	// Supported lists the database engines supported by the component.
	Supported []DBType

	// Schema maps database engines to the ordered DDL files applied by the framework.
	Schema map[DBType][]string

	// SelfMigrates lists engines whose schema is applied by the component.
	SelfMigrates []DBType

	// SharesStoreWith names the component that owns this component's runtime.
	SharesStoreWith string

	// Env maps a resolved DSN to component environment variables.
	Env func(DSN) map[string]string
}

type DBType string

type DSN struct {
	Type DBType

	// Host and Port identify the database on the component network.
	Host string
	Port int

	Database string
	User     string
	Password string
	SSLMode  string

	// FilePath is set only for embedded engines, where there is no host/port.
	FilePath string
}

type Definition struct {
	// Name is the identifier a suite file references. Unique within a registry.
	Name string

	// Image is what to run, for a single-container component.
	Image ImageRef

	// Compose backs this component with a multi-container stack instead of a single
	// image, while still presenting it as ONE component to a suite file. Mutually
	// exclusive with Image.
	Compose *ComposeSpec

	// External describes a component hosted outside the test process. It is mutually
	// exclusive with Image and Compose.
	External *ExternalSpec

	// Alias is the component's DNS name on its network.
	Alias string

	// AliasIsFixed prevents the alias from being suffixed for replicas.
	AliasIsFixed bool

	// Endpoints are the component's addressable ports.
	Endpoints []Endpoint

	// Health is the application-level readiness gate. Nil disables this gate.
	Health *HealthCheck
	// VersionedHealth replaces Health for released image versions whose readiness
	// contract differs from the source-build contract.
	VersionedHealth map[string]HealthCheck

	// Config describes configuration assembly, if the component has any.
	Config *ConfigInjection

	// DB is the storage contract, if the component has storage.
	DB *DBContract

	// Wiring decodes and validates component-specific block configuration.
	Wiring WiringSpec

	// ApplyWiring returns the definition a block's decoded wiring selects, for wiring that
	// changes what the component runs. It must not modify def. Nil leaves the definition
	// as registered.
	ApplyWiring func(def *Definition, wiring any) (*Definition, error)

	// Env is static environment applied to every instance, before DSN and wiring.
	Env map[string]string

	// Files are copied in before start.
	Files []FileMount

	// Cmd overrides the image's command.
	Cmd []string

	// Provisions returns environment values for dependent components after this component
	// becomes ready.
	Provisions func(ctx context.Context, inst *Instance, dependent string) (map[string]string, error)

	// DependsOn lists components that must be ready before this one starts.
	DependsOn []string

	// Limits caps this container's host resources.
	Limits ResourceLimits

	// Shared starts one instance for all blocks that declare the component.
	Shared bool

	// SourceProduct names the product whose source build supplies this component's image,
	// for a component that runs another product's image under its own name. Empty means
	// the product named Name.
	SourceProduct string
}

type Endpoint struct {
	// Name identifies the endpoint.
	Name string

	// Port is the in-container port.
	Port int

	// Scheme is "http", "https", "grpc", "tcp", …
	Scheme string

	// PathPrefix is prepended to paths built against this endpoint, for a component
	// that serves its API under a fixed prefix.
	PathPrefix string

	// AwaitListening includes the port in container-level readiness checks.
	AwaitListening bool

	// Service names the Compose service that provides this endpoint. Empty uses the
	// primary service.
	Service string
}

type ExternalEndpoint struct {
	// Name identifies the endpoint.
	Name string
}

type ExternalSpec struct {
	// Endpoints are the named addresses exposed by the component.
	Endpoints []ExternalEndpoint

	// RequiredParameters are runtime parameters that must be supplied before Resolve runs.
	RequiredParameters []string

	// Resolve constructs endpoint URLs from the repository root and runtime parameters.
	Resolve func(repoRoot string, parameters map[string]string) (map[string]string, error)
}

type FileMount struct {
	// HostPath is relative to the repository root. Exactly one of HostPath and Content is set.
	HostPath string
	// Content is the file's bytes, for a file the framework generates instead of reading.
	Content []byte
	// ContainerPath is the absolute destination.
	ContainerPath string
	// Mode is the file mode to set on the copy.
	Mode int64
}

type HealthCheck struct {
	// Endpoint names the Endpoint to probe.
	Endpoint string

	// Service names the Compose service to probe. Empty uses the primary service.
	Service string
	// Path is appended to the endpoint's base URL.
	Path string
	// ExpectStatus is the status that means ready. Usually 200.
	ExpectStatus int
	// Timeout bounds the whole poll.
	Timeout time.Duration
	// Interval is the gap between probes.
	Interval time.Duration
}

type ImageBuild struct {
	Context    string
	Dockerfile string
	Args       map[string]string
}

type ImageRef struct {
	// Ref is the default image, tag included.
	Ref string
	// ByArch overrides Ref for a GOARCH value ("arm64", "amd64").
	ByArch map[string]string
	// Build, when set, means the image is built from the repo rather than pulled.
	// The path is relative to the repository root.
	Build *ImageBuild
}

type Instance struct {
	// contains filtered or unexported fields
}

type Registry struct {
	// contains filtered or unexported fields
}

type ResourceLimits struct {
	CPUs     float64
	MemoryMB int64
}

type Set struct {
	// contains filtered or unexported fields
}

type Vars map[string]string

type WiringSpec interface {
	// Decode parses a wiring node into the component's wiring type.
	Decode(node *yaml.Node) (any, error)
}