JAVA/Kotlin SDK

.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ 'v*' ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          cache: 'gradle'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Build and test with coverage
+        run: ./gradlew clean check
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-results
+          path: build/test-results/test/
+
+  deploy:
+    name: Deploy to Maven Central
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          cache: 'gradle'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Publish to Maven Central
+        run: ./gradlew publishAllPublicationsToMavenRepository
+        env:
+          ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
+          ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.MAVEN_CENTRAL_PASSWORD }}
+          ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.GPG_SECRET_KEY }}
+          ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.GPG_PASSPHRASE }}

.github/workflows/integration.yml

@@ -0,0 +1,41 @@
+name: Integration Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  integration:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          cache: 'gradle'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Run integration tests
+        env:
+          SA_KEY_B64: ${{ secrets.SA_KEY_B64 }}
+          STACKIT_PROJECT_ID: ${{ secrets.STACKIT_PROJECT_ID }}
+        run: ./gradlew test --tests "cloud.stackit.pubsub.sdk.integration.*"
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: integration-test-results
+          path: build/test-results/test/

.gitignore

@@ -1 +1,48 @@
-.idea
+.gradle
+build/
+!gradle/wrapper/gradle-wrapper.jar
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### IntelliJ IDEA ###
+.idea/modules.xml
+.idea/jarRepositories.xml
+.idea/compiler.xml
+.idea/libraries/
+*.iws
+*.iml
+*.ipr
+out/
+!**/src/main/**/out/
+!**/src/test/**/out/
+
+### Kotlin ###
+.kotlin
+
+### Eclipse ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+bin/
+!**/src/main/**/bin/
+!**/src/test/**/bin/
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store
+
+# Service account keys
+*.json

README.md

