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

go get b612.me/starnet

Quick Example

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.