workspace

package
v1.0.0-beta.1 Latest Latest
Warning

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

 Go to latest Published: May 29, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ConfigFileName is the workspace config filename inside .dagger/.
	ConfigFileName = "config.toml"

	// ModuleConfigFileName is the module config filename.
	ModuleConfigFileName = "dagger.json"
)
View Source 
const (
	LockDirName  = ".dagger"
	LockFileName = "lock"
)
View Source 
const (
	LockModeDisabled LockMode = "disabled"
	LockModeLive     LockMode = "live"
	LockModePinned   LockMode = "pinned"
	LockModeFrozen   LockMode = "frozen"

	// Backward-compatible aliases for the previous experimental names.
	LockModeAuto   = LockModePinned
	LockModeStrict = LockModeFrozen

	// DefaultLockMode is used when no mode is explicitly set.
	DefaultLockMode = LockModeDisabled
)

Variables

This section is empty.

Functions

func EnsureEnv 

func EnsureEnv(cfg *Config, envName string) bool

EnsureEnv makes sure the named environment exists. It returns true when the config was changed.

func EnvNames 

func EnvNames(cfg *Config) []string

EnvNames returns the configured environment names in deterministic order.

func ExtractConfigDefaults added in v0.21.0 

func ExtractConfigDefaults(customizations []*modules.ModuleConfigArgument) map[string]any

ExtractConfigDefaults returns constructor arg defaults from customizations.

func ReadConfigValue 

func ReadConfigValue(data []byte, key string) (string, error)

ReadConfigValue reads a value from config TOML at the given dotted key. When key is empty, it returns the full config contents.

func RemoveEnv 

func RemoveEnv(cfg *Config, envName string) error

RemoveEnv removes the named environment from the config.

func ResolveModuleEntrySource 

func ResolveModuleEntrySource(configDir, source string) string

ResolveModuleEntrySource converts a workspace-config module source into the path that should actually be loaded or displayed from the workspace root. Relative local sources are resolved from the config directory; absolute local sources are preserved as-is.

func SerializeConfig 

func SerializeConfig(cfg *Config) []byte

SerializeConfig serializes a workspace config into deterministic TOML.

func UpdateConfigBytes 

func UpdateConfigBytes(existingData []byte, cfg *Config) ([]byte, error)

UpdateConfigBytes rewrites config bytes while preserving existing comments and formatting when a prior file exists.

func UpdateConfigBytesWithHints 

func UpdateConfigBytesWithHints(
	existingData []byte,
	cfg *Config,
	hints map[string][]ConstructorArgHint,
) ([]byte, error)

UpdateConfigBytesWithHints rewrites config bytes while preserving existing comments and formatting, then injects commented-out setting hints for the specified modules.

func WriteConfigValue 

func WriteConfigValue(existingData []byte, key string, rawValue string) ([]byte, error)

WriteConfigValue writes a typed value to config TOML at the given dotted key.

Types

type CompatMainModule 

type CompatMainModule struct {
	Name       string
	ConfigName string
	Entry      ModuleEntry
}

CompatMainModule is the projected legacy root module. It remains a distinct part of the compat workspace so runtime compat can load it from the original legacy location while migration persists it under .dagger/modules/<name>.

type CompatWorkspace 

type CompatWorkspace struct {
	Modules     []CompatWorkspaceModule
	MainModule  *CompatMainModule
	Config      *modules.ModuleConfig
	ConfigPath  string
	ProjectRoot string
}

CompatWorkspace is the shared projection of legacy dagger.json semantics used by both runtime compat mode and on-disk migration.

func ParseCompatWorkspace 

func ParseCompatWorkspace(data []byte) (*CompatWorkspace, error)

ParseCompatWorkspace parses a legacy dagger.json into the migration-compatible compat-workspace representation. Returns nil if the legacy config does not need to migrate into workspace config at its own location.

func ParseCompatWorkspaceAt 

func ParseCompatWorkspaceAt(data []byte, configPath string) (*CompatWorkspace, error)

ParseCompatWorkspaceAt parses a legacy dagger.json into the migration-compatible compat-workspace representation, with optional provenance from the config path. Returns nil if the legacy config does not need to migrate into workspace config at its own location.

func ParseRuntimeCompatWorkspaceAt 

func ParseRuntimeCompatWorkspaceAt(data []byte, configPath string) (*CompatWorkspace, error)

ParseRuntimeCompatWorkspaceAt parses a legacy dagger.json into the runtime compat-workspace representation, with optional provenance from the config path. Returns nil if the legacy config cannot create ambient workspace context.

func (*CompatWorkspace) MustMigrateToWorkspaceConfig 

func (compatWorkspace *CompatWorkspace) MustMigrateToWorkspaceConfig() bool

MustMigrateToWorkspaceConfig reports whether this compat workspace was created from a legacy dagger.json that must be replaced by .dagger/config.toml at the same location during migration.

