ice-jade 0.1.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 550577afe0478429f7d36a2d3a3fc3c3d332f648bf42ba4047ebc2c8cc067c91
-  data.tar.gz: 0a96c1e1cdeaab1cc213223313545a6353ad4c5301c2b4da6049480d3f75b6e8
+  metadata.gz: 70f058625ea166e107bf454a437142ebb6a4cb0f3c49d88e484fe45be069d271
+  data.tar.gz: 0ea0b70756e261510b7ac062f39f02411dd7a54301b7f3c86339c7f6380f57db
 SHA512:
-  metadata.gz: 542652be59f54b3f09e20d3cffa944a7a0303ec6b181e68ba614c5f3ee81f13310c855b6ac8dd5c75a7befdf963f20d89767841c7a660ca391c6fbc2df8c08a0
-  data.tar.gz: 2995c0ee5c479e026c33d2c9d43192472d890c6b094c3007df4357c568660cc241081c6d4ac612de6837eb8b4bbac71f707d7e12a67e23626d3fabb31824baa6
+  metadata.gz: aed37f531cce690f2ed41b80adcc5e45b8a7cab2dbb5ad1c4c2c111d4e477ae9c8e172a99f02b05a1ca13a4a150169e23c2f00109f49ec0dd640338e232eb6c1
+  data.tar.gz: 72cc6594677d28a1ea49ef7f9fac87dd73ff8af30ce1af9dac8fa3c95740171aab185b3c0b5b1f2f418e87b938dd38900c1b27ceea5adfec022c2ba76a77c874

data/README.md

@@ -1,6 +1,12 @@
 # ice-jade
 
-管理多种 IM 接口的 Ruby SDK gem，仅内部用。外部接口见 ignister。
+ice-jade 是一个基于 Ruby 标准库的轻量级工具集，零外部依赖。最初定位是 IM Webhook SDK，现已扩展为包含多个独立分支的通用 HTTP 工具包：
+
+- **Quantum** — IM Webhook 客户端
+- **Poster** — 通用 HTTP POST 客户端
+- **HttpPoster** — 独立模块级 HTTP POST 工具
+- **Cradle** — HTTP 测试服务器
+- **YAMLServer** — YAML 配置驱动的测试服务器实例
 
 ## 安装
 
@@ -12,9 +18,20 @@ gem 'ice-jade'
 bundle install
 ```
 
-## 快速开始
+或本地安装：
+
+```bash
+gem build ice-jade.gemspec
+gem install ice-jade-*.gem
+```
+
+---
+
+## 分支一：Quantum IM
+
+Quantum 是企业 IM 群机器人的 Webhook 客户端，支持文本、图片、文件、图文消息的发送，以及附件上传。
 
-### Quantum IM
+### 快速开始
 
 ```ruby
 require 'ice_jade'
@@ -37,95 +54,175 @@ client.upload_and_send_image("/path/to/photo.jpg", height: 1080, width: 1920)
 client.upload_and_send_file("/path/to/report.pdf")
 ```
 
-## 当前支持的 IM
+详细文档：`documents/im-quantum-api.md`
 
-| IM 类型 | 命名空间 | 状态 |
-|---------|----------|------|
-| Quantum | `IceJade::Quantum` | 已支持 |
+---
 
-## 架构设计（如何扩展新 IM）
+## 分支二：Poster
 
-每个 IM 独占一个命名空间，内部包含自己的 `Client` 和 `Message`（如果有）。
+`IceJade::Poster::Client` 是通用 HTTP POST 客户端，面向对象设计，支持 JSON / Form / Multipart，内置超时重试和统一 `Response` 包装。
+
+### 快速开始
+
+```ruby
+require 'ice_jade'
+
+poster = IceJade::Poster::Client.new(
+  base_url: 'https://api.example.com',
+  headers:  { 'Authorization' => 'Bearer token' },
+  timeout:  30
+)
 
