Close out NATS pending list: gate cleanup, capabilities API, metadata, ZSET guards

Five small follow-ups against the recently re-audited pending list:

1. RqueueMessageMetadataServiceImpl drops its redundant
   @conditional(RedisBackendCondition) — the per-class gate is
   redundant once RqueueRedisListenerConfig itself is conditional
   and component-scans the whole com.github.sonus21.rqueue.redis
   subtree. Last sibling to still carry it; matches the cleanup
   already applied to the other five web service impls.

2. RqueueQDetailServiceImpl.readFromZset / readFromZsetWithScore
   gain a backend-capability guard. Both used to reach into a
   Redis-shaped RqueueMessageTemplate even when the active broker
   is NATS — which has no ZSET-shaped scheduled / completion
   queue and would NPE through the template's null Redis path.
   The new requireScheduledIntrospection check inspects
   MessageBroker.capabilities().supportsScheduledIntrospection
   and surfaces a structured BackendCapabilityException (HTTP 501
   via the existing advice) instead. readFromList stays unguarded
   because the LIST path is already routed through the broker SPI
   peek when a non-Redis broker is configured.

3. New GET /rqueue/api/v1/capabilities endpoint on both the
   imperative and reactive REST controllers. Returns the active
   broker's Capabilities record so the dashboard front-end can
   hide unsupported panels at boot rather than waiting for each
   call to 501. ObjectProvider<MessageBroker> keeps the dep
   optional — deployments that strip the bean fall back to
   Capabilities.REDIS_DEFAULTS, the historical behavior.

4. spring-boot-starter wires
   spring-boot-configuration-processor as an annotationProcessor
   so the build emits spring-configuration-metadata.json with all
   36 rqueue.nats.* keys (verified after compile). Pure
   compile-time addition, no new runtime deps.

(5 — confirming NatsBackendEndToEndIT on CI — is push-driven and
covered by this push.)

All 4 module unit suites still green:
  rqueue-core / rqueue-redis (57) / rqueue-web (39) / rqueue-nats (29).

Assisted-By: Claude Code

Author: sonus21

rqueue-redis/src/main/java/com/github/sonus21/rqueue/redis/web/RqueueMessageMetadataServiceImpl.java

@@ -17,7 +17,6 @@
 package com.github.sonus21.rqueue.redis.web;
 
 import com.github.sonus21.rqueue.common.RqueueLockManager;
-import com.github.sonus21.rqueue.config.RedisBackendCondition;
 import com.github.sonus21.rqueue.config.RqueueConfig;
 import com.github.sonus21.rqueue.core.RqueueMessage;
 import com.github.sonus21.rqueue.core.support.RqueueMessageUtils;
@@ -37,13 +36,17 @@
 import java.util.stream.Collectors;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.context.annotation.Conditional;
 import org.springframework.data.redis.core.DefaultTypedTuple;
 import org.springframework.data.redis.core.ZSetOperations.TypedTuple;
 import org.springframework.stereotype.Service;
 import reactor.core.publisher.Mono;
 
