kdeploy 1.2.41 → 1.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9bab827b041d7b33e3486ddcddc0956fa7b00fddbd20275709c8e23f5201f7a
-  data.tar.gz: c7eee9c23f27b9541a4ef09c253ae5bffa9e9ae5715a941eb36f363afb5a6122
+  metadata.gz: bd3c4b1e7ad1dc2062bfa0e732144b64f0c3c81655320dc96defeaed10816392
+  data.tar.gz: 2ac13e3f6b7093042d4a313c139ad997e59e06b1fa2d6dc7372dc33919f3eebc
 SHA512:
-  metadata.gz: 9fb85d1b6243a36259f67a6d9c96e1028190a7d650a5b625d4b31f76f5bd2eb12adcce06e07c7c12177ffaa128fa32a561e8b8092674ca51df2d4c6e6d5d2790
-  data.tar.gz: 6dd1ad95b47ecf2b0d8d09ee3f2994c4caccfb248894f9ca0c374a66fe9121a427726421ad9ceb0ce30512adb34080a7c39bb7c7789022dcff5531ec8131e003
+  metadata.gz: f224afb29cf1d419a80aa7797841b1fd935030841c0f80ad403e25573635e45956b8779c6518f6c37b4150c110c19f200baa1247ea03353e442ba6e0a5061a65
+  data.tar.gz: d6cae91436717b81f3a527707f7bed7e93107d868bf457b3ec9e62d859b42b241103f8600315155fd5e9409a09671319f487f7e0e4ea0f276d9dd8a48cd3ec2a

data/README.md

@@ -207,6 +207,10 @@ kdeploy execute deploy.rb deploy_web
 - `--format FORMAT`: 输出格式（`text`|`json`，默认 `text`）
 - `--retries N`: 网络相关操作重试次数（默认 `0`）
 - `--retry-delay SECONDS`: 每次重试间隔秒数（默认 `1`）
+- `--retry-on-nonzero`: 非零退出码重试开关（默认 `false`）
+- `--timeout SECONDS`: 单 host 执行超时（秒，默认不启用）
+- `--step-timeout SECONDS`: 单 step 执行超时（秒，默认不启用）
+- `--retry-policy JSON`: 重试策略 JSON（覆盖 `.kdeploy.yml`）
 
 **示例:**
 ```bash
@@ -228,6 +232,21 @@ kdeploy execute deploy.rb deploy_web --format json --no-banner
 # 重试网络抖动导致的失败
 kdeploy execute deploy.rb deploy_web --retries 3 --retry-delay 1
 
+# 对非零退出码进行重试
+kdeploy execute deploy.rb deploy_web --retries 2 --retry-on-nonzero
+
+# 设置单 host 超时（秒）
+kdeploy execute deploy.rb deploy_web --timeout 120
+
+# 设置单 step 超时（秒）
+kdeploy execute deploy.rb deploy_web --step-timeout 30
+
+# 使用 CLI 覆盖重试策略（JSON）
+kdeploy execute deploy.rb deploy_web --retry-policy '{"run":{"retries":2,"retry_on_exit_codes":[2]}}'
+
+# 使用文件覆盖重试策略（JSON）
+kdeploy execute deploy.rb deploy_web --retry-policy-file ./retry_policy.example.json
+
 # 组合选项
 kdeploy execute deploy.rb deploy_web --limit web01 --parallel 3 --dry-run
 ```
@@ -501,6 +520,14 @@ sync "./app", "/var/www/app",
 # 排除特定文件（与 ignore 相同，但语义更清晰）
 sync "./config", "/etc/app",
   exclude: ["*.example", "*.bak", ".env.local"]
