Abstract:

This presentation by Wout Mertens introduces "Mailman," a flexible and highly testable Clojure library designed for building event-driven applications. Born from the need for a maintainable event-handling solution during the development of the Monkeyci CI/CD tool, Mailman provides an abstraction layer over underlying message brokers like JMS and NATS.

The library's architecture is inspired by familiar HTTP frameworks, featuring a central router that dispatches events to specific handlers. It heavily leverages Pedestal's interceptor pattern, allowing developers to manage side effects, validation, and other cross-cutting concerns through a chain of functions that manipulate a shared context map. Key design principles include broker independence, flexibility over rigid frameworks, and a strong emphasis on testability. A standout feature is the ability to easily replace interceptors in tests, enabling the isolation of business logic from slow or unpredictable side effects. The presentation concludes with a live coding session demonstrating these concepts, including how a handler's return value is automatically treated as new events to be published, simplifying complex event-driven workflows.

A Deep Dive into Mailman: A Testable, Event-Driven Clojure Library

• 0:01:34 Motivation and Design Goals: The library was created to address the challenges of building maintainable, testable, event-driven applications. Its core design goals are to be highly testable, feel familiar to developers accustomed to HTTP frameworks, remain independent of the underlying message broker, and offer flexibility like a toolbox rather than a restrictive framework.
• 0:06:57 Core Concepts: Mailman is built on a few key concepts:
  • Event Poster & Receiver: Simple protocols for sending and receiving events from a broker.
  • Listener: An object that connects a handler to an event source.
  • Router: Dispatches incoming events to the correct handlers, similar to routing in an HTTP library. By default, it matches events based on their :type key.
• 0:10:28 Handler Return Value as New Events: A key design choice in Mailman is that the return value of an event handler is interpreted as a collection of new events. These events are automatically posted back to the broker, simplifying the creation of event chains and workflows.
• 0:18:40 Interceptors for Side Effects: Mailman uses Pedestal's interceptor model to manage application logic. Handlers are wrapped in an interceptor chain where each link can modify a central context map. This is the recommended way to handle side effects, add logging, perform validation, or inject dependencies like database connections.
• 0:25:09 Broker Implementations: The library provides a thin abstraction layer over various messaging systems. Current implementations include JMS, NATS, Manifold (for in-process asynchronous messaging), and a simple in-memory broker ideal for testing.
• 0:29:48 A Strong Focus on Testability: Mailman is designed to make testing easy. While handlers can be unit-tested as pure functions, the library provides a replace-interceptors function to test the entire routing and processing logic. This allows developers to swap out interceptors that perform slow or side-effect-heavy operations (e.g., database calls, external API requests) with fast, predictable fakes.
• 0:32:33 Practical Broker Configuration: The presentation shows how the JMS implementation handles real-world requirements. A destination-mapper function is used to dynamically determine the correct topic or queue for an outgoing event based on its content. Listeners, in turn, specify which destination they subscribe to. The library also handles serialization via codecs, defaulting to EDN.
• 0:43:02 Live Demo: Testing with Fakes: The live coding session demonstrates how to use replace-interceptors to test a router. A "slow" interceptor that simulates a network call is replaced with a fake one that returns a fixed value, allowing for a fast and deterministic test of the application logic.
• 0:46:36 Live Demo: Full JMS Workflow: The demo concludes by connecting to a live ArtemisMQ (JMS) broker. It shows an event being posted to an "in" topic, processed by a handler, which then returns a new event that is automatically routed and sent to an "out" topic, where it is picked up by a second listener.