Sane, smart, fast, Clojure web services -- Rook

As presented to Clojerks (PDX Clojure User's Group).

1. Sane, smart, fast, Clojure web services — Rook Howard Lewis Ship - hlship@gmail.com - @hlship
2. Why?
4. Liberator (defresource entry-resource [id] :allowed-methods [:get :put :delete] :known-content-type? #(check-content-type % ["application/json"]) :exists? (fn [_] (let [e (get @entries id)] (if-not (nil? e) {::entry e}))) :existed? (fn [_] (nil? (get @entries id ::sentinel))) :available-media-types ["application/json"] :handle-ok ::entry :delete! (fn [_] (dosync (alter entries assoc id nil))) :malformed? #(parse-json % ::data) :can-put-to-missing? false :put! #(dosync (alter entries assoc id (::data %))) :new? (fn [_] (nil? (get @entries id ::sentinel))))
5. Resource vs. Endpoints
6. Rook — Goals & Philosophy
7. Goal: Simple Functions
8. (ns org.example.resources.health-check)
 
 (defn ping
 {:route [:get []]}
 []
 {:status 200
 :headers {}
 :body "Health check A-OK!"})
9. (ns org.example.server (:require [ring.adapter.jetty :as jetty] [io.aviso.rook :as rook])) (defn start-server [port] (let [handler (-> (rook/namespace-handler ['org.example.resources.health-check]) rook/wrap-with-standard-middleware)] (jetty/run-jetty handler {:port port :join? false})))
10. $ http localhost:8080 HTTP/1.1 200 OK Content-Length: 18 Date: Thu, 26 Mar 2015 23:49:54 GMT Server: Jetty(7.6.13.v20130916) Health check A-OK!
11. Goal:
 Simple/Smart Access to Request Data
12. (ns org.example.resources.health-check)
 
 (defn ping
 {:route [:get [:id]]}
 [request id]
 {:status 200
 :headers {}
 :body {:uri (:uri request)
 :message (format "Health check %s A-OK!" id)}}) 

13. $ http localhost:8080 HTTP/1.1 404 Not Found Cache-Control: must-revalidate,no-cache,no-store Content-Length: 1267 Content-Type: text/html;charset=ISO-8859-1 Date: Thu, 26 Mar 2015 23:59:19 GMT Server: Jetty(7.6.13.v20130916) <html> <head> <meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1"/> <title>Error 404 Not Found</title> </head> <body> <h2>HTTP ERROR: 404</h2> <p>Problem accessing /. Reason: <pre> Not Found</pre></p> <hr /><i><small>Powered by Jetty://</small></i> </body> </html>
14. $ http localhost:8080/gnip HTTP/1.1 200 OK Content-Length: 51 Content-Type: application/json; charset=utf-8 Date: Fri, 27 Mar 2015 00:00:36 GMT Server: Jetty(7.6.13.v20130916) { "message": "Health check gnip A-OK!", "uri": "/gnip" }
15. (ns org.example.resources.health-check)
 
 (defn ping
 {:route [:get [:id]]}
 [request id]
 {:status 200
 :headers {}
 :body {:uri (:uri request)
 :message (format "Health check %s A-OK!" id)}}) 

16. Goal:
 Free From Globals
17. (ns org.example.resources.offers
 (:require [io.aviso.rook.utils :as utils]))
 
 (defn show
 [db-conn id]
 (utils/response {:db-conn db-conn
 :id id}))
18. (ns org.example.complex-server
 (:require
 [ring.adapter.jetty :as jetty]
 [io.aviso.rook :as rook]
 [io.aviso.rook.server :as server]))
 
 (defn create-handler [database-connection]
 (-> (rook/namespace-handler {:arg-resolvers {'db-conn (fn [request] database-connection)}}
 ["offers" 'org.example.resources.offers]
 ["users" 'org.example.resources.users])
 rook/wrap-with-standard-middleware))
 
 (defn start-server
 [database-connection port]
 (jetty/run-jetty (server/construct-handler {:log true :reload true} #'create-handler database-connection)
 {:port port :join? false}))
19. $ http localhost:8080/offers/1234 HTTP/1.1 200 OK Content-Length: 44 Content-Type: application/json; charset=utf-8 Date: Fri, 27 Mar 2015 00:21:30 GMT Server: Jetty(7.6.13.v20130916) { "db-conn": "mock-db-connection", "id": "1234" }
20. (ns org.example.complex-server
 (:require
 [ring.adapter.jetty :as jetty]
 [io.aviso.rook :as rook]
 [io.aviso.rook.server :as server]))
 
 (defn create-handler [database-connection]
 (-> (rook/namespace-handler {:arg-resolvers {'db-conn (fn [request] database-connection)}}
 ["offers" 'org.example.resources.offers]
 ["users" 'org.example.resources.users])
 rook/wrap-with-standard-middleware))
 
 (defn start-server
 [database-connection port]
 (jetty/run-jetty (server/construct-handler {:log true :reload true} #'create-handler database-connection)
 {:port port :join? false}))
21. {:arg-resolvers {'db-conn (fn [request] database-connection)} Symbol to match Resolves the argument value from the request
22. {:arg-resolvers {'db-conn (constantly database-connection)} Symbol to match Resolves the argument value from the request
23. (ns org.example.complex-server
 (:require
 [ring.adapter.jetty :as jetty]
 [io.aviso.rook :as rook]
 [io.aviso.rook.server :as server]))
 
 (defn create-handler [database-connection]
 (-> (rook/namespace-handler {:arg-resolvers {'db-conn (fn [request] database-connection)}}
 ["offers" 'org.example.resources.offers]
 ["users" 'org.example.resources.users])
 rook/wrap-with-standard-middleware))
 
 (defn start-server
 [database-connection port]
 (jetty/run-jetty (server/construct-handler {:log true :reload true} #'create-handler database-connection)
 {:port port :join? false})) Development mode: the handler is recreated on each request
24. Goal: Leverage Metadata
25. (defn ping
 {:route [:get [:id]]}
 [request id]
 {:status 200
 :headers {}
 :body (format "Health check %s A-OK!" id)})

26. (defn create
 {:schema create-schema
 :responses create-responses
 :required-permissions "auth/user/create"
 :operation-trace "Creating new user."}
 […] …)
27. Endpoint Middleware (fn [handler endpoint-metadata]) ➠ handler Meta-data of function merged w/ namespace metadata (to provide defaults)
28. (rook/compose-middleware
 tracking/wrap-with-operation-tracking
 (rv/wrap-with-response-validation (not production-mode))
 sv/wrap-with-schema-validation
 auth/auth-middleware
 wrap-with-endpoint-identifier)
29. (defn wrap-with-operation-tracking
 "Checks for the :operation-trace metadata …"
 [handler metadata]
 (when-let [label (:operation-trace metadata)]
 (let [logger (-> metadata :ns t/get-logger)]
 (fn [request]
 (t/track* logger label (handler request))))))
30. Middleware Shootout Ring Rook No Metadata Available Has full metadata of endpoint function Must return a handler Can return handler, or return nil Interceptors execute during request dispatch Interceptors execute after dispatch (once endpoint known) Tree of contexts & interceptors Stack of interceptors unique for each endpoint
31. Goal: Efficient
32. Checklist • Sane? — Yes, natural mapping from URIs to simple functions • Smart? — Yes, metadata on functions w/ argument resolvers and middleware keeps code tight & free of globals • Fast? — Yes, efficient dispatch & interceptors
33. Links • Rook — http://github.com/AvisoNovate/rook