+
+# 启用快速同步（本地/远端均有 rsync 时优先使用）
+sync "./app", "/var/www/app",
+  fast: true
+
+# 设置同步并行度
+sync "./app", "/var/www/app",
+  parallel: 4
 ```
 
 **参数:**
@@ -509,6 +536,8 @@ sync "./config", "/etc/app",
 - `ignore`: 要忽略的文件/目录模式数组（支持 .gitignore 风格的通配符）
 - `exclude`: 与 `ignore` 相同，用于语义清晰
 - `delete`: 布尔值，是否删除远程目录中不存在于源目录的文件（默认: false）
+- `fast`: 布尔值，启用快速同步路径（优先 rsync，默认: false）
+- `parallel`: 上传并行度（默认: 1）
 
 **忽略模式支持:**
 - `*.log` - 匹配所有 .log 文件
@@ -682,10 +711,24 @@ export KDEPLOY_SSH_TIMEOUT=60
 parallel: 5
 ssh_timeout: 60
 verify_host_key: true
+retries: 2
+retry_delay: 1
+retry_on_nonzero: false
+step_timeout: 30
+sync_fast: false
+sync_parallel: 4
+retry_policy:
+  run:
+    retries: 2
+    retry_on_exit_codes: [2, 255]
+  upload:
+    retries: 0
 ```
 
 配置文件会自动从当前目录向上查找，直到找到 `.kdeploy.yml` 文件。
 
+**重试策略示例文件**: `retry_policy.example.json`
+
 ## 🔧 高级用法
 
 ### 条件执行
@@ -702,6 +745,16 @@ task :deploy do
 end
 ```
 
+### 重试策略示例
+
+你可以通过文件覆盖重试策略：
+
+```bash
+kdeploy execute deploy.rb deploy_web --retry-policy-file ./retry_policy.example.json
+```
+
+示例文件见：`retry_policy.example.json` / `retry_policy.example.yml`
+
 ### 循环主机
 
 ```ruby
@@ -1141,4 +1194,3 @@ end
 ---
 
 **为 DevOps 社区用 ❤️ 制作**
-

data/README_EN.md

@@ -206,6 +206,11 @@ kdeploy execute deploy.rb deploy_web
 - `--format FORMAT`: Output format (`text`|`json`, default `text`)
 - `--retries N`: Retry count for network operations (default `0`)
 - `--retry-delay SECONDS`: Delay between retries in seconds (default `1`)
+- `--retry-on-nonzero`: Retry commands on nonzero exit status (default `false`)
+- `--timeout SECONDS`: Per-host execution timeout in seconds (default: none)
+- `--step-timeout SECONDS`: Per-step execution timeout in seconds (default: none)
+- `--retry-policy JSON`: Retry policy JSON (overrides `.kdeploy.yml`)
+- `--retry-policy-file PATH`: Retry policy JSON file (overrides `.kdeploy.yml`)
 
 **Examples:**
 ```bash
@@ -227,6 +232,21 @@ kdeploy execute deploy.rb deploy_web --format json --no-banner
 # Retry transient network failures
 kdeploy execute deploy.rb deploy_web --retries 3 --retry-delay 1
 
+# Retry on nonzero exit status
+kdeploy execute deploy.rb deploy_web --retries 2 --retry-on-nonzero
+
+# Set per-host timeout (seconds)
+kdeploy execute deploy.rb deploy_web --timeout 120
+
+# Set per-step timeout (seconds)
+kdeploy execute deploy.rb deploy_web --step-timeout 30
+
+# Override retry policy via CLI JSON
+kdeploy execute deploy.rb deploy_web --retry-policy '{"run":{"retries":2,"retry_on_exit_codes":[2]}}'
+
+# Override retry policy via file
+kdeploy execute deploy.rb deploy_web --retry-policy-file ./retry_policy.example.json
+
 # Combine options
 kdeploy execute deploy.rb deploy_web --limit web01 --parallel 3 --dry-run
 ```
@@ -480,6 +500,45 @@ upload_template "./config/nginx.conf.erb", "/etc/nginx/nginx.conf",
 - `destination`: Remote file path
 - `variables`: Hash of variables for template rendering
 
