mv decorators and caveman session around

Author: vindarel

content/building-blocks/routing.md

@@ -1,5 +1,5 @@
 +++
-title = "Routing"
+title = "Routes and URL parameters"
 weight = 16
 +++
 
@@ -8,6 +8,11 @@ routes, as we did in the tutorial, so skip to its section below if you
 want. However, it can only be benificial to know the built-in
 Hunchentoot ways.
 
+{{% notice info %}}
+Please see the tutorial where we define routes with **path parameters**
+and where we also access **URL parameters**.
+{{% /notice %}}
+
 
 ## Hunchentoot
 
@@ -134,34 +139,86 @@ Hunchentoot to convert the argument to this given type. For example,
 defining an `:integer` will give you an integer and not a string (all
 URL parameters are given as a string by default, but more on that on the next section).
 
-**Decorators** are functions that are executed before the route body. They
-should call the `next` parameter function to continue executing the
-decoration chain and the route body finally. Examples:
+### easy-routes' decorators
 
-~~~lisp
-;; Ensure a user is logged in:
-(defun @auth (next)
-  (let ((*user* (hunchentoot:session-value 'user)))
-    (if (not *user*)
-	(hunchentoot:redirect "/login")
-	(funcall next))))
-
-;; Define content types:
-(defun @html (next)
-  (setf (hunchentoot:content-type*) "text/html")
-  (funcall next))
+`easy-routes` provides us with an easy way to call any function before
+the route body. Following the naming of a popular language, they are
+called "decorators".
+
+In the end route definitions are only functions, right? Decorators are
+only functions too, but they are run before the route body.
+
+Remember the shape of our routes:
+
+```lisp
+(easy-routes:defroute root ("/") ()
+    "hello app")
+```
+
+We add a list of decorators after the `"/"` part, like this:
+
+```lisp
+ (defroute my-protected-route ("/foo" :method :get
+                                      :decorators ((@json))) ()
+	"hello decorated route")
+```
 
+but what is `@json`? It's a function:
+
+```lisp
 (defun @json (next)
   (setf (hunchentoot:content-type*) "application/json")
   (funcall next))
+```
+
+You can ignore the `@` sign, it doesn't mean anything in Common Lisp
+(but as it's part of the function name it can help you reference all
+your route decorators).
 
+Route "decorators" must accept at least one argument: here called `next`, it is the
+function that will be called next (so, at one point, our route body)
+*if we want to*. Look at `(funcall next)`: our decorator correctly
+calls it.
+
+If you declare a list of decorators, calling "next" will get you
+through the chain of decorator functions, and finally to the route
+body (if no "decorator" exited before).
+
+So what it is function doing? Keep it mind that it is called in the
+context of a web request. So we can call `hunchentoot:content-type*`
+(note the `*`, this function is applied on the current web
+request). We are setting this request's content-type to
+`application/json`.
+
+Yes, you can copy-paste the `setf` line directly into your function.
+
+Here's another "decorator":
+
+```lisp
+(defun @auth (next)
+  (let ((user (hunchentoot:session-value 'user)))
+    (if (not user)
+	  (hunchentoot:redirect "/login")
+	  (funcall next))))
+```
+
+Now that's interesting. It's doing this:
+- it gets a value from the current web session. This can be any Lisp object.
+- if a user was registered in the session, we call the `next` method to run other decorators and the route body
+- otherwise, we redirect to the login page.
+
+We use them in the "User log in" section.
+
+Here's another decorator from easy-routes' README:
+
+```lisp
 ;; Ensure our PostgreSQL database is connected:
 (defun @db (next)
   (postmodern:with-connection *db-spec*
     (funcall next)))
-~~~
+```
 
-I mostly use the `@auth` and `@json` decorators, which I'll demo later. See the `easy-routes` readme for more.
+See the `easy-routes` readme for more.
 
 
 ## Accessing GET and POST parameters
@@ -170,7 +227,7 @@ You probably have nothing to do to get the value of those parameters: if you def
 
 However, here's how to interact more with URL parameters. In particular, we can define the default type of a parameter: they are strings by default, but we can ask to receive an integer.
 
-### Hunchentoot URL parameters
+### Hunchentoot and easy-routes URL parameters
 
 First of all, note that we can access query parameters anytime with
 

content/building-blocks/user-log-in.md

@@ -28,7 +28,6 @@ both the login page or the "dashboard" for logged-in users.
 
 <!-- - when we don't find a user ID in the session, we render the log-in page -->
 
-Let's start with the model functions.
 
 We use these libraries:
 
@@ -43,6 +42,7 @@ this at the top of your file:
 (in-package :myproject)
 ```
 
+Let's start with the model functions.
 
 ## Get users
 
@@ -63,6 +63,30 @@ later, we focus on the web stack. Here we return a user object, a
          (string= password (getf user :password)))))
 ~~~
 
+Look, what if we stored our own name and password in a file? No need
+of a DB for a personal or a toy web app.
+
+In `creds.lisp-expr`:
+
+```lisp
+(:name "me" :password "yadadada")
+```
+
+the ".lisp-expr" is just a convention, so that your tools won't see it
+as a lisp source.
+
+Read it back in with `uiop:read-file-form`:
+
+```lisp
+(defparameter *me* (uiop:read-file-form "creds.lisp-expr"))
+
+(getf *me* :name)
+;; => "me"
+```
+
+Cool? my 2c.
+
+
 ## Templates: login, welcome
 
 For convenience we again define our templates as strings.
@@ -141,7 +165,7 @@ You can start with this route:
 We are simply querying the session for the user name. If it's present,
 that means we have established it at login.
 
-Now is a great time to use easy-routes' "decorators".
+Now is a great time to use easy-routes' "decorators" (see the [Routing](/building-blocks/routing/) section).
 
 We can shorten the route to this:
 
@@ -294,10 +318,10 @@ This is the equivalent Hunchentoot route:
 Remarks:
 
 - we can't dispatch on the request type, so we use the `ecase` on `request-method*`
-- we can't use "decorators" so if use branching
+- we can't use "decorators" so we use branching
 - it isn't very clear but `name` and `password` are only used in the POST part.
   - we can also use `(hunchentoot:post-parameter "name")` (the parameter as a string)
-- otherwise, it's pretty similar.
+- all this adds nesting in our function but otherwise, it's pretty similar.
 
 ## Full code
 
@@ -416,3 +440,55 @@ Remarks:
 (defun stop-server ()
   (hunchentoot:stop *server*))
 ```
+
+## Caveman
+
+In Caveman, `*session*` is a hash-table that represents the session's
+data. Here are our login and logout functions:
+
+```lisp
+(defun login (user)
+  "Log the user into the session"
+  (setf (gethash :user *session*) user))
+
+(defun logout ()
+  "Log the user out of the session."
+  (setf (gethash :user *session*) nil))
+```
+
+We define a simple predicate:
+
+```lisp
+(defun logged-in-p ()
+  (gethash :user cm:*session*))
+```
+
+We don't know a mechanism as easy-routes' "decorators" but we define a
+`with-logged-in` macro:
+
+```lisp
+(defmacro with-logged-in (&body body)
+  `(if (logged-in-p)
+       (progn ,@body)
+       (render #p"login.html"
+               '(:message "Please log-in to access this page."))))
+```
+
+If the user isn't logged in, there will be nothing stored in the session store,
+and we render the login page. When all is well, we execute the macro's
+body. We use it like this:
+
+```lisp
+(defroute "/account/logout" ()
+  "Show the log-out page, only if the user is logged in."
+  (with-logged-in
+    (logout)
+    (render #p"logout.html")))
+
+(defroute ("/account/review" :method :get) ()
+  (with-logged-in
+    (render #p"review.html"
+            (list :review (get-review (gethash :user *session*))))))
+```
+
+and so on.

content/building-blocks/users-and-passwords.md

@@ -26,137 +26,6 @@ If you use a database, you'll have to create at least to save users. A
 - optionally, a key to the table listing roles.
 
 
-## Checking a user is logged-in
-
-<!-- https://www.reddit.com/r/Common_Lisp/comments/1f7bfql/simple_session_management_with_hunchentoot/ -->
-
-A framework provides a way to work with sessions.
-
-Our web app defines routes. Routes are, in the end, only functions.
-
-We must find a way to check for users before the route function. If
-our check is successful (the user registered in the current session)
-is logged-in, we call the next function (the route body). If our check
-is falsy, we don't execute the route but we redirect to the login page
-instead. Simple right?
-
-
-### Hunchentoot and easy-routes
-
-`easy-routes` provides us with an easy way to call any function before
-the route body. Following the naming of a popular language, they are
-called "decorators".
-
-Remember the shape of our routes:
-
-```lisp
-(easy-routes:defroute root ("/") ()
-    "hello app")
-```
-
-We add a list of decorators after the `"/"` part, like this:
-
-```lisp
- (defroute my-protected-route ("/foo" :method :get
-                                      :decorators ((@json)))
-	()
-	"hello decorated route")
-```
-
-but what is `@json`? It's a function:
-
-```lisp
-(defun @json (next)
-  (setf (hunchentoot:content-type*) "application/json")
-  (funcall next))
-```
-
-You can ignore the `@` sign, it doesn't mean anything in Common Lisp
-(but as it's part of the function name it can help you reference all
-your route decorators).
-
-Route "decorators" must accept at least one argument: `next`, the
-function that will be called next (so, at one point, our route body)
-*if we want to*. Look at `(funcall next)`: our decorator correctly
-calls it.
-
-So what it is function doing? Keep it mind that it is called in the
-context of a web request. So we can call `hunchentoot:content-type*`
-(note the `*`, this function is applied on the current web
-request). We are setting this request's content-type to
-`application/json`.
-
-Yes, you can copy-paste the `setf` line directly into your function.
-
-Here's another "decorator" (straight from easy-routes' documentation):
-
-```lisp
-(defun @auth (next)
-  (let ((*user* (hunchentoot:session-value 'user)))
-    (if (not *user*)
-	  (hunchentoot:redirect "/login")
-	  (funcall next))))
-```
-
-Now that's interesting. It's doing this:
-- it gets a value from the current web session. This can be any Lisp object.
-- it binds it to a global variable (we suppose the application re-uses it later) (global variables are thread-local)
-- if a user was registered in the session, we call the `next` method to run other decorators and the route body
-- otherwise, we redirect to the login page.
-
-
-### Caveman
-
-In Caveman, `*session*` is a hash table that represents the session's
-data. Here are our login and logout functions:
-
-```lisp
-(defun login (user)
-  "Log the user into the session"
-  (setf (gethash :user *session*) user))
-
-(defun logout ()
-  "Log the user out of the session."
-  (setf (gethash :user *session*) nil))
-```
-
-We define a simple predicate:
-
-```lisp
-(defun logged-in-p ()
-  (gethash :user cm:*session*))
-```
-
-We don't know a mechanism as easy-routes' "decorators" but we define a
-`with-logged-in` macro:
-
-```lisp
-(defmacro with-logged-in (&body body)
-  `(if (logged-in-p)
-       (progn ,@body)
-       (render #p"login.html"
-               '(:message "Please log-in to access this page."))))
-```
-
-If the user isn't logged in, there will be nothing stored in the session store,
-and we render the login page. When all is well, we execute the macro's
-body. We use it like this:
-
-```lisp
-(defroute "/account/logout" ()
-  "Show the log-out page, only if the user is logged in."
-  (with-logged-in
-    (logout)
-    (render #p"logout.html")))
-
-(defroute ("/account/review" :method :get) ()
-  (with-logged-in
-    (render #p"review.html"
-            (list :review (get-review (gethash :user *session*))))))
-```
-
-and so on.
-
 
 ## Encrypting passwords