fix: eliminate search OOM stampede + share slug cache across sessions (v5.2.1)#14
Merged
Merged
Conversation
…ed token The book-slug warm cache lived on each BookStackClient instance, and index.ts builds one client per MCP session, so every new session re-ran the bulk /books sweep on its first search. All sessions share ONE BookStack service token whose API rate limit is 180 req/min, so the redundant per-session sweeps burned that shared budget and, under concurrent use, tripped 429s whose Retry-After (12-47s) blocked requests — surfacing as intermittent long stalls even after the OOM fix. Move the slug cache (plus the in-flight dedup and warm promise) to a process-wide store keyed by base URL, refreshed at most once per 10-minute TTL. The book-id to slug mapping is identical for all callers of the same BookStack regardless of token, so sharing is safe. Turns N per-session sweeps into one per process/TTL. Also bumps plugin.json (was stale at 5.1.0) and version to 5.2.1.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Users reported the BookStack connector (deployed to Swarm at bookstack-mcp.teamgleim.com) being buggy and slow. Investigation found two related issues on the shared, rate-limited (180 req/min) BookStack service token:
OOM crashes (already live via the branch image, now landed on main): enhancing search/recent/list results resolved a book slug per item via a non-atomic check-then-set cache, so a batch stampeded
GET /books/{id}, BookStack 429'd the burst, retries piled up, and the Node heap OOM-crashed the container (exit 134/ "Reached heap limit"). Fixed by bulk-warming the slug cache from one/bookslisting + in-flight dedup, plus a configurable axios timeout. (commit 861796d)Intermittent long stalls (this release's new fix): the warm cache lived on each
BookStackClient, andindex.tsbuilds one client per MCP session, so every new session re-ran the/bookssweep. Those redundant sweeps burned the shared 180/min budget and, under concurrent use, tripped 429s whoseRetry-After(12–47s) blocked requests. Moved the slug cache (+ in-flight dedup + warm promise) to a process-wide store keyed by base URL, refreshed at most once per 10-min TTL. One sweep per process/TTL instead of one per session. (commit 4b72cdd)Verification
npm run type-checkandnpm run buildclean./bookssweeps): two client instances (= two sessions) now share 1 sweep (was 2), slug still resolved correctly.Notes
Retry-After)..claude-plugin/plugin.json(was stale at 5.1.0) to 5.2.1.:5.2.0(which only ever existed as a branch-built image); this PR finally lands the OOM fix onmain.