+#### `sync` - Directory Sync
+
+Recursively sync a local directory to a remote server with filtering options.
+
+```ruby
+# Basic sync
+sync "./app", "/var/www/app"
+
+# Ignore specific files/dirs
+sync "./app", "/var/www/app",
+  ignore: [".git", "*.log", "node_modules", "*.tmp"]
+
+# Delete remote files not present locally
+sync "./app", "/var/www/app",
+  ignore: [".git", "*.log"],
+  delete: true
+
+# Exclude files (alias of ignore)
+sync "./config", "/etc/app",
+  exclude: ["*.example", "*.bak", ".env.local"]
+
+# Fast sync (prefer rsync when available)
+sync "./app", "/var/www/app",
+  fast: true
+
+# Parallel sync uploads
+sync "./app", "/var/www/app",
+  parallel: 4
+```
+
+**Parameters:**
+- `source`: Local source directory path
+- `destination`: Remote destination directory path
+- `ignore`: Patterns to ignore (gitignore-style)
+- `exclude`: Same as `ignore` for clarity
+- `delete`: Delete remote files not present locally (default: false)
+- `fast`: Enable fast sync path (prefer rsync when available, default: false)
+- `parallel`: Upload concurrency for sync (default: 1)
+
 ### Chef-Style Resource DSL
 
 Kdeploy provides a declarative resource DSL similar to Chef, which can replace or mix with low-level primitives (`run`, `upload`, `upload_template`).
@@ -639,7 +698,21 @@ For project-specific configuration, create a `.kdeploy.yml`:
 parallel: 5
 ssh_timeout: 60
 verify_host_key: true
-```
+retries: 2
+retry_delay: 1
+retry_on_nonzero: false
+step_timeout: 30
+sync_fast: false
+sync_parallel: 4
+retry_policy:
+  run:
+    retries: 2
+    retry_on_exit_codes: [2, 255]
+  upload:
+    retries: 0
+```
+
+**Retry policy example file**: `retry_policy.example.json`
 
 ## 🔧 Advanced Usage
 
@@ -657,6 +730,16 @@ task :deploy do
 end
 ```
 
+### Retry Policy Example
+
+You can override retry policy via file:
+
+```bash
+kdeploy execute deploy.rb deploy_web --retry-policy-file ./retry_policy.example.json
+```
+
+Example files: `retry_policy.example.json` / `retry_policy.example.yml`
+
 ### Looping Over Hosts
 
 ```ruby
@@ -1123,7 +1206,8 @@ end
 task :deploy_app, roles: :web do
   sync "./app", "/var/www/app",
     ignore: [".git", "*.log", "node_modules", ".env.local", "*.tmp"],
-    delete: true
+    delete: true,
+    fast: true # prefer rsync when available
   sync "./config", "/etc/app", exclude: ["*.example", "*.bak"]
   service "app", action: :restart
 end

data/lib/kdeploy/{cli.rb → cli/cli.rb}

@@ -2,6 +2,7 @@
 
 require 'thor'
 require 'json'
+require 'yaml'
 require 'pastel'
 require 'tty-table'
 require 'tty-box'
@@ -51,6 +52,11 @@ module Kdeploy
     method_option :format, type: :string, default: 'text', desc: 'Output format (text|json)'
     method_option :retries, type: :numeric, desc: 'Retry count for network operations (default: 0)'
     method_option :retry_delay, type: :numeric, desc: 'Retry delay seconds (default: 1)'
+    method_option :retry_on_nonzero, type: :boolean, desc: 'Retry commands on nonzero exit status (default: false)'
+    method_option :timeout, type: :numeric, desc: 'Per-host execution timeout seconds (default: none)'
+    method_option :step_timeout, type: :numeric, desc: 'Per-step execution timeout seconds (default: none)'
+    method_option :retry_policy, type: :string, desc: 'Retry policy JSON to override config file'
+    method_option :retry_policy_file, type: :string, desc: 'Retry policy JSON file to override config file'
     def execute(task_file, task_name = nil)
       load_config_file
       show_banner_once
@@ -75,7 +81,7 @@ module Kdeploy
 
     def load_task_file(file)
       validate_task_file(file)
-      # 用 instance_eval 并传递顶层 binding，兼容 heredoc
+      # Use module_eval with top-level binding to keep heredoc compatible
       self.class.module_eval(File.read(file), file)
     rescue StandardError => e
       raise FileNotFoundError, file if e.message.include?('not found')
