config

package
v0.6.3 Latest Latest
Warning

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

 Go to latest Published: Mar 9, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotFound = errors.New("devcontainer.json not found")

ErrNotFound is returned when no devcontainer.json is found.

Functions

func CalculatePrebuildHash 

func CalculatePrebuildHash(params PrebuildHashParams) (string, error)

CalculatePrebuildHash computes a deterministic hash for caching built images. Returns a hash in format "crib-{32 hex chars}".

func Find 

func Find(folder string) (string, error)

Find searches for a devcontainer.json starting from the given folder. Search order:

  1. .devcontainer/devcontainer.json
  2. .devcontainer.json
  3. .devcontainer/{subfolder}/devcontainer.json (one level deep)

Returns the absolute path to the config file, or empty string if not found.

func GetContextPath 

func GetContextPath(config *DevContainerConfig) string

GetContextPath returns the resolved build context path relative to the devcontainer.json directory.

func GetDockerfilePath 

func GetDockerfilePath(config *DevContainerConfig) string

GetDockerfilePath returns the resolved Dockerfile path.

func SubstituteString added in v0.6.0 

func SubstituteString(ctx *SubstitutionContext, s string) string

SubstituteString applies variable substitution to a single string value.

Types

type ComposeContainer 

type ComposeContainer struct {
	DockerComposeFile StrArray `json:"dockerComposeFile,omitempty"`
	Service           string   `json:"service,omitempty"`
	RunServices       []string `json:"runServices,omitempty"`
}

ComposeContainer holds Docker Compose configuration.

type ConfigBuildOptions 

type ConfigBuildOptions struct {
	Dockerfile string             `json:"dockerfile,omitempty"`
	Context    string             `json:"context,omitempty"`
	Args       map[string]*string `json:"args,omitempty"`
	Target     string             `json:"target,omitempty"`
	CacheFrom  StrArray           `json:"cacheFrom,omitempty"`
	Options    []string           `json:"options,omitempty"`
}

ConfigBuildOptions holds build arguments and options.

type DevContainerActions 

type DevContainerActions struct {
	OnCreateCommand      LifecycleHook  `json:"onCreateCommand,omitempty"`
	UpdateContentCommand LifecycleHook  `json:"updateContentCommand,omitempty"`
	PostCreateCommand    LifecycleHook  `json:"postCreateCommand,omitempty"`
	PostStartCommand     LifecycleHook  `json:"postStartCommand,omitempty"`
	PostAttachCommand    LifecycleHook  `json:"postAttachCommand,omitempty"`
	Customizations       map[string]any `json:"customizations,omitempty"`
}

DevContainerActions holds lifecycle hook definitions.

type DevContainerConfig 

type DevContainerConfig struct {
	DevContainerConfigBase `json:",inline"`
	DevContainerActions    `json:",inline"`
	NonComposeBase         `json:",inline"`
	ImageContainer         `json:",inline"`
	ComposeContainer       `json:",inline"`
	DockerfileContainer    `json:",inline"`

	// Origin is the absolute path to the devcontainer.json file (not serialized).
	Origin string `json:"-"`
}

DevContainerConfig is the top-level parsed devcontainer.json.

func FindAndParse 

func FindAndParse(folder string) (*DevContainerConfig, error)

FindAndParse finds a devcontainer.json from the given folder and parses it. Returns ErrNotFound if no config file is found.

func Parse 

func Parse(path string) (*DevContainerConfig, error)

Parse reads and parses a devcontainer.json file at the given path. Supports JSONC (comments and trailing commas).

func ParseBytes 

func ParseBytes(data []byte) (*DevContainerConfig, error)

ParseBytes parses devcontainer.json content from bytes. Supports JSONC (comments and trailing commas).

func Substitute 

func Substitute(ctx *SubstitutionContext, config *DevContainerConfig) (*DevContainerConfig, error)

Substitute applies variable substitution to the given config. Supported variables:

  • ${localEnv:VAR}, ${localEnv:VAR:default}
  • ${containerEnv:VAR}, ${containerEnv:VAR:default}
  • ${localWorkspaceFolder}, ${localWorkspaceFolderBasename}
  • ${containerWorkspaceFolder}, ${containerWorkspaceFolderBasename}
  • ${devcontainerId}

func SubstituteContainerEnv 

func SubstituteContainerEnv(containerEnv map[string]string, config *DevContainerConfig) (*DevContainerConfig, error)

SubstituteContainerEnv substitutes only ${containerEnv:VAR} variables using the provided container environment variables.

type DevContainerConfigBase 

