Add Redis transport SDK for BabelQueue with publisher and consumer

Author: muhammetsafak

.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        java: [ "17", "21" ]
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: ${{ matrix.java }}
+          cache: maven
+
+      # `verify` runs the JUnit 5 suite (incl. the Redis binding conformance test)
+      # and the JaCoCo >=90% line-coverage gate. Tests mock the Redis command seam —
+      # no Redis, no network — so they run in the same job as the build.
+      - name: Test
+        run: mvn -B --no-transfer-progress verify
+
+  conformance:
+    name: Conformance suite in sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Verify vendored conformance matches the canonical suite
+        run: |
+          git clone --depth 1 https://github.com/BabelQueue/conformance.git "$RUNNER_TEMP/conformance"
+          diff -ru "$RUNNER_TEMP/conformance/manifest.json" "src/test/resources/conformance/manifest.json"
+          diff -ru "$RUNNER_TEMP/conformance/fixtures"      "src/test/resources/conformance/fixtures"
+          diff -ru "$RUNNER_TEMP/conformance/schema"        "src/test/resources/conformance/schema"
+          echo "Vendored conformance is in sync with the canonical suite."
+
+  ci-green:
+    name: CI green
+    runs-on: ubuntu-latest
+    needs: [test, conformance]
+    if: ${{ always() }}
+    steps:
+      - name: Fail if any required job did not pass
+        run: |
+          if ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}; then
+            echo "A required job failed or was cancelled."
+            exit 1
+          fi

.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    tags: [ "v*" ]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+          cache: maven
+          # Writes a settings.xml server entry `central` using the env vars below,
+          # and imports the GPG key for signing.
+          server-id: central
+          server-username: CENTRAL_TOKEN_USERNAME
+          server-password: CENTRAL_TOKEN_PASSWORD
+          gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
+          gpg-passphrase: MAVEN_GPG_PASSPHRASE
+
+      - name: Run tests
+        run: mvn -B --no-transfer-progress verify
+
+      - name: Publish to Maven Central
+        run: mvn -B --no-transfer-progress -Prelease -DskipTests deploy
+        env:
+          CENTRAL_TOKEN_USERNAME: ${{ secrets.CENTRAL_TOKEN_USERNAME }}
+          CENTRAL_TOKEN_PASSWORD: ${{ secrets.CENTRAL_TOKEN_PASSWORD }}
+          MAVEN_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

.gitignore

