pvectl 0.2.0

data/lib/pvectl/services/clone_vm.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates VM clone operations.
+    #
+    # Handles validation, auto-generation of VMID/name, and sync/async modes.
+    # Supports both full clones and linked clones (templates only).
+    #
+    # @example Full clone with auto-generated VMID
+    #   service = CloneVm.new(vm_repository: vm_repo, task_repository: task_repo)
+    #   result = service.execute(vmid: 100)
+    #
+    # @example Linked clone to specific node
+    #   service = CloneVm.new(vm_repository: vm_repo, task_repository: task_repo)
+    #   result = service.execute(vmid: 100, linked: true, target_node: "pve2")
+    #
+    # @example Async clone with custom timeout
+    #   service = CloneVm.new(vm_repository: vm_repo, task_repository: task_repo, options: { async: true })
+    #   result = service.execute(vmid: 100, new_vmid: 200, name: "web-clone")
+    #
+    class CloneVm
+      DEFAULT_TIMEOUT = 300
+
+      # @return [Integer] Default timeout for start operations (seconds)
+      START_TIMEOUT = 60
+
+      # Creates a new CloneVm service.
+      #
+      # @param vm_repository [Repositories::Vm] VM repository
+      # @param task_repository [Repositories::Task] Task repository
+      # @param options [Hash] Options (timeout, async)
+      def initialize(vm_repository:, task_repository:, options: {})
+        @vm_repository = vm_repository
+        @task_repository = task_repository
+        @options = options
+      end
+
+      # Executes clone operation.
+      #
+      # Performs a two-step flow: clone the VM first, then optionally apply
+      # config updates via PUT /nodes/{node}/qemu/{vmid}/config.
+      #
+      # @param vmid [Integer] Source VM identifier
+      # @param node [String, nil] Source node (auto-detected from VM if nil)
+      # @param new_vmid [Integer, nil] New VMID (auto-selected if nil)
+      # @param name [String, nil] Name for clone (auto-generated if nil)
+      # @param target_node [String, nil] Target node for clone
+      # @param storage [String, nil] Target storage
+      # @param linked [Boolean] Linked clone (default: false, requires template)
+      # @param pool [String, nil] Resource pool
+      # @param description [String, nil] Description
+      # @param config_params [Hash] VM config parameters to apply after clone
+      # @return [Models::OperationResult] Clone result
+      def execute(vmid:, node: nil, new_vmid: nil, name: nil, target_node: nil,
+                  storage: nil, linked: false, pool: nil, description: nil,
+                  config_params: {})
+        source_vm = @vm_repository.get(vmid)
+        return vm_not_found_error(vmid) unless source_vm
+
+        if linked && !source_vm.template?
+          return linked_clone_error(source_vm)
+        end
+
+        node ||= source_vm.node
+        new_vmid ||= @vm_repository.next_available_vmid
+        name ||= generate_name(source_vm)
+
+        clone_options = build_clone_options(
+          name: name, target_node: target_node, storage: storage,
+          linked: linked, pool: pool, description: description
+        )
+
+        upid = @vm_repository.clone(vmid, node, new_vmid, clone_options)
+        resource_info = { new_vmid: new_vmid, name: name, node: target_node || node }
+
+        if @options[:async]
+          Models::VmOperationResult.new(
+            vm: source_vm, operation: :clone,
+            task_upid: upid, success: :pending,
+            resource: resource_info
+          )
+        else
+          task = @task_repository.wait(upid, timeout: timeout)
+
+          unless task.successful?
+            return Models::VmOperationResult.new(
+              vm: source_vm, operation: :clone,
+              task: task, success: task.successful?,
+              resource: resource_info
+            )
+          end
+
+          if config_params.any?
+            apply_config_update(source_vm, new_vmid, resource_info[:node], config_params, resource_info)
+          else
+            start_vm(new_vmid, resource_info[:node]) if @options[:start]
+            Models::VmOperationResult.new(
+              vm: source_vm, operation: :clone,
+              task: task, success: true,
+              resource: resource_info
+            )
+          end
+        end
+      rescue StandardError => e
+        Models::VmOperationResult.new(
+          vm: source_vm, operation: :clone,
+          success: false, error: e.message
+        )
+      end
+
+      private
+
+      # Generates clone name from source VM.
+      #
+      # @param source_vm [Models::Vm] Source VM
+      # @return [String] Generated name
+      def generate_name(source_vm)
+        if source_vm.name && !source_vm.name.empty?
+          "#{source_vm.name}-clone"
+        else
+          "vm-#{source_vm.vmid}-clone"
+        end
+      end
+
+      # Builds clone options hash for repository call.
+      #
+      # @param name [String] Clone name
+      # @param target_node [String, nil] Target node
+      # @param storage [String, nil] Target storage
+      # @param linked [Boolean] Linked clone flag
+      # @param pool [String, nil] Resource pool
+      # @param description [String, nil] Description
+      # @return [Hash] Clone options
+      def build_clone_options(name:, target_node:, storage:, linked:, pool:, description:)
+        opts = { name: name, full: !linked }
+        opts[:target] = target_node if target_node
+        opts[:storage] = storage if storage
+        opts[:pool] = pool if pool
+        opts[:description] = description if description
+        opts
+      end
+
+      # Applies config update to the cloned VM.
+      #
+      # Converts user-friendly params to Proxmox API format and calls
+      # the repository update method. Returns partial result on failure.
+      #
+      # @param source_vm [Models::Vm] Source VM
+      # @param new_vmid [Integer] Cloned VM identifier
+      # @param node [String] Target node for the cloned VM
+      # @param config_params [Hash] Config parameters to apply
+      # @param resource_info [Hash] Resource info for result
+      # @return [Models::VmOperationResult] Operation result
+      def apply_config_update(source_vm, new_vmid, node, config_params, resource_info)
+        api_params = build_config_api_params(config_params)
+        @vm_repository.update(new_vmid, node, api_params)
+        start_vm(new_vmid, node) if @options[:start]
+        Models::VmOperationResult.new(
+          vm: source_vm, operation: :clone,
+          success: true, resource: resource_info
+        )
+      rescue StandardError => e
+        Models::VmOperationResult.new(
+          vm: source_vm, operation: :clone,
+          success: :partial, resource: resource_info,
+          error: "Cloned successfully, but config update failed: #{e.message}"
+        )
+      end
+
+      # Builds Proxmox API parameters from user-friendly config options.
+      #
+      # Maps config keys to their Proxmox API equivalents. Does not include
+      # name, description, or pool (those belong to the clone step).
+      #
+      # @param config_params [Hash] User-friendly config parameters
+      # @return [Hash] Proxmox API parameters
+      def build_config_api_params(config_params)
+        params = {}
+        params[:cores] = config_params[:cores] if config_params[:cores]
+        params[:sockets] = config_params[:sockets] if config_params[:sockets]
+        params[:cpu] = config_params[:cpu_type] if config_params[:cpu_type]
+        params[:numa] = config_params[:numa] ? 1 : 0 unless config_params[:numa].nil?
+        params[:memory] = config_params[:memory] if config_params[:memory]
+        params[:balloon] = config_params[:balloon] if config_params[:balloon]
+        add_disk_params(params, config_params[:disks]) if config_params[:disks]
+        params[:scsihw] = config_params[:scsihw] if config_params[:scsihw]
+        params[:cdrom] = config_params[:cdrom] if config_params[:cdrom]
+        add_net_params(params, config_params[:nets]) if config_params[:nets]
+        params[:bios] = config_params[:bios] if config_params[:bios]
+        params[:boot] = "order=#{config_params[:boot_order]}" if config_params[:boot_order]
+        params[:machine] = config_params[:machine] if config_params[:machine]
+        params[:efidisk0] = config_params[:efidisk] if config_params[:efidisk]
+        params.merge!(config_params[:cloud_init]) if config_params[:cloud_init]
+        params[:agent] = config_params[:agent] ? "1" : "0" unless config_params[:agent].nil?
+        params[:ostype] = config_params[:ostype] if config_params[:ostype]
+        params[:tags] = config_params[:tags] if config_params[:tags]
+        params
+      end
+
+      # Adds disk parameters mapped to scsi0, scsi1, etc.
+      #
+      # @param params [Hash] Parameters hash to modify
+      # @param disks [Array<Hash>] Disk configurations
+      # @return [void]
+      def add_disk_params(params, disks)
+        disks.each_with_index do |disk, index|
+          params[:"scsi#{index}"] = Parsers::DiskConfig.to_proxmox(disk)
+        end
+      end
+
+      # Adds network parameters mapped to net0, net1, etc.
+      #
+      # @param params [Hash] Parameters hash to modify
+      # @param nets [Array<Hash>] Network configurations
+      # @return [void]
+      def add_net_params(params, nets)
+        nets.each_with_index do |net, index|
+          params[:"net#{index}"] = Parsers::NetConfig.to_proxmox(net)
+        end
+      end
+
+      # Starts a VM after successful clone and config update.
+      #
+      # @param vmid [Integer] VM identifier
+      # @param node [String] Node name
+      # @return [void]
+      def start_vm(vmid, node)
+        upid = @vm_repository.start(vmid, node)
+        @task_repository.wait(upid, timeout: START_TIMEOUT)
+      end
+
+      # Returns configured timeout.
+      #
+      # @return [Integer] Timeout in seconds
+      def timeout
+        @options[:timeout] || DEFAULT_TIMEOUT
+      end
+
+      # Returns error for VM not found.
+      #
+      # @param vmid [Integer] VM identifier
+      # @return [Models::OperationResult] Failed result
+      def vm_not_found_error(vmid)
+        Models::VmOperationResult.new(
+          operation: :clone,
+          success: false,
+          error: "VM #{vmid} not found"
+        )
+      end
+
+      # Returns error for linked clone of non-template VM.
+      #
+      # @param source_vm [Models::Vm] Source VM
+      # @return [Models::OperationResult] Failed result
+      def linked_clone_error(source_vm)
+        Models::VmOperationResult.new(
+          vm: source_vm, operation: :clone,
+          success: false,
+          error: "Linked clone requires VM to be a template. VM #{source_vm.vmid} is not a template"
+        )
+      end
+    end
+  end
+end

