#moonhttp

#安装

moon add q2316367743/moonhttp

import {
  "q2316367743/moonhttp@0.1.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))

#三个入口

#请求体：四种形态

// 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

#拦截器

let plain = @moonhttp.Client::new() // 给重试用的裸实例：不带这层拦截器，天然不会无限递归
let client = @moonhttp.Client::new(
  interceptors~ = @moonhttp.Interceptors::new()
    // 请求侧：发送前改配置（加认证头、改地址、给所有请求注入公共 body 字段）
    .use_request(config => config.with_header("X-Token", "secret"))
    // 响应侧：原样返回就只是观察；要改就用 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），两个方向相反。
• 拦截器拿到的配置是合并后的；client.create(...) 派生的实例会继承这份链。
• 一次请求只跑一遍：跟 5 跳重定向也只跑一次。响应侧只作用于 Client::request，两个流式入口不过响应链。
• 闭包要写箭头形式（config => ...）或显式标 async fn——效果推断只认箭头语法，具名同步函数传不进去。

#取消请求

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

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

#自动重定向

#代理

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(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 的完整地址

#暂不支持与后续计划

• 快捷方法 get / post / put / delete / head / options / patch：都是 request 的薄封装，计划中。
• 请求体流式上传：请求体目前是一次性字节，表单含文件时整块驻留内存；计划下一期做可写流，让调用方一段段喂数据。
• 连接复用：每次请求新建连接，计划做连接池以省掉重复握手。
• cookie：不管理 cookie（没有 withCredentials / xsrf*，响应里的 Set-Cookie 也读不到）；计划做跨请求复用。
• SSE 自动重连：id / retry 已经作为持久状态带出来了，按 retry 间隔重订阅留给上层；计划内置。
• 响应体自动解析：读法由你在 text() / bytes() / json() 里显式选；静态类型下「猜内容类型」需要先重新设计响应类型的形态。
• transformRequest / transformResponse：不做成独立配置项——请求体固定为四种形态，响应体读法在 Response 上，要「发请求前换 body」「拿到响应后改正文」就在两段拦截器里做。
• 拦截器的 eject / clear / runWhen：撤下一个拦截器就重新构建一份 Interceptors 值。
• 重定向的 beforeRedirect 回调与自定义敏感头名单。
• 代理的 SOCKS 支持、http_proxy / no_proxy 环境变量，以及按请求关掉代理的开关（显式 with_proxy 已支持）。
• 单条头的多值：一个头名只能对应一个字符串值。

#参与开发

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

#许可证