Add per-user connection throttling with fair-share algorithm

When total connections exceed a configurable limit, a background
goroutine (every 5s by default) computes per-user caps using a
fair-share algorithm: small users keep their connections, remaining
budget is split equally among heavy users. New connections from
over-cap users are rejected; existing connections are not killed.

Config:
  [throttle]
  max-connections = 5000
  check-interval = "5s"

Stats API response now includes throttle state with active caps.

internal/cli/run_proxy.go

@@ -271,6 +271,9 @@ func runProxy(conf *config.Config, version string) error { //nolint: funlen
 		DoppelGangerDRS:     conf.Defense.Doppelganger.DRS.Get(false),
 
 		APIBindTo: conf.APIBindTo.Get(""),
+
+		ThrottleMaxConnections: conf.Throttle.MaxConnections.Get(0),
+		ThrottleCheckInterval:  conf.Throttle.CheckInterval.Get(5 * time.Second),
 	}
 
 	proxy, err := mtglib.NewProxy(opts)

internal/config/config.go

@@ -70,7 +70,11 @@ type Config struct {
 		Proxies []TypeProxyURL `json:"proxies"`
 	} `json:"network"`
 	APIBindTo TypeHostPort `json:"apiBindTo"`
-	Stats     struct {
+	Throttle  struct {
+		MaxConnections TypeConcurrency `json:"maxConnections"`
+		CheckInterval  TypeDuration    `json:"checkInterval"`
+	} `json:"throttle"`
+	Stats struct {
 		StatsD struct {
 			Optional
 

internal/config/parse.go

@@ -65,7 +65,11 @@ type tomlConfig struct {
 		Proxies []string `toml:"proxies" json:"proxies,omitempty"`
 	} `toml:"network" json:"network,omitempty"`
 	APIBindTo string `toml:"api-bind-to" json:"apiBindTo,omitempty"`
-	Stats     struct {
+	Throttle  struct {
+		MaxConnections uint   `toml:"max-connections" json:"maxConnections,omitempty"`
+		CheckInterval  string `toml:"check-interval" json:"checkInterval,omitempty"`
+	} `toml:"throttle" json:"throttle,omitempty"`
+	Stats struct {
 		StatsD struct {
 			Enabled      bool   `toml:"enabled" json:"enabled,omitempty"`
 			Address      string `toml:"address" json:"address,omitempty"`

mtglib/events.go

@@ -93,6 +93,14 @@ type EventReplayAttack struct {
 	eventBase
 }
 
+// EventThrottled is emitted when a connection is rejected because the
+// per-user connection cap has been reached.
+type EventThrottled struct {
+	eventBase
+
+	SecretName string
+}
+
 // EventIPListSize is emitted when mtg updates a contents of the ip lists:
 // allowlist or blocklist.
 type EventIPListSize struct {
@@ -200,6 +208,17 @@ func NewEventReplayAttack(streamID string) EventReplayAttack {
 	}
 }
 
+// NewEventThrottled creates a new EventThrottled event.
+func NewEventThrottled(streamID, secretName string) EventThrottled {
+	return EventThrottled{
+		eventBase: eventBase{
+			timestamp: time.Now(),
+			streamID:  streamID,
+		},
+		SecretName: secretName,
+	}
+}
+
 // NewEventIPListSize creates a new EventIPListSize event.
 func NewEventIPListSize(size int, isBlockList bool) EventIPListSize {
 	return EventIPListSize{

mtglib/proxy.go

@@ -87,6 +87,13 @@ func (p *Proxy) ServeConn(conn essentials.Conn) {
 		return
 	}
 
+	if !p.stats.CanConnect(ctx.secretName) {
+		ctx.logger.Info("connection throttled")
+		p.eventStream.Send(ctx, NewEventThrottled(ctx.streamID, ctx.secretName))
+
+		return
+	}
+
 	p.stats.OnConnect(ctx.secretName)
 	p.stats.UpdateLastSeen(ctx.secretName)
 
@@ -381,6 +388,11 @@ func NewProxy(opts ProxyOpts) (*Proxy, error) {
 		stats.StartServer(ctx, opts.APIBindTo, logger)
 	}
 
+	if opts.ThrottleMaxConnections > 0 {
+		stats.SetThrottle(int64(opts.ThrottleMaxConnections), opts.getThrottleCheckInterval())
+		stats.startThrottleLoop(ctx, logger)
+	}
+
 	proxy := &Proxy{
 		ctx:                      ctx,
 		ctxCancel:                cancel,

mtglib/proxy_opts.go

@@ -175,6 +175,20 @@ type ProxyOpts struct {
 	//
 	// This is an optional setting.
 	APIBindTo string
+
+	// ThrottleMaxConnections is the total connection limit. When total
+	// connections exceed this value, per-user caps are computed using
+	// a fair-share algorithm and new connections from over-cap users
+	// are rejected. 0 disables throttling.
+	//
+	// This is an optional setting.
+	ThrottleMaxConnections uint
+
+	// ThrottleCheckInterval is how often the throttle recomputes per-user
+	// caps. Defaults to 5 seconds.
+	//
+	// This is an optional setting.
+	ThrottleCheckInterval time.Duration
 }
 
 func (p ProxyOpts) valid() error {
@@ -269,6 +283,14 @@ func (p ProxyOpts) getIdleTimeout() time.Duration {
 	return p.IdleTimeout
 }
 
+func (p ProxyOpts) getThrottleCheckInterval() time.Duration {
+	if p.ThrottleCheckInterval == 0 {
+		return 5 * time.Second //nolint: mnd
+	}
+
+	return p.ThrottleCheckInterval
+}
+
 func (p ProxyOpts) getLogger(name string) Logger {
 	return p.Logger.Named(name)
 }

mtglib/proxy_stats.go

@@ -3,6 +3,7 @@ package mtglib
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"net"
 	"net/http"
 	"sync"
@@ -23,6 +24,13 @@ type ProxyStats struct {
 	mu        sync.RWMutex
 	users     map[string]*secretStats
 	startedAt time.Time
+
+	// Throttle: per-user connection caps recomputed every throttleInterval.
+	throttleMu       sync.RWMutex
+	throttleCaps     map[string]int64
+	throttleLimit    int64
+	throttleInterval time.Duration
+	throttleActive   atomic.Bool
 }
 
 // NewProxyStats creates a new ProxyStats instance.
@@ -87,14 +95,140 @@ func (s *ProxyStats) UpdateLastSeen(name string) {
 	s.getOrCreate(name).lastSeen.Store(time.Now())
 }
 
+// SetThrottle configures connection throttling. Must be called before
+// startThrottleLoop and before any connections arrive.
+func (s *ProxyStats) SetThrottle(limit int64, interval time.Duration) {
+	s.throttleLimit = limit
+	s.throttleInterval = interval
+	s.throttleCaps = make(map[string]int64)
+}
+
+// CanConnect returns true if the user is allowed to open a new connection
+// under the current throttle caps. If throttling is not configured or the
+// user has no cap, it always returns true.
+func (s *ProxyStats) CanConnect(name string) bool {
+	if s.throttleLimit == 0 {
+		return true
+	}
+
+	s.throttleMu.RLock()
+	cap, hasCap := s.throttleCaps[name]
+	s.throttleMu.RUnlock()
+
+	if !hasCap {
+		return true
+	}
+
+	return s.getOrCreate(name).connections.Load() < cap
+}
+
+// startThrottleLoop runs a background goroutine that recomputes per-user
+// caps every throttleInterval.
+func (s *ProxyStats) startThrottleLoop(ctx context.Context, logger Logger) {
+	go func() {
+		ticker := time.NewTicker(s.throttleInterval)
+		defer ticker.Stop()
+
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-ticker.C:
+				s.recomputeCaps(logger)
+			}
+		}
+	}()
+
+	logger.BindStr("limit", fmt.Sprintf("%d", s.throttleLimit)).
+		BindStr("interval", s.throttleInterval.String()).
+		Info("throttle loop started")
+}
+
+func (s *ProxyStats) recomputeCaps(logger Logger) {
+	s.mu.RLock()
+	userConns := make(map[string]int64, len(s.users))
+	for name, st := range s.users {
+		userConns[name] = st.connections.Load()
+	}
+	s.mu.RUnlock()
+
+	caps := computeFairCaps(userConns, s.throttleLimit)
+	wasActive := s.throttleActive.Load()
+	nowActive := len(caps) > 0
+
+	s.throttleMu.Lock()
+	s.throttleCaps = caps
+	s.throttleActive.Store(nowActive)
+	s.throttleMu.Unlock()
+
+	if nowActive && !wasActive {
+		logger.Warning("throttle activated")
+	} else if !nowActive && wasActive {
+		logger.Info("throttle deactivated")
+	}
+}
+
+// computeFairCaps implements the fair-share algorithm. Users below the equal
+// share keep their connections; remaining budget is split equally among the
+// rest. Returns nil when no throttling is needed.
+func computeFairCaps(userConns map[string]int64, limit int64) map[string]int64 {
+	var total int64
+	for _, c := range userConns {
+		total += c
+	}
+
+	if total <= limit {
+		return nil
+	}
+
+	remaining := make(map[string]int64, len(userConns))
+	for k, v := range userConns {
+		remaining[k] = v
+	}
+
+	budget := limit
+	caps := make(map[string]int64)
+
+	for len(remaining) > 0 {
+		fairShare := budget / int64(len(remaining))
+		changed := false
+
+		for name, conns := range remaining {
+			if conns <= fairShare {
+				budget -= conns
+				delete(remaining, name)
+				changed = true
+			}
+		}
+
+		if !changed {
+			for name := range remaining {
+				caps[name] = fairShare
+			}
+
+			break
+		}
+	}
+
+	return caps
+}
+
 // StatsResponse is the JSON response for the stats endpoint.
 type StatsResponse struct {
 	StartedAt        time.Time                `json:"started_at"`
 	UptimeSeconds    int64                    `json:"uptime_seconds"`
 	TotalConnections int64                    `json:"total_connections"`
+	Throttle         *ThrottleJSON            `json:"throttle,omitempty"`
 	Users            map[string]UserStatsJSON `json:"users"`
 }
 
+// ThrottleJSON is the throttle portion of the stats JSON response.
+type ThrottleJSON struct {
+	Active bool             `json:"active"`
+	Limit  int64            `json:"limit"`
+	Caps   map[string]int64 `json:"caps,omitempty"`
+}
+
 // UserStatsJSON is the per-user portion of the stats JSON response.
 type UserStatsJSON struct {
 	Connections int64      `json:"connections"`
@@ -129,10 +263,33 @@ func (s *ProxyStats) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
+	var throttle *ThrottleJSON
+	if s.throttleLimit > 0 {
+		s.throttleMu.RLock()
+		active := s.throttleActive.Load()
+
+		var capsCopy map[string]int64
+		if len(s.throttleCaps) > 0 {
+			capsCopy = make(map[string]int64, len(s.throttleCaps))
+			for k, v := range s.throttleCaps {
+				capsCopy[k] = v
+			}
+		}
+
+		s.throttleMu.RUnlock()
+
+		throttle = &ThrottleJSON{
+			Active: active,
+			Limit:  s.throttleLimit,
+			Caps:   capsCopy,
+		}
+	}
+
 	resp := StatsResponse{
 		StartedAt:        s.startedAt,
 		UptimeSeconds:    int64(time.Since(s.startedAt).Seconds()),
 		TotalConnections: totalConns,
+		Throttle:         throttle,
 		Users:            users,
 	}
 

mtglib/proxy_stats_test.go

@@ -159,6 +159,164 @@ func TestServeHTTPEmpty(t *testing.T) {
 	assert.Equal(t, int64(0), resp.TotalConnections)
 }
 
+func TestComputeFairCaps_NoThrottle(t *testing.T) {
+	t.Parallel()
+
+	caps := computeFairCaps(map[string]int64{
+		"a": 10,
+		"b": 20,
+	}, 100)
+
+	assert.Nil(t, caps)
+}
+
+func TestComputeFairCaps_ExactLimit(t *testing.T) {
+	t.Parallel()
+
+	caps := computeFairCaps(map[string]int64{
+		"a": 50,
+		"b": 50,
+	}, 100)
+
+	assert.Nil(t, caps)
+}
+
+func TestComputeFairCaps_UserExample(t *testing.T) {
+	t.Parallel()
+
+	// The user's exact example: limit=100, users=[1, 1, 90, 110]
+	// Small users keep their 1+1=2, remaining budget=98, split among 2 → 49 each
+	caps := computeFairCaps(map[string]int64{
+		"a": 1,
+		"b": 1,
+		"c": 90,
+		"d": 110,
+	}, 100)
+
+	assert.Len(t, caps, 2)
+	assert.Equal(t, int64(49), caps["c"])
+	assert.Equal(t, int64(49), caps["d"])
+	// "a" and "b" should not appear in caps (they're under the fair share)
+	_, hasA := caps["a"]
+	_, hasB := caps["b"]
+	assert.False(t, hasA)
+	assert.False(t, hasB)
+}
+
+func TestComputeFairCaps_AllOverLimit(t *testing.T) {
+	t.Parallel()
+
+	caps := computeFairCaps(map[string]int64{
+		"a": 100,
+		"b": 100,
+	}, 50)
+
+	assert.Len(t, caps, 2)
+	assert.Equal(t, int64(25), caps["a"])
+	assert.Equal(t, int64(25), caps["b"])
+}
+
+func TestComputeFairCaps_SingleHeavyUser(t *testing.T) {
+	t.Parallel()
+
+	caps := computeFairCaps(map[string]int64{
+		"light": 5,
+		"heavy": 200,
+	}, 100)
+
+	// light(5) < fairShare(50), keeps 5. Budget = 95. Heavy capped to 95.
+	assert.Len(t, caps, 1)
+	assert.Equal(t, int64(95), caps["heavy"])
+}
+
+func TestCanConnect_NoThrottle(t *testing.T) {
+	t.Parallel()
+
+	stats := NewProxyStats()
+	// throttleLimit = 0 (default), so CanConnect always returns true
+	assert.True(t, stats.CanConnect("anyone"))
+}
+
+func TestCanConnect_WithCap(t *testing.T) {
+	t.Parallel()
+
+	stats := NewProxyStats()
+	stats.PreRegister("heavy")
+	stats.SetThrottle(100, 5*time.Second)
+
+	// Simulate 50 connections
+	for range 50 {
+		stats.OnConnect("heavy")
+	}
+
+	// Set cap to 50
+	stats.throttleMu.Lock()
+	stats.throttleCaps = map[string]int64{"heavy": 50}
+	stats.throttleActive.Store(true)
+	stats.throttleMu.Unlock()
+
+	// At exactly the cap → reject
+	assert.False(t, stats.CanConnect("heavy"))
+
+	// Disconnect one → allow
+	stats.OnDisconnect("heavy")
+	assert.True(t, stats.CanConnect("heavy"))
+}
+
+func TestCanConnect_NoCap(t *testing.T) {
+	t.Parallel()
+
+	stats := NewProxyStats()
+	stats.SetThrottle(100, 5*time.Second)
+
+	// User not in caps map → always allowed
+	assert.True(t, stats.CanConnect("uncapped-user"))
+}
+
+func TestServeHTTPThrottleInfo(t *testing.T) {
+	t.Parallel()
+
+	stats := NewProxyStats()
+	stats.PreRegister("alice")
+	stats.SetThrottle(100, 5*time.Second)
+
+	stats.throttleMu.Lock()
+	stats.throttleCaps = map[string]int64{"alice": 50}
+	stats.throttleActive.Store(true)
+	stats.throttleMu.Unlock()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/stats", nil)
+
+	stats.ServeHTTP(rec, req)
+
+	var resp StatsResponse
+	err := json.Unmarshal(rec.Body.Bytes(), &resp)
+	require.NoError(t, err)
+
+	require.NotNil(t, resp.Throttle)
+	assert.True(t, resp.Throttle.Active)
+	assert.Equal(t, int64(100), resp.Throttle.Limit)
+	assert.Equal(t, int64(50), resp.Throttle.Caps["alice"])
+}
+
+func TestServeHTTPNoThrottle(t *testing.T) {
+	t.Parallel()
+
+	stats := NewProxyStats()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/stats", nil)
+
+	stats.ServeHTTP(rec, req)
+
+	var resp StatsResponse
+	err := json.Unmarshal(rec.Body.Bytes(), &resp)
+	require.NoError(t, err)
+
+	assert.Nil(t, resp.Throttle)
+}
+
 func TestServeHTTPLastSeenZeroIsNull(t *testing.T) {
 	t.Parallel()