feat: async execution with 202 response and executions query API

- Rule files can opt into async: true to return HTTP 202 immediately
  and run matched actions in a background goroutine
- Global backpressure via server.max_async_tasks (default 32); excess
  requests are rejected synchronously with 429
- Execution policies (block/cooldown) are still enforced at accept
  time; the running mark is released when the background task ends
- New internal/execstore ring buffer keeps the last 100 async records,
  queryable via GET /api/executions?limit=N
- Graceful shutdown waits up to 30s for in-flight async tasks before
  closing rule loggers; shutdown order adjusted accordingly
- Docs updated: configuration/usage/README in both languages,
  example.yaml gains an async comment

Author: bluvenr

README.md

@@ -86,6 +86,7 @@ $ curl -X POST http://localhost:9000/webhook/github-auto-deploy \
 - **Flexible Auth** — Token (Header/Query) + HMAC Signature (GitHub/GitLab) + IP whitelist with AND relationship
 - **Multi-Condition Filters** — Match against Header / Query / Body with operators: `eq` `ne` `contains` `regex`
 - **Execution Policies** — Three modes: `block` (prevent concurrency), `always` (always execute), `cooldown` (rate limiting)
+- **Async Execution** — Per-file `async: true` returns HTTP 202 instantly and runs actions in the background, queryable via `/api/executions`
 - **Policy Inheritance** — File-level → Rule-level override
 - **File-Level Filters** — Global constraints applied to all rules, AND with rule-level filters
 - **Parameter Passing** — Template variables (`{{.body.ref}}`) and `pass_args` to inject request data into commands

README_zh.md

@@ -86,6 +86,7 @@ $ curl -X POST http://localhost:9000/webhook/github-auto-deploy \
 - **灵活验证** — Token（Header/Query）+ HMAC 签名（GitHub/GitLab）+ IP 白名单，AND 组合
 - **多条件过滤** — 支持 Header / Query / Body 匹配，操作符：`eq` `ne` `contains` `regex`
 - **执行策略** — 三种模式：`block`（防并发）、`always`（始终执行）、`cooldown`（冷却限频）
+- **异步执行** — 文件级 `async: true` 立即返回 HTTP 202，后台执行 actions，可通过 `/api/executions` 查询执行记录
 - **策略继承** — 文件级 → 规则级逐层覆盖
 - **文件级过滤** — 全局约束应用于所有规则，与规则级 filters 为 AND 组合
 - **参数传递** — 模板变量（`{{.body.ref}}`）、`pass_args` 和环境变量注入（`env_from`）将请求数据传入命令/脚本

cmd/hookrun/main.go

@@ -125,7 +125,7 @@ func runServer() error {
 	}
 
 	// Init engine
