#moonhttp

#安装

moon add q2316367743/moonhttp

import {
  "q2316367743/moonhttp@0.6.0",
}

#快速开始

///|
async fn main {
  // 实例上一次性配好 base_url 与公共头，之后的请求只写路径
  let api = @moonhttp.create(
    @moonhttp.Config::default()
      .with_base_url("https://api.github.com")
      .with_timeout(5_000)
      .with_common_header("Accept", "application/vnd.github+json"),
  )

  let res = api.request(
    @moonhttp.Config::new("/repos/moonbitlang/core").with_params({
      "per_page": 3,
    }),
  )

  println(res.status) // 200
  println(res.text()) // 响应体原文，按 response_encoding 解码（默认 UTF-8）
  println((try! res.json()).stringify()) // 要对象就 json()
}

#功能与用法

#实例与配置合并

// 从既有实例派生：继承默认值与拦截器，再叠加本次的配置
let search = api.create(@moonhttp.Config::default().with_timeout(15_000))

#三个入口

#快捷方法

// 只要 url
let repos = api.get("/repos")

// 其余配置照旧走 config：query、超时、实例默认值（base_url、公共头）都在
let page = api.get("/repos", config=@moonhttp.Config::default().with_params({ "page": 1 }))

// 请求体也走 config：形态由 with_data_from_* 决定（json / str / form / urlencoded）
api.post("/users", config=@moonhttp.Config::default().with_data_from_json({ "name": "moon" }))
api.delete("/users/1")

#请求体：四种形态

// JSON 请求体
api.request(@moonhttp.Config::new("/users")
  .with_method(@moonhttp.Method::Post)
  .with_data_from_json({ "name": "moon" }))

// 带文件的表单：文件按「字节 + 文件名」传入，库不读盘
let form = @moonhttp.FormData::new()
  .append_text("title", "假期照片")
  .append_file("avatar", "a.png", bytes, content_type="image/png")
api.request(@moonhttp.Config::new("/upload")
  .with_method(@moonhttp.Method::Post)
  .with_data_from_form(form))

#读响应

res.text()           // 按 response_encoding（默认 UTF-8）解码成文本
res.bytes()          // 原样取出字节，不经过任何解码
try! res.json()      // 先按同一编码解码，再 @json.parse（失败抛 @json.ParseError）
res.content_length() // 响应体字节数
res.is_success()     // 状态码是不是 2xx

#压缩响应

// 关掉自动解压：请求侧改声明 identity，响应体与 Content-Encoding 都保持线上原样
let res = client.request(
  @moonhttp.Config::new("/package.tgz").with_decompress(false),
)
let compressed : Bytes = res.bytes()

#拦截器

let plain = @moonhttp.Client::new() // 给重试用的裸实例：不带这层拦截器，天然不会无限递归
let client = @moonhttp.Client::new(
  interceptors~ = @moonhttp.Interceptors::new()
    // 请求侧：发送前改配置（加认证头、改地址、给所有请求注入公共 body 字段）
    .use_request(config => config.with_header("X-Token", "secret"))
    // 请求侧的错误路径：网络类失败的重试写这（下面两处是同一个写法，写在哪一侧
    // 决定它会看到哪一类失败）
    .use_request(config => config, on_rejected=error => plain.request(error.config()))
    // 响应侧：原样返回就只是观察；要改就用 with_status / with_headers / with_body / with_text / with_json
    .use_response(response => response)
    // 响应侧的错误路径：只有「请求成功、状态码不是 2xx」会走到这——按状态码分支的重试与降级写这
    .use_response(response => response, on_rejected=error => plain.request(error.config())),
)

• 顺序：请求侧后注册先跑（LIFO）、响应侧先注册先跑（FIFO），两个方向相反。
• 错误处理器返回一个 Response 就是「这次失败救回来了」（它直接成为 request 的结果）；救不回就 raise error 继续往外抛。
• 拦截器拿到的配置是合并后的；client.create(...) 派生的实例会继承这份链。
• 一次请求只跑一遍：跟 5 跳重定向也只跑一次。两个错误处理器与响应链都只作用于 Client::request——两个流式入口只过请求拦截器。
• 拦截器闭包写成箭头形式（config => ...），或在签名上标 async fn。
• 给一条起名（use_request(f, name="auth")）就可寻址：同名再注册替换原位（换 token 源不必先撤再注册），remove_request("auth") 按名撤下，名字没注册过返回 None。要给某个实例少挂一条，就把裁过的链交给它：Client::new(interceptors~ = base.remove_response("unwrap").unwrap())。语义细则见 docs/11。

