# starnet

`starnet` is a Go network toolkit focused on practical HTTP request control, TLS sniff utilities, and ICMP ping capabilities.

## Highlights

- Request-level timeout by context (without mutating shared `http.Client` timeout)
- Fine-grained network controls: custom DNS/IP, dial timeout, proxy, TLS config
- Built-in retry with replay safety checks and configurable backoff/jitter/statuses
- Response body safety guard via max body bytes limit
- Error classification helpers (`ClassifyError`, `IsTimeout`, `IsDNS`, `IsTLS`, `IsProxy`, `IsCanceled`)
- TLS sniffer listener/dialer utilities for mixed TLS/plain traffic scenarios
- ICMP ping with IPv4/IPv6 target handling and option-based probing API

## Main Features

### HTTP Client and Request

- Fluent APIs with both `WithXxx` options and `SetXxx` chain methods
- Methods: `Get/Post/Put/Delete/Head/Patch/Options/Trace/Connect`
- Request body helpers: JSON, form data, multipart file upload, stream body
- Header/cookie/query helpers with defensive copy on key setters
- Request cloning for safe reuse in concurrent or variant calls

### Timeout and Retry

- Request timeout is applied by context deadline, not global client timeout
- Retry supports:
  - max attempts
  - backoff factor/base/max
  - jitter
  - retry status whitelist
  - idempotent-only guard
  - custom retry-on-error callback
- Retry keeps original request pointer in final response for consistency

### Response Handling

- `Bytes/String/JSON/Reader` helpers
- optional auto-fetch mode
- configurable max response body bytes to prevent oversized reads

### Ping Module

- `Ping`, `PingWithContext`, `Pingable`, and compatibility helper `IsIpPingable`
- `PingOptions` for count/timeout/interval/deadline/address preference/source IP/payload size
- explicit error semantics for permission/protocol/timeout/resolve failures

## Install

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

## Quick Example

```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
}
```

## Stability Notes

- Raw ICMP ping may require elevated privileges on some systems.
- Integration tests that rely on external network are environment-dependent.

## License

This project is licensed under the Apache License 2.0.
See [LICENSE](./LICENSE).