@@ -1 +1,131 @@
-Welcome to pubsub-java-sdk
+# pubsub-sdk-java
+
+Kotlin SDK for the **STACKIT PubSub Data Plane API**.
+
+This SDK covers the **data plane only** (publish, pull, ack, nack). Creating/deleting topics and subscriptions, and granting publisher/subscriber access, is done via the separate STACKIT PubSub **control plane** REST API or the STACKIT Portal.
+
+## Install
+
+Every GitHub Release publishes `pubsub-sdk-java` to Maven Central automatically (see `.github/workflows/ci.yml`). Once a release is cut:
+
+**Maven** (`pom.xml`):
+```xml
+<dependency>
+    <groupId>cloud.stackit.sdk</groupId>
+    <artifactId>pubsub-sdk-java</artifactId>
+    <version>1.0.0</version>
+</dependency>
+```
+
+**Gradle** (`build.gradle.kts`):
+```kotlin
+implementation("cloud.stackit.sdk:pubsub-sdk-java:1.0.0")
+```
+
+Requires JDK 21+. Runtime dependencies: `cloud.stackit.sdk:core`, `okhttp`, `gson`.
+
+## Auth
+
+Authentication goes through `AuthConfig` + `StackitAuthProvider`, backed by a STACKIT service account key.
+
+```kotlin
+import cloud.stackit.pubsub.sdk.auth.AuthConfig
+
+val authConfig = AuthConfig(
+    serviceAccountKeyPath = "sa-key.json",  // path to service account key JSON file
+    tokenEndpoint = "https://authorization.stackit.cloud/auth/token",  // default shown
+)
+```
+
+`AuthConfig` fields: `serviceAccountKey` (inline JSON string), `serviceAccountKeyPath` (file path), `privateKeyPath`, `tokenEndpoint` (default `https://authorization.stackit.cloud/auth/token`).
+
+## Environments
+
+The SDK supports three environments via the `Environment` enum:
+
+| Environment | Dataplane URL pattern |
+|-------------|----------------------|
+| `PROD` (default) | `https://{topic_id}.pubsub.{region}.onstackit.cloud` |
+| `QA` | `https://{topic_id}.pubsub.{region}.qa.onstackit.cloud` |
+| `DEV` | `https://{topic_id}.pubsub.{region}.dev.onstackit.cloud` |
+
+```kotlin
+import cloud.stackit.pubsub.sdk.config.Environment
+
+val client = PubSubClient(
+    topicId = UUID.fromString("your-topic-uuid"),
+    authConfig = authConfig,
+    environment = Environment.DEV  // use DEV environment
+)
+```
+
+## Quickstart
+
+```kotlin
+import cloud.stackit.pubsub.sdk.client.PubSubClient
+import cloud.stackit.pubsub.sdk.auth.AuthConfig
+import cloud.stackit.pubsub.sdk.models.PublishMessage
+import java.util.UUID
+
+fun main() {
+    val authConfig = AuthConfig(serviceAccountKeyPath = "sa-key.json")
+    val client = PubSubClient(
+        topicId = UUID.fromString("your-topic-uuid"),
+        authConfig = authConfig
+    )
+
+    // Publish
+    val publisher = client.getPublisher()
+    val response = publisher.publish(listOf(PublishMessage("aGVsbG8=")))  // base64-encoded "hello"
+    println(response.messageIds)
+
+    // Subscribe
+    val subscriber = client.getSubscriber(UUID.fromString("your-subscription-uuid"))
+    val messages = subscriber.pull()
+    for (msg in messages) {
+        println(msg.text)  // base64-decoded payload
+    }
+    subscriber.ack(messages.map { it.ackId })
+    // or: subscriber.nack(messages.map { it.ackId })
+}
+```
+
+`client.baseDataplaneUrl` defaults to `https://{topic_id}.pubsub.eu01.onstackit.cloud`. Override with `region` or `environment` (e.g. `environment = Environment.DEV` for `https://{topic_id}.pubsub.eu01.dev.onstackit.cloud`).
+
+`PublishMessage` takes a base64-encoded payload string. `Message.payload` (ByteArray) / `Message.text` (String) base64-decode it back.
+
+Both `PubSubPublisher` and `PubSubSubscriber` expose call counters: `publisher.messagesSent` / `.publishCalls` / `.purgeCalls`, `subscriber.pullCalls` / `.ackCalls` / `.nackCalls`.
+
+Other methods: `publisher.publishBatch(messages, batchSize = 100)`, `publisher.purgeTopic()`.
+
+## Errors
+
+All exceptions extend `PubSubAuthError` (sealed class):
+
+| Exception                    | Raised when                                                                                                                                                   |
+|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `PubSubAuthError.MissingCredentials` | No service account key configured (local validation)                                                                             |
+| `PubSubAuthError.TokenAcquisitionFailed` | HTTP 400/401/403/404/413, server errors (5xx), or token acquisition failure                                                                                               |
+|                              |                                                                                                                                             |
+
+## Retries
+
+`PubSubPublisher`/`PubSubSubscriber` retry automatically on network/timeout errors (`IOException`, `ConnectException`, `SocketTimeoutException`, `TimeoutException`) and HTTP 500/502/503/504, with exponential backoff + jitter. Configure via `retryConfig = RetryConfig(...)` passed to the publisher/subscriber constructor (or `getPublisher()`/`getSubscriber()` kwargs):
+
+```kotlin
+import cloud.stackit.pubsub.sdk.retry.RetryConfig
+
+val retryConfig = RetryConfig(maxRetries = 3, baseDelay = 500L, maxDelay = 30000L, multiplier = 2.0)
+```
+
+400/401/403/404/413 are never retried.
+
+## Examples
+
+Standalone example programs demonstrating common patterns are in [`examples/`](examples/):
+
+- `BasicExample.java` — publish/subscribe workflow
+- `ErrorHandlingExample.java` — error handling patterns
+- `BatchExample.java` — batch publishing
+- `PurgeExample.java` — topic purging
+- `RetryExample.java` — custom retry configuration