maifeeulasad/fluid-builder repository overview

⁠🌊 Fluid

🚀 A tiny but agile microservice framework built in Java 24 with first-class support for Docker 🐳, Kubernetes ☸️, and Kafka 📨 event streaming. Built for speed, scale, and simplicity.

⁠✨ Features

• ✅ Java 24-powered lightweight core
• ✅ 🔁 Kafka-based event-driven architecture
• ✅ 🐳 Docker-ready containers
• ✅ ☸️ Kubernetes-deployable out of the box
• ✅ 🔍 Minimal boilerplate, maximum flexibility
• ✅ 🔧 DIY microservice stack for builders and hackers
• ✅ 😍 100% open source

No build tool. There is no Maven or Gradle step to ship a service. Your .java files are copied into the image and compiled at container start.

⁠📚 Libraries

⁠Bundled by default

Fetched automatically at container start — nothing to add to your pom.xml:

⁠Fetched on demand

One environment variable, no pom.xml change: FLUID_METRICS=prometheus pulls in the Prometheus client (see 📊 Metrics, below); selecting snappy, lz4 or zstd compression needs its own jar too (see ⚙️ Configuration below).

⁠Supported via your own pom.xml

Fluid has no opinion on how a service talks to a database — add the driver or ORM you want and it is fetched the same way everything else is. Demonstrated end to end, with Docker Compose and CI, in fluid-example⁠:

⁠📦 Getting Started

A service is a Dockerfile, a pom.xml listing your dependencies, and your Java files. Nothing else.

FROM maifeeulasad/fluid-builder:latest

COPY pom.xml .
COPY *.java .

At container start Fluid downloads the dependencies your pom.xml names, compiles your sources, finds your listeners, and starts consuming.

⁠Write a listener 🎧

Any class with an annotated method is picked up — the file name does not matter.

public class MessageService {

    @KafkaListener(topic = "orders", groupId = "order-processors")
    public void handleOrder(String message) {
        System.out.println("📥 " + message);
    }
}

⁠Send messages 📤

To write a producer instead of a consumer, supply your own Fluid.java. It replaces the framework's entry point.

public class Fluid {
    public static void main(String[] args) throws InterruptedException {
        try {
            for (int i = 0; i < 1000; i++) {
                KafkaMessenger.sendMessage("orders", "Message " + i);
            }
        } finally {
            KafkaMessenger.shutdown();
        }
    }
}

⁠🧩 Annotations

⁠@KafkaListener — the common case

@KafkaListener(topic = "orders", groupId = "order-processors")
public void handleOrder(String message) { }

⁠@KafkaSubscription — full control

Same job, with batching, dead letter routing, topic creation and consumer tuning. Use it when you need one of those; @KafkaListener otherwise.

@KafkaSubscription(
    topic = "orders",
    groupId = "order-processors",
    partitions = 5,
    batchEnabled = true,
    enableDeadLetterQueue = true,
    deadLetterTopic = "order-errors",
    maxPollRecords = 100
)
public void handleOrder(String message) { }

Some attributes are accepted but not yet honoured — each is marked not yet honoured in its javadoc, so a setting that does nothing says so rather than pretending.

A method may carry @KafkaListener or @KafkaSubscription, not both: each drives its own consumer, so the handler would run twice per record. Startup rejects it.

⁠@SendTo — forward the result

@KafkaListener(topic = "orders", groupId = "order-processors")
@SendTo(topic = "processed-orders")
public String handleOrder(String message) {
    return "Processed: " + message;
}

⁠@ShortCircuit — route failures

@KafkaListener(topic = "orders", groupId = "order-processors")
@ShortCircuit(topic = "order-errors")
public void handleOrder(String message) {
    if (message.contains("fail")) {
        throw new RuntimeException("bad message");
    }
}

⁠⚙️ Configuration

gzip is the default because it is the only compressing codec that works with the dependency set Fluid downloads. snappy, lz4 and zstd need third-party libraries that kafka-clients does not bundle — select one and Fluid tells you which library to add rather than failing later at send time.

⁠📊 Metrics

