Route attributes

Route attributes allow you to set some metadata on each of your routes, in the routes description itself. The syntax is trivial: just an exclamation point followed by a value. Using it is also trivial: just use the routeAttrs function.

It’s easiest to understand how it all fits together, and when you might want it, with a motivating example. The case I personally most use this for is annotating administrative routes. Imagine having a website with about 12 different admin actions. You could manually add a call to requireAdmin or some such at the beginning of each action, but:

  1. It’s tedious.

  2. It’s error prone: you could easily forget one.

  3. Worse yet, it’s not easy to notice that you’ve missed one.

Modifying your isAuthorized method with an explicit list of administrative routes is a bit better, but it’s still difficult to see at a glance when you’ve missed one.

This is why I like to use route attributes for this: you add a single word to each relevant part of the route definition, and then you just check for that attribute in isAuthorized. Let’s see the code!

  1. {-# LANGUAGE MultiParamTypeClasses #-}
  2. {-# LANGUAGE OverloadedStrings     #-}
  3. {-# LANGUAGE QuasiQuotes           #-}
  4. {-# LANGUAGE TemplateHaskell       #-}
  5. {-# LANGUAGE TypeFamilies          #-}
  6. import           Data.Set         (member)
  7. import           Data.Text        (Text)
  8. import           Yesod
  9. import           Yesod.Auth
  10. import           Yesod.Auth.Dummy
  12. data App = App
  14. mkYesod "App" [parseRoutes|
  15. / HomeR GET
  16. /unprotected UnprotectedR GET
  17. /admin1 Admin1R GET !admin
  18. /admin2 Admin2R GET !admin
  19. /admin3 Admin3R GET
  20. /auth AuthR Auth getAuth
  21. |]
  23. instance Yesod App where
  24.     authRoute _ = Just $ AuthR LoginR
  25.     isAuthorized route _writable
  26.         | "admin" `member` routeAttrs route = do
  27.             muser <- maybeAuthId
  28.             case muser of
  29.                 Nothing -> return AuthenticationRequired
  30.                 Just ident
  31.                     -- Just a hack since we're using the dummy module
  32.                     | ident == "admin" -> return Authorized
  33.                     | otherwise -> return $ Unauthorized "Admin access only"
  34.         | otherwise = return Authorized
  36. instance RenderMessage App FormMessage where
  37.     renderMessage _ _ = defaultFormMessage
  39. -- Hacky YesodAuth instance for just the dummy auth plugin
  40. instance YesodAuth App where
  41.     type AuthId App = Text
  43.     loginDest _ = HomeR
  44.     logoutDest _ = HomeR
  45.     getAuthId = return . Just . credsIdent
  46.     authPlugins _ = [authDummy]
  47.     maybeAuthId = lookupSession credsKey
  48.     authHttpManager = error "no http manager provided"
  50. getHomeR :: Handler Html
  51. getHomeR = defaultLayout $ do
  52.     setTitle "Route attr homepage"
  53.     [whamlet|
  54.         <p>
  55.             <a href=@{UnprotectedR}>Unprotected
  56.         <p>
  57.             <a href=@{Admin1R}>Admin 1
  58.         <p>
  59.             <a href=@{Admin2R}>Admin 2
  60.         <p>
  61.             <a href=@{Admin3R}>Admin 3
  62.     |]
  64. getUnprotectedR, getAdmin1R, getAdmin2R, getAdmin3R :: Handler Html
  65. getUnprotectedR = defaultLayout [whamlet|Unprotected|]
  66. getAdmin1R = defaultLayout [whamlet|Admin1|]
  67. getAdmin2R = defaultLayout [whamlet|Admin2|]
  68. getAdmin3R = defaultLayout [whamlet|Admin3|]
  70. main :: IO ()
  71. main = warp 3000 App

And it was so glaring, I bet you even caught the security hole about Admin3R.