@@ -267,6 +273,11 @@ module Kdeploy
       debug_mode = options[:debug] || false
       retries = options[:retries].nil? ? Configuration.default_retries : options[:retries]
       retry_delay = options[:retry_delay].nil? ? Configuration.default_retry_delay : options[:retry_delay]
+      retry_on_nonzero =
+        options[:retry_on_nonzero].nil? ? Configuration.default_retry_on_nonzero : options[:retry_on_nonzero]
+      host_timeout = options[:timeout].nil? ? Configuration.default_host_timeout : options[:timeout]
+      step_timeout = options[:step_timeout].nil? ? Configuration.default_step_timeout : options[:step_timeout]
+      retry_policy = resolve_retry_policy
       base_dir = @task_file_dir
       runner = Runner.new(
         hosts, self.class.kdeploy_tasks,
@@ -275,7 +286,11 @@ module Kdeploy
         debug: debug_mode,
         base_dir: base_dir,
         retries: retries,
-        retry_delay: retry_delay
+        retry_delay: retry_delay,
+        retry_on_nonzero: retry_on_nonzero,
+        host_timeout: host_timeout,
+        step_timeout: step_timeout,
+        retry_policy: retry_policy
       )
       results = runner.run(task)
       if options[:format] == 'json'
@@ -363,13 +378,13 @@ module Kdeploy
         duration: step[:duration]
       }
 
-      out[:result] = step[:result] if step[:type] == :sync
-
-      if options[:debug] && step[:type] == :run && step[:output].is_a?(Hash)
+      if step[:output].is_a?(Hash)
         out[:stdout] = step[:output][:stdout]
         out[:stderr] = step[:output][:stderr]
+        out[:exit_status] = step[:output][:exit_status]
       end
 
+      out[:result] = step[:result] if step[:type] == :sync
       out
     end
 
@@ -388,7 +403,9 @@ module Kdeploy
           destination: cmd[:destination],
           ignore: cmd[:ignore] || [],
           exclude: cmd[:exclude] || [],
-          delete: cmd[:delete] || false
+          delete: cmd[:delete] || false,
+          fast: cmd[:fast],
+          parallel: cmd[:parallel]
         }
       else
         { type: cmd[:type].to_s }
@@ -400,11 +417,61 @@ module Kdeploy
 
       if result[:output].is_a?(Array)
         result[:output].map do |o|
-          o[:output][:stderr] if o[:output].is_a?(Hash)
+          next unless o.is_a?(Hash)
+
+          err = o[:output]
+          next unless err.is_a?(Hash)
+
+          pieces = []
+          pieces << "command=#{err[:command]}" if err[:command]
+          pieces << "exit_status=#{err[:exit_status]}" if err[:exit_status]
+          pieces << "stderr=#{err[:stderr]}" if err[:stderr]
+          pieces.join(' ')
         end.compact.join("\n")
       else
         result[:output].to_s
       end
     end
+
+    def parse_retry_policy(raw)
+      policy = JSON.parse(raw)
+      raise ArgumentError, 'retry_policy must be a JSON object' unless policy.is_a?(Hash)
+
+      policy
+    rescue JSON::ParserError => e
+      raise ArgumentError, "retry_policy JSON parse error: #{e.message}"
+    end
+
+    def resolve_retry_policy
+      if options[:retry_policy_file]
+        path = options[:retry_policy_file]
+        unless File.exist?(path)
+          raise ArgumentError,
+                "retry_policy file not found: #{path} (examples: retry_policy.example.json / retry_policy.example.yml)"
+        end
+
+        return parse_retry_policy_file(path)
+      end
+      return parse_retry_policy(options[:retry_policy]) if options[:retry_policy]
+
+      Configuration.default_retry_policy
+    end
+
+    def parse_retry_policy_file(path)
+      ext = File.extname(path).downcase
+      raw = File.read(path)
+      policy =
+        case ext
+        when '.yml', '.yaml'
+          YAML.safe_load(raw) || {}
+        else
+          JSON.parse(raw)
+        end
+      raise ArgumentError, 'retry_policy must be a JSON/YAML object' unless policy.is_a?(Hash)
+
+      policy
+    rescue JSON::ParserError, Psych::SyntaxError => e
+      raise ArgumentError, "retry_policy parse error: #{e.message}"
+    end
   end
 end

