Rand Stats

Rakuest

zef:skyter10086

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 满天飞」时不用抓包。

重试只针对两类失败,因为语义完全不同:

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,极难查)。

超时有三个层次:

参数位置管什么
timeoutClient / 单次请求整个请求的总预算
connect-timeoutClient建连上限,默认 10s
read-timeoutCurl 后端读空闲上限:速率低于 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) } };

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):

字段说明
phaseupload / download
done / total已传字节 / 总字节(total 未定义 = 不知道)
fraction / percent0..1 / 0..100;total 未知时是 Nil,不是 0
rate / eta本阶段平均速度(字节/秒)/ 预计剩余秒数
attempt / hop第几次尝试 / 第几跳(重定向链)
url / method / elapsed这一跳的地址、方法、本阶段已用时

几条语义值得写死:

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.newbase-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)
hooksrequest / response / redirect / retry 事件回调
cookies默认开启内存 cookie 罐
compress默认开启 gzip/deflate 协商
ca-file / ca-path / auto-ca / insecureTLS 信任根
proxy透传给后端
transport显式指定后端(此时上面 TLS 相关不再生效)
transportsscheme => 后端 映射,按 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 等价于不跟随)
streamTrue 时响应体以 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):

  1. 返回 Rakuest::Response;4xx/5xx 不是异常,是响应;
  2. 只做一跳:不跟随重定向、不碰 cookie、不重试、不注入认证头;
  3. 拿不到 HTTP 响应时 die X::Rakuest::TransportError(超时用其子类 X::Rakuest::Timeout);
  4. 流式请求把 body 放进 Response.stream,不要整块读;
  5. 用 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 罐,按 RFC 6265 的语义实现(不依赖后端,换后端行为一致):

$client.cookies.header-for('https://a.test/x');   # 看看会发什么
$client.cookies.clear;
Rakuest::Client.new(:!cookies);                   # 完全关掉

已知限制(0.8.2)

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"。