docs: add sessions usage

docs/content/1.guide/4.sessions.md

@@ -7,4 +7,92 @@ icon: ri:arrow-left-right-line
 
 Nitro, through [unjs/h3](https://github.com/h3), supports sessions out of the box.
 
-<!-- TODO: explains composables, settings and how to use them -->
+::alert{type="info"}
+A session is a series of interactions between a client and server. Because HTTP is a stateless protocol, sessions allow association of multiple requests to the same client using a cookie which is automatically sent by the browser to the server on each request.
+::
+
+## Composables available
+
+There is many composables you can use to manage sessions:
+
+- `useSession`, the most importante one since it's a wrapper around all other composables
+- `getSession`, to get the current session
+- `updateSession`, to update the data of the current session
+- `sealSession`, to protect the current session from being modified
+- `unsealSession`, to access to the current session
+- `clearSession`, to clear the current session
+
+## Use sessions
+
+To use sessions, you've just to use the `useSession` composable and provide a string password in one of your event handler. each time a client will hit this endpoint, the composable will first try to get the session from a header named `x-h3-session` then from a cookie named `h3`. If no session is found, a new one will be created.
+
+```ts [routes/index.ts]
+export default defineEventHandler(async (event) => {
+  const session = await useSession(event, {
+    password: 'f30e9a68-4960-440a-9e9b-cc91d58aad62'
+  })
+
+  return
+})
+```
+
+Starting from now, Nitro will return a header `Set-Cookie` with a cookie named `h3` to the client. This cookie is sealed so the client won't be able to read or modify it.
+
+::alert{type="info"}
+You can customize the cookie name by providing a `name` property in the options of `useSession`. This will also update the header named used to retrieve the session.
+::
+
+The `useSession` composable returns an object with three properties:
+
+- `data`, the data of the current session
+- `update`, a function to update the data of the current session
+- `clear`, a function to clear the current session
+
+So, you can easily update the data of the current session:
+
+```ts [routes/index.ts]
+export default defineEventHandler(async (event) => {
+  const session = await useSession(event, {
+    password: 'f30e9a68-4960-440a-9e9b-cc91d58aad62'
+  })
+
+  session.update({ foo: 'bar' })
+
+  return session.data
+})
+```
+
+Then, when the client will hit Nitro with the cookie, you will be able to retrieve the data of the session:
+
+```ts [routes/data.ts]
+export default defineEventHandler(async (event) => {
+  const session = await useSession(event, {
+    password: 'f30e9a68-4960-440a-9e9b-cc91d58aad62' // Same password as before in order to unseal the session
+  })
+
+  return session.data // { foo: 'bar' }
+})
+```
+
+::callout{type="info"}
+#summary
+How `useSession` works?
+#content
+Under the hood, the `useSession` composable will use the `getSession` to retrieve the current session returned as `data` and return the `updateSession` as `update` and `clearSession` as `clear`. `sealSession` is used when the `updateSession` is called with the provided password and the `unsealSession` is used when the `getSession` is called with the provided password.
+::
+
+## Customization
+
+### Cookie
+
+You can customize the cookie name by providing a `name` property in the options of `useSession`. You can also add serialized options to the cookie by providing a `cookie` property in the options of `useSession`. This property is an object with the following properties:
+
+- `maxAge`, the maximum age of the cookie **in seconds**
+- `expires`, the expiration date of the cookie
+- `path`, the path of the cookie
+- `domain`, the domain of the cookie
+- `secure`, a boolean indicating if the cookie is secure
+- `httpOnly`, a boolean indicating if the cookie is http only
+- `sameSite`, the same site policy of the cookie
+
+<!-- TODO: we could add more informations about the crypto and seal options but I dont' know if it's relevant here. -->