starnet/README.md

# starnet

`starnet` 是一个面向 Go 的网络工具库，提供 HTTP 请求控制、TLS 嗅探和 ICMP Ping 能力。

## 功能概览

- 基于 `context` 的请求级超时控制，不修改共享 `http.Client` 的全局超时
- 请求级网络控制：代理、自定义 IP / DNS、拨号超时、TLS 配置
- 支持请求级 `Host` 覆盖、显式 `TLSServerName/SNI` 控制，以及结构化 trace 回调 / 摘要
- 内置重试机制，支持重试次数、退避、抖动、状态码白名单和自定义错误判定
- 响应体大小限制，避免一次性读取过大内容
- 错误分类辅助：`ClassifyError`、`IsTimeout`、`IsDNS`、`IsTLS`、`IsProxy`、`IsCanceled`
- TLS 嗅探监听 / 拨号工具，适用于 TLS 与明文混合场景
- ICMP Ping，支持 IPv4 / IPv6 目标和选项化探测

## 主要能力

### HTTP 客户端与请求构建

- 同时提供 `WithXxx` 选项和 `SetXxx` 链式调用两套接口
- 支持 `Get`、`Post`、`Put`、`Delete`、`Head`、`Patch`、`Options`、`Trace`、`Connect`
- 支持 JSON、表单、`multipart/form-data`、流式请求体等常见请求体形态
- 支持显式 `Host` 覆盖与 `TLSServerName` 设置，便于直连 IP、虚拟主机和证书校验场景分离控制
- Header、Cookie、Query 等输入在关键路径上做防御性拷贝，降低外部可变状态污染风险
- `Request.Clone()` 可用于并发场景或同一基础请求的变体构造

### Trace 与诊断

- 支持 `TraceHooks`，可接收 DNS、建连、TLS 握手、写请求、首包等结构化事件
- 支持 `TraceRecorder` / `TraceSummary`，用于汇总一次请求的关键网络过程和 TLS 摘要
- `Request.TraceSummary()` 返回该请求最近一次执行的摘要快照，`Response.TraceSummary()` 返回当前响应对应的摘要快照
- 若多个请求共享同一个 `TraceRecorder`，其 `Summary()` 表示最近一次完成请求的摘要

### 超时与重试

- 请求超时通过 `context` 截止时间控制，不污染共享客户端配置
- 重试支持：
  - 最大尝试次数
  - 基础退避、最大退避和退避因子
  - 抖动比例
  - 可重试状态码集合
  - 仅幂等方法重试
  - 自定义错误判定函数
- 重试成功后返回的 `Response` 仍保持对原始 `Request` 的引用

### 响应处理

- 提供 `Bytes`、`String`、`JSON`、`Reader` 等响应体读取接口
- 支持自动预取响应体
- 支持按字节数限制响应体读取上限

### Ping 模块

- 提供 `Ping`、`PingWithContext`、`Pingable` 以及兼容函数 `IsIpPingable`
- `PingOptions` 支持次数、超时、间隔、截止时间、地址族偏好、源地址、负载长度等参数
- 对权限不足、协议不支持、超时、解析失败等情况提供明确错误语义

## 安装

```bash
go get b612.me/starnet
```

## 快速示例

```go
package main

import (
    "fmt"
    "net/http"
    "time"

    "b612.me/starnet"
)

func main() {
    resp, err := starnet.Get(
        "https://example.com",
        starnet.WithTimeout(2*time.Second),
        starnet.WithRetry(2,
            starnet.WithRetryBackoff(100*time.Millisecond, 1*time.Second, 2),
            starnet.WithRetryJitter(0.1),
        ),
        starnet.WithMaxRespBodyBytes(1<<20),
    )
    if err != nil {
        fmt.Println("request failed:", starnet.ClassifyError(err), err)
        return
    }
    defer resp.Close()

    fmt.Println("status:", resp.StatusCode)
    _, _ = resp.Body().Bytes()

    ok, pingErr := starnet.Pingable("example.com", &starnet.PingOptions{
        Count:   2,
        Timeout: 2 * time.Second,
    })
    fmt.Println("pingable:", ok, pingErr == nil)

    _ = http.MethodGet
}
```

## 行为说明

- `NewClient`、`NewRequest` 以及请求构造相关接口在遇到非法选项时会直接返回错误，例如格式不合法的代理地址。
- `NewClientNoErr` 是便利构造函数；如果选项校验失败，仍可能返回一个占位 `Client`，需要严格校验配置时应优先使用 `NewClient`。
- `SetHost` / `WithHost` 只覆盖 HTTP 请求的 `Host`；如需单独控制 TLS SNI 或证书校验名，应配合 `SetTLSServerName` / `WithTLSServerName` 使用。
- 重试默认仅对幂等方法生效。即使显式关闭“仅幂等方法重试”，通过 `SetBodyReader` 或 `WithBodyReader` 构造的请求在非幂等方法上仍不会自动重试。
- 当同时使用 `proxy + custom IP/DNS` 且解析出多个目标地址时，自动目标回退仅对幂等请求生效，以避免重复写入。
- 绑定到请求上的 `TraceRecorder` 用于发布已完成请求的摘要；请求执行中的中间状态不保证通过共享 recorder 实时可见。

## 稳定性说明

- 原始 ICMP Ping 在部分系统上需要额外权限。
- 依赖外部网络环境的集成测试结果可能受运行环境影响。

## 许可证

本项目采用 Apache License 2.0，详见 [LICENSE](./LICENSE)。