handlertoolchain

type BinaryParams struct {
	AppDir string
	// OS and Arch are the platform the executable has to run on rather than
	// the one building it. A dev session targets the Docker daemon's
	// architecture, and a Lambda build targets the architecture the function
	// is declared with.
	OS   string
	Arch string
	// OutputPath is where the executable must end up.
	OutputPath string
	// DeployTarget and Mode mirror PrepareParams.
	DeployTarget string
	Mode         string
}

type Config struct {
	// Command builds the handlers executable. Run through the shell, from the
	// application directory.
	Command string `json:"command"`
	// Binary is where Command leaves the executable, relative to the
	// application directory. The CLI copies it to wherever it is needed.
	Binary string `json:"binary"`
	// Env is added to Command's environment, on top of the CELERITY_BUILD_*
	// variables the CLI injects.
	Env map[string]string `json:"env,omitempty"`
	// Tidy, where set, is run after Command to reconcile the project's
	// dependency manifest.
	Tidy string `json:"tidy,omitempty"`
	// Extract reports the handlers the executable serves. Optional, and
	// without it the blueprint's hand-authored handler resources are used as
	// they are.
	Extract *ExtractConfig `json:"extract,omitempty"`
	// Test maps a suite name (unit, integration, api) to its command.
	Test map[string]string `json:"test,omitempty"`
	// WatchRoots are the directories a dev session watches, relative to the
	// application directory. Defaults to the application directory itself.
	WatchRoots []string `json:"watchRoots,omitempty"`
	// WatchExtensions are the file extensions a dev session rebuilds for.
	WatchExtensions []string `json:"watchExtensions,omitempty"`
	// WatchSkipDirs are directory names the watcher does not descend into.
	WatchSkipDirs []string `json:"watchSkipDirs,omitempty"`
	// Targets overrides any of the above per deploy target. A cross-compiled
	// binary usually lands somewhere different for each.
	Targets map[string]*Config `json:"targets,omitempty"`
}

type ExecRunner struct{}

type ExtractConfig struct {
	// Command produces a handler manifest. Run through the shell, from the
	// application directory.
	Command string `json:"command"`
	// ManifestFile is where Command writes the manifest, relative to the
	// application directory. When empty the manifest is read from the
	// command's standard output.
	ManifestFile string `json:"manifestFile,omitempty"`
}

type ExtractParams struct {
	AppDir string
}

type Options struct {
	// Runtime is the blueprint's runtime identifier.
	Runtime string
	// AppDir is the application directory.
	AppDir string
	// Config is the handlerBuild block, or nil when the app declares none.
	Config *Config
	// Runner runs external commands. Defaults to ExecRunner.
	Runner Runner
}

type PrepareParams struct {
	AppDir string
	// DeployTarget is the app's deploy target (e.g. "aws-serverless"), which
	// decides the platform packages linked into the executable.
	DeployTarget string
	// Mode is ModeDev or ModeDeploy.
	Mode string
	// ResourceKinds are the Celerity resource kinds the blueprint declares
	// (bucket, queue, topic, cache, datastore, sqlDatabase), so the toolchain
	// links an implementation for each.
	ResourceKinds []string
	// SQLEngines are the engines of the blueprint's SQL databases
	// (e.g. "postgres"), so a driver is linked for each.
	SQLEngines []string
	// Telemetry names what traces are exported with, or is empty for none.
	Telemetry string
	// TestPackages links the platform packages into the project's integration
	// suites as well as into the application, so a test that reaches a real
	// resource reaches it through the same provider the deployed binary would.
	// Set for a dev session and not for a deploy, where there are no tests to
	// generate for.
	TestPackages bool
}

type Runner interface {
	// Run executes name with args in dir, with env added to the process
	// environment, streaming output to toolOutput.
	Run(ctx context.Context, dir string, env map[string]string, toolOutput io.Writer, name string, args ...string) error
	// Output executes the command and returns its standard output, streaming
	// only standard error to toolOutput.
	Output(ctx context.Context, dir string, env map[string]string, toolOutput io.Writer, name string, args ...string) ([]byte, error)
}

type Toolchain interface {
	// Name identifies the toolchain in output and errors (e.g. "go").
	Name() string

	// Validate reports whether the project is actually set up for this
	// toolchain, so a missing SDK dependency fails before a build does.
	Validate(appDir string) error

	// Prepare runs whatever code generation has to happen before the
	// application will compile for this target. It is safe to call more than
	// once and regenerates rather than reusing what is on disk, because a dev
	// session's generated file is the wrong one for a deploy and vice versa.
	Prepare(ctx context.Context, p PrepareParams) error

	// Extract reports the handlers the executable serves. Returning a nil
	// manifest means this toolchain cannot extract, and the blueprint's
	// hand-authored handler resources are used as they are.
	//
	// Callers run Prepare first: extraction compiles the application, so it
	// fails on a project whose generated platform imports are absent or stale.
	Extract(ctx context.Context, p ExtractParams) (*preprocess.HandlerManifest, error)

	// BuildBinary compiles the handlers executable to p.OutputPath.
	BuildBinary(ctx context.Context, p BinaryParams) error

	// WatchPaths describes what a dev session should watch.
	WatchPaths() WatchPaths

	// TestCommand returns the command for a named test suite, and whether one
	// is configured.
	TestCommand(suite string) ([]string, bool)
}

type WatchPaths struct {
	// Roots are directories relative to the application directory.
	Roots []string
	// Extensions are the file extensions a change is relevant for.
	Extensions []string
	// SkipDirs are directory names not to descend into.
	SkipDirs []string
	// SkipFiles are base names a change is never relevant for, whatever their
	// extension.
	//
	// A toolchain's own generated file has to be listed here or a session
	// cannot settle, because Prepare rewrites that file and reacting to the
	// rewrite runs Prepare again.
	SkipFiles []string
}