The IDE you know, rebuilt in Rust. IntelliJ IDEA–style keymap, tool windows and search-everywhere in a fast native app: editor, code insight, debugger, Git, terminal, database and HTTP clients for 60+ languages.
TypeScript code-editorcross-platformdapdatabase-clientdebuggerdesktop-appdeveloper-toolsgithttp-clientideintellijlsprusttauriterminal
//! The project's `.devcontainer/devcontainer.json` (or `.devcontainer.json`) as a
//! remote host reads it: `remoteEnv` for every child process of the IDE backend and
//! `postStartCommand` once per backend start. No container is built. The desktop reads
//! `forwardPorts` of a dev container it opens.
use serde_json::Value;
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
/// Where the configuration may be, first match wins.
const LOCATIONS: [&str; 2] = [".devcontainer/devcontainer.json", ".devcontainer.json"];
#[derive(Debug, Default, Clone, PartialEq)]
pub struct DevContainer {
pub path: PathBuf,
/// Values as written (`None`: unset the variable), substitutions not applied.
pub remote_env: BTreeMap<String, Option<String>>,
pub post_start: Option<LifecycleCommand>,
/// `forwardPorts` of the container itself (a number, `localhost:<port>` or
/// `127.0.0.1:<port>`), in order, without duplicates. Other entries, such as the port of
/// another Compose service, are left out.
pub forward_ports: Vec<u16>,
}
/// A lifecycle command in its three forms.
#[derive(Debug, Clone, PartialEq)]
pub enum LifecycleCommand {
/// Run through `/bin/sh -c`.
Shell(String),
/// Run directly: program and arguments, no shell.
Exec(Vec<String>),
/// Named commands (each a `Shell` or an `Exec`) run in parallel; all must succeed.
Parallel(Vec<(String, LifecycleCommand)>),
}
impl LifecycleCommand {
fn parse(v: &Value) -> Result<Option<Self>, String> {
Ok(match v {
Value::Null => None,
Value::String(s) if s.trim().is_empty() => None,
Value::String(s) => Some(Self::Shell(s.clone())),
Value::Array(items) => {
let args: Vec<String> = items
.iter()
.map(|i| i.as_str().map(str::to_owned).ok_or("array items must be strings"))
.collect::<Result<_, _>>()?;
(!args.is_empty()).then_some(Self::Exec(args))
}
Value::Object(map) => {
let mut named = Vec::new();
for (name, v) in map {
match Self::parse(v)? {
Some(Self::Parallel(_)) => return Err(format!("{name}: expected a string or an array")),
Some(c) => named.push((name.clone(), c)),
None => {}
}
}
(!named.is_empty()).then_some(Self::Parallel(named))
}
_ => return Err("expected a string, an array or an object".into()),
})
}
/// The single commands to run (one, or each of a `Parallel`), with their names.
pub fn commands(&self) -> Vec<(Option<&str>, &LifecycleCommand)> {
match self {
Self::Parallel(named) => named.iter().map(|(n, c)| (Some(n.as_str()), c)).collect(),
c => vec![(None, c)],
}
}
/// Program and arguments of a `Shell` or `Exec` command (`Parallel`: `None`).
pub fn argv(&self) -> Option<Vec<String>> {
match self {
Self::Shell(s) => Some(vec!["/bin/sh".into(), "-c".into(), s.clone()]),
Self::Exec(args) => Some(args.clone()),
Self::Parallel(_) => None,
}
}
}
/// The configuration file of the project at `root`, if it has one.
pub fn find(root: &Path) -> Option<PathBuf> {
LOCATIONS.iter().map(|l| root.join(l)).find(|p| p.is_file())
}
/// Reads the project's configuration: `Ok(None)` without one, `Err` with a message when
/// it can't be read or parsed.
pub fn load(root: &Path) -> Result<Option<DevContainer>, String> {
let Some(path) = find(root) else { return Ok(None) };
load_file(&path).map(Some)
}
/// Reads the configuration at `path`.
pub fn load_file(path: &Path) -> Result<DevContainer, String> {
let text = std::fs::read_to_string(path).map_err(|e| format!("{}: {e}", path.display()))?;
parse(&text).map(|mut c| {
c.path = path.to_owned();
c
})
}
/// Parses `devcontainer.json` text (JSON with comments and trailing commas).
pub fn parse(text: &str) -> Result<DevContainer, String> {
let json: Value = serde_json::from_str(&ide_core::jsonc::strip(text)).map_err(|e| e.to_string())?;
let Value::Object(top) = json else { return Err("expected an object".into()) };
let mut config = DevContainer::default();
if let Some(env) = top.get("remoteEnv") {
let Value::Object(env) = env else { return Err("remoteEnv: expected an object".into()) };
for (k, v) in env {
let value = match v {
Value::Null => None,
Value::String(s) => Some(s.clone()),
Value::Number(n) => Some(n.to_string()),
Value::Bool(b) => Some(b.to_string()),
_ => return Err(format!("remoteEnv.{k}: expected a string")),
};
config.remote_env.insert(k.clone(), value);
}
}
if let Some(cmd) = top.get("postStartCommand") {
config.post_start = LifecycleCommand::parse(cmd).map_err(|e| format!("postStartCommand: {e}"))?;
}
// Only the desktop uses these: an entry it can't forward never makes the file unreadable.
if let Some(Value::Array(ports)) = top.get("forwardPorts") {
for port in ports.iter().filter_map(container_port) {
if !config.forward_ports.contains(&port) {
config.forward_ports.push(port);
}
}
}
Ok(config)
}
/// A `forwardPorts` entry that is a port of the container itself.
fn container_port(v: &Value) -> Option<u16> {
let port = match v {
Value::Number(n) => n.as_u64()?,
Value::String(s) => match s.trim().split_once(':') {
Some(("localhost" | "127.0.0.1", port)) => port.parse().ok()?,
Some(_) => return None,
None => s.trim().parse().ok()?,
},
_ => return None,
};
u16::try_from(port).ok().filter(|p| *p != 0)
}
/// Expands `${localEnv:NAME}`, `${containerEnv:NAME}` and `${env:NAME}` (all the remote
/// host's environment, through `env`; `${…:NAME:default}` when unset), and
/// `${localWorkspaceFolder}` / `${containerWorkspaceFolder}` (and their `…Basename`) to
/// the project root. Unknown references stay as written.
pub fn substitute(value: &str, root: &Path, env: &dyn Fn(&str) -> Option<String>) -> String {
let mut out = String::with_capacity(value.len());
let mut rest = value;
while let Some(start) = rest.find("${") {
out.push_str(&rest[..start]);
let after = &rest[start + 2..];
let Some(end) = after.find('}') else {
out.push_str(&rest[start..]);
return out;
};
let inner = &after[..end];
match resolve(inner, root, env) {
Some(v) => out.push_str(&v),
None => out.push_str(&rest[start..start + 2 + end + 1]),
}
rest = &after[end + 1..];
}
out.push_str(rest);
out
}
fn resolve(inner: &str, root: &Path, env: &dyn Fn(&str) -> Option<String>) -> Option<String> {
let basename = || root.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
match inner {
"localWorkspaceFolder" | "containerWorkspaceFolder" => return Some(root.to_string_lossy().into_owned()),
"localWorkspaceFolderBasename" | "containerWorkspaceFolderBasename" => return Some(basename()),
_ => {}
}
let (scope, spec) = inner.split_once(':')?;
if !matches!(scope, "localEnv" | "containerEnv" | "env") {
return None;
}
let (name, default) = match spec.split_once(':') {
Some((name, default)) => (name, Some(default)),
None => (spec, None),
};
Some(env(name).or_else(|| default.map(str::to_owned)).unwrap_or_default())
}
/// `remoteEnv` with substitutions applied against `env` (the environment before it), in
/// order: `None` unsets the variable.
pub fn resolve_env(
config: &DevContainer,
root: &Path,
env: &dyn Fn(&str) -> Option<String>,
) -> Vec<(String, Option<String>)> {
config.remote_env.iter().map(|(k, v)| (k.clone(), v.as_deref().map(|v| substitute(v, root, env)))).collect()
}
#[cfg(test)]
mod tests {
use super::*;
fn env(name: &str) -> Option<String> {
match name {
"PATH" => Some("/usr/bin:/bin".into()),
"HOME" => Some("/home/me".into()),
_ => None,
}
}
#[test]
fn parses_jsonc_with_remote_env_and_post_start() {
let c = parse(
r#"{
// A comment
"name": "demo",
"remoteEnv": {
"PATH": "${containerEnv:PATH}:/opt/tools/bin",
"EMPTY": null,
"PORT": 8080, /* numbers are text */
},
"postStartCommand": "make dev",
}"#,
)
.unwrap();
assert_eq!(c.remote_env.get("PATH").unwrap().as_deref(), Some("${containerEnv:PATH}:/opt/tools/bin"));
assert_eq!(c.remote_env.get("EMPTY"), Some(&None));
assert_eq!(c.remote_env.get("PORT").unwrap().as_deref(), Some("8080"));
assert_eq!(c.post_start, Some(LifecycleCommand::Shell("make dev".into())));
}
#[test]
fn forward_ports_of_the_container_only() {
let c = parse(
r#"{ "forwardPorts": [8000, "5173", "localhost:3000", "127.0.0.1:8000", "db:5432", 0, 70000, "x", null] }"#,
)
.unwrap();
assert_eq!(c.forward_ports, [8000, 5173, 3000]);
assert!(parse(r#"{ "forwardPorts": "8000" }"#).unwrap().forward_ports.is_empty());
}
#[test]
fn forward_ports_skip_malformed_entries_and_keep_valid_bounds() {
let config = parse(
r#"{
"remoteEnv": {"PORT": "8000"},
"forwardPorts": [1, 65535, " 8000 ", "localhost:8000", "127.0.0.1:8000",
-1, 1.5, 65536, 18446744073709551616, true, false, {}, [], null,
"", " ", ":80", "db:5432", "localhost:", "localhost:0", "localhost:65536",
"localhost:80:90", "localhost: 80", "http://localhost:80", "::1:80"]
}"#,
)
.unwrap();
assert_eq!(config.forward_ports, [1, 65535, 8000]);
assert_eq!(config.remote_env["PORT"].as_deref(), Some("8000"));
}
#[test]
fn post_start_command_forms() {
let parse_cmd = |json: &str| parse(&format!(r#"{{ "postStartCommand": {json} }}"#)).map(|c| c.post_start);
assert_eq!(parse_cmd(r#""echo hi""#).unwrap().unwrap().argv().unwrap(), ["/bin/sh", "-c", "echo hi"]);
let exec = parse_cmd(r#"["npm", "run", "watch"]"#).unwrap().unwrap();
assert_eq!(exec, LifecycleCommand::Exec(vec!["npm".into(), "run".into(), "watch".into()]));
assert_eq!(exec.argv().unwrap(), ["npm", "run", "watch"]);
let parallel =
parse_cmd(r#"{ "server": "npm start", "db": ["pg_ctl", "start"], "none": "" }"#).unwrap().unwrap();
let names: Vec<_> = parallel.commands().into_iter().map(|(n, _)| n.unwrap()).collect();
assert_eq!(names, ["db", "server"]);
assert!(parallel.argv().is_none());
assert_eq!(parse_cmd(r#""""#).unwrap(), None);
assert_eq!(parse_cmd("[]").unwrap(), None);
assert!(parse_cmd("42").unwrap_err().contains("postStartCommand"));
assert!(parse_cmd("[1]").is_err());
assert!(parse_cmd(r#"{ "nested": { "a": "b" } }"#).is_err());
}
#[test]
fn invalid_files_are_errors() {
assert!(parse("{ \"remoteEnv\": [] }").unwrap_err().contains("remoteEnv"));
assert!(parse("{ not json").is_err());
assert!(parse("[]").is_err());
}
#[test]
fn substitutes_remote_env_references() {
let root = Path::new("/work/demo");
let s = |v: &str| substitute(v, root, &env);
assert_eq!(s("${containerEnv:PATH}:/opt/bin"), "/usr/bin:/bin:/opt/bin");
assert_eq!(s("${localEnv:HOME}/.cache"), "/home/me/.cache");
assert_eq!(s("${env:HOME}"), "/home/me");
assert_eq!(s("${localEnv:MISSING}"), "");
assert_eq!(s("${localEnv:MISSING:fallback}"), "fallback");
assert_eq!(s("${containerWorkspaceFolder}/bin:${localWorkspaceFolderBasename}"), "/work/demo/bin:demo");
assert_eq!(s("${unknown} ${other:X} $HOME ${open"), "${unknown} ${other:X} $HOME ${open");
}
#[test]
fn resolves_against_the_environment_before_it() {
let c = parse(r#"{ "remoteEnv": { "PATH": "/opt/bin:${containerEnv:PATH}", "GONE": null } }"#).unwrap();
let resolved = resolve_env(&c, Path::new("/p"), &env);
assert_eq!(
resolved,
[("GONE".to_owned(), None), ("PATH".to_owned(), Some("/opt/bin:/usr/bin:/bin".to_owned()))]
);
}
#[test]
fn finds_either_location() {
let tmp = tempfile::tempdir().unwrap();
assert_eq!(load(tmp.path()).unwrap(), None);
std::fs::write(tmp.path().join(".devcontainer.json"), r#"{ "postStartCommand": "a" }"#).unwrap();
assert_eq!(load(tmp.path()).unwrap().unwrap().post_start, Some(LifecycleCommand::Shell("a".into())));
std::fs::create_dir(tmp.path().join(".devcontainer")).unwrap();
std::fs::write(tmp.path().join(".devcontainer/devcontainer.json"), r#"{ "postStartCommand": "b" }"#).unwrap();
let c = load(tmp.path()).unwrap().unwrap();
assert_eq!(c.post_start, Some(LifecycleCommand::Shell("b".into())));
assert!(c.path.ends_with(".devcontainer/devcontainer.json"));
}
}