fix(visualizer): cap live SSE streams, bound per-stream queues, never leak a subscription

[lmajano]

Description

Hardens the Live Tracker's Visualizer.stream() SSE action against three problems found by a reviewer with jcmd:

1. No connection limit. Every open stream pins two threads (the Undertow worker blocked in SSE()'s latch, plus the callback thread). A loop of GET .../stream requests exhausts the worker pool and takes the whole app down when the routes are not secured.
2. Unbounded queue. Each stream buffered events in a LinkedBlockingQueue() with no capacity, so a stalled or slow client grew memory without limit while rules kept firing.
3. Subscription leak on failure. bus.subscribe() ran before SSE(), so if SSE() threw, the token was never unsubscribed.

Changes:

• New models/metrics/LiveStreams.bx (LiveStreams@rulebox, singleton): an atomic stream-slot counter (tryAcquire / release), a bounded per-stream queue (newQueue, 1000 events) with offer() that drops the OLDEST event when full and never blocks the bus, and serve() which takes a slot, subscribes, runs the opener, and always unsubscribes and releases the slot in a finally.
• handlers/Visualizer.bx stream() now goes through serve(). At the cap it returns HTTP 503 { "error": "Too many live tracker connections" }. The preHandler enabled-gate is untouched.
• New setting visualizer.maxStreams (default 25), one line in ModuleConfig.bx. The handler reads it defensively (missing, non-numeric or < 1 falls back to 25), so it works whether or not the settings deep-merge fix has landed. Documented in docs/guides/visualizer.md.

Verified against the test-harness on BoxLang 1.18.0 (miniserver):

• Before: 40 concurrent GET .../stream -> 32 streams open (all 32 Undertow worker threads taken), 8 requests hang, and GET .../index times out (8s). The app is down.
• After: 40 concurrent -> 25 open, 15 get 503 {"error":"Too many live tracker connections"}; GET .../index still answers 200 in ~0.06s; after the clients leave, a new stream is accepted again (slots released by disconnect cleanup, ~2-28s depending on when the disconnect is noticed).
• A published event still reaches an open stream (event: rule with the JSON payload).
• Failure paths exercised through a scratch handler (removed): an opener that throws and a subscribe() that throws both leave activeCount() == 0 and no leaked bus subscribers; 50 publishes into a capacity-10 queue that is never drained keep exactly the newest 10.
• The TestBox runner does not work under the miniserver (missing globber module), so the new specs are relying on CI.

Issues

Found during the 2.0.0 pre-release review of the Visualizer's live SSE stream (reviewer jcmd thread dumps). No separate GitHub issue was filed.

Type of change

• Bug Fix
• Improvement
• New Feature
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Behavior change to note: more than maxStreams (default 25) simultaneous Live Tracker connections now get a 503 instead of being served.

Checklist

• My code follows the style guidelines of this project cfformat
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works (RuleEventBusSpec.bx: cap rejects the N+1th stream, a failed open or failed subscribe releases the slot, the bounded queue drops the oldest; VisualizerHandlerSpec.bx: stream() answers 503 at the cap, with the default and with an unusable setting)
• New and existing unit tests pass locally with my changes (TestBox cannot run under the miniserver here; boxlang check passes on every touched file and the behavior was verified live as above; relying on CI for the suite)

Noticed, not fixed

• SSE( async: true ) still pins two threads per stream (worker blocked in the latch plus the callback thread). The cap bounds it; switching to a non-blocking approach would be a separate change.
• On the very first concurrent burst against a cold server, 1 of 15 simultaneous rejected requests returned a 500 from ColdBox's DataMarshaller.renderContent (variables.requestService was null: a first-use initialization race inside ColdBox's renderData). It did not recur once warm. Not caused by this change.
• The test-harness Application.bx only finds the module when the checkout directory is literally named rulebox (its moduleRootPath regex), so it fails to boot from a worktree under any other directory name.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Yc5MDcm3tyR2yqPWs9RpgX

---

Generated by Claude Code