Add rqueue-spring-boot-nats-example

Spring Boot example app on the NATS / JetStream backend, mirroring the
existing rqueue-spring-boot-example. Backend selection is a property
switch only (rqueue.backend=nats + rqueue.nats.connection.url); the
listener / controller / domain code is unchanged from the redis
example, which is the whole point of the pluggable-backend split.

Two small differences from the redis example:
- Delayed / periodic enqueue endpoints (job-delay, sch-job) and their
  listeners are removed. v1 NATS broker doesn't model delayed delivery
  — the redis ZSET-backed schedulers don't exist on the NATS side,
  and the broker throws UnsupportedOperationException for those calls.
- application.properties selects NATS, points connection.url at a
  JetStream-enabled nats-server, and sets all four auto-create flags
  to true (the defaults; flipped explicitly for documentation).

Side fix: rqueue-nats now declares api(":rqueue-web") because the
NATS-shaped web service impls (NatsRqueueQDetailService etc., added in
parallel work) implement interfaces from rqueue-web. Mirrors how
rqueue-redis pulls rqueue-web for the same reason.

Includes a README documenting how to run nats-server locally, the
streams / KV buckets the app provisions, and the
autoCreate*=false / pre-create flow for locked-down JetStream
accounts.

Assisted-By: Claude Code

Author: sonus21

rqueue-nats/build.gradle

