The hipstr.util namespace is a simple namespace where you can put various helper functions you find yourself frequently using during the development of your application. Out of the box, Luminus generates a hipstr.util namespace with a single function, md->html, which converts markdown into HTML. Typically, I try to avoid namespaces such as util.clj because they eventually turn into the junk drawer in your kitchen, but they can be useful on smaller projects if things don't get too crowded. The following block of code shows the hipstr.util namespace:

(ns hipstr.util
  (:require [noir.io :as io]
            [markdown.core :as md]))

(defn md->html
  "reads a markdown file from public/md and returns an HTML
   string"
  [filename]
  (md/md-to-html-string (io/slurp-resource filename)))

One of lib-noir's exposed functionalities is session management (which we'll discuss in detail in Chapter 10, Sessions and Cookies). The default session pool in Luminus is an in-memory session pool, a shortcoming of which is that expired sessions are only removed from memory when the server handles a request associated with an expired session. As a result, old stale sessions can linger in memory indefinitely, straining memory resources on the server. Luminus boilerplates a cronj job in the hipstr.sessions-manager namespace, which occasionally removes stale, unused sessions. By default, the job runs every 30 minutes. Take a look at the following lines of code:

(ns hipstr.session-manager
  (:require [noir.session :refer [clear-expired-sessions]]
            [cronj.core :refer [cronj]]))

(def cleanup-job
  (cronj
    :entries
    [{:id "session-cleanup"
      :handler (fn [_ _] (clear-expired-sessions))
      :schedule "* /30 * * * * *"
      :opts {}}]))

The hipstr.layout namespace houses the functions that are used to render the HTTP response body. By default, Luminus creates a single function, render, which will render any Selmer template onto the HTTP response.The following lines of code is for the hipstr.layout namespace:

(ns hipstr.layout
  (:require [selmer.parser :as parser]
            [clojure.string :as s]
            [ring.util.response :refer [content-type response]]
            [compojure.response :refer [Renderable]]
            [environ.core :refer [env]]))

(def template-path "templates/")

