add sessions, sessions database and flash messages sections

Cookies.md

@@ -133,3 +133,5 @@ Also, note that the default behavior is to set its `HttpOnly` to true. It perfor
 ```go
 RemoveCookie(name string, options ...CookieOption)
 ```
+
+Continue by learning about HTTP [[Sessions]].

Home.md

@@ -29,9 +29,13 @@ This wiki is the main source of documentation for **developers** working with (o
 * [[Cache]]
 * [[File Server]]
 * [[View]]
-* [[Dependency Injection|Dependency-Injection]]
-* [[MVC]] **TODO chapter**
 * [[Cookies]]
+* [[Sessions]]
+    * [Database](Sessions-database)
+    * [Flash Messages](Sessions-flash-messages)
+* [[Websockets]]
+* [[Dependency Injection|Dependency-Injection]]
+* [[MVC]]
 * [[Testing]]
 * [Examples](https://github.com/kataras/iris/tree/master/_examples)
 * [[Starter Kits]]

Sessions-database.md

@@ -0,0 +1,67 @@
+# Sessions Database
+
+Sometimes you need a backend storage, i.e redis, which will keep your session data on server restarts and scale horizontally.
+
+Registering a session database can be done through a single call of `sessions.UseDatabase(database)`.
+
+Iris implements three (3) builtin session databases for [redis](https://redis.io/), [badger](https://github.com/dgraph-io/badger) and [boltdb](github.com/etcd-io/bbolt). These session databases are implemented via the [iris/sessions/sessiondb](https://github.com/kataras/iris/tree/master/sessions/sessiondb) subpackage which you'll have to import.
+
+1. import the `gitbub.com/kataras/iris/sessions/sessiondb/redis or boltdb or badger`,
+2. initialize the database and
+3. register it
+
+For example, to register the redis session database:
+
+```go
+import (
+    "github.com/kataras/iris"
+    "github.com/kataras/iris/sessions"
+
+    // 1. Import the session database.
+    "github.com/kataras/iris/sessions/sessiondb/redis"
+)
+
+// 2. Initialize the database.
+// Replace with your running redis' server settings:
+db := redis.New(redis.Config{
+    Network:   "tcp",
+    Addr:      "127.0.0.1:6379",
+    Timeout:   time.Duration(30) * time.Second,
+    MaxActive: 10,
+    Password:  "",
+    Database:  "",
+    Prefix:    "",
+})
+
+// Close connection when control+C/cmd+C
+iris.RegisterOnInterrupt(func() {
+    db.Close()
+})
+
+sess := sessions.New(sessions.Config{
+    Cookie:       "sessionscookieid",
+    AllowReclaim: true,
+})
+
+// 3. Register it.
+sess.UseDatabase(db)
+
+// [...]
+```
+
+**boltdb**
+
+```go
+import "os"
+import "github.com/kataras/iris/sessions/sessiondb/boltdb"
+
+db, err := boltdb.New("./sessions.db", os.FileMode(0750))
+```
+
+**badger**
+
+```go
+import "github.com/kataras/iris/sessions/sessiondb/badger"
+
+db, err := badger.New("./data")
+```

Sessions-flash-messages.md

@@ -0,0 +1,40 @@
+# Flash Messages
+
+Sometimes you need to temporarily store data between requests of the same user, such as error or success messages after a form submission. The Iris sessions package supports flash messages.
+
+As we've seen the [[Sessions]] chapter, you initialize a session like this:
+
+```go
+import "github.com/kataras/iris/sessions"
+
+sess := sessions.New(sessions.Config{Cookie: "cookieName", ...})
+```
+
+```go
+// [app := iris.New...]
+
+app.Get("/path", func(ctx iris.Context) {
+    session := sess.Start(ctx)
+    // [...]
+})
+```
+
+The `Session` contains the following methods to store, retrieve and remove flash messages.
+
+```go
+SetFlash(key string, value interface{})
+HasFlash() bool
+GetFlashes() map[string]interface{}
+
+PeekFlash(key string) interface{}
+GetFlash(key string) interface{}
+GetFlashString(key string) string
+GetFlashStringDefault(key string, defaultValue string) string
+
+DeleteFlash(key string)
+ClearFlashes()
+```
+
+The method names are self-explained. For example, if you need to get a message and remove it at the next request use the `GetFlash`. When you only need to retrieve but don't remove then use the `PeekFlash`.
+
+> Flash messages are not stored in a database.

Sessions.md

@@ -0,0 +1,204 @@
+# Sessions
+
+When you work with an application, you open it, do some changes, and then you close it. This is much like a Session. The computer knows who you are. It knows when you start the application and when you end. But on the internet there is one problem: the web server does not know who you are or what you do, because the HTTP address doesn't maintain state.
+
+Session variables solve this problem by storing user information to be used across multiple pages (e.g. username, favorite color, etc). By default, session variables last until the user closes the browser.
+
+So; Session variables hold information about one single user, and are available to all pages in one application.
+
+> **Tip**: If you need a permanent storage, you may want to store the data in a [database](Sessions-database).
+
+-------
+
+Iris has its own session implementation and sessions manager live inside the [iris/sessions](https://github.com/kataras/iris/tree/master/sessions) subpackage. You'll need to import this package in order to work with HTTP Sessions.
+
+A session is started with the `Start` function of the `Sessions` object which is created with the `New` package-level function. That function will return a `Session`.
+
+Session variables are set with the `Session.Set` method and retrieved by the `Session.Get` and its related methods. To delete a single variable use the `Session.Delete`. To delete and invalidate the whole session use the `Session.Destroy` method.
+
+<details>
+<summary>See all methods</summary>
+
+The sessions manager is created using the `New` package-level function.
+
+```go
+import "github.com/kataras/iris/sessions"
+
+sess := sessions.New(sessions.Config{Cookie: "cookieName", ...})
+```
+
+Where `Config` looks like that.
+
+```go
+SessionIDGenerator func(iris.Context) string
+
+// Defaults to "irissessionid".
+Cookie string
+
+CookieSecureTLS bool
+
+// Defaults to false.
+AllowReclaim bool
+
+// Defaults to nil.
+Encode func(cookieName string, value interface{}) (string, error)
+// Defaults to nil.
+Decode func(cookieName string, cookieValue string, v interface{}) error
+// Defaults to nil.
+Encoding Encoding
+
+// Defaults to infinitive/unlimited life duration(0).
+Expires time.Duration
+
+// Defaults to false.
+DisableSubdomainPersistence bool
+```
+
+The return value a `Sessions` pointer exports the following methods.
+
+```go
+Start(ctx iris.Context,
+    cookieOptions ...iris.CookieOption) *Session
+
+Destroy()
+DestroyAll()
+DestroyByID(sessID string)
+OnDestroy(callback func(sid string))
+
+ShiftExpiration(ctx iris.Context,
+    cookieOptions ...iris.CookieOption) error
+UpdateExpiration(ctx iris.Context, expires time.Duration,
+    cookieOptions ...iris.CookieOption) error
+
+UseDatabase(db Database)
+```
+
+Where `CookieOption` is just a `func(*http.Cookie)` which allows to customize cookie's properties.
+
+The `Start` method returns a `Session` pointer value which exports its own methods to work per session.
+
+```go
+func (ctx iris.Context) {
+    session := sess.Start(ctx)
+     .ID() string
+     .IsNew() bool
+
+     .Set(key string, value interface{})
+     .SetImmutable(key string, value interface{})
+     .GetAll() map[string]interface{}
+     .Delete(key string) bool
+     .Clear()
+
+     .Get(key string) interface{}
+     .GetString(key string) string
+     .GetStringDefault(key string, defaultValue string) string
+     .GetInt(key string) (int, error)
+     .GetIntDefault(key string, defaultValue int) int
+     .Increment(key string, n int) (newValue int)
+     .Decrement(key string, n int) (newValue int)
+     .GetInt64(key string) (int64, error)
+     .GetInt64Default(key string, defaultValue int64) int64
+     .GetFloat32(key string) (float32, error)
+     .GetFloat32Default(key string, defaultValue float32) float32
+     .GetFloat64(key string) (float64, error)
+     .GetFloat64Default(key string, defaultValue float64) float64
+     .GetBoolean(key string) (bool, error)
+     .GetBooleanDefault(key string, defaultValue bool) bool
+
+     .SetFlash(key string, value interface{})
+     .HasFlash() bool
+     .GetFlashes() map[string]interface{}
+
+     .PeekFlash(key string) interface{}
+     .GetFlash(key string) interface{}
+     .GetFlashString(key string) string
+     .GetFlashStringDefault(key string, defaultValue string) string
+
+     .DeleteFlash(key string)
+     .ClearFlashes()
+
+     .Destroy()
+}
+
+```
+
+</details>
+
+## Example
+
+In this example we will only allow authenticated users to view our secret message on the /secret age. To get access to it, the will first have to visit /login to get a valid session cookie, hich logs him in. Additionally he can visit /logout to revoke his access to our secret message.
+
+```go
+// sessions.go
+package main
+
+import (
+    "github.com/kataras/iris"
+
+    "github.com/kataras/iris/sessions"
+)
+
+var (
+    cookieNameForSessionID = "mycookiesessionnameid"
+    sess                   = sessions.New(sessions.Config{Cookie: cookieNameForSessionID})
+)
+
+func secret(ctx iris.Context) {
+    // Check if user is authenticated
+    if auth, _ := sess.Start(ctx).GetBoolean("authenticated"); !auth {
+        ctx.StatusCode(iris.StatusForbidden)
+        return
+    }
+
+    // Print secret message
+    ctx.WriteString("The cake is a lie!")
+}
+
+func login(ctx iris.Context) {
+    session := sess.Start(ctx)
+
+    // Authentication goes here
+    // ...
+
+    // Set user as authenticated
+    session.Set("authenticated", true)
+}
+
+func logout(ctx iris.Context) {
+    session := sess.Start(ctx)
+
+    // Revoke users authentication
+    session.Set("authenticated", false)
+    // Or to remove the variable:
+    session.Delete("authenticated")
+    // Or destroy the whole session:
+    session.Destroy()
+}
+
+func main() {
+    app := iris.New()
+
+    app.Get("/secret", secret)
+    app.Get("/login", login)
+    app.Get("/logout", logout)
+
+    app.Run(iris.Addr(":8080"))
+}
+```
+
+```sh
+$ go run sessions.go
+
+$ curl -s http://localhost:8080/secret
+Forbidden
+
+$ curl -s -I http://localhost:8080/login
+Set-Cookie: mysessionid=MTQ4NzE5Mz...
+
+$ curl -s --cookie "mysessionid=MTQ4NzE5Mz..." http://localhost:8080/secret
+The cake is a lie!
+```
+
+Navigate to <https://github.com/kataras/iris/tree/master/_examples/sessions> for more examples about the sessions subpackage.
+
+Continue by reading the [Flash Messages](Sessions-flash-messages) section.

_Sidebar.md

@@ -24,10 +24,14 @@
 * [[Cache]]
 * [[File Server]]
 * [[View]]
-* [[Dependency Injection|Dependency-Injection]]
-* [[MVC]] **TODO chapter**
 * [[Cookies]]
+* [[Sessions]]
+    * [Database](Sessions-database)
+    * [Flash Messages](Sessions-flash-messages)
+* [[Websockets]]
+* [[Dependency Injection|Dependency-Injection]]
+* [[MVC]]
 * [[Testing]]
 * [Examples](https://github.com/kataras/iris/tree/master/_examples)
 * [[Starter Kits]]
-* [[Publications]]
+* [[Publications]]