Skip to content

feat(miner-governor): local rate-limit token-bucket + jittered-backoff calculator (pure) #2327

Description

@JSONbored

The Governor's rate-limiting needs a deterministic backoff/jitter calculator BEFORE it can be wired into any real enforcement path. This issue is the pure math only: given a bucket state (count, window, limit) and a clock reading, return the next-allowed-at time and a jittered retry delay — no storage, no scheduling, no actual blocking of a write action.

The existing RateLimiter Durable Object in src/auth/rate-limit.ts is a SERVER-side, Cloudflare-specific limiter and is NOT reusable client-side (the miner is 100% local, per the architecture skeleton) — so this is new local logic, but the bucket math and jittered-retry shape should mirror CONFIG/RateLimitDecision's fields for consistency of vocabulary.

Deliverables

  • New pure module (e.g. packages/gittensory-engine/src/governor/rate-limit.ts) exporting a LocalRateBucket type and evaluateLocalRateLimit(bucket, config, nowMs) returning { allowed, remaining, resetAtMs, retryAfterMs }
  • A jitter function jitteredBackoffMs(baseMs, attempt, randomFn) that takes an injectable random source (never calls Math.random() directly) so it stays unit-testable and deterministic in tests
  • Unit tests: under-limit passes, at-limit blocks, window-reset clears the bucket, jitter stays within the expected multiplicative band across a swept range of attempt values
  • A short doc comment stating explicitly this module computes numbers only — it does not itself gate any write action (that wiring is a separate, maintainer-owned issue)

References

  • src/auth/rate-limit.ts (207 lines) — the server-side RateLimitConfig/RateLimitDecision vocabulary to mirror (not reuse — that one is a Cloudflare Durable Object)
  • packages/gittensory-engine/ — new shared engine package housing this pure logic

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.help wantedExtra attention is needed

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions