makina

System/component lifecycle management

Overview

Makina is a System Lifecycle Manager for Clojure. You define the components your application is made of, and the dependencies between them. And Makina takes care of starting and stopping them in the right order, and plugging them together.

Makina has two APIs, lambdaisland.makina.system is the base API. It is unopionated and flexible, it implements the basic mechanisms for system lifecycle management.

lambdaisland.makina.app is a policy namespace, it's opinionated, it assumes you follow specific conventions, and integrates with tools.namespace for smart code reloading. It uses Aero for loading config files.

Makina plays well with com.lambdaisland/config

Quickstart

(ns my.app
  (:refer-clojure :exclude [get])
  (:require
   [lambdaisland.config :as config]
   [lambdaisland.makina.app :as app]))

(def prefix "my-app")

(defonce config (config/create {:prefix prefix}))

(def get (partial config/get config))

(defonce system
  (app/create
   {:prefix prefix
    :data-readers {'config get}}))

(def load! (partial app/load! system))
(def start! (partial app/start! system))
(def stop! (partial app/stop! system))
(def refresh (partial app/refresh `system))
(def refresh-all (partial app/refresh-all `system))

(comment
  system
  (start!)
  (stop!)
  (refresh))

Then add a resources/my-app/system.edn (make sure "resources" is on the classpath).

{:my.app/first-component {:some "settings"}
 :my.app/second-component {:dep #makina/ref :my.app/first-component}}

And define handlers for your components. You have two options for this. For instance, for :my.app/first-component , you either define a var named #'my.app/first-component, or #'my.app.first-component/component

(ns my.app.first-component)

(def component 
 {:start (fn [opts] ,,,)
  :stop  (fn [v] ,,,)}

The start function receives configuration for that component from system.edn, plus some additional keys map

{:makina/id :my.app/first-component
 :makina/type :my.app/first-component
 :makina/state :stopped
 :makina/signal :start}

:stop receives the value returned from :start. If it's a map, then :makina/id, :makina/type, :makina/state, and :makina/signal are added to the map before calling :stop.

These additional keys allow you to write more generic handlers that can deal with multiple types of components.

Further reading

• Blog post with rationale
• Follow-up blog post
• Tea garden: Reloadable Component System

Installation

To use the latest release, add the following to your deps.edn (Clojure CLI)

com.lambdaisland/makina {:mvn/version "0.1.8"}

or add the following to your project.clj (Leiningen)

[com.lambdaisland/makina "0.1.8"]

Rationale

Usage

Lambda Island Open Source

Thank you! makina is made possible thanks to our generous backers. Become a backer on OpenCollective so that we can continue to make makina better.

 

makina is part of a growing collection of quality Clojure libraries created and maintained by the fine folks at Gaiwan.

Pay it forward by becoming a backer on our OpenCollective, so that we continue to enjoy a thriving Clojure ecosystem.

You can find an overview of all our different projects at lambdaisland/open-source.

 

 

Contributing

We warmly welcome patches to makina. Please keep in mind the following:

• adhere to the LambdaIsland Clojure Style Guide
• write patches that solve a problem
• start by stating the problem, then supply a minimal solution *
• by contributing you agree to license your contributions as MPL 2.0
• don't break the contract with downstream consumers **
• don't break the tests

We would very much appreciate it if you also

• update the CHANGELOG and README
• add tests for new functionality

We recommend opening an issue first, before opening a pull request. That way we can make sure we agree what the problem is, and discuss how best to solve it. This is especially true if you add new dependencies, or significantly increase the API surface. In cases like these we need to decide if these changes are in line with the project's goals.

* This goes for features too, a feature needs to solve a problem. State the problem it solves first, only then move on to solving it.

** Projects that have a version that starts with 0. may still see breaking changes, although we also consider the level of community adoption. The more widespread a project is, the less likely we're willing to introduce breakage. See LambdaIsland-flavored Versioning for more info.

License

Copyright © 2024-2025 Arne Brasseur and Contributors

Licensed under the term of the Mozilla Public License 2.0, see LICENSE.