Add progressive throttle for follows ACL mode (v0.48.10)

- Add progressive throttle feature for follows ACL mode, allowing
  non-followed users to write with increasing delay instead of blocking
- Delay increases linearly per event (default 200ms) and decays at 1:1
  ratio with elapsed time, capping at configurable max (default 60s)
- Track both IP and pubkey independently to prevent evasion
- Add periodic cleanup to remove fully-decayed throttle entries
- Fix BBolt serial resolver to return proper errors when buckets or
  entries are not found

Files modified:
- app/config/config.go: Add ORLY_FOLLOWS_THROTTLE_* env vars
- app/handle-event.go: Apply throttle delay before event processing
- app/listener.go: Add getFollowsThrottleDelay helper method
- pkg/acl/follows.go: Integrate throttle with follows ACL
- pkg/acl/follows_throttle.go: New progressive throttle implementation
- pkg/bbolt/save-event.go: Return errors from serial lookups
- pkg/version/version: Bump to v0.48.10

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

pkg/acl/follows.go

@@ -45,6 +45,8 @@ type Follows struct {
 	lastFollowListFetch time.Time
 	// Callback for external notification of follow list changes
 	onFollowListUpdate func()
+	// Progressive throttle for non-followed users (nil if disabled)
+	throttle *ProgressiveThrottle
 }
 
 func (f *Follows) Configure(cfg ...any) (err error) {
@@ -131,6 +133,22 @@ func (f *Follows) Configure(cfg ...any) (err error) {
 			}
 		}
 	}
+
+	// Initialize progressive throttle if enabled
+	if f.cfg.FollowsThrottleEnabled {
+		perEvent := f.cfg.FollowsThrottlePerEvent
+		if perEvent == 0 {
+			perEvent = 200 * time.Millisecond
+		}
+		maxDelay := f.cfg.FollowsThrottleMaxDelay
+		if maxDelay == 0 {
+			maxDelay = 60 * time.Second
+		}
+		f.throttle = NewProgressiveThrottle(perEvent, maxDelay)
+		log.I.F("follows ACL: progressive throttle enabled (increment: %v, max: %v)",
+			perEvent, maxDelay)
+	}
+
 	return
 }
 
@@ -155,6 +173,10 @@ func (f *Follows) GetAccessLevel(pub []byte, address string) (level string) {
 	if f.cfg == nil {
 		return "write"
 	}
+	// If throttle enabled, non-followed users get write access (with delay applied in handle-event)
+	if f.throttle != nil {
+		return "write"
+	}
 	return "read"
 }
 
@@ -165,6 +187,41 @@ func (f *Follows) GetACLInfo() (name, description, documentation string) {
 
 func (f *Follows) Type() string { return "follows" }
 
+// GetThrottleDelay returns the progressive throttle delay for this event.
+// Returns 0 if throttle is disabled or if the user is exempt (owner/admin/followed).
+func (f *Follows) GetThrottleDelay(pubkey []byte, ip string) time.Duration {
+	if f.throttle == nil {
+		return 0
+	}
+
+	// Check if user is exempt from throttling
+	f.followsMx.RLock()
+	defer f.followsMx.RUnlock()
+
+	// Owners bypass throttle
+	for _, v := range f.owners {
+		if utils.FastEqual(v, pubkey) {
+			return 0
+		}
+	}
+	// Admins bypass throttle
+	for _, v := range f.admins {
+		if utils.FastEqual(v, pubkey) {
+			return 0
+		}
+	}
+	// Followed users bypass throttle
+	for _, v := range f.follows {
+		if utils.FastEqual(v, pubkey) {
+			return 0
+		}
+	}
+
+	// Non-followed users get throttled
+	pubkeyHex := hex.EncodeToString(pubkey)
+	return f.throttle.GetDelay(ip, pubkeyHex)
+}
+
 func (f *Follows) adminRelays() (urls []string) {
 	f.followsMx.RLock()
 	admins := make([][]byte, len(f.admins))
@@ -353,6 +410,29 @@ func (f *Follows) Syncer() {
 
 	// Start periodic follow list and metadata fetching
 	go f.startPeriodicFollowListFetching()
+
+	// Start throttle cleanup goroutine if throttle is enabled
+	if f.throttle != nil {
+		go f.throttleCleanup()
+	}
+}
+
+// throttleCleanup periodically removes fully-decayed throttle entries
+func (f *Follows) throttleCleanup() {
+	ticker := time.NewTicker(10 * time.Minute)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-f.Ctx.Done():
+			return
+		case <-ticker.C:
+			f.throttle.Cleanup()
+			ipCount, pubkeyCount := f.throttle.Stats()
+			log.T.F("follows throttle: cleanup complete, tracking %d IPs and %d pubkeys",
+				ipCount, pubkeyCount)
+		}
+	}
 }
 
 // startPeriodicFollowListFetching starts periodic fetching of admin follow lists

pkg/acl/follows_throttle.go

