Initial release: Apache ActiveMQ Artemis JMS transport on babelqueue-core

Author: muhammetsafak

.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+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 and the JaCoCo >=90% line-coverage gate. The JMS
+      # interfaces (Session/Producer/Consumer/Message) are mocked with Mockito — no Artemis,
+      # no network.
+      - name: Test
+        run: mvn -B --no-transfer-progress verify
+
+  ci-green:
+    name: CI green
+    runs-on: ubuntu-latest
+    needs: [test]
+    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,2 @@
+target/
+*.class

CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to `com.babelqueue:babelqueue-artemis` 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-13
+
+### Added
+- Initial release. An Apache ActiveMQ Artemis transport on `babelqueue-core` over **JMS**
+  (Jakarta Messaging 3.x), implementing §7 of the broker-bindings contract. Artemis offers
+  native ack/scheduled-delivery/delivery-counter/dead-letter-address, so the binding maps onto
+  them rather than re-implementing: `ArtemisPublisher` (body = canonical envelope `TextMessage`,
+  `JMSType` = URN, `JMSCorrelationID` = `trace_id`, the `bq-` string-property projection — so a
+  JMS or AMQP-1.0 consumer routes on `JMSType`; a delay uses native JMS 2.0 `setDeliveryDelay`)
+  and `ArtemisConsumer` (`CLIENT_ACKNOWLEDGE` consume — acknowledge after success; a throwing
+  handler `recover()`s the session for broker redelivery; **`attempts = max(body,
+  JMSXDeliveryCount − 1)`** with the broker's 1-based counter authoritative; terminal failures
+  go to `<queue>.dlq` with the additive `dead_letter` block; `fail`/`delete`/`release`/
+  `dead_letter` unknown-URN strategies; poison bodies forwarded raw to the DLQ). Java 17, JUnit
+  5, JaCoCo ≥90% line coverage; the JMS interfaces are mocked with Mockito (no Artemis, no
+  network). The envelope is unchanged (`schema_version: 1`); Apache ActiveMQ Artemis is purely
+  additive.

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,121 @@
+# BabelQueue — Apache ActiveMQ Artemis (Java)
+
+`com.babelqueue:babelqueue-artemis` — an Apache ActiveMQ Artemis transport for
+[BabelQueue](https://babelqueue.com), built on **JMS** (Jakarta Messaging 3.x) and the
+framework-agnostic [`babelqueue-core`](https://github.com/BabelQueue/babelqueue-java).
+
+A canonical-envelope **publisher** and a URN-routed, `CLIENT_ACKNOWLEDGE` **consumer**, so an
+Artemis-based Java service speaks the same wire contract (envelope shape, URN identity, trace
+propagation) as the .NET, Python, Go and Node SDKs. Implements
+[§7 of the broker-bindings contract](https://babelqueue.com/docs/spec/1.x/broker-bindings#apache-activemq-artemis).
+
+Unlike Kafka, Artemis gives the binding **native** primitives — per-message acknowledgement,
+scheduled delivery, a delivery counter and a dead-letter address — so this transport maps onto
+them instead of re-implementing them (the envelope stays `schema_version: 1`):
+
+- the envelope JSON is the message **body** (`TextMessage`); the contract fields are mirrored
+  onto JMS metadata — `JMSType` = URN, `JMSCorrelationID` = `trace_id`, `JMSTimestamp` =
+  `created_at` — plus the `bq-` string properties (so a JMS **or** AMQP-1.0 consumer routes on
+  `JMSType` without decoding the body);
+- consume is `CLIENT_ACKNOWLEDGE`: **acknowledge after success**; a throwing handler leaves the
+  message unacknowledged and `recover()`s the session so the broker redelivers it (incrementing
+  `JMSXDeliveryCount`);
+- **`attempts = max(body, JMSXDeliveryCount − 1)`** — `JMSXDeliveryCount` is the broker's
+  1-based authoritative redelivery counter, the body's `attempts` the floor;
+- delay uses **native** JMS 2.0 scheduled delivery (`setDeliveryDelay`); terminal failures go to
+  an opt-in `<queue>.dlq` carrying the canonical envelope plus the additive `dead_letter` block,
+  cross-language alongside Artemis's own dead-letter address.
+
+## Install (Maven)
+
+```xml
+<dependency>
+  <groupId>com.babelqueue</groupId>
+  <artifactId>babelqueue-artemis</artifactId>
+  <version>1.0.0</version>
+</dependency>
+```
+
+It pulls `babelqueue-core` transitively. The JMS API is `provided`-style — bring your Artemis
+JMS client (`org.apache.activemq:artemis-jakarta-client`), which supplies both the
+`jakarta.jms` API and the broker connection.
+
+## Produce
+
+```java
+ConnectionFactory factory = new org.apache.activemq.artemis.jms.client.ActiveMQJMSConnectionFactory(
+    "tcp://localhost:61616");
+
+try (JMSContext ctx = factory.createContext("user", "pass")) {
+    Session session = ctx.createSession(Session.CLIENT_ACKNOWLEDGE);
+    MessageProducer producer = session.createProducer(session.createQueue("orders"));
+
+    String id = ArtemisPublisher.create(session, producer)
+        .publish("urn:babel:orders:created", Map.of("order_id", 1042));
+}
+```
+
+`publish(urn, data)` returns the message `meta.id`; overloads add a `traceId` and a relative
+`Duration delay` (native `setDeliveryDelay`).
+
+## Consume
+
+```java
+Session session = connection.createSession(false, Session.CLIENT_ACKNOWLEDGE);
+MessageConsumer consumer = session.createConsumer(session.createQueue("orders"));
+MessageProducer dlqProducer = session.createProducer(null); // anonymous, for <queue>.dlq
+
+ArtemisConsumer worker = ArtemisConsumer.builder(consumer, session)
+    .handler("urn:babel:orders:created", (env, message) -> {
+        // env.data(), env.traceId(), env.attempts() ...
+    })
+    .deadLetterQueue(dlqProducer, "orders.dlq")
+    .maxTries(3)
+    .onError((err, env, message) -> err.printStackTrace())
+    .build();
+
+connection.start();
+worker.run(() -> true); // receive → process → acknowledge, until you stop it
+```
+
+A successful handler `acknowledge()`s the message. A throwing handler leaves it unacknowledged
+and `recover()`s the session, so the broker redelivers it and bumps `JMSXDeliveryCount`; once
+`maxTries` is reached the envelope goes to `<queue>.dlq` with a `dead_letter` block. The consumer
+routes on `JMSType`, so it never decodes a message it cannot handle. Unknown-URN strategy is one
+of `fail` / `delete` / `release` / `dead_letter`.
+
+> One message per `poll()` keeps the session-wide `acknowledge()` / `recover()` correct. A JMS
+> session is single-threaded — run one `ArtemisConsumer` per thread.
+
+## Contract mapping (§7)
+
+| Envelope | Apache ActiveMQ Artemis (JMS) |
+| :--- | :--- |
+| body | message body (`TextMessage`, byte-identical across SDKs) |
+| `job` (URN) | `JMSType` (consumer routes on this) |
+| `trace_id` | `JMSCorrelationID` |
+| `meta.id` | `JMSMessageID` (broker-set for JMS; body is authoritative) |
+| `meta.schema_version` | property `bq-schema-version` (`"1"`) |
+| `meta.lang` | property `bq-source-lang` |
+| `meta.created_at` | `JMSTimestamp` (Unix ms) |
+| `attempts` | `max(body, JMSXDeliveryCount − 1)` (broker counter is 1-based) |
+| reserve / ack | `receive` → process → **`acknowledge()`** (CLIENT_ACKNOWLEDGE) |
+| retry / delay | `recover()` redelivery · native `setDeliveryDelay` |
+| dead-letter | `<queue>.dlq` + `dead_letter` block (alongside the native DLA) |
+
+The `bq-` property values are strings (integers as decimal, e.g. `"1"`); `bq-app-id` is
+`"babelqueue"`. The envelope is unchanged (`schema_version` stays `1`); Artemis is purely
+additive.
+
+## Build & test
+
+```bash
+mvn verify
+```
+
+The JMS interfaces (`Session`, `MessageProducer`, `MessageConsumer`, `Message`) are mocked with
+Mockito — no Artemis, no network. JUnit 5, JaCoCo ≥90% line coverage.
+
+## License
+
+MIT