Skip to content

Mongoose Server

Mongoose Server is a high‑performance, event‑driven library for building scalable event processing applications fast. It wires sources, processors, sinks, and services for you, handling threading and lifecycle behind the scenes, so you can focus on business logic.

Its plugin architecture lets you assemble pipelines from reusable components, including third‑party plugins from the broader ecosystem. You can mix and match existing sources, transforms, and sinks, add your own logic where needed, and get to a working system quickly without reinventing common building blocks.

Mongoose is an embeddable library: run multiple server instances inside a parent JVM application, or deploy it as a standalone single‑server app — the same APIs support both.

Why Mongoose Server?

  • Process multiple event feeds: Merge data from many real-time sources and process in a single-threaded application handler.
  • Build business logic fast: minimal learning curve, with no need to worry about threading, concurrency, or lifecycle.
  • Performance: Agent‑based concurrency with configurable idle strategies enables very high throughput and predictable latency.
  • Ease of development: Compose processors and services, configured via YAML or Java with built‑in service injection.
  • Plugin architecture: Clean extension points for event feeds, sinks, services, and dispatch strategies so you can tailor the runtime.
  • Plugin ecosystem: community plugins, including support for Kafka, Aeron, Chronicle, and more.
  • Zero‑GC: Built-in object pooling to support zero‑GC event processing.
  • Operational control: Admin commands, scheduling, logging/audit support, and dynamic event handler registration make operational control simpler.

Performance at a glance

  • At 1 million messages/second, latency statistics:
    • Avg ≈ 270 nanos (0.00027 ms), p99.999 ≈ 81 µs, Max ≈ 90.1 µs.
  • Sustained 10 million messages/second with Zero‑GC.
  • See detailed results in the benchmarks report: Server benchmarks and performance.

Build coordinates

<dependencies>
    <dependency>
        <groupId>com.telamin</groupId>
        <artifactId>mongoose</artifactId>
        <version>1.0.5</version>
    </dependency>
</dependencies>

implementation 'com.telamin:mongoose:1.0.5'

Quickstart: Hello Mongoose

Run the one-file example to see events flowing through a handler:

Micro Glossary:

  • Event feed: A source of events (e.g., in‑memory, file, Kafka).
  • Processor: Executes your handler on its own agent thread.
  • Handler: Your business logic function that receives events.
  • Agent: A named execution thread with a configurable idle strategy.
  • Idle strategy: Controls how an agent waits (e.g., BusySpin for ultra‑low latency).
  • Broadcast: When true, each event is delivered to all processors.

Example code:

public static void main(String[] args) {
    // 1) Business logic handler
    Consumer<Object> handler = event -> System.out.println(
            "thread:'" + Thread.currentThread().getName() + "' event: " + event);

    // 2) Create an in-memory event feed (String payloads)
    var feed = new InMemoryEventSource<String>();

    // 3) Build and boot mongoose server with an in-memory feed and handler using builder APIs
    var eventProcessorConfig = EventProcessorConfig.builder()
            .handlerFunction(handler)
            .name("hello-handler")
            .build();

    // 4) Wire the feed on its own agent with a busy-spin idle strategy (lowest latency)
    var feedConfig = EventFeedConfig.<String>builder()
            .instance(feed)
            .name("hello-feed")
            .broadcast(true)
            .agent("feed-agent", new BusySpinIdleStrategy())
            .build();

    // 5) Build the application config and boot the mongooseServer
    var app = MongooseServerConfig.builder()
            .addProcessor("processor-agent", eventProcessorConfig)
            .addEventFeed(feedConfig)
            .build();

    // 6) boot an embedded MongooseServer instance
    var mongooseServer = MongooseServer.bootServer(app);

    // 7) Publish a few events
    System.out.println("thread:'" + Thread.currentThread().getName() + "' publishing events\n");
    feed.offer("hi");
    feed.offer("mongoose");

    // 8) Cleanup (in a real app, keep running)
    mongooseServer.stop();
}

Expected output

thread:'main' publishing events

thread:'processor-agent' event: hi
thread:'processor-agent' event: mongoose

Learning path

Mongoose examples

GitHub repository mongoose-examples.

Documentation is organized into the following sections:

  • Start with the Overview to learn concepts and architecture.
  • See Event processing where business logic meets event handling.
  • See Examples for quick hands-on guidance.
  • See Plugins for advice on writing plugins.
  • Use How-to guides for common tasks and extensions.

Architecture and threading model for internals

If you find an issue or want to improve the docs, click “Edit this page” in the top right or open a PR on GitHub.