@@ -45,6 +45,9 @@ dependencies {
     // rqueue-spring-boot-starter (auto-config), both of which reference this module's
     // types via compileOnly and gate them behind @ConditionalOnClass(JetStream.class).
     api project(":rqueue-core")
+    // NATS-shaped web service impls (NatsRqueueQDetailService, etc.) implement interfaces
+    // declared in rqueue-web. Mirrors how rqueue-redis pulls rqueue-web for the same reason.
+    api project(":rqueue-web")
     api "io.nats:jnats:${natsVersion}"
     testImplementation project(":rqueue-test-util")
     testImplementation "org.testcontainers:testcontainers:${testcontainersVersion}"

rqueue-spring-boot-nats-example/README.md

@@ -0,0 +1,77 @@
+# rqueue-spring-boot-nats-example
+
+Spring Boot example app using **NATS / JetStream** as the Rqueue backend, mirroring
+[`rqueue-spring-boot-example`](../rqueue-spring-boot-example) (which uses Redis).
+
+The application code is identical to the redis example modulo two small things:
+
+- **Delayed and periodic enqueue endpoints are removed.** The v1 NATS broker doesn't model
+  delayed or scheduled delivery — the redis backend's ZSET schedulers don't exist on the NATS
+  side, and the broker throws `UnsupportedOperationException` for those calls.
+- **`application.properties` selects the NATS backend** via `rqueue.backend=nats` and points
+  `rqueue.nats.connection.url` at a JetStream-enabled `nats-server`.
+
+Backend selection is a property switch only — the listener / controller / domain code is
+unchanged from the redis example, which is the whole point of the pluggable-backend split.
+
+## Running locally
+
+Start a JetStream-enabled NATS server (any one of these works):
+
+```sh
+# native binary
+nats-server -js
+
+# docker
+docker run -p 4222:4222 nats:latest -js
+```
+
+Then:
+
+```sh
+./gradlew :rqueue-spring-boot-nats-example:bootRun
+```
+
+Once the app is up:
+
+```sh
+# enqueue a String to a queue (default queue is "simple-queue", from application.properties)
+curl 'http://localhost:8080/push?q=simple-queue&msg=hello'
+
+# enqueue a Job object to job-queue (with DLQ wired to job-morgue)
+curl http://localhost:8080/job
+```
+
+Watch the logs for `simple: hello` / `job-queue: Job(id=…)` from `MessageListener`.
+
+## Inspecting the JetStream state
+
+`nats stream ls` will show:
+
+```
+rqueue-js-simple-queue
+rqueue-js-job-queue
+rqueue-js-job-queue-dlq
+rqueue-js-job-morgue
+```
+
+(The `rqueue-js-` prefix is the default; configure via `rqueue.nats.naming.streamPrefix`.)
+
+`nats kv ls` will show the six shared KV buckets used by the NATS-backed daos
+(`rqueue-jobs`, `rqueue-locks`, `rqueue-message-metadata`, etc.). See the README's
+"NATS backend" section in the repo root for the full table.
+
+## Locked-down JetStream accounts
+
+If your NATS account can't run `add_stream` / `kv_create` at runtime, set:
+
+```properties
+rqueue.nats.auto-create-streams=false
+rqueue.nats.auto-create-consumers=false
+rqueue.nats.auto-create-dlq-stream=false
+rqueue.nats.auto-create-kv-buckets=false
+```
+
+…and pre-create the streams + buckets per the root README. `NatsStreamValidator` /
+`NatsKvBucketValidator` will fail boot deterministically with the list of missing
+streams / buckets if any are not present.

rqueue-spring-boot-nats-example/build.gradle

@@ -0,0 +1,20 @@
+plugins {
+    id "org.springframework.boot" version "${springBootVersion}"
+    id "war"
+}
+dependencies {
+    implementation project(":rqueue-spring-boot-starter")
+    // rqueue-nats brings the JetStream broker, KV-backed daos, NatsStreamValidator, etc.
+    // It's a runtime-conditional dependency on the starter side (gated by rqueue.backend=nats),
+    // so the example pins it explicitly.
+    implementation project(":rqueue-nats")
+    implementation "org.springframework.boot:spring-boot-starter-web:${springBootVersion}"
+    // jnats is api-exposed by rqueue-nats, but pinning it here keeps the build readable.
+    implementation "io.nats:jnats:${natsVersion}"
+    // https://mvnrepository.com/artifact/ch.qos.logback/logback-core
+    implementation "ch.qos.logback:logback-core:${logbackVersion}"
+    // https://mvnrepository.com/artifact/ch.qos.logback/logback-classic
+    implementation "ch.qos.logback:logback-classic:${logbackVersion}"
+    annotationProcessor "org.springframework.boot:spring-boot-configuration-processor:${springBootVersion}"
+    providedRuntime "org.springframework.boot:spring-boot-starter-tomcat:${springBootVersion}"
+}

rqueue-spring-boot-nats-example/src/main/java/com/github/sonus21/rqueue/example/Controller.java

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2024-2026 Sonu Kumar
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and limitations under the License.
+ *
+ */
+
+package com.github.sonus21.rqueue.example;
+
+import com.github.sonus21.rqueue.core.RqueueMessageEnqueuer;
+import com.github.sonus21.rqueue.utils.StringUtils;
+import java.util.UUID;
+import lombok.AllArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * Same shape as the redis example's controller, with delayed / periodic endpoints removed —
+ * the v1 NATS broker doesn't support delayed delivery or periodic enqueue and would throw
+ * {@code UnsupportedOperationException} at runtime if those code paths were hit.
+ */
+@RestController
+@AllArgsConstructor(onConstructor = @__(@Autowired))
+@Slf4j
+public class Controller {
+
+  private final RqueueMessageEnqueuer rqueueMessageEnqueuer;
+
+  @GetMapping(value = "/push")
+  public String push(String q, String msg) {
+    String messageId = rqueueMessageEnqueuer.enqueue(q, msg);
+    log.info("Message {}", msg);
+    return "Message sent successfully, message id " + messageId;
+  }
+
+  private String getQueue(String queue) {
+    if (queue == null) {
+      return "job-queue";
+    }
+    return queue;
+  }
+
+  private Job getJob(String message) {
+    Job job = new Job();
+    job.setId(UUID.randomUUID().toString());
+    if (!StringUtils.isEmpty(message)) {
+      job.setMessage(message);
+    } else {
+      job.setMessage("Hi this is " + job.getId());
+    }
+    return job;
+  }
+
+  @GetMapping("job")
+  public String sendJobNotification(
+      @RequestParam(required = false) String msg, @RequestParam(required = false) String q) {
+    Job job = getJob(msg);
+    String messageId = rqueueMessageEnqueuer.enqueue(getQueue(q), job);
+    job.setMessage(messageId);
+    return job.toString();
+  }
+}

rqueue-spring-boot-nats-example/src/main/java/com/github/sonus21/rqueue/example/Job.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2024-2026 Sonu Kumar
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and limitations under the License.
+ *
+ */
+
+package com.github.sonus21.rqueue.example;
+
+import lombok.Getter;
+import lombok.Setter;
+import lombok.ToString;
+
+@Getter
+@Setter
+@ToString
+public class Job {
+
+  private String id;
+  private String message;
+  private String messageId;
+}

rqueue-spring-boot-nats-example/src/main/java/com/github/sonus21/rqueue/example/MessageListener.java

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2024-2026 Sonu Kumar
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and limitations under the License.
+ *
+ */
+
+package com.github.sonus21.rqueue.example;
+
+import com.github.sonus21.rqueue.annotation.RqueueListener;
+import com.github.sonus21.rqueue.utils.TimeoutUtils;
+import java.util.Random;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+/**
+ * Same listener shape as the redis example, minus the delayed-queue and scheduled-job
+ * listeners (those rely on Redis-only ZSET-backed schedulers; the v1 NATS broker delegates
+ * redelivery to JetStream's own {@code AckWait} timer instead).
+ */
+@Component
+@Slf4j
+public class MessageListener {
+
+  private static final Random random = new Random();
+
+  @Value("${job.fail.percentage:0}")
+  private int percentageFailure;
+
+  @Value("${job.execution.interval:100}")
+  private int jobExecutionTime;
+
+  protected boolean shouldFail() {
+    if (percentageFailure == 0) {
+      return false;
+    }
+    if (percentageFailure >= 100) {
+      return true;
+    }
+    return random.nextInt(100) < percentageFailure;
+  }
+
+  protected void execute(String msg, Object any, boolean failingEnabled) {
+    log.info(msg, any);
+    TimeoutUtils.sleep(random.nextInt(jobExecutionTime));
+    if (failingEnabled && shouldFail()) {
+      throw new IllegalArgumentException("Failing On Purpose " + any);
+    }
+  }
+
+  @RqueueListener(value = "${rqueue.simple.queue}")
+  public void onSimpleMessage(String message) {
+    execute("simple: {}", message, false);
+  }
+
+  @RqueueListener(
+      value = "job-queue",
+      deadLetterQueue = "job-morgue",
+      numRetries = "2",
+      deadLetterQueueListenerEnabled = "false",
+      concurrency = "10-20")
+  public void onJobMessage(Job job) {
+    execute("job-queue: {}", job, true);
+  }
+
+  @RqueueListener(value = "job-morgue", numRetries = "1", concurrency = "1-3")
+  public void onJobDlqMessage(Job job) {
+    execute("job-morgue: {}", job, true);
+  }
+}

rqueue-spring-boot-nats-example/src/main/java/com/github/sonus21/rqueue/example/MvcConfig.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2024-2026 Sonu Kumar
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and limitations under the License.
+ *
+ */
+
+package com.github.sonus21.rqueue.example;
+
+import com.github.sonus21.rqueue.utils.StringUtils;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.EnableWebMvc;
+import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+@EnableWebMvc
+@Configuration
+public class MvcConfig implements WebMvcConfigurer {
+
+  @Value("${rqueue.web.url.prefix:}")
+  private String rqueueWebUrlPrefix;
+
+  @Override
+  public void addResourceHandlers(ResourceHandlerRegistry registry) {
+    if (!registry.hasMappingForPattern("/webjars/**")) {
+      registry
+          .addResourceHandler("/webjars/**")
+          .addResourceLocations("classpath:/META-INF/resources/webjars/");
+    }
+    if (!StringUtils.isEmpty(rqueueWebUrlPrefix)) {
+      registry
+          .addResourceHandler(rqueueWebUrlPrefix + "/**")
+          .addResourceLocations("classpath:/public/");
+    }
+    if (!registry.hasMappingForPattern("/**")) {
+      registry.addResourceHandler("/**").addResourceLocations("classpath:/public/");
+    }
+  }
+}

rqueue-spring-boot-nats-example/src/main/java/com/github/sonus21/rqueue/example/RQueueApplication.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2024-2026 Sonu Kumar
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and limitations under the License.
+ *
+ */
+
+package com.github.sonus21.rqueue.example;
+
+import com.github.sonus21.rqueue.config.SimpleRqueueListenerContainerFactory;
+import com.github.sonus21.rqueue.utils.Constants;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * Mirror of the redis-backed {@code rqueue-spring-boot-example} for the NATS / JetStream backend.
+ * Selecting the backend is a property switch only (see {@code application.properties}); the
+ * application code is unchanged from the redis example, which is the whole point of the
+ * pluggable-backend split.
+ */
+@SpringBootApplication
+public class RQueueApplication {
+
+  @Value("${workers.count:3}")
+  private int workersCount;
+
+  public static void main(String[] args) {
+    SpringApplication.run(RQueueApplication.class, args);
+  }
+
+  @Bean
+  public SimpleRqueueListenerContainerFactory simpleRqueueListenerContainerFactory() {
+    SimpleRqueueListenerContainerFactory simpleRqueueListenerContainerFactory =
+        new SimpleRqueueListenerContainerFactory();
+    simpleRqueueListenerContainerFactory.setMaxNumWorkers(workersCount);
+    simpleRqueueListenerContainerFactory.setPollingInterval(Constants.ONE_MILLI);
+    return simpleRqueueListenerContainerFactory;
+  }
+}