Skip to content

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

refactor: browsersession holds its one mutex across the session-file write, where session.Store deliberately does not (PIN-133)

Luigi Agostidd7d36ebec6a
diff --git a/internal/browsersession/session.go b/internal/browsersession/session.go
index d6f9cef6..882d48d7 100644
--- a/internal/browsersession/session.go
+++ b/internal/browsersession/session.go
@@ -31,7 +31,7 @@ type Config struct {
}
type Manager struct {
- mu sync.Mutex
+ mu sync.RWMutex
sessions map[string]sessionState
idleTimeout time.Duration
maxLifetime time.Duration
@@ -41,6 +41,31 @@ type Manager struct {
persistElevationAcrossRestart bool
now func() time.Time
lastTouchSave time.Time // last LastSeen-only flush (debounce gate)
+
+ // A snapshot is built under mu and stamped with a monotonic saveSeq, then
+ // marshalled + written under saveMu so session traffic is never serialized
+ // behind disk I/O. writtenSeq (guarded by saveMu) lets a writer skip a
+ // snapshot older than one already on disk.
+ saveMu sync.Mutex
+ saveSeq uint64 // guarded by mu
+ writtenSeq uint64 // guarded by saveMu
+
+ beforeWrite func() // test seam: runs inside writeSnapshot, before the syscalls
+}
+
+// saveJob is a self-contained snapshot built under mu and written outside it. A
+// zero path means there is nothing to write.
+type saveJob struct {
+ snapshot persistedSessions
+ seq uint64
+ path string
+}
+
+// authRequest is the lock-free prelude of a session lookup.
+type authRequest struct {
+ id string
+ now time.Time
+ expected [32]byte
}
type sessionState struct {
@@ -90,63 +115,97 @@ func (m *Manager) Create(token string) (string, error) {
LastSeen: now,
TokenHash: hashToken(token),
}
- m.saveLocked()
+ job := m.snapshotLocked()
m.mu.Unlock()
+ m.writeSnapshot(job)
return id, nil
}
-// withValidSession runs the shared auth prelude (trim/hash/lock/lookup/expiry,
-// deleting + persisting an invalid session) and, on success, invokes apply under
-// m.mu to mutate state and persist. Returns false on any validation failure.
-func (m *Manager) withValidSession(sessionID, token string, apply func(id string, now time.Time, state sessionState) bool) bool {
+func (m *Manager) newAuthRequest(sessionID, token string) (authRequest, bool) {
+ sessionID = strings.TrimSpace(sessionID)
+ if sessionID == "" {
+ return authRequest{}, false
+ }
+ return authRequest{id: sessionID, now: m.now(), expected: hashToken(token)}, true
+}
+
+// withValidSession runs the auth prelude under the write lock and, on success,
+// invokes apply to mutate state and return the snapshot to persist. An invalid
+// session is deleted and persisted. Every write happens after m.mu is released.
+func (m *Manager) withValidSession(sessionID, token string, apply func(req authRequest, state sessionState) (saveJob, bool)) bool {
if m == nil {
return false
}
- sessionID = strings.TrimSpace(sessionID)
- if sessionID == "" {
+ req, ok := m.newAuthRequest(sessionID, token)
+ if !ok {
return false
}
- now := m.now()
- expected := hashToken(token)
-
m.mu.Lock()
- defer m.mu.Unlock()
+ state, found := m.sessions[req.id]
+ var job saveJob
+ var result bool
+ switch {
+ case !found:
+ case m.sessionValid(state, req.now, req.expected):
+ job, result = apply(req, state)
+ default:
+ delete(m.sessions, req.id)
+ job = m.snapshotLocked()
+ }
+ m.mu.Unlock()
+
+ m.writeSnapshot(job)
+ return result
+}
- state, ok := m.sessions[sessionID]
+// withValidSessionRead answers a read-only question under the read lock. An
+// invalid session escalates to withValidSession, which owns the delete.
+func (m *Manager) withValidSessionRead(sessionID, token string, read func(req authRequest, state sessionState) bool) bool {
+ if m == nil {
+ return false
+ }
+ req, ok := m.newAuthRequest(sessionID, token)
if !ok {
return false
}
- if !m.sessionValid(state, now, expected) {
- delete(m.sessions, sessionID)
- m.saveLocked()
+
+ m.mu.RLock()
+ state, found := m.sessions[req.id]
+ valid := found && m.sessionValid(state, req.now, req.expected)
+ m.mu.RUnlock()
+
+ if valid {
+ return read(req, state)
+ }
+ if !found {
return false
}
- return apply(sessionID, now, state)
+ return m.withValidSession(sessionID, token, func(authRequest, sessionState) (saveJob, bool) {
+ return saveJob{}, false
+ })
}
func (m *Manager) Validate(sessionID, token string) bool {
- return m.withValidSession(sessionID, token, func(id string, now time.Time, state sessionState) bool {
- state.LastSeen = now
- m.sessions[id] = state
- m.saveTouchLocked(now)
- return true
+ return m.withValidSession(sessionID, token, func(req authRequest, state sessionState) (saveJob, bool) {
+ state.LastSeen = req.now
+ m.sessions[req.id] = state
+ return m.snapshotTouchLocked(req.now), true
})
}
func (m *Manager) Elevate(sessionID, token string) bool {
- return m.withValidSession(sessionID, token, func(id string, now time.Time, state sessionState) bool {
- state.LastSeen = now
- state.ElevatedUntil = now.Add(m.elevationWindow)
- m.sessions[id] = state
- m.saveLocked()
- return true
+ return m.withValidSession(sessionID, token, func(req authRequest, state sessionState) (saveJob, bool) {
+ state.LastSeen = req.now
+ state.ElevatedUntil = req.now.Add(m.elevationWindow)
+ m.sessions[req.id] = state
+ return m.snapshotLocked(), true
})
}
func (m *Manager) IsElevated(sessionID, token string) bool {
- return m.withValidSession(sessionID, token, func(id string, now time.Time, state sessionState) bool {
- return !state.ElevatedUntil.IsZero() && !now.After(state.ElevatedUntil)
+ return m.withValidSessionRead(sessionID, token, func(req authRequest, state sessionState) bool {
+ return !state.ElevatedUntil.IsZero() && !req.now.After(state.ElevatedUntil)
})
}
@@ -160,16 +219,17 @@ func (m *Manager) Revoke(sessionID string) {
}
m.mu.Lock()
delete(m.sessions, sessionID)
- m.saveLocked()
+ job := m.snapshotLocked()
m.mu.Unlock()
+ m.writeSnapshot(job)
}
func (m *Manager) MaxLifetime() time.Duration {
if m == nil {
return DefaultSessionMaxLifetime
}
- m.mu.Lock()
- defer m.mu.Unlock()
+ m.mu.RLock()
+ defer m.mu.RUnlock()
return m.maxLifetime
}
@@ -177,8 +237,8 @@ func (m *Manager) IdleTimeout() time.Duration {
if m == nil {
return DefaultSessionIdleTimeout
}
- m.mu.Lock()
- defer m.mu.Unlock()
+ m.mu.RLock()
+ defer m.mu.RUnlock()
return m.idleTimeout
}
@@ -186,8 +246,8 @@ func (m *Manager) ElevationWindow() time.Duration {
if m == nil {
return DefaultSessionElevationWindow
}
- m.mu.Lock()
- defer m.mu.Unlock()
+ m.mu.RLock()
+ defer m.mu.RUnlock()
return m.elevationWindow
}
@@ -201,9 +261,10 @@ func (m *Manager) UpdateConfig(cfg Config) {
oldPersist := m.persist
m.applyConfigLocked(cfg)
m.pruneExpiredLocked(m.now())
- m.saveLocked()
+ job := m.snapshotLocked()
persist, persistPath := m.persist, m.persistPath
m.mu.Unlock()
+ m.writeSnapshot(job)
if oldPersist && oldPath != "" && (!persist || oldPath != persistPath) {
_ = os.Remove(oldPath)
@@ -256,22 +317,24 @@ func (m *Manager) loadPersisted() {
return
}
- m.mu.Lock()
- defer m.mu.Unlock()
-
- if !m.persist || m.persistPath == "" {
+ m.mu.RLock()
+ persist, persistPath := m.persist, m.persistPath
+ m.mu.RUnlock()
+ if !persist || persistPath == "" {
return
}
- data, err := os.ReadFile(m.persistPath)
+ data, err := os.ReadFile(persistPath)
if err != nil {
return
}
+
var persisted persistedSessions
if err := json.Unmarshal(data, &persisted); err != nil {
return
}
+ m.mu.Lock()
now := m.now()
loaded := make(map[string]sessionState, len(persisted.Sessions))
for _, record := range persisted.Sessions {
@@ -301,23 +364,27 @@ func (m *Manager) loadPersisted() {
loaded[recordID] = state
}
m.sessions = loaded
- m.saveLocked()
+ job := m.snapshotLocked()
+ m.mu.Unlock()
+ m.writeSnapshot(job)
}
-// saveTouchLocked persists a LastSeen-only update at most once per
-// touchPersistInterval. Caller holds m.mu. The next real mutation's saveLocked()
+// snapshotTouchLocked snapshots a LastSeen-only update at most once per
+// touchPersistInterval. Caller holds m.mu. The next real mutation's snapshot
// opportunistically flushes any debounced LastSeen for all sessions.
-func (m *Manager) saveTouchLocked(now time.Time) {
+func (m *Manager) snapshotTouchLocked(now time.Time) saveJob {
if now.Sub(m.lastTouchSave) < touchPersistInterval {
- return
+ return saveJob{}
}
m.lastTouchSave = now
- m.saveLocked()
+ return m.snapshotLocked()
}
-func (m *Manager) saveLocked() {
+// snapshotLocked captures the session map plus every config field the writer
+// needs, stamped with a monotonic sequence. Caller holds m.mu.
+func (m *Manager) snapshotLocked() saveJob {
if !m.persist || m.persistPath == "" {
- return
+ return saveJob{}
}
snapshot := persistedSessions{
@@ -338,20 +405,43 @@ func (m *Manager) saveLocked() {
snapshot.Sessions = append(snapshot.Sessions, record)
}
- data, err := json.MarshalIndent(snapshot, "", " ")
+ m.saveSeq++
+ return saveJob{snapshot: snapshot, seq: m.saveSeq, path: m.persistPath}
+}
+
+// writeSnapshot marshals and atomically writes a snapshot with m.mu released.
+// Writers serialize on saveMu; a snapshot older than one already written is
+// skipped so a stale snapshot can never clobber a fresher one.
+func (m *Manager) writeSnapshot(job saveJob) {
+ if job.path == "" {
+ return
+ }
+
+ m.saveMu.Lock()
+ defer m.saveMu.Unlock()
+ if job.seq <= m.writtenSeq {
+ return
+ }
+ m.writtenSeq = job.seq
+
+ if m.beforeWrite != nil {
+ m.beforeWrite()
+ }
+
+ data, err := json.MarshalIndent(job.snapshot, "", " ")
if err != nil {
return
}
- if err := os.MkdirAll(filepath.Dir(m.persistPath), 0755); err != nil {
+ if err := os.MkdirAll(filepath.Dir(job.path), 0755); err != nil {
return
}
// Atomic write: a torn file here fails to unmarshal on the next start and
// silently logs every dashboard user out.
- tmpPath := m.persistPath + ".tmp"
+ tmpPath := job.path + ".tmp"
if err := os.WriteFile(tmpPath, data, 0600); err != nil {
return
}
- if err := os.Rename(tmpPath, m.persistPath); err != nil {
+ if err := os.Rename(tmpPath, job.path); err != nil {
_ = os.Remove(tmpPath)
}
}
diff --git a/internal/browsersession/session_race_test.go b/internal/browsersession/session_race_test.go
index b16e4acd..4f8533ec 100644
--- a/internal/browsersession/session_race_test.go
+++ b/internal/browsersession/session_race_test.go
@@ -1,6 +1,7 @@
package browsersession
import (
+ "fmt"
"os"
"path/filepath"
"sync"
@@ -36,6 +37,56 @@ func TestDurationAccessorsAreSynchronized(t *testing.T) {
wg.Wait()
}
+// The writer runs outside the state lock, so every config field it needs must
+// be captured in the snapshot rather than read while UpdateConfig is in flight.
+func TestPersistConfigCapturedUnderStateLock(t *testing.T) {
+ dir := t.TempDir()
+ mgr := NewManager(Config{
+ IdleTimeout: time.Hour,
+ MaxLifetime: time.Hour,
+ ElevationWindow: time.Minute,
+ Persist: true,
+ PersistPath: filepath.Join(dir, "sessions-a.json"),
+ })
+
+ sessionID, err := mgr.Create("secret")
+ if err != nil {
+ t.Fatalf("Create: %v", err)
+ }
+
+ var wg sync.WaitGroup
+ wg.Add(3)
+ go func() {
+ defer wg.Done()
+ for i := 0; i < 200; i++ {
+ mgr.UpdateConfig(Config{
+ IdleTimeout: time.Hour,
+ MaxLifetime: time.Hour,
+ ElevationWindow: time.Duration(i+1) * time.Second,
+ Persist: true,
+ PersistPath: filepath.Join(dir, fmt.Sprintf("sessions-%d.json", i%3)),
+ PersistElevationAcrossRestart: i%2 == 0,
+ })
+ }
+ }()
+ go func() {
+ defer wg.Done()
+ for i := 0; i < 200; i++ {
+ mgr.Elevate(sessionID, "secret")
+ }
+ }()
+ go func() {
+ defer wg.Done()
+ for i := 0; i < 200; i++ {
+ if _, err := mgr.Create("secret"); err != nil {
+ t.Errorf("Create: %v", err)
+ return
+ }
+ }
+ }()
+ wg.Wait()
+}
+
// The persist file is written via a temp file + rename; the temp must never
// survive a successful save.
func TestPersistLeavesNoTempFile(t *testing.T) {
diff --git a/internal/browsersession/session_test.go b/internal/browsersession/session_test.go
index dfe81050..f3e357fc 100644
--- a/internal/browsersession/session_test.go
+++ b/internal/browsersession/session_test.go
@@ -2,12 +2,86 @@ package browsersession
import (
"encoding/json"
+ "fmt"
"os"
"path/filepath"
"testing"
"time"
)
+func benchManager(b *testing.B, sessions int) (*Manager, []string) {
+ b.Helper()
+ mgr := NewManager(Config{
+ IdleTimeout: 365 * 24 * time.Hour,
+ MaxLifetime: 365 * 24 * time.Hour,
+ ElevationWindow: 15 * time.Minute,
+ Persist: true,
+ PersistPath: filepath.Join(b.TempDir(), "sessions.json"),
+ })
+ ids := make([]string, 0, sessions)
+ for i := 0; i < sessions; i++ {
+ id, err := mgr.Create("secret")
+ if err != nil {
+ b.Fatalf("Create: %v", err)
+ }
+ ids = append(ids, id)
+ }
+ return mgr, ids
+}
+
+func BenchmarkElevateWithPersist(b *testing.B) {
+ for _, sessions := range []int{1, 50, 500} {
+ b.Run(fmt.Sprintf("sessions=%d", sessions), func(b *testing.B) {
+ mgr, ids := benchManager(b, sessions)
+ b.ResetTimer()
+ for i := 0; i < b.N; i++ {
+ mgr.Elevate(ids[i%len(ids)], "secret")
+ }
+ })
+ }
+}
+
+// BenchmarkElevateStateLockWait reports how long an unrelated state-lock
+// acquisition waits while Elevate persists — the cost this card removes.
+func BenchmarkElevateStateLockWait(b *testing.B) {
+ for _, sessions := range []int{1, 50, 500} {
+ b.Run(fmt.Sprintf("sessions=%d", sessions), func(b *testing.B) {
+ mgr, ids := benchManager(b, sessions)
+ stop := make(chan struct{})
+ done := make(chan struct{})
+ go func() {
+ defer close(done)
+ for i := 0; ; i++ {
+ select {
+ case <-stop:
+ return
+ default:
+ }
+ mgr.Elevate(ids[i%len(ids)], "secret")
+ }
+ }()
+
+ var waited time.Duration
+ b.ResetTimer()
+ for i := 0; i < b.N; i++ {
+ time.Sleep(100 * time.Microsecond)
+ start := time.Now()
+ mgr.mu.Lock()
+ sessions := len(mgr.sessions)
+ mgr.mu.Unlock()
+ waited += time.Since(start)
+ if sessions == 0 {
+ b.Fatal("sessions drained")
+ }
+ }
+ b.StopTimer()
+ close(stop)
+ <-done
+ b.ReportMetric(float64(waited.Nanoseconds())/float64(b.N), "lockwait-ns/op")
+ })
+ }
+}
+
func TestIsElevatedPersistsExpiryDeletion(t *testing.T) {
path := filepath.Join(t.TempDir(), "sessions.json")
base := time.Date(2026, 3, 18, 12, 0, 0, 0, time.UTC)
@@ -115,6 +189,83 @@ func TestValidateDebouncesLastSeenPersistence(t *testing.T) {
}
}
+func TestPersistWritesWithStateLockReleased(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "sessions.json")
+ mgr := NewManager(Config{
+ IdleTimeout: time.Hour,
+ MaxLifetime: 24 * time.Hour,
+ ElevationWindow: time.Minute,
+ Persist: true,
+ PersistPath: path,
+ })
+
+ writes := 0
+ available := 0
+ mgr.beforeWrite = func() {
+ writes++
+ if mgr.mu.TryLock() {
+ available++
+ mgr.mu.Unlock()
+ }
+ }
+
+ sessionID, err := mgr.Create("secret")
+ if err != nil {
+ t.Fatalf("Create: %v", err)
+ }
+ if !mgr.Elevate(sessionID, "secret") {
+ t.Fatal("Elevate() = false, want true")
+ }
+ mgr.Revoke(sessionID)
+
+ if writes == 0 {
+ t.Fatal("no persist write observed")
+ }
+ if available != writes {
+ t.Errorf("state lock was held during %d of %d writes, want 0", writes-available, writes)
+ }
+}
+
+func TestWriteSnapshotDiscardsSupersededWrite(t *testing.T) {
+ path := filepath.Join(t.TempDir(), "sessions.json")
+ mgr := NewManager(Config{
+ IdleTimeout: time.Hour,
+ MaxLifetime: 24 * time.Hour,
+ Persist: true,
+ PersistPath: path,
+ })
+
+ first, err := mgr.Create("secret")
+ if err != nil {
+ t.Fatalf("Create: %v", err)
+ }
+ mgr.mu.Lock()
+ older := mgr.snapshotLocked()
+ second, err := randomSessionID()
+ if err != nil {
+ t.Fatalf("randomSessionID: %v", err)
+ }
+ mgr.sessions[second] = mgr.sessions[first]
+ newer := mgr.snapshotLocked()
+ mgr.mu.Unlock()
+
+ // The newer snapshot lands first; the in-flight older one must not regress it.
+ mgr.writeSnapshot(newer)
+ mgr.writeSnapshot(older)
+
+ data, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("read persist file: %v", err)
+ }
+ var ps persistedSessions
+ if err := json.Unmarshal(data, &ps); err != nil {
+ t.Fatalf("unmarshal: %v", err)
+ }
+ if len(ps.Sessions) != 2 {
+ t.Fatalf("persist file has %d sessions, want 2 — the older snapshot overwrote the newer", len(ps.Sessions))
+ }
+}
+
func TestSessionManagerValidateAndExpiry(t *testing.T) {
now := time.Date(2026, 3, 18, 12, 0, 0, 0, time.UTC)
mgr := NewManager(Config{