docs(queue): Broker\Nats control connection is inertia, not intent - #149
Open
levivannoort wants to merge 1 commit into
Open
docs(queue): Broker\Nats control connection is inertia, not intent#149levivannoort wants to merge 1 commit into
levivannoort wants to merge 1 commit into
Conversation
…ntent Document why getQueueSize() reads over a client connection and needs a dedicated control connection: it's the inherited Consumer-contract depth gauge (a free LLEN on Redis, a consumer.info() round-trip on NATS), not a deliberate metrics-connection design. The same num_pending is already on the NATS monitoring endpoint, so this and the extra connection are a migration-parity stopgap to retire once depth comes from that endpoint (KEDA/observability work).
levivannoort
requested review from
ChiragAgg5k,
abnegate and
lohanidamodar
as code owners
August 19, 2026 08:43
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.
Comment-only. Records why
Broker\Nats::getQueueSize()reads over a client connection and needs a dedicated control connection (added in #147), so the next reader doesn't mistake it for a deliberate "metrics get their own NATS connection" design.Why it exists — inertia, not intent:
getQueueSize()is part of theConsumercontract, andQueue\Serveremits a generic queue-depth gauge through it.getQueueSize()is a cheapLLENon a pooled connection — free, unnoticed.consumer.info()round-trip over the single-owner socket. MakingBroker\Natsa drop-inConsumer(MIG-4) kept that call, and the control connection is only there to keep it safe under Swoole (the consume loop and the telemetry coroutine can't share one socket).num_pendingis already published on the NATS monitoring endpoint (thepromExporterscrape). So the client-side read and the extra connection are a migration-parity stopgap.Retire path: once autoscaling/telemetry read depth from the monitoring endpoint (KEDA / MIG-9), drop the client-side depth gauge for NATS and delete the control connection — then it's exactly one connection per consume coroutine and zero for metrics.
No behaviour change;
php -land Pint clean.