system
Reloaded components à la carte

Two minimal projects that will help you get started. Both the Leiningen and Boot toolchain are covered.

A web service written multiple times using different styles.

• System map is accessed directly. https://github.com/danielsz/system-advanced-example
• Dependency injection, Duct abstractions and other known techniques. https://github.com/danielsz/system-dependency-injection

A web application with client-side UI. Demonstrates login procedure with Sente (a realtime web comms library).

• https://github.com/danielsz/system-websockets

A Ring application is composed with separate API and site middleware.

• Applying separate middleware to corresponding routes. https://github.com/danielsz/system-api-example
• Running multiple handlers separately. https://github.com/danielsz/system-api-immutant-example

A convenience macro, defsystem, allows you to declare systems succinctly:

(ns my-app.systems
  (:require
   [system.core :refer [defsystem]]
   (system.components
    [jetty :refer [new-web-server]]
    [repl-server :refer [new-repl-server]]
    [datomic :refer [new-datomic-db]]
    [mongo :refer [new-mongo-db]])
   [my-app.webapp :refer [handler]]
   [environ.core :refer [env]]))

(defsystem dev-system
  [:datomic-db (new-datomic-db (env :db-url))
   :mongo-db (new-mongo-db)
   :web (new-web-server (env :http-port) handler)])

(defsystem prod-system
  [:datomic-db (new-datomic-db (env :db-url))
   :mongo-db (new-mongo-db (env :mongo-url))
   :web (new-web-server (env :http-port) handler)
   :repl-server (new-repl-server (env :repl-port))])

Note: Component allows you to define dependency relationships within systems. Please don’t use said macro for those cases. Be sure to consult component’s API to see the range of options available to you.

At runtime, the system var can be used anywhere after requiring it from the system.repl namespace:

(ns front-end.webapp.handler
 (:require [system.repl :refer [system]]))

(code-using system ...)

Note this pattern of directly accessing the global system var is in contrast with the pattern of dependency injection integral to Stuart Sierra's vision of Component. In this perspective, components are defined in terms of the components on which they depend. system, as a repository of readymade, reusable components, cannot and does not anticipate all the possible ways in which users will want to assemble components together. What it can and does, however, is anticipate common scenarii. Like your typical Ring application, for example, where you may want to inject the database in the routes, so that it is readily available when serving http requests.

system ships with a web framework, Raamwerk, inspired by the Duct framework: the endpoint, middleware and handler components. The endpoint component returns routes that are closed over by the component passed to it, so that its constituents are accessible via standard map destructuring. The rationale for this is explained here. If the previous sentence didn’t sound agreeable, I suggest you check out the wiki and the examples.

The ability to decompose a web application in mulitple endpoints offers flexibility and opportunies of reuse. For example, you can isolate functionality in library projects, and join the endpoints in the target application’s unified handler. The possibilities are numerous.

Documentation for Raamwerk’s components is available.

As with many patterns, DI can be abused. It is easy to get carried away with dependency injection and build a towering dependency graph that is unnecessary and even counter-productive. — Ben Morris in How not to use dependency injection: service locators and injection mania.

Whatever you do, use your best judgment.

In traditional Lisp systems, users can redefine arbitrary, discrete units of code. Clojure, as a Lisp, is no exception. However, as a hosted language with many advanced dynamic features, code reloading has many pitfalls. tools.namespace fixes many of them, but ultimately, reloaded code will not agree with runtime state, and the system will need a full restart. This is where component fits in. (Note that both libraries were authored by Stuart Sierra).

It is important to understand that code reloading and system restarts are orthogonal—both are desirable properties in a programming environment. A full restart is a blunt tool. No need to restart the database just because a helper function was modified.

We don’t want to restart the system with every code change. Ideally, we want to only reload the code that has changed, and occasionally restart (when necessary).

boot-system gives you finegrained tuning over system restarts vs code reload. Each time you change a file, boot-system will reload your code. Conversely, filenames that have been designated in the files option will trigger a full restart. Typically, the files vector will be small, as most modifications do not warrant a full restart. An example of when you would want a full restart is when you modify a Var that is used in a thread (that of a web server, for example). This is explained in detail in the Ghosts in the machine blog post. Check the options with boot system -h.

In summary, when you instruct boot-system to manage your application lifecycle (with the auto option), either one of those two things will happen after you change a source file:

• refresh will first unload all affected namespaces (to remove old definitions) before reloading them in dependency order.
• reset will restart the system if that file was defined in the files vector.

With system, you can enjoy a true Lisp environment where code is always live (live coding). A tutorial is available in a separate repository. It is dubbed the Holy Grail, because the solution encompasses back-end and front-end. Some people like to start off from the setup in that repo as a fast track for clj/cljs combo projects. For them, Akash Shakdwipeea has made a Boot template available.

If you are using Leiningen, we recommend Figwheel to address browser-side hot-reloading concerns.

My Clojure Workflow, Reloaded

I gave a talk at several Clojure user groups (Belgium, Spain, Israel). BeClojure did a great job at recording it and making it available on Youtube. Mattias Buelens also produced a very nice interactive UI for the BeClojure talk.

And more references touching on the topic.

• Clojure in the Large
• Retrofitting the Reloaded pattern into Clojure projects
• 5 faces of dependency injection in Clojure
• REPL functions to support the reloaded workflow

To help choose if system is right for you, here are a couple of tips. Take a component for an often used dependency (a web server, for example, or a database), and compare their source code. The system library puts an emphasis on two properties:

• minimalism: system provides a way to instantiate components that fulfill the Licecycle protocol (start and stop). Nothing more, nothing less.
• Interactive programming: system is best used in a Lispy, interactive workflow, hence its deep integration with boot.