107 lines
3.0 KiB
Markdown
107 lines
3.0 KiB
Markdown
|
# 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).
|
||
|
|
|