Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: os random refuses a linux-only browser while listing it as an available pair (PIN-149)

Luigi Agostidc823774e1e2
diff --git a/internal/handlers/stealth.go b/internal/handlers/stealth.go
index 504b0931..b0aa8556 100644
--- a/internal/handlers/stealth.go
+++ b/internal/handlers/stealth.go
@@ -170,8 +170,10 @@ func (h *Handlers) fingerprintMatrix() map[string]map[string]fingerprint {
},
},
// A Linux host asking for a fingerprint used to get a foreign one, since only
- // windows and mac had entries. os: "random" stays windows-or-mac: adding linux
- // to the weighted pick would change what a default request returns.
+ // windows and mac had entries. linux stays out of the os: "random" WEIGHTING —
+ // adding it there would change what a default request returns — but it is a
+ // fallback candidate for any browser no weighted row holds, so a browser only
+ // this row carries is reachable through os: "random" rather than refused.
"linux": {
"chrome": {
UserAgent: linuxChrome,
@@ -197,39 +199,85 @@ func availableFingerprintPairs(matrix map[string]map[string]fingerprint) []strin
return pairs
}
-// randomFingerprintOSWeights is the weighted pick behind os: "random". linux is
-// absent on purpose: adding it would change what a default request returns.
-var randomFingerprintOSWeights = []struct {
+// weightedFingerprintOS is one candidate of the os: "random" draw.
+type weightedFingerprintOS struct {
name string
weight float64
-}{
+}
+
+// randomFingerprintOSWeights is the weighting behind os: "random". linux is absent
+// on purpose: adding it here would change what a default request returns. Absent
+// from the WEIGHTING is not absent from the draw — fingerprintOSCandidates falls
+// back to the unweighted rows when no weighted one holds the requested browser.
+var randomFingerprintOSWeights = []weightedFingerprintOS{
{name: "windows", weight: 0.7},
{name: "mac", weight: 0.3},
}
-// resolveRandomFingerprintOS picks among the weighted os rows that actually hold
-// the requested browser, re-weighting over those candidates. Picking an os first
-// and looking the pair up second made os: "random" answer 200 or 400 by coin flip
-// for browsers only one os holds — safari refused whenever the pick was windows.
-// It reports no candidate when no weighted row holds the browser at all, which is
-// still a refusal: the constraint narrows the pick, it does not remove the refusal.
-func resolveRandomFingerprintOS(matrix map[string]map[string]fingerprint, browser string) (string, bool) {
- total := 0.0
+// fingerprintOSCandidates is the set os: "random" draws from for one browser: the
+// weighted rows that hold it, or — only when none does — every other row that
+// holds it, uniformly.
+//
+// The fallback is what makes "random" mean any os that can answer rather than any
+// WEIGHTED os that can answer. Without it a browser held only by an unweighted row
+// is refused while the refusal lists that very pair as available, which is the
+// same coin-flip defect the browser constraint fixed, one layer along: the caller
+// delegated the os choice, named a browser the product has, and would have to know
+// to retry with an explicit os.
+//
+// It cannot move the default: the fallback is reached only when no weighted row
+// holds the browser, and chrome is held by windows and mac, so a default request
+// never sees an unweighted candidate and keeps its 0.7/0.3 split. The unweighted
+// candidates are sorted and equally weighted, so several of them cannot make the
+// pick depend on map iteration order.
+func fingerprintOSCandidates(matrix map[string]map[string]fingerprint, browser string) []weightedFingerprintOS {
+ candidates := make([]weightedFingerprintOS, 0, len(matrix))
+ weighted := make(map[string]bool, len(randomFingerprintOSWeights))
for _, candidate := range randomFingerprintOSWeights {
+ weighted[candidate.name] = true
if _, ok := matrix[candidate.name][browser]; ok {
- total += candidate.weight
+ candidates = append(candidates, candidate)
}
}
- if total == 0 {
- return "", false
+ if len(candidates) > 0 {
+ return candidates
}
- draw := rand.Float64() * total
- picked := ""
- for _, candidate := range randomFingerprintOSWeights {
- if _, ok := matrix[candidate.name][browser]; !ok {
+ names := make([]string, 0, len(matrix))
+ for osName, browsers := range matrix {
+ if weighted[osName] {
continue
}
+ if _, ok := browsers[browser]; ok {
+ names = append(names, osName)
+ }
+ }
+ sort.Strings(names)
+ for _, name := range names {
+ candidates = append(candidates, weightedFingerprintOS{name: name, weight: 1})
+ }
+ return candidates
+}
+
+// resolveRandomFingerprintOS runs one weighted draw over the candidates that hold
+// the requested browser. Picking an os first and looking the pair up second made
+// os: "random" answer 200 or 400 by coin flip for browsers only one os holds —
+// safari refused whenever the pick was windows. It reports no candidate only when
+// NO row holds the browser, which is still a refusal, and which is what makes the
+// full matrix listing in that refusal both correct and actionable.
+func resolveRandomFingerprintOS(matrix map[string]map[string]fingerprint, browser string) (string, bool) {
+ candidates := fingerprintOSCandidates(matrix, browser)
+ if len(candidates) == 0 {
+ return "", false
+ }
+
+ total := 0.0
+ for _, candidate := range candidates {
+ total += candidate.weight
+ }
+ draw := rand.Float64() * total
+ picked := candidates[0].name
+ for _, candidate := range candidates {
picked = candidate.name
draw -= candidate.weight
if draw < 0 {
diff --git a/internal/handlers/stealth_test.go b/internal/handlers/stealth_test.go
index aefcb76f..59e2a52e 100644
--- a/internal/handlers/stealth_test.go
+++ b/internal/handlers/stealth_test.go
@@ -5,6 +5,7 @@ import (
"context"
"encoding/json"
"net/http/httptest"
+ "reflect"
"sort"
"strings"
"testing"
@@ -310,8 +311,11 @@ func TestGenerateFingerprintAgreesWithTheLaunchPersonaOnThisHost(t *testing.T) {
}
}
-// os: "linux" is answerable now; os: "random" is deliberately NOT extended to it,
-// because that would change what a default request returns. This states which.
+// os: "random" keeps its windows/mac weighting for every browser a weighted row
+// holds — which is every browser the shipped matrix has outside linux/chrome — so
+// the default request is untouched. linux is a candidate only when nothing weighted
+// holds the requested browser, and chrome is held by both weighted rows, so this
+// drives the real matrix and must never see the Linux UA.
func TestGenerateFingerprintRandomStaysWindowsOrMac(t *testing.T) {
h := Handlers{Config: &config.RuntimeConfig{BrowserVersion: "144.0.7559.133"}}
linuxUA := stealth.ChromeUserAgent(stealth.PlatformLinux, stealth.ReducedBrowserVersion("144.0.7559.133"))
@@ -634,3 +638,174 @@ func TestHandleFingerprintRotateStillAcceptsAListedPair(t *testing.T) {
t.Error("a rotated fingerprint carries an empty userAgent")
}
}
+
+// probeMatrix is the real matrix plus one browser held only by unweighted rows —
+// the state no shipped matrix reaches yet, and the one the weighted-only draw got
+// wrong. fingerprintMatrix returns a fresh literal per call, so mutating the copy
+// cannot leak into another test.
+func probeMatrix(t *testing.T, h *Handlers, browser string, osNames ...string) map[string]map[string]fingerprint {
+ t.Helper()
+ matrix := h.fingerprintMatrix()
+ for _, osName := range osNames {
+ for _, weighted := range randomFingerprintOSWeights {
+ if osName == weighted.name {
+ t.Fatalf("probe os %q is in randomFingerprintOSWeights, so it cannot stand in for an unweighted row", osName)
+ }
+ }
+ if matrix[osName] == nil {
+ matrix[osName] = map[string]fingerprint{}
+ }
+ matrix[osName][browser] = fingerprint{UserAgent: "probe-" + osName + "-" + browser}
+ }
+ for _, weighted := range randomFingerprintOSWeights {
+ if _, ok := matrix[weighted.name][browser]; ok {
+ t.Fatalf("probe browser %q is held by the weighted row %q, so the fallback under test is never reached", browser, weighted.name)
+ }
+ }
+ return matrix
+}
+
+// The gap this card closes: a browser held only by an unweighted row was refused
+// under os: "random" while the refusal listed that very pair as available. The
+// caller delegated the os choice and named a browser the product has, so a refusal
+// tells them nothing they can act on. Asserted on every draw, because the defect it
+// replaces was a coin flip rather than a constant.
+func TestRandomOSResolvesABrowserOnlyAnUnweightedRowHolds(t *testing.T) {
+ h := Handlers{Config: &config.RuntimeConfig{BrowserVersion: "144.0.7559.133"}}
+ matrix := probeMatrix(t, &h, "firefox", "linux")
+
+ for i := 0; i < 200; i++ {
+ picked, ok := resolveRandomFingerprintOS(matrix, "firefox")
+ if !ok {
+ t.Fatalf("draw %d: os=random refused firefox although linux/firefox exists; the refusal would list a pair the caller cannot reach", i)
+ }
+ if picked != "linux" {
+ t.Fatalf("draw %d: os=random resolved to %q, want linux — the only row holding firefox", i, picked)
+ }
+ }
+}
+
+// With several unweighted rows holding the browser, the pick must be uniform and
+// must not depend on map iteration order — a silently order-dependent fallback is
+// the next defect of this shape.
+func TestRandomOSFallbackPicksUniformlyAmongUnweightedRows(t *testing.T) {
+ h := Handlers{Config: &config.RuntimeConfig{BrowserVersion: "144.0.7559.133"}}
+ matrix := probeMatrix(t, &h, "firefox", "linux", "freebsd")
+
+ const draws = 1200
+ seen := map[string]int{}
+ for i := 0; i < draws; i++ {
+ picked, ok := resolveRandomFingerprintOS(matrix, "firefox")
+ if !ok {
+ t.Fatalf("draw %d: firefox refused although two rows hold it", i)
+ }
+ seen[picked]++
+ }
+ for _, want := range []string{"linux", "freebsd"} {
+ if seen[want] == 0 {
+ t.Fatalf("%q never drawn in %d draws (%v); the fallback picks one row rather than among them", want, draws, seen)
+ }
+ // A wide band: this pins uniform-ish against first-wins or order-dependent,
+ // not the RNG's quality.
+ if share := float64(seen[want]) / draws; share < 0.35 || share > 0.65 {
+ t.Errorf("%q drawn %.0f%% of %d draws (%v), want roughly half each", want, share*100, draws, seen)
+ }
+ }
+}
+
+// The fallback is reached ONLY when no weighted row holds the browser. This is what
+// keeps the 0.7/0.3 split and the default request untouched, and it is the half a
+// widening change is most likely to overshoot: chrome is held by weighted rows, so
+// an unweighted row holding it too must never be drawn.
+func TestRandomOSIgnoresUnweightedRowsWhenAWeightedRowHoldsTheBrowser(t *testing.T) {
+ h := Handlers{Config: &config.RuntimeConfig{BrowserVersion: "144.0.7559.133"}}
+ matrix := h.fingerprintMatrix()
+ matrix["linux"]["edge"] = fingerprint{UserAgent: "probe-linux-edge"}
+
+ for i := 0; i < 400; i++ {
+ for _, browser := range []string{"chrome", "edge"} {
+ picked, ok := resolveRandomFingerprintOS(matrix, browser)
+ if !ok {
+ t.Fatalf("draw %d: %s refused", i, browser)
+ }
+ if picked == "linux" {
+ t.Fatalf("draw %d: os=random browser=%s resolved to linux, which is unweighted; the weighted rows hold it, so the fallback must not be reached", i, browser)
+ }
+ }
+ }
+}
+
+// The candidate list is what the draw runs over, and it must not vary with map
+// iteration order: same matrix, same list, every time. Built repeatedly because Go
+// randomises range order per loop, so a single call cannot tell a sorted list from
+// a lucky one.
+func TestFingerprintOSCandidatesAreStableAndEquallyWeightedInTheFallback(t *testing.T) {
+ h := Handlers{Config: &config.RuntimeConfig{BrowserVersion: "144.0.7559.133"}}
+ matrix := probeMatrix(t, &h, "firefox", "linux", "freebsd", "openbsd")
+ want := []string{"freebsd", "linux", "openbsd"}
+
+ for i := 0; i < 50; i++ {
+ candidates := fingerprintOSCandidates(matrix, "firefox")
+ got := make([]string, 0, len(candidates))
+ for _, candidate := range candidates {
+ got = append(got, candidate.name)
+ if candidate.weight != 1 {
+ t.Fatalf("fallback candidate %q carries weight %v, want 1 — the fallback is uniform, and a weight here is a second place the 0.7/0.3 split could be edited", candidate.name, candidate.weight)
+ }
+ }
+ if !reflect.DeepEqual(got, want) {
+ t.Fatalf("build %d: candidates = %v, want %v every time; the order follows map iteration, so the pick is not reproducible", i, got, want)
+ }
+ }
+
+ // The weighted arm keeps its own weights and is not sorted into the fallback's shape.
+ for _, candidate := range fingerprintOSCandidates(matrix, "chrome") {
+ if candidate.weight == 1 {
+ t.Errorf("weighted candidate %q lost its weight (%v); chrome must keep the 0.7/0.3 split", candidate.name, candidate.weight)
+ }
+ }
+}
+
+// What makes the refusal's full-matrix listing honest after the widening: os:
+// "random" refuses only a browser NO row holds, so a refusal never names a pair the
+// caller could have had. Derived from the matrix rather than from a hand-picked
+// pair or two, so the next row added is covered without editing this test — which
+// is the case this card exists for.
+func TestEveryBrowserTheMatrixHoldsIsReachableThroughRandom(t *testing.T) {
+ h := Handlers{Config: &config.RuntimeConfig{BrowserVersion: "144.0.7559.133"}}
+ matrix := h.fingerprintMatrix()
+
+ holders := map[string][]string{}
+ for osName, row := range matrix {
+ for browser := range row {
+ holders[browser] = append(holders[browser], osName)
+ }
+ }
+ browsers := map[string]bool{}
+ for browser, rows := range holders {
+ sort.Strings(rows)
+ holders[browser] = rows
+ browsers[browser] = true
+ }
+ if len(browsers) == 0 {
+ t.Fatal("the matrix holds no browsers, so this guard would pass vacuously")
+ }
+
+ for browser := range browsers {
+ t.Run(browser, func(t *testing.T) {
+ for i := 0; i < 100; i++ {
+ if _, ok := resolveRandomFingerprintOS(matrix, browser); !ok {
+ t.Fatalf("draw %d: os=random refused %q although %v hold it; the refusal would list those pairs as available while refusing the browser in them",
+ i, browser, holders[browser])
+ }
+ fp, err := h.generateFingerprint(fingerprintRequest{OS: "random", Browser: browser})
+ if err != nil {
+ t.Fatalf("draw %d: os=random browser=%s refused end to end: %v", i, browser, err)
+ }
+ if fp.UserAgent == "" {
+ t.Fatalf("draw %d: os=random browser=%s resolved to an empty identity", i, browser)
+ }
+ }
+ })
+ }
+}