Doc: Start of Session doc

Author: jknack

docs/asciidoc/context.adoc

@@ -453,6 +453,31 @@ File upload are available ONLY for multipart requests.
 
 ====
 
+==== Session
+
+Session parameters are available via javadoc::Context[session] or javadoc::Context[sessionOrNull]
+methods. HTTP Session is covered in his own <<session, chapter>>, but here is a quick look:
+
+.Java
+[source,java,role="primary"]
+----
+  Session session = ctx.session();                      // <1>
+
+  String attribute = ctx.session("attribute").value();  // <2>
+
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+  val session = ctx.session()                             // <1>
+
+  val attribute = session.attribute("attribute").value()  // <2>
+----
+
+<1> Find an existing Session or create one
+<2> Get a session attribute
+
 ==== Flash
 
 Flash parameters are designed to transport success/error messages between requests. It is similar to

docs/asciidoc/index.adoc

@@ -238,6 +238,8 @@ include::static-files.adoc[]
 
 include::templates.adoc[]
 
+include::session.adoc[]
+
 include::execution-model.adoc[]
 
 include::responses.adoc[]

docs/asciidoc/session.adoc

@@ -1 +1,21 @@
 == Session
+
+Session is accessible via 
+
+- javadoc::Context[sessionOrNull]: which find an existing session
+- javadoc::Context[session]: which find an existing session or create a new one
+
+Sessions have a lot of uses cases but the most commons are: authentication, storing information 
+about current user, etc.
+
+A session attribute must be a String or a primitive. The session doesn't allow storing of arbitrary 
+objects. It's intended as a simple mechanism to store basic data (not an object graph).
+
+Jooby provides two javadoc::SessionStore[] implementation:
+
+- In-Memory sessions - which you should combine with an a sticky sessions proxy if you plan to run multiple instances.
+- Cookie sessions signed with a secret key
+
+=== Working with Sessions
+
+