@opencode-cloud/core 1.0.10 → 3.1.1

package/src/docker/container.rs

@@ -4,6 +4,7 @@
 //! Docker containers for the opencode-cloud service.
 
 use super::dockerfile::{IMAGE_NAME_GHCR, IMAGE_TAG_DEFAULT};
+use super::mount::ParsedMount;
 use super::volume::{
     MOUNT_CONFIG, MOUNT_PROJECTS, MOUNT_SESSION, VOLUME_CONFIG, VOLUME_PROJECTS, VOLUME_SESSION,
 };
@@ -12,7 +13,9 @@ use bollard::container::{
     Config, CreateContainerOptions, RemoveContainerOptions, StartContainerOptions,
     StopContainerOptions,
 };
-use bollard::service::{HostConfig, Mount, MountTypeEnum, PortBinding, PortMap};
+use bollard::service::{
+    HostConfig, Mount, MountPointTypeEnum, MountTypeEnum, PortBinding, PortMap,
+};
 use std::collections::HashMap;
 use tracing::debug;
 
@@ -36,6 +39,7 @@ pub const OPENCODE_WEB_PORT: u16 = 3000;
 /// * `bind_address` - IP address to bind on host (defaults to "127.0.0.1")
 /// * `cockpit_port` - Port to bind on host for Cockpit (defaults to 9090)
 /// * `cockpit_enabled` - Whether to enable Cockpit port mapping (defaults to true)
