Moleculer action queue depth exposure for client-side backoff decisions

Direct answer

Moleculer middleware is the supported extension point for intercepting action calls and ServiceUnavailable errors, but the framework does not document a public API for reading live action-queue length. You can catch and enrich rejection errors in middleware, but injecting authoritative queue depth, estimated wait time, or a Retry-After hint requires reading undocumented broker internals, which is not supported across upgrades. There is no confirmed plan for a queueDepth metric or Retry-After header in the available release information; treat both as unplanned until verified in the project's issue tracker or release notes.

Confirmed facts

• maxConcurrency and queueSize limit per-action concurrency; a full queue rejects with ServiceUnavailable.
• The standard error payload does not include queue depth, wait time, or Retry-After.
• Moleculer is transport-agnostic; HTTP-style headers are not a built-in broker concept and depend on the transporter or API gateway layer.
• Circuit breaker state is tracked per action and is not automatically coupled to maxConcurrency, queueSize, or queue-depth signaling.

Likely explanation and uncertainty

A custom middleware can wrap action invocation, record enqueue timestamps, and count rejections locally. That produces a client-side approximation, not authoritative broker state. Under concurrent load the estimate can be stale, and transporter prefetch buffers (Redis, NATS, AMQP, MQTT, TCP) add latency that middleware cannot distinguish from action-queue wait time. Whether a specific Moleculer version exposes any action stats object depends on the installed version; this has not been verified against your codebase.

Steps for this case

1. Implement a custom middleware with an error handler that catches ServiceUnavailable rejections and attaches application-specific context, such as the action name and timestamp.
2. Track rejections and in-flight counts in the middleware itself as a local load-shedding signal, not as broker queue depth.
3. Add jitter and absolute retry caps on the client so inferred backoff cannot cause thundering-herd retries.
4. Verify transporter prefetch settings separately; low broker queue depth does not guarantee immediate execution when transport buffers are full.

Verification

Run npm ls moleculer to confirm the installed version, then inspect that version's middleware and action API for any public queue-length property before relying on it. Load-test with maxConcurrency and queueSize while logging middleware-observed rejections to confirm whether any depth data is present. Do not access undocumented broker internals in production.

Missing diagnostic detail

Which Moleculer version are you running? The middleware API and available action stats differ between versions, and that determines whether custom error enrichment is straightforward or requires version-specific shims.