+# POST JSON
+resp = poster.post_json('/users', { name: 'Alice' })
+puts resp.data if resp.success?
+
+# POST Form
+resp = poster.post_form('/login', { username: 'admin', password: 'secret' })
+
+# POST Multipart（文件上传）
+resp = poster.post_multipart('/upload', { file: '/path/to/image.png' })
+
+# 通用 post（自定义 Content-Type）
+resp = poster.post('/hook', '<xml>...</xml>', content_type: 'application/xml')
 ```
-lib/ice_jade/
-  quantum/
-    client.rb   # Quantum::Client < ClientBase
-    message.rb  # Quantum::Message
-  feishu/       # 未来其他IM
-    client.rb
-  dingtalk/     # 未来其他IM#2
-    client.rb
+
+### 与 Quantum 的关系
+
+| 分支 | 定位 | 典型场景 |
+|------|------|----------|
+| Quantum | IM Webhook 专用 SDK | 向企业 IM 群机器人发消息 |
+| Poster | 通用 HTTP POST 客户端 | 调用任意 REST API、Webhook |
+
+两者共享 `IceJade::Response` 与 `IceJade::Error`，响应处理风格一致。
+
+详细文档：`documents/poster-api.md`
+
+---
+
+## 分支三：HttpPoster（独立模块）
+
+`HttpPoster` 是 `lib/http_poster.rb` 中定义的纯标准库 HTTP POST 工具，零 gem 依赖。它是独立于 ice-jade gem 的扁平化脚本，适合不想引入任何 gem 的场景。
+
+### 快速开始
+
+```ruby
+require_relative 'lib/http_poster'
+
+# POST JSON（模块静态方法）
+res = HttpPoster.post_json(
+  'https://api.example.com/users',
+  { name: 'Alice' },
+  { 'Authorization' => 'Bearer token' },
+  { timeout: 30 }
+)
+puts res  # => Hash（解析后的 JSON）
 ```
 
-### 添加新 IM 的步骤
+### 与 Poster 的对比
+
+| 维度 | HttpPoster | IceJade::Poster::Client |
+|------|------------|-------------------------|
+| 调用方式 | 模块静态方法 | 先 `new` 实例化再调用 |
+| URL 处理 | 只能传完整 URL | 支持 `base_url` + 相对路径 |
+| 参数风格 | 位置参数 `(url,p,h,opts)` | 关键字参数 `(headers:)` |
+| 成功返回 | Hash / String | `IceJade::Response` |
+| 错误处理 | 抛 `TimeoutError` / `HttpError` | 包装为 `Response`（不抛异常） |
+| 所属体系 | 独立脚本（无依赖） | ice-jade gem 分支 |
+| 典型场景 | 快速脚本、教学、零依赖 | 正式项目、与 Quantum 混用 |
+
+详细文档：`documents/http-poster-api.md`
+
+---
+
+## 分支四：Cradle（HTTP 测试服务器）
+
+Cradle 是轻量级 HTTP 测试服务器，基于 Ruby 标准库 `socket` + `thread`，零外部依赖。用于本地测试 Poster、Quantum 或其他 HTTP 客户端。
 
-1. 在 `lib/ice_jade/` 下新建目录，例如 `feishu/`
-2. 实现 `lib/ice_jade/feishu/client.rb`，继承 `IceJade::ClientBase`
-3. 在 `lib/ice_jade.rb` 中 `require_relative 'feishu/client'`
+### 命令行启动
 
-示例模板：
+```bash
+cradle              # 默认监听 0.0.0.0:8765
+cradle -p 3000      # 监听 0.0.0.0:3000
+cradle -h 127.0.0.1 # 仅本地访问
+```
+
+### 代码启动
 
 ```ruby