data/lib/pvectl/services/cloudinit.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates cloud-init operations on VMs.
+    #
+    # Provides three operations:
+    # - +regenerate+ — rebuild the cloud-init ISO from current config
+    # - +pending+    — list configuration changes not yet applied
+    # - +dump+       — retrieve the auto-generated cloud-init YAML
+    #
+    # Operations are VM-only — LXC containers do not expose cloud-init
+    # endpoints. When the +vmid+ resolves to a non-QEMU resource, the
+    # service raises +Pvectl::ResourceNotFoundError+.
+    #
+    # @example Regenerate ISO for a VM
+    #   service = Cloudinit.new(vm_repository: vm_repo, resource_resolver: resolver)
+    #   service.regenerate(100)
+    #
+    # @example Dump generated user-data YAML
+    #   yaml = service.dump(100, "user")
+    #
+    class Cloudinit
+      # Cloud-init config types supported by the +dump+ operation.
+      VALID_DUMP_TYPES = %w[user network meta].freeze
+
+      # Creates a new Cloudinit service.
+      #
+      # @param vm_repository [Repositories::Vm] VM repository
+      # @param resource_resolver [Utils::ResourceResolver] resolver for VMID -> node
+      def initialize(vm_repository:, resource_resolver:)
+        @vm_repository = vm_repository
+        @resolver = resource_resolver
+      end
+
+      # Regenerates the cloud-init ISO for the given VM.
+      #
+      # @param vmid [Integer] VM identifier
+      # @param node [String, nil] explicit node name (skips resolver)
+      # @return [Hash{Symbol => untyped}] +{ vmid: Integer, node: String }+
+      # @raise [Pvectl::ResourceNotFoundError] when VM does not exist or is not QEMU
+      def regenerate(vmid, node: nil)
+        node ||= resolve_node!(vmid)
+        @vm_repository.cloudinit_regenerate(node, vmid)
+        { vmid: vmid, node: node }
+      end
+
+      # Returns pending cloud-init configuration changes.
+      #
+      # @param vmid [Integer] VM identifier
+      # @param node [String, nil] explicit node name (skips resolver)
+      # @return [Array<Hash{Symbol => untyped}>] pending entries
+      # @raise [Pvectl::ResourceNotFoundError] when VM does not exist or is not QEMU
+      def pending(vmid, node: nil)
+        node ||= resolve_node!(vmid)
+        @vm_repository.cloudinit_pending(node, vmid)
+      end
+
+      # Dumps the auto-generated cloud-init configuration.
+      #
+      # @param vmid [Integer] VM identifier
+      # @param type [String] one of +"user"+, +"network"+, +"meta"+
+      # @param node [String, nil] explicit node name (skips resolver)
+      # @return [String] raw cloud-init YAML/text
+      # @raise [ArgumentError] when +type+ is not a valid dump type
+      # @raise [Pvectl::ResourceNotFoundError] when VM does not exist or is not QEMU
+      def dump(vmid, type, node: nil)
+        unless VALID_DUMP_TYPES.include?(type)
+          raise ArgumentError, "Invalid cloud-init dump type: #{type.inspect} " \
+                               "(valid: #{VALID_DUMP_TYPES.join(', ')})"
+        end
+
+        node ||= resolve_node!(vmid)
+        @vm_repository.cloudinit_dump(node, vmid, type)
+      end
+
+      private
+
+      # Resolves a VMID to its node, ensuring the resource is a QEMU VM.
+      #
+      # @param vmid [Integer] VM identifier
+      # @return [String] node name
+      # @raise [Pvectl::ResourceNotFoundError] when not found or not a VM
+      def resolve_node!(vmid)
+        resolved = @resolver.resolve(vmid)
+        raise Pvectl::ResourceNotFoundError, "VM #{vmid} not found" if resolved.nil?
+
+        unless resolved[:type] == :qemu
+          raise Pvectl::ResourceNotFoundError, "Resource #{vmid} is not a VM (cloud-init is VM-only)"
+        end
+
+        resolved[:node]
+      end
+    end
+  end
+end

