buildengine

Documentation

Overview

Package buildengine provides a framework for building FTL modules.

Index

• func CleanStubs(ctx context.Context, projectRoot string) error
• func Deploy(ctx context.Context, module Module, deploy []string, replicas int32, ...) error
• func FindFilesToDeploy(config moduleconfig.AbsModuleConfig, deploy []string) ([]string, error)
• func GenerateStubs(ctx context.Context, projectRoot string, modules []*schema.Module, ...) error
• func SyncStubReferences(ctx context.Context, projectRoot string, moduleNames []string, ...) error
• func TopologicalSort(graph map[string][]string) (groups [][]string, cycleError error)
• type DeployClient
• type Engine
  • func New(ctx context.Context, client DeployClient, projectRoot string, ...) (*Engine, error)
  • func (e *Engine) Build(ctx context.Context) error
  • func (e *Engine) BuildAndDeploy(ctx context.Context, replicas int32, waitForDeployOnline bool, ...) error
  • func (e *Engine) Close() error
  • func (e *Engine) Deploy(ctx context.Context, replicas int32, waitForDeployOnline bool) error
  • func (e *Engine) Dev(ctx context.Context, period time.Duration) error
  • func (e *Engine) Each(fn func(Module) error) (err error)
  • func (e *Engine) Graph(moduleNames ...string) (map[string][]string, error)
  • func (e *Engine) Import(ctx context.Context, schema *schema.Module)
  • func (e *Engine) Modules() []string
• type Listener
• type Module
  • func (m Module) CopyWithDependencies(dependencies []string) Module
  • func (m Module) CopyWithDeploy(files []string) Module
• type Option
  • func BuildEnv(env []string) Option
  • func Parallelism(n int) Option
  • func WithDevMode(devMode bool) Option
  • func WithListener(listener Listener) Option
  • func WithStartTime(startTime time.Time) Option

Functions

func CleanStubs

func CleanStubs(ctx context.Context, projectRoot string) error

CleanStubs removes all generated stubs.

func Deploy

func Deploy(ctx context.Context, module Module, deploy []string, replicas int32, waitForDeployOnline bool, client DeployClient) error

Deploy a module to the FTL controller with the given number of replicas. Optionally wait for the deployment to become ready.

func FindFilesToDeploy

func FindFilesToDeploy(config moduleconfig.AbsModuleConfig, deploy []string) ([]string, error)

FindFilesToDeploy returns a list of files to deploy for the given module.

func GenerateStubs

func GenerateStubs(ctx context.Context, projectRoot string, modules []*schema.Module, moduleConfigs []moduleconfig.ModuleConfig) error

GenerateStubs generates stubs for the given modules.

Currently, only Go stubs are supported. Kotlin and other language stubs can be added in the future.

func SyncStubReferences

func SyncStubReferences(ctx context.Context, projectRoot string, moduleNames []string, moduleConfigs []moduleconfig.ModuleConfig) error

SyncStubReferences syncs the references in the generated stubs.

For Go, this means updating all the go.work files to include all known modules in the shared stubbed modules directory.

func TopologicalSort

func TopologicalSort(graph map[string][]string) (groups [][]string, cycleError error)

TopologicalSort attempts to order the modules supplied in the graph based on their topologically sorted order. A cycle in the module dependency graph will cause this sort to be incomplete. The sorted modules are returned as a sequence of `groups` of modules that may be built in parallel. The `unsorted` modules impacted by a dependency cycle get reported as an error.

Types

type DeployClient