-	eng := engine.New(configMgr.Rules(), log, cfg.Log.Mode, cfg.Log.RetentionDays, cfg.Log.MaxSizeMB)
+	eng := engine.New(configMgr.Rules(), log, cfg.Log.Mode, cfg.Log.RetentionDays, cfg.Log.MaxSizeMB, cfg.Server.MaxAsyncTaskLimit())
 
 	// Init relay registry (if enabled)
 	if cfg.Server.IsRelayRegistryEnabled() {

docs/configuration.md

@@ -17,6 +17,7 @@ HookRun uses two levels of YAML configuration:
 | `server.route` | string | `/webhook` | Base webhook endpoint path |
 | `server.allow_all` | bool | `false` | Allow base route (`/webhook`) to iterate all config files |
 | `server.max_body_size_mb` | int | `10` | Max request body size in MB. `0` = unlimited |
+| `server.max_async_tasks` | int | `32` | Max concurrent background async tasks. Excess requests get HTTP 429 |
 | `server.relay_registry_token` | string | `""` | Relay registry API auth token. Non-empty enables registry |
 | `server.max_relay_ttl` | int | `0` (unlimited) | Max TTL cap for registered targets (seconds) |
 | `server.max_registry_entries` | int | `100` | Max number of registered targets |
@@ -169,6 +170,7 @@ Each YAML file in `config_dir` defines a rule set. The **filename** (without `.y
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `name` | string | Yes | Rule set name, used in logs and responses |
+| `async` | bool | No | `true` = return HTTP 202 immediately and run actions in background (default `false`) |
 | `auth` | object | No | Authentication settings (AND relationship) |
 | `execution` | object | No | File-level execution policy |
 | `filters` | array | No | File-level global filters (AND with rule-level) |
@@ -283,6 +285,30 @@ Priority: **Rule-level > File-level > Default (block)**
 
 ---
 
+### 2.2.5 `async` — Asynchronous Execution
+
+When `async: true`, a matched request is accepted immediately with HTTP 202 while the actions run in the background:
+
+```yaml
+name: "deploy"
+async: true                     # return 202, execute in background
+execution:
+  policy: "block"
+rules:
+  - name: "deploy-main"
+    actions:
+      - type: "command"
+        cmd: "deploy.sh"
+```
+
+Behavior details:
+
+- The 202 response carries a `request_id` used to correlate logs and execution records
+- Execution policies (`block` / `cooldown`) are still enforced — policy rejections (409/429) are returned synchronously
+- Backpressure: when the number of running background tasks reaches `server.max_async_tasks`, new requests are rejected with 429
+- Recent async executions are queryable via `GET /api/executions` (see Usage docs)
+- On shutdown, in-flight async tasks get a 30-second grace period before forced exit
+
 ### 2.3 `filters` — File-Level Filters
 
 File-level filters act as **global constraints** applied to ALL rules in the config. They use **AND** logic with rule-level filters: both must match for a rule to execute.

docs/configuration_zh.md

@@ -17,6 +17,7 @@ HookRun 使用两级 YAML 配置：
 | `server.route` | string | `/webhook` | Webhook 基础路由路径 |
 | `server.allow_all` | bool | `false` | 是否允许基础路由 `/webhook` 遍历所有配置文件 |
 | `server.max_body_size_mb` | int | `10` | 请求体大小上限 MB。`0` = 不限制 |
+| `server.max_async_tasks` | int | `32` | 后台异步任务最大并发数，超出时新请求返回 HTTP 429 |
 | `server.relay_registry_token` | string | `""` | 注册池 API 鉴权 token。非空时启用注册池 |
 | `server.max_relay_ttl` | int | `0`（不限） | 注册目标的最大 TTL 上限（秒） |
 | `server.max_registry_entries` | int | `100` | 注册池最大容量 |
@@ -169,6 +170,7 @@ log:
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `name` | string | 是 | 规则集名称，用于日志和响应 |
+| `async` | bool | 否 | `true` = 立即返回 HTTP 202，后台执行 actions（默认 `false`） |
 | `auth` | object | 否 | 认证设置（AND 关系） |
 | `execution` | object | 否 | 文件级执行策略 |
 | `filters` | array | 否 | 文件级全局过滤条件（与规则级 AND 组合） |
@@ -283,6 +285,30 @@ rules:
 
 ---
 
+### 2.2.5 `async` — 异步执行
+
+配置 `async: true` 后，匹配成功的请求立即返回 HTTP 202，actions 在后台执行：
+
+```yaml
+name: "deploy"
+async: true                     # 返回 202，后台执行
+execution:
+  policy: "block"
+rules:
+  - name: "deploy-main"
+    actions:
+      - type: "command"
+        cmd: "deploy.sh"
+```
+
+行为说明：
+
+- 202 响应携带 `request_id`，用于关联日志与执行记录
+- 执行策略（`block` / `cooldown`）依然生效 — 策略拒绝（409/429）同步返回
+- 背压保护：后台运行任务数达到 `server.max_async_tasks` 时，新请求返回 429
+- 最近的异步执行记录可通过 `GET /api/executions` 查询（见使用文档）
+- 关闭时在途异步任务有 30 秒宽限期，超时后强制退出
+
 ### 2.3 `filters` — 文件级过滤条件
 
 文件级 filters 作为**全局约束**，应用于该文件下的所有规则。与规则级 filters 为 **AND** 关系：两者必须同时匹配才能执行规则。

docs/usage.md

@@ -303,6 +303,37 @@ When relay is configured, an additional `relay` field is included:
 {"status": "ok", "uptime": "2h30m15s", "rules": 3, "version": "x.y.z", "relay": {"role": "upstream+downstream", "upstream_targets": 3, "downstream_connected": true}}
 ```
 
+### Async Execution Records
+
+```
+GET /api/executions?limit=20
+```
+
+Lists recent asynchronous executions (newest first), kept in memory (last 100). No authentication, consistent with `/health`. `limit` defaults to 20 and is capped at 100.
+
+```bash
+curl http://localhost:9000/api/executions?limit=5
+```
+
+```json
+{
+  "executions": [
+    {
+      "request_id": "1720000000000-a1b2c3d4",
+      "config": "deploy",
+      "rule": "deploy-main",
+      "status": "succeeded",
+      "started_at": "2026-08-05T10:00:00Z",
+      "finished_at": "2026-08-05T10:00:12Z",
+      "duration": "12.05s",
+      "exit_code": 0
+    }
+  ]
+}
+```
+
+`status` is one of `running`, `succeeded`, or `failed`. Failed records carry `exit_code` (`-1` when not applicable) and an `error` message.
+
 ### Relay API
 
 #### `GET /api/relay/status` — Comprehensive Relay Status (always available, no auth)
@@ -432,6 +463,22 @@ When `policy: "cooldown"` and the cooldown window is active:
 }
 ```
 
+### Accepted Asynchronously (202)
+
+When the matched config has `async: true`, the request is accepted immediately and actions run in the background:
+
+```json
+{
+  "code": 202,
+  "message": "Accepted, executing asynchronously",
+  "config": "deploy",
+  "rule": "deploy-main",
+  "request_id": "1720000000000-a1b2c3d4"
+}
+```
+
+Use `request_id` to correlate log entries and execution records.
+
 ### Base Route Disabled (400)
 
 When `allow_all: false` and a request is sent to `/webhook`:

docs/usage_zh.md

@@ -303,6 +303,37 @@ GET /health
 {"status": "ok", "uptime": "2h30m15s", "rules": 3, "version": "x.y.z", "relay": {"role": "upstream+downstream", "upstream_targets": 3, "downstream_connected": true}}
 ```
 
+### 异步执行记录
+
+```
+GET /api/executions?limit=20
+```
+
+列出最近的异步执行记录（最新在前），保存在内存中（最近 100 条）。无需认证，与 `/health` 一致。`limit` 默认 20，上限 100。
+
+```bash
+curl http://localhost:9000/api/executions?limit=5
+```
+
+```json
+{
+  "executions": [
+    {
+      "request_id": "1720000000000-a1b2c3d4",
+      "config": "deploy",
+      "rule": "deploy-main",
+      "status": "succeeded",
+      "started_at": "2026-08-05T10:00:00Z",
+      "finished_at": "2026-08-05T10:00:12Z",
+      "duration": "12.05s",
+      "exit_code": 0
+    }
+  ]
+}
+```
+
+`status` 取值为 `running`、`succeeded` 或 `failed`。失败记录携带 `exit_code`（无退出码时为 `-1`）和 `error` 信息。
+
 ### Relay API
 
 #### `GET /api/relay/status` — 综合 Relay 状态（始终可用，无需认证）
@@ -432,6 +463,22 @@ curl -H "Authorization: Bearer your-registry-secret" \
 }
 ```
 
+### 异步接受（202）
+
+当匹配的配置文件设置了 `async: true` 时，请求立即被接受，actions 在后台执行：
+
+```json
+{
+  "code": 202,
+  "message": "Accepted, executing asynchronously",
+  "config": "deploy",
+  "rule": "deploy-main",
+  "request_id": "1720000000000-a1b2c3d4"
+}
+```
+
+使用 `request_id` 关联日志条目和执行记录。
+
 ### 基础路由已禁用（400）
 
 当 `allow_all: false` 时请求 `/webhook`：

hooks/example.yaml

@@ -20,6 +20,10 @@ execution:
   policy: "block"                # "block" | "always" | "cooldown"
   # cooldown_seconds: 300        # only for "cooldown" policy
 
+# Async execution (optional): return HTTP 202 immediately and run actions
+# in the background. Results are logged and queryable via GET /api/executions.
+# async: true
+
 # Rule-level independent log file (dual-write: global + this file)
 # log:
 #   path: "./logs/github-auto-deploy.log"

internal/config/loader.go

@@ -87,8 +87,8 @@ func (m *Manager) ValidateAll() []error {
 	}
 
 	// Check for duplicate config names and routing file names
-	seenNames := make(map[string]string)  // config name -> source file
-	seenFiles := make(map[string]string)  // file name (routing key) -> source file
+	seenNames := make(map[string]string) // config name -> source file
+	seenFiles := make(map[string]string) // file name (routing key) -> source file
 	for _, r := range m.rules {
 		if prev, dup := seenNames[r.Name]; dup {
 			errs = append(errs, fmt.Errorf("duplicate config name '%s' in '%s' and '%s'", r.Name, prev, r.FilePath))

internal/config/types.go

@@ -20,6 +20,7 @@ type ServerConfig struct {
 	Route              string `yaml:"route"`
 	AllowAll           *bool  `yaml:"allow_all,omitempty"`            // allow /webhook to iterate all configs (default: false)
 	MaxBodySizeMB      *int   `yaml:"max_body_size_mb,omitempty"`     // max request body in MB, 0 = unlimited (default: 10)
+	MaxAsyncTasks      *int   `yaml:"max_async_tasks,omitempty"`      // max concurrent background async tasks (default: 32)
 	RelayRegistryToken string `yaml:"relay_registry_token,omitempty"` // registry API auth token (empty = registry disabled)
 	MaxRelayTTL        int    `yaml:"max_relay_ttl,omitempty"`        // max TTL cap in seconds, 0 = unlimited
 	MaxRegistryEntries int    `yaml:"max_registry_entries,omitempty"` // registry pool capacity (default: 100)
@@ -41,6 +42,7 @@ type RuleLogConfig struct {
 // RuleConfig represents a single hooks/*.yaml file structure.
 type RuleConfig struct {
 	Name        string             `yaml:"name"`
+	Async       bool               `yaml:"async,omitempty"` // true = return 202 and execute actions in background
 	Auth        *AuthConfig        `yaml:"auth,omitempty"`
 	Execution   *ExecutionConfig   `yaml:"execution,omitempty"`
 	Filters     []Filter           `yaml:"filters,omitempty"`     // file-level global filters (AND with rule-level)
@@ -206,6 +208,9 @@ func (g *GlobalConfig) Validate() error {
 	if *g.Server.MaxBodySizeMB < 0 {
 		return fmt.Errorf("server.max_body_size_mb must be >= 0, got %d", *g.Server.MaxBodySizeMB)
 	}
+	if g.Server.MaxAsyncTasks != nil && *g.Server.MaxAsyncTasks < 0 {
+		return fmt.Errorf("server.max_async_tasks must be >= 0, got %d", *g.Server.MaxAsyncTasks)
+	}
 	if g.Server.MaxRegistryEntries < 0 {
 		return fmt.Errorf("server.max_registry_entries must be >= 0, got %d", g.Server.MaxRegistryEntries)
 	}
@@ -248,6 +253,15 @@ func (s *ServerConfig) IsAllowAll() bool {
 	return *s.AllowAll
 }
 
+// MaxAsyncTaskLimit returns the effective max concurrent async task count
+// (nil or non-positive values fall back to the default of 32).
+func (s *ServerConfig) MaxAsyncTaskLimit() int {
+	if s.MaxAsyncTasks == nil || *s.MaxAsyncTasks <= 0 {
+		return 32
+	}
+	return *s.MaxAsyncTasks
+}
+
 // IsRelayRegistryEnabled returns true when the relay registry is activated.
 func (s *ServerConfig) IsRelayRegistryEnabled() bool {
 	return s.RelayRegistryToken != ""