Off by default. Set one variable and the backend's jars are fetched at container start — nothing to add to your pom.xml, and an image that does not use metrics stays exactly as small as before.

environment:
  - FLUID_METRICS=prometheus

Then scrape http://your-service:9400/metrics.

Everything is named fluid_*, and the prefix is enforced rather than merely documented:

fluid_messages_consumed_total{topic,group,handler}
fluid_messages_produced_total{topic}
fluid_handler_duration_seconds{handler}
fluid_handler_failures_total{handler,topic}
fluid_partition_rewinds_total{topic,partition}

⁠Producers that exit

A pull-based scrape cannot observe a process that has already stopped. A batch producer that sends and exits may never be scraped at all.

Point it at a Pushgateway and it pushes on shutdown, whatever entry point it uses:

environment:
  - FLUID_METRICS=prometheus
  - FLUID_METRICS_PUSHGATEWAY=pushgateway:9091

Scrape the gateway with honor_labels: true, or Prometheus rewrites every pushed series to the gateway itself and all your producers collapse into one.

⁠Routes you can take, and routes you have taken

At start-up Fluid works out every route your service can take, before it takes any — from @KafkaListener, @SendTo and @ShortCircuit, and by parsing your sources for direct KafkaMessenger.sendMessage("topic", ...) calls.

fluid_route_declared{from,to,type,dynamic}          1 for every possible route
fluid_route_traversed_total{from,to,type,dynamic}   times it actually carried a message

A route with declared=1 and no traversals is a path that exists but has never been used. A topic computed at runtime cannot be known in advance, so it is marked dynamic="true" and appears only once used — which is why the two cases are distinguishable rather than both looking like absence.

⁠🛠️ Architecture

[Your Producer] ──▶ KafkaMessenger ──▶ [Kafka Broker] ──▶ MessageConsumer ──▶ [Your Listener]
                    MessageProducer                       KafkaProcessor

• 🧩 Handlers are found by annotation at startup, not by file name
• 🧵 Records are handled on the poll thread, so per-partition order holds
• ✅ Offsets are committed only after a record has been processed
• 🛑 A failing handler leaves its partition uncommitted and rewinds to retry, rather than committing past the failure

⁠🧪 Building and testing

Run it the way it ships:

java DependencyDownloader.java   # populates lib/
java -cp "lib/*" Fluid.java

Run the tests:

mvn test

Maven exists for tests, linting and CI only — its output is never shipped, and it compiles the same flat sources in place. See DEVELOPMENT.md.

⁠🔏 Image attestations

Every tag published to Docker Hub (latest, the date tag, and the commit tag) carries build provenance and an SBOM, attached as attestation manifests alongside the image rather than documented separately — so they can't silently go stale. The publish workflow refuses to push an image that fails its own smoke test first.

Verify either with Buildx, no pull required:

docker buildx imagetools inspect maifeeulasad/fluid-builder:latest

or inspect the SBOM's actual package list with Docker Scout⁠:

docker scout sbom maifeeulasad/fluid-builder:latest

⁠📚 Examples

Runnable, docker-composed examples — Kafka producers/consumers, and database read/write with and without an ORM — live in fluid-ecosystem/fluid-example⁠, built against this image.

⁠🔮 Roadmap

• 🛑 Graceful shutdown hooks
• 🔁 At-least-once delivery with per-partition ordering
• 💀 Dead letter routing
• 📊 Metrics (Prometheus), pull and Pushgateway, declared vs. traversed routes
• 🗺️ Service topology visualization — see dashboard⁠
• 📚 Example suite: Kafka (basic + full API), Postgres (JDBC + Hibernate), MongoDB, H2 — see fluid-example⁠
• 💾 Configuration via fluid.yaml
• 🧠 Built-in retry and backoff strategy — @KafkaSubscription accepts the attributes, not yet honoured
• 🔀 Parallel handling that preserves per-partition order — preserveOrder, not yet honoured

⁠🤝 Contributing

PRs are welcome! Open an issue or suggest an improvement — let's make microservices fun and fast again 🧪

⁠📜 License

MIT License © 2026 Maifee Ul Asad