type DeployClient interface {
	GetArtefactDiffs(ctx context.Context, req *connect.Request[ftlv1.GetArtefactDiffsRequest]) (*connect.Response[ftlv1.GetArtefactDiffsResponse], error)
	UploadArtefact(ctx context.Context, req *connect.Request[ftlv1.UploadArtefactRequest]) (*connect.Response[ftlv1.UploadArtefactResponse], error)
	CreateDeployment(ctx context.Context, req *connect.Request[ftlv1.CreateDeploymentRequest]) (*connect.Response[ftlv1.CreateDeploymentResponse], error)
	ReplaceDeploy(ctx context.Context, req *connect.Request[ftlv1.ReplaceDeployRequest]) (*connect.Response[ftlv1.ReplaceDeployResponse], error)
	Status(ctx context.Context, req *connect.Request[ftlv1.StatusRequest]) (*connect.Response[ftlv1.StatusResponse], error)
	UpdateDeploy(ctx context.Context, req *connect.Request[ftlv1.UpdateDeployRequest]) (*connect.Response[ftlv1.UpdateDeployResponse], error)
	GetSchema(ctx context.Context, req *connect.Request[ftlv1.GetSchemaRequest]) (*connect.Response[ftlv1.GetSchemaResponse], error)
	PullSchema(ctx context.Context, req *connect.Request[ftlv1.PullSchemaRequest]) (*connect.ServerStreamForClient[ftlv1.PullSchemaResponse], error)
	Ping(ctx context.Context, req *connect.Request[ftlv1.PingRequest]) (*connect.Response[ftlv1.PingResponse], error)
}

type Engine

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

Engine for building a set of modules.

func New

func New(ctx context.Context, client DeployClient, projectRoot string, moduleDirs []string, options ...Option) (*Engine, error)

New constructs a new Engine.

Completely offline builds are possible if the full dependency graph is locally available. If the FTL controller is available, it will be used to pull in missing schemas.

"dirs" are directories to scan for local modules.

func (*Engine) Build

func (e *Engine) Build(ctx context.Context) error

Build attempts to build all local modules.

func (*Engine) BuildAndDeploy

func (e *Engine) BuildAndDeploy(ctx context.Context, replicas int32, waitForDeployOnline bool, moduleNames ...string) error

BuildAndDeploy attempts to build and deploy all local modules.

func (*Engine) Close

func (e *Engine) Close() error

Close stops the Engine's schema sync.

func (*Engine) Deploy

func (e *Engine) Deploy(ctx context.Context, replicas int32, waitForDeployOnline bool) error

Deploy attempts to deploy all (already compiled) local modules.

If waitForDeployOnline is true, this function will block until all deployments are online.

func (*Engine) Dev

func (e *Engine) Dev(ctx context.Context, period time.Duration) error

Dev builds and deploys all local modules and watches for changes, redeploying as necessary.

func (*Engine) Each

func (e *Engine) Each(fn func(Module) error) (err error)

Each iterates over all local modules.

func (*Engine) Graph

func (e *Engine) Graph(moduleNames ...string) (map[string][]string, error)

Graph returns the dependency graph for the given modules.

If no modules are provided, the entire graph is returned. An error is returned if any dependencies are missing.

func (*Engine) Import

func (e *Engine) Import(ctx context.Context, schema *schema.Module)

Import manually imports a schema for a module as if it were retrieved from the FTL controller.

func (*Engine) Modules

func (e *Engine) Modules() []string

Modules returns the names of all modules.

type Listener

type Listener interface {
	// OnBuildStarted is called when a build is started for a project.
	OnBuildStarted(module Module)

	// OnBuildSuccess is called when all modules have been built successfully and deployed.
	OnBuildSuccess()

	// OnBuildFailed is called for any build failures.
	// OnBuildSuccess should not be called if this is called after a OnBuildStarted.
	OnBuildFailed(err error)
}

type Module

type Module struct {
	Config       moduleconfig.ModuleConfig
	Dependencies []string
	// paths to deploy, relative to ModuleConfig.DeployDir
	Deploy []string
}

Module represents an FTL module in the build engine

func (Module) CopyWithDependencies

func (m Module) CopyWithDependencies(dependencies []string) Module

func (Module) CopyWithDeploy

func (m Module) CopyWithDeploy(files []string) Module

type Option

type Option func(o *Engine)

func BuildEnv

func BuildEnv(env []string) Option

func Parallelism

func Parallelism(n int) Option

func WithDevMode

func WithDevMode(devMode bool) Option

WithDevMode sets the engine to dev mode.

func WithListener

func WithListener(listener Listener) Option

WithListener sets the event listener for the Engine.

func WithStartTime

func WithStartTime(startTime time.Time) Option

WithStartTime sets the start time to report total startup time