data/lib/kdeploy/{help_formatter.rb → cli/help_formatter.rb}

@@ -34,6 +34,11 @@ module Kdeploy
         #{@pastel.dim('    --format FORMAT')}            Output format (text|json)
         #{@pastel.dim('    --retries N')}                Retry count for network operations (default: 0; overridden by .kdeploy.yml)
         #{@pastel.dim('    --retry-delay SECONDS')}      Retry delay seconds (default: 1; overridden by .kdeploy.yml)
+        #{@pastel.dim('    --retry-on-nonzero')}         Retry commands on nonzero exit status (default: false; overridden by .kdeploy.yml)
+        #{@pastel.dim('    --timeout SECONDS')}          Per-host execution timeout seconds (default: none; overridden by .kdeploy.yml)
+        #{@pastel.dim('    --step-timeout SECONDS')}     Per-step execution timeout seconds (default: none; overridden by .kdeploy.yml)
+        #{@pastel.dim('    --retry-policy JSON')}        Retry policy JSON (overrides .kdeploy.yml)
+        #{@pastel.dim('    --retry-policy-file PATH')}   Retry policy JSON file (overrides .kdeploy.yml)
 
         #{@pastel.bright_yellow('🆕')} #{@pastel.bright_white('init [DIR]')}                  Initialize new deployment project
         #{@pastel.bright_yellow('ℹ️')} #{@pastel.bright_white('version')}                    Show version information

data/lib/kdeploy/{configuration.rb → config/configuration.rb}

@@ -10,6 +10,12 @@ module Kdeploy
     DEFAULT_VERIFY_HOST_KEY = :never
     DEFAULT_RETRIES = 0
     DEFAULT_RETRY_DELAY = 1
+    DEFAULT_HOST_TIMEOUT = nil
+    DEFAULT_RETRY_ON_NONZERO = false
+    DEFAULT_SYNC_FAST = false
+    DEFAULT_STEP_TIMEOUT = nil
+    DEFAULT_RETRY_POLICY = nil
+    DEFAULT_SYNC_PARALLEL = 1
     CONFIG_FILE_NAME = '.kdeploy.yml'
 
     class << self
@@ -17,7 +23,13 @@ module Kdeploy
                     :default_ssh_timeout,
                     :default_verify_host_key,
                     :default_retries,
-                    :default_retry_delay
+                    :default_retry_delay,
+                    :default_host_timeout,
+                    :default_retry_on_nonzero,
+                    :default_sync_fast,
+                    :default_step_timeout,
+                    :default_retry_policy,
+                    :default_sync_parallel
 
       def reset
         @default_parallel = DEFAULT_PARALLEL
@@ -25,6 +37,12 @@ module Kdeploy
         @default_verify_host_key = DEFAULT_VERIFY_HOST_KEY
         @default_retries = DEFAULT_RETRIES
         @default_retry_delay = DEFAULT_RETRY_DELAY
+        @default_host_timeout = DEFAULT_HOST_TIMEOUT
+        @default_retry_on_nonzero = DEFAULT_RETRY_ON_NONZERO
+        @default_sync_fast = DEFAULT_SYNC_FAST
+        @default_step_timeout = DEFAULT_STEP_TIMEOUT
+        @default_retry_policy = DEFAULT_RETRY_POLICY
+        @default_sync_parallel = DEFAULT_SYNC_PARALLEL
       end
 
       def load_from_file(config_path = nil)
@@ -64,6 +82,12 @@ module Kdeploy
         @default_verify_host_key = parse_verify_host_key(config['verify_host_key']) if config.key?('verify_host_key')
         @default_retries = config['retries'] if config.key?('retries')
         @default_retry_delay = config['retry_delay'] if config.key?('retry_delay')
