# Session Middleware

{% hint style="info" %}
This article does not address how sessions work under the hood. This article is only to understand how the session middleware work and how to use it.
{% endhint %}

## Main

Mandarine contains a Session Core (Part of Mandarine Security Module) that allows your web-application to make use of the concept of sessions. 

Sessions are states (in variables) that can be distributed across your web-application and they contain information that can be updated at request-time.

Sessions are unique per requester, it is a way to tell your web server who is requesting your endpoints.

Some use cases that may help you understand what a session is are: They can store the user Id of someone, and then that user Id can be used across your web-application to retrieve the information of the user in different pages.

## Concepts

* Mandarine Session Cookie
  * A encrypted cookie that is created at request-time. This cookie contains a signature to verify that the it has not been manipulated & contains the session id that will be used to retrieve the information of the session. 

## Process

1. A request is made to an endpoint by someone.
2. Before the request gets to the [custom middleware](https://mandarineframework.gitbook.io/mandarine-ts/mandarine-mvc/custom-middleware) & [HTTP handlers](https://mandarineframework.gitbook.io/mandarine-ts/mandarine-mvc/controllers/http-handlers), it is intercepted by the session middleware
3. The session middleware verifies that the request contains a *mandarine session cookie*
   1. If the request **does not** contain a *mandarine session cookie*, then a new cookie is created along with a new session. Otherwise, the mandarine session cookie works as the key for the Mandarine Session Container & the current session is retrieved.
4. After the session is retrieved or created, three variables are **injected** in the request context (request object)
   1. **request**.*sessionContext:* Contains all the information about the session.
   2. **request**.*sessionID*: Contains the key of the session (UUID).
   3. **request**.*session:* Contains the data that the session holds.
      1. When information is added/removed to this object, the *session container* receives a signal that the current session context must be updated.
5. After the session variables are injected in the request, the session is ready to be used in the [custom middleware](https://mandarineframework.gitbook.io/mandarine-ts/mandarine-mvc/custom-middleware) and/or the [HTTP handlers](https://mandarineframework.gitbook.io/mandarine-ts/mandarine-mvc/controllers/http-handlers).
6. After the HTTP handlers & post-request middleware are called, the session is then saved and its context is updated.

## Accessing the session object

As described above, the session object is part of the request object when a request is made to an endpoint. The session object is accessible via the use of [HTTP Parameter Decorators](https://mandarineframework.gitbook.io/mandarine-ts/mandarine-mvc/controllers/http-handlers#http-parameter-decorators), by using the decorator `@Session()` . Please, refer to the link in order to understand this concept.

For examples of this please [click here ](https://mandarineframework.gitbook.io/mandarine-ts/mandarine-mvc/controllers/http-handlers#usage)and then click on **@Session tab***.*