data/lib/pvectl/services/console.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "uri"
+require "rest_client"
+require "json"
+
+module Pvectl
+  module Services
+    # Orchestrates an interactive console session to a VM or container.
+    #
+    # Handles: authentication (session ticket), termproxy setup,
+    # WebSocket URL construction, and terminal session lifecycle.
+    #
+    # @example Basic usage
+    #   service = Console.new
+    #   service.run(resource: vm, resource_path: "qemu/100", server: "https://pve1:8006",
+    #               username: "root@pam", password: "secret", verify_ssl: true)
+    #
+    class Console
+      # Raised when the target resource is not in a running state.
+      class ResourceNotRunningError < Pvectl::Error; end
+
+      # Raised when authentication fails.
+      class AuthenticationError < Pvectl::Error; end
+
+      # Builds the WebSocket URL for vncwebsocket endpoint.
+      #
+      # @param server [String] Proxmox server URL (e.g. "https://pve1:8006")
+      # @param node [String] node name
+      # @param resource_path [String] resource path (e.g. "qemu/100" or "lxc/200")
+      # @param port [Integer] termproxy port
+      # @param ticket [String] PVEVNC ticket
+      # @return [String] full WebSocket URL
+      def build_websocket_url(server:, node:, resource_path:, port:, ticket:)
+        uri = URI.parse(server)
+        scheme = uri.scheme == "https" ? "wss" : "ws"
+        host = uri.host
+        ws_port = uri.port || 8006
+        encoded_ticket = URI.encode_www_form_component(ticket)
+
+        "#{scheme}://#{host}:#{ws_port}/api2/json/nodes/#{node}/#{resource_path}/vncwebsocket" \
+          "?port=#{port}&vncticket=#{encoded_ticket}"
+      end
+
+      # Validates that the resource is in a running state.
+      #
+      # @param resource [Models::Vm, Models::Container] resource to check
+      # @return [void]
+      # @raise [ResourceNotRunningError] if resource is not running
+      def validate_resource_running!(resource)
+        return if resource.status == "running"
+
+        raise ResourceNotRunningError,
+              "Resource #{resource.vmid} is not running (status: #{resource.status})"
+      end
+
+      # Runs a console session end-to-end.
+      #
+      # All API calls (authenticate, termproxy) use the same session-based
+      # REST client to ensure PVEVNC ticket and PVEAuthCookie share the
+      # same identity. Using a token-based connection for termproxy would
+      # generate a ticket bound to the token identity (e.g., "root@pam!pvectl"),
+      # which is rejected by the WebSocket endpoint expecting a session cookie
+      # for "root@pam".
+      #
+      # @param resource [Models::Vm, Models::Container] target resource
+      # @param resource_path [String] API path segment ("qemu/{vmid}" or "lxc/{ctid}")
+      # @param server [String] Proxmox server URL
+      # @param username [String] username for auth
+      # @param password [String] password for auth
+      # @param verify_ssl [Boolean] SSL verification flag
+      # @return [void]
+      def run(resource:, resource_path:, server:, username:, password:, verify_ssl:)
+        validate_resource_running!(resource)
+
+        # All operations use one session-authenticated REST client
+        api_url = "#{server}/api2/json/"
+        session_client = RestClient::Resource.new(api_url, verify_ssl: verify_ssl)
+
+        # 1. Authenticate
+        auth = authenticate_with_client(session_client, username, password)
+
+        # 2. Open termproxy (using session ticket, not API token)
+        termproxy_data = open_termproxy(
+          session_client, auth,
+          node: resource.node, resource_path: resource_path
+        )
+
+        # 3. Build websocket URL
+        url = build_websocket_url(
+          server: server,
+          node: resource.node,
+          resource_path: resource_path,
+          port: termproxy_data[:port],
+          ticket: termproxy_data[:ticket]
+        )
+
+        # 4. Run terminal session
+        session = Pvectl::Console::TerminalSession.new(
+          url: url,
+          cookie: "PVEAuthCookie=#{auth[:ticket]}",
+          user: termproxy_data[:user],
+          ticket: termproxy_data[:ticket],
+          verify_ssl: verify_ssl
+        )
+        session.run
+      end
+
+      private
+
+      # Authenticates using a provided REST client and returns session data.
+      #
+      # @param client [RestClient::Resource] clean REST client
+      # @param username [String] Proxmox username
+      # @param password [String] password
+      # @return [Hash] { ticket:, csrf_token: }
+      # @raise [AuthenticationError] on failure
+      def authenticate_with_client(client, username, password)
+        response = client["access/ticket"].post(username: username, password: password)
+        data = JSON.parse(response.body, symbolize_names: true)[:data]
+
+        {
+          ticket: data[:ticket],
+          csrf_token: data[:CSRFPreventionToken]
+        }
+      rescue StandardError => e
+        raise AuthenticationError, "Authentication failed: #{e.message}"
+      end
+
+      # Opens a termproxy session using session auth credentials.
+      #
+      # @param client [RestClient::Resource] REST client
+      # @param auth [Hash] session auth with :ticket and :csrf_token
+      # @param node [String] Proxmox node name
+      # @param resource_path [String] e.g. "qemu/100" or "lxc/200"
+      # @return [Hash] { port:, ticket:, user: }
+      def open_termproxy(client, auth, node:, resource_path:)
+        endpoint = "nodes/#{node}/#{resource_path}/termproxy"
+        response = client[endpoint].post(
+          {},
+          cookies: { PVEAuthCookie: auth[:ticket] },
+          CSRFPreventionToken: auth[:csrf_token]
+        )
+        data = JSON.parse(response.body, symbolize_names: true)[:data]
+
+        { port: data[:port], ticket: data[:ticket], user: data[:user] }
+      rescue StandardError => e
+        raise AuthenticationError, "Termproxy failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/pvectl/services/container_lifecycle.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Pvectl
+  module Services
+    # Orchestrates container lifecycle operations.
+    #
+    # Handles execution of start/stop/shutdown/restart operations
+    # with sync/async modes, error handling, and result collection.
+    #
+    # @example Basic usage
+    #   service = ContainerLifecycle.new(ct_repo, task_repo)
+    #   results = service.execute(:start, [ct1, ct2])
+    #   results.each { |r| puts "#{r.container.vmid}: #{r.status_text}" }
+    #
+    class ContainerLifecycle
+      SYNC_OPERATIONS = %i[start stop].freeze
+      ASYNC_OPERATIONS = %i[shutdown restart].freeze
+      ALL_OPERATIONS = (SYNC_OPERATIONS + ASYNC_OPERATIONS).freeze
+
+      DEFAULT_TIMEOUT = 60
+
+      # Creates a new ContainerLifecycle service.
+      #
+      # @param container_repository [Repositories::Container] Container repository
+      # @param task_repository [Repositories::Task] Task repository
+      # @param options [Hash] Options (timeout, async, wait, fail_fast)
+      def initialize(container_repository, task_repository, options = {})
+        @container_repository = container_repository
+        @task_repository = task_repository
+        @options = options
+      end
+
+      # Executes a lifecycle operation on a list of containers.
+      #
+      # @param operation [Symbol] Operation to execute
+      # @param containers [Array<Models::Container>] Containers to operate on
+      # @return [Array<Models::ContainerOperationResult>] Results for each container
+      def execute(operation, containers)
+        validate_operation!(operation)
+
+        results = []
+        containers.each do |container|
+          result = execute_single(operation, container)
+          results << result
+
+          break if @options[:fail_fast] && result.failed?
+        end
+        results
+      end
+
+      private
+
+      # Executes operation on a single container.
+      #
+      # @param operation [Symbol] Operation
+      # @param container [Models::Container] Container
+      # @return [Models::ContainerOperationResult] Result
+      def execute_single(operation, container)
+        task_upid = call_api(operation, container)
+
+        if sync_mode?(operation)
+          task = @task_repository.wait(task_upid, timeout: timeout)
+          Models::ContainerOperationResult.new(
+            container: container,
+            operation: operation,
+            task: task,
+            success: task.successful?
+          )
+        else
+          Models::ContainerOperationResult.new(
+            container: container,
+            operation: operation,
+            task_upid: task_upid,
+            success: :pending
+          )
+        end
+      rescue StandardError => e
+        Models::ContainerOperationResult.new(
+          container: container,
+          operation: operation,
+          success: false,
+          error: e.message
+        )
+      end
+
+      # Calls the appropriate API method.
+      #
+      # @param operation [Symbol] Operation
+      # @param container [Models::Container] Container
+      # @return [String] Task UPID
+      def call_api(operation, container)
+        @container_repository.send(operation, container.vmid, container.node)
+      end
+
+      # Determines if operation should run in sync mode.
+      #
+      # @param operation [Symbol] Operation
+      # @return [Boolean] true if sync mode
+      def sync_mode?(operation)
+        return false if @options[:async]
+        return true if @options[:wait]
+
+        SYNC_OPERATIONS.include?(operation)
+      end
+
+      # Returns configured timeout.
+      #
+      # @return [Integer] Timeout in seconds
+      def timeout
+        @options[:timeout] || DEFAULT_TIMEOUT
+      end
+
+      # Validates operation is supported.
+      #
+      # @param operation [Symbol] Operation
+      # @raise [ArgumentError] if operation is not supported
+      def validate_operation!(operation)
+        return if ALL_OPERATIONS.include?(operation)
+
+        raise ArgumentError, "Unknown operation: #{operation}. Valid: #{ALL_OPERATIONS.join(', ')}"
+      end
+    end
+  end
+end