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.

⁠📦 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.

⁠🛠️ 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.

⁠🔮 Roadmap

• 🛑 Graceful shutdown hooks
• 🔁 At-least-once delivery with per-partition ordering
• 💀 Dead letter routing
• 📊 Metrics (Prometheus or Micrometer)
• 💾 Configuration via fluid.yaml
• 🧠 Built-in retry and backoff strategy
• 🔀 Parallel handling that preserves per-partition order

⁠🤝 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