func (*CompatWorkspace) WorkspaceConfig 

func (compatWorkspace *CompatWorkspace) WorkspaceConfig() *Config

type CompatWorkspaceModule 

type CompatWorkspaceModule struct {
	Name              string
	ConfigName        string
	Source            string
	Pin               string
	Entry             ModuleEntry
	ArgCustomizations []*modules.ModuleConfigArgument
}

CompatWorkspaceModule is one workspace-owned module projected out of a legacy dagger.json.

type Config 

type Config struct {
	Modules            map[string]ModuleEntry `toml:"modules"`
	Ignore             []string               `toml:"ignore"`
	DefaultsFromDotEnv bool                   `toml:"defaults_from_dotenv,omitempty"`
	Env                map[string]EnvOverlay  `toml:"env"`
	Ports              map[string]PortMapping `toml:"ports,omitempty"`
}

Config represents a parsed .dagger/config.toml workspace configuration.

func ApplyEnvOverlay 

func ApplyEnvOverlay(cfg *Config, envName string) (*Config, error)

ApplyEnvOverlay returns a copy of cfg with the named environment overlay applied on top of the base module settings.

In v1, environments may only override [modules.<name>.settings] values.

func ParseConfig 

func ParseConfig(data []byte) (*Config, error)

ParseConfig parses config.toml bytes into a workspace config.

type ConstructorArgHint 

type ConstructorArgHint struct {
	Name         string
	TypeLabel    string
	Description  string
	ExampleValue string
}

ConstructorArgHint captures a constructor-backed setting hint for a module.

type EnvModuleOverlay 

type EnvModuleOverlay struct {
	Settings map[string]any `toml:"settings,omitempty"`
}

EnvModuleOverlay is the environment-specific overlay for one installed module.

type EnvOverlay 

type EnvOverlay struct {
	Modules map[string]EnvModuleOverlay `toml:"modules"`
}

EnvOverlay is a named workspace environment overlay. It intentionally supports only a constrained subset of the root schema.

type LegacyBlueprint 

type LegacyBlueprint struct {
	Name   string
	Source string
	Pin    string
}

LegacyBlueprint represents a blueprint extracted from a legacy dagger.json.

func ParseLegacyBlueprint 

func ParseLegacyBlueprint(data []byte) (*LegacyBlueprint, error)

ParseLegacyBlueprint parses a legacy dagger.json and extracts its blueprint. Returns nil if no blueprint is present.

type LegacyToolchain 

type LegacyToolchain struct {
	Name           string
	Source         string
	Pin            string
	ConfigDefaults map[string]any
	Customizations []*modules.ModuleConfigArgument
}

LegacyToolchain represents a toolchain extracted from a legacy dagger.json, with constructor arg defaults already resolved from customizations.

func ParseLegacyToolchains 

func ParseLegacyToolchains(data []byte) ([]LegacyToolchain, error)

ParseLegacyToolchains parses a legacy dagger.json and extracts its toolchains with their constructor arg defaults. Returns nil if no toolchains are present.

type Lock added in v0.21.0 

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

Lock is the workspace lockfile wrapper.

func NewLock added in v0.21.0 

func NewLock() *Lock

NewLock returns an empty workspace lock.

func ParseLock added in v0.21.0 

func ParseLock(data []byte) (*Lock, error)

ParseLock parses .dagger/lock data.

func (*Lock) Clone added in v0.21.0 

func (l *Lock) Clone() (*Lock, error)

Clone returns a deep copy of the lock.

func (*Lock) DeleteLookup added in v0.21.0 

func (l *Lock) DeleteLookup(namespace, operation string, inputs []any) bool

DeleteLookup removes a generic lookup tuple entry.

func (*Lock) Entries added in v0.21.0 

func (l *Lock) Entries() ([]LookupEntry, error)

Entries returns a deterministic snapshot of all lookup entries.

func (*Lock) GetLookup added in v0.21.0 

func (l *Lock) GetLookup(namespace, operation string, inputs []any) (LookupResult, bool, error)

GetLookup retrieves the lock result for a generic lookup tuple.

func (*Lock) GetModuleResolve added in v0.21.0 

func (l *Lock) GetModuleResolve(source string) (LookupResult, bool, error)

GetModuleResolve retrieves the lock result for a module source lookup.

func (*Lock) Marshal added in v0.21.0 

func (l *Lock) Marshal() ([]byte, error)

Marshal serializes lock entries.

func (*Lock) Merge added in v0.21.0 

func (l *Lock) Merge(other *Lock) error

Merge applies all entries from other onto l.

func (*Lock) SetLookup added in v0.21.0 

func (l *Lock) SetLookup(namespace, operation string, inputs []any, result LookupResult) error

SetLookup sets the lock result for a generic lookup tuple.

func (*Lock) SetModuleResolve added in v0.21.0 

func (l *Lock) SetModuleResolve(source string, result LookupResult) error

