ruby_llm-docker 0.0.1 → 0.2.5

data/lib/ruby_llm/docker/remove_image.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for removing Docker images.
+    #
+    # This tool provides the ability to permanently delete Docker images from
+    # the local system to free up disk space and remove unused images. It
+    # supports both regular and forced removal with options for parent image
+    # handling.
+    #
+    # == Features
+    #
+    # - Remove images by ID, name, or name:tag
+    # - Force removal of images in use
+    # - Control parent image cleanup
+    # - Comprehensive error handling
+    # - Safe removal with dependency checking
+    #
+    # == ⚠️ Data Loss Warning ⚠️
+    #
+    # **DESTRUCTIVE OPERATION - PERMANENT DATA LOSS**
+    #
+    # This operation permanently deletes images and associated data:
+    # - Image layers are deleted from disk
+    # - All tags pointing to the image are removed
+    # - Operation cannot be undone
+    # - Dependent containers may become unusable
+    # - Custom modifications to images are lost
+    #
+    # == Dependency Management
+    #
+    # Docker images have complex dependency relationships:
+    # - **Child Images**: Images built FROM this image
+    # - **Parent Images**: Base images this image depends on
+    # - **Running Containers**: Containers using this image
+    # - **Stopped Containers**: Containers that could be restarted
+    #
+    # == Security Considerations
+    #
+    # Image removal affects system security posture:
+    # - Removes potentially vulnerable software
+    # - May break running applications
+    # - Could remove security patches
+    # - Affects rollback capabilities
+    #
+    # Best practices:
+    # - Verify no critical containers depend on the image
+    # - Backup important images before removal
+    # - Use force removal judiciously
+    # - Monitor disk space after removal
+    # - Maintain image inventory documentation
+    #
+    # == Removal Options
+    #
+    # - **Normal Removal**: Only removes if no containers use the image
+    # - **Force Removal**: Removes even if containers depend on it
+    # - **Prune Parents**: Automatically removes unused parent images
+    # - **No Prune**: Keeps parent images even if unused
+    #
+    # == Example Usage
+    #
+    #   # Safe removal of unused image
+    #   RemoveImage.call(
+    #     server_context: context,
+    #     id: "old-app:v1.0"
+    #   )
+    #
+    #   # Force removal of image in use
+    #   RemoveImage.call(
+    #     server_context: context,
+    #     id: "broken-image:latest",
+    #     force: true
+    #   )
+    #
+    #   # Remove image but keep parent layers
+    #   RemoveImage.call(
+    #     server_context: context,
+    #     id: "temp-build:abc123",
+    #     noprune: true
+    #   )
+    #
+    # @see ListImages
+    # @see BuildImage
+    # @see Docker::Image#remove
+    # @since 0.1.0
+    class RemoveImage < RubyLLM::Tool
+      description 'Remove a Docker image'
+
+      param :id, type: :string, desc: 'Image ID, name, or name:tag'
+      param :force, type: :boolean, desc: 'Force removal of the image (default: false)', required: false
+      param :noprune, type: :boolean, desc: 'Do not delete untagged parents (default: false)', required: false
+
+      # Remove a Docker image from the local system.
+      #
+      # This method permanently deletes the specified image from local storage.
+      # By default, it performs safety checks to prevent removal of images with
+      # dependent containers. Force removal bypasses these checks.
+      #
+      # @param id [String] image ID, name, or name:tag to remove
+      # @param server_context [Object] RubyLLM context (unused but required)
+      # @param force [Boolean] whether to force removal despite dependencies (default: false)
+      # @param noprune [Boolean] whether to preserve parent images (default: false)
+      #
+      # @return [RubyLLM::Tool::Response] removal operation results
+      #
+      # @raise [Docker::Error::NotFoundError] if image doesn't exist
+      # @raise [StandardError] for removal failures or dependency conflicts
+      #
+      # @example Remove unused image
+      #   response = RemoveImage.call(
+      #     server_context: context,
+      #     id: "old-version:1.0"
+      #   )
+      #
+      # @example Force remove problematic image
+      #   response = RemoveImage.call(
+      #     server_context: context,
+      #     id: "corrupted-image",
+      #     force: true
+      #   )
+      #
+      # @example Remove while preserving layers
+      #   response = tool.execute(
+      #     id: "temp-image:build-123",
+      #     noprune: true
+      #   )
+      #
+      # @see Docker::Image#remove
+      def execute(id:, force: false, noprune: false)
+        image = ::Docker::Image.get(id)
+        image.remove(force: force, noprune: noprune)
+
+        "Image #{id} removed successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Image #{id} not found"
+      rescue StandardError => e
+        "Error removing image: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/remove_network.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for removing Docker networks.
+    #
+    # This tool provides the ability to permanently delete Docker networks from
+    # the system. It safely removes custom networks while protecting built-in
+    # system networks from accidental deletion.
+    #
+    # == Features
+    #
+    # - Remove custom Docker networks by ID or name
+    # - Protection against removing built-in networks
+    # - Comprehensive error handling
+    # - Dependency checking (prevents removal if containers are connected)
+    # - Safe cleanup of network resources
+    #
+    # == ⚠️ Service Disruption Warning ⚠️
+    #
+    # **NETWORK REMOVAL CAN DISRUPT SERVICES**
+    #
+    # Removing networks can cause immediate service disruption:
+    # - Connected containers lose network connectivity
+    # - Inter-container communication is broken
+    # - Services may become unreachable
+    # - Application functionality can be severely impacted
+    # - Network-dependent processes may fail
+    #
+    # == Protected Networks
+    #
+    # Docker protects certain built-in networks from removal:
+    # - **bridge**: Default bridge network
+    # - **host**: Host networking
+    # - **none**: No networking
+    # - **System networks**: Docker-managed networks
+    #
+    # == Security Considerations
+    #
+    # Network removal affects security boundaries:
+    # - Removes network isolation between containers
+    # - May expose containers to unintended networks
+    # - Could impact security segmentation strategies
+    # - Affects network-based access controls
+    #
+    # Security implications:
+    # - Ensure no critical containers depend on the network
+    # - Verify alternative connectivity exists if needed
+    # - Consider impact on security boundaries
+    # - Monitor for unauthorized network modifications
+    #
+    # Best practices:
+    # - Stop containers before removing their networks
+    # - Verify network dependencies before removal
+    # - Have rollback plans for critical networks
+    # - Document network removal procedures
+    # - Monitor network connectivity after removal
+    #
+    # == Example Usage
+    #
+    #   # Remove custom network
+    #   RemoveNetwork.call(
+    #     server_context: context,
+    #     id: "app-network"
+    #   )
+    #
+    #   # Remove by network ID
+    #   RemoveNetwork.call(
+    #     server_context: context,
+    #     id: "abc123def456"
+    #   )
+    #
+    # @see CreateNetwork
+    # @see ListNetworks
+    # @see Docker::Network#delete
+    # @since 0.1.0
+    class RemoveNetwork < RubyLLM::Tool
+      description 'Remove a Docker network'
+
+      param :id, type: :string, desc: 'Network ID or name'
+
+      # Remove a Docker network from the system.
+      #
+      # This method permanently deletes the specified network. The network
+      # must not have any containers connected to it, and built-in system
+      # networks cannot be removed.
+      #
+      # @param id [String] network ID or name to remove
+      # @param server_context [Object] RubyLLM context (unused but required)
+      #
+      # @return [RubyLLM::Tool::Response] removal operation results
+      #
+      # @raise [Docker::Error::NotFoundError] if network doesn't exist
+      # @raise [StandardError] for removal failures or dependency conflicts
+      #
+      # @example Remove custom network
+      #   response = RemoveNetwork.call(
+      #     server_context: context,
+      #     id: "frontend-network"
+      #   )
+      #
+      # @example Remove by ID
+      #   response = tool.execute(
+      #     id: "1a2b3c4d5e6f"
+      #   )
+      #
+      # @see Docker::Network#delete
+      def execute(id:)
+        network = ::Docker::Network.get(id)
+        network.delete
+
+        "Network #{id} removed successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Network #{id} not found"
+      rescue StandardError => e
+        "Error removing network: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/remove_volume.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for removing Docker volumes.
+    #
+    # This tool provides the ability to permanently delete Docker volumes from
+    # the system. This is a destructive operation that will permanently delete
+    # all data stored in the volume.
+    #
+    # == Features
+    #
+    # - Remove Docker volumes by name
+    # - Force removal option for volumes in use
+    # - Comprehensive error handling
+    # - Dependency checking (prevents removal if containers are using the volume)
+    # - Safe cleanup of storage resources
+    #
+    # == ⚠️ CRITICAL DATA LOSS WARNING ⚠️
+    #
+    # **DESTRUCTIVE OPERATION - PERMANENT DATA LOSS**
+    #
+    # This operation permanently and irreversibly deletes data:
+    # - **ALL DATA** in the volume is deleted forever
+    # - No recovery possible after deletion
+    # - Applications may lose critical data
+    # - Databases and persistent state are destroyed
+    # - Configuration files and user data are lost
+    # - Operation cannot be undone
+    #
+    # == Volume Dependencies
+    #
+    # Volumes may have active dependencies:
+    # - **Running Containers**: Containers currently using the volume
+    # - **Stopped Containers**: Containers that could be restarted
+    # - **Application Data**: Critical application state and databases
+    # - **User Data**: User-generated content and files
+    #
+    # == Security Considerations
+    #
+    # Volume removal has security implications:
+    # - Sensitive data is not securely wiped
+    # - Data may be recoverable from disk sectors
+    # - Shared volumes may affect multiple applications
+    # - Removal logs may reveal data existence
+    #
+    # Critical security measures:
+    # - **Backup critical data** before removal
+    # - Verify no containers depend on the volume
+    # - Consider secure data wiping for sensitive volumes
+    # - Audit volume removal operations
+    # - Monitor for unauthorized volume deletions
+    #
+    # == Force Removal Risks
+    #
+    # Force removal bypasses safety checks:
+    # - Removes volumes even if containers are using them
+    # - Can cause immediate application failures
+    # - May corrupt running applications
+    # - Data loss occurs immediately
+    #
+    # == Example Usage
+    #
+    #   # Safe removal of unused volume
+    #   RemoveVolume.call(
+    #     server_context: context,
+    #     name: "temp-data"
+    #   )
+    #
+    #   # Force removal of volume in use (DANGEROUS)
+    #   RemoveVolume.call(
+    #     server_context: context,
+    #     name: "stuck-volume",
+    #     force: true
+    #   )
+    #
+    # @see CreateVolume
+    # @see ListVolumes
+    # @see Docker::Volume#remove
+    # @since 0.1.0
+    class RemoveVolume < RubyLLM::Tool
+      description 'Remove a Docker volume'
+
+      param :name, type: :string, desc: 'Volume name'
+      param :force, type: :boolean, desc: 'Force removal of the volume (default: false)', required: false
+
+      # Remove a Docker volume permanently from the system.
+      #
+      # This method permanently deletes the specified volume and all data
+      # contained within it. By default, it performs safety checks to prevent
+      # removal of volumes with active container dependencies.
+      #
+      # @param name [String] name of the volume to remove
+      # @param server_context [Object] RubyLLM context (unused but required)
+      # @param force [Boolean] whether to force removal despite dependencies (default: false)
+      #
+      # @return [RubyLLM::Tool::Response] removal operation results
+      #
+      # @raise [Docker::Error::NotFoundError] if volume doesn't exist
+      # @raise [StandardError] for removal failures or dependency conflicts
+      #
+      # @example Remove unused volume
+      #   response = RemoveVolume.call(
+      #     server_context: context,
+      #     name: "old-cache-data"
+      #   )
+      #
+      # @example Force remove problematic volume
+      #   response = tool.execute(
+      #     name: "corrupted-volume",
+      #     force: true
+      #   )
+      #
+      # @see Docker::Volume#remove
+      def execute(name:, force: false)
+        volume = ::Docker::Volume.get(name)
+        volume.remove(force: force)
+
+        "Volume #{name} removed successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Volume #{name} not found"
+      rescue StandardError => e
+        "Error removing volume: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/run_container.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for running Docker containers (create and start in one operation).
+    #
+    # This tool provides a convenient way to create and immediately start Docker
+    # containers from images. It combines the functionality of container creation
+    # and startup into a single operation, which is the most common use case for
+    # Docker containers.
+    #
+    # == Features
+    #
+    # - Create and start containers in one operation
+    # - Full support for container configuration options
+    # - Port mapping and network configuration
+    # - Volume mounting capabilities
+    # - Environment variable configuration
+    # - Custom command execution
+    # - Comprehensive error handling
+    #
+    # == Security Considerations
+    #
+    # - Containers inherit Docker daemon privileges
+    # - Port mappings expose services to host network
+    # - Volume mounts provide filesystem access
+    # - Environment variables may contain sensitive data
+    # - Custom commands can execute arbitrary code
+    #
+    # Use appropriate security measures:
+    # - Run containers with minimal required privileges
+    # - Limit port exposure to necessary services only
+    # - Use read-only volumes where possible
+    # - Avoid mounting sensitive host directories
+    # - Validate environment variables for secrets
+    #
+    # == Example Usage
+    #
+    #   # Simple container run
+    #   RunContainer.call(
+    #     server_context: context,
+    #     image: "nginx:latest",
+    #     name: "web-server"
+    #   )
+    #
+    #   # Advanced configuration with ports and volumes
+    #   RunContainer.call(
+    #     server_context: context,
+    #     image: "postgres:13",
+    #     name: "database",
+    #     env: ["POSTGRES_PASSWORD=secret"],
+    #     host_config: {
+    #       "PortBindings" => {"5432/tcp" => [{"HostPort" => "5432"}]},
+    #       "Binds" => ["/host/data:/var/lib/postgresql/data"]
+    #     }
+    #   )
+    #
+    # @see CreateContainer
+    # @see StartContainer
+    # @see Docker::Container.create
+    # @since 0.1.0
+    class RunContainer < RubyLLM::Tool
+      description 'Run a Docker container (create and start)'
+
+      param :image, desc: 'Image name to use (e.g., "ubuntu:22.04")'
+      param :name, desc: 'Container name (optional)', required: false
+      param :cmd, desc: 'Command to run (optional)', required: false
+      param :env,
+            desc: 'Environment variables as comma-separated KEY=VALUE pairs ' \
+                  '(optional, e.g., "VAR1=value1,VAR2=value2")',
+            required: false
+      param :exposed_ports, desc: 'Exposed ports as JSON object (optional)', required: false
+      param :host_config, desc: 'Host configuration including port bindings, volumes, etc.',
+                          required: false
+
+      def execute(image:, name: nil, cmd: nil, env: nil, exposed_ports: nil, host_config: nil)
+        config = { 'Image' => image }
+        config['name'] = name if name
+        config['Cmd'] = cmd if cmd
+
+        # Parse environment variables string into array if provided
+        if env && !env.empty?
+          env_array = env.split(',').map(&:strip).select { |e| e.include?('=') }
+          config['Env'] = env_array unless env_array.empty?
+        end
+
+        config['ExposedPorts'] = exposed_ports if exposed_ports
+        config['HostConfig'] = host_config if host_config
+
+        container = ::Docker::Container.create(config)
+        container.start
+        container_name = container.info['Names']&.first&.delete_prefix('/')
+
+        "Container started successfully. ID: #{container.id}, Name: #{container_name}"
+      rescue ::Docker::Error::NotFoundError
+        "Image #{image} not found"
+      rescue ::Docker::Error::ConflictError
+        "Container with name #{name} already exists"
+      rescue StandardError => e
+        "Error running container: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/start_container.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for starting existing Docker containers.
+    #
+    # This tool provides the ability to start Docker containers that have been
+    # created but are currently stopped. It's the counterpart to StopContainer
+    # and is commonly used after CreateContainer or when restarting stopped
+    # containers.
+    #
+    # == Features
+    #
+    # - Start stopped containers by ID or name
+    # - Simple and reliable container lifecycle management
+    # - Comprehensive error handling
+    # - Works with containers in any stopped state
+    #
+    # == Security Considerations
+    #
+    # Starting containers can have security implications:
+    # - Containers resume with their original configuration
+    # - Services become accessible on mapped ports
+    # - Processes resume execution with previous privileges
+    # - Network connections are re-established
+    #
+    # Ensure containers are properly configured before starting:
+    # - Review port mappings and network exposure
+    # - Verify volume mounts and file permissions
+    # - Check environment variables for sensitive data
+    # - Validate container image integrity
+    #
+    # == Example Usage
+    #
+    #   # Start container by name
+    #   StartContainer.call(
+    #     server_context: context,
+    #     id: "web-server"
+    #   )
+    #
+    #   # Start container by ID
+    #   StartContainer.call(
+    #     server_context: context,
+    #     id: "a1b2c3d4e5f6"
+    #   )
+    #
+    # @see CreateContainer
+    # @see StopContainer
+    # @see RunContainer
+    # @see Docker::Container#start
+    # @since 0.1.0
+    class StartContainer < RubyLLM::Tool
+      description 'Start a Docker container'
+
+      param :id, desc: 'Container ID or name'
+
+      # Start an existing Docker container.
+      #
+      # This method starts a container that is currently in a stopped state.
+      # The container must already exist and be in a startable state. If the
+      # container is already running, Docker will typically ignore the start
+      # command without error.
+      #
+      # @param id [String] container ID (full or short) or container name
+      # @param server_context [Object] RubyLLM context (unused but required)
+      #
+      # @return [RubyLLM::Tool::Response] start operation results
+      #
+      # @raise [Docker::Error::NotFoundError] if container doesn't exist
+      # @raise [StandardError] for other start failures
+      #
+      # @example Start by container name
+      #   response = StartContainer.call(
+      #     server_context: context,
+      #     id: "my-app-container"
+      #   )
+      #
+      # @example Start by container ID
+      #   response = StartContainer.call(
+      #     server_context: context,
+      #     id: "abc123def456"
+      #   )
+      #
+      # @see Docker::Container#start
+      def execute(id:)
+        container = ::Docker::Container.get(id)
+        container.start
+
+        "Container #{id} started successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Container #{id} not found"
+      rescue StandardError => e
+        "Error starting container: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/stop_container.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for stopping running Docker containers.
+    #
+    # This tool provides the ability to gracefully stop running Docker containers
+    # with configurable timeout handling. It sends a SIGTERM signal to the main
+    # process and waits for the specified timeout before forcibly killing the
+    # container with SIGKILL.
+    #
+    # == Features
+    #
+    # - Graceful container shutdown with SIGTERM
+    # - Configurable timeout before force kill
+    # - Works with containers by ID or name
+    # - Comprehensive error handling
+    # - Safe for already stopped containers
+    #
+    # == Shutdown Process
+    #
+    # 1. Send SIGTERM to container's main process
+    # 2. Wait for graceful shutdown up to timeout
+    # 3. Send SIGKILL if container hasn't stopped
+    # 4. Return success when container is stopped
+    #
+    # == Security Considerations
+    #
+    # Stopping containers affects service availability:
+    # - Services become unavailable immediately
+    # - Network connections are terminated
+    # - Data may be lost if not properly persisted
+    # - Dependent services may be affected
+    #
+    # Best practices:
+    # - Ensure data persistence before stopping
+    # - Consider impact on dependent services
+    # - Use appropriate timeout for graceful shutdown
+    # - Monitor application logs during shutdown
+    #
+    # == Example Usage
+    #
+    #   # Stop with default timeout (10 seconds)
+    #   StopContainer.call(
+    #     server_context: context,
+    #     id: "web-server"
+    #   )
+    #
+    #   # Stop with custom timeout
+    #   StopContainer.call(
+    #     server_context: context,
+    #     id: "database",
+    #     timeout: 30
+    #   )
+    #
+    # @see StartContainer
+    # @see RemoveContainer
+    # @see Docker::Container#stop
+    # @since 0.1.0
+    class StopContainer < RubyLLM::Tool
+      description 'Stop a Docker container'
+
+      param :id, desc: 'Container ID or name'
+      param :timeout, type: :integer, desc: 'Seconds to wait before killing the container (default: 10)',
+                      required: false
+
+      # Stop a running Docker container gracefully.
+      #
+      # This method stops a container by sending SIGTERM to the main process
+      # and waiting for the specified timeout before sending SIGKILL. The
+      # operation is idempotent - stopping an already stopped container
+      # typically succeeds without error.
+      #
+      # @param id [String] container ID (full or short) or container name
+      # @param server_context [Object] RubyLLM context (unused but required)
+      # @param timeout [Integer] seconds to wait before force killing (default: 10)
+      #
+      # @return [RubyLLM::Tool::Response] stop operation results
+      #
+      # @raise [Docker::Error::NotFoundError] if container doesn't exist
+      # @raise [StandardError] for other stop failures
+      #
+      # @example Stop with default timeout
+      #   response = StopContainer.call(
+      #     server_context: context,
+      #     id: "nginx-server"
+      #   )
+      #
+      # @example Stop database with longer timeout
+      #   response = StopContainer.call(
+      #     server_context: context,
+      #     id: "postgres-db",
+      #     timeout: 60  # Allow more time for DB shutdown
+      #   )
+      #
+      # @see Docker::Container#stop
+      def execute(id:, timeout: 10)
+        container = ::Docker::Container.get(id)
+        container.stop('timeout' => timeout)
+
+        "Container #{id} stopped successfully"
+      rescue ::Docker::Error::NotFoundError
+        "Container #{id} not found"
+      rescue StandardError => e
+        "Error stopping container: #{e.message}"
+      end
+    end
+  end
+end