Lambda Island

We continue our journey through Luminus by building a wiki. In this episode you’ll learn how to create the form to edit pages, and handle creating new page revisions. We’ll also come across Cross Site Request Forgery, and learn how to prevent it.

Transcript

In the previous episode we created a new Luminus application, set up a PostgreSQL database, wrote queries to insert and retrieve pages, and added a route and template to tie it all together. In this episode we’ll finish our wiki, and with that conclude our grand tour of Luminus.

If you didn’t follow along you can grab the code from GitHub instead. Start from the part-1 branch, and follow the instructions in the README to set up your database.

I’m just going to start from where we left off. In Emacs, I’ll open a Clojure file within the project so I can jack in CIDER and get a REPL.

Let’s have another look of what we have so far. Start the app and open it in a browser (http://localhost:3000/).

;; Start a connected REPL. For Emacs/CIDER: M-x cider-jack-in
user> (start)

We got redirected to /home, but we can’t yet edit the page. We created this page last time from the REPL, but we can’t expect our users to do the same!

We’ll need two new routes, which we’ll add to home.clj. One that shows the form to edit a page, and one that handles the form submission. We haven’t used the POST function before, so don’t forget to refer to it in the namespace declaration.

(ns lambwiki.routes.home ,,,)

(defroutes home-routes
  ,,,

  ;; show the form to edit a page
  (GET "/:uri_slug/edit" _)

  ;; submit the form, creating a new revision
  (POST "/:uri_slug" _))

Last time we set up two database tables to store the pages of the wiki. The “pages” table contains the uri slug and the title, while the page body is stored in “revisions”. In hindsight it probably makes more sense to store the page title together with the body. Let’s add a migration to move it to the revisions table.

lein migratus create move-page-title-to-revision

This migration consists of three steps, which, like in the previous episode, need to be separated with “–;;”. First we add the new column, then copy the data over, and finally we can drop the old column.

Normally you would also write a “down” migration, which does the opposite, so you can roll this change back. I’m not going to show the “down” migration, but you can do it as an exercise. It’s very similar to the one I just wrote, except now pages and revisions are swapped. Also make sure you get the page title from the most recent revision.

;; resources/migrations/20160516162634-move-page-title-to-revision.up.sql
ALTER TABLE revisions ADD COLUMN title TEXT;
---;;
UPDATE revisions SET title=pages.title FROM pages WHERE revisions.page_id=pages.id;
--;;
ALTER TABLE pages DROP COLUMN title;

Now run the migration.

lein run migrate

That looks good.

Our database is different now, so our queries will look a bit different as well. Let’s update them to use the new schema. Go to queries.sql, remove title from the create-page! query, and add it to the create-revision! query instead. Now only the id and uri_slug come from the pages table, while body and title will be loaded from the latest revision.

-- resource/sql/queries.sql
-- ...

-- :name create-page! :insert :raw
INSERT INTO pages (uri_slug) VALUES (:uri_slug)

-- :name create-revision! :insert :raw
INSERT INTO revisions (page_id, body, title) VALUES (:page_id, :body, :title)

-- :name find-page-by-uri-slug :query :one
SELECT pages.id, pages.uri_slug, revisions.body, revisions.title
FROM pages, revisions
WHERE pages.id = page_id
AND uri_slug=:uri_slug
ORDER BY revisions.created_at DESC
LIMIT 1

As I pointed out in the last episode, when the app is already running and you make changes to queries.sql, you need to make sure they get loaded into the app. The way to do that is by reevaluating this call to conman/bind-connection. I’m using Emacs with CIDER, and so I can go to this namespace, place my cursor behind this form, and press C-x C-e to evaluate it. More often though I will press C-c C-k which reloads the whole namespace.

;; src/lambwiki/db/core.clj
(conman/bind-connection *db* "sql/queries.sql")

Alternatively you can reload a namespace from the REPL, by passing the :reload keyword to require. This is good to know, especially for those moments when you’re using a plain REPL that isn’t connected to your editor.

user> (require 'lambwiki.db.core :reload)

So far we’ve just been putting the ingredients we’ll be needing within easy reach. Time to cook up some features!

Start by adding an edit button to the wiki-page.html template.

  <hr>
  <a class="ui button" href="/{{uri_slug}}/edit">Edit</a>

Clicking the button results in a 404, which isn’t too surpising. Let’s cook up the form to edit pages.

Make a new template called edit-page.html. You can start by copying over the wiki-page template. I’m using markup classes from Semantic UI to make the form look nice. This form will send a POST request to that POST route we defined earlier. We’ll give it two fields: one for the title, and one for the body of the page, all the info we need to create a new page revision. We can determine which page was edited based on the URL the form was submitted to.

{% extends "base.html" %}
{% block content %}
<div class="ui container">
  <h1 class="ui header">Edit page</h1>
  <form class="ui form" method="POST" action="/{{uri_slug}}">
    <div class="ui field">
      <label for="title">Title</label>
      <input type="text" name="title" value="{{title}}">
    </div>
    <div class="ui field">
      <label for="body">Body</label>
      <textarea name="body">{{body}}</textarea>
    </div>
    <div class="ui field">
      <input type="submit" class="ui button" value="Save!">
    </div>
  </form>
</div>
{% endblock %}

In the home routes file I can reuse the code for the wiki page route with minimal changes. We’ll have to make it a bit smarter later on, but for now this will do.

(ns lambwiki.routes.home ,,,)

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

(defroutes home-routes
  ,,,
  (GET "/:uri_slug/edit" [uri_slug]
    (if-let [page (find-page-by-uri-slug {:uri_slug uri_slug})]
      (edit-page page)))
  ,,,)

So now we have a form and can start editing, which is great because there’s an important change I’ve been meaning to make to the home page.

![](/img/lamb.jpg)

We can submit that, but we haven’t implemented yet what should happen when we submit the form, so you would expect a 404, indicating this page is missing. Instead the response is a 403, meaning that somehow we aren’t authorized to perform this operation.

The reason for this is a little thing called “Cross Site Request Forgery”, a vulnerability that can plague any unguarded site on the web. Explaining CSRF in detail would take us too far.

What you need to know is that Luminus tries to protect you by checking a hidden token submitted in the form against a secret value in the user’s session. This token needs to be present in every POST request, or the request will be rejected, resulting in this 403.

The csrf-field markup tag does the trick, and now we get a 404 as expected, since the route to handle this form submission doesn’t do anything yet.

<!-- resource/templates/edit-page.html -->
<form ...>
  {% csrf-field %}

Now let me show you how to handle that form submission. We need three pieces of information: the uri_slug, so we can find the right page, and the body and title of the new revision. The first is pulled from the URI, and the others are submitted as form data, but Ring makes them all available in a single :params map inside the request. Compojure’s destructuring makes it easy to pull them out.

We haven’t used create-revision! yet, so make sure to add it to the namespace. Finally we render the new version of the page. A common pattern would be to redirect and let the browser do another request to load the page, but we’re already on the right URI, so let’s just render the page straight away. One thing to watch out for is that page now contains the values for the old revision. That’s no good! We could load the page data again, but in this case params has all the data we need, so we can use that instead. A nice side effect of simply using Clojure maps for everything.

(ns lambwiki.routes.home
  (:require ,,,
            [lambwiki.db.core :refer [find-page-by-uri-slug create-revision!]]))

(defroutes home-routes
  ,,,

  ;; submit the form, creating a new revision
  (POST "/:uri_slug" {{:keys [uri_slug title body] :as params} :params}
    (when-let [page (find-page-by-uri-slug {:uri_slug uri_slug})]
      (create-revision! {:page_id (:id page)
                         :body body
                         :title title})
      (wiki-page params))))

Nice, we can finally add that cute little lamb. Isn’t it adorable?

![](/img/lamb.jpg)

## Welcome to Lamb Wiki

The place to be for big and little lambs.

We added a complete feature now, we’re able to edit the home page. Let’s commit this to git before we accidentally break it again.

git add -A
git commit

A key feature of a Wiki is that it lets you easily link to pages which don’t exist yet. We’ll implement some custom markup for wiki links which looks like this.

![](/img/lamb.jpg)

## Welcome to Lamb Wiki

The place to be for [[Big Lambs]] and [[Little Lambs]].

To make these links work, we’ll have to add a custom filter to the templating system, which you can learn all about in the third and final part of this Luminus introduction.

If you have any feedback on this episode please send it to arne@lambdaisland.com. Also make sure to check the show notes, where I’ve added some interesing links about wikis, and cross site request forgery.

Show Notes

Code

The code for this episode can be found on Github under lambdaisland/lambwiki.

Wikis

Wiki has become synonymous with Wikipedia, but the first Wiki was actually about patterns in software development. Wikimedia has a great video interview with the inventor of the wiki, Ward Cunningham.

Some example pages on Ward’s wiki

CSRF

Cross-site Request Forgery (CSRF) is one of the most common security problems on the web, together with Cross-site Scripting (XSS). If you’re a professional web developer you should understand both these exploits and how to prevent them.

The Wikipedia Page on CSRF gives a good overview of the problems and solutions.

OWASP, an online community for security in free and open source software, has a very extensive wiki page that deals with the finer points of CSRF.

Note that our wiki as it stands is wide open to XSS attacks. You can try out some of the snippets from the OWASP XSS (Cross Site Scripting) Prevention Cheat Sheet to verify this yourself. We’ll talk more about XSS in a future episode.

Versions

The software used in this episode

$ lein --version
Leiningen 2.6.1 on Java 1.8.0_91 Java HotSpot(TM) 64-Bit Server VM

  :dependencies [[org.clojure/clojure "1.8.0"]
                 [selmer "1.0.4"]
                 [markdown-clj "0.9.88"]
                 [ring-middleware-format "0.7.0"]
                 [metosin/ring-http-response "0.6.5"]
                 [bouncer "1.0.0"]
                 [org.webjars/bootstrap "4.0.0-alpha.2"]
                 [org.webjars/font-awesome "4.6.1"]
                 [org.webjars.bower/tether "1.1.1"]
                 [org.webjars/jquery "2.2.2"]
                 [org.clojure/tools.logging "0.3.1"]
                 [compojure "1.5.0"]
                 [ring-webjars "0.1.1"]
                 [ring/ring-defaults "0.2.0"]
                 [mount "0.1.10"]
                 [cprop "0.1.7"]
                 [org.clojure/tools.cli "0.3.3"]
                 [luminus-nrepl "0.1.4"]
                 [org.webjars/webjars-locator-jboss-vfs "0.1.0"]
                 [luminus-immutant "0.2.0"]
                 [luminus-migrations "0.1.2"]
                 [conman "0.5.1"]
                 [org.postgresql/postgresql "9.4-1206-jdbc4"]
                 [luminus-log4j "0.1.3"]
                 [hiccup "1.0.5"]]

GNU Emacs 25.0.92.2 (x86_64-unknown-linux-gnu, GTK+ Version 3.16.7) of 2016-03-30
CIDER 0.13.0snapshot (package: 20160510.1330)

Introduction to Luminus, part 2