refractored stargate into a library

Author: lanrat

.cspell.json

@@ -5,15 +5,21 @@
     "dictionaries": [],
     "words": [
         "bijective",
+        "BINDANY",
         "buildx",
         "congruential",
+        "errgroup",
+        "Freebind",
         "goarch",
         "godoc",
         "golangci",
+        "GOPROXY",
         "goreleaser",
         "ldflags",
         "Mersenne",
+        "netip",
         "nonlocal",
+        "stargate",
         "trimpath"
     ],
     "ignoreWords": [],

.vscode/.gitignore

@@ -9,7 +9,7 @@ SOURCES := $(shell find . -type f -name "*.go")
 .PHONY: all fmt clean docker lint
 
 stargate: ${SOURCES} go.mod go.sum
-	CGO_ENABLED=0 go build -ldflags "-w -s -X main.version=${VERSION}" -trimpath -o $@
+	CGO_ENABLED=0 go build -ldflags "-w -s -X main.version=${VERSION}" -trimpath -o $@ cmd/*.go
 
 clean:
 	rm stargate

.vscode/settings.json

@@ -1,10 +1,10 @@
 # Stargate
 
-Stargate is a TCP SOCKS5 proxy server that can egress traffic from multiple IP addresses within a subnet. It randomly distributes connections across different IP addresses to help avoid rate-limiting and provide load balancing across your available IP range.
+Stargate is both a Go library and a TCP SOCKS5 proxy server that can egress traffic from multiple IP addresses within a subnet. It randomly distributes connections across different IP addresses to help avoid rate-limiting and provide load balancing across your available IP range.
 
 This requires the host running stargate to have the subnet routed directly to it.
 
-If you have an IPv6 subnet, stargate can allow you to make full use of it by any program that can speak SOCKS.
+If you have an IPv6 subnet, stargate can allow you to make full use of it by any program that can speak SOCKS, or you can use the library directly in your Go applications.
 
 ## Usage
 
@@ -155,3 +155,73 @@ This will produce a statically linked binary that's ready to use.
 ### Platforms
 
 Stargate makes use of freebind, which allowed for creating a socket with a source IP address on an interface that does not have that IP directly bound to it. This is only available on Linux and FreeBSD. Stargate can work on other platforms, but it will require every address to be previously bound to the interface before running.
+
+## Go Library
+
+You can use Stargate as a Go library in your applications to make HTTP requests or other network connections using random source IP addresses:
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "net/http"
+    "net/netip"
+    "time"
+
+    "github.com/lanrat/stargate"
+)
+
+func main() {
+    // Parse your CIDR range
+    prefix, err := netip.ParsePrefix("192.0.2.0/24")
+    if err != nil {
+        panic(err)
+    }
+
+    // Create a RandomIPDialer for the subnet
+    dialer, err := stargate.NewRandomIPIterator(prefix, 32)
+    if err != nil {
+        panic(err)
+    }
+
+    // Create an HTTP client that uses random source IPs
+    client := &http.Client{
+        Transport: &http.Transport{
+            DialContext: dialer.Dial,
+        },
+        Timeout: 10 * time.Second,
+    }
+
+    // Make requests - each will use a different random IP
+    for i := 0; i < 5; i++ {
+        resp, err := client.Get("https://httpbin.org/ip")
+        if err != nil {
+            fmt.Printf("Request %d failed: %v\n", i+1, err)
+            continue
+        }
+        resp.Body.Close()
+        fmt.Printf("Request %d: Status %d\n", i+1, resp.StatusCode)
+    }
+}
+```
+
+You can also get the next random IP and DialFunc separately:
+
+```go
+// Get next random IP and dialer function
+ip, dialFunc, err := dialer.NextDial()
+if err != nil {
+    panic(err)
+}
+
+fmt.Printf("Next egress IP will be: %s\n", ip)
+
+// Use the dial function directly
+conn, err := dialFunc(context.Background(), "tcp", "example.com:80")
+if err != nil {
+    panic(err)
+}
+defer conn.Close()
+```

Makefile

@@ -1,4 +1,4 @@
-package main
+package stargate
 
 import (
 	"fmt"
@@ -7,21 +7,23 @@ import (
 )
 
 // broadcastAddrs is a global map that tracks IP addresses identified as broadcast addresses.
-// It is populated by checkHostConflicts and used to prevent binding to these addresses.
+// It is populated by CheckHostConflicts and used to prevent binding to these addresses.
 var broadcastAddrs = make(map[string]bool)
 
-// checkHostConflicts detects if any of the addresses we are going to use are broadcast addresses.
+// CheckHostConflicts detects if any of the addresses we are going to use are broadcast addresses.
 // It populates the global broadcastAddrs map by examining all system network interfaces.
-func checkHostConflicts(prefix *netip.Prefix) error {
+// It returns a list of all conflicting IPs
+func CheckHostConflicts(prefix *netip.Prefix) ([]net.IP, error) {
 	interfaces, err := net.Interfaces()
 	if err != nil {
-		return err
+		return nil, err
 	}
 
+	conflictIPs := make([]net.IP, 0)
 	for _, i := range interfaces {
 		addrs, err := i.Addrs()
 		if err != nil {
-			return err
+			return nil, err
 		}
 		for _, a := range addrs {
 			ipnet, ok := a.(*net.IPNet)
@@ -34,20 +36,21 @@ func checkHostConflicts(prefix *netip.Prefix) error {
 			}
 			brdIP, err := getBroadcastAddressFromAddr(ipnet)
 			if err != nil {
-				return err
+				return nil, err
 			}
 			brdAddr, ok := netip.AddrFromSlice(brdIP)
 			if !ok {
-				return fmt.Errorf("unable to parse IP to addr: %+v", brdAddr)
+				return nil, fmt.Errorf("unable to parse IP to addr: %+v", brdAddr)
 			}
 			if prefix.Contains(brdAddr) {
 				broadcastAddrs[brdAddr.String()] = true
-				l.Printf("WARNING: interface %s broadcast address is within provided prefix %s", i.Name, brdIP)
+				v("WARNING: interface %s broadcast address is within provided prefix %s", i.Name, brdIP)
+				conflictIPs = append(conflictIPs, brdIP)
 			}
 		}
 	}
 
-	return nil
+	return conflictIPs, nil
 }
 
 // getBroadcastAddressFromAddr calculates the broadcast address from a net.IPNet.

README.md

@@ -12,6 +12,7 @@ import (
 	"strings"
 
 	"github.com/haxii/socks5"
+	"github.com/lanrat/stargate"
 )
 
 // Command-line flags
@@ -83,18 +84,25 @@ func main() {
 	// more could be supported by switching from uint64 to big.Int types.
 	// for even with IPv6, using more than 2^64 networks is incredibly unlikely
 	// if someone dares to do this, error
-	totalNetworks := *subnetBits - uint(cidrBits)
-	if totalNetworks > 64 {
-		log.Fatalf("subnet host range too large. Can't run on over 2^64 networks, got 2^%d", totalNetworks)
+	totalNetworksBits := *subnetBits - uint(cidrBits)
+	if totalNetworksBits > 64 {
+		l.Fatalf("subnet host range too large. Can't run on over 2^64 networks, got 2^%d", totalNetworksBits)
 	}
 
+	// set stargate Logger
+	stargate.Logger = v
+
 	// check for IP conflicts
-	err = checkHostConflicts(&parsedNetwork)
+	conflicts, err := stargate.CheckHostConflicts(&parsedNetwork)
 	if err != nil {
 		l.Fatal(err)
 	}
+	for _, ip := range conflicts {
+		l.Printf("Warning: possible IP conflict on %s", ip)
+	}
 
 	hostsPerNetwork := 1 << (maxNetworkBits - *subnetBits)
+	totalNetworks := 1 << totalNetworksBits
 	l.Printf("Running with subnet size /%d and /%d prefix resulting in %d egress networks and %d options per network", *subnetBits, cidrBits, totalNetworks, hostsPerNetwork)
 
 	// test mode
@@ -128,7 +136,7 @@ func main() {
 }
 
 // v logs a message if verbose logging is enabled.
-func v(format string, a ...interface{}) {
+func v(format string, a ...any) {
 	if *verbose {
 		l.Printf(format, a...)
 	}

addresses.go broadcast_addresses.goaddresses.go renamed to broadcast_addresses.go

@@ -4,6 +4,7 @@ import (
 	"net/netip"
 
 	"github.com/haxii/socks5"
+	"github.com/lanrat/stargate"
 )
 
 // runRandomSubnetProxy starts a SOCKS5 proxy server listening on listenAddr that distributes
@@ -12,7 +13,7 @@ import (
 // This is memory efficient for large IPv6 ranges as it doesn't pre-generate all addresses.
 // The function cycles through all available subnets before repeating.
 func runRandomSubnetProxy(listenAddr string, parsedNetwork netip.Prefix, cidrSize uint) error {
-	ipItr, err := NewRandomIPIterator(parsedNetwork, cidrSize)
+	ipItr, err := stargate.NewRandomIPIterator(parsedNetwork, cidrSize)
 	if err != nil {
 		return err
 	}

main.go cmd/main.gomain.go renamed to cmd/main.go

@@ -12,6 +12,7 @@ import (
 	"sync/atomic"
 	"time"
 
+	"github.com/lanrat/stargate"
 	"golang.org/x/sync/errgroup"
 )
 
@@ -27,15 +28,15 @@ const (
 // testDial represents a test configuration pairing an IP address with its corresponding dialer function.
 type testDial struct {
 	ip   net.IP
-	dial DialFunc
+	dial stargate.DialFunc
 }
 
 // test validates that all IP addresses in the given CIDR range can successfully
 // make HTTP requests and receive the expected source IP in the response.
 // It uses cloudflare.com/cdn-cgi/trace to verify the egress IP address.
 func test(ctx context.Context, parsedNetwork netip.Prefix, cidrSize uint) error {
 	// Create iterator for all host indices
-	ipItr, err := NewRandomIPIterator(parsedNetwork, cidrSize)
+	ipItr, err := stargate.NewRandomIPIterator(parsedNetwork, cidrSize)
 	if err != nil {
 		return err
 	}
@@ -144,7 +145,7 @@ func test(ctx context.Context, parsedNetwork netip.Prefix, cidrSize uint) error
 
 // testWithDialer performs an HTTP request using the provided dialer and verifies
 // that the egress IP matches the expected IP address by querying cloudflare.com/cdn-cgi/trace.
-func testWithDialer(ctx context.Context, dial DialFunc, expectedIP net.IP) error {
+func testWithDialer(ctx context.Context, dial stargate.DialFunc, expectedIP net.IP) error {
 	ctx, cancel := context.WithTimeout(ctx, testTimeout)
 	defer cancel()
 
@@ -161,7 +162,7 @@ func testWithDialer(ctx context.Context, dial DialFunc, expectedIP net.IP) error
 	resp, err := client.Do(req)
 	if err != nil {
 		// If bindError, then unwrap
-		var bindErr *IPBindError
+		var bindErr *stargate.IPBindError
 		if errors.As(err, &bindErr) {
 			return bindErr
 		}