buildengine

package
v0.376.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 1, 2024 License: Apache-2.0 Imports: 56 Imported by: 0

Documentation

Overview

Package buildengine provides a framework for building FTL modules.

Index

Constants

View Source 
const BuildLockTimeout = time.Minute

Variables

View Source 
var ErrSkip = errors.New("skip directory")

ErrSkip can be returned by the WalkDir callback to skip a file or directory.

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, 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 DiscoverModules 

func DiscoverModules(ctx context.Context, moduleDirs []string) ([]moduleconfig.ModuleConfig, error)

DiscoverModules recursively loads all modules under the given directories (or if none provided, the current working directory is used).

func FindFilesToDeploy 

func FindFilesToDeploy(moduleConfig moduleconfig.AbsModuleConfig) ([]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.

func WalkDir 

func WalkDir(dir string, fn func(path string, d fs.DirEntry) error) error

WalkDir performs a depth-first walk of the file tree rooted at dir, calling fn for each file or directory in the tree, including dir.

It will adhere to .gitignore files. The callback "fn" can return ErrSkip to skip recursion.

Types

type AutoRebuildEndedEvent added in v0.376.0 

type AutoRebuildEndedEvent struct {
	Module string
	Result either.Either[BuildResult, error]
}

AutoRebuildEndedEvent is sent when the plugin ends an automatic rebuild.

func (AutoRebuildEndedEvent) ModuleName added in v0.376.0 

func (e AutoRebuildEndedEvent) ModuleName() string

type AutoRebuildStartedEvent added in v0.376.0 

type AutoRebuildStartedEvent struct {
	Module string
}

AutoRebuildStartedEvent is sent when the plugin starts an automatic rebuild.

func (AutoRebuildStartedEvent) ModuleName added in v0.376.0 

func (e AutoRebuildStartedEvent) ModuleName() string

type BuildResult added in v0.376.0 

type BuildResult struct {
	Name      string
	Errors    []*schema.Error
	Schema    *schema.Module
	StartTime time.Time
}

type CompilerBuildError 

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

func (CompilerBuildError) Error 

func (e CompilerBuildError) Error() string

func (CompilerBuildError) Unwrap 

func (e CompilerBuildError) Unwrap() error

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 FileChangeType 

type FileChangeType rune
const (
	FileAdded   FileChangeType = '+'
	FileRemoved FileChangeType = '-'
	FileChanged FileChangeType = '*'
)

func CompareFileHashes 

func CompareFileHashes(oldFiles, newFiles FileHashes) (FileChangeType, string, bool)

CompareFileHashes compares the hashes of the files in the oldFiles and newFiles maps.

Returns true if the hashes are equal, false otherwise.

If false, the returned string will be a file that caused the difference and the returned FileChangeType will be the type of change that occurred.

func (FileChangeType) GoString 

func (f FileChangeType) GoString() string

func (FileChangeType) String 

func (f FileChangeType) String() string

type FileHashes 

type FileHashes map[string][]byte

type LanguagePlugin added in v0.376.0 

type LanguagePlugin interface {
	// Topic for all update events from the plugin
	// The same topic must be returned each time this method is called
	Updates() *pubsub.Topic[PluginEvent]

	// GetCreateModuleFlags returns the flags that can be used to create a module for this language.
	GetCreateModuleFlags(ctx context.Context) ([]*kong.Flag, error)

	// CreateModule creates a new module in the given directory with the given name and language.
	CreateModule(ctx context.Context, projConfig projectconfig.Config, moduleConfig moduleconfig.ModuleConfig, flags map[string]string) error

	// GetDependencies returns the dependencies of the module.
	GetDependencies(ctx context.Context) ([]string, error)

	// Build builds the module with the latest config and schema.
	// In dev mode, plugin is responsible for automatically rebuilding as relevant files within the module change,
	// and publishing these automatic builds updates to Updates().
	Build(ctx context.Context, projectRoot string, config moduleconfig.ModuleConfig, sch *schema.Schema, buildEnv []string, devMode bool) (BuildResult, error)

	// Kill stops the plugin and cleans up any resources.
	Kill(ctx context.Context) error
}

LanguagePlugin handles building and scaffolding modules in a specific language.

func PluginFromConfig added in v0.376.0 

func PluginFromConfig(ctx context.Context, config moduleconfig.ModuleConfig, projectRoot string) (p LanguagePlugin, err error)

PluginFromConfig creates a new language plugin from the given config.

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 ModifyFilesTransaction 

type ModifyFilesTransaction interface {
	Begin() error
	ModifiedFiles(paths ...string) error
	End() error
}

ModifyFilesTransaction allows builds to modify files in a module without triggering a watch event. This helps us avoid infinite loops with builds changing files, and those changes triggering new builds.as a no-op

type Module 

type Module struct {
	Config       moduleconfig.ModuleConfig
	Dependencies []string
}

Module represents an FTL module in the build engine

func LoadModule 

func LoadModule(dir string) (Module, error)

LoadModule loads a module from the given directory.

func UpdateDependencies 

func UpdateDependencies(ctx context.Context, module Module, plugin LanguagePlugin) (Module, error)

UpdateDependencies finds the dependencies for a module and returns a Module with those dependencies populated.

func (Module) CopyWithDependencies 

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

type Option 

type Option func(o *Engine)

func BuildEnv added in v0.361.0 

func BuildEnv(env []string) Option

func Parallelism 

func Parallelism(n int) Option

func WithDevMode added in v0.367.0 

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 added in v0.370.0 

func WithStartTime(startTime time.Time) Option

WithStartTime sets the start time to report total startup time

type PluginEvent added in v0.376.0 

type PluginEvent interface {
	ModuleName() string
	// contains filtered or unexported methods
}

PluginEvent is used to notify of updates from the plugin.

type WatchEvent 

type WatchEvent interface {
	// contains filtered or unexported methods
}

A WatchEvent is an event that occurs when a module is added, removed, or changed.

type WatchEventModuleAdded 

type WatchEventModuleAdded struct{ Config moduleconfig.ModuleConfig }

type WatchEventModuleChanged 

type WatchEventModuleChanged struct {
	Config moduleconfig.ModuleConfig
	Change FileChangeType
	Path   string
	Time   time.Time
}

type WatchEventModuleRemoved 

type WatchEventModuleRemoved struct{ Config moduleconfig.ModuleConfig }

type Watcher 

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

func NewWatcher 

func NewWatcher(patterns ...string) *Watcher

func (*Watcher) GetTransaction 

func (w *Watcher) GetTransaction(moduleDir string) ModifyFilesTransaction

func (*Watcher) Watch 

func (w *Watcher) Watch(ctx context.Context, period time.Duration, moduleDirs []string) (*pubsub.Topic[WatchEvent], error)

Watch the given directories for new modules, deleted modules, and changes to existing modules, publishing a change event for each.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.