IHP Api Reference| Copyright | (c) digitally induced GmbH 2021 |
|---|---|
| Safe Haskell | None |
IHP.Controller.Session
Description
The session provides a way for your application to store small amounts of information that will be persisted between requests. It’s mainly used from inside your controller actions.
In general, you should not store complex data structures in the session. It’s better to store scalar values in there only. For example: Store the current user-id instead of the current user record.
The session works by storing the data inside a cryptographically signed and encrypted cookie on the client. The encryption key is generated automatically and is stored at Config/client_session_key.aes. Internally IHP uses the clientsession library. You can find more technical details on the implementation in the clientsession documentation.
The cookie max-age is set to 30 days by default. To protect against CSRF, the SameSite Policy is set to Lax.
Synopsis
- data SessionError
- setSession :: (?context :: ControllerContext, Serialize value) => ByteString -> value -> IO ()
- getSession :: forall value. (?context :: ControllerContext, Serialize value) => ByteString -> IO (Maybe value)
- getSessionEither :: forall value. (?context :: ControllerContext, Serialize value) => ByteString -> IO (Either SessionError value)
- deleteSession :: (?context :: ControllerContext) => ByteString -> IO ()
- getSessionAndClear :: forall value. (?context :: ControllerContext, Serialize value) => ByteString -> IO (Maybe value)
Session Error
data SessionError Source #
Types of possible errors as a result of requesting a value from the session storage
Constructors
| NotFoundError | Value not found in the session storage |
| ParseError String | Error occurce during parsing value |
Instances
| Eq SessionError Source # | |
Defined in IHP.Controller.Session | |
| Show SessionError Source # | |
Defined in IHP.Controller.Session Methods showsPrec :: Int -> SessionError -> ShowS # show :: SessionError -> String showList :: [SessionError] -> ShowS # | |
Interacting with session store
setSession :: (?context :: ControllerContext, Serialize value) => ByteString -> value -> IO () Source #
Stores a value inside the session:
action SessionExampleAction { userId } = do
setSession "userId" userIdFor cases where setSession is used with literals, to avoid type ambiguity, you can use one of the options below
Example: Annotate a literal with a type
action LogoutAction = do
setSession "userEmail" ("hi@digitallyinduced.com" :: Text)Example: Using setSession with type application
action LogoutAction = do
setSession @Text "userEmail" "hi@digitallyinduced.com"getSession :: forall value. (?context :: ControllerContext, Serialize value) => ByteString -> IO (Maybe value) Source #
Retrives a value from the session:
action SessionExampleAction = do
userEmail <- getSession @Text "userEmail"
counter <- getSession @Int "counter"
userId <- getSession @(Id User) "userId"userEmail is set to Just' "hidigitallyinduced.com"@
when the value has been set before. Otherwise, it will be Nothing.
If an error occurs while getting the value, the result will be Nothing.
getSessionEither :: forall value. (?context :: ControllerContext, Serialize value) => ByteString -> IO (Either SessionError value) Source #
Retrives a value from the session:
getSession variant, which returns SessionError if an error occurs
while getting value from session storage
action SessionExampleAction = do
counter <- getSessionEither @Int "counter"
case counter of
Right value -> ...
Left (ParseError errorMessage) -> ...
Left NotFoundError -> ...
Left VaultError -> ...deleteSession :: (?context :: ControllerContext) => ByteString -> IO () Source #
Remove session values from storage:
Example: Deleting a userId field from the session
action LogoutAction = do
deleteSession "userId"Example: Calling getSession after
using deleteSession will return Nothing
setSession "userId" (1337 :: Int) userId <- getSession @Int "userId" -- Returns: Just 1337 deleteSession "userId" userId <- getSession @Int "userId" -- Returns: Nothing
getSessionAndClear :: forall value. (?context :: ControllerContext, Serialize value) => ByteString -> IO (Maybe value) Source #
Returns a value from the session, and deletes it after retrieving:
action SessionExampleAction = do
notification <- getSessionAndClear @Text "notification"