SetModuleResolve sets the lock result for a module source lookup.

type LockMode added in v0.21.0 

type LockMode string

LockMode controls where lookup results come from for a run.

func ParseLockMode added in v0.21.0 

func ParseLockMode(mode string) (LockMode, error)

ParseLockMode validates an explicitly configured lock mode.

func ResolveLockMode added in v0.21.0 

func ResolveLockMode(mode string) (LockMode, error)

ResolveLockMode applies the branch default when the mode is unspecified.

type LockPolicy added in v0.21.0 

type LockPolicy string

LockPolicy controls update intent for a lock entry. 

const (
	PolicyPin   LockPolicy = "pin"
	PolicyFloat LockPolicy = "float"
)

type LookupEntry added in v0.21.0 

type LookupEntry struct {
	Namespace string
	Operation string
	Inputs    []any
	Result    LookupResult
}

LookupEntry is a structured lockfile lookup tuple.

type LookupResult added in v0.21.0 

type LookupResult struct {
	Value  string     `json:"value"`
	Policy LockPolicy `json:"policy"`
}

LookupResult is the stored lock result for a lookup tuple.

type MigrationPlan 

type MigrationPlan struct {
	ProjectRoot              string
	LookupSources            []string
	Warnings                 []string
	MigrationGapCount        int
	MigrationReportPath      string
	WorkspaceConfigData      []byte
	MigratedModuleConfigData []byte
	MigratedModuleConfigPath string
	MigrationReportData      []byte
	LockData                 []byte
}

MigrationPlan is the pure filesystem plan for migrating a legacy dagger.json project to workspace format.

func PlanMigration 

func PlanMigration(compatWorkspace *CompatWorkspace) (*MigrationPlan, error)

PlanMigration computes the pure filesystem plan for migrating a compat workspace into workspace format.

type ModuleEntry 

type ModuleEntry struct {
	Source            string         `toml:"source"`
	Settings          map[string]any `toml:"settings,omitempty"`
	Entrypoint        bool           `toml:"entrypoint,omitempty"`
	LegacyDefaultPath bool           `toml:"legacy-default-path,omitempty"`
	Up                ModuleSkip     `toml:"up,omitempty"`
	Generate          ModuleSkip     `toml:"generate,omitempty"`
	Check             ModuleSkip     `toml:"check,omitempty"`
}

ModuleEntry represents a single module entry in the workspace config.

type ModuleSkip 

type ModuleSkip struct {
	Skip []string `toml:"skip,omitempty"`
}

ModuleSkip carries the per-action skip patterns for a module entry. Patterns may be exact names or globs and apply to the action's leaf nodes scoped under the module (e.g. "redis", "infra:database", "other-generators:*").

type PathExistsFunc 

type PathExistsFunc func(ctx context.Context, path string) (parentDir string, exists bool, err error)

PathExistsFunc checks whether a filesystem path exists. Returns the canonical parent directory and whether the path exists.

type PortMapping 

type PortMapping struct {
	BackendService string `toml:"backendService"`
	BackendPort    int    `toml:"backendPort"`
}

PortMapping declares a host port that forwards to a workspace service. The map key on Config.Ports is the host port (string for TOML key shape: `[ports.3000]`). BackendService is the service path scoped under a workspace module (e.g. "hello-with-services:web").

type Workspace 

type Workspace struct {
	// Root is the workspace boundary: the detected git root.
	Root string

	// Cwd is the detection start location relative to Root. "." means Root.
	Cwd string

	// ConfigFile is the selected native config.toml path relative to Root.
	// Empty means no native workspace config exists.
	ConfigFile string

	// LockFile is the selected lockfile path relative to Root. It is the nearest
	// existing .dagger/lock from Cwd up to Root, or the selected .dagger fallback
	// directory when none exists.
	LockFile string
}

Workspace represents a detected workspace boundary and selected files within it. ConfigFile and LockFile are deliberately separate: config.toml may be absent or projected from compat dagger.json, while the lockfile is a local writable binding selected from the workspace tree.

func Detect 

func Detect(
	ctx context.Context,
	pathExists PathExistsFunc,
	cwd string,
) (*Workspace, error)

Detect finds the workspace boundary and selected workspace files from the given working directory.

Workspace root detection finds up to .git. If no git root is found, there is no workspace; callers should treat the nil workspace as a normal no-workspace condition, not an error.

After the boundary is known, ConfigFile is the nearest .dagger/config.toml walking upward from cwd, stopping at the workspace root. LockFile is the nearest existing .dagger/lock, or the nearest .dagger/lock write target when no lock exists yet.

func DetectInRoot 

func DetectInRoot(
	ctx context.Context,
	pathExists PathExistsFunc,
	cwd string,
	root string,
) (*Workspace, error)

DetectInRoot detects the workspace cwd and selected files within an already known workspace root. This is used for remote workspaces, where the cloned git tree root is already the boundary even when .git is not present in the tree.

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.