type DevContainerConfigBase struct {
	Name                        string                   `json:"name,omitempty"`
	Features                    map[string]any           `json:"features,omitempty"`
	OverrideFeatureInstallOrder []string                 `json:"overrideFeatureInstallOrder,omitempty"`
	ForwardPorts                StrIntArray              `json:"forwardPorts,omitempty"`
	PortsAttributes             map[string]PortAttribute `json:"portsAttributes,omitempty"`
	OtherPortsAttributes        *PortAttribute           `json:"otherPortsAttributes,omitempty"`
	UpdateRemoteUserUID         *bool                    `json:"updateRemoteUserUID,omitempty"`
	RemoteEnv                   map[string]string        `json:"remoteEnv,omitempty"`
	RemoteUser                  string                   `json:"remoteUser,omitempty"`
	InitializeCommand           LifecycleHook            `json:"initializeCommand,omitempty"`
	ShutdownAction              string                   `json:"shutdownAction,omitempty"`
	WaitFor                     string                   `json:"waitFor,omitempty"`
	UserEnvProbe                string                   `json:"userEnvProbe,omitempty"`
	HostRequirements            *HostRequirements        `json:"hostRequirements,omitempty"`
	OverrideCommand             *bool                    `json:"overrideCommand,omitempty"`
	WorkspaceFolder             string                   `json:"workspaceFolder,omitempty"`

	// Deprecated fields (kept for legacy replacement).
	Settings   map[string]any `json:"settings,omitempty"`
	Extensions []string       `json:"extensions,omitempty"`
	DevPort    int            `json:"devPort,omitempty"`
}

DevContainerConfigBase holds common configuration fields.

type DockerfileContainer 

type DockerfileContainer struct {
	Dockerfile string              `json:"dockerfile,omitempty"`
	Context    string              `json:"context,omitempty"`
	Build      *ConfigBuildOptions `json:"build,omitempty"`
}

DockerfileContainer holds Dockerfile-based build configuration.

type HostRequirements 

type HostRequirements struct {
	CPUs    int    `json:"cpus,omitempty"`
	Memory  string `json:"memory,omitempty"`
	Storage string `json:"storage,omitempty"`
	GPU     any    `json:"gpu,omitempty"`
}

HostRequirements defines minimum host resource requirements.

type ImageContainer 

type ImageContainer struct {
	Image string `json:"image,omitempty"`
}

ImageContainer holds the image reference for image-based devcontainers.

type ImageMetadata 

type ImageMetadata struct {
	ID         string `json:"id,omitempty"`
	Entrypoint string `json:"entrypoint,omitempty"`

	DevContainerConfigBase `json:",inline"`
	DevContainerActions    `json:",inline"`
	NonComposeBase         `json:",inline"`
}

ImageMetadata represents metadata embedded in an image label or extracted from a feature's devcontainer-feature.json.

func ImageMetadataFromConfig 

func ImageMetadataFromConfig(config *DevContainerConfig) *ImageMetadata

ImageMetadataFromConfig creates an ImageMetadata entry from a DevContainerConfig.

func ParseImageMetadata 

func ParseImageMetadata(label string) ([]*ImageMetadata, error)

ParseImageMetadata parses the devcontainer.metadata image label value. The label contains a JSON array of ImageMetadata entries.

type ImageMetadataConfig 

type ImageMetadataConfig struct {
	Raw    []*ImageMetadata
	Config []*ImageMetadata
}

ImageMetadataConfig holds both raw and processed image metadata entries.

type LifecycleHook 

type LifecycleHook map[string][]string

LifecycleHook accepts multiple JSON formats for lifecycle commands:

  • A string: "echo hello"
  • An array: ["echo", "hello"]
  • An object: {"name": "echo hello"} or {"name": ["echo", "hello"]}

All forms are normalized to map[string][]string. For string and array forms, the key is empty string.

func (*LifecycleHook) UnmarshalJSON 

func (l *LifecycleHook) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type MergedConfigProperties 

type MergedConfigProperties struct {
	Entrypoints           []string        `json:"entrypoints,omitempty"`
	OnCreateCommands      []LifecycleHook `json:"onCreateCommands,omitempty"`
	UpdateContentCommands []LifecycleHook `json:"updateContentCommands,omitempty"`
	PostCreateCommands    []LifecycleHook `json:"postCreateCommands,omitempty"`
	PostStartCommands     []LifecycleHook `json:"postStartCommands,omitempty"`
	PostAttachCommands    []LifecycleHook `json:"postAttachCommands,omitempty"`
}

MergedConfigProperties holds accumulated lifecycle hooks and customizations from multiple image metadata entries.

