Skip to content
Browse files

Add some docs

  • Loading branch information...
1 parent 4dd2d18 commit 1e94262559ebc6a97eaa1cf7b0129db47919f1a8 @ozataman ozataman committed Aug 15, 2011
View
4 snap.cabal
@@ -51,6 +51,10 @@ Library
exposed-modules:
Snap.Snaplet,
Snap.Snaplet.Heist,
+ Snap.Snaplet.Auth,
+ Snap.Snaplet.Auth.Types,
+ Snap.Snaplet.Auth.Handlers,
+ Snap.Snaplet.Auth.Backends.JsonFile,
Snap.Snaplet.Session,
Snap.Snaplet.Session.Backends.CookieSession,
Snap.Snaplet.Internal.TemporaryLensCruft
View
40 src/Snap/Snaplet/Auth.hs
@@ -3,15 +3,32 @@
module Snap.Snaplet.Auth
(
+
+ -- * Higher Level Handler Functions
createUser
, loginByUsername
, checkPasswordAndLogin
, forceLogin
, logout
, isLoggedIn
+
+ -- * Lower Level Handler Functions
+ , markAuthSuccess
+ , markAuthFail
+
+ -- * Types
+ , AuthManager
+ , IAuthBackend
, AuthSettings(..)
, defAuthSettings
- , AuthManager
+ , AuthUser(..)
+ , UserId(..)
+ , Password(..)
+ , AuthFailure(..)
+ , BackendError(..)
+
+ -- * Other Utilities
+ , authenticatePassword
)
where
@@ -83,7 +100,7 @@ rememberUser = cacheOrLookup f
------------------------------------------------------------------------------
--- Logout the active user
+-- | Logout the active user
logout :: Handler b (AuthManager b) ()
logout = do
s <- gets session
@@ -116,7 +133,9 @@ isLoggedIn = do
-- You might need these if you are rolling your own handlers/authenticators
------------------------------------------------------------------------------
--- | Mutate an 'AuthUser', marking failed authentication now.
+-- | Mutate an 'AuthUser', marking failed authentication
+--
+-- This will save the user to the backend.
markAuthFail :: AuthUser -> Handler b (AuthManager b) AuthUser
markAuthFail u = do
(AuthManager r _ _ _ _ _ _ _) <- get
@@ -129,7 +148,9 @@ markAuthFail u = do
------------------------------------------------------------------------------
--- | Mutate an 'AuthUser', marking successful authentication now.
+-- | Mutate an 'AuthUser', marking successful authentication
+--
+-- This will save the user to the backend.
markAuthSuccess :: AuthUser -> Handler b (AuthManager b) AuthUser
markAuthSuccess u = do
(AuthManager r _ _ _ _ _ _ _) <- get
@@ -160,7 +181,7 @@ markAuthSuccess u = do
--
-- 3. Mark success/failure of the authentication trial on the user record
checkPasswordAndLogin
- :: AuthUser
+ :: AuthUser -- ^ An existing user, somehow looked up from db
-> Password -- ^ A ClearText password
-> Bool -- ^ Set remember cookie?
-> Handler b (AuthManager b) (Either AuthFailure AuthUser)
@@ -182,8 +203,8 @@ checkPasswordAndLogin u pw remember =
-- Meant to be used if you have other means of being sure that the person is
-- who she says she is.
forceLogin
- :: AuthUser
- -> Bool -- ^ Set remember cookie?
+ :: AuthUser -- ^ An existing user, somehow looked up from db
+ -> Bool -- ^ Set remember cookie?
-> Handler b (AuthManager b) Bool
forceLogin u rc = do
AuthManager _ s _ _ _ _ _ _ <- get
@@ -217,7 +238,10 @@ getSessionUserId = do
------------------------------------------------------------------------------
--- | Check password for a given user.
+-- | Check password for a given user.
+--
+-- Returns 'Nothing" if check is successful and an 'IncorrectPassword' error
+-- otherwise
authenticatePassword
:: AuthUser -- ^ Looked up from the back-end
-> Password -- ^ Check against this password
View
10 src/Snap/Snaplet/Auth/Backends/JsonFile.hs
@@ -2,7 +2,10 @@
{-# LANGUAGE TypeOperators #-}
{-# LANGUAGE OverloadedStrings #-}
-module Snap.Snaplet.Auth.Backends.JsonFile where
+module Snap.Snaplet.Auth.Backends.JsonFile
+ ( initJsonFileAuthManager
+ , mkJsonAuthMgr
+ ) where
import Control.Applicative
@@ -57,7 +60,10 @@ initJsonFileAuthManager s l db =
}
--- Load an existing datafile into memory cache
+------------------------------------------------------------------------------
+-- | Load/create a datafile into memory cache and return the manager.
+--
+-- This data type can be used by itself for batch/non-handler processing.
mkJsonAuthMgr :: FilePath -> IO JsonFileAuthManager
mkJsonAuthMgr fp = do
db <- loadUserCache fp
View
7 src/Snap/Snaplet/Auth/Handlers.hs
@@ -7,10 +7,6 @@
Provides generic, somewhat customizable handlers that can be plugged
directly into Snap applications.
- The core 'Snap.Auth' module is pretty much stand-alone and taking these as
- starting point examples, you should be able to write your own custom
- handlers.
-
-}
module Snap.Snaplet.Auth.Handlers
@@ -35,7 +31,8 @@ import Snap.Snaplet.Auth.Types
import Snap.Snaplet
-
+------------------------------------------------------------------------------
+-- | Register a new user by specifying login and password 'Param' fields
registerUser
:: ByteString -- Login field
-> ByteString -- Password field
View
11 src/Snap/Snaplet/Auth/Types.hs
@@ -45,6 +45,7 @@ checkPassword (ClearText pw) (Encrypted pw') = verifyPassword pw pw'
checkPassword _ _ =
error "checkPassword failed. Make sure you pass ClearText passwords"
+
------------------------------------------------------------------------------
-- | Authentication failures indicate what went wrong during authentication.
-- They may provide useful information to the developer, although it is
@@ -120,6 +121,8 @@ defAuthUser = AuthUser {
}
+------------------------------------------------------------------------------
+-- | Authetication settings defined at initialization time
data AuthSettings = AuthSettings {
asMinPasswdLen :: Int
, asRememberCookieName :: ByteString
@@ -136,6 +139,9 @@ defAuthSettings = AuthSettings {
, asSiteKey = "site_key.txt"
}
+
+------------------------------------------------------------------------------
+-- | Abstract data type holding all necessary information for auth operation
data AuthManager b = forall r. IAuthBackend r => AuthManager {
backend :: r
-- ^ Storage back-end
@@ -171,7 +177,10 @@ data BackendError = DuplicateLogin | BackendError String
instance Exception BackendError
--- | Backend operations may throw 'BackendError's
+------------------------------------------------------------------------------
+-- | All storage backends need to implement this typeclass
+--
+-- Backend operations may throw 'BackendError's
class IAuthBackend r where
-- | Needs to create or update the given 'AuthUser' record

0 comments on commit 1e94262

Please sign in to comment.
Something went wrong with that request. Please try again.