+/// * `bind_mounts` - User-defined bind mounts from config and CLI flags (optional)
 #[allow(clippy::too_many_arguments)]
 pub async fn create_container(
     client: &DockerClient,
@@ -46,6 +50,7 @@ pub async fn create_container(
     bind_address: Option<&str>,
     cockpit_port: Option<u16>,
     cockpit_enabled: Option<bool>,
+    bind_mounts: Option<Vec<ParsedMount>>,
 ) -> Result<String, DockerError> {
     let container_name = name.unwrap_or(CONTAINER_NAME);
     let default_image = format!("{IMAGE_NAME_GHCR}:{IMAGE_TAG_DEFAULT}");
@@ -81,7 +86,7 @@ pub async fn create_container(
     }
 
     // Create volume mounts
-    let mounts = vec![
+    let mut mounts = vec![
         Mount {
             target: Some(MOUNT_SESSION.to_string()),
             source: Some(VOLUME_SESSION.to_string()),
@@ -105,6 +110,13 @@ pub async fn create_container(
         },
     ];
 
+    // Add user-defined bind mounts from config/CLI
+    if let Some(ref user_mounts) = bind_mounts {
+        for parsed in user_mounts {
+            mounts.push(parsed.to_bollard_mount());
+        }
+    }
+
     // Create port bindings (default to localhost for security)
     let bind_addr = bind_address.unwrap_or("127.0.0.1");
     let mut port_bindings: PortMap = HashMap::new();
@@ -356,6 +368,105 @@ pub async fn container_state(client: &DockerClient, name: &str) -> Result<String
     }
 }
 
+/// Container port configuration
+#[derive(Debug, Clone)]
+pub struct ContainerPorts {
+    /// Host port for opencode web UI (mapped from container port 3000)
+    pub opencode_port: Option<u16>,
+    /// Host port for Cockpit (mapped from container port 9090)
+    pub cockpit_port: Option<u16>,
+}
+
+/// A bind mount from an existing container
+#[derive(Debug, Clone)]
+pub struct ContainerBindMount {
+    /// Source path on host
+    pub source: String,
+    /// Target path in container
+    pub target: String,
+    /// Read-only flag
+    pub read_only: bool,
+}
+
+/// Get the port bindings from an existing container
+///
+/// Returns the host ports that the container's internal ports are mapped to.
+/// Returns None for ports that aren't mapped.
+pub async fn get_container_ports(
+    client: &DockerClient,
+    name: &str,
+) -> Result<ContainerPorts, DockerError> {
+    debug!("Getting container ports: {}", name);
+
+    let info = client
+        .inner()
+        .inspect_container(name, None)
+        .await
+        .map_err(|e| DockerError::Container(format!("Failed to inspect container {name}: {e}")))?;
+
+    let port_bindings = info
+        .host_config
+        .and_then(|hc| hc.port_bindings)
+        .unwrap_or_default();
+
+    // Extract opencode port (3000/tcp -> host port)
+    let opencode_port = port_bindings
+        .get("3000/tcp")
+        .and_then(|bindings| bindings.as_ref())
+        .and_then(|bindings| bindings.first())
+        .and_then(|binding| binding.host_port.as_ref())
+        .and_then(|port_str| port_str.parse::<u16>().ok());
+
+    // Extract cockpit port (9090/tcp -> host port)
+    let cockpit_port = port_bindings
+        .get("9090/tcp")
+        .and_then(|bindings| bindings.as_ref())
+        .and_then(|bindings| bindings.first())
+        .and_then(|binding| binding.host_port.as_ref())
+        .and_then(|port_str| port_str.parse::<u16>().ok());
+
+    Ok(ContainerPorts {
+        opencode_port,
+        cockpit_port,
+    })
+}
+
+/// Get bind mounts from an existing container
+///
+/// Returns only user-defined bind mounts (excludes system mounts like cgroup).
+pub async fn get_container_bind_mounts(
+    client: &DockerClient,
+    name: &str,
+) -> Result<Vec<ContainerBindMount>, DockerError> {
+    debug!("Getting container bind mounts: {}", name);
+
+    let info = client
+        .inner()
+        .inspect_container(name, None)
+        .await
+        .map_err(|e| DockerError::Container(format!("Failed to inspect container {name}: {e}")))?;
+
+    let mounts = info.mounts.unwrap_or_default();
+
+    // Filter to only bind mounts, excluding system paths
+    let bind_mounts: Vec<ContainerBindMount> = mounts
+        .iter()
+        .filter(|m| m.typ == Some(MountPointTypeEnum::BIND))
+        .filter(|m| {
+            // Exclude system mounts (cgroup, etc.)
+            let target = m.destination.as_deref().unwrap_or("");
+            !target.starts_with("/sys/")
+        })
+        .map(|m| ContainerBindMount {
+            source: m.source.clone().unwrap_or_default(),
+            target: m.destination.clone().unwrap_or_default(),
+            read_only: m.rw.map(|rw| !rw).unwrap_or(false),
+        })
+        .collect();
+
+    Ok(bind_mounts)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -369,6 +480,6 @@ mod tests {
     #[test]
     fn default_image_format() {
         let expected = format!("{IMAGE_NAME_GHCR}:{IMAGE_TAG_DEFAULT}");
-        assert_eq!(expected, "ghcr.io/prizz/opencode-cloud:latest");
+        assert_eq!(expected, "ghcr.io/prizz/opencode-cloud-sandbox:latest");
     }
 }

package/src/docker/dockerfile.rs

@@ -1,9 +1,13 @@
 //! Embedded Dockerfile content
 //!
-//! This module contains the Dockerfile for building the opencode-cloud container image,
-//! embedded at compile time for distribution with the CLI.
+//! This module contains the Dockerfile for building the opencode-cloud-sandbox
+//! container image, embedded at compile time for distribution with the CLI.
+//!
+//! Note: The image is named "opencode-cloud-sandbox" (not "opencode-cloud") to
+//! clearly indicate this is the sandboxed container environment that the
+//! opencode-cloud CLI deploys, not the CLI tool itself.
 
-/// The Dockerfile for building the opencode-cloud container image
+/// The Dockerfile for building the opencode-cloud-sandbox container image
 pub const DOCKERFILE: &str = include_str!("Dockerfile");
 
 // =============================================================================
@@ -15,27 +19,26 @@ pub const DOCKERFILE: &str = include_str!("Dockerfile");
 // - Registry: The server hosting the image (e.g., ghcr.io, gcr.io, docker.io)
 //   When omitted, Docker Hub (docker.io) is assumed.
 // - Namespace: Usually the username or organization (e.g., prizz)
-// - Image: The image name (e.g., opencode-cloud)
+// - Image: The image name (e.g., opencode-cloud-sandbox)
 // - Tag: Version identifier (e.g., latest, v1.0.0). Defaults to "latest" if omitted.
 //
 // Examples:
-//   ghcr.io/prizz/opencode-cloud:latest  - GitHub Container Registry
-//   prizz/opencode-cloud:latest          - Docker Hub (registry omitted)
-//   gcr.io/my-project/myapp:v1.0         - Google Container Registry
+//   ghcr.io/prizz/opencode-cloud-sandbox:latest  - GitHub Container Registry
+//   prizz/opencode-cloud-sandbox:latest          - Docker Hub (registry omitted)
+//   gcr.io/my-project/myapp:v1.0                 - Google Container Registry
 //
-// We use GHCR as the primary registry since it integrates well with GitHub
-// Actions for CI/CD publishing.
+// We publish to both GHCR (primary) and Docker Hub for maximum accessibility.
 // =============================================================================
 
 /// Docker image name for GitHub Container Registry (primary registry)
 ///
 /// Format: `ghcr.io/{github-username}/{image-name}`
-pub const IMAGE_NAME_GHCR: &str = "ghcr.io/prizz/opencode-cloud";
+pub const IMAGE_NAME_GHCR: &str = "ghcr.io/prizz/opencode-cloud-sandbox";
 
-/// Docker image name for Docker Hub (fallback registry)
+/// Docker image name for Docker Hub (secondary registry)
 ///
 /// Format: `{dockerhub-username}/{image-name}` (registry prefix omitted for Docker Hub)
-pub const IMAGE_NAME_DOCKERHUB: &str = "prizz/opencode-cloud";
+pub const IMAGE_NAME_DOCKERHUB: &str = "prizz/opencode-cloud-sandbox";
 
 /// Default image tag
 pub const IMAGE_TAG_DEFAULT: &str = "latest";

package/src/docker/mod.rs

@@ -19,7 +19,9 @@ mod error;
 pub mod exec;
 mod health;
 pub mod image;
+pub mod mount;
 pub mod progress;
+pub mod state;
 pub mod update;
 pub mod users;
 mod version;
@@ -62,12 +64,19 @@ pub use volume::{
     VOLUME_SESSION, ensure_volumes_exist, remove_all_volumes, remove_volume, volume_exists,
 };
 
+// Bind mount parsing and validation
+pub use mount::{MountError, ParsedMount, check_container_path_warning, validate_mount_path};
+
 // Container lifecycle
 pub use container::{
-    CONTAINER_NAME, OPENCODE_WEB_PORT, container_exists, container_is_running, container_state,
-    create_container, remove_container, start_container, stop_container,
+    CONTAINER_NAME, ContainerBindMount, ContainerPorts, OPENCODE_WEB_PORT, container_exists,
+    container_is_running, container_state, create_container, get_container_bind_mounts,
+    get_container_ports, remove_container, start_container, stop_container,
 };
 
+// Image state tracking
+pub use state::{ImageState, clear_state, get_state_path, load_state, save_state};
+
 /// Full setup: ensure volumes exist, create container if needed, start it
 ///
 /// This is the primary entry point for starting the opencode service.
@@ -80,6 +89,7 @@ pub use container::{
 /// * `bind_address` - IP address to bind on host (defaults to "127.0.0.1")
 /// * `cockpit_port` - Port to bind on host for Cockpit (defaults to 9090)
 /// * `cockpit_enabled` - Whether to enable Cockpit port mapping (defaults to true)
+/// * `bind_mounts` - User-defined bind mounts from config and CLI flags (optional)
 pub async fn setup_and_start(
     client: &DockerClient,
     opencode_web_port: Option<u16>,
@@ -87,6 +97,7 @@ pub async fn setup_and_start(
     bind_address: Option<&str>,
     cockpit_port: Option<u16>,
     cockpit_enabled: Option<bool>,
+    bind_mounts: Option<Vec<mount::ParsedMount>>,
 ) -> Result<String, DockerError> {
     // Ensure volumes exist first
     volume::ensure_volumes_exist(client).await?;
@@ -114,6 +125,7 @@ pub async fn setup_and_start(
             bind_address,
             cockpit_port,
             cockpit_enabled,
+            bind_mounts,
         )
         .await?
     };
@@ -126,13 +138,22 @@ pub async fn setup_and_start(
     Ok(container_id)
 }
 
+/// Default graceful shutdown timeout in seconds
+pub const DEFAULT_STOP_TIMEOUT_SECS: i64 = 30;
+
 /// Stop and optionally remove the opencode container
 ///
 /// # Arguments
 /// * `client` - Docker client
 /// * `remove` - Also remove the container after stopping
-pub async fn stop_service(client: &DockerClient, remove: bool) -> Result<(), DockerError> {
+/// * `timeout_secs` - Graceful shutdown timeout (default: 30 seconds)
+pub async fn stop_service(
+    client: &DockerClient,
+    remove: bool,
+    timeout_secs: Option<i64>,
+) -> Result<(), DockerError> {
     let name = container::CONTAINER_NAME;
+    let timeout = timeout_secs.unwrap_or(DEFAULT_STOP_TIMEOUT_SECS);
 
     // Check if container exists
     if !container::container_exists(client, name).await? {
@@ -143,7 +164,7 @@ pub async fn stop_service(client: &DockerClient, remove: bool) -> Result<(), Doc
 
     // Stop if running
     if container::container_is_running(client, name).await? {
-        container::stop_container(client, name, None).await?;
+        container::stop_container(client, name, Some(timeout)).await?;
     }
 
     // Remove if requested

package/src/docker/mount.rs

@@ -0,0 +1,330 @@
+//! Bind mount parsing and validation for container configuration.
+//!
+//! This module provides functionality to:
+//! - Parse mount strings in Docker format (`/host:/container[:ro|rw]`)
+//! - Validate mount paths (existence, type, permissions)
+//! - Convert parsed mounts to Bollard's Mount type for Docker API
+//! - Warn about potentially dangerous container mount points
+
+use bollard::service::{Mount, MountTypeEnum};
+use std::path::PathBuf;
+use thiserror::Error;
+
+/// Errors that can occur during mount parsing and validation.
+#[derive(Debug, Error)]
+pub enum MountError {
+    /// Mount path is relative, but must be absolute.
+    #[error("Mount paths must be absolute. Use: /full/path/to/dir (got: {0})")]
+    RelativePath(String),
+
+    /// Mount string format is invalid.
+    #[error("Invalid mount format. Expected: /host/path:/container/path[:ro] (got: {0})")]
+    InvalidFormat(String),
+
+    /// Path does not exist or cannot be accessed.
+    #[error("Path not found: {0} ({1})")]
+    PathNotFound(String, String),
+
+    /// Path exists but is not a directory.
+    #[error("Path is not a directory: {0}")]
+    NotADirectory(String),
+
+    /// Permission denied accessing path.
+    #[error("Cannot access path (permission denied): {0}")]
+    PermissionDenied(String),
+}
+
+/// A parsed bind mount specification.
+#[derive(Debug, Clone, PartialEq)]
+pub struct ParsedMount {
+    /// Host path to mount (absolute).
+    pub host_path: PathBuf,
+
+    /// Container path where the host path is mounted.
+    pub container_path: String,
+
+    /// Whether the mount is read-only.
+    pub read_only: bool,
+}
+
+impl ParsedMount {
+    /// Parse a mount string in Docker format.
+    ///
+    /// Format: `/host/path:/container/path[:ro|rw]`
+    ///
+    /// # Arguments
+    /// * `mount_str` - The mount specification string.
+    ///
+    /// # Returns
+    /// * `Ok(ParsedMount)` - Successfully parsed mount.
+    /// * `Err(MountError)` - Parse error.
+    ///
+    /// # Examples
+    /// ```
+    /// use opencode_cloud_core::docker::ParsedMount;
+    ///
+    /// // Read-write mount (default)
+    /// let mount = ParsedMount::parse("/home/user/data:/workspace/data").unwrap();
+    /// assert_eq!(mount.host_path.to_str().unwrap(), "/home/user/data");
+    /// assert_eq!(mount.container_path, "/workspace/data");
+    /// assert!(!mount.read_only);
+    ///
+    /// // Read-only mount
+    /// let mount = ParsedMount::parse("/home/user/config:/etc/app:ro").unwrap();
+    /// assert!(mount.read_only);
+    /// ```
+    pub fn parse(mount_str: &str) -> Result<Self, MountError> {
+        let parts: Vec<&str> = mount_str.split(':').collect();
+
+        match parts.len() {
+            2 => {
+                // /host:/container (default rw)
+                let host_path = PathBuf::from(parts[0]);
+                if !host_path.is_absolute() {
+                    return Err(MountError::RelativePath(parts[0].to_string()));
+                }
+                Ok(Self {
+                    host_path,
+                    container_path: parts[1].to_string(),
+                    read_only: false,
+                })
+            }
+            3 => {
+                // /host:/container:ro or /host:/container:rw
+                let host_path = PathBuf::from(parts[0]);
+                if !host_path.is_absolute() {
+                    return Err(MountError::RelativePath(parts[0].to_string()));
+                }
+                let read_only = match parts[2].to_lowercase().as_str() {
+                    "ro" => true,
+                    "rw" => false,
+                    _ => return Err(MountError::InvalidFormat(mount_str.to_string())),
+                };
+                Ok(Self {
+                    host_path,
+                    container_path: parts[1].to_string(),
+                    read_only,
+                })
+            }
+            _ => Err(MountError::InvalidFormat(mount_str.to_string())),
+        }
+    }
+
+    /// Convert to a Bollard Mount for the Docker API.
+    ///
+    /// Returns a bind mount with the parsed host and container paths.
+    pub fn to_bollard_mount(&self) -> Mount {
+        Mount {
+            target: Some(self.container_path.clone()),
+            source: Some(self.host_path.to_string_lossy().to_string()),
+            typ: Some(MountTypeEnum::BIND),
+            read_only: Some(self.read_only),
+            ..Default::default()
+        }
+    }
+}
+
+/// Validate that a mount host path exists and is accessible.
+///
+/// Checks:
+/// 1. Path is absolute.
+/// 2. Path exists (via canonicalize, which also resolves symlinks).
+/// 3. Path is a directory.
+///
+/// # Arguments
+/// * `path` - The path to validate.
+///
+/// # Returns
+/// * `Ok(PathBuf)` - The canonical (resolved) path.
+/// * `Err(MountError)` - Validation error.
+pub fn validate_mount_path(path: &std::path::Path) -> Result<PathBuf, MountError> {
+    // Check absolute
+    if !path.is_absolute() {
+        return Err(MountError::RelativePath(path.display().to_string()));
+    }
+
+    // Canonicalize (resolves symlinks, checks existence)
+    let canonical = std::fs::canonicalize(path).map_err(|e| {
+        if e.kind() == std::io::ErrorKind::PermissionDenied {
+            MountError::PermissionDenied(path.display().to_string())
+        } else {
+            MountError::PathNotFound(path.display().to_string(), e.to_string())
+        }
+    })?;
+
+    // Check it's a directory
+    let metadata = std::fs::metadata(&canonical).map_err(|e| {
+        if e.kind() == std::io::ErrorKind::PermissionDenied {
+            MountError::PermissionDenied(path.display().to_string())
+        } else {
+            MountError::PathNotFound(path.display().to_string(), e.to_string())
+        }
+    })?;
+
+    if !metadata.is_dir() {
+        return Err(MountError::NotADirectory(path.display().to_string()));
+    }
+
+    Ok(canonical)
+}
+
+/// System paths that should typically not be mounted over.
+const SYSTEM_PATHS: &[&str] = &["/etc", "/usr", "/bin", "/sbin", "/lib", "/var"];
+
+/// Check if mounting to a container path might be dangerous.
+///
+/// Returns a warning message if the container path is a system path,
+/// or `None` if the path appears safe.
+///
+/// # Arguments
+/// * `container_path` - The path inside the container.
+///
+/// # Returns
+/// * `Some(String)` - Warning message about the system path.
+/// * `None` - Path appears safe.
+pub fn check_container_path_warning(container_path: &str) -> Option<String> {
+    for system_path in SYSTEM_PATHS {
+        if container_path == *system_path || container_path.starts_with(&format!("{system_path}/"))
+        {
+            return Some(format!(
+                "Warning: mounting to '{container_path}' may affect container system files"
+            ));
+        }
+    }
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_valid_mount_rw() {
+        let mount = ParsedMount::parse("/a:/b").unwrap();
+        assert_eq!(mount.host_path, PathBuf::from("/a"));
+        assert_eq!(mount.container_path, "/b");
+        assert!(!mount.read_only);
+    }
+
+    #[test]
+    fn parse_valid_mount_ro() {
+        let mount = ParsedMount::parse("/a:/b:ro").unwrap();
+        assert_eq!(mount.host_path, PathBuf::from("/a"));
+        assert_eq!(mount.container_path, "/b");
+        assert!(mount.read_only);
+    }
+
+    #[test]
+    fn parse_valid_mount_explicit_rw() {
+        let mount = ParsedMount::parse("/a:/b:rw").unwrap();
+        assert_eq!(mount.host_path, PathBuf::from("/a"));
+        assert_eq!(mount.container_path, "/b");
+        assert!(!mount.read_only);
+    }
+
+    #[test]
+    fn parse_valid_mount_ro_uppercase() {
+        let mount = ParsedMount::parse("/a:/b:RO").unwrap();
+        assert!(mount.read_only);
+    }
+
+    #[test]
+    fn parse_invalid_format_single_part() {
+        let result = ParsedMount::parse("invalid");
+        assert!(matches!(result, Err(MountError::InvalidFormat(_))));
+    }
+
+    #[test]
+    fn parse_invalid_format_too_many_parts() {
+        let result = ParsedMount::parse("/a:/b:ro:extra");
+        assert!(matches!(result, Err(MountError::InvalidFormat(_))));
+    }
+
+    #[test]
+    fn parse_invalid_format_bad_mode() {
+        let result = ParsedMount::parse("/a:/b:invalid");
+        assert!(matches!(result, Err(MountError::InvalidFormat(_))));
+    }
+
+    #[test]
+    fn parse_relative_path_rejected() {
+        let result = ParsedMount::parse("./rel:/b");
+        assert!(matches!(result, Err(MountError::RelativePath(_))));
+    }
+
+    #[test]
+    fn parse_relative_path_no_dot_rejected() {
+        let result = ParsedMount::parse("relative/path:/b");
+        assert!(matches!(result, Err(MountError::RelativePath(_))));
+    }
+
+    #[test]
+    fn system_path_warning_etc() {
+        let warning = check_container_path_warning("/etc");
+        assert!(warning.is_some());
+        assert!(warning.unwrap().contains("/etc"));
+    }
+
+    #[test]
+    fn system_path_warning_etc_subdir() {
+        let warning = check_container_path_warning("/etc/passwd");
+        assert!(warning.is_some());
+    }
+
+    #[test]
+    fn system_path_warning_usr() {
+        let warning = check_container_path_warning("/usr");
+        assert!(warning.is_some());
+    }
+
+    #[test]
+    fn system_path_warning_usr_local() {
+        let warning = check_container_path_warning("/usr/local");
+        assert!(warning.is_some());
+    }
+
+    #[test]
+    fn non_system_path_no_warning() {
+        let warning = check_container_path_warning("/workspace/data");
+        assert!(warning.is_none());
+    }
+
+    #[test]
+    fn non_system_path_home_no_warning() {
+        let warning = check_container_path_warning("/home/user/data");
+        assert!(warning.is_none());
+    }
+
+    #[test]
+    fn to_bollard_mount_structure() {
+        let mount = ParsedMount {
+            host_path: PathBuf::from("/host/path"),
+            container_path: "/container/path".to_string(),
+            read_only: true,
+        };
+        let bollard_mount = mount.to_bollard_mount();
+        assert_eq!(bollard_mount.target, Some("/container/path".to_string()));
+        assert_eq!(bollard_mount.source, Some("/host/path".to_string()));
+        assert_eq!(bollard_mount.typ, Some(MountTypeEnum::BIND));
+        assert_eq!(bollard_mount.read_only, Some(true));
+    }
+
+    #[test]
+    fn validate_mount_path_relative_rejected() {
+        let result = validate_mount_path(std::path::Path::new("./relative"));
+        assert!(matches!(result, Err(MountError::RelativePath(_))));
+    }
+
+    #[test]
+    fn validate_mount_path_nonexistent() {
+        let result = validate_mount_path(std::path::Path::new("/nonexistent/path/xyz123"));
+        assert!(matches!(result, Err(MountError::PathNotFound(_, _))));
+    }
+
+    #[test]
+    fn validate_mount_path_existing_directory() {
+        // Use /tmp which should exist on any Unix system
+        let result = validate_mount_path(std::path::Path::new("/tmp"));
+        assert!(result.is_ok());
+    }
+}