type MergedDevContainerConfig 

type MergedDevContainerConfig struct {
	DevContainerConfigBase `json:",inline"`
	MergedConfigProperties `json:",inline"`
	NonComposeBase         `json:",inline"`
	ImageContainer         `json:",inline"`
	ComposeContainer       `json:",inline"`
	DockerfileContainer    `json:",inline"`

	Origin string `json:"-"`
}

MergedDevContainerConfig is the result of merging a base config with image metadata entries from features and base images.

func MergeConfiguration 

func MergeConfiguration(config *DevContainerConfig, imageMetadata []*ImageMetadata) *MergedDevContainerConfig

MergeConfiguration merges a DevContainerConfig with image metadata entries to produce a MergedDevContainerConfig. Metadata entries come from features and the base image. The base config takes priority, then entries are applied in reverse order (first entry = highest priority after base).

type Mount 

type Mount struct {
	Type     string `json:"type,omitempty"`
	Source   string `json:"source,omitempty"`
	Target   string `json:"target,omitempty"`
	External bool   `json:"external,omitempty"`
}

Mount represents a volume or bind mount. It supports both string format ("type=bind,src=/a,dst=/b") and object format in JSON.

func ParseMount 

func ParseMount(s string) (Mount, error)

ParseMount parses a mount string in Docker mount format. Example: "type=bind,src=/tmp,dst=/tmp" or "type=volume,source=mydata,target=/data". Returns an error if the target is empty (required for a valid mount).

func (Mount) String 

func (m Mount) String() string

String returns the mount in Docker mount string format.

func (*Mount) UnmarshalJSON 

func (m *Mount) UnmarshalJSON(data []byte) error

UnmarshalJSON handles both string format and object format for mounts.

type NonComposeBase 

type NonComposeBase struct {
	AppPort        StrIntArray       `json:"appPort,omitempty"`
	ContainerEnv   map[string]string `json:"containerEnv,omitempty"`
	ContainerUser  string            `json:"containerUser,omitempty"`
	Mounts         []Mount           `json:"mounts,omitempty"`
	Init           *bool             `json:"init,omitempty"`
	Privileged     *bool             `json:"privileged,omitempty"`
	CapAdd         []string          `json:"capAdd,omitempty"`
	SecurityOpt    []string          `json:"securityOpt,omitempty"`
	RunArgs        []string          `json:"runArgs,omitempty"`
	WorkspaceMount string            `json:"workspaceMount,omitempty"`
}

NonComposeBase holds container runtime configuration for non-compose scenarios.

type PortAttribute 

type PortAttribute struct {
	Label            string `json:"label,omitempty"`
	Protocol         string `json:"protocol,omitempty"`
	OnAutoForward    string `json:"onAutoForward,omitempty"`
	RequireLocalPort bool   `json:"requireLocalPort,omitempty"`
	ElevateIfNeeded  bool   `json:"elevateIfNeeded,omitempty"`
}

PortAttribute describes port forwarding metadata.

type PrebuildHashParams 

type PrebuildHashParams struct {
	// Config is the devcontainer configuration.
	Config *DevContainerConfig

	// Platform is the target platform (e.g., "linux/amd64").
	Platform string

	// ContextPath is the absolute path to the build context directory.
	ContextPath string

	// DockerfileContent is the raw Dockerfile content.
	DockerfileContent string

	// IncludeFiles limits the context hash to only these files (relative paths).
	// If nil, all files in the context are included (minus .dockerignore exclusions).
	IncludeFiles []string
}

PrebuildHashParams holds all inputs for computing the prebuild hash.

type StrArray 

type StrArray []string

StrArray accepts either a single string or an array of strings in JSON.

func (*StrArray) UnmarshalJSON 

func (sa *StrArray) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type StrBool 

type StrBool string

StrBool accepts either a string or bool in JSON, storing as string.

func (StrBool) IsTrue 

func (s StrBool) IsTrue() bool

IsTrue returns true if the value is "true" (case-insensitive).

func (*StrBool) UnmarshalJSON 

func (s *StrBool) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type StrIntArray 

type StrIntArray []string

StrIntArray accepts a string, number, or an array of mixed string/number values. All values are stored as strings.

func (*StrIntArray) UnmarshalJSON 

func (sa *StrIntArray) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type SubstitutionContext 

type SubstitutionContext struct {
	DevContainerID           string
	LocalWorkspaceFolder     string
	ContainerWorkspaceFolder string
	Env                      map[string]string
}

SubstitutionContext holds the values available for variable substitution.

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.