shishantbiswas/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-06-02 20:48:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(agent/agentcontainers): generate devcontainer metadata from schema (#16881)

Browse Source 
Adds new dcspec package containing automatically generated devcontainer schema (using glideapps/quicktype).
This commit is contained in:
Cian Johnston
2025-03-18 13:00:21 +00:00
committed by GitHub
parent ec517657a8
commit 13a3ddd964
11 changed files with 1954 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitattributes
+1
View File
@@ -1,5 +1,6 @@
# Generated files
agent/agentcontainers/acmock/acmock.go linguist-generated=true
agent/agentcontainers/dcspec/dcspec_gen.go linguist-generated=true
coderd/apidoc/docs.go linguist-generated=true
docs/reference/api/*.md linguist-generated=true
docs/reference/cli/*.md linguist-generated=true
Makefile
+6 -2
View File
@@ -564,8 +564,8 @@ GEN_FILES := \
examples/examples.gen.json \
$(TAILNETTEST_MOCKS) \
coderd/database/pubsub/psmock/psmock.go \
agent/agentcontainers/acmock/acmock.go
agent/agentcontainers/acmock/acmock.go \
agent/agentcontainers/dcspec/dcspec_gen.go
# all gen targets should be added here and to gen/mark-fresh
gen: gen/db $(GEN_FILES)
@@ -600,6 +600,7 @@ gen/mark-fresh:
$(TAILNETTEST_MOCKS) \
coderd/database/pubsub/psmock/psmock.go \
agent/agentcontainers/acmock/acmock.go \
agent/agentcontainers/dcspec/dcspec_gen.go \
"
for file in $$files; do
@@ -634,6 +635,9 @@ coderd/database/pubsub/psmock/psmock.go: coderd/database/pubsub/pubsub.go
agent/agentcontainers/acmock/acmock.go: agent/agentcontainers/containers.go
go generate ./agent/agentcontainers/acmock/
agent/agentcontainers/dcspec/dcspec_gen.go: agent/agentcontainers/dcspec/devContainer.base.schema.json
go generate ./agent/agentcontainers/dcspec/
$(TAILNETTEST_MOCKS): tailnet/coordinator.go tailnet/service.go
go generate ./tailnet/tailnettest/
agent/agentcontainers/containers_dockercli.go
+11 -3
View File
@@ -13,8 +13,10 @@ import (
"strings"
"time"
"github.com/coder/coder/v2/agent/agentcontainers/dcspec"
"github.com/coder/coder/v2/agent/agentexec"
"github.com/coder/coder/v2/agent/usershell"
"github.com/coder/coder/v2/coderd/util/ptr"
"github.com/coder/coder/v2/codersdk"
"golang.org/x/exp/maps"
@@ -183,7 +185,7 @@ func devcontainerEnv(ctx context.Context, execer agentexec.Execer, container str
return nil, nil
}
meta := make([]DevContainerMeta, 0)
meta := make([]dcspec.DevContainer, 0)
if err := json.Unmarshal([]byte(rawMeta), &meta); err != nil {
return nil, xerrors.Errorf("unmarshal devcontainer.metadata: %w", err)
}
@@ -192,7 +194,13 @@ func devcontainerEnv(ctx context.Context, execer agentexec.Execer, container str
env := make([]string, 0)
for _, m := range meta {
for k, v := range m.RemoteEnv {
env = append(env, fmt.Sprintf("%s=%s", k, v))
if v == nil { // *string per spec
// devcontainer-cli will set this to the string "null" if the value is
// not set. Explicitly setting to an empty string here as this would be
// more expected here.
v = ptr.Ref("")
}
env = append(env, fmt.Sprintf("%s=%s", k, *v))
}
}
slices.Sort(env)
@@ -276,7 +284,7 @@ func (dcl *DockerCLILister) List(ctx context.Context) (codersdk.WorkspaceAgentLi
// log this error, but I'm not sure it's worth it.
ins, dockerInspectStderr, err := runDockerInspect(ctx, dcl.execer, ids...)
if err != nil {
return codersdk.WorkspaceAgentListContainersResponse{}, xerrors.Errorf("run docker inspect: %w", err)
return codersdk.WorkspaceAgentListContainersResponse{}, xerrors.Errorf("run docker inspect: %w: %s", err, dockerInspectStderr)
}
for _, in := range ins {
agent/agentcontainers/containers_internal_test.go
+5 -4
View File
@@ -34,8 +34,9 @@ import (
// It can be run manually as follows:
//
// CODER_TEST_USE_DOCKER=1 go test ./agent/agentcontainers -run TestDockerCLIContainerLister
//
//nolint:paralleltest // This test tends to flake when lots of containers start and stop in parallel.
func TestIntegrationDocker(t *testing.T) {
t.Parallel()
if ctud, ok := os.LookupEnv("CODER_TEST_USE_DOCKER"); !ok || ctud != "1" {
t.Skip("Set CODER_TEST_USE_DOCKER=1 to run this test")
}
@@ -418,8 +419,9 @@ func TestConvertDockerVolume(t *testing.T) {
// It can be run manually as follows:
//
// CODER_TEST_USE_DOCKER=1 go test ./agent/agentcontainers -run TestDockerEnvInfoer
//
//nolint:paralleltest // This test tends to flake when lots of containers start and stop in parallel.
func TestDockerEnvInfoer(t *testing.T) {
t.Parallel()
if ctud, ok := os.LookupEnv("CODER_TEST_USE_DOCKER"); !ok || ctud != "1" {
t.Skip("Set CODER_TEST_USE_DOCKER=1 to run this test")
}
@@ -483,9 +485,8 @@ func TestDockerEnvInfoer(t *testing.T) {
expectedUserShell: "/bin/bash",
},
} {
//nolint:paralleltest // variable recapture no longer required
t.Run(fmt.Sprintf("#%d", idx), func(t *testing.T) {
t.Parallel()
// Start a container with the given image
// and environment variables
image := strings.Split(tt.image, ":")[0]
agent/agentcontainers/dcspec/dcspec_gen.go
Generated
+355
View File
@@ -0,0 +1,355 @@
// Code generated by dcspec/gen.sh. DO NOT EDIT.
package dcspec
// Defines a dev container
type DevContainer struct {
// Docker build-related options.
Build *BuildOptions `json:"build,omitempty"`
// The location of the context folder for building the Docker image. The path is relative to
// the folder containing the `devcontainer.json` file.
Context *string `json:"context,omitempty"`
// The location of the Dockerfile that defines the contents of the container. The path is
// relative to the folder containing the `devcontainer.json` file.
DockerFile *string `json:"dockerFile,omitempty"`
// The docker image that will be used to create the container.
Image *string `json:"image,omitempty"`
// Application ports that are exposed by the container. This can be a single port or an
// array of ports. Each port can be a number or a string. A number is mapped to the same
// port on the host. A string is passed to Docker unchanged and can be used to map ports
// differently, e.g. "8000:8010".
AppPort *DevContainerAppPort `json:"appPort"`
// Whether to overwrite the command specified in the image. The default is true.
//
// Whether to overwrite the command specified in the image. The default is false.
OverrideCommand *bool `json:"overrideCommand,omitempty"`
// The arguments required when starting in the container.
RunArgs []string `json:"runArgs,omitempty"`
// Action to take when the user disconnects from the container in their editor. The default
// is to stop the container.
//
// Action to take when the user disconnects from the primary container in their editor. The
// default is to stop all of the compose containers.
ShutdownAction *ShutdownAction `json:"shutdownAction,omitempty"`
// The path of the workspace folder inside the container.
//
// The path of the workspace folder inside the container. This is typically the target path
// of a volume mount in the docker-compose.yml.
WorkspaceFolder *string `json:"workspaceFolder,omitempty"`
// The --mount parameter for docker run. The default is to mount the project folder at
// /workspaces/$project.
WorkspaceMount *string `json:"workspaceMount,omitempty"`
// The name of the docker-compose file(s) used to start the services.
DockerComposeFile *CacheFrom `json:"dockerComposeFile"`
// An array of services that should be started and stopped.
RunServices []string `json:"runServices,omitempty"`
// The service you want to work on. This is considered the primary container for your dev
// environment which your editor will connect to.
Service *string `json:"service,omitempty"`
// The JSON schema of the `devcontainer.json` file.
Schema *string `json:"$schema,omitempty"`
AdditionalProperties map[string]interface{} `json:"additionalProperties,omitempty"`
// Passes docker capabilities to include when creating the dev container.
CapAdd []string `json:"capAdd,omitempty"`
// Container environment variables.
ContainerEnv map[string]string `json:"containerEnv,omitempty"`
// The user the container will be started with. The default is the user on the Docker image.
ContainerUser *string `json:"containerUser,omitempty"`
// Tool-specific configuration. Each tool should use a JSON object subproperty with a unique
// name to group its customizations.
Customizations map[string]interface{} `json:"customizations,omitempty"`
// Features to add to the dev container.
Features *Features `json:"features,omitempty"`
// Ports that are forwarded from the container to the local machine. Can be an integer port
// number, or a string of the format "host:port_number".
ForwardPorts []ForwardPort `json:"forwardPorts,omitempty"`
// Host hardware requirements.
HostRequirements *HostRequirements `json:"hostRequirements,omitempty"`
// Passes the --init flag when creating the dev container.
Init *bool `json:"init,omitempty"`
// A command to run locally (i.e Your host machine, cloud VM) before anything else. This
// command is run before "onCreateCommand". If this is a single string, it will be run in a
// shell. If this is an array of strings, it will be run as a single command without shell.
// If this is an object, each provided command will be run in parallel.
InitializeCommand *Command `json:"initializeCommand"`
// Mount points to set up when creating the container. See Docker's documentation for the
// --mount option for the supported syntax.
Mounts []MountElement `json:"mounts,omitempty"`
// A name for the dev container which can be displayed to the user.
Name *string `json:"name,omitempty"`
// A command to run when creating the container. This command is run after
// "initializeCommand" and before "updateContentCommand". If this is a single string, it
// will be run in a shell. If this is an array of strings, it will be run as a single
// command without shell. If this is an object, each provided command will be run in
// parallel.
OnCreateCommand *Command `json:"onCreateCommand"`
OtherPortsAttributes *OtherPortsAttributes `json:"otherPortsAttributes,omitempty"`
// Array consisting of the Feature id (without the semantic version) of Features in the
// order the user wants them to be installed.
OverrideFeatureInstallOrder []string `json:"overrideFeatureInstallOrder,omitempty"`
PortsAttributes *PortsAttributes `json:"portsAttributes,omitempty"`
// A command to run when attaching to the container. This command is run after
// "postStartCommand". If this is a single string, it will be run in a shell. If this is an
// array of strings, it will be run as a single command without shell. If this is an object,
// each provided command will be run in parallel.
PostAttachCommand *Command `json:"postAttachCommand"`
// A command to run after creating the container. This command is run after
// "updateContentCommand" and before "postStartCommand". If this is a single string, it will
// be run in a shell. If this is an array of strings, it will be run as a single command
// without shell. If this is an object, each provided command will be run in parallel.
PostCreateCommand *Command `json:"postCreateCommand"`
// A command to run after starting the container. This command is run after
// "postCreateCommand" and before "postAttachCommand". If this is a single string, it will
// be run in a shell. If this is an array of strings, it will be run as a single command
// without shell. If this is an object, each provided command will be run in parallel.
PostStartCommand *Command `json:"postStartCommand"`
// Passes the --privileged flag when creating the dev container.
Privileged *bool `json:"privileged,omitempty"`
// Remote environment variables to set for processes spawned in the container including
// lifecycle scripts and any remote editor/IDE server process.
RemoteEnv map[string]*string `json:"remoteEnv,omitempty"`
// The username to use for spawning processes in the container including lifecycle scripts
// and any remote editor/IDE server process. The default is the same user as the container.
RemoteUser *string `json:"remoteUser,omitempty"`
// Recommended secrets for this dev container. Recommendations are provided as environment
// variable keys with optional metadata.
Secrets *Secrets `json:"secrets,omitempty"`
// Passes docker security options to include when creating the dev container.
SecurityOpt []string `json:"securityOpt,omitempty"`
// A command to run when creating the container and rerun when the workspace content was
// updated while creating the container. This command is run after "onCreateCommand" and
// before "postCreateCommand". If this is a single string, it will be run in a shell. If
// this is an array of strings, it will be run as a single command without shell. If this is
// an object, each provided command will be run in parallel.
UpdateContentCommand *Command `json:"updateContentCommand"`
// Controls whether on Linux the container's user should be updated with the local user's
// UID and GID. On by default when opening from a local folder.
UpdateRemoteUserUID *bool `json:"updateRemoteUserUID,omitempty"`
// User environment probe to run. The default is "loginInteractiveShell".
UserEnvProbe *UserEnvProbe `json:"userEnvProbe,omitempty"`
// The user command to wait for before continuing execution in the background while the UI
// is starting up. The default is "updateContentCommand".
WaitFor *WaitFor `json:"waitFor,omitempty"`
}
// Docker build-related options.
type BuildOptions struct {
// The location of the context folder for building the Docker image. The path is relative to
// the folder containing the `devcontainer.json` file.
Context *string `json:"context,omitempty"`
// The location of the Dockerfile that defines the contents of the container. The path is
// relative to the folder containing the `devcontainer.json` file.
Dockerfile *string `json:"dockerfile,omitempty"`
// Build arguments.
Args map[string]string `json:"args,omitempty"`
// The image to consider as a cache. Use an array to specify multiple images.
CacheFrom *CacheFrom `json:"cacheFrom"`
// Additional arguments passed to the build command.
Options []string `json:"options,omitempty"`
// Target stage in a multi-stage build.
Target *string `json:"target,omitempty"`
}
// Features to add to the dev container.
type Features struct {
Fish interface{} `json:"fish"`
Gradle interface{} `json:"gradle"`
Homebrew interface{} `json:"homebrew"`
Jupyterlab interface{} `json:"jupyterlab"`
Maven interface{} `json:"maven"`
}
// Host hardware requirements.
type HostRequirements struct {
// Number of required CPUs.
Cpus *int64 `json:"cpus,omitempty"`
GPU *GPUUnion `json:"gpu"`
// Amount of required RAM in bytes. Supports units tb, gb, mb and kb.
Memory *string `json:"memory,omitempty"`
// Amount of required disk space in bytes. Supports units tb, gb, mb and kb.
Storage *string `json:"storage,omitempty"`
}
// Indicates whether a GPU is required. The string "optional" indicates that a GPU is
// optional. An object value can be used to configure more detailed requirements.
type GPUClass struct {
// Number of required cores.
Cores *int64 `json:"cores,omitempty"`
// Amount of required RAM in bytes. Supports units tb, gb, mb and kb.
Memory *string `json:"memory,omitempty"`
}
type Mount struct {
// Mount source.
Source *string `json:"source,omitempty"`
// Mount target.
Target string `json:"target"`
// Mount type.
Type Type `json:"type"`
}
type OtherPortsAttributes struct {
// Automatically prompt for elevation (if needed) when this port is forwarded. Elevate is
// required if the local port is a privileged port.
ElevateIfNeeded *bool `json:"elevateIfNeeded,omitempty"`
// Label that will be shown in the UI for this port.
Label *string `json:"label,omitempty"`
// Defines the action that occurs when the port is discovered for automatic forwarding
OnAutoForward *OnAutoForward `json:"onAutoForward,omitempty"`
// The protocol to use when forwarding this port.
Protocol *Protocol `json:"protocol,omitempty"`
RequireLocalPort *bool `json:"requireLocalPort,omitempty"`
}
type PortsAttributes struct{}
// Recommended secrets for this dev container. Recommendations are provided as environment
// variable keys with optional metadata.
type Secrets struct{}
type GPUEnum string
const (
Optional GPUEnum = "optional"
)
// Mount type.
type Type string
const (
Bind Type = "bind"
Volume Type = "volume"
)
// Defines the action that occurs when the port is discovered for automatic forwarding
type OnAutoForward string
const (
Ignore OnAutoForward = "ignore"
Notify OnAutoForward = "notify"
OpenBrowser OnAutoForward = "openBrowser"
OpenPreview OnAutoForward = "openPreview"
Silent OnAutoForward = "silent"
)
// The protocol to use when forwarding this port.
type Protocol string
const (
HTTP Protocol = "http"
HTTPS Protocol = "https"
)
// Action to take when the user disconnects from the container in their editor. The default
// is to stop the container.
//
// Action to take when the user disconnects from the primary container in their editor. The
// default is to stop all of the compose containers.
type ShutdownAction string
const (
ShutdownActionNone ShutdownAction = "none"
StopCompose ShutdownAction = "stopCompose"
StopContainer ShutdownAction = "stopContainer"
)
// User environment probe to run. The default is "loginInteractiveShell".
type UserEnvProbe string
const (
InteractiveShell UserEnvProbe = "interactiveShell"
LoginInteractiveShell UserEnvProbe = "loginInteractiveShell"
LoginShell UserEnvProbe = "loginShell"
UserEnvProbeNone UserEnvProbe = "none"
)
// The user command to wait for before continuing execution in the background while the UI
// is starting up. The default is "updateContentCommand".
type WaitFor string
const (
InitializeCommand WaitFor = "initializeCommand"
OnCreateCommand WaitFor = "onCreateCommand"
PostCreateCommand WaitFor = "postCreateCommand"
PostStartCommand WaitFor = "postStartCommand"
UpdateContentCommand WaitFor = "updateContentCommand"
)
// Application ports that are exposed by the container. This can be a single port or an
// array of ports. Each port can be a number or a string. A number is mapped to the same
// port on the host. A string is passed to Docker unchanged and can be used to map ports
// differently, e.g. "8000:8010".
type DevContainerAppPort struct {
Integer *int64
String *string
UnionArray []AppPortElement
}
// Application ports that are exposed by the container. This can be a single port or an
// array of ports. Each port can be a number or a string. A number is mapped to the same
// port on the host. A string is passed to Docker unchanged and can be used to map ports
// differently, e.g. "8000:8010".
type AppPortElement struct {
Integer *int64
String *string
}
// The image to consider as a cache. Use an array to specify multiple images.
//
// The name of the docker-compose file(s) used to start the services.
type CacheFrom struct {
String *string
StringArray []string
}
type ForwardPort struct {
Integer *int64
String *string
}
type GPUUnion struct {
Bool *bool
Enum *GPUEnum
GPUClass *GPUClass
}
// A command to run locally (i.e Your host machine, cloud VM) before anything else. This
// command is run before "onCreateCommand". If this is a single string, it will be run in a
// shell. If this is an array of strings, it will be run as a single command without shell.
// If this is an object, each provided command will be run in parallel.
//
// A command to run when creating the container. This command is run after
// "initializeCommand" and before "updateContentCommand". If this is a single string, it
// will be run in a shell. If this is an array of strings, it will be run as a single
// command without shell. If this is an object, each provided command will be run in
// parallel.
//
// A command to run when attaching to the container. This command is run after
// "postStartCommand". If this is a single string, it will be run in a shell. If this is an
// array of strings, it will be run as a single command without shell. If this is an object,
// each provided command will be run in parallel.
//
// A command to run after creating the container. This command is run after
// "updateContentCommand" and before "postStartCommand". If this is a single string, it will
// be run in a shell. If this is an array of strings, it will be run as a single command
// without shell. If this is an object, each provided command will be run in parallel.
//
// A command to run after starting the container. This command is run after
// "postCreateCommand" and before "postAttachCommand". If this is a single string, it will
// be run in a shell. If this is an array of strings, it will be run as a single command
// without shell. If this is an object, each provided command will be run in parallel.
//
// A command to run when creating the container and rerun when the workspace content was
// updated while creating the container. This command is run after "onCreateCommand" and
// before "postCreateCommand". If this is a single string, it will be run in a shell. If
// this is an array of strings, it will be run as a single command without shell. If this is
// an object, each provided command will be run in parallel.
type Command struct {
String *string
StringArray []string
UnionMap map[string]*CacheFrom
}
type MountElement struct {
Mount *Mount
String *string
}
agent/agentcontainers/dcspec/devContainer.base.schema.json
+771
View File
@@ -0,0 +1,771 @@
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"description": "Defines a dev container",
"allowComments": true,
"allowTrailingCommas": false,
"definitions": {
"devContainerCommon": {
"type": "object",
"properties": {
"$schema": {
"type": "string",
"format": "uri",
"description": "The JSON schema of the `devcontainer.json` file."
},
"name": {
"type": "string",
"description": "A name for the dev container which can be displayed to the user."
},
"features": {
"type": "object",
"description": "Features to add to the dev container.",
"properties": {
"fish": {
"deprecated": true,
"deprecationMessage": "Legacy feature not supported. Please check https://containers.dev/features for replacements."
},
"maven": {
"deprecated": true,
"deprecationMessage": "Legacy feature will be removed in the future. Please check https://containers.dev/features for replacements. E.g., `ghcr.io/devcontainers/features/java` has an option to install Maven."
},
"gradle": {
"deprecated": true,
"deprecationMessage": "Legacy feature will be removed in the future. Please check https://containers.dev/features for replacements. E.g., `ghcr.io/devcontainers/features/java` has an option to install Gradle."
},
"homebrew": {
"deprecated": true,
"deprecationMessage": "Legacy feature not supported. Please check https://containers.dev/features for replacements."
},
"jupyterlab": {
"deprecated": true,
"deprecationMessage": "Legacy feature will be removed in the future. Please check https://containers.dev/features for replacements. E.g., `ghcr.io/devcontainers/features/python` has an option to install JupyterLab."
}
},
"additionalProperties": true
},
"overrideFeatureInstallOrder": {
"type": "array",
"description": "Array consisting of the Feature id (without the semantic version) of Features in the order the user wants them to be installed.",
"items": {
"type": "string"
}
},
"secrets": {
"type": "object",
"description": "Recommended secrets for this dev container. Recommendations are provided as environment variable keys with optional metadata.",
"patternProperties": {
"^[a-zA-Z_][a-zA-Z0-9_]*$": {
"type": "object",
"description": "Environment variable keys following unix-style naming conventions. eg: ^[a-zA-Z_][a-zA-Z0-9_]*$",
"properties": {
"description": {
"type": "string",
"description": "A description of the secret."
},
"documentationUrl": {
"type": "string",
"format": "uri",
"description": "A URL to documentation about the secret."
}
},
"additionalProperties": false
},
"additionalProperties": false
},
"additionalProperties": false
},
"forwardPorts": {
"type": "array",
"description": "Ports that are forwarded from the container to the local machine. Can be an integer port number, or a string of the format \"host:port_number\".",
"items": {
"oneOf": [
{
"type": "integer",
"maximum": 65535,
"minimum": 0
},
{
"type": "string",
"pattern": "^([a-z0-9-]+):(\\d{1,5})$"
}
]
}
},
"portsAttributes": {
"type": "object",
"patternProperties": {
"(^\\d+(-\\d+)?$)|(.+)": {
"type": "object",
"description": "A port, range of ports (ex. \"40000-55000\"), or regular expression (ex. \".+\\\\/server.js\"). For a port number or range, the attributes will apply to that port number or range of port numbers. Attributes which use a regular expression will apply to ports whose associated process command line matches the expression.",
"properties": {
"onAutoForward": {
"type": "string",
"enum": [
"notify",
"openBrowser",
"openBrowserOnce",
"openPreview",
"silent",
"ignore"
],
"enumDescriptions": [
"Shows a notification when a port is automatically forwarded.",
"Opens the browser when the port is automatically forwarded. Depending on your settings, this could open an embedded browser.",
"Opens the browser when the port is automatically forwarded, but only the first time the port is forward during a session. Depending on your settings, this could open an embedded browser.",
"Opens a preview in the same window when the port is automatically forwarded.",
"Shows no notification and takes no action when this port is automatically forwarded.",
"This port will not be automatically forwarded."
],
"description": "Defines the action that occurs when the port is discovered for automatic forwarding",
"default": "notify"
},
"elevateIfNeeded": {
"type": "boolean",
"description": "Automatically prompt for elevation (if needed) when this port is forwarded. Elevate is required if the local port is a privileged port.",
"default": false
},
"label": {
"type": "string",
"description": "Label that will be shown in the UI for this port.",
"default": "Application"
},
"requireLocalPort": {
"type": "boolean",
"markdownDescription": "When true, a modal dialog will show if the chosen local port isn't used for forwarding.",
"default": false
},
"protocol": {
"type": "string",
"enum": [
"http",
"https"
],
"description": "The protocol to use when forwarding this port."
}
},
"default": {
"label": "Application",
"onAutoForward": "notify"
}
}
},
"markdownDescription": "Set default properties that are applied when a specific port number is forwarded. For example:\n\n```\n\"3000\": {\n \"label\": \"Application\"\n},\n\"40000-55000\": {\n \"onAutoForward\": \"ignore\"\n},\n\".+\\\\/server.js\": {\n \"onAutoForward\": \"openPreview\"\n}\n```",
"defaultSnippets": [
{
"body": {
"${1:3000}": {
"label": "${2:Application}",
"onAutoForward": "notify"
}
}
}
],
"additionalProperties": false
},
"otherPortsAttributes": {
"type": "object",
"properties": {
"onAutoForward": {
"type": "string",
"enum": [
"notify",
"openBrowser",
"openPreview",
"silent",
"ignore"
],
"enumDescriptions": [
"Shows a notification when a port is automatically forwarded.",
"Opens the browser when the port is automatically forwarded. Depending on your settings, this could open an embedded browser.",
"Opens a preview in the same window when the port is automatically forwarded.",
"Shows no notification and takes no action when this port is automatically forwarded.",
"This port will not be automatically forwarded."
],
"description": "Defines the action that occurs when the port is discovered for automatic forwarding",
"default": "notify"
},
"elevateIfNeeded": {
"type": "boolean",
"description": "Automatically prompt for elevation (if needed) when this port is forwarded. Elevate is required if the local port is a privileged port.",
"default": false
},
"label": {
"type": "string",
"description": "Label that will be shown in the UI for this port.",
"default": "Application"
},
"requireLocalPort": {
"type": "boolean",
"markdownDescription": "When true, a modal dialog will show if the chosen local port isn't used for forwarding.",
"default": false
},
"protocol": {
"type": "string",
"enum": [
"http",
"https"
],
"description": "The protocol to use when forwarding this port."
}
},
"defaultSnippets": [
{
"body": {
"onAutoForward": "ignore"
}
}
],
"markdownDescription": "Set default properties that are applied to all ports that don't get properties from the setting `remote.portsAttributes`. For example:\n\n```\n{\n \"onAutoForward\": \"ignore\"\n}\n```",
"additionalProperties": false
},
"updateRemoteUserUID": {
"type": "boolean",
"description": "Controls whether on Linux the container's user should be updated with the local user's UID and GID. On by default when opening from a local folder."
},
"containerEnv": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Container environment variables."
},
"containerUser": {
"type": "string",
"description": "The user the container will be started with. The default is the user on the Docker image."
},
"mounts": {
"type": "array",
"description": "Mount points to set up when creating the container. See Docker's documentation for the --mount option for the supported syntax.",
"items": {
"anyOf": [
{
"$ref": "#/definitions/Mount"
},
{
"type": "string"
}
]
}
},
"init": {
"type": "boolean",
"description": "Passes the --init flag when creating the dev container."
},
"privileged": {
"type": "boolean",
"description": "Passes the --privileged flag when creating the dev container."
},
"capAdd": {
"type": "array",
"description": "Passes docker capabilities to include when creating the dev container.",
"examples": [
"SYS_PTRACE"
],
"items": {
"type": "string"
}
},
"securityOpt": {
"type": "array",
"description": "Passes docker security options to include when creating the dev container.",
"examples": [
"seccomp=unconfined"
],
"items": {
"type": "string"
}
},
"remoteEnv": {
"type": "object",
"additionalProperties": {
"type": [
"string",
"null"
]
},
"description": "Remote environment variables to set for processes spawned in the container including lifecycle scripts and any remote editor/IDE server process."
},
"remoteUser": {
"type": "string",
"description": "The username to use for spawning processes in the container including lifecycle scripts and any remote editor/IDE server process. The default is the same user as the container."
},
"initializeCommand": {
"type": [
"string",
"array",
"object"
],
"description": "A command to run locally (i.e Your host machine, cloud VM) before anything else. This command is run before \"onCreateCommand\". If this is a single string, it will be run in a shell. If this is an array of strings, it will be run as a single command without shell. If this is an object, each provided command will be run in parallel.",
"items": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"array"
],
"items": {
"type": "string"
}
}
},
"onCreateCommand": {
"type": [
"string",
"array",
"object"
],
"description": "A command to run when creating the container. This command is run after \"initializeCommand\" and before \"updateContentCommand\". If this is a single string, it will be run in a shell. If this is an array of strings, it will be run as a single command without shell. If this is an object, each provided command will be run in parallel.",
"items": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"array"
],
"items": {
"type": "string"
}
}
},
"updateContentCommand": {
"type": [
"string",
"array",
"object"
],
"description": "A command to run when creating the container and rerun when the workspace content was updated while creating the container. This command is run after \"onCreateCommand\" and before \"postCreateCommand\". If this is a single string, it will be run in a shell. If this is an array of strings, it will be run as a single command without shell. If this is an object, each provided command will be run in parallel.",
"items": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"array"
],
"items": {
"type": "string"
}
}
},
"postCreateCommand": {
"type": [
"string",
"array",
"object"
],
"description": "A command to run after creating the container. This command is run after \"updateContentCommand\" and before \"postStartCommand\". If this is a single string, it will be run in a shell. If this is an array of strings, it will be run as a single command without shell. If this is an object, each provided command will be run in parallel.",
"items": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"array"
],
"items": {
"type": "string"
}
}
},
"postStartCommand": {
"type": [
"string",
"array",
"object"
],
"description": "A command to run after starting the container. This command is run after \"postCreateCommand\" and before \"postAttachCommand\". If this is a single string, it will be run in a shell. If this is an array of strings, it will be run as a single command without shell. If this is an object, each provided command will be run in parallel.",
"items": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"array"
],
"items": {
"type": "string"
}
}
},
"postAttachCommand": {
"type": [
"string",
"array",
"object"
],
"description": "A command to run when attaching to the container. This command is run after \"postStartCommand\". If this is a single string, it will be run in a shell. If this is an array of strings, it will be run as a single command without shell. If this is an object, each provided command will be run in parallel.",
"items": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"array"
],
"items": {
"type": "string"
}
}
},
"waitFor": {
"type": "string",
"enum": [
"initializeCommand",
"onCreateCommand",
"updateContentCommand",
"postCreateCommand",
"postStartCommand"
],
"description": "The user command to wait for before continuing execution in the background while the UI is starting up. The default is \"updateContentCommand\"."
},
"userEnvProbe": {
"type": "string",
"enum": [
"none",
"loginShell",
"loginInteractiveShell",
"interactiveShell"
],
"description": "User environment probe to run. The default is \"loginInteractiveShell\"."
},
"hostRequirements": {
"type": "object",
"description": "Host hardware requirements.",
"properties": {
"cpus": {
"type": "integer",
"minimum": 1,
"description": "Number of required CPUs."
},
"memory": {
"type": "string",
"pattern": "^\\d+([tgmk]b)?$",
"description": "Amount of required RAM in bytes. Supports units tb, gb, mb and kb."
},
"storage": {
"type": "string",
"pattern": "^\\d+([tgmk]b)?$",
"description": "Amount of required disk space in bytes. Supports units tb, gb, mb and kb."
},
"gpu": {
"oneOf": [
{
"type": [
"boolean",
"string"
],
"enum": [
true,
false,
"optional"
],
"description": "Indicates whether a GPU is required. The string \"optional\" indicates that a GPU is optional. An object value can be used to configure more detailed requirements."
},
{
"type": "object",
"properties": {
"cores": {
"type": "integer",
"minimum": 1,
"description": "Number of required cores."
},
"memory": {
"type": "string",
"pattern": "^\\d+([tgmk]b)?$",
"description": "Amount of required RAM in bytes. Supports units tb, gb, mb and kb."
}
},
"description": "Indicates whether a GPU is required. The string \"optional\" indicates that a GPU is optional. An object value can be used to configure more detailed requirements.",
"additionalProperties": false
}
]
}
},
"unevaluatedProperties": false
},
"customizations": {
"type": "object",
"description": "Tool-specific configuration. Each tool should use a JSON object subproperty with a unique name to group its customizations."
},
"additionalProperties": {
"type": "object",
"additionalProperties": true
}
}
},
"nonComposeBase": {
"type": "object",
"properties": {
"appPort": {
"type": [
"integer",
"string",
"array"
],
"description": "Application ports that are exposed by the container. This can be a single port or an array of ports. Each port can be a number or a string. A number is mapped to the same port on the host. A string is passed to Docker unchanged and can be used to map ports differently, e.g. \"8000:8010\".",
"items": {
"type": [
"integer",
"string"
]
}
},
"runArgs": {
"type": "array",
"description": "The arguments required when starting in the container.",
"items": {
"type": "string"
}
},
"shutdownAction": {
"type": "string",
"enum": [
"none",
"stopContainer"
],
"description": "Action to take when the user disconnects from the container in their editor. The default is to stop the container."
},
"overrideCommand": {
"type": "boolean",
"description": "Whether to overwrite the command specified in the image. The default is true."
},
"workspaceFolder": {
"type": "string",
"description": "The path of the workspace folder inside the container."
},
"workspaceMount": {
"type": "string",
"description": "The --mount parameter for docker run. The default is to mount the project folder at /workspaces/$project."
}
}
},
"dockerfileContainer": {
"oneOf": [
{
"type": "object",
"properties": {
"build": {
"type": "object",
"description": "Docker build-related options.",
"allOf": [
{
"type": "object",
"properties": {
"dockerfile": {
"type": "string",
"description": "The location of the Dockerfile that defines the contents of the container. The path is relative to the folder containing the `devcontainer.json` file."
},
"context": {
"type": "string",
"description": "The location of the context folder for building the Docker image. The path is relative to the folder containing the `devcontainer.json` file."
}
},
"required": [
"dockerfile"
]
},
{
"$ref": "#/definitions/buildOptions"
}
],
"unevaluatedProperties": false
}
},
"required": [
"build"
]
},
{
"allOf": [
{
"type": "object",
"properties": {
"dockerFile": {
"type": "string",
"description": "The location of the Dockerfile that defines the contents of the container. The path is relative to the folder containing the `devcontainer.json` file."
},
"context": {
"type": "string",
"description": "The location of the context folder for building the Docker image. The path is relative to the folder containing the `devcontainer.json` file."
}
},
"required": [
"dockerFile"
]
},
{
"type": "object",
"properties": {
"build": {
"description": "Docker build-related options.",
"$ref": "#/definitions/buildOptions"
}
}
}
]
}
]
},
"buildOptions": {
"type": "object",
"properties": {
"target": {
"type": "string",
"description": "Target stage in a multi-stage build."
},
"args": {
"type": "object",
"additionalProperties": {
"type": [
"string"
]
},
"description": "Build arguments."
},
"cacheFrom": {
"type": [
"string",
"array"
],
"description": "The image to consider as a cache. Use an array to specify multiple images.",
"items": {
"type": "string"
}
},
"options": {
"type": "array",
"description": "Additional arguments passed to the build command.",
"items": {
"type": "string"
}
}
}
},
"imageContainer": {
"type": "object",
"properties": {
"image": {
"type": "string",
"description": "The docker image that will be used to create the container."
}
},
"required": [
"image"
]
},
"composeContainer": {
"type": "object",
"properties": {
"dockerComposeFile": {
"type": [
"string",
"array"
],
"description": "The name of the docker-compose file(s) used to start the services.",
"items": {
"type": "string"
}
},
"service": {
"type": "string",
"description": "The service you want to work on. This is considered the primary container for your dev environment which your editor will connect to."
},
"runServices": {
"type": "array",
"description": "An array of services that should be started and stopped.",
"items": {
"type": "string"
}
},
"workspaceFolder": {
"type": "string",
"description": "The path of the workspace folder inside the container. This is typically the target path of a volume mount in the docker-compose.yml."
},
"shutdownAction": {
"type": "string",
"enum": [
"none",
"stopCompose"
],
"description": "Action to take when the user disconnects from the primary container in their editor. The default is to stop all of the compose containers."
},
"overrideCommand": {
"type": "boolean",
"description": "Whether to overwrite the command specified in the image. The default is false."
}
},
"required": [
"dockerComposeFile",
"service",
"workspaceFolder"
]
},
"Mount": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"bind",
"volume"
],
"description": "Mount type."
},
"source": {
"type": "string",
"description": "Mount source."
},
"target": {
"type": "string",
"description": "Mount target."
}
},
"required": [
"type",
"target"
],
"additionalProperties": false
}
},
"oneOf": [
{
"allOf": [
{
"oneOf": [
{
"allOf": [
{
"oneOf": [
{
"$ref": "#/definitions/dockerfileContainer"
},
{
"$ref": "#/definitions/imageContainer"
}
]
},
{
"$ref": "#/definitions/nonComposeBase"
}
]
},
{
"$ref": "#/definitions/composeContainer"
}
]
},
{
"$ref": "#/definitions/devContainerCommon"
}
]
},
{
"type": "object",
"$ref": "#/definitions/devContainerCommon",
"additionalProperties": false
}
],
"unevaluatedProperties": false
}
agent/agentcontainers/dcspec/doc.go
+5
View File
@@ -0,0 +1,5 @@
// Package dcspec contains an automatically generated Devcontainer
// specification.
package dcspec
//go:generate ./gen.sh
agent/agentcontainers/dcspec/gen.sh
Executable
+53
View File
@@ -0,0 +1,53 @@
#!/usr/bin/env bash
set -euo pipefail
# This script requires quicktype to be installed.
# While you can install it using npm, we have it in our devDependencies
# in ${PROJECT_ROOT}/package.json.
PROJECT_ROOT="$(git rev-parse --show-toplevel)"
if ! pnpm list | grep quicktype &>/dev/null; then
echo "quicktype is required to run this script!"
echo "Ensure that it is present in the devDependencies of ${PROJECT_ROOT}/package.json and then run pnpm install."
exit 1
fi
DEST_FILENAME="dcspec_gen.go"
SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
DEST_PATH="${SCRIPT_DIR}/${DEST_FILENAME}"
# Location of the JSON schema for the devcontainer specification.
SCHEMA_SRC="https://raw.githubusercontent.com/devcontainers/spec/refs/heads/main/schemas/devContainer.base.schema.json"
SCHEMA_DEST="${SCRIPT_DIR}/devContainer.base.schema.json"
UPDATE_SCHEMA="${UPDATE_SCHEMA:-false}"
if [[ "${UPDATE_SCHEMA}" = true || ! -f "${SCHEMA_DEST}" ]]; then
# Download the latest schema.
echo "Updating schema..."
curl --fail --silent --show-error --location --output "${SCHEMA_DEST}" "${SCHEMA_SRC}"
else
echo "Using existing schema..."
fi
TMPDIR=$(mktemp -d)
trap 'rm -rfv "$TMPDIR"' EXIT
pnpm exec quicktype \
--src-lang schema \
--lang go \
--just-types-and-package \
--top-level "DevContainer" \
--out "${TMPDIR}/${DEST_FILENAME}" \
--package "dcspec" \
"${SCHEMA_DEST}"
# Format the generated code.
go run mvdan.cc/gofumpt@v0.4.0 -w -l "${TMPDIR}/${DEST_FILENAME}"
# Add a header so that Go recognizes this as a generated file.
if grep -q -- "\[-i extension\]" < <(sed -h 2>&1); then
# darwin sed
sed -i '' '1s/^/\/\/ Code generated by dcspec\/gen.sh. DO NOT EDIT.\n/' "${TMPDIR}/${DEST_FILENAME}"
else
sed -i'' '1s/^/\/\/ Code generated by dcspec\/gen.sh. DO NOT EDIT.\n/' "${TMPDIR}/${DEST_FILENAME}"
fi
mv -v "${TMPDIR}/${DEST_FILENAME}" "${DEST_PATH}"
agent/agentcontainers/devcontainer_meta.go
-5
View File
@@ -1,5 +0,0 @@
package agentcontainers
type DevContainerMeta struct {
RemoteEnv map[string]string `json:"remoteEnv,omitempty"`
}
package.json
+2 -1
View File
@@ -10,6 +10,7 @@
},
"devDependencies": {
"markdown-table-formatter": "^1.6.1",
"markdownlint-cli2": "^0.16.0"
"markdownlint-cli2": "^0.16.0",
"quicktype": "^23.0.0"
}
}
pnpm-lock.yaml
Generated
+745
View File
File diff suppressed because it is too large Load Diff