Configuring Cookies

All cookie values can be defined in our settings file. Let's see an example:

...
cookie:
    renew: login
    login_cookie:
        name: id
        max_age: 86400000
        http_only: true
        secure: true
        value:
        expires:
        domain:
        path: /
...

Be aware, we can hard-code these values in our Rust modules as well. Although the former is the recommended way forward, feel free to take the approach that better fits your needs.

Find a description of these fields in the table below:

Using Cookies

Kalgan provides the struct kalgan::storage::cookie::Cookie :

#[derive(Debug, Clone)]
pub struct Cookie {
    name: String,
    value: String,
    max_age: usize,
    expires: String,
    domain: String,
    path: String,
    secure: bool,
    http_only: bool
}

We're not going to detail these fields as they are the same we commented on the above table.

Creating cookies

Notice that all the fields in Cookie are private. To set their values we'll have to use the methods commonly known as setters (for example Cookie.set_name("cookie_name") ).

However Kalgan offers as well the method Cookie.set_from_settings() which takes all the cookie parameters defined in our settings file. This is the way forward we should take. Anyway, nothing stops us from keep setting any value after this method.

For example:

use kalgan::http::{ request::Request, response::Response };
use kalgan::storage::cookie::Cookie;

pub(crate) fn foobar(request: &Request) -> Response {
    ...
    let cookie = Cookie::new()
        .set_from_settings("cookie.login_cookie")
        .set_value("Cookie Value");
    ...
}

Finally, to pass the cookie to the browser we must include it in the Response calling the method Response.add_cookie().

For example:

use kalgan::http::{ request::Request, response::Response };
use kalgan::storage::cookie::Cookie;

pub(crate) fn foobar(request: &Request) -> Response {
    ...
    let cookie = Cookie::new();
    ...
    let contents: String = "...";
    Response::new()
        .set_status(200)
        .set_content_type("text/html; charset=UTF-8")
        .set_content_length(contents.len())
        .set_content(&contents)
        .add_cookie(cookie)
}

Notice we can use this method with the shortcuts to create the Response. For example:

use kalgan::http::{ request::Request, response::Response };
use kalgan::storage::cookie::Cookie;

pub(crate) fn foobar(request: &Request) -> Response {
    ...
    let cookie = Cookie::new();
    ...
    render!("foo/foobar.html").add_cookie(cookie)
}

Reading cookies

Kalgan doesn't provide getters to read the values. This is because the cookie is expected to be read just by the browser. However we're going to need to check the cookie value sent by the browser. These values can be access through the struct Request thanks to the method Request.get_cookies(), which returns a key-value collection of cookies.

For example:

use kalgan::http::{ request::Request, response::Response };
use kalgan::storage::cookie::Cookie;

pub(crate) fn foobar(request: &Request) -> Response {
    ...
    let cookies: &HashMap = request.get_cookies();
    let value = cookies["id"];
    ...
}

Configuring Sessions

Session system is based on crate kalgan_cache, which in turn is based on crate redis. Redis is an in-memory key-value database, cache system and message broker.

Therefore, the first we must do is installing Redis in our machine. For this purpose we can see Configuring Redis in the docs.

Once we have Redis up and running, we must configure Kalgan. For this purpose we can see Configuring Cache in the docs.

A session use the value of the cookie sent by the browser. For this reason we must define in the settings file the session along with the cookie above defined.

For example:

...
session:
    backoffice:
        cookie: login_cookie
...

In this example we have defined a session called backoffice which depends on the cookie login_cookie we've been using above.

Using Sessions

Kalgan provides the struct kalgan::storage::session::Session :

pub struct Session {
    cache: Cache,
    cookies: HashMap
}

Find a description of these fields in the table below:

Besides, this object count with the following public methods:

Kalgan really makes easy working with sessions. Create a Session is pretty straightforward.

Let's see and example of how to create a session which in addition stores the user data:

use kalgan::http::{ request::Request, response::Response };
use kalgan::storage::cookie::Cookie;

pub(crate) fn foobar(request: &Request) -> Response {
    ...
    let user model::User = ...
    ...
    let session_id = Session::new(&request).create(serde_json::to_string(&user).unwrap());
    ...
}

However there's one more step we must do: we have to send this value back to the browser (as a cookie). Again, this is pretty simple.

For this purpose we have to use the method Response.add_session() which will create the cookie login_cookie for us with the value of the session_id. For example:

use kalgan::http::{ request::Request, response::Response };
use kalgan::storage::cookie::Cookie;

pub(crate) fn foobar(request: &Request) -> Response {
    ...
    let session_id = ...
    ...
    render!("foo/foobar.html").add_session("backoffice", session_id)
}