(deftype RenderableTemplate [template params]
  Renderable
  (render [this request]
    (content-type
      (->> (assoc params
        (keyword
        (s/replace template #".html" "-selected"))"active"
          :dev (env :dev)
            :servlet-context
              (if-let [context (:servlet-context request)]
              ;; If we're not inside a serlvet environment
              ;; (for example when using mock requests), then
              ;; .getContextPath might not exist
              (try (.getContextPath context)
                (catch IllegalArgumentException _ 
                context))))
            (parser/render-file (str template-path template))
           response)
          "text/html; charset=utf-8")))

(defn render [template & [params]]
(RenderableTemplate. template params))

The key to the hipstr.layout namespace is that it remains high level and generic. You should avoid writing functions with domain knowledge in this namespace, and instead focus on generating response bodies. If you put an explicit URL or filename in this namespace, you're probably doing it wrong.

Middleware, for the unfamiliar, is a function that can work with an incoming request prior to the request being handled by the main application (that is our proverbial business logic). Its function is similar to how a car moves through an assembly line; each employee working the line is responsible for interacting with the car in some specific way. Much like how at the end of the assembly line the car is in its final state and ready for consumption, so is the request in its final state and ready for processing by the main application. The following code is for the hipstr.middleware namespace:

(ns hipstr.middleware
  (:require [taoensso.timbre :as timbre]
            [selmer.parser :as parser]
            [environ.core :refer [env]]
            [selmer.middleware :refer [wrap-error-page]]
            [prone.middleware :refer [wrap-exceptions]]
            [noir-exception.core :refer [wrap-internal-error]]))

(defn log-request [handler]
  (fn [req]
    (timbre/debug req)
    (handler req)))

(def development-middleware
  [wrap-error-page
   wrap-exceptions])

(def production-middleware
  [#(wrap-internal-error % :log (fn [e] (timbre/error e)))])

(defn load-middleware []
  (concat (when (env :dev) development-middleware)
          production-middleware))

The hipstr.middleware namespace has two primary responsibilities. The first is that it ties together all the different middleware we want across any of our runtime environments. The second is that it gives us a place to add additional middleware, if desired. Of course, there's nothing prohibiting us from writing our middleware in a new namespace, but for the sake of simplicity and for this book, we'll simply create additional middleware in the hipstr.middleware namespace.

One of the directories that Luminus generated was a route folder. Routes are what tie a request to a specific handler (or, in layman's terms, a chunk of code to be executed based on the URL the request is sent to). Luminus generates 2 routes for us:

Take a look at the following lines of code:

(ns hipstr.routes.home
  (:require [compojure.core :refer :all]
            [hipstr.layout :as layout]
            [hipstr.util :as util]))

(defn home-page []
  (layout/render
    "home.html" {:content (util/md->html "/md/docs.md")}))

(defn about-page []
  (layout/render "about.html"))

(defroutes home-routes
  (GET "/" [] (home-page))
  (GET "/about" [] (about-page)))

We will create a couple of our own routing namespaces over the course of this book. The routes we'll create in those namespaces will follow the same pattern demonstrated in the preceding hipster.routes.home namespace. We'll talk a bit more about routes in Chapter 4, URL Routing and Template Rendering.

Everything we've seen in this chapter is brought together into a single, harmonious, running application in the hipstr.handler namespace, explained in the following lines of code. Opening the file for a cursory scan reveals our cron job to clean up expired sessions, the home-routes from the hipstr.routes.home namespace, the configuration of our Timbre logging, and so on.

(ns hipstr.handler
  (:require [compojure.core :refer [defroutes]]
    ; ... snipped for brevity …
    [cronj.core :as cronj]))

(defroutes base-routes
  (route/resources "/")
  (route/not-found "Not Found"))

(defn init
  "init will be called once when
    app is deployed as a servlet on
    an app server such as Tomcat
    put any initialization code here"
  []
  ;… snipped for brevity …)

(defn destroy
  "destroy will be called when your application
   shuts down, put any clean up code here"
  []
  ; ... snipped for brevity ...)

;; timeout sessions after 30 minutes
(def session-defaults
  {:timeout (* 60 30)
   :timeout-response (redirect "/")})

(defn- mk-defaults
       "set to true to enable XSS protection"
       [xss-protection?]
       ;... snipped for brevity ...
)

(def app (app-handler
            ;; add your application routes here
            [home-routes base-routes]
            ;; add custom middleware here
            :middleware (load-middleware)
            :ring-defaults (mk-defaults false)
            ;; add access rules here
            :access-rules []
            ;; serialize/deserialize the following data formats
            ;; available formats:
            ;; :json :json-kw :yaml :yaml-kw :edn :yaml-in-html
            :formats [:json-kw :edn :transit-json]))

We'll get into detail about what all is happening, and when, in Chapter 2, Ring and the Ring Server.

The last Luminus generated namespace, hipstr.repl, is one that often confuses beginners because it's strikingly similar to hipster.handler. The hipstr.repl namespace has a start-server and stop-server function, much like hipster.handler. However, hipstr.repl allows us to start and stop our development server from the Clojure REPL. This might seem like a weird thing to do, but by running our server from the REPL we can modify our running system and the changes will be "automagically" reloaded in our server. No need for the time consuming and frustrating "compile-deploy-restart-grab-a-coffee-and-twiddle-your-thumbs cycle!"

(ns hipstr.repl
  (:use hipstr.handler
        ring.server.standalone
        [ring.middleware file-info file]))

(defonce server (atom nil))

(defn get-handler []
  ;; #'app expands to (var app) so that when we reload our code,
  ;; the server is forced to re-resolve the symbol in the var
  ;; rather than having its own copy. When the root binding
  ;; changes, the server picks it up without having to restart.
  ; ... snipped for brevity ...
)

(defn start-server
  "used for starting the server in development mode from REPL"
  [& [port]]
  ; ... snipped for brevity ...
)

(defn stop-server []
  ;… snipped for brevity …
)

Incorporating the REPL into your development workflow is a wonderful thing to do. You can load your namespace into the REPL while you work on it and test the code while you're developing right then and there. In fact, some IDEs such as LightTable take this a step further, and will "live-evaluate" your code as you type. The ability of running the dev server from the REPL completes the circle.