@@ -0,0 +1,5 @@
+target/
+*.class
+
+# CommitBrief local config and cache
+.commitbrief/

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `com.babelqueue:babelqueue-redis` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The envelope wire format is versioned separately by `meta.schema_version`
+(currently **1**) — see the contract at [babelqueue.com](https://babelqueue.com).
+
+## [1.0.0] - 2026-06-14
+
+### Added
+- Initial release. A Redis transport on `babelqueue-core` + the Lettuce client,
+  implementing §1 of the broker-bindings contract (the reliable-queue list pattern):
+  `RedisPublisher` (produce = `RPUSH` the canonical envelope JSON byte-for-byte, no
+  wrapping and no property projection — Redis lists carry no native metadata) and
+  `RedisConsumer` (reserve = `BLMOVE <queue> <queue>:processing LEFT RIGHT` so an
+  in-flight message survives a worker crash → URN-routed `BabelHandler`s → ack via
+  `LREM`; at-least-once, a throwing handler leaves the message on the processing list;
+  `onError`/`onUnknownUrn` hooks; `attempts` taken from the body unchanged since Redis
+  has no native delivery counter). Java 17, JUnit 5, Mockito, JaCoCo ≥90% line coverage
+  (currently 100%); unit tests mock the `RedisCommands` seam (no Redis, no network) and
+  capture the `RPUSH`/`BLMOVE`/`LREM` calls. The envelope is unchanged
+  (`schema_version: 1`); Redis is purely additive. This is a Java-owned reliable queue;
+  full parity with Laravel's reserved-sorted-set reservation on a shared Redis queue is
+  a separate task (broker-bindings §1.4).
+
+[Unreleased]: https://github.com/BabelQueue/babelqueue-java-redis/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/BabelQueue/babelqueue-java-redis/releases/tag/v1.0.0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammet Şafak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,89 @@
+# BabelQueue — Redis (Java)
+
+`com.babelqueue:babelqueue-redis` — a Redis transport for
+[BabelQueue](https://babelqueue.com), built on the [Lettuce](https://lettuce.io)
+client and the framework-agnostic
+[`babelqueue-core`](https://github.com/BabelQueue/babelqueue-java).
+
+A canonical-envelope **publisher** and a URN-routed **consumer**, so a Redis-based Java
+service speaks the same wire contract (envelope shape, URN identity, trace propagation)
+as the PHP/Laravel, Python, Go, Node and .NET SDKs. Implements
+[§1 of the broker-bindings contract](https://babelqueue.com) — the reliable-queue list
+pattern.
+
+## Install (Maven)
+
+```xml
+<dependency>
+  <groupId>com.babelqueue</groupId>
+  <artifactId>babelqueue-redis</artifactId>
+  <version>1.0.0</version>
+</dependency>
+```
+
+It pulls `babelqueue-core` and `io.lettuce:lettuce-core` transitively.
+
+## Use
+
+```java
+RedisClient client = RedisClient.create("redis://localhost:6379");
+RedisCommands<String, String> redis = client.connect().sync(); // the command seam
+
+// produce
+String id = RedisPublisher.create(redis, "orders")
+    .publish("urn:babel:orders:created", Map.of("order_id", 1042));
+
+// consume
+RedisConsumer consumer = RedisConsumer.builder(redis, "orders")
+    .handler("urn:babel:orders:created", (env, body) -> {
+        // env.data(), env.traceId(), env.attempts() ...
+    })
+    .onError((err, env, body) -> log.warn("bad message", err))
+    .build();
+consumer.run(); // blocking-reserves until the thread is interrupted
+```
+
+Point the `RedisClient` at any Redis (local, cluster via the appropriate client, or a
+managed instance). The command seam is Lettuce's `RedisCommands<String, String>`
+interface, so it is trivially mockable in your own tests.
+
+## Contract mapping (§1)
+
+| Envelope | Redis |
+| :--- | :--- |
+| body | the list element — the canonical envelope JSON, **byte-for-byte, no wrapping** |
+| `job` (URN) | read from the body and routed consumer-side (Redis lists carry no native metadata) |
+| produce | `RPUSH <queue> <envelope>` |
+| reserve | `BLMOVE <queue> <queue>:processing LEFT RIGHT` (head → tail; crash-safe in-flight) |
+| ack | `LREM <queue>:processing 1 <envelope>` |
+| `attempts` | taken from the body unchanged (Redis has no native delivery counter) |
+
+Redis lists have **no native attribute channel**, so — unlike the SQS/RabbitMQ/Kafka
+bindings — there is **no property projection**. The single cross-SDK invariant is
+**payload identity**: the stored element is the exact envelope bytes, with no outer
+job-structure and no added fields.
+
+Retry is **at-least-once**: a throwing handler leaves the message on the
+`<queue>:processing` list (a recovery sweep can requeue it); a successful handler `LREM`s
+it. The poll loop never stops on a bad message — observe via `onError` / `onUnknownUrn`.
+The envelope is unchanged (`schema_version` stays `1`); Redis is purely additive.
+
+> **Scope.** This is a **Java-owned reliable queue**, mirroring the Go runtime's
+> reliable-queue mechanism. Pointed at a queue this SDK owns end-to-end it is a complete,
+> crash-safe transport. **Full parity with Laravel's reserved-sorted-set reservation on a
+> _shared_ PHP+Java Redis queue is a separate task** (see broker-bindings §1.4): a
+> consumer reading a queue produced by the Laravel driver must replicate Laravel's
+> reserve/ack semantics.
+
+## Build & test
+
+```bash
+mvn verify
+```
+
+Unit tests mock the `RedisCommands` seam (no Redis, no network) and capture the
+`RPUSH`/`BLMOVE`/`LREM` calls with Mockito. JaCoCo gates the build at ≥90% line coverage.
+
+## License
+
+MIT