ruby_llm-docker 0.0.1 → 0.2.5

data/lib/ruby_llm/docker/build_image.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for building Docker images from Dockerfile content.
+    #
+    # This tool provides the ability to build Docker images by providing Dockerfile
+    # content as a string. It supports optional tagging of the resulting image for
+    # easy identification and reuse.
+    #
+    # == Security Considerations
+    #
+    # Building Docker images can be potentially dangerous:
+    # - Dockerfile commands execute with Docker daemon privileges
+    # - Images can contain malicious software or backdoors
+    # - Build process can access host resources (network, files)
+    # - Base images may contain vulnerabilities
+    # - Build context may expose sensitive information
+    #
+    # Security recommendations:
+    # - Review Dockerfile content carefully before building
+    # - Use trusted base images from official repositories
+    # - Scan built images for vulnerabilities
+    # - Limit network access during builds
+    # - Avoid including secrets in Dockerfile instructions
+    # - Use multi-stage builds to minimize final image size
+    #
+    # == Features
+    #
+    # - Build images from Dockerfile content strings
+    # - Optional image tagging during build
+    # - Comprehensive error handling
+    # - Support for all standard Dockerfile instructions
+    # - Returns image ID and build status
+    #
+    # == Example Usage
+    #
+    #   # Simple image build
+    #   BuildImage.call(
+    #     server_context: context,
+    #     dockerfile: "FROM alpine:latest\nRUN apk add --no-cache curl"
+    #   )
+    #
+    #   # Build with custom tag
+    #   BuildImage.call(
+    #     server_context: context,
+    #     dockerfile: dockerfile_content,
+    #     tag: "myapp:v1.0"
+    #   )
+    #
+    # @see Docker::Image.build
+    # @see TagImage
+    # @since 0.1.0
+    class BuildImage < RubyLLM::Tool
+      description 'Build a Docker image'
+
+      param :dockerfile, type: :string, desc: 'Dockerfile content as a string'
+      param :tag, type: :string, desc: 'Tag for the built image (e.g., "myimage:latest")', required: false
+
+      # Build a Docker image from Dockerfile content.
+      #
+      # This method creates a Docker image by building from the provided Dockerfile
+      # content string. The Dockerfile is processed by the Docker daemon and can
+      # include any valid Dockerfile instructions. Optionally, the resulting image
+      # can be tagged with a custom name for easy reference.
+      #
+      # @param dockerfile [String] the complete Dockerfile content as a string
+      # @param server_context [Object] RubyLLM context (unused but required)
+      # @param tag [String, nil] optional tag to apply to the built image
+      #
+      # @return [RubyLLM::Tool::Response] build results including image ID and tag info
+      #
+      # @raise [Docker::Error] for Docker daemon communication errors
+      # @raise [StandardError] for build failures or other errors
+      #
+      # @example Build simple image
+      #   dockerfile = <<~DOCKERFILE
+      #     FROM alpine:latest
+      #     RUN apk add --no-cache nginx
+      #     EXPOSE 80
+      #     CMD ["nginx", "-g", "daemon off;"]
+      #   DOCKERFILE
+      #
+      #   response = tool.execute(
+      #     dockerfile: dockerfile,
+      #     tag: "my-nginx:latest"
+      #   )
+      #
+      # @see Docker::Image.build
+      def execute(dockerfile:, tag: nil)
+        # Build the image
+        image = ::Docker::Image.build(dockerfile)
+
+        # If a tag was specified, tag the image
+        if tag
+          # Split tag into repo and tag parts
+          repo, image_tag = tag.split(':', 2)
+          image_tag ||= 'latest'
+          image.tag('repo' => repo, 'tag' => image_tag, 'force' => true)
+        end
+
+        response_text = "Image built successfully. ID: #{image.id}"
+        response_text += ", Tag: #{tag}" if tag
+
+        response_text
+      rescue StandardError => e
+        "Error building image: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/copy_to_container.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for copying files and directories from host to Docker containers.
+    #
+    # This tool provides the ability to copy files or entire directory trees from
+    # the host filesystem into running Docker containers. It uses Docker's archive
+    # streaming API to efficiently transfer files while preserving permissions and
+    # directory structure.
+    #
+    # == ⚠️ SECURITY WARNING ⚠️
+    #
+    # This tool can be dangerous as it allows:
+    # - Reading arbitrary files from the host filesystem
+    # - Writing files into container filesystems
+    # - Potentially overwriting critical container files
+    # - Escalating privileges if used with setuid/setgid files
+    # - Exposing sensitive host data to containers
+    #
+    # Security recommendations:
+    # - Validate source paths to prevent directory traversal
+    # - Ensure containers run with minimal privileges
+    # - Monitor file copy operations for sensitive paths
+    # - Use read-only filesystems where possible
+    # - Implement proper access controls on source files
+    #
+    # == Features
+    #
+    # - Copy individual files or entire directories
+    # - Preserve file permissions and directory structure
+    # - Optional ownership changes after copy
+    # - Comprehensive error handling
+    # - Support for both absolute and relative paths
+    #
+    # == Example Usage
+    #
+    #   # Copy a configuration file
+    #   CopyToContainer.call(
+    #     server_context: context,
+    #     id: "web-server",
+    #     source_path: "/host/config/nginx.conf",
+    #     destination_path: "/etc/nginx/"
+    #   )
+    #
+    #   # Copy directory with ownership change
+    #   CopyToContainer.call(
+    #     server_context: context,
+    #     id: "app-container",
+    #     source_path: "/host/app/src",
+    #     destination_path: "/app/",
+    #     owner: "appuser:appgroup"
+    #   )
+    #
+    # @see Docker::Container#archive_in_stream
+    # @since 0.1.0
+    class CopyToContainer < RubyLLM::Tool
+      description 'Copy a file or directory from the local filesystem into a running Docker container. ' \
+                  'The source path is on the local machine, and the destination path is inside the container.'
+
+      param :id, type: :string, desc: 'Container ID or name'
+      param :source_path, type: :string, desc: 'Path to the file or directory on the local filesystem to copy'
+      param :destination_path, type: :string,
+                               desc: 'Path inside the container where the file/directory should be copied'
+      param :owner, type: :string,
+                    desc: 'Owner for the copied files (optional, e.g., "1000:1000" or "username:group")',
+                    required: false
+
+      # Copy files or directories from host filesystem to a Docker container.
+      #
+      # This method creates a tar archive of the source path and streams it into
+      # the specified container using Docker's archive API. The operation preserves
+      # file permissions and directory structure. Optionally, ownership can be
+      # changed after the copy operation completes.
+      #
+      # The source path must exist on the host filesystem and be readable by the
+      # process running the application. The destination path must be a valid path
+      # within the container.
+      #
+      # @param id [String] container ID or name to copy files into
+      # @param source_path [String] path to file/directory on host filesystem
+      # @param destination_path [String] destination path inside container
+      # @param server_context [Object] RubyLLM context (unused but required)
+      # @param owner [String, nil] ownership specification (e.g., "user:group", "1000:1000")
+      #
+      # @return [RubyLLM::Tool::Response] success/failure message with operation details
+      #
+      # @raise [Docker::Error::NotFoundError] if container doesn't exist
+      # @raise [StandardError] for file system or Docker API errors
+      #
+      # @example Copy configuration file
+      #   response = CopyToContainer.call(
+      #     server_context: context,
+      #     id: "nginx-container",
+      #     source_path: "/etc/nginx/sites-available/default",
+      #     destination_path: "/etc/nginx/sites-enabled/"
+      #   )
+      #
+      # @example Copy directory with ownership
+      #   response = tool.execute(
+      #     id: "app-container",
+      #     source_path: "/local/project",
+      #     destination_path: "/app/",
+      #     owner: "www-data:www-data"
+      #   )
+      #
+      # @see Docker::Container#archive_in_stream
+      # @see #add_to_tar
+      def execute(id:, source_path:, destination_path:, owner: nil)
+        container = ::Docker::Container.get(id)
+
+        # Verify source path exists
+        return "Source path not found: #{source_path}" unless File.exist?(source_path)
+
+        # Create a tar archive of the source
+        tar_io = StringIO.new
+        tar_io.set_encoding('ASCII-8BIT')
+
+        Gem::Package::TarWriter.new(tar_io) do |tar|
+          self.class.add_to_tar(tar, source_path, File.basename(source_path))
+        end
+
+        tar_io.rewind
+
+        # Copy to container
+        container.archive_in_stream(destination_path) do
+          tar_io.read
+        end
+
+        # Optionally change ownership
+        if owner
+          chown_path = File.join(destination_path, File.basename(source_path))
+          container.exec(['chown', '-R', owner, chown_path])
+        end
+
+        file_type = File.directory?(source_path) ? 'directory' : 'file'
+        response_text = "Successfully copied #{file_type} from #{source_path} to #{id}:#{destination_path}"
+        response_text += "\nOwnership changed to #{owner}" if owner
+
+        response_text
+      rescue ::Docker::Error::NotFoundError
+        "Container #{id} not found"
+      rescue StandardError => e
+        "Error copying to container: #{e.message}"
+      end
+
+      # Recursively add files and directories to a tar archive.
+      #
+      # This helper method builds a tar archive by recursively traversing
+      # the filesystem starting from the given path. It preserves file
+      # permissions and handles both files and directories appropriately.
+      #
+      # For directories, it creates directory entries in the tar and then
+      # recursively processes all contained files and subdirectories.
+      # For files, it reads the content and adds it to the tar with
+      # preserved permissions.
+      #
+      # @param tar [Gem::Package::TarWriter] the tar writer instance
+      # @param path [String] the filesystem path to add to the archive
+      # @param archive_path [String] the path within the tar archive
+      #
+      # @return [void]
+      #
+      # @example Add single file
+      #   add_to_tar(tar_writer, "/host/file.txt", "file.txt")
+      #
+      # @example Add directory tree
+      #   add_to_tar(tar_writer, "/host/mydir", "mydir")
+      #
+      # @see Gem::Package::TarWriter#mkdir
+      # @see Gem::Package::TarWriter#add_file_simple
+      def self.add_to_tar(tar, path, archive_path)
+        if File.directory?(path)
+          # Add directory entry
+          tar.mkdir(archive_path, File.stat(path).mode)
+
+          # Add directory contents
+          Dir.entries(path).each do |entry|
+            next if ['.', '..'].include?(entry)
+
+            full_path = File.join(path, entry)
+            archive_entry_path = File.join(archive_path, entry)
+            add_to_tar(tar, full_path, archive_entry_path)
+          end
+        else
+          # Add file
+          File.open(path, 'rb') do |file|
+            tar.add_file_simple(archive_path, File.stat(path).mode, file.size) do |tar_file|
+              IO.copy_stream(file, tar_file)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/create_container.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for creating Docker containers without starting them.
+    #
+    # This tool provides the ability to create Docker containers from images with
+    # comprehensive configuration options. Unlike RunContainer, this tool only
+    # creates the container but does not start it, allowing for additional
+    # configuration or manual startup control.
+    #
+    # == Features
+    #
+    # - Create containers from any available Docker image
+    # - Full container configuration support
+    # - Port exposure and binding configuration
+    # - Volume mounting capabilities
+    # - Environment variable configuration
+    # - Custom command specification
+    # - Comprehensive error handling with specific error types
+    #
+    # == Security Considerations
+    #
+    # - Containers inherit Docker daemon security context
+    # - Host configuration can expose host resources
+    # - Volume mounts provide filesystem access
+    # - Port bindings expose services to networks
+    # - Environment variables may contain sensitive data
+    #
+    # Use appropriate security measures:
+    # - Validate image sources and integrity
+    # - Limit host resource exposure
+    # - Use read-only volumes where appropriate
+    # - Restrict network access through host configuration
+    # - Sanitize environment variables
+    #
+    # == Example Usage
+    #
+    #   # Simple container creation
+    #   CreateContainer.call(
+    #     server_context: context,
+    #     image: "nginx:latest",
+    #     name: "web-server"
+    #   )
+    #
+    #   # Advanced container with configuration
+    #   CreateContainer.call(
+    #     server_context: context,
+    #     image: "postgres:13",
+    #     name: "database",
+    #     env: "POSTGRES_PASSWORD=secret,POSTGRES_DB=myapp",
+    #     exposed_ports: {"5432/tcp" => {}},
+    #     host_config: {
+    #       "PortBindings" => {"5432/tcp" => [{"HostPort" => "5432"}]},
+    #       "Binds" => ["/host/data:/var/lib/postgresql/data:rw"]
+    #     }
+    #   )
+    #
+    # @see RunContainer
+    # @see StartContainer
+    # @see Docker::Container.create
+    # @since 0.1.0
+    class CreateContainer < RubyLLM::Tool
+      description 'Create a Docker container'
+
+      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. as JSON object (optional)',
+                          required: false
+
+      # Create a new Docker container from an image.
+      #
+      # This method creates a container with the specified configuration but does
+      # not start it. The container can be started later using StartContainer or
+      # other Docker commands. All configuration parameters are optional except
+      # for the base image.
+      #
+      # @param image [String] Docker image name with optional tag (e.g., "nginx:latest")
+      # @param server_context [Object] RubyLLM context (unused but required)
+      # @param name [String, nil] custom name for the container
+      # @param cmd [String, nil] command to execute in the container
+      # @param env [String, nil] environment variables as comma-separated KEY=VALUE pairs
+      # @param exposed_ports [Hash, nil] ports to expose in {"port/protocol" => {}} format
+      # @param host_config [Hash, nil] Docker host configuration including bindings and volumes
+      #
+      # @return [RubyLLM::Tool::Response] creation results with container ID and name
+      #
+      # @raise [Docker::Error::NotFoundError] if the specified image doesn't exist
+      # @raise [Docker::Error::ConflictError] if container name already exists
+      # @raise [StandardError] for other creation failures
+      #
+      # @example Create simple container
+      #   response = CreateContainer.call(
+      #     server_context: context,
+      #     image: "alpine:latest",
+      #     name: "test-container"
+      #   )
+      #
+      # @example Create container with full configuration
+      #   response = CreateContainer.call(
+      #     server_context: context,
+      #     image: "redis:7-alpine",
+      #     name: "redis-cache",
+      #     env: "REDIS_PASSWORD=secret",
+      #     exposed_ports: {"6379/tcp" => {}},
+      #     host_config: {
+      #       "PortBindings" => {"6379/tcp" => [{"HostPort" => "6379"}]},
+      #       "RestartPolicy" => {"Name" => "unless-stopped"}
+      #     }
+      #   )
+      #
+      # @see Docker::Container.create
+      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_name = container.info['Names']&.first&.delete_prefix('/')
+
+        "Container created 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 creating container: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ruby_llm/docker/create_network.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Docker
+    # RubyLLM tool for creating Docker networks.
+    #
+    # This tool provides the ability to create custom Docker networks for
+    # container communication and isolation. Networks enable containers to
+    # communicate securely while providing isolation from other network
+    # segments.
+    #
+    # == Features
+    #
+    # - Create custom Docker networks
+    # - Support for different network drivers
+    # - Duplicate name detection
+    # - Comprehensive error handling
+    # - Flexible network configuration
+    #
+    # == Network Drivers
+    #
+    # Docker supports various network drivers:
+    # - **bridge**: Default isolated network for single-host networking
+    # - **host**: Remove network isolation, use host networking directly
+    # - **overlay**: Multi-host networking for swarm services
+    # - **macvlan**: Assign MAC addresses to containers
+    # - **none**: Disable networking completely
+    # - **Custom**: Third-party network drivers
+    #
+    # == Security Considerations
+    #
+    # Network creation affects system security:
+    # - **Network Isolation**: Networks provide security boundaries
+    # - **Traffic Control**: Custom networks enable traffic filtering
+    # - **Access Control**: Networks control container communication
+    # - **DNS Resolution**: Networks provide internal DNS services
+    #
+    # Security implications:
+    # - Bridge networks isolate containers from host network
+    # - Host networks expose containers to all host traffic
+    # - Custom networks should follow least-privilege principles
+    # - Network names may reveal infrastructure details
+    #
+    # Best practices:
+    # - Use descriptive but not sensitive network names
+    # - Implement network segmentation strategies
+    # - Limit container access to necessary networks only
+    # - Monitor network traffic and connections
+    # - Regular audit of network configurations
+    #
+    # == Example Usage
+    #
+    #   # Create basic bridge network
+    #   CreateNetwork.call(
+    #     server_context: context,
+    #     name: "app-network"
+    #   )
+    #
+    #   # Create network with specific driver
+    #   CreateNetwork.call(
+    #     server_context: context,
+    #     name: "frontend-net",
+    #     driver: "bridge"
+    #   )
+    #
+    #   # Create without duplicate checking
+    #   CreateNetwork.call(
+    #     server_context: context,
+    #     name: "temp-network",
+    #     check_duplicate: false
+    #   )
+    #
+    # @see ListNetworks
+    # @see RemoveNetwork
+    # @see Docker::Network.create
+    # @since 0.1.0
+    class CreateNetwork < RubyLLM::Tool
+      description 'Create a Docker network'
+
+      param :name, type: :string, desc: 'Name of the network'
+      param :driver, type: :string, desc: 'Driver to use (default: bridge)', required: false
+      param :check_duplicate, type: :boolean, desc: 'Check for networks with duplicate names (default: true)',
+                              required: false
+
+      # Create a new Docker network.
+      #
+      # This method creates a custom Docker network with the specified name
+      # and driver. The network can then be used by containers for isolated
+      # communication.
+      #
+      # @param name [String] name for the new network
+      # @param server_context [Object] RubyLLM context (unused but required)
+      # @param driver [String] network driver to use (default: "bridge")
+      # @param check_duplicate [Boolean] whether to check for duplicate names (default: true)
+      #
+      # @return [RubyLLM::Tool::Response] network creation results with network ID
+      #
+      # @raise [Docker::Error::ConflictError] if network name already exists
+      # @raise [StandardError] for other network creation failures
+      #
+      # @example Create application network
+      #   response = CreateNetwork.call(
+      #     server_context: context,
+      #     name: "webapp-network"
+      #   )
+      #
+      # @example Create host network
+      #   response = tool.execute(
+      #     name: "high-performance-net",
+      #     driver: "host"
+      #   )
+      #
+      # @see Docker::Network.create
+      def execute(name:, driver: 'bridge', check_duplicate: true)
+        options = {
+          'Name' => name,
+          'Driver' => driver,
+          'CheckDuplicate' => check_duplicate
+        }
+
+        network = ::Docker::Network.create(name, options)
+
+        "Network #{name} created successfully. ID: #{network.id}"
+      rescue ::Docker::Error::ConflictError
+        "Network #{name} already exists"
+      rescue StandardError => e
+        "Error creating network: #{e.message}"
+      end
+    end
+  end
+end