-# lib/ice_jade/feishu/client.rb
-require 'json'
-require 'net/http'
-
-module IceJade
-  module Feishu
-    class Client < ClientBase
-      def initialize(webhook_url)
-        @webhook_url = webhook_url
-      end
-
-      def send_text(content, **opts)
-        # 飞书特有的 JSON 结构
-        payload = { msg_type: 'text', content: { text: content } }
-        # ...post...
-      end
-
-      def send_image(file_id, **opts)
-        raise NotImplementedError
-      end
-
-      def send_file(file_id, **opts)
-        raise NotImplementedError
-      end
-
-      def send_news(title, url, **opts)
-        raise NotImplementedError
-      end
-    end
-  end
+require 'ice_jade'
+
+server = IceJade::Cradle::Server.new(port: 8765)
+
+# 注册自定义路由
+server.route(:post, '/echo') do |req|
+  [200, { 'Content-Type' => 'application/json' },
+   JSON.generate(method: req.method, body: req.parsed_body)]
 end
+
+server.start
 ```
 
-然后使用：
+详细文档：`documents/cradle-api.md`
 
-```ruby
-client = IceJade::Feishu::Client.new('https://open.feishu.cn/...')
-client.send_text("hello from feishu")
+---
+
+## 分支五：YAMLServer（YAML 配置驱动的测试实例）
+
+YAMLServer 通过载入 YAML 配置文件启动定制化的 HTTP 测试实例，无需写 Ruby 代码注册路由，适合频繁切换测试场景。
+
+### 命令行启动
+
+```bash
+cradle-instance config/cradle/poster_test.yml
 ```
 
-### 统一接口（可选）
+### YAML 配置示例
 
-如果你需要在运行时根据配置切换 IM，可以包装一个简单工厂：
+```yaml
+port: 8765
+host: 127.0.0.1
 
-```ruby
-def build_im_client(config)
-  case config[:type]
-  when 'quantum'  then IceJade::Quantum::Client.new(config[:key])
-  when 'feishu'   then IceJade::Feishu::Client.new(config[:webhook_url])
-  else raise "Unknown IM type: #{config[:type]}"
-  end
-end
+routes:
+  - method: POST
+    path: /echo
+    handler: echo_json
+
+  - method: POST
+    path: /error
+    handler: static
+    status: 500
+    headers:
+      Content-Type: application/json
+    body: '{"error":"Internal Server Error"}'
 ```
 
+内置 handler：`echo_json`、`echo_form`、`echo_upload`、`static`、`delay`。
+
+详细文档：`documents/yaml-server-api.md`
+
+---
+
+## 扩展 Cradle / YAMLServer
+
+Cradle 和 YAMLServer 都可以通过扩展代码添加新功能，变成满足实际需求的 HTTP 服务器：
+
+- **Cradle::Server**：通过 `route(method, path) { |req| ... }` 注册自定义路由
+- **YAMLServer**：通过 `HANDLERS['name'] = lambda { |req, cfg| ... }` 注册自定义处理器
+- **混合模式**：YAML 启动基础路由，Ruby 代码追加动态路由
+
+扩展能力包括：自定义响应格式、路径参数、请求头校验、状态计数器、随机延迟、分页模拟、代理转发等。也可以把扩展封装为独立 gem 复用 Cradle 内核。
+
+详细文档：`documents/cradle-extension.md`
+
+---
+
 ## 文件结构
 
 ```
 lib/
-  ice_jade.rb
+  ice_jade.rb                  # 主入口
+  http_poster.rb               # 独立模块（零依赖）
   ice_jade/
     version.rb
     error.rb
@@ -134,13 +231,94 @@ lib/
     quantum/
       client.rb
       message.rb