-@Conditional(RedisBackendCondition.class)
+/**
+ * Redis-shaped impl. Backend gating is handled at module level via
+ * {@code RqueueRedisListenerConfig.@Conditional(RedisBackendCondition)} + its
+ * {@code @ComponentScan} of {@code com.github.sonus21.rqueue.redis} — a per-class
+ * {@code @Conditional} would be redundant.
+ */
 @Service
 @Slf4j
 public class RqueueMessageMetadataServiceImpl implements RqueueMessageMetadataService {

rqueue-spring-boot-starter/build.gradle

@@ -55,6 +55,11 @@ dependencies {
     compileOnly project(":rqueue-nats")
     compileOnly "io.nats:jnats:${natsVersion}"
 
+    // Generates spring-configuration-metadata.json from @ConfigurationProperties classes
+    // (RqueueNatsProperties primarily) so IDE autocomplete and the Spring Boot metadata viewer
+    // surface every rqueue.nats.* key. Processor only — no runtime dep added.
+    annotationProcessor "org.springframework.boot:spring-boot-configuration-processor:${springBootVersion}"
+
     testImplementation project(":rqueue-spring-common-test")
     testImplementation project(":rqueue-nats")
     testImplementation "org.springframework.boot:spring-boot-starter-test:${springBootVersion}"

rqueue-web/src/main/java/com/github/sonus21/rqueue/web/controller/ReactiveRqueueRestController.java

@@ -65,6 +65,9 @@ public class ReactiveRqueueRestController extends BaseReactiveController {
   private final RqueueUtilityService rqueueUtilityService;
   private final RqueueSystemManagerService rqueueQManagerService;
   private final RqueueJobService rqueueJobService;
+  private final org.springframework.beans.factory.ObjectProvider<
+          com.github.sonus21.rqueue.core.spi.MessageBroker>
+      messageBrokerProvider;
 
   @Autowired
   public ReactiveRqueueRestController(
@@ -73,13 +76,17 @@ public ReactiveRqueueRestController(
       RqueueUtilityService rqueueUtilityService,
       RqueueSystemManagerService rqueueQManagerService,
       RqueueWebConfig rqueueWebConfig,
-      RqueueJobService rqueueJobService) {
+      RqueueJobService rqueueJobService,
+      org.springframework.beans.factory.ObjectProvider<
+              com.github.sonus21.rqueue.core.spi.MessageBroker>
+          messageBrokerProvider) {
     super(rqueueWebConfig);
     this.rqueueDashboardChartService = rqueueDashboardChartService;
     this.rqueueQDetailService = rqueueQDetailService;
     this.rqueueUtilityService = rqueueUtilityService;
     this.rqueueQManagerService = rqueueQManagerService;
     this.rqueueJobService = rqueueJobService;
+    this.messageBrokerProvider = messageBrokerProvider;
   }
 
   @PostMapping("chart")
@@ -215,4 +222,19 @@ public Mono<DataSelectorResponse> aggregateDataCounter(
     }
     return null;
   }
+
+  /** Reactive twin of {@code RqueueRestController#capabilities}. See javadoc there. */
+  @GetMapping("capabilities")
+  @ResponseBody
+  public Mono<com.github.sonus21.rqueue.core.spi.Capabilities> capabilities(
+      ServerHttpResponse response) {
+    if (!isEnabled(response)) {
+      return Mono.empty();
+    }
+    com.github.sonus21.rqueue.core.spi.MessageBroker broker = messageBrokerProvider.getIfAvailable();
+    return Mono.just(
+        broker == null
+            ? com.github.sonus21.rqueue.core.spi.Capabilities.REDIS_DEFAULTS
+            : broker.capabilities());
+  }
 }

rqueue-web/src/main/java/com/github/sonus21/rqueue/web/controller/RqueueRestController.java

@@ -17,6 +17,8 @@
 package com.github.sonus21.rqueue.web.controller;
 
 import com.github.sonus21.rqueue.config.RqueueWebConfig;
+import com.github.sonus21.rqueue.core.spi.Capabilities;
+import com.github.sonus21.rqueue.core.spi.MessageBroker;
 import com.github.sonus21.rqueue.exception.ProcessingException;
 import com.github.sonus21.rqueue.models.enums.AggregationType;
 import com.github.sonus21.rqueue.models.request.ChartDataRequest;
@@ -44,6 +46,7 @@
 import jakarta.servlet.http.HttpServletResponse;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotEmpty;
+import org.springframework.beans.factory.ObjectProvider;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.context.annotation.Conditional;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -64,6 +67,7 @@ public class RqueueRestController extends BaseController {
   private final RqueueUtilityService rqueueUtilityService;
   private final RqueueSystemManagerService rqueueQManagerService;
   private final RqueueJobService rqueueJobService;
+  private final ObjectProvider<MessageBroker> messageBrokerProvider;
 
   @Autowired
   public RqueueRestController(
@@ -72,13 +76,15 @@ public RqueueRestController(
       RqueueUtilityService rqueueUtilityService,
       RqueueSystemManagerService rqueueQManagerService,
       RqueueWebConfig rqueueWebConfig,
-      RqueueJobService rqueueJobService) {
+      RqueueJobService rqueueJobService,
+      ObjectProvider<MessageBroker> messageBrokerProvider) {
     super(rqueueWebConfig);
     this.rqueueDashboardChartService = rqueueDashboardChartService;
     this.rqueueQDetailService = rqueueQDetailService;
     this.rqueueUtilityService = rqueueUtilityService;
     this.rqueueQManagerService = rqueueQManagerService;
     this.rqueueJobService = rqueueJobService;
+    this.messageBrokerProvider = messageBrokerProvider;
   }
 
   @PostMapping("chart")
@@ -212,4 +218,25 @@ public DataSelectorResponse aggregateDataCounter(
     }
     return null;
   }
+
+  /**
+   * Reports the active broker's capability flags (delayed enqueue, scheduled introspection,
+   * cron jobs, primary-handler dispatch). The dashboard front-end reads this once at boot to
+   * hide panels the backend cannot service rather than relying on per-call 501 responses.
+   *
+   * <p>Sourced from {@link MessageBroker#capabilities()} — the Redis broker answers with
+   * {@link Capabilities#REDIS_DEFAULTS} (everything true) and the NATS broker answers
+   * with everything false in v1. {@link ObjectProvider} keeps the broker dependency optional
+   * so deployments that strip the bean still get a sane payload (defaults to Redis, the
+   * historical behavior).
+   */
+  @GetMapping("capabilities")
+  @ResponseBody
+  public Capabilities capabilities(HttpServletResponse response) {
+    if (!isEnable(response)) {
+      return null;
+    }
+    MessageBroker broker = messageBrokerProvider.getIfAvailable();
+    return broker == null ? Capabilities.REDIS_DEFAULTS : broker.capabilities();
+  }
 }

rqueue-web/src/main/java/com/github/sonus21/rqueue/web/service/impl/RqueueQDetailServiceImpl.java

@@ -223,6 +223,7 @@ public List<NavTab> getNavTabs(QueueConfig queueConfig) {
 
   private List<TypedTuple<RqueueMessage>> readFromZset(
       String name, int pageNumber, int itemPerPage) {
+    requireScheduledIntrospection("readFromZset");
     long start = pageNumber * (long) itemPerPage;
     long end = start + itemPerPage - 1;
 
@@ -242,11 +243,27 @@ private List<TypedTuple<RqueueMessage>> readFromList(
 
   private List<TypedTuple<RqueueMessage>> readFromZetWithScore(
       String name, int pageNumber, int itemPerPage) {
+    requireScheduledIntrospection("readFromZsetWithScore");
     long start = pageNumber * (long) itemPerPage;
     long end = start + itemPerPage - 1;
     return rqueueMessageTemplate.readFromZsetWithScore(name, start, end);
   }
 
+  /**
+   * Guard for ZSET-shaped lookups that the redis backend services natively but no other backend
+   * does. Backends that report {@code !supportsScheduledIntrospection()} surface a structured 501
+   * via {@code BackendCapabilityException} instead of NPE-ing through a Redis-shaped template
+   * with no Redis connection.
+   */
+  private void requireScheduledIntrospection(String op) {
+    if (messageBroker != null && !messageBroker.capabilities().supportsScheduledIntrospection()) {
+      throw new com.github.sonus21.rqueue.exception.BackendCapabilityException(
+          messageBroker.getClass().getSimpleName(),
+          op,
+          "broker does not expose scheduled / completion ZSET introspection");
+    }
+  }
+
   private List<TableRow> buildRows(
       List<TypedTuple<RqueueMessage>> rqueueMessages, RowBuilder rowBuilder) {
     if (CollectionUtils.isEmpty(rqueueMessages)) {