Titan

Titan is a lightweight message dispatch platform for real-time STOMP messaging over TCP, WebSocket, and TLS. It provides an in-memory destination queue, fanout delivery, reconnecting Java clients, Spring Boot integration, and local runtime monitoring in a standalone JVM process.

Use Titan for notifications, chat-style messaging, telemetry fanout, and live interaction backends where messages can be handled in memory. Titan is not an in-process event bus or a durable broker replacement.

Why Titan?

• STOMP without a large broker stack. Run a standalone JAR and connect using TCP or WebSocket.
• One client API. TitanClient hides the native and Vert.x implementations behind the same messaging contract.
• Connection recovery. The client reconnects after an unexpected disconnect and restores active subscriptions.
• Spring-native usage. Send with TitanTemplate and receive with @TitanListener.
• Built-in visibility. Inspect JVM and destination queue state through the local monitor API or terminal CLI.

Choose Titan when lightweight, in-memory STOMP dispatch is the goal. Choose a durable broker such as Kafka or RabbitMQ when persistence, replicated logs, clustering, or guaranteed recovery across server restarts is required.

Quick Start

1. Download the server

Titan requires JDK 21 or newer. Download the standalone JAR from GitHub Releases, or use:

curl -LO https://github.com/traffic-hunter/titan/releases/download/0.8.1/titan-server-0.8.1.jar

2. Create titan-env.yml

titan:
  monitor:
    enabled: true
    host: 127.0.0.1
    port: 7777
  servers:
    - name: stomp-dispatch
      protocol: stomp
      host: 0.0.0.0
      port: 61613
      protocol-options:
        supported-versions: "1.2"
        fanout-mode: "virtual"

3. Start Titan

java -Dtitan.environment.path=./titan-env.yml \
  -jar titan-server-0.8.1.jar

The STOMP server now listens on localhost:61613. Verify the node through the monitor endpoint:

curl http://localhost:7777/titan/monitor/health
curl http://localhost:7777/titan/monitor/snapshot

Alternatively, start the standalone server with Docker Compose:

docker compose up --build

The Compose configuration exposes STOMP on 61613 and binds the monitor API to 127.0.0.1:7777. Edit docker/titan-env.yml to change the server transport or runtime settings.

Open the terminal dashboard in a second terminal:

docker compose --profile tools run --rm titan-cli

Continue with the Java client or Spring Boot client to subscribe and send a message. The complete walkthrough is available in the Quickstart guide.

Installation

Titan artifacts are published to Maven Central.

Released container images are available from GitHub Container Registry:

docker pull ghcr.io/traffic-hunter/titan:latest
docker run --rm --name titan \
  -p 61613:61613 \
  -p 127.0.0.1:7777:7777 \
  ghcr.io/traffic-hunter/titan:latest

The image includes a container-ready default configuration. Override it when you need custom server or monitor settings:

docker run --rm --name titan \
  -p 61613:61613 \
  -p 127.0.0.1:7777:7777 \
  -v "$PWD/titan-env.yml:/etc/titan/titan-env.yml:ro" \
  ghcr.io/traffic-hunter/titan:latest

The mounted configuration must bind Titan servers and the monitor endpoint to 0.0.0.0 so Docker can publish their ports. Pin a release tag instead of latest for production deployments.

The terminal monitor is published as a separate image. Run both images on one Docker network when using the CLI without Compose:

docker network create titan
docker run --detach --name titan --network titan \
  -p 61613:61613 -p 127.0.0.1:7777:7777 \
  ghcr.io/traffic-hunter/titan:latest
docker run --rm -it --network titan \
  ghcr.io/traffic-hunter/titan-cli:latest \
  --addr http://titan:7777

repositories {
    mavenCentral()
}

For a Spring Boot application:

implementation("org.traffichunter.titan:titan-spring-client:0.8.1")

For a standalone Java client:

implementation("org.traffichunter.titan:titan-client:0.8.1")

Low-level server and extension artifacts:

Use the same 0.8.1 version for each artifact. The native client is selected by default; call implementation(TitanClient.Implementation.VERTX) on the client builder to select Vert.x without changing the messaging API.

Basic Commands

# Start the standalone server
java -Dtitan.environment.path=./titan-env.yml -jar titan-server-0.8.1.jar

# Check health and inspect a snapshot
curl http://localhost:7777/titan/monitor/health
curl http://localhost:7777/titan/monitor/snapshot

# Build and test from source
./gradlew build
./gradlew test

# Build the standalone server JAR from source
./gradlew :bootstrap:shadowJar

Prebuilt releases also contain the terminal monitor CLI:

tar -xzf titan-cli-0.8.1-linux-amd64.tar.gz
./titan --addr http://localhost:7777
./titan --addr http://localhost:7777 --view queues
./titan --addr http://localhost:7777 queue list

The same CLI is available as ghcr.io/traffic-hunter/titan-cli for Linux amd64 and arm64 containers.

See Monitoring and CLI for queue management, authentication, and platform-specific archives.

Documentation

• Quickstart
• How Titan works
• Java client
• Spring Boot client
• Server embedding
• Configuration, WebSocket, and TLS
• Monitoring and CLI

Support

• Report bugs and request features through GitHub Issues.
• Use an issue to discuss a proposed contribution before starting a large change.
• Check existing issues and documentation before opening a new report. Include the Titan version, JDK version, transport, configuration, and relevant logs when reporting a runtime problem.

Project Scope

• STOMP over TCP and WebSocket is the primary protocol surface.
• Dispatch and fanout state is currently held in memory.
• Monitoring focuses on local JVM, channel, and destination queue visibility.
• Durable storage, clustering, and replicated delivery are not current runtime guarantees.

Development

Requirements:

• JDK 21+
• Gradle wrapper (./gradlew)
• Go 1.22+ for titan-cli

Run the smoke suites separately when changing transport or Spring lifecycle behavior:

./gradlew :smoke-test:smoke-spring:test
./gradlew :smoke-test:smoke-titan:test

Contributors

Thanks to everyone who has contributed to Titan.

See the full GitHub contributors list.

License

MIT License. See LICENSE.