@@ -0,0 +1,126 @@
+package acl
+
+import (
+	"sync"
+	"time"
+)
+
+// ThrottleState tracks accumulated delay for an identity (IP or pubkey)
+type ThrottleState struct {
+	AccumulatedDelay time.Duration
+	LastEventTime    time.Time
+}
+
+// ProgressiveThrottle implements linear delay with time decay.
+// Each event adds perEvent delay, and delay decays at 1:1 ratio with elapsed time.
+// This creates a natural rate limit that averages to 1 event per perEvent interval.
+type ProgressiveThrottle struct {
+	mu           sync.Mutex
+	ipStates     map[string]*ThrottleState
+	pubkeyStates map[string]*ThrottleState
+	perEvent     time.Duration // delay increment per event (default 200ms)
+	maxDelay     time.Duration // cap (default 60s)
+}
+
+// NewProgressiveThrottle creates a new throttle with the given parameters.
+// perEvent is the delay added per event (e.g., 200ms).
+// maxDelay is the maximum accumulated delay cap (e.g., 60s).
+func NewProgressiveThrottle(perEvent, maxDelay time.Duration) *ProgressiveThrottle {
+	return &ProgressiveThrottle{
+		ipStates:     make(map[string]*ThrottleState),
+		pubkeyStates: make(map[string]*ThrottleState),
+		perEvent:     perEvent,
+		maxDelay:     maxDelay,
+	}
+}
+
+// GetDelay returns accumulated delay for this identity and updates state.
+// It tracks both IP and pubkey independently and returns the maximum of both.
+// This prevents evasion via different pubkeys from same IP or vice versa.
+func (pt *ProgressiveThrottle) GetDelay(ip, pubkeyHex string) time.Duration {
+	pt.mu.Lock()
+	defer pt.mu.Unlock()
+
+	now := time.Now()
+	var ipDelay, pubkeyDelay time.Duration
+
+	if ip != "" {
+		ipDelay = pt.updateState(pt.ipStates, ip, now)
+	}
+	if pubkeyHex != "" {
+		pubkeyDelay = pt.updateState(pt.pubkeyStates, pubkeyHex, now)
+	}
+
+	// Return max of both to prevent evasion
+	if ipDelay > pubkeyDelay {
+		return ipDelay
+	}
+	return pubkeyDelay
+}
+
+// updateState calculates and updates the delay for a single identity.
+// The algorithm:
+// 1. Decay: subtract elapsed time from accumulated delay (1:1 ratio)
+// 2. Add: add perEvent for this new event
+// 3. Cap: limit to maxDelay
+func (pt *ProgressiveThrottle) updateState(states map[string]*ThrottleState, key string, now time.Time) time.Duration {
+	state, exists := states[key]
+	if !exists {
+		// First event from this identity
+		states[key] = &ThrottleState{
+			AccumulatedDelay: pt.perEvent,
+			LastEventTime:    now,
+		}
+		return pt.perEvent
+	}
+
+	// Decay: subtract elapsed time (1:1 ratio)
+	elapsed := now.Sub(state.LastEventTime)
+	state.AccumulatedDelay -= elapsed
+	if state.AccumulatedDelay < 0 {
+		state.AccumulatedDelay = 0
+	}
+
+	// Add new event's delay
+	state.AccumulatedDelay += pt.perEvent
+	state.LastEventTime = now
+
+	// Cap at max
+	if state.AccumulatedDelay > pt.maxDelay {
+		state.AccumulatedDelay = pt.maxDelay
+	}
+
+	return state.AccumulatedDelay
+}
+
+// Cleanup removes entries that have fully decayed (no remaining delay).
+// This should be called periodically to prevent unbounded memory growth.
+func (pt *ProgressiveThrottle) Cleanup() {
+	pt.mu.Lock()
+	defer pt.mu.Unlock()
+
+	now := time.Now()
+
+	// Remove IP entries that have fully decayed
+	for k, v := range pt.ipStates {
+		elapsed := now.Sub(v.LastEventTime)
+		if elapsed >= v.AccumulatedDelay {
+			delete(pt.ipStates, k)
+		}
+	}
+
+	// Remove pubkey entries that have fully decayed
+	for k, v := range pt.pubkeyStates {
+		elapsed := now.Sub(v.LastEventTime)
+		if elapsed >= v.AccumulatedDelay {
+			delete(pt.pubkeyStates, k)
+		}
+	}
+}
+
+// Stats returns the current number of tracked IPs and pubkeys (for monitoring)
+func (pt *ProgressiveThrottle) Stats() (ipCount, pubkeyCount int) {
+	pt.mu.Lock()
+	defer pt.mu.Unlock()
+	return len(pt.ipStates), len(pt.pubkeyStates)
+}

pkg/bbolt/save-event.go

@@ -350,12 +350,15 @@ func (r *bboltSerialResolver) GetPubkeyBySerial(serial uint64) (pubkey []byte, e
 	r.b.db.View(func(tx *bolt.Tx) error {
 		bucket := tx.Bucket(bucketSpk)
 		if bucket == nil {
+			err = errors.New("bbolt: spk bucket not found")
 			return nil
 		}
 		val := bucket.Get(makeSerialKey(serial))
 		if val != nil {
 			pubkey = make([]byte, 32)
 			copy(pubkey, val)
+		} else {
+			err = errors.New("bbolt: pubkey serial not found")
 		}
 		return nil
 	})
@@ -374,12 +377,15 @@ func (r *bboltSerialResolver) GetEventIdBySerial(serial uint64) (eventID []byte,
 	r.b.db.View(func(tx *bolt.Tx) error {
 		bucket := tx.Bucket(bucketSei)
 		if bucket == nil {
+			err = errors.New("bbolt: sei bucket not found")
 			return nil
 		}
 		val := bucket.Get(makeSerialKey(serial))
 		if val != nil {
 			eventID = make([]byte, 32)
 			copy(eventID, val)
+		} else {
+			err = errors.New("bbolt: event serial not found")
 		}
 		return nil
 	})

pkg/version/version

@@ -1 +1 @@
-v0.48.9
+v0.48.10