Creating Web Services with Liberator - f(by) 2016

Slides for my conference talk at f(by) 2016 in Minsk

Liberator is a clojure liberator to create web services that fully embrace the REST architectural style. In this talk you will learn about the motivation to create liberator and how it's very declarative style allows you to build resources that strictly conform with the HTTP semantics and leverage the full potential of HTTP.

Transcript

1. liberator A clojure library to implement REST resources https://clojure-liberator.github.io/ Philipp Meier @ordnungswprog Software Developer http://philipp.meier.name
2. Clojure
3. Clojure » lisp » repl » jvm » ClojureScript (targets javascript) » 10 years of awesomness in 2017
4. data structures Immutable, Persistent » PersistentVector (aka. Bitmapped Vector Tries) » O(log32 n) is fast enough » Vectors, HashMaps, Sets
5. Keywords » Evaluate to themselves :a-keyword » ad-hoc identifiers » keywords are functions: map lookup
6. Clojure syntax 101
7. Clojure syntax 101 (function arg1 arg2 arg2) (foo 1 2 3) (foo (bar (1 2 3)))
8. Clojure syntax 101 (defn foo [bar baz] (let [rab (reverse bar)] (str bar baz)))
9. Clojure syntax 101 (+ 2 (* 3 4)) ;; => 14 (fn [a b c] (+ a b c)) ;; => an anonymous fn / lambda (keep odd? [1 2 3 4]) ;; => [1 3]
10. Clojure syntax 101 (def p {:firstname "Philipp" :lastname "Meier"}) ;; map destructuring (let [{f :firstname l :lastname} p] (str l ", " f)) ;; => "Meier, Philipp"
11. Keywords examples :keyword (def person {:firstname "Philipp" :lastname "Meier"}) ;; keywords are functions to lookup from maps (:firstname person) ;; maps a functions to (person :firstname) ;; same as (get person :firstname) ;; nobody uses that
12. Ring » Specification for HTTP service implementation » Handlers are functions 123
13. Liberator Some History “The best way to predict the future is to invent it” Alan Kay
14. Liberator Some History » New to clojure » Looking for a problem » Web applications since 1996 » Erlangs webmachine » This is Nov 2009 » Malcolm Sparks joins around Euroclojure 2012 » Getting speed...
15. HTTP is huge
16. HTTP IS COMPLEX » Request and response » Headers and body » Methods » Status codes » Content negotiation » Conditional request » And more...
17. HTTP Methods
18. HTTP Methods 8
19. HTTP Methods 8 RFC 7231 GET, PUT, POST, DELETE, HEAD, OPTIONS, TRACE, CONNECT
20. HTTP Methods 8+1+7 RFC 7231 PATCH (RFC 5789) WEBDAV (RFC 4918)
21. HTTP Header Fields
22. HTTP Header Fields 47
23. HTTP Header Fields 47 Accept ... WWW-Authenticate
24. HTTP Status codes
25. HTTP Status codes 5 Classes
26. HTTP Status codes 5 Classes » 1xx Informational » 2xx Successful » 3xx Redirection » 4xx Client Error » 5xx Server error
27. HTTP Status codes
28. HTTP Status codes 41
29. HTTP Status codes 41 (RFC 7231)
30. HTTP Status codes 41+1 (RFC 7231) WebDav (RFC 5842)
31. HTTP Status codes 41+1+1 (RFC 7231) WebDav (RFC 5842) HTCPCP (RFC 2324)
32. 418 I'm a Teapot HTCPCP (RFC 2324)
33. HTTP Status codes 41 (RFC 7231)
34. HTTP Status codes 41 (< 41 2^6) » Maximum # of needed decisions » At least 40 branching points
35. Ring {:request-method ... :headers {...} :body "..."} ‑ {:status ... :headers {...} :body "..."}
36. How do we tackle this?
37. Ring (my-handler {:request-method ... :headers {...} :body "..."}) ‑ {:status ... :headers {...} :body "..."}
38. Ring Implementing a handler (defn my-handler [req] ???)
39. Ring Dispatch somehow gives status codes (defn my-handler [req] (cond ... {:status 503} ... {:status 501} ... {:status 403} ... {:status 405} ... {:status 400} ... {:status 200}))
40. Ring Dispatch somehow gives status codes (defn my-handler [req] (cond ? {:status 503} ... {:status 501} ... {:status 403} ... {:status 405} ... {:status 400} ... {:status 200}))
41. Ring Dispatch somehow gives status codes (defn my-handler [req] (cond ? {:status 503} ? {:status 501} ? {:status 403} ? {:status 405} ? {:status 400} ? {:status 200}))
42. Implementing a well behaved ring handler - KISS (defn my-handler [req] {:status 200 :headers {"Content-Type" "text/html"} :body "a talk"})
43. Implementing a well behaved ring handler - KISS (defn my-handler [{m :request-method {id "id"} :query-params}] (if (= :get m) {:status 200 :headers {"Content-Type" "text/plain; charset=UTF-8"} :body (pr-str (find-session id))} {:status 405 :body "Method not allowed."}))
44. Implementing a well behaved ring handler Font size is getting smaller (defn my-handler [{m :request-method {id "id"} :params}] (if (= :get m) (if-let [e (find-session id)] {:status 200 :headers {"Content-Type" "text/plain; charset=UTF-8"} :body (pr-str (find-session id))} {:status 404 :body "Not found."}) {:status 405 :body "Method not allowed."}))
45. Implementing a well behaved ring handler Can you still read this? (defn my-handler [{m :request-method {id "id"} :params {accept "accept"} :headers}] (if (= :get m) (if-let [e (find-session id)] (if-let [mt (some #(when (or (nil? accept) (= accept "*/*") (.contains accept %)) %) ["application/clojure" "text/html"])] (condp = mt "application/clojure" {:status 200 :headers {"Content-Type" "application/clojure; charset=UTF-8"} :body (pr-str e)} "text/html" {:status 200 :headers {"Content-Type" "text/html; charset=UTF-8"} :body (apply format "<html><h1>%s</h1><p>%s</p><p><small>%s</small></p></html>" ((juxt :title :time :speaker) e)) }) {:status 406 :body "Requested media type not acceptable."}) {:status 404 :body "Not found."}) {:status 505 :body "Method not allowed."}))
46. What's going on? (defn handler [{m :request-method {id "id"} :params {accept "accept" ims "if-modified-since"} :headers}] (if (#{:get :post :put :delete :head :options :trace} m) (if (= :get m) (if-let [e (find-session id)] (if-let [mt (some #(when (or (nil? accept) (= accept "*/*") (.contains accept %)) %) ["application/clojure" "text/html"])] (let [last-modified (begin-of-last-minute) cache-headers {"Last-Modified" (.format (http-date-format) last-modified) "Vary" "Accept"}] (if (and ims (let [imsd (.parse (http-date-format) ims)] (= last-modified imsd))) {:status 304 :headers cache-headers} (condp = mt "application/clojure" {:status 200 :headers (assoc cache-headers "Content-Type" "application/clojure; charset=UTF-8") :body (pr-str e)} "text/html" {:status 200 :headers (assoc cache-headers "Content-Type" "text/html; charset=UTF-8") :body (apply format "<html><h1>%s</h1><p>%s</p><p><small>%s</small></p></html>" ((juxt :title :time :speaker) e)) }))) {:status 406 :body "Requested media type not acceptable."}) {:status 404 :body "Not found."}) {:status 501 :body "Not implemented."}) {:status 405 :body "Method not allowed."}))
47. Conditionals! (defn handler [ #_... ] (if #_... (if #_... (if-let #_... (if-let #_... (if #_... {:status 304} (condp #_... {:status 200} {:status 200})) {:status 406}) {:status 404}) {:status 501}) {:status 405}))
48. Extract the decision flow
49. DEMO
50. Demo result (defresource talk :available-media-types ["text/html" "application/json" "application/edn"] :exists? (fn [{{{id "id"} :params} :request}] (if-let [talk (find-talk id)] {::talk talk})) :handle-ok ::talk :last-modified (fn [_] (begin-of-last-minute)) :etag (fn [{{{id "id"} :params} :request}] (apply str (reverse (str id id)))))
51. Remember the explicit implementation? (defn handler [{m :request-method {id "id"} :params {accept "accept" ims "if-modified-since"} :headers}] (if (#{:get :post :put :delete :head :options :trace} m) (if (= :get m) (if-let [e (find-session id)] (if-let [mt (some #(when (or (nil? accept) (= accept "*/*") (.contains accept %)) %) ["application/clojure" "text/html"])] (let [last-modified (begin-of-last-minute) cache-headers {"Last-Modified" (.format (http-date-format) last-modified) "Vary" "Accept"}] (if (and ims (let [imsd (.parse (http-date-format) ims)] (= last-modified imsd))) {:status 304 :headers cache-headers} (condp = mt "application/clojure" {:status 200 :headers (assoc cache-headers "Content-Type" "application/clojure; charset=UTF-8") :body (pr-str e)} "text/html" {:status 200 :headers (assoc cache-headers "Content-Type" "text/html; charset=UTF-8") :body (apply format "<html><h1>%s</h1><p>%s</p><p><small>%s</small></p></html>" ((juxt :title :time :speaker) e)) }))) {:status 406 :body "Requested media type not acceptable."}) {:status 404 :body "Not found."}) {:status 501 :body "Not implemented."}) {:status 405 :body "Method not allowed."}))
52. Be more expressive (defresource talk :available-media-types ["text/html" "application/json" "application/edn"] :exists? (fn [{{{id "id"} :params} :request}] (if-let [talk (find-talk id)] {::talk talk})) :handle-ok (fn [{talk ::talk {mt :media-type} :representation}] (if (= mt "text/html" (apply format "<html><h1>%s</h1><p>%s</p><p><small>%s</small></p></html>" ((juxt :title :time :speaker) talk)) talk))) :last-modified (fn [_] (begin-of-last-minute)) :etag (fn [{{{id "id"} :params} :request}] (apply str (reverse (str id id)))))
53. Application logic in the provided functions (defresource talk :available-media-types (fn [ctx] ...) :exists? (fn [ctx] ...) :handle-ok (fn [ctx] ...) :last-modified (fn [ctx] ...) :etag (fn [ctx] ...))
54. Execution model
55. Pass along the context
56. Context State of the execution
57. Context Context is passed to all resource functions (defresource talk :available-media-types (fn [ctx] ...) :exists? (fn [ctx] ...) :handle-ok (fn [ctx] ...) :last-modified (fn [ctx] ...) :etag (fn [ctx] ...))
58. Context update Result of decision functions merged "intelligently" interpreted as a boolean use to update the context
59. Context update ; Boolean value false ; Map is merged -- and true {:talk {:title "liberator 101" ...}} ; Vector to specify bool and update [false {:error "Database explosion"}]
60. Context Build incrementally {:request {:request-method :get :params ...}}
61. Context Build incrementally {:request {:request-method :get :params ...} ::talk {:speaker "Philipp Meier"...}}
62. Context Build incrementally {:request {:request-method :get :params ...} ::talk {:speaker "Philipp Meier"...} :representation {:media-type "application/edn" :language "de" :charset "UTF-8“}}
63. Implementation
64. Implementation Clojure loves data
65. Implementation Resource definitions are maps of functions
66. Maps of functions (def talk (resource {:available-media-types (fn [ctx] ...) :exists? (fn [ctx] ...) :handle-ok (fn [ctx] ...) :last-modified (fn [ctx] ...) :etag (fn [ctx] ...)}))
67. Implementation
68. Implementation Macros for expressive code ;; name if-true if-false (defdecision authorized? allowed? handle-unauthorized) (defdecision malformed? handle-malformed authorized?) (defdecision method-allowed? coll-validator malformed? handle-method-not-allowed) (defdecision uri-too-long? handle-uri-too-long method-allowed?) (defdecision known-method? uri-too-long? handle-unknown-method) (defdecision service-available? known-method? handle-service-not-available) (defaction initialize-context service-available?)
69. Implementation » Fixed (opinionated) decision graph » It's simply "functions calling functions" » Dispatched by function "decide" based on the return value of each decision function
70. Decide (defn decide [name test then else {:keys [resource request] :as context}] (if (or test (contains? resource name)) (try (let [ftest (or (resource name) test) ftest (make-function ftest) fthen (make-function then) felse (make-function else) decision (ftest context) result (if (vector? decision) (first decision) decision) context-update (if (vector? decision) (second decision) decision) context (update-context context context-update)] (log! :decision name decision) ((if result fthen felse) context)) (catch Exception e (handle-exception (assoc context :exception e)))) {:status 500 :body (str "No handler found for key \"" name "\"." " Keys defined for resource are " (keys resource))}))
71. Decide (defn decide [name then else {:keys [resource request] :as context}] (try (let [ftest (resource name) ftest (make-function ftest) fthen (make-function then) felse (make-function else) decision (ftest context) result (if (vector? decision) (first decision) decision) context-update (if (vector? decision) (second decision) decision) context (update-context context context-update)] (log! :decision name decision) ((if result fthen felse) context)) (catch Exception e (handle-exception (assoc context :exception e))))) ;;
72. Call stack java.lang.ArithmeticException: Divide by zero at clojure.lang.Numbers.divide(Numbers.java:158) at clojure.lang.Numbers.divide(Numbers.java:3808) at free_your_data.liberator$talk$fn__22708.invoke(form-init6714364267415717902.clj:600) at liberator.core$gen_last_modified.invokeStatic(core.clj:62) at liberator.core$gen_last_modified.invoke(core.clj:60) at liberator.core$run_handler.invokeStatic(core.clj:146) at liberator.core$run_handler.invoke(core.clj:130) at liberator.core$handle_exception.invokeStatic(core.clj:495) at liberator.core$handle_exception.invoke(core.clj:495) at liberator.core$decide.invokeStatic(core.clj:88) at liberator.core$decide.invoke(core.clj:73) at liberator.core$initialize_context.invokeStatic(core.clj:493) at liberator.core$initialize_context.invoke(core.clj:493) at liberator.core$run_resource.invokeStatic(core.clj:581) at liberator.core$run_resource.invoke(core.clj:579) at free_your_data.liberator$talk.invokeStatic(form-init6714364267415717902.clj:592) at free_your_data.liberator$talk.invoke(form-init6714364267415717902.clj:592)
73. Re: Essential complexity » You need to implement the decision functions no matter which technology. » With liberator thats often all you need to do.
74. Liberator is opinionated
75. Don't write plumbing code
76. Not writing code feels so good
78. Outlook
79. Outlook Liberator approaches feature completeness
80. Outlook Alternative execution models
81. Alternative execution models Async
82. Outlook More resource centric Less HTTP centric
83. Outlook More resource centric Less HTTP centric 㱺 YADA
84. Questions?
85. Thank you! Philipp Meier @ordnungswprog » http://clojure-liberator.github.io/liberator » https://github.com/ordnungswidrig/liberator- presentation » http://clojure.org