Rakuest
English | 中文
一个 httpx 风格的 Raku HTTP 客户端:请求体用 json / form / files / data / body-stream 关键字传,响应是普通对象(4xx/5xx 不抛异常),cookie、重定向、重试、认证、压缩、TLS 信任根都在门面层统一处理。
底层是窄腰架构:Rakuest::Client 只管策略,Rakuest::Transport 只做「一跳」。默认后端是纯 Raku 的 Cro::HTTP::Client;需要 HTTP/3、SOCKS 代理、mTLS、FTP/SFTP 时换成 libcurl 后端即可,门面一行不改。
大文件双向都不进内存:上传按拉模型分块读(body-stream 与 multipart 的每个文件部件),下载按流直推(download / stream => True)。传入 progress => 就能拿到逐块的上传/下载进度,hooks => 能看到每一跳、每次重试。
安装
zef install .
# 或开发时直接用
raku -Ilib -e 'use Rakuest; ...'
依赖:Cro::HTTP、JSON::Fast。libcurl 后端不额外依赖 Raku 模块——它直接 FFI 到系统里的 libcurl;gzip/deflate 解压用自带的 Rakuest::Zlib(直连系统 zlib,见下面「压缩」一节),也不依赖第三方压缩模块。
注:Cro 0.8.x 的 META 漏声明了 OO::Monitors,个别机器上 zef install . 会在 staging 阶段报 Could not find OO::Monitors。先 zef install OO::Monitors,或用 --to='inst#~/.raku' 指定安装目标。
快速开始
use Rakuest;
my $client = Rakuest::Client.new(
base-url => 'https://360.zef.pm',
timeout => 30,
retry => 2, # 只在传输失败时重试
headers => { accept => 'application/json' },
);
my $r = $client.get('/search', params => { q => 'json' });
say $r.status; # 200
say $r.header('content-type');
say $r.text; # 解码后的字符串
say $r.json; # 自动 from-json(不是 JSON 会明确报错,见下)
say $r.body; # Blob(= content = blob,三个名字同一份字节)
say $r.elapsed; # Duration
$r.raise-for-status; # 想要 httpx 的 raise_for_status 语义时显式调用
请求体五种写法,一次只能选一种(data 例外:它还能配合 files 当文本字段):
$client.post('/api', json => { name => 'rakuest' });
$client.post('/form', form => { a => 1, b => 'x y' });
$client.post('/upload', files => { file => 'README.md' }, data => { note => 'hi' });
$client.put('/raw', data => 'bytes or Blob');
$client.put('/huge', 'body-stream' => 'big.iso'); # 边读边传
上传(流式,内存里只有一块):
use Rakuest::Body; # body-from-handle / body-from-path
$client.post('/upload', 'body-stream' => 'big.iso'); # 路径,长度已知 → Content-Length
$client.post('/upload', 'body-stream' => $*IN); # IO::Handle
$client.post('/upload', 'body-stream' => $supply-of-blobs); # 长度未知 → chunked
$client.post('/upload', 'body-stream' => body-from-handle($fh, :length(1024)));
multipart 也是流式的——文件不会整块读进内存:
$client.post('/upload',
files => {
avatar => 'me.png', # 路径:边读边传,长度已知
log => $fh, # IO::Handle
raw => $blob, # Blob
gen => $supply-of-blobs, # Supply:长度未知 → 整份表单走 chunked
},
data => { note => 'hi' }, # 文本字段,和 files 一起用
);
整份表单是一条 Rakuest::Body::Stream:部件头是常量字节,文件部件直接接上自己的流,
所以内存里始终只有一块,和 body-stream 是同一套机制。想自己拼部件时用底层模型:
use Rakuest::Form;
my $mp = Rakuest::Form::Multipart.new;
$mp.add(Rakuest::Form::Part.new(name => 'note', value => 'hi'));
$mp.add(Rakuest::Form::Part.new(name => 'f', filename => 'a.bin',
content-type => 'application/octet-stream',
stream => body-from-path('a.bin'.IO)));
$client.post('/u', 'body-stream' => $mp.to-stream, content-type => $mp.content-type);
下载(流式落盘,不整块进内存):
my $r = $client.download('/dist/foo.tar.gz', 'foo.tar.gz');
只想自己处理字节流、不落盘时:
my $r = $client.get('/big', stream => True);
react whenever $r.body-stream -> $chunk { ... } # 边收边处理
流式响应不带 content-encoding 协商(增量解压是另一层的事),elapsed 表示首字节时间而不是总耗时。
认证:
Rakuest::Client.new(:$base-url, auth => { username => 'u', password => 'p' }); # Basic
Rakuest::Client.new(:$base-url, auth => { bearer => 'token' }); # Bearer
$client.get('/x', auth => 'user:pass'); # 单次覆盖
错误处理
4xx/5xx 是响应不是异常(想要 httpx 的 raise_for_status 就显式调 raise-for-status)。真正会 die 的是「没拿到 HTTP 响应」:
use Rakuest; # 异常族已经跟着入口模块进来了
try {
$client.get('/boom');
CATCH {
when X::Rakuest::Timeout { say '超时,可重试' }
when X::Rakuest::TransportError { say "连不上:{.message}" }
when X::Rakuest { say "其它失败:{.message}" } # 基类兜底
default { .rethrow }
}
}
use Rakuest; 单独就够(0.4.0 起)。只想要异常类型、不想加载客户端时用 use Rakuest::Error;,名字一样。
.json 解析失败也会落到 X::Rakuest,消息里带状态码、content-type 和正文开头——因为这类失败十有八九不是「JSON 写坏了」,而是拿到了 404/500 的 XML 或 HTML 错误页:
Rakuest: 响应不是 JSON(HTTP 404,content-type: application/xml):<?xml version="1.0"?><Error><Code>NoSuchKey</Code>…。4xx/5xx 不是异常,想直接抛就用 raise-for-status。
顺手说一句:X::Rakuest::TransportError 遇到证书问题时会在消息后面补一行「提示:」,按「本地有没有 CA bundle」分别指向 ca-file 还是「证书链本身有问题」,不用再对着 unable to get local issuer certificate 发呆。
维护备注:lib/Rakuest/Error.rakumod 里的类不能写 is export。这些类叫 X::Rakuest…,不在模块命名空间 Rakuest::Error 之下,is export 会按名字最后一段装符号,于是往 use 方作用域塞一个名叫 Rakuest 的符号、把 Rakuest 包顶掉——use Rakuest; use Rakuest::Error; 会直接报 Redeclaration of symbol 'Rakuest'。所以改成文件末尾的显式 sub EXPORT;t/14-loading.rakutest 守着这条。
选后端
默认后端是 Cro,纯 Raku、不额外 FFI 原生库(HTTPS 要 OpenSSL,gzip 解压要系统 zlib,都是系统里本来就在的东西)。需要下面这些能力时换 libcurl 后端:
| 能力 | Cro 后端 | Curl 后端 |
|---|
| HTTP/1.1 | ✅ | ✅ |
| HTTP/2 | ✅(Cro 自带) | 取决于 libcurl 构建 |
| HTTP/3 | ❌ | 取决于 libcurl 构建 |
| HTTPS 经代理(CONNECT) | ❌ 见下 | ✅ |
| SOCKS4/5 代理 | ❌ | ✅ |
| mTLS 客户端证书 | ❌ | ✅ |
| FTP / SFTP / SCP / SMTP… | ❌ | ✅ |
| Windows 证书库 | ❌(要 ca-file) | ✅(Schannel) |
| 流式下载内存占用 | 低(Supply 直推) | 低(Channel 分块直推) |
| 流式上传(chunked) | ✅ | ✅ |
| 连接复用 | ✅(Cro 自带连接池) | ✅(handle 池,按 host 分桶) |
读空闲超时(read-timeout) | ❌ | ✅(低速检测) |
| 传输进度 | ✅(按块计数) | ✅(原生 xferinfo,整块响应也有) |
| 非 HTTP 协议(ftp/file…) | ❌ | ✅ |
use Rakuest::Client;
use Rakuest::Transport::Curl;
my $client = Rakuest::Client.new(
transport => Rakuest::Transport::Curl.new(
proxy-type => 'socks5', # http | socks4 | socks4a | socks5 | socks5h
proxy => 'socks5://127.0.0.1:1080',
client-cert => 'client.pem', # mTLS
client-key => 'client.key',
connect-timeout => 5,
verbose => True, # 相当于 curl -v,调协议时很有用
),
base-url => 'https://api.example.com',
);
say $client.transport.version; # libcurl/8.21.0 Schannel zlib/1.3.2 …
say $client.transport.available; # 系统里到底有没有 libcurl
say $client.transport.capabilities.keys; # ('http1' 'https' 'ftp' 'socks' 'mtls' …)
注意:显式传了 transport 就以它为准,门面的 insecure / ca-file / ca-path 不再作用到它上面(TLS 交给后端自己的同名参数)。没传时门面按下面的规则自动配置。
libcurl 找不到时(available 为假)不会静默降级:capabilities 返回空集合,请求抛 X::Rakuest::BackendUnavailable,消息里带库名和「换回 Cro 后端」的提示。
绑定不是写死 libcurl.so:native('curl') 只在装了 dev 包(有这个软链)的机器上找得到,所以启动时会在标准库目录里挨个探 libcurl.so.4 / libcurl.dylib 这类真名。libc 同理——Debian/Ubuntu 的 libc.so 是个 GROUP ( … ) 的 ld 脚本,dlopen 会报 invalid ELF header,所以直接要 libc.so.6 / musl 的 soname。这两处都能用环境变量覆盖:RAKUEST_CURL_LIB、RAKUEST_CRT_LIB(值可以是路径,也可以是裸名)。
流式上传与连接复用
请求体是拉模型,不是推模型。 开始传输后,后端反复向 Rakuest::Body::Stream 要数据:Curl 后端走 CURLOPT_READFUNCTION,Cro 后端走 chunked 编码器。要多少给多少,内存里始终只有一块。
长度已知(文件、Blob)就发 Content-Length;不知道(Supply)就 Transfer-Encoding: chunked。两条路都实测过:300KB 文件按 64KB 分块,服务端收到的字节逐字节一致。
$client.post('/up', 'body-stream' => 'big.iso'); # 可重放(每次重开文件)
$client.post('/up', 'body-stream' => supply { ... }); # 只能发一次
连接复用:Curl 后端把 handle 借出/归还(curl_easy_reset 清选项但保留连接缓存),所以同一个后端实例连续请求同一站点只握手一次。默认开启。
池子按 host 分桶(key 是 scheme://host:port,host 不区分大小写、端口补 scheme 默认值),max-idle-connections 因此是每个 host 的额度,默认 8。为什么值得分:混在一个池里时 A、B 两个站点会互抢句柄——并发一高,B 归还时把 A 的暖句柄顶出池子,A 下一跳又得重新握手;而且「8 个额度到底算谁的」也说不清。分桶后各拿各的,邻居的流量影响不到你。
my $c = Rakuest::Client.new(transport => Rakuest::Transport::Curl.new);
$c.get('/a'); $c.get('/b'); $c.get('/c'); # 服务器只看到 1 次 accept
$c.close; # 连池子一起清掉
my $t = Rakuest::Transport::Curl.new(
:max-idle-connections(8), # 每个 host 各留 8 个空闲句柄
:max-host-pools(64), # 最多跟踪 64 个 host,超过按 LRU 整桶回收
);
$t.pool-size; # 空闲句柄总数
$t.pool-size-for('https://a.test/x'); # 只看这一个 host 的桶
$t.pool-hosts; # 当前有哪些 host 桶
$t.pool-key('https://a.test/x'); # → https://a.test:443
Rakuest::Transport::Curl.new(:!reuse-connections); # 每个请求一条连接
Rakuest::Transport::Curl.new(:max-idle-connections(0)); # 同上
307/308 要原样重发请求体。路径 / Blob 来源能重开,Supply 不能——后者抛 X::Rakuest::BodyReplay,而不是悄悄发一个空 body 过去(服务端只会看到长度 0,极难查)。
非 HTTP 协议
libcurl 后端能跑 FTP/SFTP/SCP/file 等,但门面默认只把 http/https 交给默认后端,其它 scheme 要显式映射:
my $curl = Rakuest::Transport::Curl.new;
my $c = Rakuest::Client.new(
transport => $curl,
transports => { 'ftp' => $curl, 'file' => $curl },
);
$c.get('ftp://127.0.0.1:2121/pub/a.txt').text;
$c.get('file:///C:/Windows/win.ini').text;
非 HTTP 协议没有状态行,响应码统一归一成 200(真失败在传输层就已经是 TransportError 了)。否则 is-success 永远是假——这正是之前「能列进能力集合、却没法判断成功」的原因。
上传到 FTP 这类场景目前只支持下载语义(get 读、download 落盘);FTP 上传还没接。
压缩
默认开启:门面自动发 Accept-Encoding: gzip, deflate,收到响应后按 Content-Encoding 解压,并把 content-encoding / content-length 从头里去掉(否则下游按长度读会以为数据被截断)。
$client.get('/x'); # 自动协商 + 解压
$client.get('/x', :!compress); # 单次关掉
Rakuest::Client.new(:!compress); # 全局关掉
$client.get('/x', headers => { 'accept-encoding' => 'identity' }); # 自己接管
流式请求(download)不协商:在流上做增量解码是另一层的事,而且大文件通常是 .tar.gz 这种 Content-Type 层面的压缩,不走 Content-Encoding。
服务端返回不认识的编码(brotli/zstd)或压缩流本身坏了,抛 X::Rakuest::ContentEncoding——不会把压缩字节当正文交出去。
解压是自己实现的(Rakuest::Zlib,百来行 NativeCall,直连系统 zlib),不用 Compress::Zlib。原因不是洁癖:它的 z_stream 把裸 C 指针塞进 CArray / Str 这种受 GC 管理的字段里,和 Cro 的 HTTPS 栈一起加载时,inflate 循环里只要触发一次 GC 就会把 zlib 写的指针当对象指针去标记,进程当场段错误——也就是「HTTP 客户端 + gzip 响应」这个最常见的组合在那边会崩。换成自己的绑定后指针槽一律是 uint64,GC 不会去动它。
代价是多一个原生依赖:Linux 上通常是 zlib1g(默认就装着,curl 自己就依赖它),macOS 自带,Windows 上找 zlib1.dll(Git for Windows 里有一份)。找不到时 decode-body 会抛 X::Rakuest::ContentEncoding 并把「装什么 / RAKUEST_ZLIB_LIB 怎么指」写在消息里,而不是交出一堆乱码。
重定向、重试与超时
重定向的每一跳都留在 response.history 里(老的在前,self 是最后一跳):
my $r = $client.get('/old');
say $r.status; # 200
say $r.history».status; # (301 302) —— 跳了几次一眼就看出来
say $r.history[0].url; # 第一跳的地址(不是最终地址)
$client.get('/old', follow => False); # 只看这一跳:history 为空,status 就是 30x
history 里也都是普通的 Response(status/url/headers/body 都在),排查「302 满天飞」时不用抓包。
重试只针对两类失败,因为语义完全不同:
- 传输失败(连不上、TLS、断流):没有响应可看,按
retry-delay * 第几次 线性退避重发; retry-status 里的状态码(默认 429 503):服务端明说「等会儿再来」,重发前先听 Retry-After。
Rakuest::Client.new(:$base-url, retry => 3); # 最多 4 次尝试
Rakuest::Client.new(:$base-url, retry => 3, retry-status => set()); # 只重传输失败
Rakuest::Client.new(:$base-url, retry => 3, max-retry-delay => 5); # Retry-After 封顶 5s
Retry-After 支持秒数与 HTTP-date 两种写法;过去的时间点按「立刻重试」处理,超过 max-retry-delay(默认 60s)就截断——不能由服务端决定客户端挂多久。
重试不会拿重发不了的请求体开玩笑:body-stream 来源是 Supply 时(replayable 为假)直接把 429 原样交回,而不是偷偷补发一个空 body(服务端只会看到长度 0,极难查)。
超时有三个层次:
| 参数 | 位置 | 管什么 |
|---|
timeout | Client / 单次请求 | 整个请求的总预算 |
connect-timeout | Client | 建连上限,默认 10s |
read-timeout | Curl 后端 | 读空闲上限:速率低于 1 字节/秒持续 N 秒就中断 |
Rakuest::Client.new(
transport => Rakuest::Transport::Curl.new(read-timeout => 30),
timeout => 120,
);
「服务端接了连接就装死」是最常见的一种假卡死,只靠总超时会白等掉整个预算;read-timeout 一两秒就能断开。Cro 后端没有等价能力(它的 timeout 只有 connect / total)。
并发
一个 Client 可以被多个线程同时用:
my @responses = await @urls.map: -> $u { start { $client.get($u) } };
- cookie 罐内部有锁:
absorb / header-for / clear / elems 都是原子的。这不是洁癖——一边写一边迭代 %!store.values,在 MoarVM 上会直接炸 MVM_str_hash_at_end called with a stale hashtable pointer; - 默认后端的懒创建也有锁,并发下不会建出两个连接池(多出来的那个没人关);
- Curl 后端的句柄池是锁保护的,并且按 host 分桶:
max-idle-connections 是每个 host 的额度,max-host-pools 限定最多跟踪多少个 host(超出按 LRU 整桶回收);
close 不是并发安全的:先停掉在飞的请求再关。
进度与钩子
大文件传输最想知道两件事:「传到哪了」和「它到底在干什么」。前者用 progress,后者用 hooks。
my $c = Rakuest::Client.new(
:$base-url,
# total 可能是 Nil(chunked),顺手显示成 "?"
progress => -> Rakuest::Progress $p {
note "{$p.phase} {$p.done}/{$p.total // '?'} {$p.rate.Int} B/s";
},
);
$c.download('/big.iso', 'big.iso'); # 下载按块报
$c.post('/upload', 'body-stream' => 'big.iso'); # 上传按块报
每次回调收到一份不可变快照(Rakuest::Progress):
| 字段 | 说明 |
|---|
phase | upload / download |
done / total | 已传字节 / 总字节(total 未定义 = 不知道) |
fraction / percent | 0..1 / 0..100;total 未知时是 Nil,不是 0 |
rate / eta | 本阶段平均速度(字节/秒)/ 预计剩余秒数 |
attempt / hop | 第几次尝试 / 第几跳(重定向链) |
url / method / elapsed | 这一跳的地址、方法、本阶段已用时 |
几条语义值得写死:
- 重试从头计数:每次尝试一个新 tracker,
attempt 跟着变大,不会把上一轮的字节混进来; - 不确定就不编:chunked 上传/下载没有总长,
total / fraction / eta 一律 Nil,由调用方决定怎么显示「未知」; - 终点一定报:
done == total 那一次不受 progress-interval 限制,进度条不会卡在 99%; - 失败也报:中途断了会补一次「到哪儿了」,不假装成功;
- 回调里抛异常 → 请求失败,异常原样抛到调用点。跑在传输线程(Curl 甚至在原生回调里),别在里面做阻塞操作;静默吞掉异常会让「进度条停住但请求成功」变成最难查的一类问题。
progress-interval 是两次回调的最小间隔(秒,默认 0 = 每个传输 tick 都报)。curl 每 64 KB tick 一次,1 GB 就是一万多次;UI 一般 0.1(10 Hz)就够。单次请求可以 progress => False 关掉,或换一个回调覆盖:
$c.get('/poll'); # 用客户端的回调
$c.get('/poll', progress => False); # 这一次不要进度
$c.post('/up', 'body-stream' => $path, progress => &my_bar);
生命周期钩子
my $c = Rakuest::Client.new(
:$base-url,
hooks => {
request => -> $e { $log.info("→ {$e<method>} {$e<url>}") },
response => -> $e { $log.info("← {$e<response>.status} {$e<url>}") },
redirect => -> $e { $log.info(" {$e<status>} {$e<from>} → {$e<to>}") },
retry => -> $e { $log.info(" retry #{$e<attempt>} in {$e<delay>}s") },
},
);
| 事件 | 何时触发 | 字段 |
|---|
request | 每次尝试发出前 | method url hop attempt |
response | 收到一份响应后(4xx/5xx 也算) | response hop attempt |
redirect | 决定跟随之后 | from to status response |
retry | 决定重试之后 | url attempt delay,外加 status 或 error |
事件对象是 Rakuest::Event,用 $e<字段> 取;一个事件可以挂多个回调(值写成数组)。拼错的事件名在 Client.new 阶段就报错,不会安静地什么都不发生。
redirect / retry 在门面里同步触发(调用方线程),异常直接冒到 request() 的调用点。想在钩子里读响应体要小心:流式响应还没被消费。
TLS 信任根
顺序:insecure > ca-file > ca-path > 自动探测。自动探测会依次看环境变量 RAKUEST_CA_FILE / SSL_CERT_FILE / CURL_CA_BUNDLE,再试常见路径(Git for Windows 的 ca-bundle.crt、/etc/ssl/certs/ca-certificates.crt、Homebrew 的 cert.pem 等)。
Rakuest::Client.new(:$base-url); # 自动探测
Rakuest::Client.new(:$base-url, ca-file => 'ca.pem'); # 指定 bundle
Rakuest::Client.new(:$base-url, ca-path => '/etc/ssl/certs');
Rakuest::Client.new(:$base-url, :!auto-ca); # 什么都不指定,用 OpenSSL 默认行为
Rakuest::Client.new(:$base-url, insecure => True); # 只用于测试
校验失败时不是只把 OpenSSL 那句话抛出来了事:消息后面会跟一行 提示:,并且区分两种情况——本地没有 CA bundle(告诉你去指哪个文件)和有 bundle 但对不上(大概率是服务端漏发中间证书,或中间有 TLS 拦截代理)。Windows 上 libcurl 的错误文字是中文的(Schannel 的 FormatMessage),所以 Curl 后端按错误码判定,不靠字符串匹配。
常用参数
| 位置 | 参数 | 说明 |
|---|
Client.new | base-url | 相对 URL 的基准(建议以 / 结尾) |
| timeout / connect-timeout | 秒;总预算 / 建连 |
| follow / max-redirects | 默认跟随,上限 10 |
| retry / retry-delay | 传输失败重试次数与退避基数 |
| retry-status / max-retry-delay | 这些状态码也重试(默认 429 503);Retry-After 封顶秒数(默认 60) |
| progress / progress-interval | 上传下载进度回调;两次回调的最小间隔(秒,默认 0) |
| hooks | request / response / redirect / retry 事件回调 |
| cookies | 默认开启内存 cookie 罐 |
| compress | 默认开启 gzip/deflate 协商 |
| ca-file / ca-path / auto-ca / insecure | TLS 信任根 |
| proxy | 透传给后端 |
| transport | 显式指定后端(此时上面 TLS 相关不再生效) |
| transports | scheme => 后端 映射,按 scheme 分流 |
get/post/... | params / headers | 查询串 / 请求头 |
| json/form/files/data | 请求体(files 的值可以是路径 / IO::Handle / Blob / Supply,都边读边传) |
| body-stream | 流式请求体:路径 / IO::Handle / Supply / Rakuest::Body::Stream |
| timeout / auth / compress | 单次覆盖 |
| progress | 单次覆盖进度回调(False = 这一次不要) |
| follow / max-redirects | 单次覆盖重定向策略(max-redirects => 0 等价于不跟随) |
| stream | True 时响应体以 Supply 给出,不整块读 |
| http-version | '1.1' / '2' / '3'(要求后端具备该能力) |
选项既可以写成 name => value,也可以写成 'name' => value。Raku 默认把后者当位置参数——门面会把它收编成选项,省得你撞上 Too many positionals passed。
架构:门面 + 窄腰
Rakuest::Client 策略:重定向 / cookie / 认证 / 重试 / 超时 / 压缩 / TLS 信任根 / 能力协商
│
Rakuest::Transport 窄腰 role:request(Request) → Promise<Response>,只做一跳
│
Rakuest::Transport::Cro 默认,纯 Raku,HTTP/1.1 + HTTP/2
Rakuest::Transport::Curl 可选,NativeCall 直连 libcurl:HTTP/2·3 / SOCKS / mTLS / FTP…
Rakuest::Zlib gzip/deflate 解压,NativeCall 直连系统 zlib(与后端无关)
后端契约(加新后端时逐条对照,见 lib/Rakuest/Transport.rakumod):
- 返回
Rakuest::Response;4xx/5xx 不是异常,是响应; - 只做一跳:不跟随重定向、不碰 cookie、不重试、不注入认证头;
- 拿不到 HTTP 响应时 die
X::Rakuest::TransportError(超时用其子类 X::Rakuest::Timeout); - 流式请求把 body 放进
Response.stream,不要整块读; - 用
capabilities 声明能力(http1 http2 http3 ftp socks mtls…)。
因为策略全在门面,换后端时用户代码与行为都不变——这也是 t/05-client.rakutest 用一个假后端就能验证全部策略的原因。
加一个后端
use Rakuest::Transport;
use Rakuest::Response;
class My::Transport does Rakuest::Transport {
method capabilities(--> Set) { set(<http1>) }
method request(Rakuest::Request $req, Rakuest::Progress::Tracker :$progress --> Promise) {
start {
# 只做一跳,结果塞进 Rakuest::Response
Rakuest::Response.new(status => 200, headers => %(), url => $req.url, blob => Blob.new);
}
}
}
:$progress 可以不管(不传时是 Nil,门面也不会多传这个参数);想支持进度就照 Cro / Curl 的做法:上传按块 advance('upload', $n)、下载按块 advance('download', $n)(或按累计值 report)、已知总长时 set-total,阶段结束 finish,收尾前 abort-if-failed 把用户回调的异常抛回去。
Cookie
内存 cookie 罐,按 RFC 6265 的语义实现(不依赖后端,换后端行为一致):
name / value / Domain / Path / Secure / Max-Age / Expires;Expires 支持 IMF-fixdate(Sun, 06 Nov 1994 08:49:37 GMT)、RFC 850(06-Nov-94)、asctime(Sun Nov 6 08:49:37 1994)三种历史格式;解析不出来的当会话 cookie;Max-Age 优先于 Expires;Max-Age <= 0 或过去的 Expires 直接删除该 cookie(站点登出就靠这个);Domain 必须是请求域名的后缀,否则忽略整条属性——避免 Set-Cookie: a=1; Domain=com 把 cookie 发给整个顶级域;- 发送时路径更具体的排在前面。
$client.cookies.header-for('https://a.test/x'); # 看看会发什么
$client.cookies.clear;
Rakuest::Client.new(:!cookies); # 完全关掉
已知限制(0.8.2)
- Cro 后端不支持 HTTPS 经代理:Cro 没有实现 CONNECT 隧道,会把
GET https://host/ 明文发给代理端口(连带 Authorization 一起漏)。这既是功能缺陷也是安全问题,所以检测到就直接抛 X::Rakuest::ProxyUnsupported;可用 NO_PROXY 放行,或换 Curl 后端。 - 代理是构造期设置,不支持单请求切换。
- 连接池按
scheme://host:port 分桶:同一台机器的 HTTP 与 HTTPS 各自成桶(本来也不该共享 socket),显式端口不同的视为不同 host,file:// 全部共用一个桶。走代理时桶仍按目标 host 算,不是代理地址——这样同一代理上的多个站点不会互相抢 tunnel。 - 流式响应的
elapsed 是首字节时间;中途断流时异常从 Supply 上传出,已经写出去的字节不会回滚。 - multipart 的文本字段(
data)只能是字符串;文件名字段按 UTF-8 原样发送,没做 RFC 5987 的 filename* 编码。整份表单要么能重放(全部来自路径 / Blob),要么一跳都不能重定向 —— 中间夹一个 Supply 会让 307/308 直接抛 BodyReplay。 - 非 HTTP 协议只做了下载语义,FTP 上传未接。
read-timeout 只有 Curl 后端有;Cro 后端只能靠 timeout 兜底。- 进度计的是字节,不是「工作完成度」:gzip 响应报的是压缩后的字节(与 Content-Length 一致),不是解压后的体积;也不包含 DNS / TCP / TLS 握手那一段。
- 钩子是同步的(在调用方线程或传输线程上直接执行),没有异步派发,也没有优先级;
progress 不走 hooks,它是独立选项。 - 重试的等待是线性的(
retry-delay * 次数),没有抖动,也没有指数退避。 - 解压依赖系统 zlib:库不在时,带
Content-Encoding 的响应直接抛 X::Rakuest::ContentEncoding,不会退回原始压缩字节。 - 响应头不是 UTF-8 时(老服务器用 GBK 发
filename="报表.xlsx")不会让请求失败:先按 UTF-8 解,失败再按 latin-1 兜底。代价是这类头值取出来是乱码而不是中文——HTTP 头本身没有编码声明,靠猜只会错得更隐蔽。 - HTTP/2 只在 Cro 后端与带 nghttp2 的 libcurl 上可用;HTTP/3 要求 libcurl 用 quiche/ngtcp2 构建。
Windows 备注
IO::Socket::Async::SSL(Cro 用的)不会读系统证书库,HTTPS 可能报 Server certificate verification failed。0.2.0 起门面会自动找 Git for Windows 自带的 ca-bundle.crt,多数情况下已经不用手动配置;实在找不到就显式给 ca-file,或者换 Curl 后端(走 Schannel,天然读系统库)。
解压要有一个 zlib1.dll:Git for Windows 在 <安装目录>\usr\bin\ 下带了一份,通常已经在 PATH 里。找不到时 decode-body 抛 X::Rakuest::ContentEncoding,消息里写着缺什么,也可以用 RAKUEST_ZLIB_LIB 直接指到具体文件(路径或裸名都行)。
测试
for t in t/*.rakutest; do raku -Ilib "$t"; done
# 真网络测试(默认跳过)
RAKUEST_LIVE=1 raku -Ilib xt/live.rakutest
RAKUEST_LIVE=1 RAKUEST_LIVE_BACKEND=curl RAKUEST_LIVE_BASE=https://example.com raku -Ilib xt/live.rakutest
离线测试 600 个(含子测试;Linux 上 libcurl 能力探测有几条按环境跳过,那边是 598),不联网:URL 解析、响应对象(blob/content/body 同一份字节、非 JSON 响应的报错话术)、重定向语义与 history、cookie 罐(含 Expires 三种日期格式与 Domain 校验)、门面策略(用假后端)、TLS 信任根优先级与证书错误的提示分支(缺 bundle / 有 bundle 但对不上 / 自签名 / 已过期 / 本地化中文错误文字)、gzip/deflate 解码(拿系统 gzip 造的真字节、gzip/zlib/raw 三种包装、空输入、300KB 往返、坏流与截断必须抛 X::Rakuest::ContentEncoding)、宽松解码(UTF-8 直通、GBK 错误消息、GBK 响应头不让请求失败)、原生库按 soname 定位、libcurl 能力协商与请求头链表结构、流式分块与断流传播、流式上传(300KB 逐字节比对、chunked 分块、307 重放)、multipart(手写 RFC 格式逐字节比对、文件 300KB 逐字节比对、两个后端一致、句柄/Blob/Supply 三种来源、chunked 退让、307 重放)、连接复用(数服务器 accept 次数)与连接池分桶(两个 host 各自成桶、per-host 额度、LRU 整桶回收)、file:// 与 ftp://(自带一个最小 FTP 服务器)、模块加载组合(子进程里 use 各模块,防包符号冲突回归)、并发(多线程共享 Client 与 cookie 罐)、重试策略(429/503、Retry-After 两种写法、上限截断)、读空闲超时、进度回调(两个后端 × 上传/下载/流式/整块、chunked 无总长、限流、回调抛异常)、生命周期钩子(request/response/redirect/retry 与拼错事件名)。
其中带网络的部分都用 t/lib/RakuestTestServer.rakumod 起的裸 socket 服务器验证——不依赖外网,也不依赖 Cro 把细节藏起来。
名字
Rakuest = Raku + request。读起来就是 "request"。