Compare commits

..
4 Commits
Author SHA1 Message Date
vex1023 3dd1eacfde pcurl regression suite (35 cases) + 3 bug fixes
Fixes found by the suite:
- timeout error mapping: 'operation timed out' did not match 'timeout' -> exit 7 instead of 28
- invalid --impersonate value now exits 2 (usage error), was falling into connect-error 7
- -F multipart: primp files expects {field: path}; plain form fields via data=
- -j/--json implies POST even with empty body (curl modern semantics)
- -I/--head implies -i (headers shown), matching curl

tests/pcurl-regression.sh: 35 checks covering GET/POST/form/JSON/multipart,
headers, redirects, methods, --fail, TLS, fingerprint UA, env proxy,
error exit codes, flag combining.
2026-10-01 11:13:12 +08:00
vex1023 31a88fc7e3 pcurl: comprehensive Chinese help (examples, env vars, exit codes, curl diffs) 2026-10-01 10:56:11 +08:00
vex1023 99e03c9d14 pcurl: -d implies form-urlencoded content type (curl semantics) 2026-10-01 10:52:53 +08:00
vex1023 b48a3216bf Add pcurl: curl-like CLI backed by primp (Chrome TLS fingerprint)
- curl-compatible subset: -X/-d/-H/-F/-o/-L/-k/-s/-i/-I/-j/--max-time/--proxy
- Default impersonate chrome_146 (primp 2.x); --no-fingerprint to opt out
- Env proxy default (PRIMP_PATCH_PROXY/HTTPS_PROXY); curl exit codes
- Registered as console script 'pcurl' + python -m primp_patch.curl
2026-10-01 10:52:07 +08:00
4 changed files with 379 additions and 0 deletions

No files matched your search

+23
View File
@@ -72,3 +72,26 @@ python -c "import primp_patch, requests; print(requests.get('https://example.com
## License ## License
MIT MIT
## pcurl — curl 平替(内置 CLI)
v0.2.0 起内置 `pcurl`:primp 内核的 curl 风格命令行,默认 Chrome TLS/JA3 指纹。
```bash
pip install primp-patch # 安装后自带 pcurl 命令
python -m primp_patch.curl ... # 或不经 PATH 直接调用
pcurl https://api.github.com/zen # GET,Chrome 指纹
pcurl -s https://httpbin.org/get # -s 静默(状态行不打 stderr)
pcurl -si https://example.com # -i 含响应头
pcurl -X POST https://httpbin.org/post -d 'a=1&b=2'
pcurl -j https://httpbin.org/post <<< '{"k":"v"}' # JSON 快捷(stdin)
pcurl -o page.html https://example.com # 落盘
pcurl -L -k --max-time 10 --proxy http://127.0.0.1:7890 https://target
pcurl --impersonate firefox https://example.com # 换指纹档位
pcurl --no-fingerprint https://example.com # 不做 TLS 伪装
```
- 代理默认取 `$PRIMP_PATCH_PROXY` / `$HTTPS_PROXY`
- 档位(primp 2.x):`chrome_146`(默认)、`chrome_145`、`firefox`、`safari`、`edge`
- 退出码对齐 curl:6 解析失败 / 7 连接失败 / 22 `--fail` 时 4xx/5xx / 28 超时
+3
View File
@@ -23,6 +23,9 @@ dependencies = [
"primp>=0.10", "primp>=0.10",
] ]
[project.scripts]
pcurl = "primp_patch.curl:main"
[project.optional-dependencies] [project.optional-dependencies]
requests = ["requests>=2.20"] requests = ["requests>=2.20"]
urllib3 = ["urllib3>=1.26"] urllib3 = ["urllib3>=1.26"]
+258
View File
@@ -0,0 +1,258 @@
#!/usr/bin/env python3
"""pcurl — curl 风格命令行,primp 内核(浏览器 TLS/JA3 指纹)
用法:
pcurl [选项] <URL>
描述:
pcurl 是 curl 的常用子集平替,底层用 primp(rnet 内核)发送请求,
默认模拟 Chrome 的 TLS/JA3 指纹与 User-Agent,用于访问有反爬
(TLS 指纹检测)的站点。常规管道用法与 curl 一致:
响应体写 stdout,状态信息写 stderr,因此 `pcurl url | jq` 无需 -s。
常用示例:
pcurl https://api.github.com/zen # GET(Chrome 指纹)
pcurl -s https://httpbin.org/get # -s 静默(不打印状态行)
pcurl -si https://example.com # -i 输出含响应头
pcurl -o page.html https://example.com # 响应体落盘
pcurl -L https://example.com/redirect # 跟随重定向(最多 10 跳)
pcurl -X POST https://httpbin.org/post -d 'a=1&b=2' # 表单(自动带 urlencoded CT)
pcurl -d 'a=1' -d 'b=2' URL # 多个 -d 用 & 拼接
pcurl -H 'Authorization: Bearer xxx' URL # 自定义请求头(可重复)
echo '{"k":"v"}' | pcurl -j https://httpbin.org/post # JSON 快捷(读 stdin)
pcurl -j -d '{"k":"v"}' URL # JSON 快捷(直接给数据)
pcurl -F 'file=@photo.jpg' -F 'caption=hi' URL # multipart 上传
pcurl -I https://example.com # HEAD 请求
pcurl -k https://self-signed.badssl.com/ # 忽略证书错误
pcurl --max-time 10 --proxy http://127.0.0.1:7890 URL
pcurl --impersonate firefox URL # 换指纹档位
pcurl --no-fingerprint URL # 关闭 TLS 伪装(普通客户端)
pcurl -f https://httpbin.org/status/404 # 4xx/5xx 时 exit 22,不输出 body
选项 (curl 兼容子集):
请求:
-X, --method <M> HTTP 方法(默认 GET;有 -d/-F 时自动 POST)
-d, --data <data> 请求体;可重复,多个值用 & 拼接;自动附加
Content-Type: application/x-www-form-urlencoded
(除非显式用 -H 指定过 Content-Type)
--data-raw <data> 同 -d(不支持 @file 语法)
-H, --header <h> 请求头 "Name: value"(可重复)
-F, --form <f> multipart 字段 "k=v" 或 "k=@file"(可重复)
-j, --json JSON 快捷:自动加 Content-Type: application/json,
数据来自 -d 或 stdin;合法 JSON 时结构化发送
-I, --head 发 HEAD 请求
-e (无) 不支持,请用 -H 'Referer: ...'
响应控制:
-o, --output <file> 响应体写入文件(- 表示 stdout,默认)
-i, --include 输出中包含响应头(HTTP/1.1 200 风格)
-s, --silent 不向 stderr 打印状态行
-f, --fail 状态码 >= 400 时不输出 body 且 exit 22
-L, --location 跟随 3xx 重定向(最多 10 跳)
--compressed 兼容 curl 而已——primp 始终自动处理压缩
连接与安全:
-k, --insecure 跳过 TLS 证书校验
--proxy <url> 本请求使用的代理;默认取环境变量
$PRIMP_PATCH_PROXY,其次 $HTTPS_PROXY
-m, --max-time <sec> 总超时秒数(默认 30)
--impersonate <p> TLS 指纹档位。primp 2.x 可用:
chrome_146(默认)/ chrome_145 / firefox /
safari / edge;也可用环境变量 $PCURL_IMPERSONATE
--no-fingerprint 不做 TLS 伪装(使用客户端原生指纹)
其他:
-v, --verbose 在 stderr 打印请求摘要
-h, --help 本帮助
环境变量:
PRIMP_PATCH_PROXY 默认代理(如 http://127.0.0.1:7890)
HTTPS_PROXY 次选默认代理
PCURL_IMPERSONATE 默认指纹档位(--impersonate 可覆盖)
退出码(对齐 curl):
0 成功(含 4xx/5xx,除非 --fail)
2 用法错误(未知选项、缺 URL 等)
6 域名解析失败
7 连接失败
22 --fail 时收到 4xx/5xx
28 超时
与 curl 的差异:
* 只支持单个 URL
* 不支持 -w/--write-out、--resolve、-u(Basic 认证请用 -H
'Authorization: Basic ...')、cookie 文件(-b/-c)、@file 请求体
* 遇到不认识的选项会明确报错(退出码 2),不会静默转发给真 curl
* -d 自动附加 form-urlencoded 头(与 curl 一致),但 JSON 场景请用 -j
"""
import sys, os, json as _json
def die(msg, code=2):
print(f"pcurl: {msg}", file=sys.stderr)
sys.exit(code)
def parse_args(argv):
o = dict(method=None, data=[], headers=[], forms=[], output=None,
follow=False, insecure=False, silent=False, include=False,
head=False, json_mode=False, impersonate=None, proxy=None,
max_time=None, verbose=False, fail=False, urls=[],
no_fingerprint=False)
i = 0
while i < len(argv):
a = argv[i]
if a in ('-X', '--method'): o['method'] = argv[i+1]; i += 2
elif a in ('-d', '--data', '--data-raw', '--data-binary'): o['data'].append(argv[i+1]); i += 2
elif a in ('-H', '--header'): o['headers'].append(argv[i+1]); i += 2
elif a in ('-F', '--form'): o['forms'].append(argv[i+1]); i += 2
elif a in ('-o', '--output'): o['output'] = argv[i+1]; i += 2
elif a in ('-L', '--location'): o['follow'] = True; i += 1
elif a in ('-k', '--insecure'): o['insecure'] = True; i += 1
elif a in ('-s', '--silent'): o['silent'] = True; i += 1
elif a in ('-i', '--include'): o['include'] = True; i += 1
elif a in ('-I', '--head'): o['head'] = True; i += 1
elif a in ('-j', '--json'): o['json_mode'] = True; i += 1
elif a == '--impersonate': o['impersonate'] = argv[i+1]; i += 2
elif a == '--proxy': o['proxy'] = argv[i+1]; i += 2
elif a in ('-m', '--max-time'): o['max_time'] = float(argv[i+1]); i += 2
elif a == '--compressed': i += 1
elif a == '--no-fingerprint': o['no_fingerprint'] = True; i += 1
elif a in ('-v', '--verbose'): o['verbose'] = True; i += 1
elif a in ('-f', '--fail'): o['fail'] = True; i += 1
elif a in ('-h', '--help'): print(__doc__); sys.exit(0)
elif a.startswith('-') and len(a) > 1 and a not in ('-',):
# combined short flags e.g. -sS, -si
if not a.startswith('--') and all(c in 'sSikIvLfhj' for c in a[1:]):
for c in a[1:]:
if c == 's': o['silent'] = True
elif c == 'i': o['include'] = True
elif c == 'k': o['insecure'] = True
elif c == 'I': o['head'] = True
elif c == 'v': o['verbose'] = True
elif c == 'L': o['follow'] = True
elif c == 'f': o['fail'] = True
elif c == 'j': o['json_mode'] = True
i += 1
else:
die(f"unrecognized option {a} (use real curl for advanced flags)")
else:
o['urls'].append(a); i += 1
if not o['urls']: die("no URL specified")
if len(o['urls']) > 1: die("only one URL supported per call")
return o
def main():
args = parse_args(sys.argv[1:])
url = args['urls'][0]
# proxy default from env
proxy = args['proxy'] or os.environ.get('PRIMP_PATCH_PROXY') or os.environ.get('HTTPS_PROXY') or None
try:
import primp
except ImportError:
die("primp not importable — install into the venv")
imp = args['impersonate'] or os.environ.get('PCURL_IMPERSONATE') or 'chrome_146'
kw = dict(impersonate=imp, timeout=args['max_time'] or 30.0,
follow_redirects=args['follow'], max_redirects=10,
verify=not args['insecure'], proxy=proxy)
if args['no_fingerprint']:
kw.pop('impersonate')
# headers
hdrs = {}
auth = None
for h in args['headers']:
if ':' not in h: die(f"bad header: {h}")
k, _, v = h.partition(':')
hdrs[k.strip()] = v.strip()
body = None
if args['json_mode']:
hdrs.setdefault('Content-Type', 'application/json')
stdin = sys.stdin.read() if (not args['data'] or args['data'] == ['@-']) else '&'.join(args['data'])
try: body = stdin if stdin else None
except Exception: body = None
elif args['data']:
body = '&'.join(d for d in args['data'])
method = (args['method'] or ('HEAD' if args['head'] else ('POST' if (body or args['forms'] or args['json_mode']) else 'GET'))).upper()
if args['head']:
args['include'] = True # curl: -I implies -i
# multipart: files={field: path}, plain fields via data dict
files = None
form_fields = {}
if args['forms']:
files = {}
for f in args['forms']:
k, _, v = f.partition('=')
if v.startswith('@'):
files[k] = v[1:]
else:
form_fields[k] = v
if not files:
files = None
try:
client = primp.Client(**kw)
req_kw = dict(headers=hdrs or None)
if files is not None:
req_kw['files'] = files
if form_fields:
req_kw['data'] = form_fields
elif args['json_mode'] and body:
try:
req_kw['json'] = _json.loads(body)
except _json.JSONDecodeError:
req_kw['data'] = body
elif body:
req_kw['data'] = body
# curl semantics: -d implies form-urlencoded content type
if not any(k.lower() == 'content-type' for k in (hdrs or {})):
hdrs = dict(hdrs or {})
hdrs['Content-Type'] = 'application/x-www-form-urlencoded'
req_kw['headers'] = hdrs
resp = client.request(method, url, **req_kw)
except Exception as e:
msg = str(e)
low = msg.lower()
if 'timeout' in low or 'timed out' in low: die(msg, 28)
if 'invalid impersonate' in low: die(msg, 2)
if 'resolve' in low or 'dns' in low or 'name or service' in low: die(msg, 6)
die(msg, 7)
status = resp.status_code
rheaders = resp.headers
out = sys.stdout.buffer if args['output'] in (None, '-') else open(args['output'], 'wb')
if args['output'] not in (None, '-'):
outf = open(args['output'], 'wb')
else:
outf = sys.stdout.buffer
if not args['silent'] and args['output'] not in (None, '-'):
# status line to stderr so piping stays clean
pass
if args['include']:
lines = [f"HTTP/1.1 {status}"]
for k, v in rheaders.items():
lines.append(f"{k}: {v}")
outf.write(('\r\n'.join(lines) + '\r\n\r\n').encode())
elif not args['silent']:
print(f"[pcurl] {method} {url} → {status} ({rheaders.get('content-type','')})", file=sys.stderr)
content = resp.content
if args['fail'] and status >= 400:
sys.exit(22)
outf.write(content)
if args['output'] not in (None, '-'):
outf.close()
sys.exit(0 if status < 400 else (22 if args['fail'] else 0))
def cli():
main()
if __name__ == '__main__':
main()
+95
View File
@@ -0,0 +1,95 @@
#!/bin/bash
# pcurl 回归测试套件 — 对齐 curl 语义
# 用法: bash pcurl-regression.sh
# 依赖: pcurl 在 PATH, httpbin.org 可达
PASS=0; FAIL=0
ck() { # ck <name> <expected> <actual>
if [ "$2" = "$3" ]; then PASS=$((PASS+1)); echo "PASS $1"
else FAIL=$((FAIL+1)); echo "FAIL $1 (期望=$2 实际=$3)"; fi
}
j() { python3 -c "import json,sys; d=json.load(sys.stdin); print($1)"; }
# ── T0 基础 GET ──
r=$(pcurl -s https://api.github.com/zen 2>/dev/null); ck "T0a GET github zen 非空" ok "$([ -n "$r" ] && echo ok)"
code=$(pcurl -s -o /dev/null --max-time 20 https://httpbin.org/get 2>/dev/null; echo $?); ck "T0b GET httpbin exit=0" 0 "$code"
# ── T1 状态行到 stderr,body 到 stdout ──
err=$(pcurl https://api.github.com/zen 2>&1 >/dev/null | head -1); ck "T1 stderr 状态行格式" ok "$(echo "$err" | grep -q '^\[pcurl\] GET .* → 200' && echo ok)"
out=$(pcurl -s https://api.github.com/zen 2>/dev/null); ck "T1b -s 时 stderr 干净" 0 "$(pcurl -s https://api.github.com/zen 2>&1 >/dev/null | wc -l | tr -d ' ')"
# ── T2 -i 响应头 ──
h=$(pcurl -si https://httpbin.org/get 2>/dev/null | head -1 | tr -d "\r"); ck "T2 -i 首行 HTTP/1.1 200" "HTTP/1.1 200" "$h"
# ── T3 POST JSON(显式 -H) ──
r=$(pcurl -s -X POST https://httpbin.org/post -H 'Content-Type: application/json' -d '{"k":"v","n":7}' 2>/dev/null | j "d['json']"); ck "T3 POST JSON 回显" "{'k': 'v', 'n': 7}" "$r"
# ── T4 表单 -d 自动 CT ──
r=$(pcurl -s -d 'a=1&b=2' https://httpbin.org/post 2>/dev/null | j "d['form']"); ck "T4 表单回显" "{'a': '1', 'b': '2'}" "$r"
r=$(pcurl -s -d 'a=1&b=2' https://httpbin.org/post 2>/dev/null | j "d['headers']['Content-Type']"); ck "T4b 自动 CT" "application/x-www-form-urlencoded" "$r"
# ── T5 显式 CT 不被覆盖 ──
r=$(pcurl -s -d 'x=1' -H 'Content-Type: text/plain' https://httpbin.org/post 2>/dev/null | j "d['headers']['Content-Type']"); ck "T5 显式 CT 保留" "text/plain" "$r"
# ── T6 多个 -d 用 & 拼接 ──
r=$(pcurl -s -d 'a=1' -d 'b=2' https://httpbin.org/post 2>/dev/null | j "d['form']"); ck "T6 多 -d 拼接" "{'a': '1', 'b': '2'}" "$r"
# ── T7 -j stdin JSON ──
r=$(echo '{"a":1}' | pcurl -s -j https://httpbin.org/post 2>/dev/null | j "d['json']"); ck "T7 -j stdin JSON" "{'a': 1}" "$r"
r=$(pcurl -s -j -d '{"k":"v"}' https://httpbin.org/post 2>/dev/null | j "d['json']"); ck "T7b -j -d JSON" "{'k': 'v'}" "$r"
r=$(pcurl -s -j https://httpbin.org/post 2>/dev/null | j "d['headers']['Content-Type']"); ck "T7c -j 自动 CT" "application/json" "$r"
# ── T8 自定义头 ──
r=$(pcurl -s -H 'X-Test: hello123' https://httpbin.org/get 2>/dev/null | j "d['headers']['X-Test']"); ck "T8 自定义头透传" "hello123" "$r"
# ── T9 -o 落盘 ──
pcurl -s -o /tmp/pc_t9.bin https://api.github.com/zen 2>/dev/null; s=$(wc -c < /tmp/pc_t9.bin); rm -f /tmp/pc_t9.bin
ck "T9 -o 落盘非空" ok "$([ "$s" -gt 0 ] && echo ok)"
# ── T10 重定向 ──
r=$(pcurl -sL -o /dev/null -w '' "https://httpbin.org/redirect/2" 2>/dev/null; echo $?)
r=$(pcurl -sL https://httpbin.org/redirect/2 2>/dev/null >/dev/null; echo $?); ck "T10 -L 跟随重定向" 0 "$r"
# ── T11 方法 ──
r=$(pcurl -s -X PUT https://httpbin.org/put -d 'x=1' -o /dev/null 2>/dev/null; echo $?); ck "T11a PUT" 0 "$r"
r=$(pcurl -s -X DELETE https://httpbin.org/delete -o /dev/null 2>/dev/null; echo $?); ck "T11b DELETE" 0 "$r"
r=$(pcurl -s -I https://httpbin.org/get 2>/dev/null | head -1 | tr -d "\r"); ck "T11c -I HEAD(隐含-i)" "HTTP/1.1 200" "$r"
# ── T12 --fail ──
pcurl -sf https://httpbin.org/status/404 >/dev/null 2>&1; ck "T12a --fail 404 exit=22" 22 $?
pcurl -s https://httpbin.org/status/404 >/dev/null 2>&1; ck "T12b 无 --fail 时 404 exit=0" 0 $?
pcurl -sf https://httpbin.org/status/200 >/dev/null 2>&1; ck "T12c --fail 200 exit=0" 0 $?
# ── T13 -k 自签 ──
pcurl -sk -o /dev/null https://self-signed.badssl.com/ 2>/dev/null; ck "T13 -k 自签通过" 0 $?
pcurl -s -o /dev/null https://self-signed.badssl.com/ >/dev/null 2>&1; c=$?; ck "T13b 无 -k 自签失败(7或35)" ok "$([ $c -ne 0 ] && echo ok)"
# ── T14 UA 指纹 ──
r=$(pcurl -s https://httpbin.org/user-agent 2>/dev/null | j "d['user-agent']"); ck "T14a UA=Chrome 指纹" ok "$(echo "$r" | grep -q 'Mozilla/5.0' && echo "$r" | grep -q 'Chrome/' && echo ok)"
r=$(pcurl -s --no-fingerprint https://httpbin.org/user-agent 2>/dev/null | python3 -c "import json,sys; print(json.load(sys.stdin)['user-agent'] is None)")
ck "T14b --no-fingerprint UA=null" "True" "$r"
# ── T15 环境变量代理 ──
r=$(PRIMP_PATCH_PROXY=http://100.88.88.88:7890 pcurl -s -o /dev/null "https://query1.finance.yahoo.com/v8/finance/chart/AAPL?range=1d&interval=1d" 2>/dev/null; echo $?); ck "T15 env 代理可达 yahoo" 0 "$r"
# ── T16 错误处理 ──
pcurl https://nonexistent-domain-abc123xyz.invalid/ >/dev/null 2>&1; c=$?; ck "T16a DNS 失败 exit∈{6,7}" ok "$([ $c -eq 6 ] || [ $c -eq 7 ] && echo ok)"
pcurl -s --max-time 3 https://httpbin.org/delay/15 >/dev/null 2>&1; ck "T16b 超时 exit=28" 28 $?
pcurl -s --bogus-flag https://x/ >/dev/null 2>&1; ck "T16c 未知选项 exit=2" 2 $?
pcurl >/dev/null 2>&1; ck "T16d 缺 URL exit=2" 2 $?
# ── T17 --impersonate ──
r=$(pcurl -s --impersonate firefox https://httpbin.org/user-agent 2>/dev/null | j "d['user-agent']"); ck "T17a firefox 档位" ok "$(echo "$r" | grep -qi 'Firefox/' && echo ok)"
pcurl -s --impersonate bogus_xyz https://httpbin.org/get >/dev/null 2>&1; ck "T17b 非法档位报错" 2 $?
# ── T18 组合短旗标 ──
h=$(pcurl -si https://httpbin.org/get 2>/dev/null | head -1 | tr -d "\r"); ck "T18 组合旗标 -si" "HTTP/1.1 200" "$h"
# ── T19 multipart ──
echo "hello-pcurl" > /tmp/pc_t19.txt
r=$(pcurl -s -F 'f=@/tmp/pc_t19.txt' -F 'note=hi' https://httpbin.org/post 2>/dev/null | j "(d['form']['note'], 'hello-pcurl' in (d.get('files') or {}).get('f',''))")
ck "T19 multipart 字段+文件" "('hi', True)" "$r"; rm -f /tmp/pc_t19.txt
echo "──────────────────────────"
echo "总计: $PASS PASS / $FAIL FAIL"
[ $FAIL -eq 0 ] && echo "全部通过 ✓" || echo "存在失败 ✗"
exit $FAIL