+        @default_host_timeout = config['host_timeout'] if config.key?('host_timeout')
+        @default_retry_on_nonzero = config['retry_on_nonzero'] if config.key?('retry_on_nonzero')
+        @default_sync_fast = config['sync_fast'] if config.key?('sync_fast')
+        @default_step_timeout = config['step_timeout'] if config.key?('step_timeout')
+        @default_retry_policy = config['retry_policy'] if config.key?('retry_policy')
+        @default_sync_parallel = config['sync_parallel'] if config.key?('sync_parallel')
       end
 
       def parse_verify_host_key(value)

data/lib/kdeploy/{dsl.rb → dsl/dsl.rb}

@@ -161,7 +161,7 @@ module Kdeploy
       }
     end
 
-    def sync(source, destination, ignore: [], delete: false, exclude: [])
+    def sync(source, destination, ignore: [], delete: false, exclude: [], fast: nil, parallel: nil)
       @kdeploy_commands ||= []
       @kdeploy_commands << {
         type: :sync,
@@ -169,7 +169,9 @@ module Kdeploy
         destination: destination,
         ignore: Array(ignore),
         exclude: Array(exclude),
-        delete: delete
+        delete: delete,
+        fast: fast,
+        parallel: parallel
       }
     end
 
@@ -177,14 +179,14 @@ module Kdeploy
     # Chef-style resource DSL (compiles to run/upload/upload_template)
     # -------------------------------------------------------------------------
 
-    # 安装系统包。默认 apt 平台；支持 platform: :yum。
+    # Install a system package. Defaults to apt; supports platform: :yum.
     def package(name, version: nil, platform: :apt)
       @kdeploy_commands ||= []
       cmd = build_package_command(name, version, platform)
       @kdeploy_commands << { type: :run, command: cmd, sudo: true }
     end
 
-    # 管理系统服务（systemd）。action 支持 :start, :stop, :restart, :reload, :enable, :disable。
+    # Manage a systemd service. action supports :start, :stop, :restart, :reload, :enable, :disable.
     def service(name, action: :start)
       @kdeploy_commands ||= []
       actions = Array(action)
@@ -194,7 +196,7 @@ module Kdeploy
       end
     end
 
-    # 部署 ERB 模板到远程路径。支持 block 或关键字参数。
+    # Deploy an ERB template to a remote path. Supports block and keyword args.
     def template(destination, source: nil, variables: nil, &block)
       @kdeploy_commands ||= []
       if block
@@ -211,13 +213,13 @@ module Kdeploy
       upload_template(src, destination, vars)
     end
 
-    # 上传本地文件到远程路径。
+    # Upload a local file to a remote path.
     def file(destination, source:)
       @kdeploy_commands ||= []
       upload(source, destination)
     end
 
-    # 确保远程目录存在。支持 mode 参数。
+    # Ensure a remote directory exists. Supports mode option.
     def directory(path, mode: nil)
       @kdeploy_commands ||= []
       cmd = "mkdir -p #{Shellwords.escape(path.to_s)}"

data/lib/kdeploy/{initializer.rb → dsl/initializer.rb}

@@ -96,11 +96,11 @@ module Kdeploy
     end
 
     def create_config_files
-      # 创建配置目录
+      # Create config directory
       config_dir = File.join(@target_dir, 'config')
       FileUtils.mkdir_p(config_dir)
 
-      # 创建 Nginx ERB 模板
+      # Create Nginx ERB template
       File.write(File.join(config_dir, 'nginx.conf.erb'), <<~CONF)
         user nginx;
         worker_processes <%= worker_processes %>;
@@ -152,7 +152,7 @@ module Kdeploy
         }
       CONF
 
-      # 创建静态配置文件示例
+      # Create static config file example
       File.write(File.join(config_dir, 'app.conf'), <<~CONF)
         location /api {
             proxy_pass http://localhost:3000;

data/lib/kdeploy/errors.rb

@@ -52,6 +52,13 @@ module Kdeploy
     attr_reader :original_error
   end
 
+  # Raised when a step exceeds configured timeout
+  class StepTimeoutError < Error
+    def initialize(message)
+      super("Step timeout: #{message}")
+    end
+  end
+
   # Raised when configuration is invalid
   class ConfigurationError < Error
     def initialize(message)