docs(auth): update API key touch throttle map cap and eviction docs

[github-actions]

What changed

The apiKeyLastTouchedAt throttle map now uses FIFO eviction capped at 10,000 entries (defaultAPIKeyTouchMaxEntries = DefaultRateLimiterMaxVisitors) instead of the old sweep-at-100-entries behaviour introduced before PR #236.

This PR updates docs/auth/middleware.md to accurately describe:

• Bounded cap: the map tracks at most 10,000 distinct API key IDs concurrently.
• FIFO eviction: when the cap is reached, the oldest-inserted entry is removed before the new key is added.
• Renewal semantics: keys that are already tracked (re-insertion within the 5-minute window) update in-place and do not trigger eviction of an unrelated entry.
• Flood behaviour: under sustained load with > 10,000 distinct active keys, oldest tracked keys are evicted earlier than the normal 5-minute interval.

Why

The previous docs stated:

The throttle map is swept whenever it has at least 100 entries, removing entries whose last write was at least 5 minutes ago.

This was no longer accurate after the fix landed in #236.

Testing

Documentation-only change; no code modified.

Generated by Update Docs · ● 631.8K · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/update-docs.md@96b9d4c39aa22359c0b38265927eadb31dcf4e2a

Greptile Summary

This documentation-only PR updates docs/auth/middleware.md to accurately describe the API key touch throttle map, replacing the outdated sweep-at-100-entries description with the current FIFO-eviction-at-10,000-entries behaviour introduced in #236.

• Adds a new paragraph documenting the 10,000-entry cap (defaultAPIKeyTouchMaxEntries = DefaultRateLimiterMaxVisitors), FIFO eviction semantics, and in-place renewal behaviour, all of which match the implementation in auth/middleware.go.
• Replaces the stale bullet about sweep-at-100-entries with an accurate description of flood-eviction behaviour under sustained load with more than 10,000 distinct active keys.

Confidence Score: 5/5

Documentation-only change with no code modifications; the new text accurately matches the implementation in auth/middleware.go.

All claims in the updated paragraph — the 10,000-entry cap, FIFO eviction via the insertion-order queue, and in-place renewal without evicting an unrelated entry — were verified against the shouldTouchAPIKeyLastUsed implementation. The removed bullet about sweep-at-100-entries no longer exists in the code.

No files require special attention.

Important Files Changed

Filename	Overview
docs/auth/middleware.md	Documentation update replacing stale sweep-at-100 description with accurate FIFO-eviction-at-10,000 semantics; content matches the implementation in auth/middleware.go.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Incoming API key request] --> B{Key in throttle map AND within 5-min window?}
    B -- Yes --> C[Return false: Skip TouchAPIKeyLastUsed]
    B -- No --> D[Run compactOrderLocked on apiKeyTouchOrder]
    D --> E{Key already in map? isRenewal check}
    E -- Yes renewal --> F[Skip eviction, update entry in-place, append new orderEntry]
    E -- No new key --> G{len map >= 10,000 cap?}
    G -- No --> F
    G -- Yes --> H{apiKeyTouchOrder non-empty?}
    H -- Yes --> I[Pop oldest orderEntry, FIFO evict that key]
    H -- No fallback --> J[Evict arbitrary map entry]
    I --> F
    J --> F
    F --> K[Return true: Call TouchAPIKeyLastUsed]

Loading

_{Reviews (1): Last reviewed commit: "docs(auth): update API key touch throttl..." | Re-trigger Greptile}

[veverkap]

@copilot is this different than #246?

[Copilot]

@copilot is this different than #246?

Yes—different context. #246 documented the earlier cap behavior (sweep-before-insert + skip touch when still full, plus benchmark docs). This PR updates that same section again to match the newer logic from #236: capped at 10,000 with FIFO eviction and renewal updates in place (no unrelated eviction on renewal).

[Copilot]

Pull request overview

Updates the authentication middleware documentation to match the current API key last_used_at touch throttling implementation (post-#236), specifically how the in-process throttle map is bounded and how entries are evicted under load.

Changes:

• Document the 10,000-entry cap for the API key touch throttle map (bounded memory usage).
• Document FIFO eviction behavior when the cap is reached.
• Clarify renewal semantics and the effect of sustained load above the cap (earlier-than-5-minute touches for evicted keys).

Show a summary per file

File	Description
docs/auth/middleware.md	Updates API key last_used_at throttle documentation to reflect the capped FIFO-eviction behavior and its operational implications.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 1/1 changed files
• Comments generated: 0