+    poster/
+      client.rb
+    cradle/
+      server.rb               # 原生服务器
+      yaml_server.rb          # YAML 配置层
+
+bin/
+  cradle                      # 命令行：启动原生服务器
+  cradle-instance             # 命令行：启动 YAML 实例
+
+config/cradle/
+  poster_test.yml             # Poster 测试专用配置
+
+examples/
+  quantum_usage.rb            # Quantum 用法示例
+  poster_usage.rb             # Poster + YAMLServer 联测
+  comparison_poster.rb        # HttpPoster vs Poster 对比
+  cradle_usage.rb             # Cradle 服务器用法
+
+documents/
+  im-quantum-api.md           # Quantum API 文档
+  poster-api.md               # Poster API 文档
+  http-poster-api.md          # HttpPoster 文档
+  cradle-api.md               # Cradle 文档
+  yaml-server-api.md          # YAMLServer 文档
+  cradle-extension.md         # 扩展指南
+```
+
+---
+
+## 架构设计
+
+### 分支关系
+
+```
+ice-jade/
+├── Quantum        # IM Webhook 客户端
+├── Poster         # 通用 HTTP POST 客户端
+├── HttpPoster     # 独立模块（零 gem 依赖）
+├── Cradle         # HTTP 测试服务器
+└── YAMLServer     # YAML 配置层（基于 Cradle）
+```
+
+### 添加新 IM（Quantum 模式）
+
+每个 IM 独占一个命名空间，内部包含自己的 `Client` 和 `Message`（如果有）。
+
+```
+lib/ice_jade/
+  quantum/
+    client.rb   # Quantum::Client < ClientBase
+    message.rb  # Quantum::Message
+  feishu/       # 未来其他IM
+    client.rb
+  dingtalk/     # 未来其他IM#2
+    client.rb
+```
+
+步骤：
+
+1. 在 `lib/ice_jade/` 下新建目录
+2. 实现 `client.rb`，继承 `IceJade::ClientBase`
+3. 在 `lib/ice_jade.rb` 中 `require_relative`
+
+模板见 `README.md` 原 Quantum 扩展章节。
+
+### 统一接口（可选工厂）
+
+```ruby
+def build_im_client(config)
+  case config[:type]
+  when 'quantum' then IceJade::Quantum::Client.new(config[:key])
+  when 'feishu'  then IceJade::Feishu::Client.new(config[:webhook_url])
+  else raise "Unknown IM type: #{config[:type]}"
+  end
+end
 ```
 
+---
+
 ## 依赖
 
 - Ruby >= 2.5
-- 仅使用标准库
+- 仅使用标准库（`net/http`、`socket`、`json`、`uri`、`yaml` 等）
+
+---
 
 ## 限制
 
-- Quantum: 文件上传 30MB，消息频率 20条/分钟
+- Quantum：文件上传 30MB，消息频率 20条/分钟
+- Cradle：不支持 WebSocket、HTTPS、持久连接

data/bin/cradle

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Cradle —— ice-jade 内置 HTTP 测试服务器
+#
+# 用法:
+#   cradle [选项]
+#
+# 选项:
+#   -p, --port PORT    监听端口 (默认: 8765)
+#   -h, --host HOST    监听地址 (默认: 0.0.0.0)
+#   --help             显示帮助
+#
+# 示例:
+#   cradle              # 默认启动，监听 0.0.0.0:8765
+#   cradle -p 3000      # 监听 0.0.0.0:3000
+#   cradle -h 127.0.0.1 # 仅本地访问
+#
+
+require_relative '../lib/ice_jade/cradle'
+
+port = IceJade::Cradle::Server::DEFAULT_PORT
+host = IceJade::Cradle::Server::DEFAULT_HOST
+
+args = ARGV.dup
+while args.any?
+  arg = args.shift
+  case arg
+  when '-p', '--port'
+    port = (args.shift || port).to_i
+  when '-h', '--host'
+    host = args.shift || host
+  when '--help', '-?'
+    puts DATA.read
+    exit 0
+  end
+end
+
+server = IceJade::Cradle::Server.new(port: port, host: host)
+
+trap('INT')  { server.stop; exit 0 }
+trap('TERM') { server.stop; exit 0 }
+
+server.start
+
+__END__
+Cradle —— ice-jade 内置 HTTP 测试服务器
+
+基于 Ruby 标准库，零外部依赖，用于本地测试 ice-jade 各分支的 HTTP 调用。
+
+用法: cradle [选项]
+
+选项:
+  -p, --port PORT    监听端口 (默认: 8765)
+  -h, --host HOST    监听地址 (默认: 0.0.0.0)
+  --help             显示本帮助
+
+内置路由:
+  GET  /                     欢迎页
+  ALL  /health               健康检查
+  GET  /echo?foo=bar         回显查询参数
+  POST /echo                 回显请求体 (JSON / Form)
+  POST /upload               接收 multipart 文件上传
+  GET  /status/:code         返回指定 HTTP 状态码
+  POST /delay/:seconds       延迟响应
+  GET  /headers              回显请求头
+  POST /form                 接收 form-urlencoded
+
+示例:
+  cradle              # 启动，监听 http://0.0.0.0:8765
+  cradle -p 3000      # 监听 http://0.0.0.0:3000
+  cradle -h 127.0.0.1 # 仅本地访问

data/bin/cradle-instance

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Cradle Instance —— 通过 YAML 配置启动定制 HTTP 测试服务器
+#
+# 用法:
+#   cradle-instance <config.yml> [选项]
+#
+# 选项:
+#   --help             显示帮助
+#
+# 示例:
+#   cradle-instance config/cradle/poster_test.yml
+#   cradle-instance config/cradle/my_api.yml
+
+require_relative '../lib/ice_jade'
+
+config_path = ARGV[0]
+
+if config_path.nil? || config_path == '--help' || config_path == '-h'
+  puts DATA.read
+  exit 0
+end
+
+unless File.exist?(config_path)
+  puts "Error: Config file not found: #{config_path}"
+  puts "Usage: cradle-instance <config.yml>"
+  exit 1
+end
+
+instance = IceJade::Cradle::YAMLServer.new(config_path)
+
+trap('INT')  { instance.stop; exit 0 }
+trap('TERM') { instance.stop; exit 0 }
+
+puts "Cradle Instance started from #{config_path}"
+puts "Listening on http://#{instance.config['host']}:#{instance.config['port']}"
+puts "Press Ctrl+C to stop"
+
+instance.start
+
+__END__
+Cradle Instance —— YAML 配置驱动的 HTTP 测试服务器
+
+基于 ice-jade Cradle 内核，通过 YAML 文件快速定义路由和响应。
+
+用法: cradle-instance <config.yml>
+
+YAML 格式示例:
+  port: 8765
+  host: 127.0.0.1
+  routes:
+    - method: POST
+      path: /echo
+      handler: echo_json
+
+    - method: POST
+      path: /error
+      handler: static
+      status: 500
+      headers:
+        Content-Type: application/json
+      body: '{"error":"Internal Server Error"}'
+
+内置 handler:
+  echo_json   — 回显 JSON 请求体 (method/path/content_type/headers/body)
+  echo_form   — 回显 form-urlencoded 数据
+  echo_upload — 回显 multipart 文件上传
+  static      — 返回 YAML 中指定的 status/headers/body
+  delay       — 延迟 N 秒后响应（delay 字段或 URL 参数 :seconds）
+
+示例:
+  cradle-instance config/cradle/poster_test.yml
+  cradle-instance config/cradle/my_api.yml

data/config/cradle/poster_test.yml

@@ -0,0 +1,41 @@
+# Cradle 实例配置：Poster 测试专用
+#
+# 启动命令:
+#   ruby bin/cradle-instance config/cradle/poster_test.yml
+#
+# 本配置为 IceJade::Poster 测试提供精确匹配的响应格式，
+# 使 examples/poster_usage.rb 和 examples/comparison_poster.rb 能够本地闭环通过。
+
+port: 8765
+host: 127.0.0.1
+
+routes:
+  # POST /echo —— 回显 JSON 请求体
+  - method: POST
+    path: /echo
+    handler: echo_json
+
+  # POST /form —— 回显 form-urlencoded 数据
+  - method: POST
+    path: /form
+    handler: echo_form
+
+  # POST /upload —— 回显 multipart 文件上传
+  - method: POST
+    path: /upload
+    handler: echo_upload
+
+  # POST /error —— 模拟 500 错误
+  - method: POST
+    path: /error
+    handler: static
+    status: 500
+    headers:
+      Content-Type: application/json
+    body: '{"error":"Internal Server Error"}'
+
+  # POST /delay/:seconds —— 延迟响应
+  - method: POST
+    path: /delay/:seconds
+    handler: delay
+    delay: 1