Router

Bidirectional RESTfull Ring router for clojure and clojurescript.

Comparation

library	clj	cljs	dsl	named routes	mountable apps	abstraction	export format	extensibility
compojure	✓		macros			url
secretary		✓	macros	✓		url		protocols
bidi	✓	✓	data/functions	✓		url	route description data	protocols
darkleaf/router	✓	✓	functions	✓	✓	resource	explain data	protocols

Usage

(ns app.some-ns
  (:require [darkleaf.router :as r]
            [ring.util.response :refer [response]]))

(r/defcontroller controller
  (index [req]
    (let [request-for (::r/request-for req)]
      (response (str (request-for :index [:pages] {}))))))

(def routing (r/resources :pages :page controller))

(def handler (r/make-handler routing))
(def request-for (r/make-request-for routing))

(handler {:uri "/pages", :request-method :get}) ;; call index action from controller
(request-for :index [:pages] {}) ;; returns {:uri "/pages", :request-method :get}

Single routing namespace:

(ns app.routing
  (:require
   [darkleaf.router :as r]
   [app.controllers.main :as main]
   [app.controllers.session :as session]
   [app.controllers.account.invites :as account.invites]
   [app.controllers.users :as users]
   [app.controllers.users.statistics :as users.statistics]
   [app.controllers.users.pm-bonus :as users.pm-bonus]
   [app.controllers.projects :as projects]
   [app.controllers.projects.status :as projects.status]
   [app.controllers.projects.completion :as projects.completion]
   [app.controllers.tasks :as tasks]
   [app.controllers.tasks.status :as tasks.status]
   [app.controllers.tasks.comments :as tasks.comments]))
   
(def routes
  (r/group
    (r/resource :main main/controller :segment false)
    (r/resource :session session/controller)
    (r/section :account
      (r/resources :invites :invite account.invites/controller)) 
    (r/resources :users :user users/controller
      (r/resource :statistics users.statistics/controller)
      (r/resource :pm-bonus users.pm-bonus/controller))
    (r/resources :projects :project projects/controller
      (r/resource :status projects.status/controller)
      (r/resource :completion projects.completion/controller))
    (r/resources :tasks :task tasks/controller
      (r/resource :status tasks.status/controller)
      (r/resources :comments tasks.comments/controller))))

Multiple routing namespaces:

(ns app.routes.main
  (:require
   [darkleaf.router :as r]))

(r/defcontroller controller
  (show [req] ...))

(def routes (r/resource :main main-controller :segment false))

(ns app.routes
  (:require
   [darkleaf.router :as r]
   [app.routes.main :as main]
   [app.routes.session :as session]
   [app.routes.account :as account]
   [app.routes.users :as users]
   [app.routes.projects :as projects]
   [app.routes.tasks :as tasks]))

(def routes
  (r/group
    main/routes
    session/routes
    account/routes
    users/routes
    projects/routes
    tasks/routes))

Use cases

Rationale

Routing libraries work similarly on all programming languages: they only map uri with a handler using templates. For example compojure, sinatra, express.js, cowboy.

There are some downsides of this approach.

No reverse or named routing. Url is set in templates as a string.
Absence of structure. Libraries do not offer any ways of code structure, that results of chaos in url and unclean code.
Inability to mount an external application. Inability to create html links related with mount point.
Inability to serialize routing and use it in other external applications for request forming.

Most of these problems are solved in Ruby on Rails.

If you know the action, controller name and parameters, you can get url, for example: edit_admin_post_path(@post.id).
You can use rest resources to describe routing. Actions of controllers match to handlers. However, framework allows to add non-standart actions into controller, that makes your code unlean later.
There is an engine support. For example, you can mount a forum engine into your project or decompose your application into several engines.
There is an API for routes traversing, which uses rake routes command. The library js-routes brings url helpers in js.

Solution my library suggests.

Knowing action, scope and params, we can get the request, which invokes the handler of this route: (request-for :edit [:admin :post] {:post "1"}).
The main abstraction is the rest resource. Controller contains only standard actions. You can see resource composition how to deal with it.
Ability to mount an external application. See example for details.
The library interface is identical in clojure and clojurecript, that allows to share the code between server and client using .cljc files. You can also export routing description with cross-platform templates as a simple data structure. See example for details.

Resources

Action name	Scope	Params	Http method	Url	Type	Used for
index	[:pages]	{}	Get	/pages	collection	display a list of pages
show	[:page]	{:page 1}	Get	/pages/1	member	display a specific page
new	[:page]	{}	Get	/pages/new	collection	display a form for creating new page
create	[:page]	{}	Post	/pages	collection	create a new page
edit	[:page]	{:page 1}	Get	/pages/1/edit	member	display a form for updating page
update	[:page]	{:page 1}	Patch	/pages/1	member	update a specific page
put	[:page]	{:page 1}	Put	/pages/1	member	upsert a specific page, may be combined with edit action
destroy	[:page]	{:page 1}	Delete	/pages/1	member	delete a specific page

(ns app.some-ns
  (:require [darkleaf.router :as r]
            [ring.util.response :refer [response]]))

;; all items are optional
(r/defcontroller pages-controller
  (middleware [h]
    (fn [req] (h req)))
  (collection-middleware [h]
    (fn [req] (h req)))
  (member-middleware [h]
    (fn [req] (h req)))
  (index [req]
    (response "index resp"))
  (show [req]
    (response "show resp"))
  (new [req]
    (response "new resp"))
  (create [req]
    (response "create resp"))
  (edit [req]
    (response "edit resp"))
  (update [req]
    (response "update resp"))
  (put [req]
    (response "put resp"))
  (destroy [req]
    (response "destroy resp")))

;; :index [:pages] {} -> /pages
;; :show [:page] {:page 1} -> /pages/1
(r/resources :pages :page pages-controller)

;; :index [:people] {} -> /menschen
;; :show [:person] {:person 1} -> /menschen/1
(r/resources :people :person people-controller :segment "menschen")

;; :index [:people] {} -> /
;; :show [:person] {:person 1} -> /1
(r/resources :people :person people-controller :segment false)

;; :put [:page :star] {:page 1} -> PUT /pages/1/star
(r/resources :pages :page pages-controller
  (r/resource :star star-controller)

There are 3 types of middlewares:

middleware applied to all action handlers including nested.
collection-middleware applied only to index, new and create actions.
member-middleware applied to show, edit, update, put, delete and all nested handlers, look here for details.

Please see test for all examples.