#取消请求

let stop = @moonhttp.AbortController::new()

@async.with_task_group(group => {
  let running = group.spawn(() => {
    api.request(
      @moonhttp.Config::new("/reports/big.csv"),
      signal=stop.signal(),
    ) catch {
      error if error.is_cancelled() => println("已取消：" + error.message())
    }
  })
  @async.sleep(2_000)
  stop.abort(reason="Operation canceled by the user.")
  running.wait()
})

#自动重定向

#Cookie 自动维护

let jar = @moonhttp.CookieJar::new()
let client = @moonhttp.Client::new(cookie_jar=jar)
ignore(client.request(@moonhttp.Config::new("https://example.com/login")))    // 响应种下会话 cookie
ignore(client.request(@moonhttp.Config::new("https://example.com/profile")))  // 自动带上

#代理

let client = @moonhttp.create(
  @moonhttp.Config::default()
    .with_base_url("https://api.example.com")
    .with_proxy("127.0.0.1", port=9000, username="mikeymike", password="rapunz3l"),
)

#上传与下载进度

client.request(
  @moonhttp.Config::new("/upload")
  .with_method(@moonhttp.Method::Post)
  .with_data_from_json({ "name": "moon" })
  .with_on_upload_progress(fn(event) { println("已上传 \{event.loaded} 字节") })
  .with_on_download_progress(fn(event) { println("已下载 \{event.loaded} 字节") }),
)

#流式响应与 SSE

///|
async fn download(api : @moonhttp.Client) -> Unit raise @moonhttp.HttpError {
  let res = api.stream(@moonhttp.Config::new("/big-file"))
  println(res.status) // 响应头已到手，body 还没读
  while res.read_some() is Some(chunk) {
    println(chunk.length())
  }
}

///|
async fn watch(api : @moonhttp.Client) -> Unit raise @moonhttp.HttpError {
  let events = api.sse(@moonhttp.Config::new("/events"))
  while events.next_event() is Some(event) {
    println(event.event + ": " + event.data) // message: {...}
  }
}

#错误处理

try {
  ignore(api.request(config))
} catch {
  @moonhttp.HttpError::HttpError(info) => {
    println(info.code) // BadRequest
    println(info.message) // 请求失败，状态码 404
    println(info.response.unwrap().status) // 404
    println(info.config.url) // 出错时的配置，便于定位
  }
}

#用 Mock 传输层测试

let mock = @transport.MockTransport::new(response)
let transport : &@transport.Transport = mock
ignore(@moonhttp.Client::new(transport=transport).request(@moonhttp.Config::new("/users")))
println(mock.last_request().unwrap().url) // 已经拼好 base_url 与 query 的完整地址

#暂不支持与后续计划

• 连接复用：每次请求新建连接，计划做连接池以省掉重复握手。
• SSE 自动重连：id / retry 已经作为持久状态带出来了，按 retry 间隔重订阅留给上层；计划内置。
• 响应体自动解析：读法由你在 text() / bytes() / json() 里显式选；静态类型下「猜内容类型」要先重新设计响应类型的形态，留待后续版本。
• transformRequest / transformResponse：不做成独立配置项——用两段拦截器代替（请求侧改 body、响应侧改正文，见上面「拦截器」一节）。
• 拦截器的 runWhen（按条件跳过）与 synchronous（批量注册）：条件写在拦截器体内 if 即可，批量注册用链式 use_*；eject 的等价物是具名注册 + remove_request / remove_response。
• 重定向的 beforeRedirect 回调与自定义敏感头名单。
• 代理的 SOCKS 支持（自研传输 HttpConnTransport 的下一个提交补 SOCKS5）、http_proxy / no_proxy 环境变量，以及按请求关掉代理的开关（显式 with_proxy 已支持）。
• 单条头的多值：一个头名只能对应一个字符串值。
• deflate / br 等其它压缩编码：响应解压只做 gzip（moonbitlang/async 只提供 gzip 的编解码器）；别的编码既不解压也不报错，字节与 Content-Encoding 原样交给你。

#参与开发

moon check              # 类型检查
moon test               # 全部测试（不需要外网）
moon run src/main        # 快速上手示例（真实网络，本地手动测试用，不随包发布）
moon run src/main/proxy  # 其余七个方向同理：把 <方向> 换成 basics/methods/proxy/
                         # progress/redirect/interceptors/sse 之一
moon info && moon fmt   # 更新 .mbti 接口并格式化，提交前跑一次

chmod +x .githooks/pre-commit && git config core.hooksPath .githooks

#许可证