# Rakuest **Repository Path**: skyter10086/rakuest ## Basic Information - **Project Name**: Rakuest - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-20 - **Last Updated**: 2026-11-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Rakuest [English](README.en.md) | 中文 一个 **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 =>` 能看到每一跳、每次重试。 ## 安装 ```bash 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'` 指定安装目标。 ## 快速开始 ```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` 当文本字段): ```raku $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'); # 边读边传 ``` 上传(流式,内存里只有一块): ```raku 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 也是流式的——文件不会整块读进内存: ```raku $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` 是同一套机制。想自己拼部件时用底层模型: ```raku 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); ``` 下载(流式落盘,不整块进内存): ```raku my $r = $client.download('/dist/foo.tar.gz', 'foo.tar.gz'); ``` 只想自己处理字节流、不落盘时: ```raku my $r = $client.get('/big', stream => True); react whenever $r.body-stream -> $chunk { ... } # 边收边处理 ``` > 流式响应不带 `content-encoding` 协商(增量解压是另一层的事),`elapsed` 表示**首字节时间**而不是总耗时。 认证: ```raku 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 响应」: ```raku 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):NoSuchKey…。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…) | ❌ | ✅ | ```raku 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 分块,服务端收到的字节逐字节一致。 ```raku $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 个额度到底算谁的」也说不清。分桶后各拿各的,邻居的流量影响不到你。 ```raku 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 要显式映射: ```raku 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` 从头里去掉(否则下游按长度读会以为数据被截断)。 ```raku $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` 是最后一跳): ```raku 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`。 ```raku 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 秒就中断 | ```raku Rakuest::Client.new( transport => Rakuest::Transport::Curl.new(read-timeout => 30), timeout => 120, ); ``` 「服务端接了连接就装死」是最常见的一种假卡死,只靠总超时会白等掉整个预算;`read-timeout` 一两秒就能断开。Cro 后端没有等价能力(它的 `timeout` 只有 connect / total)。 ## 并发 一个 `Client` 可以被多个线程同时用: ```raku 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`。 ```raku 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` 关掉,或换一个回调覆盖: ```raku $c.get('/poll'); # 用客户端的回调 $c.get('/poll', progress => False); # 这一次不要进度 $c.post('/up', 'body-stream' => $path, progress => &my_bar); ``` ### 生命周期钩子 ```raku my $c = Rakuest::Client.new( :$base-url, hooks => { request => -> $e { $log.info("→ {$e} {$e}") }, response => -> $e { $log.info("← {$e.status} {$e}") }, redirect => -> $e { $log.info(" {$e} {$e} → {$e}") }, retry => -> $e { $log.info(" retry #{$e} in {$e}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` 等)。 ```raku 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,只做一跳 │ 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` 用一个假后端就能验证全部策略的原因。 ### 加一个后端 ```raku use Rakuest::Transport; use Rakuest::Response; class My::Transport does Rakuest::Transport { method capabilities(--> Set) { set() } 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 发给整个顶级域; - 发送时路径更具体的排在前面。 ```raku $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` 直接指到具体文件(路径或裸名都行)。 ## 测试 ```bash 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"。